Utility Functions

Overview

This section covers the most commonly used helpers in the Push Chain Core SDK to simplify common workflows.

Helper Utilities

Parse Units

PushChain.utils.helpers.parseUnits(value, {options}): bigint

Converts a human-readable token amount into its smallest unit representation (bigint). It multiplies the given value by 10^decimals, ensuring amounts are safe for on-chain use.

Commonly used when preparing transaction parameters (e.g., converting 1.5 into 1500000000000000000, similar to how you convert ETH to wei, PC to uPC, or any other tokens to its smallest denominator).

const result = PushChain.utils.helpers.parseUnits('1.5', { decimals: 18 });
// variation: const result = PushChain.utils.helpers.parseUnits('1.5', 18);

// Returns: 1500000000000000000n (1.5 PC in uPC)

TheseArgumentsare mandatory

Arguments	Type	Description
`value`	`string`	The string representation of the number to parse. Can include decimals (e.g., `"1.5"`, `"420"`, `"0.1"`).
`options.decimals`	`number`	The number of decimal places to scale by. Must be a non-negative integer. For example, use `18` for PC or ETH, `6` for USDC, `8` for BTC.

Returns `value` <bigint>

// bigint - the scaled integer value
1500000000000000000n

Live Playground: Parse Units for Common Token Scenarios

VIRTUAL NODE IDE

Format Units

PushChain.utils.helpers.formatUnits(value, {options}): string

Converts a raw token amount in smallest units (bigint) into a human-readable decimal string. It divides the given value by 10^decimals, making it easy to display amounts for users.

Commonly used in UI or logs (e.g., turning 1500000000000000000 into 1.5 or any token from smallest unit to its human-readable value).

const result = PushChain.utils.helpers.formatUnits('1500000000000000000', { decimals: 18 });
// variation: const result = PushChain.utils.helpers.formatUnits('1500000000000000000', 18);

// Returns: 1.5 (1.5 PC in uPC)

TheseArgumentsare mandatory

Arguments	Type	Description
`value`	`bigint \| string`	Raw amount in smallest units (e.g., `'1500000000000000000'` for 1.5 assuming `18` decimals).
`options.decimals`	`number`	The number of decimal places to scale by. Must be a non-negative integer. For example, use `18` for PC or ETH, `6` for USDC, `8` for BTC.
`options.precision`	`number`	The number of precision to scale by, will round up the value. Must be a non-negative integer. For example, use `4` for returning 4 digits after the decimal.

Returns `value` <string>

// string - human readable value
1.5

Live Playground: Format Units for Common Token Scenarios

VIRTUAL NODE IDE

Encode Transaction Data

PushChain.utils.helpers.encodeTxData({abi, functionName, args}): string

const encodedData = PushChain.utils.helpers.encodeTxData({
  abi,
  functionName: 'functionName',
  args: []
});

TheseArgumentsare mandatory

Arguments	Type	Default	Description
`abi`	`any[]`	-	The ABI array of the smart contract containing function definitions.
`functionName`	`string`	-	The name of the function to encode transaction data for.
`args`	`any[]`	`[]`	The arguments to pass to the function. Defaults to empty array for functions with no parameters.

Returns `encodedData` <string>

// encodedData string - the encoded function call data
'0xd09de08a';

Live Playground: Encode Transaction Data for Smart Contract Function

VIRTUAL NODE IDE

Chain Utilities

Get Chain Namespace from Chain Name

PushChain.utils.chains.getChainNamespace(chainName): string

Every external chain is represented as a particular string on Push Chain. You can see the list of supported chains in the Chain Configuration section.

const chainName = PushChain.utils.chains.getChainNamespace('PUSH_TESTNET_DONUT');

TheseArgumentsare mandatory

Arguments	Type	Description
`name`	`string`	The chain name to convert to chain namespace. Eg: `PUSH_TESTNET_DONUT` converts to `eip155:42101`, `ETHEREUM_SEPOLIA` converts to `eip155:11155111`.

Returns `chainNamespace` <string>

// chainNamespace string
'eip155:42101';

// NOTE: returns undefined if chainName is unsupported

Live Playground: Get Chain Namespace from Chain Name

VIRTUAL NODE IDE

Get Chain Name from Chain Namespace

PushChain.utils.chains.getChainName(chainNamespace): string

Every external chain is represented as a particular string on Push Chain. You can see the list of supported chains in the chain configuration section.

const chainName = PushChain.utils.chains.getChainName('eip155:42101');

TheseArgumentsare mandatory

Arguments	Type	Description
`namespace`	`string`	The chain namespace to convert to chain name. Eg: `eip155:42101` converts to `PUSH_TESTNET_DONUT`, `eip155:11155111` converts to `ETHEREUM_SEPOLIA`.

Returns `chainName` <string>

// chainName string
'PUSH_TESTNET_DONUT';

// NOTE: returns undefined if chainNamespace is unsupported

Live Playground: Get Chain Name from Chain Namespace

VIRTUAL NODE IDE

Get Supported Chains

PushChain.utils.chains.getSupportedChains(pushNetwork): { chains: [] }

Returns the list of chains supported for a given Push Network.

const chains = PushChain.utils.chains.getSupportedChains(PushChain.CONSTANTS.PUSH_NETWORK.TESTNET);

TheseArgumentsare mandatory

Arguments	Type	Description
`pushNetwork`	`PushChain.CONSTANTS.PUSH_NETWORK`	Push Chain network to retrieve list of supported chains from. For example: `PushChain.CONSTANTS.PUSH_NETWORK.TESTNET` PushChain.CONSTANTS.PUSH_NETWORK `PushChain.CONSTANTS.PUSH_NETWORK.TESTNET` `PushChain.CONSTANTS.PUSH_NETWORK.LOCALNET`

Returns `{ chains }` <object>

// { chains } object
{
  chains: [
    PushChain.CONSTANTS.CHAIN.PUSH_TESTNET,
    PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA,
    PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET,
    // ...
  ]
}

// NOTE: returns empty chains array if pushNetwork is unsupported

Live Playground: Get Supported Chains for a given Push Network

VIRTUAL NODE IDE

Account Utilities

Convert to Universal Account

PushChain.utils.account.toUniversal(address, {options}): <UniversalAccount>

const account = PushChain.utils.account.toUniversal(address, {
  chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA,
});

TheseArgumentsare mandatory

Arguments	Type	Description
`address`	`string`	An address string (e.g., `0xabc...`).
`options.chain`	`CHAIN`	The target chain for the signer. For example: `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT` PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_MAINNET` `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET` `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT` `PushChain.CONSTANTS.CHAIN.PUSH_LOCALNET` `PushChain.CONSTANTS.CHAIN.ETHEREUM_MAINNET` `PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA` `PushChain.CONSTANTS.CHAIN.SOLANA_MAINNET` `PushChain.CONSTANTS.CHAIN.SOLANA_TESTNET` `PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`

Returns `UniversalAccount` <object>

// UniversalAccount object
{
  chain: 'eip155:11155111',
  address: '0xD8d6aF611a17C236b13235B5318508FA61dE3Dba'
}

Live Playground: Convert Ethereum Sepolia Address to UniversalAccount

VIRTUAL NODE IDE

Convert to Chain-Agnostic Address

PushChain.utils.account.toChainAgnostic(address, {options}): string

const chainAgnosticAddress = PushChain.utils.account.toChainAgnostic(address, {
  chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA,
});

TheseArgumentsare mandatory

Arguments	Type	Description
`address`	`string`	An address string (e.g., `0xabc...`).
`options.chain`	`CHAIN`	The target chain for the signer. For example: `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT` PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_MAINNET` `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET` `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT` `PushChain.CONSTANTS.CHAIN.PUSH_LOCALNET` `PushChain.CONSTANTS.CHAIN.ETHEREUM_MAINNET` `PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA` `PushChain.CONSTANTS.CHAIN.SOLANA_MAINNET` `PushChain.CONSTANTS.CHAIN.SOLANA_TESTNET` `PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`

Returns `ChainAgnosticAddress` <string>

// Chain Agnostic Address
'eip155:11155111:0xD8d6aF611a17C236b13235B5318508FA61dE3Dba';

Live Playground: Convert Ethereum Sepolia address to chain agnostic address

VIRTUAL NODE IDE

Convert from Chain-Agnostic to Universal Account

PushChain.utils.account.fromChainAgnostic(chainAgnosticAddress): <UniversalAccount>

const account = PushChain.utils.account.fromChainAgnostic(chainAgnosticAddress);

TheseArgumentsare mandatory

Arguments	Type	Description
`chainAgnosticAddress`	`string`	A full chain agnostic address string (e.g., `eip155:11155111:0x35B84d6848D16415177c64D64504663b998A6ab4`).

Returns `UniversalAccount` <object>

// UniversalAccount object: { chain: string, address: string }
{
  chain: 'eip155:11155111',
  address: '0xD8d6aF611a17C236b13235B5318508FA61dE3Dba'
}

Live Playground: Convert Ethereum Sepolia chain agnostic address to UniversalAccount

VIRTUAL NODE IDE

Convert Origin to Executor Account

PushChain.utils.account.convertOriginToExecutor(account, {options}): Promise<ExecutorAccountInfo>

Gives the deterministic executor account address for a given origin account (UOA). Also helps in checking if a given origin account (UOA) has an executor account (UEA) deployed on Push Chain.

const info =
  await PushChain.utils.account.convertOriginToExecutor(universalAccount);

TheseArgumentsare mandatory

Arguments	Type	Default	Description
`account`	`UniversalAccount`	-	A UniversalAccount object containing chain and address information.
`options.onlyCompute`	`boolean`	`false`	Whether to check if the computed executor account is deployed. Set to `true` to include deployment status.

Returns `ExecutorAccountInfo` <object>

// ExecutorAccountInfo object
{
  address: '0x98cA97d2FB78B3C0597E2F78cd11868cACF423C5',
  deployed: true
}

Live Playground: Convert Origin Account to Universal Executor Account

VIRTUAL NODE IDE

Convert Executor Address to Origin Account

PushChain.utils.account.convertExecutorToOriginAccount(ueaAddress): Promise<OriginAccountInfo>

Gives the origin account (UOA) for a given executor account (UEA).

const { account, exists } = await PushChain.utils.account.convertExecutorToOriginAccount(ueaAddress);

TheseArgumentsare mandatory

Arguments	Type	Default	Description
`ueaAddress`	`string`	-	Address of the executor account (UEA).

Returns `OriginAccountInfo` <object>

// OriginAccountInfo object
{
  account: {
    chain: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
    address: 'FNDJWigdNWsmxXYGrFV2gCvioLYwXnsVxZ4stL33wFHf'
  },
  exists: true
}

Live Playground: Convert Executor Account to Origin Account

VIRTUAL NODE IDE

Signer Utilities

Create Universal Signer from Keypair

PushChain.utils.signer.toUniversalFromKeypair(keypair, {options}): Promise<UniversalSigner>

const universalSigner = await PushChain.utils.signer.toUniversalFromKeypair(
  keypair,
  {
    chain: PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET,
    library: PushChain.CONSTANTS.LIBRARY.SOLANA_WEB3JS,
  }
);

TheseArgumentsare mandatory

Arguments	Type	Description
`keypair`	`Keypair`	A keypair object from one of the supported libraries (ethers v5/v6, viem, or a custom UniversalSignerSkeleton)
`options.chain`	`CHAIN`	The target chain for the signer. For example: `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT` PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.PUSH_MAINNET` `PushChain.CONSTANTS.PUSH_TESTNET` `PushChain.CONSTANTS.PUSH_TESTNET_DONUT` `PushChain.CONSTANTS.PUSH_LOCALNET` `PushChain.CONSTANTS.CHAIN.ETHEREUM_MAINNET` `PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA` `PushChain.CONSTANTS.CHAIN.SOLANA_MAINNET` `PushChain.CONSTANTS.CHAIN.SOLANA_TESTNET` `PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`
`options.library`	`LIBRARY`	The library to use for the signer. For example: `PushChain.CONSTANTS.LIBRARY.ETHEREUM_ETHERSV6` PushChain.CONSTANTS.LIBRARY `PushChain.CONSTANTS.LIBRARY.ETHEREUM_ETHERSV6` `PushChain.CONSTANTS.LIBRARY.ETHEREUM_VIEM` `PushChain.CONSTANTS.LIBRARY.SOLANA_WEB3JS`

Returns `UniversalSigner` <object>

// UniversalSigner object
{
  account: {
    address: '0xD173b7f04D539A5794e14030c4E172B2E3df92f3',
    chain: 'eip155:11155111'
  },
  signMessage: [Function: signMessage],
  signAndSendTransaction: [Function: signAndSendTransaction],
  signTypedData: [Function: signTypedData]
}

Live Playground: Create Universal Signer from Keypair

Ethers (v6)
Viem
Solana (Web3 JS)

VIRTUAL NODE IDE

Token Utilities

Get Moveable Tokens

PushChain.utils.tokens.getMoveableTokens(chainOrClient?): { tokens: [] }

Commonly used to get list of supported assets that can be moved across chains. See send universal transaction for more info.

// All supported moveable tokens across chains
const { tokens: allMoveable } = PushChain.utils.tokens.getMoveableTokens();

// Filtered for a specific chain
const { tokens: sepoliaMoveable } = PushChain.utils.tokens.getMoveableTokens(
  PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA
);

TheseArgumentsare mandatory

Arguments	Type	Description
`chainOrClient`	`CHAIN \| PushChain`	Optional. A chain enum or an initialized client to filter tokens for that chain.

Returns `{ tokens }` <object>

// tokens object { tokens: [] }
{
  tokens: [
    { chain: 'eip155:11155111', symbol: 'ETH', decimals: 18, address: '0x...' },
    { chain: 'eip155:11155111', symbol: 'USDC', decimals: 6, address: '0x...' },
    // ...
  ]
}

Live Playground: List moveable tokens for a specific chain

VIRTUAL NODE IDE

Get Payable Tokens

PushChain.utils.tokens.getPayableTokens(chainOrClient?): { tokens: [] }

Commonly used to get list of supported assets to pay with (either for gas or token movement) across chains. See send universal transaction for more info.

// All supported payable tokens across chains
const { tokens: allPayable } = PushChain.utils.tokens.getPayableTokens();

// Filtered for a specific chain
const { tokens: solanaDevnetPayable } = PushChain.utils.tokens.getPayableTokens(
  PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET
);

TheseArgumentsare mandatory

Arguments	Type	Description
`chainOrClient`	`CHAIN \| PushChain`	Optional. A chain enum or an initialized client to filter tokens for that chain.

Returns `{ tokens }` <object>

// tokens object { tokens: [] }
{
  tokens: [
    { chain: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', symbol: 'SOL', decimals: 9, address: 'So11111111111111111111111111111111111111112' },
    { chain: 'eip155:11155111', symbol: 'USDC', decimals: 6, address: '0x...' },
    // ...
  ]
}

Live Playground: List payable tokens for a specific chain

VIRTUAL NODE IDE

Conversion Utilities

Calculate Minimum Amount from Slippage

PushChain.utils.conversion.slippageToMinAmount(amount, { slippageBps }): string

const minOut = PushChain.utils.conversion.slippageToMinAmount('100000000', {
  slippageBps: 100, // 1%
});
// Returns: '99000000'

TheseArgumentsare mandatory

Arguments	Type	Description
`amount`	`string`	Input amount in smallest units (e.g., '100000000' for 100 USDC as it has 6 decimals).
`options.slippageBps`	`number` (integer)	Slippage in basis points. `100 = 1%`, `50 = 0.5%`.

Returns `minOut` <string>

// minOut `string` (in smallest units)
'99000000'

Live Playground: Calculate minimum amount out from slippage

VIRTUAL NODE IDE

Get Conversion Quote

pushChainClient.funds.getConversionQuote(amount, {options}): Promise<ConversionQuote>

Note: This function is available only after initializing the Push Chain client.

The function is used to get conversion quote especially when you want to pay with (from) one token, move as (to) another token. Used in send universal transaction for token movement across chains or to pay gas in other tokens instead of native token of the source chain.

Convention: from = the token you pay with (Payable), to = the token you move as (Moveable).

const quote = pushChainClient.funds.getConversionQuote('100000000', {
  from: pushChainClient.payable.token.WETH, // PayableToken - Assuming client initialized with ETHEREUM_ 
  to: pushChainClient.moveable.token.USDT // MoveableToken - Assuming client initialized with ETHEREUM_ 
});

// Returns: { "amountIn": "5000000000000000", "amountOut": "11813463066488417", "rate": 2362692613297.683, "route": [ "WETH", "USDT" ], "timestamp": 1758582899267 }

Arguments	Type	Description
`amount`	`string`	The string representation of the amount to parse. Can include decimals (e.g., "1.5", "420", "0.1").
`options.from`	`<PayableToken>` (dynamic)	List of supported tokens provided dynamically through get `getPayableTokens`.
`options.to`	`<MoveableToken>` (dynamic)	List of supported tokens provided dynamically through get `getMoveableTokens`.

Supported chains

funds.getConversionQuote currently works on Ethereum Mainnet and Sepolia. Other origins will throw an error.

Returns `ConversionQuote` <object>

Field	Type	Description
`amountIn`	`string`	Input amount in smallest units
`amountOut`	`string`	Output amount in smallest units
`rate`	`number`	Normalized rate: tokenOut per tokenIn
`route`	`string[]`	Optional swap path (e.g., `["WETH","USDT"]`)
`timestamp`	`number`	Unix time (ms)

Live Playground: Quote WETH → USDT on Sepolia

VIRTUAL NODE IDE

Explorer Utilities

Get Transaction URL

pushChainClient.explorer.getTransactionUrl(txHash): string

Note: This function is available only after initializing the Push Chain client.

// ... Initialize Push Chain Client
const url = pushChainClient.explorer.getTransactionUrl(txHash);

TheseArgumentsare mandatory

Arguments	Type	Description
`txHash`	`string`	The transaction hash to convert to explorer URL.

Returns `url` <string>

// url string
'https://donut.push.network/tx/0x...';

Live Playground: Get Explorer URL for a transaction hash

VIRTUAL NODE IDE

List all Explorer URLs

pushChainClient.explorer.listUrls(): { urls: string[] }

Note: This function is available only after initializing the Push Chain client.

// ... Initialize Push Chain Client
const urls = pushChainClient.explorer.listUrls();

Returns `urls` <{ urls: string[] }>

// urls object { urls:[] }
{
  urls: ['https://donut.push.network', 'https://scan.push.org'];
}

Live Playground: List all Explorer URLs

VIRTUAL NODE IDE

Next Steps

Dive into reading blockchain state
Harness our on-chain contract helpers to supercharge your app
Explore and abstract away wallet and any chain-related logic using UI Kit

Start building

Quick Start

Learn with tutorials

Explore Push Chain

Join Discord

Explore Examples

Utility Functions

Overview

Helper Utilities

Parse Units

Format Units

Encode Transaction Data

Chain Utilities

Get Chain Namespace from Chain Name

Get Chain Name from Chain Namespace

Get Supported Chains

Account Utilities

Convert to Universal Account

Convert to Chain-Agnostic Address

Convert from Chain-Agnostic to Universal Account

Convert Origin to Executor Account

Convert Executor Address to Origin Account

Signer Utilities

Create Universal Signer from Keypair

Token Utilities

Get Moveable Tokens

Get Payable Tokens

Conversion Utilities

Calculate Minimum Amount from Slippage

Get Conversion Quote

Explorer Utilities

Get Transaction URL

List all Explorer URLs

Next Steps

Start building

Quick Start

Learn with tutorials

Explore Push Chain

Join Discord

Explore Examples

Overview​

Helper Utilities​

Parse Units​

Format Units​

Encode Transaction Data​

Chain Utilities​

Get Chain Namespace from Chain Name​

Get Chain Name from Chain Namespace​

Get Supported Chains​

Account Utilities​

Convert to Universal Account​

Convert to Chain-Agnostic Address​

Convert from Chain-Agnostic to Universal Account​

Convert Origin to Executor Account​

Convert Executor Address to Origin Account​

Signer Utilities​

Create Universal Signer from Keypair​

Token Utilities​

Get Moveable Tokens​

Get Payable Tokens​

Conversion Utilities​

Calculate Minimum Amount from Slippage​

Get Conversion Quote​

Explorer Utilities​

Get Transaction URL​

List all Explorer URLs​

Next Steps​

Overview

Helper Utilities

Parse Units

Format Units

Encode Transaction Data

Chain Utilities

Get Chain Namespace from Chain Name

Get Chain Name from Chain Namespace

Get Supported Chains

Account Utilities

Convert to Universal Account

Convert to Chain-Agnostic Address

Convert from Chain-Agnostic to Universal Account

Convert Origin to Executor Account

Convert Executor Address to Origin Account

Signer Utilities

Create Universal Signer from Keypair

Token Utilities

Get Moveable Tokens

Get Payable Tokens

Conversion Utilities

Calculate Minimum Amount from Slippage

Get Conversion Quote

Explorer Utilities

Get Transaction URL

List all Explorer URLs

Next Steps