@octaflowlabs/onchain-sdk 1.1.4 → 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/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/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';
@@ -24,4 +25,4 @@ 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.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.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; } });

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/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';
@@ -24,4 +25,4 @@ 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';

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaflowlabs/onchain-sdk",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "onchain methods for web3",
   "repository": "https://github.com/crisramb665/onchain-sdk.git",
   "license": "MIT",