@circle-fin/usdckit 0.21.1 → 0.23.0

package/dist/cjs/abis/EIP2612.d.ts

@@ -0,0 +1,197 @@
+/**
+ * EIP-2612 ABI extension
+ */
+declare const _default: readonly [{
+    readonly type: "event";
+    readonly name: "Approval";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "Transfer";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "allowance";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "decimals";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "totalSupply";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "transfer";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "transferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "sender";
+        readonly type: "address";
+    }, {
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+    readonly name: "nonces";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly inputs: readonly [];
+    readonly name: "version";
+    readonly outputs: readonly [{
+        readonly internalType: "string";
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly internalType: "address";
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint8";
+        readonly name: "v";
+        readonly type: "uint8";
+    }, {
+        readonly internalType: "bytes32";
+        readonly name: "r";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "bytes32";
+        readonly name: "s";
+        readonly type: "bytes32";
+    }];
+    readonly name: "permit";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}];
+export default _default;

package/dist/cjs/abis/EIP2612.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const viem_1 = require("viem");
+/**
+ * EIP-2612 ABI extension
+ */
+exports.default = [
+    ...viem_1.erc20Abi,
+    {
+        inputs: [
+            {
+                internalType: 'address',
+                name: 'owner',
+                type: 'address',
+            },
+        ],
+        stateMutability: 'view',
+        type: 'function',
+        name: 'nonces',
+        outputs: [
+            {
+                internalType: 'uint256',
+                name: '',
+                type: 'uint256',
+            },
+        ],
+    },
+    {
+        inputs: [],
+        name: 'version',
+        outputs: [{ internalType: 'string', name: '', type: 'string' }],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [
+            {
+                internalType: 'address',
+                name: 'owner',
+                type: 'address',
+            },
+            {
+                internalType: 'address',
+                name: 'spender',
+                type: 'address',
+            },
+            {
+                internalType: 'uint256',
+                name: 'value',
+                type: 'uint256',
+            },
+            {
+                internalType: 'uint256',
+                name: 'deadline',
+                type: 'uint256',
+            },
+            {
+                internalType: 'uint8',
+                name: 'v',
+                type: 'uint8',
+            },
+            {
+                internalType: 'bytes32',
+                name: 'r',
+                type: 'bytes32',
+            },
+            {
+                internalType: 'bytes32',
+                name: 's',
+                type: 'bytes32',
+            },
+        ],
+        name: 'permit',
+        outputs: [],
+        stateMutability: 'nonpayable',
+        type: 'function',
+    },
+];

package/dist/cjs/actions/generateTransferLink.d.ts

@@ -1,5 +1,5 @@
-import type { Account, Address, NativeUnits, BaseUnits, ExtendedViemClient } from '../types.js';
-import type { Abi, Chain as ViemChain } from 'viem';
+import type { Account, Address, NativeUnits, BaseUnits } from '../types.js';
+import type { Abi, Chain as ViemChain, Client } from 'viem';
 export type GenerateTransferLinkParams = {
     /** The recipient address. */
     to: Address | Account;
@@ -32,4 +32,4 @@ export type GenerateTransferLinkParams = {
  * // => 'ethereum:0xRecipientAddress@11155111?value=100&token=0xTokenAddress'
  * ```
  */
-export declare function generateTransferLink(client: ExtendedViemClient, params: GenerateTransferLinkParams): Promise<string>;
+export declare function generateTransferLink(client: Client, params: GenerateTransferLinkParams): Promise<string>;

package/dist/cjs/actions/generateTransferLink.js

@@ -37,6 +37,9 @@ const toERC681_js_1 = require("../utils/toERC681.js");
  */
 async function generateTransferLink(client, params) {
     const { to, amount: _amount, chain: _chain = client.chain } = params;
+    if (_chain === undefined) {
+        throw new Error('chain is required');
+    }
     const toAccount = (0, parseAccount_js_1.parseAccount)(to, { chain: _chain });
     const chain = toAccount.chain;
     const token = params.token != null ? (0, parseAddress_js_1.parseAddress)(params.token) : null;

package/dist/cjs/actions/generateTransferLink.test.js

@@ -61,4 +61,21 @@ vitest_1.describe.concurrent('generateTransferLink', () => {
     ])('return a valid URL', async (params, expectedResult) => {
         await (0, vitest_1.expect)((0, generateTransferLink_js_1.generateTransferLink)(client, params)).resolves.toBe(expectedResult);
     });
+    (0, vitest_1.test)('should throw error when chain is undefined', async () => {
+        const clientWithoutChain = {
+            chain: undefined,
+            getContract: vitest_1.vi.fn(({ address }) => ({
+                address,
+                read: {
+                    decimals: vitest_1.vi.fn(() => 6),
+                },
+                abi: viem_1.erc20Abi,
+            })),
+        };
+        const params = {
+            to: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+            amount: '1',
+        };
+        await (0, vitest_1.expect)((0, generateTransferLink_js_1.generateTransferLink)(clientWithoutChain, params)).rejects.toThrow('chain is required');
+    });
 });

package/dist/cjs/actions/getSwapExactInQuote.d.ts

@@ -1,6 +1,6 @@
 import type { Chain } from '../providers/uniswap/index.js';
-import type { Address, BaseUnits, ControlFlowOptions, ExtendedViemClient, NativeUnits } from '../types.js';
-import type { Abi } from 'viem';
+import type { Address, BaseUnits, ControlFlowOptions, NativeUnits } from '../types.js';
+import type { Abi, Client } from 'viem';
 /**
  * Parameters for the {@link getSwapExactInQuote} function.
  */
@@ -68,4 +68,4 @@ export type GetSwapExactInQuoteReturnType = {
  * await client.swap({ ...quote, account })
  * ```
  */
-export declare function getSwapExactInQuote(client: ExtendedViemClient, params: GetSwapExactInQuoteParams & ControlFlowOptions): Promise<GetSwapExactInQuoteReturnType>;
+export declare function getSwapExactInQuote(client: Client, params: GetSwapExactInQuoteParams & ControlFlowOptions): Promise<GetSwapExactInQuoteReturnType>;

package/dist/cjs/actions/getTokenBalance.d.ts

@@ -0,0 +1,30 @@
+import type { Account, Address, BaseUnits, ChainContract, NativeUnits } from '../types.js';
+import type { Chain, Client } from 'viem';
+export type GetTokenBalanceInput = {
+    account: Account;
+    chain?: Chain;
+    token?: Address | ChainContract;
+};
+export type GetTokenBalanceReturnType = {
+    /**
+     * The token address, or undefined for native token
+     */
+    token: Address | undefined;
+    /**
+     * The number of decimals used by the token
+     */
+    decimals: number | undefined;
+    /**
+     * The token symbol (e.g., "ETH", "USDC")
+     */
+    symbol: string | undefined;
+    /**
+     * The balance value in the smallest indivisible unit
+     */
+    value: BaseUnits;
+    /**
+     * The formatted balance
+     */
+    formatted: NativeUnits;
+};
+export declare function getTokenBalance(client: Client, params: GetTokenBalanceInput): Promise<GetTokenBalanceReturnType>;

package/dist/cjs/actions/getTokenBalance.js

@@ -0,0 +1,51 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTokenBalance = getTokenBalance;
+const viem_1 = require("viem");
+const actions_1 = require("viem/actions");
+const utils_1 = require("viem/utils");
+const getClient_js_1 = require("../utils/getClient.js");
+async function getTokenBalance(client, params) {
+    const { account, token } = params;
+    // Get the client for the given chain.
+    const chain = (account['chain'] ?? params.chain ?? client.chain);
+    const _client = (0, getClient_js_1.getClient)(client, chain);
+    const readContract = (0, utils_1.getAction)(_client, actions_1.readContract, 'readContract');
+    const getBalance = (0, utils_1.getAction)(_client, actions_1.getBalance, 'getBalance');
+    // If token is given, get the balance of the given token from reading the contract.
+    if (token !== undefined) {
+        const address = typeof token === 'string' ? token : token.address;
+        const abi = viem_1.erc20Abi;
+        const [balance, decimals, symbol] = await Promise.all([
+            readContract({ address, abi, functionName: 'balanceOf', args: [account.address] }),
+            readContract({ address, abi, functionName: 'decimals' }),
+            readContract({ address, abi, functionName: 'symbol' }),
+        ]);
+        return {
+            token: address,
+            decimals,
+            symbol,
+            value: balance,
+            formatted: (0, utils_1.formatUnits)(balance, decimals),
+        };
+    }
+    // Get the balance of the native token.
+    const balance = await getBalance({ address: account.address });
+    return {
+        token: undefined,
+        decimals: chain.nativeCurrency.decimals,
+        symbol: chain.nativeCurrency.symbol,
+        value: balance,
+        formatted: (0, utils_1.formatUnits)(balance, chain.nativeCurrency.decimals),
+    };
+}

package/dist/cjs/actions/getTokenBalance.test.js

@@ -0,0 +1,165 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+const viem_1 = require("viem");
+const vitest_1 = require("vitest");
+const index_js_1 = require("../chains/index.js");
+const getTokenBalance_js_1 = require("./getTokenBalance.js");
+vitest_1.vi.mock('../utils/getClient.js', () => ({
+    getClient: vitest_1.vi.fn((client, _chain) => client),
+}));
+(0, vitest_1.describe)('getTokenBalance()', () => {
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.restoreAllMocks();
+    });
+    const mockClient = {
+        chain: index_js_1.ETH_SEPOLIA,
+        readContract: vitest_1.vi.fn(),
+        getBalance: vitest_1.vi.fn(),
+    };
+    (0, vitest_1.it)('should get ERC20 token balance', async () => {
+        const account = { address: '0x123' };
+        const tokenAddress = '0xabc';
+        mockClient.readContract
+            .mockResolvedValueOnce(1000000n) // balanceOf
+            .mockResolvedValueOnce(6) // decimals
+            .mockResolvedValueOnce('USDC'); // symbol
+        const result = await (0, getTokenBalance_js_1.getTokenBalance)(mockClient, {
+            account,
+            token: tokenAddress,
+        });
+        (0, vitest_1.expect)(mockClient.readContract).toHaveBeenCalledTimes(3);
+        (0, vitest_1.expect)(mockClient.readContract).toHaveBeenNthCalledWith(1, {
+            address: tokenAddress,
+            abi: viem_1.erc20Abi,
+            functionName: 'balanceOf',
+            args: [account.address],
+        });
+        (0, vitest_1.expect)(mockClient.readContract).toHaveBeenNthCalledWith(2, {
+            address: tokenAddress,
+            abi: viem_1.erc20Abi,
+            functionName: 'decimals',
+        });
+        (0, vitest_1.expect)(mockClient.readContract).toHaveBeenNthCalledWith(3, {
+            address: tokenAddress,
+            abi: viem_1.erc20Abi,
+            functionName: 'symbol',
+        });
+        (0, vitest_1.expect)(result).toEqual({
+            token: tokenAddress,
+            decimals: 6,
+            symbol: 'USDC',
+            value: 1000000n,
+            formatted: '1',
+        });
+    });
+    (0, vitest_1.it)('should get ERC20 token balance with ChainContract input', async () => {
+        const account = { address: '0x123' };
+        const token = { address: '0xabc' };
+        mockClient.readContract
+            .mockResolvedValueOnce(500000n) // balanceOf
+            .mockResolvedValueOnce(18) // decimals
+            .mockResolvedValueOnce('WETH'); // symbol
+        const result = await (0, getTokenBalance_js_1.getTokenBalance)(mockClient, {
+            account,
+            token,
+        });
+        (0, vitest_1.expect)(result).toEqual({
+            token: token.address,
+            decimals: 18,
+            symbol: 'WETH',
+            value: 500000n,
+            formatted: '0.0000000000005',
+        });
+    });
+    (0, vitest_1.it)('should get native token balance', async () => {
+        const account = { address: '0x123' };
+        mockClient.getBalance.mockResolvedValueOnce(2000000000000000000n); // 2 ETH
+        const result = await (0, getTokenBalance_js_1.getTokenBalance)(mockClient, {
+            account,
+        });
+        (0, vitest_1.expect)(mockClient.getBalance).toHaveBeenCalledWith({
+            address: account.address,
+        });
+        (0, vitest_1.expect)(result).toEqual({
+            token: undefined,
+            decimals: index_js_1.ETH_SEPOLIA.nativeCurrency.decimals,
+            symbol: index_js_1.ETH_SEPOLIA.nativeCurrency.symbol,
+            value: 2000000000000000000n,
+            formatted: '2',
+        });
+    });
+    (0, vitest_1.it)('should use account chain when provided', async () => {
+        const account = { address: '0x123', chain: index_js_1.MATIC_AMOY };
+        mockClient.getBalance.mockResolvedValueOnce(1000000000000000000n); // 1 MATIC
+        const result = await (0, getTokenBalance_js_1.getTokenBalance)(mockClient, {
+            account,
+        });
+        (0, vitest_1.expect)(result).toEqual({
+            token: undefined,
+            decimals: index_js_1.MATIC_AMOY.nativeCurrency.decimals,
+            symbol: index_js_1.MATIC_AMOY.nativeCurrency.symbol,
+            value: 1000000000000000000n,
+            formatted: '1',
+        });
+    });
+    (0, vitest_1.it)('should use explicit chain parameter', async () => {
+        const account = { address: '0x123' };
+        mockClient.getBalance.mockResolvedValueOnce(1500000000000000000n); // 1.5 MATIC
+        const result = await (0, getTokenBalance_js_1.getTokenBalance)(mockClient, {
+            account,
+            chain: index_js_1.MATIC_AMOY,
+        });
+        (0, vitest_1.expect)(result).toEqual({
+            token: undefined,
+            decimals: index_js_1.MATIC_AMOY.nativeCurrency.decimals,
+            symbol: index_js_1.MATIC_AMOY.nativeCurrency.symbol,
+            value: 1500000000000000000n,
+            formatted: '1.5',
+        });
+    });
+    (0, vitest_1.it)('should handle string token address', async () => {
+        const account = { address: '0x123' };
+        const token = '0xdef';
+        mockClient.readContract
+            .mockResolvedValueOnce(750000n) // balanceOf
+            .mockResolvedValueOnce(8) // decimals
+            .mockResolvedValueOnce('DAI'); // symbol
+        const result = await (0, getTokenBalance_js_1.getTokenBalance)(mockClient, {
+            account,
+            token,
+        });
+        (0, vitest_1.expect)(result.token).toBe(token);
+        (0, vitest_1.expect)(result.decimals).toBe(8);
+        (0, vitest_1.expect)(result.symbol).toBe('DAI');
+        (0, vitest_1.expect)(result.value).toBe(750000n);
+        (0, vitest_1.expect)(result.formatted).toBe('0.0075');
+    });
+    (0, vitest_1.it)('should handle zero balances', async () => {
+        const account = { address: '0x123' };
+        mockClient.getBalance.mockResolvedValueOnce(0n);
+        const result = await (0, getTokenBalance_js_1.getTokenBalance)(mockClient, {
+            account,
+        });
+        (0, vitest_1.expect)(result.value).toBe(0n);
+        (0, vitest_1.expect)(result.formatted).toBe('0');
+    });
+    (0, vitest_1.it)('should handle contract call failures', async () => {
+        const account = { address: '0x123' };
+        const tokenAddress = '0xabc';
+        mockClient.readContract.mockRejectedValueOnce(new Error('Contract call failed'));
+        await (0, vitest_1.expect)((0, getTokenBalance_js_1.getTokenBalance)(mockClient, {
+            account,
+            token: tokenAddress,
+        })).rejects.toThrow('Contract call failed');
+    });
+});