Utility Functions

Overview

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

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.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

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.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

Returns `ChainAgnosticAddress` <string>

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

Live Playground: Convert Ethereum Mainnet 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

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)

VIRTUAL NODE IDE

Viem

VIRTUAL NODE IDE

Solana (Web3 JS)

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.

// ... Intialize 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(): string[]

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

// ... Intialize Push Chain Client
const explorerUrls = pushChainClient.explorer.listUrls();

Returns `explorerUrls` <string[]>

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

Live Playground: List all Explorer URLs

VIRTUAL NODE IDE

Helper Utilities

Get Chain Name from Chain Namespace

PushChain.utils.helpers.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.helpers.getChainName(namespace);

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 chainId is unsupported

Live Playground: Get Chain Name from Chain ID

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

Parse Units

PushChain.utils.helpers.parseUnits(value, exponent): bigint

Converts a human-readable string representation of a number to a scaled integer (bigint) by multiplying by 10^exponent. This is commonly used for handling token amounts where you need to convert from human-readable decimals to the smallest unit (like converting ETH to wei or PC to uPC).

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").
exponent	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 `bigint`

// bigint - the scaled integer value
1500000000000000000n

Live Playground: Parse Units for Common Token Scenarios

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