fix: correct XdrLargeInt range errors, fix a dead test (#1659)

* fix: name the actual constraint in XdrLargeInt range errors

* fix(test): make the muxed key assertion compare bytes again

* refactor: reuse intRange for XdrLargeInt bounds

* Updated docs

Author: quietbits

CHANGELOG.md

@@ -19,6 +19,10 @@ A breaking change will get clearly marked in this log.
   +xdr.TransactionMeta.v3(transactionMetaV3);
   ```
 
+* `XdrLargeInt` encoding errors name the actual constraint. `toI64()`/`toI128()`/`toI256()` reported `value too large for i64: <v>` with no indication of the valid range, and now report `bigint value <v> for i64 out of range [<min>, <max>]`. The width check reported `value too large for 64 bits (i128)` even when the value was `1` — it rejects the declared type, not the value — and now reports `cannot encode i128 as 64 bits`. `toNumber()` printed its safe-integer range with the bounds reversed. For these range violations the error is unchanged apart from its text: the same `RangeError` on the same inputs.
+
+* `XdrLargeInt` coerces a `toBigInt()` hook result with `BigInt(...)` instead of requiring an exact `bigint`. A custom object whose `toBigInt()` returns a bigint-convertible value — a `number` such as `5`, or `""` — is now accepted and normalized rather than throwing; a result that cannot be converted (`"abc"`, `NaN`, `null`, `{}`) still throws. This is what keeps `value` a genuine `bigint`: the range check compares with `<` and `>`, which yield `false` for a string or `NaN`, so without the coercion such a value passed every check and `toNumber()` returned `NaN` instead of throwing.
+
 * `equals()` on XDR values is now callable from TypeScript on union types like `xdr.ScVal`, `xdr.TransactionEnvelope`, and `xdr.Memo` — which is what the SDK's accessors return ([#1630](https://github.com/stellar/js-stellar-sdk/issues/1630)). The parameter was typed as polymorphic `this`, which reduces to `never` on a union, so every call failed with TS2345 even though the runtime worked. The parameter is now `XdrValue`, so comparing two different XDR types compiles and returns `false`.
 
 * `Keypair.verify` and `Keypair.verifyMessage` throw a `TypeError` for arguments whose type they don't accept, instead of returning `false` ([#1649](https://github.com/stellar/js-stellar-sdk/pull/1649)). Both previously swallowed every error and reported `false`, so a caller mistake was indistinguishable from an invalid signature. `verify` requires `data` to be a `Uint8Array` and `signature` to be either a `Uint8Array` or an `xdr.Signature`; `verifyMessage` takes the same `signature` and a `message` that is a string or a `Uint8Array`. Anything else now throws — a hex/base64 signature string, a plain array of byte values, the `xdr.DecoratedSignature` that `tx.signatures[0]` holds, or a `message` that is neither string nor bytes. A well-formed signature that doesn't match still returns `false`. Accepting an `xdr.Signature` — what `DecoratedSignature.signature` holds — means `kp.verify(tx.hash(), tx.signatures[0].signature)` works again. `authorizeEntry` likewise rejects a signer result it would have passed on unchecked — a callback returning none of its three shapes, a non-bytes `signature`, a non-string `publicKey`, or a `signatureScVal` that isn't an `xdr.ScVal`.

docs/reference/core-transactions.md

@@ -24,10 +24,10 @@ import { XdrLargeInt, type ScIntType } from "./xdr_large_int.js";
  * 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 = new ScInt(0xdeadcafebabe);
- * sci.toBigInt() // returns 244838016400062n
- * sci.toNumber() // throws: too large
+ * // You have a large value and want to shove it into a contract.
+ * sci = new ScInt(0xdeadcafebabedeadn);
+ * sci.toBigInt() // returns 16045704242794520237n
+ * sci.toNumber() // throws: not in range for Number
  *
  * // Pass any to e.g. a Contract.call(), conversion happens automatically
  * // regardless of the initial type.

src/base/numbers/sc_int.ts

@@ -5,6 +5,7 @@ import {
   Uint128Parts,
   Uint256Parts,
 } from "../../xdr/index.js";
+import { intRange } from "../../xdr/values/bigint-parts.js";
 
 type BigIntLike = { toBigInt(): bigint };
 type XdrLargeIntValues =
@@ -46,6 +47,34 @@ const SIGNED: Readonly<Record<ScIntType, boolean>> = {
   duration: false,
 };
 
+/**
+ * Throws a `RangeError` if `value` can't be represented as `name`, a `bits`-wide
+ * integer.
+ *
+ * A negative value for an unsigned type is reported as a sign error rather than
+ * as an overflow, and the valid range appears in the out-of-range message, so
+ * the text states why the value was actually rejected. Both messages match the
+ * ones `js-xdr` produced through v16.
+ */
+function assertInRange(
+  value: bigint,
+  name: string,
+  bits: 64 | 128 | 256,
+  signed: boolean,
+): void {
+  if (!signed && value < 0n) {
+    throw new RangeError(`expected a positive value, got: ${value}`);
+  }
+
+  const [min, max] = intRange(signed, bits);
+
+  if (value < min || value > max) {
+    throw new RangeError(
+      `bigint value ${value} for ${name} out of range [${min}, ${max}]`,
+    );
+  }
+}
+
 /**
  * A wrapper class to represent large XDR-encodable integers.
  *
@@ -83,7 +112,10 @@ export class XdrLargeInt {
           "toBigInt" in i &&
           typeof (i as BigIntLike).toBigInt === "function"
         ) {
-          return (i as BigIntLike).toBigInt();
+          // `toBigInt()` is a consumer-supplied hook, so its result is coerced
+          // rather than trusted: the range check below compares with `<` and
+          // `>`, which yield `false` instead of throwing for a non-bigint.
+          return BigInt((i as BigIntLike).toBigInt());
         }
         return BigInt(i as number | string);
       },
@@ -103,18 +135,7 @@ export class XdrLargeInt {
     // `LargeInt`-backed implementation enforced this at construction time and
     // several callers (notably `nativeToScVal` via `ScInt`) depend on it.
     if (parts.length === 1) {
-      const bits = SIZE[type];
-      if (SIGNED[type]) {
-        if (BigInt.asIntN(bits, value) !== value) {
-          throw new RangeError(
-            `value too large for ${bits}-bit ${type}: ${value}`,
-          );
-        }
-      } else if (value < 0n || BigInt.asUintN(bits, value) !== value) {
-        throw new RangeError(
-          `value too large for ${bits}-bit ${type}: ${value}`,
-        );
-      }
+      assertInRange(value, type, SIZE[type], SIGNED[type]);
     }
 
     this.value = value;
@@ -131,7 +152,7 @@ export class XdrLargeInt {
     if (bi > Number.MAX_SAFE_INTEGER || bi < Number.MIN_SAFE_INTEGER) {
       throw RangeError(
         `value ${bi} not in range for Number ` +
-          `[${Number.MAX_SAFE_INTEGER}, ${Number.MIN_SAFE_INTEGER}]`,
+          `[${Number.MIN_SAFE_INTEGER}, ${Number.MAX_SAFE_INTEGER}]`,
       );
     }
     return Number(bi);
@@ -150,9 +171,7 @@ export class XdrLargeInt {
   toI64(): ScVal {
     this._sizeCheck(64);
     const v = this.value;
-    if (BigInt.asIntN(64, v) !== v) {
-      throw RangeError(`value too large for i64: ${v}`);
-    }
+    assertInRange(v, "i64", 64, true);
     return ScVal.scvI64(v);
   }
 
@@ -182,9 +201,7 @@ export class XdrLargeInt {
   toI128(): ScVal {
     this._sizeCheck(128);
     const v = this.value;
-    if (BigInt.asIntN(128, v) !== v) {
-      throw RangeError(`value too large for i128: ${v}`);
-    }
+    assertInRange(v, "i128", 128, true);
     return ScVal.scvI128(
       new Int128Parts({
         hi: BigInt.asIntN(64, v >> 64n),
@@ -216,9 +233,7 @@ export class XdrLargeInt {
    */
   toI256(): ScVal {
     const v = this.value;
-    if (BigInt.asIntN(256, v) !== v) {
-      throw RangeError(`value too large for i256: ${v}`);
-    }
+    assertInRange(v, "i256", 256, true);
     return ScVal.scvI256(
       new Int256Parts({
         hiHi: BigInt.asIntN(64, v >> 192n),
@@ -297,8 +312,10 @@ export class XdrLargeInt {
   }
 
   private _sizeCheck(bits: number): void {
+    // This rejects the declared type, not the value: a small `i128` still can't
+    // be encoded as 64 bits, so the message must not blame the value's size.
     if (SIZE[this.type] > bits) {
-      throw RangeError(`value too large for ${bits} bits (${this.type})`);
+      throw RangeError(`cannot encode ${this.type} as ${bits} bits`);
     }
   }
 

src/base/numbers/xdr_large_int.ts

@@ -553,8 +553,8 @@ describe("ScInt", () => {
         let b = new ScInt(sentinel);
         expect(b.toBigInt()).toBe(sentinel);
         expect(() => b.toNumber()).toThrow(/not in range/i);
-        expect(() => b.toU64()).toThrow(/too large/i);
-        expect(() => b.toI64()).toThrow(/too large/i);
+        expect(() => b.toU64()).toThrow(/cannot encode u128 as 64 bits/);
+        expect(() => b.toI64()).toThrow(/cannot encode u128 as 64 bits/);
 
         let scvU = b.toU128();
         if (scvU.type !== "scvU128") throw new Error("expected scvU128");
@@ -672,15 +672,17 @@ describe("ScInt", () => {
         big = new ScInt(Number.MAX_SAFE_INTEGER + 1);
         expect(() => big.toNumber()).toThrow(/not in range/i);
 
+        // the value is 1: these fail on the declared type's width, not on the
+        // value's magnitude, and the message says so
         big = new ScInt(1, { type: "i128" });
-        expect(() => big.toU64()).toThrow(/too large/i);
-        expect(() => big.toI64()).toThrow(/too large/i);
+        expect(() => big.toU64()).toThrow(/cannot encode i128 as 64 bits/);
+        expect(() => big.toI64()).toThrow(/cannot encode i128 as 64 bits/);
 
         big = new ScInt(1, { type: "i256" });
-        expect(() => big.toU64()).toThrow(/too large/i);
-        expect(() => big.toI64()).toThrow(/too large/i);
-        expect(() => big.toI128()).toThrow(/too large/i);
-        expect(() => big.toU128()).toThrow(/too large/i);
+        expect(() => big.toU64()).toThrow(/cannot encode i256 as 64 bits/);
+        expect(() => big.toI64()).toThrow(/cannot encode i256 as 64 bits/);
+        expect(() => big.toI128()).toThrow(/cannot encode i256 as 128 bits/);
+        expect(() => big.toU128()).toThrow(/cannot encode i256 as 128 bits/);
       });
     });
   });