zerc20-client-sdk 0.1.13 → 0.1.14

package/dist/utils/__tests__/http.test.js

@@ -0,0 +1,295 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { ensureFetch, normalizeBaseUrl, buildUrl, wrapFetchError, sleep, mergeHeaders, HttpClient, } from "../http.js";
+describe("ensureFetch", () => {
+    test("returns fetch when available", () => {
+        const fetchFn = ensureFetch();
+        expect(typeof fetchFn).toBe("function");
+    });
+    test("throws when fetch is not available", () => {
+        const original = globalThis.fetch;
+        vi.stubGlobal("fetch", undefined);
+        try {
+            expect(() => ensureFetch()).toThrow("fetch is not available in the current environment");
+        }
+        finally {
+            vi.stubGlobal("fetch", original);
+        }
+    });
+});
+describe("normalizeBaseUrl", () => {
+    test("adds trailing slash when missing", () => {
+        expect(normalizeBaseUrl("https://example.com")).toBe("https://example.com/");
+    });
+    test("keeps trailing slash when present", () => {
+        expect(normalizeBaseUrl("https://example.com/")).toBe("https://example.com/");
+    });
+    test("handles path segments", () => {
+        expect(normalizeBaseUrl("https://example.com/api/v1")).toBe("https://example.com/api/v1/");
+    });
+});
+describe("buildUrl", () => {
+    test("builds URL from base and path", () => {
+        expect(buildUrl("https://example.com", "api/test")).toBe("https://example.com/api/test");
+    });
+    test("handles base without trailing slash", () => {
+        expect(buildUrl("https://example.com/v1", "test")).toBe("https://example.com/v1/test");
+    });
+    test("handles path with leading slash", () => {
+        expect(buildUrl("https://example.com/", "/test")).toBe("https://example.com/test");
+    });
+});
+describe("wrapFetchError", () => {
+    test("wraps Error with message", () => {
+        const error = wrapFetchError("https://example.com", new Error("Network error"));
+        expect(error.message).toBe("request to https://example.com failed: Network error");
+    });
+    test("wraps string error", () => {
+        const error = wrapFetchError("https://example.com", "Connection refused");
+        expect(error.message).toBe("request to https://example.com failed: Connection refused");
+    });
+    test("wraps object error", () => {
+        const error = wrapFetchError("https://example.com", { code: "ECONNREFUSED" });
+        expect(error.message).toBe("request to https://example.com failed: [object Object]");
+    });
+    test("includes context when provided", () => {
+        const error = wrapFetchError("https://example.com", new Error("timeout"), "API call");
+        expect(error.message).toBe("API call: request to https://example.com failed: timeout");
+    });
+});
+describe("sleep", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    test("resolves after specified time", async () => {
+        const promise = sleep(50);
+        vi.advanceTimersByTime(50);
+        await promise;
+        // If we get here without hanging, the sleep resolved correctly
+        expect(true).toBe(true);
+    });
+});
+describe("mergeHeaders", () => {
+    test("merges plain objects", () => {
+        const result = mergeHeaders({ a: "1" }, { b: "2" });
+        expect(result).toEqual({ a: "1", b: "2" });
+    });
+    test("later sources override earlier", () => {
+        const result = mergeHeaders({ a: "1" }, { a: "2" });
+        expect(result).toEqual({ a: "2" });
+    });
+    test("handles Headers instance", () => {
+        const headers = new Headers();
+        headers.set("Authorization", "Bearer token");
+        const result = mergeHeaders({ a: "1" }, headers);
+        expect(result).toEqual({ a: "1", authorization: "Bearer token" });
+    });
+    test("handles tuple array", () => {
+        const tuples = [
+            ["x-custom", "value"],
+            ["x-another", "test"],
+        ];
+        const result = mergeHeaders({ a: "1" }, tuples);
+        expect(result).toEqual({ a: "1", "x-custom": "value", "x-another": "test" });
+    });
+    test("skips undefined sources", () => {
+        const result = mergeHeaders({ a: "1" }, undefined, { b: "2" });
+        expect(result).toEqual({ a: "1", b: "2" });
+    });
+    test("returns empty object for no sources", () => {
+        const result = mergeHeaders();
+        expect(result).toEqual({});
+    });
+});
+describe("HttpClient", () => {
+    function createMockFetch(responses) {
+        let callIndex = 0;
+        return vi.fn().mockImplementation(() => {
+            const response = responses[callIndex] ?? responses[responses.length - 1];
+            callIndex++;
+            return Promise.resolve({
+                ok: response.ok,
+                status: response.status ?? (response.ok ? 200 : 500),
+                json: response.json ?? (() => Promise.resolve({})),
+            });
+        });
+    }
+    describe("constructor", () => {
+        test("normalizes base URL", () => {
+            const mockFetch = createMockFetch([{ ok: true }]);
+            const client = new HttpClient("https://example.com/api", { fetchImpl: mockFetch });
+            expect(client.baseUrl).toBe("https://example.com/api/");
+        });
+        test("keeps trailing slash", () => {
+            const mockFetch = createMockFetch([{ ok: true }]);
+            const client = new HttpClient("https://example.com/api/", { fetchImpl: mockFetch });
+            expect(client.baseUrl).toBe("https://example.com/api/");
+        });
+    });
+    describe("url", () => {
+        test("builds full URL from path", () => {
+            const mockFetch = createMockFetch([]);
+            const client = new HttpClient("https://example.com/api", { fetchImpl: mockFetch });
+            expect(client.url("test")).toBe("https://example.com/api/test");
+        });
+    });
+    describe("fetch", () => {
+        beforeEach(() => {
+            vi.clearAllMocks();
+        });
+        test("makes request to correct URL", async () => {
+            const mockFetch = createMockFetch([{ ok: true }]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            await client.fetch("test");
+            expect(mockFetch).toHaveBeenCalledWith("https://example.com/test", expect.any(Object));
+        });
+        test("merges default headers", async () => {
+            const mockFetch = createMockFetch([{ ok: true }]);
+            const client = new HttpClient("https://example.com", {
+                fetchImpl: mockFetch,
+                defaultHeaders: { Authorization: "Bearer token" },
+            });
+            await client.fetch("test");
+            expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                headers: expect.objectContaining({ Authorization: "Bearer token" }),
+            }));
+        });
+        test("option headers override default headers", async () => {
+            const mockFetch = createMockFetch([{ ok: true }]);
+            const client = new HttpClient("https://example.com", {
+                fetchImpl: mockFetch,
+                defaultHeaders: { Authorization: "Bearer token", "x-default": "1" },
+            });
+            await client.fetch("test", {
+                headers: { Authorization: "Override", "x-custom": "2" },
+            });
+            expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                headers: expect.objectContaining({
+                    Authorization: "Override",
+                    "x-default": "1",
+                    "x-custom": "2",
+                }),
+            }));
+        });
+        test("throws wrapped error on fetch failure", async () => {
+            const mockFetch = vi.fn().mockRejectedValue(new Error("Network error"));
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            await expect(client.fetch("test")).rejects.toThrow("request to");
+            await expect(client.fetch("test")).rejects.toThrow("Network error");
+        });
+    });
+    describe("fetchOk", () => {
+        test("returns response when ok", async () => {
+            const mockFetch = createMockFetch([{ ok: true, status: 200 }]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            const response = await client.fetchOk("test");
+            expect(response.ok).toBe(true);
+        });
+        test("throws on non-ok response", async () => {
+            const mockFetch = createMockFetch([{ ok: false, status: 404 }]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            await expect(client.fetchOk("test")).rejects.toThrow("failed with status 404");
+            await expect(client.fetchOk("test")).rejects.toThrow("request to https://example.com/test failed with status 404");
+        });
+    });
+    describe("getJson", () => {
+        test("returns parsed JSON", async () => {
+            const mockFetch = createMockFetch([
+                { ok: true, json: () => Promise.resolve({ data: "test" }) },
+            ]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            const result = await client.getJson("test");
+            expect(result).toEqual({ data: "test" });
+        });
+        test("makes GET request", async () => {
+            const mockFetch = createMockFetch([{ ok: true }]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            await client.getJson("test");
+            expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ method: "GET" }));
+        });
+    });
+    describe("postOk", () => {
+        test("sends JSON body and returns response without parsing", async () => {
+            const mockFetch = createMockFetch([{ ok: true, status: 201 }]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            const response = await client.postOk("test", { name: "test" });
+            expect(response.ok).toBe(true);
+            expect(response.status).toBe(201);
+            expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                method: "POST",
+                headers: expect.objectContaining({ "Content-Type": "application/json" }),
+                body: JSON.stringify({ name: "test" }),
+            }));
+        });
+        test("throws on non-ok response", async () => {
+            const mockFetch = createMockFetch([{ ok: false, status: 400 }]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            await expect(client.postOk("test", { name: "test" })).rejects.toThrow("failed with status 400");
+        });
+        test("allows overriding Content-Type via options headers", async () => {
+            const mockFetch = createMockFetch([{ ok: true, status: 200 }]);
+            const client = new HttpClient("https://example.com", {
+                fetchImpl: mockFetch,
+                defaultHeaders: { Authorization: "Bearer token" },
+            });
+            await client.postOk("test", { name: "test" }, { headers: { "Content-Type": "text/plain" } });
+            expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                method: "POST",
+                headers: expect.objectContaining({
+                    Authorization: "Bearer token",
+                    "Content-Type": "text/plain",
+                }),
+            }));
+        });
+    });
+    describe("postJson", () => {
+        test("sends JSON body and returns JSON response", async () => {
+            const mockFetch = createMockFetch([{ ok: true, json: () => Promise.resolve({ id: 1 }) }]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            const result = await client.postJson("test", {
+                name: "test",
+            });
+            expect(result).toEqual({ id: 1 });
+            expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                method: "POST",
+                headers: expect.objectContaining({ "Content-Type": "application/json" }),
+                body: JSON.stringify({ name: "test" }),
+            }));
+        });
+    });
+    describe("poll", () => {
+        test("returns when condition is met", async () => {
+            let callCount = 0;
+            const mockFetch = createMockFetch([
+                { ok: true, json: () => Promise.resolve({ status: "pending" }) },
+                { ok: true, json: () => Promise.resolve({ status: "pending" }) },
+                { ok: true, json: () => Promise.resolve({ status: "done" }) },
+            ]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            const result = await client.poll("status", {
+                until: (r) => r.status === "done",
+                intervalMs: 1,
+                timeoutMs: 1000,
+                onPoll: () => {
+                    callCount++;
+                },
+            });
+            expect(result.status).toBe("done");
+            expect(callCount).toBe(3);
+        });
+        test("throws on timeout", async () => {
+            const mockFetch = createMockFetch([
+                { ok: true, json: () => Promise.resolve({ status: "pending" }) },
+            ]);
+            const client = new HttpClient("https://example.com", { fetchImpl: mockFetch });
+            await expect(client.poll("status", {
+                until: (r) => r.status === "done",
+                intervalMs: 5,
+                timeoutMs: 10,
+            })).rejects.toThrow("timed out");
+        });
+    });
+});
+//# sourceMappingURL=http.test.js.map

package/dist/utils/__tests__/http.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.test.js","sourceRoot":"","sources":["../../../src/utils/__tests__/http.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/branded.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Branded types for improved type safety.
+ *
+ * Branded types (also known as nominal or opaque types) allow TypeScript
+ * to distinguish between values that have the same underlying type but
+ * different semantic meanings.
+ *
+ * @remarks
+ * All hex-based types require lowercase `0x` prefix. Uppercase `0X` is
+ * intentionally rejected for consistency with EIP-55 and viem conventions.
+ *
+ * @example
+ * ```typescript
+ * const address: EvmAddress = toEvmAddress("0x1234...");
+ * const hex: HexString = toHexString("0xabcd...");
+ *
+ * // These are not interchangeable even though both are strings
+ * function requiresAddress(addr: EvmAddress) { ... }
+ * requiresAddress(hex); // Type error!
+ * ```
+ */
+declare const __brand: unique symbol;
+/**
+ * Creates a branded type from a base type.
+ * The brand is purely a compile-time construct and has no runtime overhead.
+ */
+export type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/**
+ * EVM address (20 bytes, hex-encoded with 0x prefix).
+ * Example: "0x1234567890123456789012345678901234567890"
+ */
+export type EvmAddress = Brand<`0x${string}`, "EvmAddress">;
+/**
+ * Generic hex-encoded string with 0x prefix.
+ * Used for raw bytes, transaction data, etc.
+ *
+ * @remarks Named HexString to avoid conflict with viem's Hex type.
+ */
+export type HexString = Brand<`0x${string}`, "HexString">;
+/**
+ * ZK circuit field element (32 bytes, hex-encoded with 0x prefix).
+ * Used in zero-knowledge proof operations.
+ * Example: "0x0000000000000000000000000000000000000000000000000000000000000001"
+ */
+export type FieldElement = Brand<`0x${string}`, "FieldElement">;
+/**
+ * Blockchain chain identifier.
+ * Must be a positive integer.
+ * Examples: 1n (Ethereum mainnet), 137n (Polygon), 42161n (Arbitrum)
+ */
+export type ChainId = Brand<bigint, "ChainId">;
+/**
+ * Merkle tree leaf index.
+ * Must be a non-negative integer.
+ */
+export type LeafIndex = Brand<bigint, "LeafIndex">;
+/**
+ * Block number on an EVM chain.
+ * Must be a non-negative integer.
+ */
+export type BlockNumber = Brand<bigint, "BlockNumber">;
+/**
+ * Checks if a string is a valid Ethereum address format.
+ */
+export declare function isEvmAddress(value: string): value is EvmAddress;
+/**
+ * Checks if a string is a valid hex string with 0x prefix.
+ */
+export declare function isHexString(value: string): value is HexString;
+/**
+ * Checks if a string is a valid 32-byte field element.
+ */
+export declare function isFieldElement(value: string): value is FieldElement;
+/**
+ * Checks if a value is a valid chain ID (positive bigint).
+ * Accepts `unknown` for runtime validation of external input.
+ */
+export declare function isChainId(value: unknown): value is ChainId;
+/**
+ * Checks if a value is a valid leaf index (non-negative bigint).
+ * Accepts `unknown` for runtime validation of external input.
+ */
+export declare function isLeafIndex(value: unknown): value is LeafIndex;
+/**
+ * Checks if a value is a valid block number (non-negative bigint).
+ * Accepts `unknown` for runtime validation of external input.
+ */
+export declare function isBlockNumber(value: unknown): value is BlockNumber;
+/**
+ * Casts a string to EvmAddress type.
+ * Use when you know the string is a valid address (e.g., from trusted source).
+ *
+ * @throws Error if the value is not a valid address format
+ */
+export declare function toEvmAddress(value: string): EvmAddress;
+/**
+ * Casts a string to HexString type.
+ *
+ * @throws Error if the value is not a valid hex format
+ */
+export declare function toHexString(value: string): HexString;
+/**
+ * Casts a string to FieldElement type.
+ *
+ * @throws Error if the value is not a valid field element format
+ */
+export declare function toFieldElement(value: string): FieldElement;
+/**
+ * Casts a bigint to ChainId type.
+ *
+ * @throws Error if the value is not positive
+ */
+export declare function toChainId(value: bigint): ChainId;
+/**
+ * Casts a bigint to LeafIndex type.
+ *
+ * @throws Error if the value is negative
+ */
+export declare function toLeafIndex(value: bigint): LeafIndex;
+/**
+ * Casts a bigint to BlockNumber type.
+ *
+ * @throws Error if the value is negative
+ */
+export declare function toBlockNumber(value: bigint): BlockNumber;
+/**
+ * Casts a string to EvmAddress type without validation.
+ * Use only when validation has already been performed or for performance-critical paths.
+ */
+export declare function asEvmAddress(value: `0x${string}`): EvmAddress;
+/**
+ * Casts a string to HexString type without validation.
+ */
+export declare function asHexString(value: `0x${string}`): HexString;
+/**
+ * Casts a string to FieldElement type without validation.
+ */
+export declare function asFieldElement(value: `0x${string}`): FieldElement;
+/**
+ * Casts a bigint to ChainId type without validation.
+ */
+export declare function asChainId(value: bigint): ChainId;
+/**
+ * Casts a bigint to LeafIndex type without validation.
+ */
+export declare function asLeafIndex(value: bigint): LeafIndex;
+/**
+ * Casts a bigint to BlockNumber type without validation.
+ */
+export declare function asBlockNumber(value: bigint): BlockNumber;
+export {};
+//# sourceMappingURL=branded.d.ts.map

package/dist/utils/branded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branded.d.ts","sourceRoot":"","sources":["../../src/utils/branded.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,CAAC,MAAM,OAAO,EAAE,OAAO,MAAM,CAAC;AAErC;;;GAGG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAEvE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,MAAM,EAAE,EAAE,YAAY,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,MAAM,EAAE,EAAE,cAAc,CAAC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAUvD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAEnE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAKtD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAKpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAK1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKhD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAKpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAKxD;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,MAAM,EAAE,GAAG,UAAU,CAE7D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,MAAM,EAAE,GAAG,SAAS,CAE3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,MAAM,EAAE,GAAG,YAAY,CAEjE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAEpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAExD"}

package/dist/utils/branded.js

@@ -0,0 +1,177 @@
+/**
+ * Branded types for improved type safety.
+ *
+ * Branded types (also known as nominal or opaque types) allow TypeScript
+ * to distinguish between values that have the same underlying type but
+ * different semantic meanings.
+ *
+ * @remarks
+ * All hex-based types require lowercase `0x` prefix. Uppercase `0X` is
+ * intentionally rejected for consistency with EIP-55 and viem conventions.
+ *
+ * @example
+ * ```typescript
+ * const address: EvmAddress = toEvmAddress("0x1234...");
+ * const hex: HexString = toHexString("0xabcd...");
+ *
+ * // These are not interchangeable even though both are strings
+ * function requiresAddress(addr: EvmAddress) { ... }
+ * requiresAddress(hex); // Type error!
+ * ```
+ */
+// ============================================================================
+// Type guards and validators
+// ============================================================================
+const ADDRESS_REGEX = /^0x[0-9a-fA-F]{40}$/;
+const HEX_REGEX = /^0x[0-9a-fA-F]*$/;
+const FIELD_ELEMENT_REGEX = /^0x[0-9a-fA-F]{64}$/;
+/**
+ * Checks if a string is a valid Ethereum address format.
+ */
+export function isEvmAddress(value) {
+    return ADDRESS_REGEX.test(value);
+}
+/**
+ * Checks if a string is a valid hex string with 0x prefix.
+ */
+export function isHexString(value) {
+    return HEX_REGEX.test(value);
+}
+/**
+ * Checks if a string is a valid 32-byte field element.
+ */
+export function isFieldElement(value) {
+    return FIELD_ELEMENT_REGEX.test(value);
+}
+/**
+ * Checks if a value is a valid chain ID (positive bigint).
+ * Accepts `unknown` for runtime validation of external input.
+ */
+export function isChainId(value) {
+    return typeof value === "bigint" && value > 0n;
+}
+/**
+ * Checks if a value is a valid leaf index (non-negative bigint).
+ * Accepts `unknown` for runtime validation of external input.
+ */
+export function isLeafIndex(value) {
+    return typeof value === "bigint" && value >= 0n;
+}
+/**
+ * Checks if a value is a valid block number (non-negative bigint).
+ * Accepts `unknown` for runtime validation of external input.
+ */
+export function isBlockNumber(value) {
+    return typeof value === "bigint" && value >= 0n;
+}
+// ============================================================================
+// Validated casting functions (throw on invalid input)
+// ============================================================================
+/**
+ * Casts a string to EvmAddress type.
+ * Use when you know the string is a valid address (e.g., from trusted source).
+ *
+ * @throws Error if the value is not a valid address format
+ */
+export function toEvmAddress(value) {
+    if (!isEvmAddress(value)) {
+        throw new Error(`Invalid address format: ${value}`);
+    }
+    return value;
+}
+/**
+ * Casts a string to HexString type.
+ *
+ * @throws Error if the value is not a valid hex format
+ */
+export function toHexString(value) {
+    if (!isHexString(value)) {
+        throw new Error(`Invalid hex format: ${value}`);
+    }
+    return value;
+}
+/**
+ * Casts a string to FieldElement type.
+ *
+ * @throws Error if the value is not a valid field element format
+ */
+export function toFieldElement(value) {
+    if (!isFieldElement(value)) {
+        throw new Error(`Invalid field element format: ${value}`);
+    }
+    return value;
+}
+/**
+ * Casts a bigint to ChainId type.
+ *
+ * @throws Error if the value is not positive
+ */
+export function toChainId(value) {
+    if (!isChainId(value)) {
+        throw new Error(`Invalid chain ID: ${value} (must be positive)`);
+    }
+    return value;
+}
+/**
+ * Casts a bigint to LeafIndex type.
+ *
+ * @throws Error if the value is negative
+ */
+export function toLeafIndex(value) {
+    if (!isLeafIndex(value)) {
+        throw new Error(`Invalid leaf index: ${value} (must be non-negative)`);
+    }
+    return value;
+}
+/**
+ * Casts a bigint to BlockNumber type.
+ *
+ * @throws Error if the value is negative
+ */
+export function toBlockNumber(value) {
+    if (!isBlockNumber(value)) {
+        throw new Error(`Invalid block number: ${value} (must be non-negative)`);
+    }
+    return value;
+}
+// ============================================================================
+// Unchecked casting functions (for performance-critical paths)
+// ============================================================================
+/**
+ * Casts a string to EvmAddress type without validation.
+ * Use only when validation has already been performed or for performance-critical paths.
+ */
+export function asEvmAddress(value) {
+    return value;
+}
+/**
+ * Casts a string to HexString type without validation.
+ */
+export function asHexString(value) {
+    return value;
+}
+/**
+ * Casts a string to FieldElement type without validation.
+ */
+export function asFieldElement(value) {
+    return value;
+}
+/**
+ * Casts a bigint to ChainId type without validation.
+ */
+export function asChainId(value) {
+    return value;
+}
+/**
+ * Casts a bigint to LeafIndex type without validation.
+ */
+export function asLeafIndex(value) {
+    return value;
+}
+/**
+ * Casts a bigint to BlockNumber type without validation.
+ */
+export function asBlockNumber(value) {
+    return value;
+}
+//# sourceMappingURL=branded.js.map

package/dist/utils/branded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branded.js","sourceRoot":"","sources":["../../src/utils/branded.ts"],"names":[],"mappings":"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"}