Add wrappers to easily deal with the myriad of ScVal integer types.

.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
         node-version: ${{ matrix.node-version }}
 
     - name: Install Dependencies
-      run: yarn install
+      run: yarn install --network-concurrency 1
 
     - name: Build All
       run: yarn build:prod

config/.eslintrc.js

@@ -1,6 +1,7 @@
 module.exports = {
   env: {
-    es6: true
+    es6: true,
+    es2020: true
   },
   extends: ['airbnb-base', 'prettier'],
   plugins: ['@babel', 'prettier', 'prefer-import'],

package.json

@@ -12,14 +12,15 @@
     "build:browser:prod": "cross-env NODE_ENV=production yarn build:browser",
     "build:prod": "cross-env NODE_ENV=production yarn build",
     "test": "yarn build && yarn test:node && yarn test:browser",
-    "test:node": "nyc --nycrc-path ./config/.nycrc mocha",
+    "test:node": "yarn _nyc mocha",
     "test:browser": "karma start ./config/karma.conf.js",
     "docs": "jsdoc -c ./config/.jsdoc.json --verbose",
     "lint": "eslint -c ./config/.eslintrc.js src/ && dtslint --localTs node_modules/typescript/lib types/",
     "preversion": "yarn clean && yarn fmt && yarn lint && yarn build:prod && yarn test",
     "fmt": "prettier --config ./config/prettier.config.js --ignore-path ./config/.prettierignore --write './**/*.js'",
     "prepare": "yarn build:prod",
-    "clean": "rm -rf lib/ dist/ coverage/ .nyc_output/"
+    "clean": "rm -rf lib/ dist/ coverage/ .nyc_output/",
+    "_nyc": "nyc --nycrc-path ./config/.nycrc"
   },
   "mocha": {
     "require": [
@@ -80,7 +81,6 @@
     "@typescript-eslint/parser": "^5.59.5",
     "babel-loader": "^9.1.2",
     "babel-plugin-istanbul": "^6.1.1",
-    "buffer": "^6.0.3",
     "chai": "^4.3.7",
     "cross-env": "^7.0.3",
     "eslint": "^8.40.0",
@@ -120,9 +120,10 @@
   "dependencies": {
     "base32.js": "^0.1.0",
     "bignumber.js": "^9.1.1",
+    "buffer": "^6.0.3",
     "crc": "^4.3.2",
     "crypto-browserify": "^3.12.0",
-    "js-xdr": "^2.0.0",
+    "js-xdr": "^3.0.0",
     "lodash": "^4.17.21",
     "sha.js": "^2.3.6",
     "tweetnacl": "^1.0.3"

src/contract.js

@@ -43,12 +43,12 @@ export class Contract {
    */
   contractId(format = 'strkey') {
     switch (format) {
-    case 'strkey':
-      return StrKey.encodeContract(this._id);
-    case 'hex':
-      return this._id.toString('hex');
-    default:
-      throw new Error(`Invalid format: ${format}`);
+      case 'strkey':
+        return StrKey.encodeContract(this._id);
+      case 'hex':
+        return this._id.toString('hex');
+      default:
+        throw new Error(`Invalid format: ${format}`);
     }
   }
 

src/index.js

@@ -47,4 +47,14 @@ export {
   encodeMuxedAccount
 } from './util/decode_encode_muxed_account';
 
+export {
+  ScInt,
+  XdrLargeInt,
+  scValToBigInt,
+  Uint256,
+  Int256,
+  Uint128,
+  Int128
+} from './numbers/index';
+
 export default module.exports;

src/numbers/index.js

@@ -0,0 +1,64 @@
+import { XdrLargeInt } from './xdr_large_int';
+
+import { Uint128 } from './uint128';
+import { Uint256 } from './uint256';
+import { Int128 } from './int128';
+import { Int256 } from './int256';
+
+export { Uint256, Int256, Uint128, Int128 };
+
+export { ScInt } from './sc_int';
+export { XdrLargeInt };
+
+/**
+ * Transforms an opaque {@link xdr.ScVal} into a native bigint, if possible.
+ *
+ * If you then want to use this in the abstractions provided by this module,
+ * you can pass it to the constructor of {@link XdrLargeInt}.
+ *
+ * @example
+ * ```js
+ * let scv = contract.call("add", x, y); // assume it returns an xdr.ScVal
+ * let bigi = scValToBigInt(scv);
+ *
+ * new ScInt(bigi);           // if you don't care about types, and
+ * new XdrLargeInt('i128', bigi);  // if you do
+ * ```
+ *
+ * @param {xdr.ScVal} scv - the raw XDR value to parse into an integer
+ * @returns {bigint} the native value of this input value
+ *
+ * @throws {TypeError} if the `scv` input value doesn't represent an integer
+ */
+export function scValToBigInt(scv) {
+  const type = scv.switch().name.slice(3).toLowerCase();
+
+  switch (scv.switch().name) {
+    case 'scvU32':
+    case 'scvI32':
+      return BigInt(scv.value());
+
+    case 'scvU64':
+    case 'scvI64':
+      return new XdrLargeInt(type, scv.value()).toBigInt();
+
+    case 'scvU128':
+    case 'scvI128':
+      return new XdrLargeInt(type, [
+        scv.value().lo(),
+        scv.value().hi()
+      ]).toBigInt();
+
+    case 'scvU256':
+    case 'scvI256':
+      return new XdrLargeInt(type, [
+        scv.value().loLo(),
+        scv.value().loHi(),
+        scv.value().hiLo(),
+        scv.value().hiHi()
+      ]).toBigInt();
+
+    default:
+      throw TypeError(`expected integer type, got ${scv.switch()}`);
+  }
+}

src/numbers/int128.js

@@ -0,0 +1,23 @@
+import { LargeInt } from 'js-xdr';
+
+export class Int128 extends LargeInt {
+  /**
+   * Construct a signed 128-bit integer that can be XDR-encoded.
+   *
+   * @param  {Array<number|bigint|string>}  args - one or more slices to encode
+   *     in big-endian format (i.e. earlier elements are higher bits)
+   */
+  constructor(...args) {
+    super(args);
+  }
+
+  get unsigned() {
+    return false;
+  }
+
+  get size() {
+    return 128;
+  }
+}
+
+Int128.defineIntBoundaries();

src/numbers/int256.js

@@ -0,0 +1,23 @@
+import { LargeInt } from 'js-xdr';
+
+export class Int256 extends LargeInt {
+  /**
+   * Construct a signed 256-bit integer that can be XDR-encoded.
+   *
+   * @param  {Array<number|bigint|string>}  args - one or more slices to encode
+   *     in big-endian format (i.e. earlier elements are higher bits)
+   */
+  constructor(...args) {
+    super(args);
+  }
+
+  get unsigned() {
+    return false;
+  }
+
+  get size() {
+    return 256;
+  }
+}
+
+Int256.defineIntBoundaries();

src/numbers/sc_int.js

@@ -0,0 +1,116 @@
+import { XdrLargeInt } from './xdr_large_int';
+
+/**
+ * Provides an easier way to manipulate large numbers for Stellar operations.
+ *
+ * You can instantiate this value either from bigints, strings, or numbers
+ * (whole numbers, or this will throw).
+ *
+ * If you need to create a native BigInt from a list of integer "parts" (for
+ * example, you have a series of encoded 32-bit integers that represent a larger
+ * value), you can use the lower level abstraction {@link XdrLargeInt}. For example,
+ * you could do `new XdrLargeInt('u128', bytes...).toBigInt()`.
+ *
+ * @example
+ * ```js
+ * import sdk from "stellar-base";
+ *
+ * // You have an ScVal from a contract and want to parse it into JS native.
+ * const value = sdk.xdr.ScVal.fromXDR(someXdr, "base64");
+ * const bigi = sdk.ScInt.fromScVal(value); // grab it as a BigInt
+ * let sci = new ScInt(bigi);
+ *
+ * sci.toNumber(); // gives native JS type (w/ size check)
+ * sci.toBigInt(); // gives the native BigInt value
+ * sci.toU64();    // gives ScValType-specific XDR constructs (with size checks)
+ *
+ * // You have a number and want to shove it into a contract.
+ * sci = sdk.ScInt(0xdeadcafebabe);
+ * sci.toBigInt() // returns 244838016400062n
+ * sci.toNumber() // throws: too large
+ *
+ * // Pass any to e.g. a Contract.call(), conversion happens automatically
+ * // regardless of the initial type.
+ * const scValU128 = sci.toU128();
+ * const scValI256 = sci.toI256();
+ * const scValU64  = sci.toU64();
+ *
+ * // Lots of ways to initialize:
+ * sdk.ScInt("123456789123456789")
+ * sdk.ScInt(123456789123456789n);
+ * sdk.ScInt(1n << 140n);
+ * sdk.ScInt(-42);
+ * sdk.ScInt.fromScVal(scValU128); // from above
+ *
+ * // If you know the type ahead of time (accessing `.raw` is faster than
+ * // conversions), you can specify the type directly (otherwise, it's
+ * // interpreted from the numbers you pass in):
+ * const i = sdk.ScInt(123456789n, { type: "u256" });
+ *
+ * // For example, you can use the underlying `sdk.U256` and convert it to an
+ * // `xdr.ScVal` directly like so:
+ * const scv = new xdr.ScVal.scvU256(i.raw);
+ *
+ * // Or reinterpret it as a different type (size permitting):
+ * const scv = i.toI64();
+ * ```
+ *
+ * @param {number|bigint|string|ScInt} value - a single, integer-like value
+ *    which will be interpreted in the smallest appropriate XDR type supported
+ *    by Stellar (64, 128, or 256 bit integer values). signed values are
+ *    supported, though they are sanity-checked against `opts.type`. if you need
+ *    32-bit values, you can construct them directly without needing this
+ *    wrapper, e.g. `xdr.ScVal.scvU32(1234)`.
+ *
+ * @param {object}  [opts] - an optional object controlling optional parameters
+ * @param {string}  [opts.type] - force a specific data type. the type choices
+ *    are: 'i64', 'u64', 'i128', 'u128', 'i256', and 'u256' (default: the
+ *    smallest one that fits the `value`)
+ *
+ * @throws {RangeError} if the `value` is invalid (e.g. floating point), too
+ *    large (i.e. exceeds a 256-bit value), or doesn't fit in the `opts.type`
+ *
+ * @throws {TypeError} on missing parameters, or if the "signedness" of `opts`
+ *    doesn't match input `value`, e.g. passing `{type: 'u64'}` yet passing -1n
+ *
+ * @throws {SyntaxError} if a string `value` can't be parsed as a big integer
+ */
+export class ScInt extends XdrLargeInt {
+  constructor(value, opts) {
+    const signed = value < 0;
+    let type = opts?.type ?? '';
+    if (type.startsWith('u') && signed) {
+      throw TypeError(`specified type ${opts.type} yet negative (${value})`);
+    }
+
+    // If unspecified, we make a best guess at the type based on the bit length
+    // of the value, treating 64 as a minimum and 256 as a maximum.
+    if (type === '') {
+      type = signed ? 'i' : 'u';
+      const bitlen = nearestBigIntSize(value);
+
+      switch (bitlen) {
+        case 64:
+        case 128:
+        case 256:
+          type += bitlen.toString();
+          break;
+
+        default:
+          throw RangeError(
+            `expected 64/128/256 bits for parts (${value}), got ${bitlen}`
+          );
+      }
+    }
+
+    super(type, value);
+  }
+}
+
+function nearestBigIntSize(bigI) {
+  // Note: Even though BigInt.toString(2) includes the negative sign for
+  // negative values (???), the following is still accurate, because the
+  // negative sign would be represented by a sign bit.
+  const bitlen = bigI.toString(2).length;
+  return [64, 128, 256].find((len) => bitlen <= len) ?? bitlen;
+}

src/numbers/uint128.js

@@ -0,0 +1,23 @@
+import { LargeInt } from 'js-xdr';
+
+export class Uint128 extends LargeInt {
+  /**
+   * Construct an unsigned 128-bit integer that can be XDR-encoded.
+   *
+   * @param  {Array<number|bigint|string>}  args - one or more slices to encode
+   *     in big-endian format (i.e. earlier elements are higher bits)
+   */
+  constructor(...args) {
+    super(args);
+  }
+
+  get unsigned() {
+    return true;
+  }
+
+  get size() {
+    return 128;
+  }
+}
+
+Uint128.defineIntBoundaries();

src/numbers/uint256.js

@@ -0,0 +1,23 @@
+import { LargeInt } from 'js-xdr';
+
+export class Uint256 extends LargeInt {
+  /**
+   * Construct an unsigned 256-bit integer that can be XDR-encoded.
+   *
+   * @param  {Array<number|bigint|string>}  args - one or more slices to encode
+   *     in big-endian format (i.e. earlier elements are higher bits)
+   */
+  constructor(...args) {
+    super(args);
+  }
+
+  get unsigned() {
+    return true;
+  }
+
+  get size() {
+    return 256;
+  }
+}
+
+Uint256.defineIntBoundaries();