Merge pull request #702 from Jagadeeshftw/fix/682-u256-range

fix: reject out-of-range u256 values

Author: Jagadeeshftw

src/utils/codec.test.ts

@@ -5,6 +5,8 @@ import {
   toHexString,
   formatTokenAmount,
   DEFAULT_TOKEN_DECIMALS,
+  U256_MAX,
+  U256OverflowError,
 } from "./codec";
 
 describe("parseU256", () => {
@@ -20,6 +22,19 @@ describe("parseU256", () => {
     expect(BigInt(r.low as never)).toBe(7n);
     expect(BigInt(r.high as never)).toBe(1n);
   });
+
+  it("accepts the maximum representable value", () => {
+    expect(parseU256(U256_MAX.toString())).toBeTruthy();
+  });
+
+  it("throws a distinct error for values outside the u256 range", () => {
+    expect(() => parseU256((U256_MAX + 1n).toString())).toThrow(U256OverflowError);
+    expect(() => parseU256("-1")).toThrow(U256OverflowError);
+  });
+
+  it("keeps the existing native error path for malformed values", () => {
+    expect(() => parseU256("not-a-number")).toThrow(SyntaxError);
+  });
 });
 
 describe("u256ToString", () => {
@@ -103,7 +118,7 @@ describe("formatTokenAmount", () => {
   it("formats the full u256 max without precision loss", () => {
     const u256Max = (1n << 256n) - 1n;
     expect(formatTokenAmount(u256Max)).toBe(
-      "115792089237316195423570985008687907853269984665640564039457584007913129.639935"
+      "115792089237316195423570985008687907853269984665640564039457584007913129.639935",
     );
   });
 
@@ -124,7 +139,7 @@ describe("Fuzz testing round-trip (encode/decode)", () => {
     const MAX_U256 = (1n << 256n) - 1n;
     const MAX_U128 = (1n << 128n) - 1n;
     const iterations = 10000;
-    
+
     for (let i = 0; i < iterations; i++) {
       let randomBigInt = 0n;
       // Generate random up to 256 bits by appending 32 random bits at a time
@@ -137,11 +152,11 @@ describe("Fuzz testing round-trip (encode/decode)", () => {
       if (i === 1) randomBigInt = MAX_U256;
       if (i === 2) randomBigInt = MAX_U128;
       if (i === 3) randomBigInt = 1n << 128n; // min value in high part
-      
+
       const str = randomBigInt.toString();
       const parsed = parseU256(str);
       const back = u256ToString(parsed);
-      
+
       expect(back).toBe(str);
     }
   });

src/utils/codec.ts

@@ -1,7 +1,20 @@
 import { cairo } from "starknet";
 
+export const U256_MAX = (1n << 256n) - 1n;
+
+/** Thrown when a value cannot be represented by a Starknet u256. */
+export class U256OverflowError extends RangeError {
+  constructor(value: bigint) {
+    super(`u256 value out of range: ${value.toString()}`);
+    this.name = "U256OverflowError";
+  }
+}
+
 export function parseU256(value: string) {
   const bn = BigInt(value);
+  if (bn < 0n || bn > U256_MAX) {
+    throw new U256OverflowError(bn);
+  }
   return cairo.uint256(bn);
 }
 
@@ -67,7 +80,7 @@ export const DEFAULT_TOKEN_DECIMALS = 6;
  */
 export function formatTokenAmount(
   raw: string | bigint,
-  decimals: number = DEFAULT_TOKEN_DECIMALS
+  decimals: number = DEFAULT_TOKEN_DECIMALS,
 ): string {
   if (!Number.isInteger(decimals) || decimals < 0) {
     throw new RangeError(`decimals must be a non-negative integer, got ${decimals}`);