@circle-fin/usdckit 0.18.0 → 0.19.1

package/dist/esm/utils/getContract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getContract.d.ts","sourceRoot":"","sources":["../../../src/utils/getContract.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAE7D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAA;CACjB,GAAG,CACA;IACE,GAAG,EAAE,GAAG,CAAA;IACR,MAAM,EAAE,MAAM,CAAA;CACf,GACD;IACE,GAAG,CAAC,EAAE,KAAK,CAAA;IACX,MAAM,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,KAAK,CAAA;KAAE,CAAA;CAClC,CACJ,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBnD"}
+{"version":3,"file":"getContract.d.ts","sourceRoot":"","sources":["../../../src/utils/getContract.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAA;AAChE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAEvC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,GAAG,CAAA;CACV,GAAG,CACA;IACE,KAAK,EAAE,KAAK,CAAA;IACZ,MAAM,CAAC,EAAE,KAAK,CAAA;CACf,GACD;IACE,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CACJ,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BnD"}

package/dist/esm/utils/getContract.js

@@ -8,7 +8,7 @@
 // evidence any actual or intended publication of such source code. Disclosure
 // of this source code or any related proprietary information is strictly
 // prohibited without the express written permission of Circle Internet Group, Inc.
-import { getContract as _getContract } from 'viem';
+import { createPublicClient, getContract as _getContract, http } from 'viem';
 /**
  * Retrieves a contract instance using the provided address, ABI, and client.
  *
@@ -17,9 +17,14 @@ import { getContract as _getContract } from 'viem';
  * @returns The contract instance.
  */
 export function getContract(params) {
-    const { address, client } = params;
-    const chain = client.chain;
+    const { address } = params;
     let { abi } = params;
+    const client = params.client ??
+        createPublicClient({
+            chain: params.chain,
+            transport: http(),
+        });
+    const chain = client.chain;
     // If ABI is not provided, attempt to default to the chain's contract ABI
     if (abi === undefined && chain?.contracts !== undefined) {
         const chainContract = Object.values(chain.contracts).find((contract) => contract !== undefined && contract.address === address);

package/dist/esm/utils/getContract.js.map

@@ -1 +1 @@
-{"version":3,"file":"getContract.js","sourceRoot":"","sources":["../../../src/utils/getContract.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,uBAAuB;AACvB,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAClD,8EAA8E;AAC9E,yEAAyE;AACzE,mFAAmF;AAEnF,OAAO,EAAE,WAAW,IAAI,YAAY,EAAE,MAAM,MAAM,CAAA;AAkBlD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAwB;IAClD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;IAC1B,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAAA;IAEpB,yEAAyE;IACzE,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;QACxD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CACvD,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,SAAS,IAAK,QAA0B,CAAC,OAAO,KAAK,OAAO,CAC3D,CAAA;QAE9B,uDAAuD;QACvD,GAAG,GAAG,aAAa,EAAE,GAAsB,CAAA;IAC7C,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,EAAE,CAAC,CAAA;IAC/D,CAAC;IAED,OAAO,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAA;AAC/C,CAAC"}
+{"version":3,"file":"getContract.js","sourceRoot":"","sources":["../../../src/utils/getContract.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,uBAAuB;AACvB,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAClD,8EAA8E;AAC9E,yEAAyE;AACzE,mFAAmF;AAEnF,OAAO,EAAE,kBAAkB,EAAE,WAAW,IAAI,YAAY,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAmB5E;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAwB;IAClD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAA;IAC1B,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAAA;IAEpB,MAAM,MAAM,GACV,MAAM,CAAC,MAAM;QACb,kBAAkB,CAAC;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE,IAAI,EAAE;SAClB,CAAC,CAAA;IACJ,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;IAE1B,yEAAyE;IACzE,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;QACxD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CACvD,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,SAAS,IAAK,QAA0B,CAAC,OAAO,KAAK,OAAO,CAC3D,CAAA;QAE9B,uDAAuD;QACvD,GAAG,GAAG,aAAa,EAAE,GAAsB,CAAA;IAC7C,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,EAAE,CAAC,CAAA;IAC/D,CAAC;IAED,OAAO,YAAY,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAA;AAC/C,CAAC"}

package/dist/esm/utils/getContract.test.js

@@ -8,9 +8,15 @@
 // evidence any actual or intended publication of such source code. Disclosure
 // of this source code or any related proprietary information is strictly
 // prohibited without the express written permission of Circle Internet Group, Inc.
-import { describe, test, expect, vi, afterEach } from 'vitest';
+import { createPublicClient } from 'viem';
+import { describe, test, expect, vi, afterEach, it } from 'vitest';
 import { ETH_SEPOLIA, MATIC_AMOY } from '../chains/index.js';
 import { getContract } from './getContract.js';
+vi.mock('viem', async (importOriginal) => ({
+    ...(await importOriginal()),
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    createPublicClient: vi.fn(({ chain }) => ({ chain })),
+}));
 describe('getContract', () => {
     const client = {
         chain: ETH_SEPOLIA,
@@ -35,6 +41,18 @@ describe('getContract', () => {
     ])('should return a contract using %s', (_, params, expectedResult) => {
         expect(getContract(params)).toMatchObject(expectedResult);
     });
+    it('should return a contract using a default public client', () => {
+        expect(getContract({
+            address: ETH_SEPOLIA.contracts.USDC.address,
+            abi: [],
+            chain: ETH_SEPOLIA,
+        })).toMatchObject({
+            address: ETH_SEPOLIA.contracts.USDC.address,
+            abi: [],
+        });
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        expect(createPublicClient).toHaveBeenCalledWith({ chain: ETH_SEPOLIA, transport: expect.anything() });
+    });
     test.each([
         [
             { address: ETH_SEPOLIA.contracts.USDC.address, abi: undefined, client: {} },

package/dist/esm/utils/getContract.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"getContract.test.js","sourceRoot":"","sources":["../../../src/utils/getContract.test.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,uBAAuB;AACvB,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAClD,8EAA8E;AAC9E,yEAAyE;AACzE,mFAAmF;AAEnF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAE9D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAI9C,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,WAAW;KACQ,CAAA;IAE5B,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,eAAe,EAAE,CAAA;IACtB,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,IAAI,CAAC;QACR;YACE,cAAc;YACd,EAAE,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,EAAkB,EAAE;YACpF,EAAE,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE;SACzD;QACD;YACE,gCAAgC;YAChC;gBACE,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO;gBAC3C,MAAM;aACP;YACD,EAAE,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE;SACrF;KACO,CAAC,CAAC,mCAAmC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE;QAC7E,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,IAAI,CAAC;QACR;YACE,EAAE,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,EAAkB,EAAE;YAC3F,mCAAmC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE;SACxE;QACD;YACE;gBACE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO;gBAC1C,GAAG,EAAE,SAAS;gBACd,MAAM;aACP;YACD,mCAAmC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE;SACvE;KACO,CAAC,CAAC,kCAAkC,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE;QACxE,MAAM,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,CAAA;IAC/D,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}
+{"version":3,"file":"getContract.test.js","sourceRoot":"","sources":["../../../src/utils/getContract.test.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/groupBy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Groups array elements by a key function, similar to Object.groupBy
+ * @param items - Array of items to group
+ * @param keyFn - Function that extracts the grouping key from each item
+ * @returns Object with keys as group identifiers and values as arrays of grouped items
+ */
+export declare function groupBy<T>(items: T[], keyFn: (item: T) => string | number | symbol): Record<string | number | symbol, T[]>;
+//# sourceMappingURL=groupBy.d.ts.map

package/dist/esm/utils/groupBy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupBy.d.ts","sourceRoot":"","sources":["../../../src/utils/groupBy.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,GAAG,MAAM,yCAYlF"}

package/dist/esm/utils/groupBy.js

@@ -0,0 +1,28 @@
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+/**
+ * Groups array elements by a key function, similar to Object.groupBy
+ * @param items - Array of items to group
+ * @param keyFn - Function that extracts the grouping key from each item
+ * @returns Object with keys as group identifiers and values as arrays of grouped items
+ */
+export function groupBy(items, keyFn) {
+    const result = {};
+    for (const item of items) {
+        const key = keyFn(item);
+        if (!(key in result)) {
+            result[key] = [];
+        }
+        result[key].push(item);
+    }
+    return result;
+}
+//# sourceMappingURL=groupBy.js.map

package/dist/esm/utils/groupBy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupBy.js","sourceRoot":"","sources":["../../../src/utils/groupBy.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,uBAAuB;AACvB,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAClD,8EAA8E;AAC9E,yEAAyE;AACzE,mFAAmF;AAEnF;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAI,KAAU,EAAE,KAA4C;IACjF,MAAM,MAAM,GAA0C,EAAE,CAAA;IAExD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;QACvB,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAA;QAClB,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/esm/utils/groupBy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=groupBy.test.d.ts.map

package/dist/esm/utils/groupBy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupBy.test.d.ts","sourceRoot":"","sources":["../../../src/utils/groupBy.test.ts"],"names":[],"mappings":""}

package/dist/esm/utils/groupBy.test.js

@@ -0,0 +1,125 @@
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+import { expect, describe, it } from 'vitest';
+import { groupBy } from './groupBy.js';
+describe.concurrent('groupBy', () => {
+    it('should group numbers by even/odd', () => {
+        const numbers = [1, 2, 3, 4, 5, 6];
+        const result = groupBy(numbers, (x) => x % 2);
+        expect(result).toEqual({
+            0: [2, 4, 6],
+            1: [1, 3, 5],
+        });
+    });
+    it('should group strings by length', () => {
+        const words = ['a', 'ab', 'abc', 'abcd', 'ab', 'a'];
+        const result = groupBy(words, (word) => word.length);
+        expect(result).toEqual({
+            1: ['a', 'a'],
+            2: ['ab', 'ab'],
+            3: ['abc'],
+            4: ['abcd'],
+        });
+    });
+    it('should group objects by property', () => {
+        const people = [
+            { name: 'Alice', age: 25 },
+            { name: 'Bob', age: 30 },
+            { name: 'Charlie', age: 25 },
+            { name: 'David', age: 30 },
+        ];
+        const result = groupBy(people, (person) => person.age);
+        expect(result).toEqual({
+            25: [
+                { name: 'Alice', age: 25 },
+                { name: 'Charlie', age: 25 },
+            ],
+            30: [
+                { name: 'Bob', age: 30 },
+                { name: 'David', age: 30 },
+            ],
+        });
+    });
+    it('should handle nested object properties', () => {
+        const balances = [
+            { token: { tokenAddress: '0x123' }, amount: 100 },
+            { token: { tokenAddress: '0x456' }, amount: 200 },
+            { token: { tokenAddress: '0x123' }, amount: 300 },
+            { token: { tokenAddress: null }, amount: 400 },
+        ];
+        const result = groupBy(balances, ({ token: { tokenAddress } }) => tokenAddress ?? '');
+        expect(result).toEqual({
+            '0x123': [
+                { token: { tokenAddress: '0x123' }, amount: 100 },
+                { token: { tokenAddress: '0x123' }, amount: 300 },
+            ],
+            '0x456': [{ token: { tokenAddress: '0x456' }, amount: 200 }],
+            '': [{ token: { tokenAddress: null }, amount: 400 }],
+        });
+    });
+    it('should handle empty array', () => {
+        const result = groupBy([], (x) => x);
+        expect(result).toEqual({});
+    });
+    it('should handle array with single item', () => {
+        const result = groupBy(['single'], (x) => x.length);
+        expect(result).toEqual({
+            6: ['single'],
+        });
+    });
+    it('should group by string keys', () => {
+        const items = [
+            { category: 'fruit', name: 'apple' },
+            { category: 'vegetable', name: 'carrot' },
+            { category: 'fruit', name: 'banana' },
+            { category: 'vegetable', name: 'lettuce' },
+        ];
+        const result = groupBy(items, (item) => item.category);
+        expect(result).toEqual({
+            fruit: [
+                { category: 'fruit', name: 'apple' },
+                { category: 'fruit', name: 'banana' },
+            ],
+            vegetable: [
+                { category: 'vegetable', name: 'carrot' },
+                { category: 'vegetable', name: 'lettuce' },
+            ],
+        });
+    });
+    it('should handle symbol keys', () => {
+        const sym1 = Symbol('group1');
+        const sym2 = Symbol('group2');
+        const items = [1, 2, 3, 4];
+        const result = groupBy(items, (x) => (x % 2 === 0 ? sym1 : sym2));
+        expect(result[sym1]).toEqual([2, 4]);
+        expect(result[sym2]).toEqual([1, 3]);
+    });
+    it('should preserve order within groups', () => {
+        const items = [
+            { id: 1, group: 'A' },
+            { id: 2, group: 'B' },
+            { id: 3, group: 'A' },
+            { id: 4, group: 'B' },
+            { id: 5, group: 'A' },
+        ];
+        const result = groupBy(items, (item) => item.group);
+        expect(result.A).toEqual([
+            { id: 1, group: 'A' },
+            { id: 3, group: 'A' },
+            { id: 5, group: 'A' },
+        ]);
+        expect(result.B).toEqual([
+            { id: 2, group: 'B' },
+            { id: 4, group: 'B' },
+        ]);
+    });
+});
+//# sourceMappingURL=groupBy.test.js.map

package/dist/esm/utils/groupBy.test.js.map

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

package/dist/esm/utils/parseAccount.d.ts

@@ -3,7 +3,7 @@ import type { Account, Address, Chain } from '../types.js';
  * Parses an account address or object and adds serialization utilities.
  *
  * @param account - The account address or object to parse.
- * @returns The parsed account with added toString and toJSON methods.
+ * @returns The parsed Account object
  */
 export declare function parseAccount(account: Address, options?: {
     chain: undefined;

package/dist/esm/utils/parseAddress.d.ts

@@ -12,11 +12,8 @@ import type { Address, Chain } from '../types.js';
  * parseAddress({ address: '0x123...', chain: MATIC_AMOY }) // => { address: '0x123...', chain: MATIC_AMOY }
  * ```
  */
-export declare function parseAddress(value: Address | {
+export declare function parseAddress<T extends {
     address: Address;
     chain?: Chain;
-}): {
-    address: Address;
-    chain?: Chain;
-};
+}>(value: Address | T): T;
 //# sourceMappingURL=parseAddress.d.ts.map

package/dist/esm/utils/parseAddress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseAddress.d.ts","sourceRoot":"","sources":["../../../src/utils/parseAddress.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAClF,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAEA"}
+{"version":3,"file":"parseAddress.d.ts","sourceRoot":"","sources":["../../../src/utils/parseAddress.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAMjG"}

package/dist/esm/utils/parseAddress.js

@@ -22,6 +22,9 @@
  * ```
  */
 export function parseAddress(value) {
-    return typeof value === 'string' ? { address: value } : value;
+    if (typeof value === 'string') {
+        return { address: value };
+    }
+    return value;
 }
 //# sourceMappingURL=parseAddress.js.map

package/dist/esm/utils/parseAddress.js.map

@@ -1 +1 @@
-{"version":3,"file":"parseAddress.js","sourceRoot":"","sources":["../../../src/utils/parseAddress.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,uBAAuB;AACvB,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAClD,8EAA8E;AAC9E,yEAAyE;AACzE,mFAAmF;AAInF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,KAAoD;IAI/E,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;AAC/D,CAAC"}
+{"version":3,"file":"parseAddress.js","sourceRoot":"","sources":["../../../src/utils/parseAddress.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,uBAAuB;AACvB,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAClD,8EAA8E;AAC9E,yEAAyE;AACzE,mFAAmF;AAInF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAgD,KAAkB;IAC5F,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAO,CAAA;IAChC,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/esm/utils/parseUnitsAsToken.d.ts

@@ -0,0 +1,39 @@
+import type { Address, Chain, NativeUnits, BaseUnits } from '../types.js';
+import type { Abi } from 'viem';
+export type ParseUnitsAsTokenParams = {
+    /** The amount to transfer. */
+    value: NativeUnits | BaseUnits;
+    /** The token address (optional). */
+    token?: Address | {
+        address: Address;
+        abi?: Abi;
+    } | null;
+    /** The blockchain chain to use. */
+    chain: Chain;
+};
+/**
+ * Parses a given value into the appropriate token units based on the specified chain and token.
+ *
+ * @returns The parsed token value in base units.
+ *
+ * @example
+ * ```typescript
+ * const link = await parseUnitsAsToken(client, {
+ *   value: '1',
+ *   chain: ETH_SEPOLIA,
+ * });
+ * // => 1000000000000000000n
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const link = await parseUnitsAsToken(client, {
+ *   value: '1',
+ *   chain: ETH_SEPOLIA,
+ *   token: ETH_SEPOLIA.contracts.USDC,
+ * });
+ * // => 1000000n
+ * ```
+ */
+export declare function parseUnitsAsToken(params: ParseUnitsAsTokenParams): Promise<bigint>;
+//# sourceMappingURL=parseUnitsAsToken.d.ts.map

package/dist/esm/utils/parseUnitsAsToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseUnitsAsToken.d.ts","sourceRoot":"","sources":["../../../src/utils/parseUnitsAsToken.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACzE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAE/B,MAAM,MAAM,uBAAuB,GAAG;IACpC,8BAA8B;IAC9B,KAAK,EAAE,WAAW,GAAG,SAAS,CAAA;IAC9B,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI,CAAA;IACxD,mCAAmC;IACnC,KAAK,EAAE,KAAK,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,mBAetE"}

package/dist/esm/utils/parseUnitsAsToken.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+import { erc20Abi } from 'viem';
+import { getContract } from './getContract.js';
+import { parseAddress } from './parseAddress.js';
+import { parseUnits } from './parseUnits.js';
+/**
+ * Parses a given value into the appropriate token units based on the specified chain and token.
+ *
+ * @returns The parsed token value in base units.
+ *
+ * @example
+ * ```typescript
+ * const link = await parseUnitsAsToken(client, {
+ *   value: '1',
+ *   chain: ETH_SEPOLIA,
+ * });
+ * // => 1000000000000000000n
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const link = await parseUnitsAsToken(client, {
+ *   value: '1',
+ *   chain: ETH_SEPOLIA,
+ *   token: ETH_SEPOLIA.contracts.USDC,
+ * });
+ * // => 1000000n
+ * ```
+ */
+export async function parseUnitsAsToken(params) {
+    const { value, token: _token, chain } = params;
+    // Skip parsing
+    if (typeof value === 'bigint')
+        return value;
+    let decimals = chain.nativeCurrency.decimals;
+    if (_token != null) {
+        const { address, abi } = parseAddress(_token);
+        const token = getContract({ address, abi: abi ?? erc20Abi, chain });
+        decimals = (await token.read.decimals());
+    }
+    return parseUnits(value, decimals);
+}
+//# sourceMappingURL=parseUnitsAsToken.js.map

package/dist/esm/utils/parseUnitsAsToken.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseUnitsAsToken.js","sourceRoot":"","sources":["../../../src/utils/parseUnitsAsToken.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,uBAAuB;AACvB,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAClD,8EAA8E;AAC9E,yEAAyE;AACzE,mFAAmF;AAEnF,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAA;AAE/B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAc5C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAA+B;IACrE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAA;IAE9C,eAAe;IACf,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAE3C,IAAI,QAAQ,GAAG,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAA;IAE5C,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;QACnB,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;QAC7C,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;QACnE,QAAQ,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAW,CAAA;IACpD,CAAC;IAED,OAAO,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;AACpC,CAAC"}

package/dist/esm/utils/parseUnitsAsToken.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseUnitsAsToken.test.d.ts","sourceRoot":"","sources":["../../../src/utils/parseUnitsAsToken.test.ts"],"names":[],"mappings":""}

package/dist/esm/utils/parseUnitsAsToken.test.js

@@ -0,0 +1,75 @@
+// Copyright (c) 2025, Circle Internet Group, Inc.
+// All rights reserved.
+//
+// Circle Internet Group, Inc. CONFIDENTIAL
+//
+// This file includes unpublished proprietary source code of Circle Internet
+// Group, Inc. The copyright notice above does not
+// evidence any actual or intended publication of such source code. Disclosure
+// of this source code or any related proprietary information is strictly
+// prohibited without the express written permission of Circle Internet Group, Inc.
+import { expect, test, describe, vi } from 'vitest';
+import { ETH_SEPOLIA } from '../chains/index.js';
+// Mock the getContract function
+vi.mock('./getContract.js', () => ({
+    getContract: vi.fn(() => ({
+        abi: [],
+        read: {
+            decimals: vi.fn().mockResolvedValue(6), // USDC commonly has 6 decimals
+        },
+    })),
+}));
+import { parseUnitsAsToken } from './parseUnitsAsToken.js';
+describe.concurrent('parseUnitsAsToken', () => {
+    const client = {
+        chain: ETH_SEPOLIA,
+    };
+    test.each([
+        [
+            'bigint as input',
+            {
+                value: 1n,
+                chain: client.chain,
+            },
+            1n,
+        ],
+        [
+            'native token',
+            {
+                value: '1',
+                chain: client.chain,
+            },
+            1000000000000000000n,
+        ],
+        [
+            'local chain contract',
+            {
+                value: '1',
+                token: ETH_SEPOLIA.contracts.USDC,
+                chain: client.chain,
+            },
+            1000000n,
+        ],
+        [
+            'local chain contract as string token',
+            {
+                value: '1',
+                token: '0x1234567890abcdef1234567890abcdef12345678',
+                chain: client.chain,
+            },
+            1000000n,
+        ],
+        [
+            'default erc20 ABI',
+            {
+                value: '1',
+                token: { address: '0x1234567890abcdef1234567890abcdef12345678' },
+                chain: client.chain,
+            },
+            1000000n,
+        ],
+    ])('should return the parsed value as token base units using %s', async (_, params, expectedResult) => {
+        await expect(parseUnitsAsToken(params)).resolves.toBe(expectedResult);
+    });
+});
+//# sourceMappingURL=parseUnitsAsToken.test.js.map

package/dist/esm/utils/parseUnitsAsToken.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseUnitsAsToken.test.js","sourceRoot":"","sources":["../../../src/utils/parseUnitsAsToken.test.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,uBAAuB;AACvB,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,kDAAkD;AAClD,8EAA8E;AAC9E,yEAAyE;AACzE,mFAAmF;AAEnF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAEnD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,gCAAgC;AAChC,EAAE,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,EAAE,CAAC,CAAC;IACjC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QACxB,GAAG,EAAE,EAAE;QACP,IAAI,EAAE;YACJ,QAAQ,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,+BAA+B;SACxE;KACF,CAAC,CAAC;CACJ,CAAC,CAAC,CAAA;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAI1D,QAAQ,CAAC,UAAU,CAAC,mBAAmB,EAAE,GAAG,EAAE;IAC5C,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,WAAW;KACc,CAAA;IAElC,IAAI,CAAC,IAAI,CAAC;QACR;YACE,iBAAiB;YACjB;gBACE,KAAK,EAAE,EAAE;gBACT,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB;YACD,EAAE;SACH;QACD;YACE,cAAc;YACd;gBACE,KAAK,EAAE,GAAG;gBACV,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB;YACD,oBAAoB;SACrB;QACD;YACE,sBAAsB;YACtB;gBACE,KAAK,EAAE,GAAG;gBACV,KAAK,EAAE,WAAW,CAAC,SAAS,CAAC,IAAI;gBACjC,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB;YACD,QAAQ;SACT;QACD;YACE,sCAAsC;YACtC;gBACE,KAAK,EAAE,GAAG;gBACV,KAAK,EAAE,4CAA4C;gBACnD,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB;YACD,QAAQ;SACT;QACD;YACE,mBAAmB;YACnB;gBACE,KAAK,EAAE,GAAG;gBACV,KAAK,EAAE,EAAE,OAAO,EAAE,4CAA4C,EAAE;gBAChE,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB;YACD,QAAQ;SACT;KACO,CAAC,CAAC,6DAA6D,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE;QAC7G,MAAM,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IACvE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/esm/utils/toERC681.test.js

@@ -8,6 +8,7 @@
 // evidence any actual or intended publication of such source code. Disclosure
 // of this source code or any related proprietary information is strictly
 // prohibited without the express written permission of Circle Internet Group, Inc.
+import { erc20Abi } from 'viem';
 import { expect, test, describe } from 'vitest';
 import { toERC681 } from './toERC681.js';
 describe('toERC681', () => {
@@ -38,32 +39,7 @@ describe('toERC681', () => {
     describe('contract transaction request', () => {
         const USDC = {
             address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
-            abi: [
-                {
-                    inputs: [
-                        {
-                            internalType: 'address',
-                            name: 'to',
-                            type: 'address',
-                        },
-                        {
-                            internalType: 'uint256',
-                            name: 'value',
-                            type: 'uint256',
-                        },
-                    ],
-                    name: 'transfer',
-                    outputs: [
-                        {
-                            internalType: 'bool',
-                            name: '',
-                            type: 'bool',
-                        },
-                    ],
-                    stateMutability: 'nonpayable',
-                    type: 'function',
-                },
-            ],
+            abi: erc20Abi,
         };
         test('transfer(address, amount)', () => {
             expect(toERC681({

package/dist/esm/utils/toERC681.test.js.map

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