@pushchain/core
Version:
Push Chain is a true universal L1 that is 100% EVM compatible. It allows developers to deploy once and make their apps instantly compatible with users from all other L1s (Ethereum, Solana, etc) with zero on-chain code change.
232 lines (231 loc) • 9.76 kB
TypeScript
import { convertOriginToExecutor, fromChainAgnostic, convertExecutorToOriginAccount, toChainAgnostic, toUniversal } from './universal/account';
import { construct, toUniversal as toUniversalSigner, toUniversalFromKeypair } from './universal/signer';
import { CHAIN, PUSH_NETWORK } from './constants/enums';
import { type MoveableToken } from './constants/tokens';
import type { PushChain } from './push-chain/push-chain';
/**
* @dev - THESE UTILS ARE EXPORTED TO SDK CONSUMER
* @dev - Make sure each exported fn has good comments to help out sdk consumer
*/
/**
* Utility class for handling CAIP-10 chain-agnostic address formatting
* and universal account conversions.
*/
export declare class Utils {
static account: {
toChainAgnostic: typeof toChainAgnostic;
toUniversal: typeof toUniversal;
/**
* Converts a CAIP-10 formatted string into a UniversalAccount.
*
* @param {string} caip - A CAIP-10 address string (e.g., 'eip155:1:0xabc...').
* @returns {UniversalAccount} The resolved account.
* @throws {Error} If the CAIP string is invalid or unsupported.
*
* @example
* Utils.account.fromChainAgnostic('eip155:11155111:0xabc...')
* // → { chain: CHAIN.ETHEREUM_SEPOLIA, address: '0xabc...' }
*/
fromChainAgnostic: typeof fromChainAgnostic;
convertOriginToExecutor: typeof convertOriginToExecutor;
convertExecutorToOriginAccount: typeof convertExecutorToOriginAccount;
};
static signer: {
/**
* Converts various signer types (viem, ethers v6, Solana) into a UniversalSigner.
*/
toUniversalFromKeypair: typeof toUniversalFromKeypair;
/**
* Constructs a UniversalSignerSkeleton from raw signing functions.
*/
construct: typeof construct;
/**
* Converts a UniversalSignerSkeleton to a UniversalSigner.
*/
toUniversal: typeof toUniversalSigner;
};
static chains: {
/**
* Returns the list of supported chains for a given Push network.
* Future-proofed to return an object with a `chains` array.
*
* @param {PUSH_NETWORK} network - The Push network environment.
* @returns {{ chains: CHAIN[] }} Object containing supported chains.
*
* @example
* Utils.chains.getSupportedChains(PushChain.CONSTANTS.PUSH_NETWORK.TESTNET)
* // => { chains: [CHAIN.ETHEREUM_SEPOLIA, CHAIN.SOLANA_DEVNET] }
*
* @example
* Utils.chains.getSupportedChains(PushChain.CONSTANTS.PUSH_NETWORK.MAINNET)
* // => { chains: [] }
*/
getSupportedChains: (network: PUSH_NETWORK) => {
chains: CHAIN[];
};
getChainName: (chainNamespace: string) => string | undefined;
/**
* Returns the chain namespace (e.g., 'eip155:11155111') for a given chain name.
* Reverse of getChainName. If input is already a namespace, it is returned.
*
* @param {string} chainName - The CHAIN key name (e.g., 'ETHEREUM_SEPOLIA' or 'PUSH_TESTNET_DONUT')
* or an existing namespace (e.g., 'eip155:11155111').
* @returns {string | undefined} The chain namespace, or undefined if unsupported.
*/
getChainNamespace: (chainName: string) => string | undefined;
};
static helpers: {
/**
* @deprecated Use PushChain.utils.chains.getChainNamespace(chainName) instead.
* Alias maintained for backwards compatibility. Logs a deprecation warning
* and delegates to Utils.chains.getChainNamespace.
*/
getChainName: (chainName: string) => string | undefined;
encodeTxData({ abi, functionName, args, }: {
abi: any[];
functionName: string;
args?: any[];
}): `0x${string}`;
/**
* Multiplies a string representation of a number by a given exponent of base 10 (10^exponent).
*
* This is commonly used for converting human-readable token amounts to their on-chain representation.
* For example, converting "1.5" ETH to wei (18 decimals) would be parseUnits("1.5", 18).
*
* @param {string} value - The string representation of the number to multiply.
* @param {number | {decimals: number}} exponent - The exponent (number of decimal places) or an object with decimals property.
* @returns {bigint} The result as a bigint.
*
* @example
* Utils.helpers.parseUnits('420', 9)
* // → 420000000000n
*
* @example
* Utils.helpers.parseUnits('1.5', 18)
* // → 1500000000000000000n
*
* @example
* Utils.helpers.parseUnits('1.5', {decimals: 18})
* // → 1500000000000000000n
*/
parseUnits(value: string, exponent: number | {
decimals: number;
}): bigint;
/**
* Formats a value from smallest units to human-readable string.
*
* Supports both EVM-style (like ethers/viem) and Push-style (options object) usage patterns.
* Always returns a string for UI safety.
*
* @param {bigint | string} value - The value in smallest units (e.g., "1500000" or 1500000000000000000n).
* @param {number | {decimals: number; precision?: number}} decimalsOrOptions - Token decimals or options object.
* @returns {string} Human-readable string (e.g., "1.5").
*
* @example
* // EVM-style usage
* Utils.helpers.formatUnits(1500000000000000000n, 18)
* // → "1.5"
*
* @example
* // Push-style usage
* Utils.helpers.formatUnits("1500000", { decimals: 6 })
* // → "1.5"
*
* @example
* // With precision (truncate after 2 decimals)
* Utils.helpers.formatUnits("1234567", { decimals: 6, precision: 2 })
* // → "1.23"
*/
formatUnits(value: bigint | string, decimalsOrOptions: number | {
decimals: number;
precision?: number;
}): string;
};
static conversion: {
/**
* Calculates the minimum amount out after applying slippage.
*
* Given an input amount and slippage in basis points, returns the minimum amount
* that should be received after accounting for slippage.
*
* @param {string} amount - The input amount in smallest units (e.g., "100000000" for 100 USDC with 6 decimals)
* @param {object} options - Configuration options
* @param {number} options.slippageBps - Slippage in basis points (100 = 1%, 50 = 0.5%)
* @returns {string} The minimum amount out in smallest units
*
* @example
* // Calculate minimum amount for 100 USDC with 1% slippage
* const amount = PushChain.utils.helpers.parseUnits("100", 6); // "100000000"
* const minOut = PushChain.utils.conversion.slippageToMinAmount(amount, {
* slippageBps: 100, // 1%
* });
* // => "99000000" (99 USDC in smallest units)
*
* @example
* // Simple case with whole numbers
* const minOut = PushChain.utils.conversion.slippageToMinAmount("100", {
* slippageBps: 100, // 1%
* });
* // => "99"
*/
slippageToMinAmount(amount: string, options: {
slippageBps: number;
}): string;
};
static tokens: {
/**
* Returns supported moveable tokens as a flat list with chain info.
* - If a specific chain or a PushChain client is passed, returns only that chain's tokens
* - Otherwise returns tokens across all chains
*/
getMoveableTokens(chainOrClient?: CHAIN | PushChain): {
tokens: Array<{
chain: CHAIN;
symbol: string;
decimals: number;
address: string;
mechanism: "approve" | "permit2" | "native";
}>;
};
/**
* Returns supported payable tokens as a flat list with chain info.
* - If a specific chain or a PushChain client is passed, returns only that chain's tokens
* - Otherwise returns tokens across all chains
*/
getPayableTokens(chainOrClient?: CHAIN | PushChain): {
tokens: Array<{
chain: CHAIN;
symbol: string;
decimals: number;
address: string;
mechanism: "approve" | "permit2" | "native";
}>;
};
/**
* Convert any supported origin-chain token into its mapped PRC20 token address on Push Chain.
*
* @param token - Either a MoveableToken from `pushChainClient.moveable.token.*`
* or an object with the origin chain and token address.
* @returns {`0x${string}`} The synthetic asset address on Push Chain.
*
* @example
* ```jsx
* PushChain.utils.tokens.getPRC20Address(
* token: MoveableToken | {
* chain: CONSTANTS.CHAIN.ETHEREUM_SEPOLIA;
* address: `0x${string}`;
* }
* );
* // → `0x...`
* ```
*/
getPRC20Address(token: MoveableToken | {
chain: string;
address: string;
}): `0x${string}`;
};
/**
* Internal: resolves a CHAIN enum from either a CHAIN value or a PushChain client instance.
*/
private static resolveChainFromInput;
}