From ffa92d3e86b99fe796714751ea342103121377be Mon Sep 17 00:00:00 2001
From: Jeremy Klein <jklein24@gmail.com>
Date: Wed, 15 Nov 2023 12:12:06 -0800
Subject: [PATCH] Add displayDecimals to the currency object. (#36)

* Add displayDecimals to the currency object.

This helps the sender display the receiving currency amount correctly in their UI.

Protocol change: https://github.com/uma-universal-money-address/protocol/pull/7

* plurals
---
 packages/core/src/Currency.ts       | 36 ++++++++++++++++++++++++++++-
 packages/core/src/tests/uma.test.ts |  1 +
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/packages/core/src/Currency.ts b/packages/core/src/Currency.ts
index ac73d2d..8249962 100644
--- a/packages/core/src/Currency.ts
+++ b/packages/core/src/Currency.ts
@@ -1,12 +1,46 @@
 import { z } from "zod";
 
 export const CurrencySchema = z.object({
+  /**
+   * The currency code, eg. "USD".
+   */
   code: z.string(),
+
+  /**
+   * The full currency name in plural form, eg. "US Dollars".
+   */
   name: z.string(),
+
+  /**
+   * The symbol of the currency, eg. "$".
+   */
   symbol: z.string(),
-  multiplier: z.number(), // millisatoshi per unit
+
+  /**
+   * Estimated millisats per smallest "unit" of this currency (eg. 1 cent in USD).
+   */
+  multiplier: z.number(),
+
+  /**
+   * Minimum amount that can be sent in this currency. This is in the smallest unit of the currency
+   * (eg. cents for USD).
+   */
   minSendable: z.number(),
+
+  /**
+   * Maximum amount that can be sent in this currency. This is in the smallest unit of the currency
+   * (eg. cents for USD).
+   */
   maxSendable: z.number(),
+
+  /**
+   * Number of digits after the decimal point for display on the sender side. For example,
+   * in USD, by convention, there are 2 digits for cents - $5.95. in this case, `displayDecimals`
+   * would be 2. Note that the multiplier is still always in the smallest unit (cents). This field
+   * is only for display purposes. The sender should assume zero if this field is omitted, unless
+   * they know the proper display format of the target currency.
+   */
+  displayDecimals: z.optional(z.number()),
 });
 
 export type Currency = z.infer<typeof CurrencySchema>;
diff --git a/packages/core/src/tests/uma.test.ts b/packages/core/src/tests/uma.test.ts
index 4815c72..1272bc9 100644
--- a/packages/core/src/tests/uma.test.ts
+++ b/packages/core/src/tests/uma.test.ts
@@ -282,6 +282,7 @@ describe("uma", () => {
           multiplier: 34_150,
           minSendable: 1,
           maxSendable: 10_000_000,
+          displayDecimals: 2,
         },
       ],
       receiverKycStatus: KycStatus.Verified,