@octaflowlabs/onchain-sdk 1.1.3 → 1.2.0

package/README.md

@@ -1 +1,53 @@
-# onchain-sdk
+# onchain-sdk
+
+Lightweight TypeScript SDK for EVM onchain utilities. It provides helpers for
+balances, transaction building, broadcasting, gas estimation, and wallet
+derivation.
+
+## Install
+
+Install with npm or yarn.
+
+## How to use
+
+- Add the package to the project and import the helpers needed.
+- Provide a valid RPC URL (public or private) and the target chain ID.
+- Call the balance, transaction, or signing helpers based on your flow.
+- Handle errors at the call site and decide how often to poll or refresh.
+
+## What this SDK provides
+
+Balances
+
+- Fetch native token balances for an address.
+- Fetch ERC-20 token balances for an address.
+- Fetch multiple token balances across multiple chains with multicall batching.
+
+Transactions
+
+- Build unsigned native or ERC-20 transfer transactions.
+- Estimate gas limits and fee data from a provider.
+- Broadcast signed transactions.
+- Check transaction status and receipt confirmation.
+
+Wallets and signing
+
+- Generate and derive EVM wallets from entropy.
+- Sign messages and transactions.
+
+Utilities
+
+- Format and parse amounts for display.
+- Normalize addresses and shorten hashes.
+- Transform bigint values for UI use.
+
+ABIs and constants
+
+- ERC-20 ABI for balance and transfer calls.
+- Multicall3 ABI and address for batched reads.
+- Gas limit defaults per transaction type.
+
+## Design notes
+
+- The SDK is stateless and transport-agnostic. It expects a caller-provided RPC URL.
+- Caching, polling, and background jobs should be handled by the consumer app or backend.

package/dist/ABIs/MULTICALL3_ABI.d.ts

@@ -0,0 +1,65 @@
+declare const _default: readonly [{
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "address";
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "callData";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct Multicall3.Call[]";
+        readonly name: "calls";
+        readonly type: "tuple[]";
+    }];
+    readonly name: "aggregate";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "blockNumber";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "bytes[]";
+        readonly name: "returnData";
+        readonly type: "bytes[]";
+    }];
+    readonly stateMutability: "payable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "address";
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly internalType: "bool";
+            readonly name: "allowFailure";
+            readonly type: "bool";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "callData";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct Multicall3.Call3[]";
+        readonly name: "calls";
+        readonly type: "tuple[]";
+    }];
+    readonly name: "aggregate3";
+    readonly outputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "bool";
+            readonly name: "success";
+            readonly type: "bool";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "returnData";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct Multicall3.Result[]";
+        readonly name: "returnData";
+        readonly type: "tuple[]";
+    }];
+    readonly stateMutability: "payable";
+    readonly type: "function";
+}];
+export default _default;

package/dist/ABIs/MULTICALL3_ABI.js

@@ -0,0 +1,52 @@
+// & Multicall3 ABI - standard contract deployed on most EVM chains
+// & https://www.multicall3.com/
+export default [
+    {
+        inputs: [
+            {
+                components: [
+                    { internalType: 'address', name: 'target', type: 'address' },
+                    { internalType: 'bytes', name: 'callData', type: 'bytes' },
+                ],
+                internalType: 'struct Multicall3.Call[]',
+                name: 'calls',
+                type: 'tuple[]',
+            },
+        ],
+        name: 'aggregate',
+        outputs: [
+            { internalType: 'uint256', name: 'blockNumber', type: 'uint256' },
+            { internalType: 'bytes[]', name: 'returnData', type: 'bytes[]' },
+        ],
+        stateMutability: 'payable',
+        type: 'function',
+    },
+    {
+        inputs: [
+            {
+                components: [
+                    { internalType: 'address', name: 'target', type: 'address' },
+                    { internalType: 'bool', name: 'allowFailure', type: 'bool' },
+                    { internalType: 'bytes', name: 'callData', type: 'bytes' },
+                ],
+                internalType: 'struct Multicall3.Call3[]',
+                name: 'calls',
+                type: 'tuple[]',
+            },
+        ],
+        name: 'aggregate3',
+        outputs: [
+            {
+                components: [
+                    { internalType: 'bool', name: 'success', type: 'bool' },
+                    { internalType: 'bytes', name: 'returnData', type: 'bytes' },
+                ],
+                internalType: 'struct Multicall3.Result[]',
+                name: 'returnData',
+                type: 'tuple[]',
+            },
+        ],
+        stateMutability: 'payable',
+        type: 'function',
+    },
+];

package/dist/blockchain/broadcastTransaction.js

@@ -3,7 +3,10 @@ import { Transaction } from 'ethers';
 /** local imports */
 import { getProvider } from './getProvider';
 import { errorMessagesForBroadcast, handleErrorMessages } from '../utils/handleErrorMessages';
+import { ensurePublicHost, testJsonRpc } from '../rpc';
 export const broadcastTransaction = async ({ signedTx, rpcUrl, chainId, waitConfirmations = 0, }) => {
+    await ensurePublicHost(rpcUrl);
+    await testJsonRpc(rpcUrl, 'eth_chainId', []);
     const provider = getProvider(rpcUrl, chainId);
     if (!provider)
         throw new Error('Could not create provider with given rpcUrl');

package/dist/blockchain/buildUnsignedTransferTx.js

@@ -3,7 +3,10 @@ import { Interface, formatUnits, parseUnits } from 'ethers';
 /** local imports */
 import { getProvider } from './getProvider';
 import { estimateGasLimitFromProvider } from './estimateGasLimitFromProvider';
+import { ensurePublicHost, testJsonRpc } from '../rpc';
 export const buildUnsignedTransferTx = async (options) => {
+    await ensurePublicHost(options.rpcUrl);
+    await testJsonRpc(options.rpcUrl, 'eth_chainId', []);
     const provider = getProvider(options.rpcUrl, options.chainId);
     if (!provider)
         throw new Error('Could not create provider with given rpcUrl and chainId');

package/dist/blockchain/estimateGasLimitFromProvider.js

@@ -29,6 +29,12 @@ export const estimateGasLimitFromProvider = async ({ provider, unsignedTx, walle
         }
         const bufferPercentage = Math.min(Math.max(Math.round(congestionFactor * 5), 5), 30); // 5% to 30% buffer
         const newGasLimit = gasEstimated + (gasEstimated * BigInt(bufferPercentage)) / BigInt(100);
+        // let suggested: GasFeesApiResponse | undefined = undefined
+        // try {
+        //   suggested = await this.getSuggestedGasPrice((await provider.getNetwork()).chainId)
+        // } catch {
+        //   suggested = undefined
+        // }
         return {
             gasEstimated,
             gasLimit: newGasLimit,

package/dist/blockchain/getBalances.d.ts

@@ -0,0 +1,3 @@
+import { GetBalanceParams, GetBalanceResult, GetBalancesParams } from '../types/common';
+export declare const getBalance: ({ walletAddress, rpcUrl, tokenAddress, chainId }: GetBalanceParams) => Promise<any> | undefined;
+export declare const getBalances: ({ walletAddress, chains: chainRequests, }: GetBalancesParams) => Promise<GetBalanceResult>;

package/dist/blockchain/getBalances.js

@@ -0,0 +1,121 @@
+/** npm imports */
+import { Contract, Interface } from 'ethers';
+/** local imports */
+import { getProvider } from './getProvider';
+import ERC20_TOKEN_CONTRACT_ABI from '../ABIs/ERC20_TOKEN_CONTRACT_ABI';
+import MULTICALL3_ABI from '../ABIs/MULTICALL3_ABI';
+import { MULTICALL3_ADDRESS } from '../constants/constants';
+import { handleErrorMessages } from '../utils/handleErrorMessages';
+export const getBalance = ({ walletAddress, rpcUrl, tokenAddress, chainId }) => {
+    const provider = getProvider(rpcUrl, chainId);
+    if (!provider)
+        throw new Error('Failed to create provider with the given RPC URL and chain ID.');
+    try {
+        if (!tokenAddress)
+            return provider.getBalance(walletAddress);
+        const tokenContract = new Contract(tokenAddress, ERC20_TOKEN_CONTRACT_ABI, provider);
+        return tokenContract.balanceOf(walletAddress);
+    }
+    catch (error) {
+        console.error('Error fetching balance:', error);
+        handleErrorMessages({ e: error, message: 'Error fetching balance' });
+    }
+};
+const buildChainKey = (rpcUrl, chainId) => `${rpcUrl}|${chainId ?? 'default'}`;
+const buildRequestKey = ({ walletAddress, rpcUrl, chainId, tokenAddress, }) => {
+    const walletKey = walletAddress.toLowerCase();
+    const tokenKey = tokenAddress ? tokenAddress.toLowerCase() : 'native';
+    const chainKey = chainId ?? 'default';
+    return `${walletKey}|${rpcUrl}|${chainKey}|${tokenKey}`;
+};
+const fetchTokenBalancesWithMulticall = async (walletAddress, tokenAddresses, rpcUrl, chainId) => {
+    const provider = getProvider(rpcUrl, chainId);
+    if (!provider)
+        return tokenAddresses.map(() => null);
+    try {
+        const erc20Interface = new Interface(ERC20_TOKEN_CONTRACT_ABI);
+        const multicall = new Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, provider);
+        const calls = tokenAddresses.map((tokenAddress) => ({
+            target: tokenAddress,
+            allowFailure: true,
+            callData: erc20Interface.encodeFunctionData('balanceOf', [walletAddress]),
+        }));
+        const results = await multicall.aggregate3.staticCall(calls);
+        return results.map((result, index) => {
+            if (!result.success || result.returnData === '0x')
+                return null;
+            try {
+                const decoded = erc20Interface.decodeFunctionResult('balanceOf', result.returnData);
+                return decoded[0];
+            }
+            catch {
+                console.error(`Failed to decode balance for token ${tokenAddresses[index]}`);
+                return null;
+            }
+        });
+    }
+    catch (error) {
+        console.error('Multicall failed, falling back to individual calls:', error);
+        return Promise.allSettled(tokenAddresses.map((tokenAddress) => getBalance({ walletAddress, rpcUrl, tokenAddress, chainId }))).then((results) => results.map((r) => (r.status === 'fulfilled' && r.value ? r.value : null)));
+    }
+};
+export const getBalances = async ({ walletAddress, chains: chainRequests, }) => {
+    const chainGroups = new Map();
+    chainRequests.forEach(({ rpcUrl, chainId, tokenAddresses, includeNative }) => {
+        const chainKey = buildChainKey(rpcUrl, chainId);
+        if (!chainGroups.has(chainKey)) {
+            chainGroups.set(chainKey, {
+                rpcUrl,
+                chainId,
+                nativeBalanceRequests: [],
+                tokenBalanceRequests: [],
+            });
+        }
+        const group = chainGroups.get(chainKey);
+        if (includeNative) {
+            const nativeRequest = { walletAddress, rpcUrl, chainId };
+            const key = buildRequestKey(nativeRequest);
+            if (!group.nativeBalanceRequests.some((r) => buildRequestKey(r) === key))
+                group.nativeBalanceRequests.push(nativeRequest);
+        }
+        tokenAddresses.forEach((tokenAddress) => {
+            const request = { walletAddress, rpcUrl, chainId, tokenAddress };
+            const key = buildRequestKey(request);
+            if (!group.tokenBalanceRequests.some((r) => buildRequestKey(r) === key))
+                group.tokenBalanceRequests.push(request);
+        });
+    });
+    const chainResults = await Promise.allSettled(Array.from(chainGroups.values()).map(async (group) => {
+        const tokenBalances = [];
+        const nativeResults = await Promise.allSettled(group.nativeBalanceRequests.map((request) => getBalance(request)));
+        nativeResults.forEach((result) => {
+            tokenBalances.push({
+                tokenAddress: null,
+                balance: result.status === 'fulfilled' ? (result.value ?? null) : null,
+                error: result.status === 'rejected' ? result.reason : undefined,
+            });
+        });
+        if (group.tokenBalanceRequests.length > 0) {
+            const tokenAddresses = group.tokenBalanceRequests.map((r) => r.tokenAddress);
+            const balances = await fetchTokenBalancesWithMulticall(walletAddress, tokenAddresses, group.rpcUrl, group.chainId);
+            balances.forEach((balance, index) => {
+                tokenBalances.push({
+                    tokenAddress: group.tokenBalanceRequests[index].tokenAddress ?? null,
+                    balance,
+                    error: balance === null ? 'Failed to fetch balance' : undefined,
+                });
+            });
+        }
+        return {
+            chainId: group.chainId,
+            balances: tokenBalances,
+        };
+    }));
+    const chainsWithBalances = chainResults
+        .filter((result) => result.status === 'fulfilled')
+        .map((result) => result.value);
+    return {
+        walletAddress,
+        chains: chainsWithBalances,
+    };
+};

package/dist/cjs/ABIs/MULTICALL3_ABI.d.ts

@@ -0,0 +1,65 @@
+declare const _default: readonly [{
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "address";
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "callData";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct Multicall3.Call[]";
+        readonly name: "calls";
+        readonly type: "tuple[]";
+    }];
+    readonly name: "aggregate";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "blockNumber";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "bytes[]";
+        readonly name: "returnData";
+        readonly type: "bytes[]";
+    }];
+    readonly stateMutability: "payable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "address";
+            readonly name: "target";
+            readonly type: "address";
+        }, {
+            readonly internalType: "bool";
+            readonly name: "allowFailure";
+            readonly type: "bool";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "callData";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct Multicall3.Call3[]";
+        readonly name: "calls";
+        readonly type: "tuple[]";
+    }];
+    readonly name: "aggregate3";
+    readonly outputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "bool";
+            readonly name: "success";
+            readonly type: "bool";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "returnData";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct Multicall3.Result[]";
+        readonly name: "returnData";
+        readonly type: "tuple[]";
+    }];
+    readonly stateMutability: "payable";
+    readonly type: "function";
+}];
+export default _default;

package/dist/cjs/ABIs/MULTICALL3_ABI.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// & Multicall3 ABI - standard contract deployed on most EVM chains
+// & https://www.multicall3.com/
+exports.default = [
+    {
+        inputs: [
+            {
+                components: [
+                    { internalType: 'address', name: 'target', type: 'address' },
+                    { internalType: 'bytes', name: 'callData', type: 'bytes' },
+                ],
+                internalType: 'struct Multicall3.Call[]',
+                name: 'calls',
+                type: 'tuple[]',
+            },
+        ],
+        name: 'aggregate',
+        outputs: [
+            { internalType: 'uint256', name: 'blockNumber', type: 'uint256' },
+            { internalType: 'bytes[]', name: 'returnData', type: 'bytes[]' },
+        ],
+        stateMutability: 'payable',
+        type: 'function',
+    },
+    {
+        inputs: [
+            {
+                components: [
+                    { internalType: 'address', name: 'target', type: 'address' },
+                    { internalType: 'bool', name: 'allowFailure', type: 'bool' },
+                    { internalType: 'bytes', name: 'callData', type: 'bytes' },
+                ],
+                internalType: 'struct Multicall3.Call3[]',
+                name: 'calls',
+                type: 'tuple[]',
+            },
+        ],
+        name: 'aggregate3',
+        outputs: [
+            {
+                components: [
+                    { internalType: 'bool', name: 'success', type: 'bool' },
+                    { internalType: 'bytes', name: 'returnData', type: 'bytes' },
+                ],
+                internalType: 'struct Multicall3.Result[]',
+                name: 'returnData',
+                type: 'tuple[]',
+            },
+        ],
+        stateMutability: 'payable',
+        type: 'function',
+    },
+];

package/dist/cjs/blockchain/broadcastTransaction.js

@@ -6,7 +6,10 @@ const ethers_1 = require("ethers");
 /** local imports */
 const getProvider_1 = require("./getProvider");
 const handleErrorMessages_1 = require("../utils/handleErrorMessages");
+const rpc_1 = require("../rpc");
 const broadcastTransaction = async ({ signedTx, rpcUrl, chainId, waitConfirmations = 0, }) => {
+    await (0, rpc_1.ensurePublicHost)(rpcUrl);
+    await (0, rpc_1.testJsonRpc)(rpcUrl, 'eth_chainId', []);
     const provider = (0, getProvider_1.getProvider)(rpcUrl, chainId);
     if (!provider)
         throw new Error('Could not create provider with given rpcUrl');

package/dist/cjs/blockchain/buildUnsignedTransferTx.js

@@ -6,7 +6,10 @@ const ethers_1 = require("ethers");
 /** local imports */
 const getProvider_1 = require("./getProvider");
 const estimateGasLimitFromProvider_1 = require("./estimateGasLimitFromProvider");
+const rpc_1 = require("../rpc");
 const buildUnsignedTransferTx = async (options) => {
+    await (0, rpc_1.ensurePublicHost)(options.rpcUrl);
+    await (0, rpc_1.testJsonRpc)(options.rpcUrl, 'eth_chainId', []);
     const provider = (0, getProvider_1.getProvider)(options.rpcUrl, options.chainId);
     if (!provider)
         throw new Error('Could not create provider with given rpcUrl and chainId');

package/dist/cjs/blockchain/estimateGasLimitFromProvider.js

@@ -32,6 +32,12 @@ const estimateGasLimitFromProvider = async ({ provider, unsignedTx, walletAddres
         }
         const bufferPercentage = Math.min(Math.max(Math.round(congestionFactor * 5), 5), 30); // 5% to 30% buffer
         const newGasLimit = gasEstimated + (gasEstimated * BigInt(bufferPercentage)) / BigInt(100);
+        // let suggested: GasFeesApiResponse | undefined = undefined
+        // try {
+        //   suggested = await this.getSuggestedGasPrice((await provider.getNetwork()).chainId)
+        // } catch {
+        //   suggested = undefined
+        // }
         return {
             gasEstimated,
             gasLimit: newGasLimit,

package/dist/cjs/blockchain/getBalances.d.ts

@@ -0,0 +1,3 @@
+import { GetBalanceParams, GetBalanceResult, GetBalancesParams } from '../types/common';
+export declare const getBalance: ({ walletAddress, rpcUrl, tokenAddress, chainId }: GetBalanceParams) => Promise<any> | undefined;
+export declare const getBalances: ({ walletAddress, chains: chainRequests, }: GetBalancesParams) => Promise<GetBalanceResult>;

package/dist/cjs/blockchain/getBalances.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBalances = exports.getBalance = void 0;
+/** npm imports */
+const ethers_1 = require("ethers");
+/** local imports */
+const getProvider_1 = require("./getProvider");
+const ERC20_TOKEN_CONTRACT_ABI_1 = __importDefault(require("../ABIs/ERC20_TOKEN_CONTRACT_ABI"));
+const MULTICALL3_ABI_1 = __importDefault(require("../ABIs/MULTICALL3_ABI"));
+const constants_1 = require("../constants/constants");
+const handleErrorMessages_1 = require("../utils/handleErrorMessages");
+const getBalance = ({ walletAddress, rpcUrl, tokenAddress, chainId }) => {
+    const provider = (0, getProvider_1.getProvider)(rpcUrl, chainId);
+    if (!provider)
+        throw new Error('Failed to create provider with the given RPC URL and chain ID.');
+    try {
+        if (!tokenAddress)
+            return provider.getBalance(walletAddress);
+        const tokenContract = new ethers_1.Contract(tokenAddress, ERC20_TOKEN_CONTRACT_ABI_1.default, provider);
+        return tokenContract.balanceOf(walletAddress);
+    }
+    catch (error) {
+        console.error('Error fetching balance:', error);
+        (0, handleErrorMessages_1.handleErrorMessages)({ e: error, message: 'Error fetching balance' });
+    }
+};
+exports.getBalance = getBalance;
+const buildChainKey = (rpcUrl, chainId) => `${rpcUrl}|${chainId ?? 'default'}`;
+const buildRequestKey = ({ walletAddress, rpcUrl, chainId, tokenAddress, }) => {
+    const walletKey = walletAddress.toLowerCase();
+    const tokenKey = tokenAddress ? tokenAddress.toLowerCase() : 'native';
+    const chainKey = chainId ?? 'default';
+    return `${walletKey}|${rpcUrl}|${chainKey}|${tokenKey}`;
+};
+const fetchTokenBalancesWithMulticall = async (walletAddress, tokenAddresses, rpcUrl, chainId) => {
+    const provider = (0, getProvider_1.getProvider)(rpcUrl, chainId);
+    if (!provider)
+        return tokenAddresses.map(() => null);
+    try {
+        const erc20Interface = new ethers_1.Interface(ERC20_TOKEN_CONTRACT_ABI_1.default);
+        const multicall = new ethers_1.Contract(constants_1.MULTICALL3_ADDRESS, MULTICALL3_ABI_1.default, provider);
+        const calls = tokenAddresses.map((tokenAddress) => ({
+            target: tokenAddress,
+            allowFailure: true,
+            callData: erc20Interface.encodeFunctionData('balanceOf', [walletAddress]),
+        }));
+        const results = await multicall.aggregate3.staticCall(calls);
+        return results.map((result, index) => {
+            if (!result.success || result.returnData === '0x')
+                return null;
+            try {
+                const decoded = erc20Interface.decodeFunctionResult('balanceOf', result.returnData);
+                return decoded[0];
+            }
+            catch {
+                console.error(`Failed to decode balance for token ${tokenAddresses[index]}`);
+                return null;
+            }
+        });
+    }
+    catch (error) {
+        console.error('Multicall failed, falling back to individual calls:', error);
+        return Promise.allSettled(tokenAddresses.map((tokenAddress) => (0, exports.getBalance)({ walletAddress, rpcUrl, tokenAddress, chainId }))).then((results) => results.map((r) => (r.status === 'fulfilled' && r.value ? r.value : null)));
+    }
+};
+const getBalances = async ({ walletAddress, chains: chainRequests, }) => {
+    const chainGroups = new Map();
+    chainRequests.forEach(({ rpcUrl, chainId, tokenAddresses, includeNative }) => {
+        const chainKey = buildChainKey(rpcUrl, chainId);
+        if (!chainGroups.has(chainKey)) {
+            chainGroups.set(chainKey, {
+                rpcUrl,
+                chainId,
+                nativeBalanceRequests: [],
+                tokenBalanceRequests: [],
+            });
+        }
+        const group = chainGroups.get(chainKey);
+        if (includeNative) {
+            const nativeRequest = { walletAddress, rpcUrl, chainId };
+            const key = buildRequestKey(nativeRequest);
+            if (!group.nativeBalanceRequests.some((r) => buildRequestKey(r) === key))
+                group.nativeBalanceRequests.push(nativeRequest);
+        }
+        tokenAddresses.forEach((tokenAddress) => {
+            const request = { walletAddress, rpcUrl, chainId, tokenAddress };
+            const key = buildRequestKey(request);
+            if (!group.tokenBalanceRequests.some((r) => buildRequestKey(r) === key))
+                group.tokenBalanceRequests.push(request);
+        });
+    });
+    const chainResults = await Promise.allSettled(Array.from(chainGroups.values()).map(async (group) => {
+        const tokenBalances = [];
+        const nativeResults = await Promise.allSettled(group.nativeBalanceRequests.map((request) => (0, exports.getBalance)(request)));
+        nativeResults.forEach((result) => {
+            tokenBalances.push({
+                tokenAddress: null,
+                balance: result.status === 'fulfilled' ? (result.value ?? null) : null,
+                error: result.status === 'rejected' ? result.reason : undefined,
+            });
+        });
+        if (group.tokenBalanceRequests.length > 0) {
+            const tokenAddresses = group.tokenBalanceRequests.map((r) => r.tokenAddress);
+            const balances = await fetchTokenBalancesWithMulticall(walletAddress, tokenAddresses, group.rpcUrl, group.chainId);
+            balances.forEach((balance, index) => {
+                tokenBalances.push({
+                    tokenAddress: group.tokenBalanceRequests[index].tokenAddress ?? null,
+                    balance,
+                    error: balance === null ? 'Failed to fetch balance' : undefined,
+                });
+            });
+        }
+        return {
+            chainId: group.chainId,
+            balances: tokenBalances,
+        };
+    }));
+    const chainsWithBalances = chainResults
+        .filter((result) => result.status === 'fulfilled')
+        .map((result) => result.value);
+    return {
+        walletAddress,
+        chains: chainsWithBalances,
+    };
+};
+exports.getBalances = getBalances;

package/dist/cjs/constants/constants.d.ts

@@ -3,3 +3,4 @@ export declare const GAS_LIMIT_PER_TX_TYPE: {
     DEFAULT_TRANSFER_ERC20: bigint;
     DEFAULT_APPROVAL: bigint;
 };
+export declare const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";

package/dist/cjs/constants/constants.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GAS_LIMIT_PER_TX_TYPE = void 0;
+exports.MULTICALL3_ADDRESS = exports.GAS_LIMIT_PER_TX_TYPE = void 0;
 exports.GAS_LIMIT_PER_TX_TYPE = {
     DEFAULT_TRANSFER_NATIVE: 21000n,
     DEFAULT_TRANSFER_ERC20: 65000n,
     DEFAULT_APPROVAL: 100000n,
 };
+// & Multicall3 contract address (same on most chains)
+// & https://www.multicall3.com/deployments
+exports.MULTICALL3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11';

package/dist/cjs/index.d.ts

@@ -2,13 +2,14 @@
 import ERC20_TOKEN_CONTRACT_ABI from './ABIs/ERC20_TOKEN_CONTRACT_ABI';
 export { ERC20_TOKEN_CONTRACT_ABI };
 /** constants exports */
-export { GAS_LIMIT_PER_TX_TYPE } from './constants/constants';
+export { GAS_LIMIT_PER_TX_TYPE, MULTICALL3_ADDRESS } from './constants/constants';
 /** basic blockchain exports */
 export { buildMaxNativeTransferTx, buildUnsignedTransferTx, } from './blockchain/buildUnsignedTransferTx';
 export { broadcastTransaction } from './blockchain/broadcastTransaction';
 export { estimateGasLimitFromProvider } from './blockchain/estimateGasLimitFromProvider';
 export { getProvider } from './blockchain/getProvider';
 export { txStatus } from './blockchain/txStatus';
+export { getBalance, getBalances } from './blockchain/getBalances';
 /** services exports */
 export { EvmWalletService, EvmGeneratedWallet, EvmDerivedWallet, } from './services/evm-wallet-core/evmWalletService';
 export { EntropySource } from './services/evm-wallet-core/entropy';
@@ -20,5 +21,8 @@ import NATIVE_TOKENS from './utils/tokens';
 export { NATIVE_TOKENS };
 export { formattedAmountForDisplay, parsedAmount } from './utils/formatAmount';
 export { handleErrorMessages, errorMessagesForBroadcast, errorMessagesForGasLimitEstimation, } from './utils/handleErrorMessages';
+export { normalizeAddress } from './utils/normalizeAddress';
+/** rpc exports */
+export { validateRpcUrl, ensurePublicHost, testJsonRpc } from './rpc/index';
 /** types exports */
-export { BroadcastTransactionOptions, BuildMaxNativeTransferTxOptions, BuildMaxNativeTransferTxResponse, BuildUnsignedTransferTxOptions, EstimateGasLimitFromProviderProps, GasEstimateResult, TxStatusOptions, TxStatusResponse, UnsignedTransferTxResponse, FormatAmountOptions, TransactionRequest, } from './types/common';
+export { BroadcastTransactionOptions, BuildMaxNativeTransferTxOptions, BuildMaxNativeTransferTxResponse, BuildUnsignedTransferTxOptions, EstimateGasLimitFromProviderProps, GasEstimateResult, TxStatusOptions, TxStatusResponse, UnsignedTransferTxResponse, FormatAmountOptions, TransactionRequest, GetBalanceParams, GetBalancesParams, GetBalancesChainRequest, GetBalanceResult, ChainBalances, TokenBalance, ChainGroup, } from './types/common';

package/dist/cjs/index.js

@@ -3,13 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.errorMessagesForGasLimitEstimation = exports.errorMessagesForBroadcast = exports.handleErrorMessages = exports.parsedAmount = exports.formattedAmountForDisplay = exports.NATIVE_TOKENS = exports.transformBigInt = exports.getShortenData = exports.getShortenTransactionHashOrAddress = exports.signTransaction = exports.signMessage = exports.createWallet = exports.EvmWalletService = exports.txStatus = exports.getProvider = exports.estimateGasLimitFromProvider = exports.broadcastTransaction = exports.buildUnsignedTransferTx = exports.buildMaxNativeTransferTx = exports.GAS_LIMIT_PER_TX_TYPE = exports.ERC20_TOKEN_CONTRACT_ABI = void 0;
+exports.testJsonRpc = exports.ensurePublicHost = exports.validateRpcUrl = exports.normalizeAddress = exports.errorMessagesForGasLimitEstimation = exports.errorMessagesForBroadcast = exports.handleErrorMessages = exports.parsedAmount = exports.formattedAmountForDisplay = exports.NATIVE_TOKENS = exports.transformBigInt = exports.getShortenData = exports.getShortenTransactionHashOrAddress = exports.signTransaction = exports.signMessage = exports.createWallet = exports.EvmWalletService = exports.getBalances = exports.getBalance = exports.txStatus = exports.getProvider = exports.estimateGasLimitFromProvider = exports.broadcastTransaction = exports.buildUnsignedTransferTx = exports.buildMaxNativeTransferTx = exports.MULTICALL3_ADDRESS = exports.GAS_LIMIT_PER_TX_TYPE = exports.ERC20_TOKEN_CONTRACT_ABI = void 0;
 /** ABIs exports */
 const ERC20_TOKEN_CONTRACT_ABI_1 = __importDefault(require("./ABIs/ERC20_TOKEN_CONTRACT_ABI"));
 exports.ERC20_TOKEN_CONTRACT_ABI = ERC20_TOKEN_CONTRACT_ABI_1.default;
 /** constants exports */
 var constants_1 = require("./constants/constants");
 Object.defineProperty(exports, "GAS_LIMIT_PER_TX_TYPE", { enumerable: true, get: function () { return constants_1.GAS_LIMIT_PER_TX_TYPE; } });
+Object.defineProperty(exports, "MULTICALL3_ADDRESS", { enumerable: true, get: function () { return constants_1.MULTICALL3_ADDRESS; } });
 /** basic blockchain exports */
 var buildUnsignedTransferTx_1 = require("./blockchain/buildUnsignedTransferTx");
 Object.defineProperty(exports, "buildMaxNativeTransferTx", { enumerable: true, get: function () { return buildUnsignedTransferTx_1.buildMaxNativeTransferTx; } });
@@ -22,6 +23,9 @@ var getProvider_1 = require("./blockchain/getProvider");
 Object.defineProperty(exports, "getProvider", { enumerable: true, get: function () { return getProvider_1.getProvider; } });
 var txStatus_1 = require("./blockchain/txStatus");
 Object.defineProperty(exports, "txStatus", { enumerable: true, get: function () { return txStatus_1.txStatus; } });
+var getBalances_1 = require("./blockchain/getBalances");
+Object.defineProperty(exports, "getBalance", { enumerable: true, get: function () { return getBalances_1.getBalance; } });
+Object.defineProperty(exports, "getBalances", { enumerable: true, get: function () { return getBalances_1.getBalances; } });
 /** services exports */
 var evmWalletService_1 = require("./services/evm-wallet-core/evmWalletService");
 Object.defineProperty(exports, "EvmWalletService", { enumerable: true, get: function () { return evmWalletService_1.EvmWalletService; } });
@@ -44,3 +48,10 @@ var handleErrorMessages_1 = require("./utils/handleErrorMessages");
 Object.defineProperty(exports, "handleErrorMessages", { enumerable: true, get: function () { return handleErrorMessages_1.handleErrorMessages; } });
 Object.defineProperty(exports, "errorMessagesForBroadcast", { enumerable: true, get: function () { return handleErrorMessages_1.errorMessagesForBroadcast; } });
 Object.defineProperty(exports, "errorMessagesForGasLimitEstimation", { enumerable: true, get: function () { return handleErrorMessages_1.errorMessagesForGasLimitEstimation; } });
+var normalizeAddress_1 = require("./utils/normalizeAddress");
+Object.defineProperty(exports, "normalizeAddress", { enumerable: true, get: function () { return normalizeAddress_1.normalizeAddress; } });
+/** rpc exports */
+var index_1 = require("./rpc/index");
+Object.defineProperty(exports, "validateRpcUrl", { enumerable: true, get: function () { return index_1.validateRpcUrl; } });
+Object.defineProperty(exports, "ensurePublicHost", { enumerable: true, get: function () { return index_1.ensurePublicHost; } });
+Object.defineProperty(exports, "testJsonRpc", { enumerable: true, get: function () { return index_1.testJsonRpc; } });

package/dist/cjs/rpc/index.d.ts

@@ -0,0 +1,3 @@
+export declare const validateRpcUrl: (rpcUrl: string, allowLocal?: boolean) => URL;
+export declare const ensurePublicHost: (rpcUrl: string) => Promise<boolean>;
+export declare const testJsonRpc: (rpcUrl: string, method?: string, params?: any[]) => Promise<unknown>;

package/dist/cjs/rpc/index.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testJsonRpc = exports.ensurePublicHost = exports.validateRpcUrl = void 0;
+/** npm imports */
+const promises_1 = __importDefault(require("dns/promises"));
+const net_1 = __importDefault(require("net"));
+const PRIVATE_IP_RANGES = [
+    /^127\./,
+    /^10\./,
+    /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+    /^192\.168\./,
+    /^169\.254\./,
+];
+const validateRpcUrl = (rpcUrl, allowLocal = false) => {
+    let url;
+    try {
+        url = new URL(rpcUrl);
+        if (!allowLocal && ['localhost', '127.0.0.1', '::1'].includes(url.hostname))
+            throw new Error('Localhost URLs are not allowed');
+    }
+    catch {
+        throw new Error('Invalid RPC URL');
+    }
+    if (!['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol))
+        throw new Error('Unsupported protocol. Only http, https, ws, and wss are allowed.');
+    if (['localhost', '127.0.0.1'].includes(url.hostname))
+        throw new Error('Localhost RPC not allowed');
+    return url;
+};
+exports.validateRpcUrl = validateRpcUrl;
+const ensurePublicHost = async (rpcUrl) => {
+    const url = (0, exports.validateRpcUrl)(rpcUrl);
+    try {
+        const addresses = await promises_1.default.lookup(url.hostname, { all: true });
+        const hasPrivateIp = addresses
+            .filter((a) => net_1.default.isIP(a.address))
+            .some((a) => PRIVATE_IP_RANGES.some((r) => r.test(a.address)));
+        if (hasPrivateIp)
+            throw new Error('RPC URL resolves to a private IP address');
+        return true;
+    }
+    catch (error) {
+        console.error('Error validating RPC URL:', error);
+        throw new Error('Failed to validate RPC URL');
+    }
+};
+exports.ensurePublicHost = ensurePublicHost;
+const testJsonRpc = async (rpcUrl, method = 'eth_chainId', params = []) => {
+    await (0, exports.ensurePublicHost)(rpcUrl);
+    const payload = { jsonrpc: '2.0', id: 1, method, params };
+    try {
+        const res = await fetch(rpcUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(5000),
+        });
+        const data = await res.json();
+        return data;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`RPC test failed: ${errorMessage}`);
+    }
+};
+exports.testJsonRpc = testJsonRpc;

package/dist/cjs/types/common.d.ts

@@ -72,3 +72,38 @@ export interface FormatAmountOptions {
     maxDisplayDigits?: number;
 }
 export type { TransactionRequest };
+export interface GetBalanceParams {
+    walletAddress: string;
+    rpcUrl: string;
+    tokenAddress?: string;
+    chainId?: number;
+}
+export interface GetBalancesChainRequest {
+    rpcUrl: string;
+    chainId?: number;
+    tokenAddresses: string[];
+    includeNative?: boolean;
+}
+export interface GetBalancesParams {
+    walletAddress: string;
+    chains: GetBalancesChainRequest[];
+}
+export interface TokenBalance {
+    tokenAddress: string | null;
+    balance: bigint | null;
+    error?: unknown;
+}
+export interface ChainBalances {
+    chainId?: number;
+    balances: TokenBalance[];
+}
+export interface GetBalanceResult {
+    walletAddress: string;
+    chains: ChainBalances[];
+}
+export interface ChainGroup {
+    rpcUrl: string;
+    chainId?: number;
+    nativeBalanceRequests: GetBalanceParams[];
+    tokenBalanceRequests: GetBalanceParams[];
+}

package/dist/cjs/utils/formatAmount.js

@@ -6,9 +6,8 @@ const ethers_1 = require("ethers");
 const formattedAmountForDisplay = (amount, decimals, options = {}) => {
     const { decimalsToShow = 0, useGroupSeparator = true, locale = 'en-US', minimumFractionDigits, minDisplayDecimals = 9, maxDisplayDigits = 16, } = options;
     const formattedAmount = (0, ethers_1.formatUnits)(amount, decimals);
-    if (formattedAmount.startsWith('-')) {
+    if (formattedAmount.startsWith('-'))
         throw new Error('Negative balances are not supported');
-    }
     const [wholePart = '0', fractionPart = ''] = formattedAmount.split('.');
     if (wholePart.length >= maxDisplayDigits) {
         const mantissaWhole = wholePart[0] ?? '0';

package/dist/cjs/utils/normalizeAddress.d.ts

@@ -0,0 +1 @@
+export declare const normalizeAddress: (address: string) => string;

package/dist/cjs/utils/normalizeAddress.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAddress = void 0;
+/** npm imports */
+const ethers_1 = require("ethers");
+const normalizeAddress = (address) => {
+    try {
+        return (0, ethers_1.getAddress)(address);
+    }
+    catch (e) {
+        console.log('Error normalizing address:', e);
+        throw new Error('Error normalizing address: ' + (e instanceof Error ? e.message : String(e)));
+    }
+};
+exports.normalizeAddress = normalizeAddress;

package/dist/constants/constants.d.ts

@@ -3,3 +3,4 @@ export declare const GAS_LIMIT_PER_TX_TYPE: {
     DEFAULT_TRANSFER_ERC20: bigint;
     DEFAULT_APPROVAL: bigint;
 };
+export declare const MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";

package/dist/constants/constants.js

@@ -3,3 +3,6 @@ export const GAS_LIMIT_PER_TX_TYPE = {
     DEFAULT_TRANSFER_ERC20: 65000n,
     DEFAULT_APPROVAL: 100000n,
 };
+// & Multicall3 contract address (same on most chains)
+// & https://www.multicall3.com/deployments
+export const MULTICALL3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11';

package/dist/index.d.ts

@@ -2,13 +2,14 @@
 import ERC20_TOKEN_CONTRACT_ABI from './ABIs/ERC20_TOKEN_CONTRACT_ABI';
 export { ERC20_TOKEN_CONTRACT_ABI };
 /** constants exports */
-export { GAS_LIMIT_PER_TX_TYPE } from './constants/constants';
+export { GAS_LIMIT_PER_TX_TYPE, MULTICALL3_ADDRESS } from './constants/constants';
 /** basic blockchain exports */
 export { buildMaxNativeTransferTx, buildUnsignedTransferTx, } from './blockchain/buildUnsignedTransferTx';
 export { broadcastTransaction } from './blockchain/broadcastTransaction';
 export { estimateGasLimitFromProvider } from './blockchain/estimateGasLimitFromProvider';
 export { getProvider } from './blockchain/getProvider';
 export { txStatus } from './blockchain/txStatus';
+export { getBalance, getBalances } from './blockchain/getBalances';
 /** services exports */
 export { EvmWalletService, EvmGeneratedWallet, EvmDerivedWallet, } from './services/evm-wallet-core/evmWalletService';
 export { EntropySource } from './services/evm-wallet-core/entropy';
@@ -20,5 +21,8 @@ import NATIVE_TOKENS from './utils/tokens';
 export { NATIVE_TOKENS };
 export { formattedAmountForDisplay, parsedAmount } from './utils/formatAmount';
 export { handleErrorMessages, errorMessagesForBroadcast, errorMessagesForGasLimitEstimation, } from './utils/handleErrorMessages';
+export { normalizeAddress } from './utils/normalizeAddress';
+/** rpc exports */
+export { validateRpcUrl, ensurePublicHost, testJsonRpc } from './rpc/index';
 /** types exports */
-export { BroadcastTransactionOptions, BuildMaxNativeTransferTxOptions, BuildMaxNativeTransferTxResponse, BuildUnsignedTransferTxOptions, EstimateGasLimitFromProviderProps, GasEstimateResult, TxStatusOptions, TxStatusResponse, UnsignedTransferTxResponse, FormatAmountOptions, TransactionRequest, } from './types/common';
+export { BroadcastTransactionOptions, BuildMaxNativeTransferTxOptions, BuildMaxNativeTransferTxResponse, BuildUnsignedTransferTxOptions, EstimateGasLimitFromProviderProps, GasEstimateResult, TxStatusOptions, TxStatusResponse, UnsignedTransferTxResponse, FormatAmountOptions, TransactionRequest, GetBalanceParams, GetBalancesParams, GetBalancesChainRequest, GetBalanceResult, ChainBalances, TokenBalance, ChainGroup, } from './types/common';

package/dist/index.js

@@ -2,13 +2,14 @@
 import ERC20_TOKEN_CONTRACT_ABI from './ABIs/ERC20_TOKEN_CONTRACT_ABI';
 export { ERC20_TOKEN_CONTRACT_ABI };
 /** constants exports */
-export { GAS_LIMIT_PER_TX_TYPE } from './constants/constants';
+export { GAS_LIMIT_PER_TX_TYPE, MULTICALL3_ADDRESS } from './constants/constants';
 /** basic blockchain exports */
 export { buildMaxNativeTransferTx, buildUnsignedTransferTx, } from './blockchain/buildUnsignedTransferTx';
 export { broadcastTransaction } from './blockchain/broadcastTransaction';
 export { estimateGasLimitFromProvider } from './blockchain/estimateGasLimitFromProvider';
 export { getProvider } from './blockchain/getProvider';
 export { txStatus } from './blockchain/txStatus';
+export { getBalance, getBalances } from './blockchain/getBalances';
 /** services exports */
 export { EvmWalletService, } from './services/evm-wallet-core/evmWalletService';
 export { createWallet, signMessage, signTransaction } from './services/evm-wallet-core/signer';
@@ -19,3 +20,6 @@ import NATIVE_TOKENS from './utils/tokens';
 export { NATIVE_TOKENS };
 export { formattedAmountForDisplay, parsedAmount } from './utils/formatAmount';
 export { handleErrorMessages, errorMessagesForBroadcast, errorMessagesForGasLimitEstimation, } from './utils/handleErrorMessages';
+export { normalizeAddress } from './utils/normalizeAddress';
+/** rpc exports */
+export { validateRpcUrl, ensurePublicHost, testJsonRpc } from './rpc/index';

package/dist/rpc/index.d.ts

@@ -0,0 +1,3 @@
+export declare const validateRpcUrl: (rpcUrl: string, allowLocal?: boolean) => URL;
+export declare const ensurePublicHost: (rpcUrl: string) => Promise<boolean>;
+export declare const testJsonRpc: (rpcUrl: string, method?: string, params?: any[]) => Promise<unknown>;

package/dist/rpc/index.js

@@ -0,0 +1,60 @@
+/** npm imports */
+import dns from 'dns/promises';
+import net from 'net';
+const PRIVATE_IP_RANGES = [
+    /^127\./,
+    /^10\./,
+    /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+    /^192\.168\./,
+    /^169\.254\./,
+];
+export const validateRpcUrl = (rpcUrl, allowLocal = false) => {
+    let url;
+    try {
+        url = new URL(rpcUrl);
+        if (!allowLocal && ['localhost', '127.0.0.1', '::1'].includes(url.hostname))
+            throw new Error('Localhost URLs are not allowed');
+    }
+    catch {
+        throw new Error('Invalid RPC URL');
+    }
+    if (!['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol))
+        throw new Error('Unsupported protocol. Only http, https, ws, and wss are allowed.');
+    if (['localhost', '127.0.0.1'].includes(url.hostname))
+        throw new Error('Localhost RPC not allowed');
+    return url;
+};
+export const ensurePublicHost = async (rpcUrl) => {
+    const url = validateRpcUrl(rpcUrl);
+    try {
+        const addresses = await dns.lookup(url.hostname, { all: true });
+        const hasPrivateIp = addresses
+            .filter((a) => net.isIP(a.address))
+            .some((a) => PRIVATE_IP_RANGES.some((r) => r.test(a.address)));
+        if (hasPrivateIp)
+            throw new Error('RPC URL resolves to a private IP address');
+        return true;
+    }
+    catch (error) {
+        console.error('Error validating RPC URL:', error);
+        throw new Error('Failed to validate RPC URL');
+    }
+};
+export const testJsonRpc = async (rpcUrl, method = 'eth_chainId', params = []) => {
+    await ensurePublicHost(rpcUrl);
+    const payload = { jsonrpc: '2.0', id: 1, method, params };
+    try {
+        const res = await fetch(rpcUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(5000),
+        });
+        const data = await res.json();
+        return data;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`RPC test failed: ${errorMessage}`);
+    }
+};

package/dist/types/common.d.ts

@@ -72,3 +72,38 @@ export interface FormatAmountOptions {
     maxDisplayDigits?: number;
 }
 export type { TransactionRequest };
+export interface GetBalanceParams {
+    walletAddress: string;
+    rpcUrl: string;
+    tokenAddress?: string;
+    chainId?: number;
+}
+export interface GetBalancesChainRequest {
+    rpcUrl: string;
+    chainId?: number;
+    tokenAddresses: string[];
+    includeNative?: boolean;
+}
+export interface GetBalancesParams {
+    walletAddress: string;
+    chains: GetBalancesChainRequest[];
+}
+export interface TokenBalance {
+    tokenAddress: string | null;
+    balance: bigint | null;
+    error?: unknown;
+}
+export interface ChainBalances {
+    chainId?: number;
+    balances: TokenBalance[];
+}
+export interface GetBalanceResult {
+    walletAddress: string;
+    chains: ChainBalances[];
+}
+export interface ChainGroup {
+    rpcUrl: string;
+    chainId?: number;
+    nativeBalanceRequests: GetBalanceParams[];
+    tokenBalanceRequests: GetBalanceParams[];
+}

package/dist/utils/formatAmount.js

@@ -3,9 +3,8 @@ import { formatUnits, parseUnits } from 'ethers';
 export const formattedAmountForDisplay = (amount, decimals, options = {}) => {
     const { decimalsToShow = 0, useGroupSeparator = true, locale = 'en-US', minimumFractionDigits, minDisplayDecimals = 9, maxDisplayDigits = 16, } = options;
     const formattedAmount = formatUnits(amount, decimals);
-    if (formattedAmount.startsWith('-')) {
+    if (formattedAmount.startsWith('-'))
         throw new Error('Negative balances are not supported');
-    }
     const [wholePart = '0', fractionPart = ''] = formattedAmount.split('.');
     if (wholePart.length >= maxDisplayDigits) {
         const mantissaWhole = wholePart[0] ?? '0';

package/dist/utils/normalizeAddress.d.ts

@@ -0,0 +1 @@
+export declare const normalizeAddress: (address: string) => string;

package/dist/utils/normalizeAddress.js

@@ -0,0 +1,11 @@
+/** npm imports */
+import { getAddress } from 'ethers';
+export const normalizeAddress = (address) => {
+    try {
+        return getAddress(address);
+    }
+    catch (e) {
+        console.log('Error normalizing address:', e);
+        throw new Error('Error normalizing address: ' + (e instanceof Error ? e.message : String(e)));
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaflowlabs/onchain-sdk",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "onchain methods for web3",
   "repository": "https://github.com/crisramb665/onchain-sdk.git",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "prepublishOnly": "yarn run build"
   },
   "devDependencies": {
+    "@types/node": "^25.2.2",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",