Merge pull request #1921 from cosmos/fromAtomics-bigint

Let Decimal.fromAtomics accept `string | bigint`

Author: webmaster128

CHANGELOG.md

@@ -98,6 +98,10 @@ and this project adheres to
   `Secp256k1.verifySignature`/`.createSignature`/`.makeKeypair` synchronous and
   let them not return a Promise.
 - @cosmjs/cosmwasm-stargate: Rename package to @cosmjs/cosmwasm. ([#1903])
+- @cosmjs/math: `Decimal.fromAtomics` now accepts atomics as `string | bigint`
+  such that you can pass in BigInts directly. This is more performant than going
+  through strings in cases where you have a BitInt already. Strings remain
+  supported for convenient usage with coins.
 
 [#1883]: https://github.com/cosmos/cosmjs/issues/1883
 [#1866]: https://github.com/cosmos/cosmjs/issues/1866

packages/math/src/decimal.spec.ts

@@ -3,11 +3,12 @@ import { Uint32, Uint53, Uint64 } from "./integers";
 
 describe("Decimal", () => {
   describe("fromAtomics", () => {
-    it("leads to correct atomics value", () => {
+    it("leads to correct atomics value (string)", () => {
       expect(Decimal.fromAtomics("1", 0).atomics).toEqual("1");
       expect(Decimal.fromAtomics("1", 1).atomics).toEqual("1");
       expect(Decimal.fromAtomics("1", 2).atomics).toEqual("1");
 
+      expect(Decimal.fromAtomics("0", 5).atomics).toEqual("0");
       expect(Decimal.fromAtomics("1", 5).atomics).toEqual("1");
       expect(Decimal.fromAtomics("2", 5).atomics).toEqual("2");
       expect(Decimal.fromAtomics("3", 5).atomics).toEqual("3");
@@ -24,24 +25,51 @@ describe("Decimal", () => {
       expect(Decimal.fromAtomics("00044", 5).atomics).toEqual("44");
     });
 
+    it("leads to correct atomics value (bigint)", () => {
+      expect(Decimal.fromAtomics(1n, 0).atomics).toEqual("1");
+      expect(Decimal.fromAtomics(1n, 1).atomics).toEqual("1");
+      expect(Decimal.fromAtomics(1n, 2).atomics).toEqual("1");
+
+      expect(Decimal.fromAtomics(0n, 5).atomics).toEqual("0");
+      expect(Decimal.fromAtomics(1n, 5).atomics).toEqual("1");
+      expect(Decimal.fromAtomics(2n, 5).atomics).toEqual("2");
+      expect(Decimal.fromAtomics(3n, 5).atomics).toEqual("3");
+      expect(Decimal.fromAtomics(10n, 5).atomics).toEqual("10");
+      expect(Decimal.fromAtomics(20n, 5).atomics).toEqual("20");
+      expect(Decimal.fromAtomics(30n, 5).atomics).toEqual("30");
+      expect(Decimal.fromAtomics(100000000000000000000000n, 5).atomics).toEqual("100000000000000000000000");
+      expect(Decimal.fromAtomics(200000000000000000000000n, 5).atomics).toEqual("200000000000000000000000");
+      expect(Decimal.fromAtomics(300000000000000000000000n, 5).atomics).toEqual("300000000000000000000000");
+    });
+
     it("reads fractional digits correctly", () => {
       expect(Decimal.fromAtomics("44", 0).toString()).toEqual("44");
       expect(Decimal.fromAtomics("44", 1).toString()).toEqual("4.4");
       expect(Decimal.fromAtomics("44", 2).toString()).toEqual("0.44");
       expect(Decimal.fromAtomics("44", 3).toString()).toEqual("0.044");
       expect(Decimal.fromAtomics("44", 4).toString()).toEqual("0.0044");
+      expect(Decimal.fromAtomics(44n, 0).toString()).toEqual("44");
+      expect(Decimal.fromAtomics(44n, 1).toString()).toEqual("4.4");
+      expect(Decimal.fromAtomics(44n, 2).toString()).toEqual("0.44");
+      expect(Decimal.fromAtomics(44n, 3).toString()).toEqual("0.044");
+      expect(Decimal.fromAtomics(44n, 4).toString()).toEqual("0.0044");
     });
 
     it("throws for atomics that are not non-negative integers", () => {
       expect(() => Decimal.fromAtomics("0xAA", 0)).toThrowError(
-        "Invalid string format. Only non-negative integers in decimal representation supported.",
+        "Invalid string format. Only integers in decimal representation supported.",
       );
       expect(() => Decimal.fromAtomics("", 0)).toThrowError(
-        "Invalid string format. Only non-negative integers in decimal representation supported.",
+        "Invalid string format. Only integers in decimal representation supported.",
       );
-      expect(() => Decimal.fromAtomics("-1", 0)).toThrowError(
-        "Invalid string format. Only non-negative integers in decimal representation supported.",
+      expect(() => Decimal.fromAtomics("--2", 0)).toThrowError(
+        "Invalid string format. Only integers in decimal representation supported.",
       );
+      expect(() => Decimal.fromAtomics("0.7", 0)).toThrowError(
+        "Invalid string format. Only integers in decimal representation supported.",
+      );
+
+      expect(() => Decimal.fromAtomics("-1", 0)).toThrowError("Only non-negative values supported.");
     });
   });
 

packages/math/src/decimal.ts

@@ -51,17 +51,39 @@ export class Decimal {
 
     const quantity = BigInt(`${whole}${fractional.padEnd(fractionalDigits, "0")}`);
 
+    // We can remove this restriction, but then need to test and update arithmetic operations.
+    // See also https://github.com/cosmos/cosmjs/issues/1897
+    if (quantity < 0n) throw new Error("Only non-negative values supported.");
+
     return new Decimal(quantity, fractionalDigits);
   }
 
-  public static fromAtomics(atomics: string, fractionalDigits: number): Decimal {
-    Decimal.verifyFractionalDigits(fractionalDigits);
-    if (!atomics.match(/^[0-9]+$/)) {
-      throw new Error(
-        "Invalid string format. Only non-negative integers in decimal representation supported.",
-      );
+  /**
+   * Constructs a decimal given the atomic units and the fractional digits.
+   *
+   * Atomics units are the smallest unit you operate with.
+   * E.g. for EUR this could be Euro cents and for BTC this would be Satishi.
+   *
+   * To create the decimal value 12.60 (EUR) you would use atomics=1260, fractionalDigits=2.
+   * To create the decimal value 3.4 (BTC) you would use atomics=340000000, fractionalDigits=8.
+   *
+   * In order to perform arithmetic operations on Decimal, all values must have the same `fractionalDigits` value.
+   * So this should be fixed once per currency, not different per value.
+   */
+  public static fromAtomics(atomics: string | bigint, fractionalDigits: number): Decimal {
+    if (typeof atomics === "string") {
+      if (!atomics.match(/^-?[0-9]+$/)) {
+        throw new Error("Invalid string format. Only integers in decimal representation supported.");
+      }
+      return Decimal.fromAtomics(BigInt(atomics), fractionalDigits);
     }
-    return new Decimal(BigInt(atomics), fractionalDigits);
+
+    // We can remove this restriction, but then need to test and update arithmetic operations.
+    // See also https://github.com/cosmos/cosmjs/issues/1897
+    if (atomics < 0n) throw new Error("Only non-negative values supported.");
+
+    Decimal.verifyFractionalDigits(fractionalDigits);
+    return new Decimal(atomics, fractionalDigits);
   }
 
   /**