{ "schema_version": "1.0.0", "version": "1.5.0", "current_sdk_version": "6.0.26", "generated": "2026-09-22T00:00:00.000Z", "description": "Complete SDK method surface for @pushchain/core and @pushchain/ui-kit: all namespaces, method signatures, parameter types, return types, and safe_for_autonomous_execution flags. For intent-level capability definitions (what an agent can do) see capabilities.json. For routing logic see decision-tree.json and task-router.md.", "namespaces": [ { "namespace": "PushChain", "description": "Root SDK namespace for initialization and constants", "methods": [ { "name": "initialize", "signature": "PushChain.initialize(signer: UniversalSigner | UniversalAccount, options: { network: PUSH_NETWORK, rpcUrls?, blockExplorers?, printTraces?, progressHook? }): Promise", "description": "Initializes SDK client with universal signer or read-only account", "returns": "PushChainClient", "safe_for_autonomous_execution": true } ] }, { "namespace": "PushChain.CONSTANTS", "description": "All constant values for networks, chains, libraries, and tokens", "methods": [ { "name": "PUSH_NETWORK", "signature": "PushChain.CONSTANTS.PUSH_NETWORK.TESTNET | TESTNET_DONUT | MAINNET | LOCALNET", "description": "Network constants: TESTNET (latest testnet), TESTNET_DONUT (Donut testnet), MAINNET, LOCALNET", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "CHAIN", "signature": "PushChain.CONSTANTS.CHAIN.", "description": "Chain identifiers in CAIP-2 format. CHAIN.WEB2 (web2:https) is a read-only destination for Universal Read, not a transaction destination.", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "LIBRARY", "signature": "PushChain.CONSTANTS.LIBRARY.", "description": "Supported signer library constants", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "MOVEABLE.TOKEN", "signature": "PushChain.CONSTANTS.MOVEABLE.TOKEN.", "description": "Supported tokens for cross-chain asset movement", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "PAYABLE.TOKEN", "signature": "PushChain.CONSTANTS.PAYABLE.TOKEN.", "description": "Supported tokens for paying gas fees via tx.payGasWith", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "READ", "signature": "PushChain.CONSTANTS.READ.STATUS | RESULT_STATUS | UNIVERSAL_READ_REGISTRY_ADDRESS.TESTNET_DONUT", "description": "Universal Read constants. READ.STATUS is the request lifecycle (PENDING, VOTING, FULFILLED, EXPIRED, FAILED, ABORTED); READ.RESULT_STATUS is what the source returned (SUCCESS or ERROR); READ.UNIVERSAL_READ_REGISTRY_ADDRESS.TESTNET_DONUT is the Universal Read Registry (0x00000000000000000000000000000000000000b2). Full values in agents/constants.json.", "returns": "object", "safe_for_autonomous_execution": true } ] }, { "namespace": "PushChain.utils.svm", "description": "Solana (SVM) escape-hatch utilities for manual Anchor IDL registration. Only needed when building tx.data manually with raw Anchor discriminator + Borsh bytes — normal callers use encodeTxData({ idl, ... }) which auto-registers.", "methods": [ { "name": "registerIdl", "signature": "PushChain.utils.svm.registerIdl(programId: string, idl: Idl): void", "description": "Manually registers an Anchor IDL for a given Solana program ID. Required only when constructing raw SVM tx data without encodeTxData.", "returns": "void", "safe_for_autonomous_execution": true }, { "name": "getRegisteredIdls", "signature": "PushChain.utils.svm.getRegisteredIdls(): Record", "description": "Returns all currently registered Anchor IDLs keyed by program ID.", "returns": "Record", "safe_for_autonomous_execution": true } ] }, { "namespace": "PushChain.utils.signer", "description": "Universal signer creation and conversion utilities", "methods": [ { "name": "toUniversal", "signature": "PushChain.utils.signer.toUniversal(signer: viem.WalletClient | ethers.Wallet | UniversalSignerSkeleton): Promise", "description": "Converts EVM signer or skeleton to universal signer. Since v6.0.19 auto-wires the optional signAuthorization method (EIP-7702) for ethers v6 Wallet (local key) and viem local accounts (e.g. privateKeyToAccount), enabling atomic native-EOA multicall batching. Not available for JSON-RPC accounts (browser wallets like MetaMask) or ethers v5.", "returns": "UniversalSigner", "safe_for_autonomous_execution": true }, { "name": "toUniversalFromKeypair", "signature": "PushChain.utils.signer.toUniversalFromKeypair(keypair: Keypair, options: { chain: CHAIN, library: LIBRARY }): Promise", "description": "Converts non-EVM keypair (e.g., Solana) to universal signer", "returns": "UniversalSigner", "safe_for_autonomous_execution": true }, { "name": "construct", "signature": "PushChain.utils.signer.construct(account: UniversalAccount, options: { signAndSendTransaction, signMessage, signTypedData, signAuthorization? }): UniversalSignerSkeleton", "description": "Constructs custom signer skeleton with manual signing implementations. Optional signAuthorization (v6.0.19+): (params: { contractAddress: `0x${string}`, chainId?: number, nonce?: number, executor?: 'self' }) => Promise (viem-compatible { address, chainId, nonce, r, s, yParity, v? }) — provide it to enable atomic EIP-7702 multicall batching for native Push Chain EOAs.", "returns": "UniversalSignerSkeleton", "safe_for_autonomous_execution": true } ] }, { "namespace": "PushChain.utils.account", "description": "Account conversion and derivation utilities", "methods": [ { "name": "toUniversal", "signature": "PushChain.utils.account.toUniversal(address: string, options: { chain: CHAIN }): UniversalAccount", "description": "Converts address to UniversalAccount with chain context", "returns": "UniversalAccount", "safe_for_autonomous_execution": true }, { "name": "toChainAgnostic", "signature": "PushChain.utils.account.toChainAgnostic(address: string, options: { chain: CHAIN }): string", "description": "Produces a fully-qualified CAIP-10 chain-agnostic address string, e.g. 'eip155:11155111:0xAbc...'", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "fromChainAgnostic", "signature": "PushChain.utils.account.fromChainAgnostic(caip: string): UniversalAccount", "description": "Parses a CAIP-10 chain-agnostic address string back into a UniversalAccount", "returns": "UniversalAccount", "safe_for_autonomous_execution": true }, { "name": "deriveExecutorAccount", "signature": "PushChain.utils.account.deriveExecutorAccount(uoa: UniversalAccount, options: { chain: CHAIN; skipNetworkCheck?: boolean }): Promise<{ address: string }>", "description": "Derives the Chain Executor Account (CEA) address for a given UOA on a specific external chain. Use skipNetworkCheck:true for chains not yet live.", "returns": "Promise<{ address: string }>", "safe_for_autonomous_execution": true }, { "name": "resolveControllerAccount", "signature": "PushChain.utils.account.resolveControllerAccount(account: string, options?: { chain?: CHAIN; skipNetworkCheck?: boolean }): Promise<{ accounts: Array<{ chain, chainName, address, type, exists, role? }> }>", "description": "Recursively resolves the controller identity chain behind any executor address. UEA → UOA; CEA → Push account → UOA. type: 'uea' | 'uoa' | 'cea'. role: 'controller' marks the root controlling account. Pass options.chain for CEA resolution. Complement of deriveExecutorAccount (forward: UOA→executor; this: executor→UOA).", "returns": "Promise<{ accounts: Array<{ chain, chainName, address, type, exists, role? }> }>", "safe_for_autonomous_execution": true }, { "name": "convertExecutorToOriginAccount", "signature": "PushChain.utils.account.convertExecutorToOriginAccount(executorAddress: string, options?: { chain?: CHAIN }): Promise", "description": "Reverse-maps a UEA (Push Chain execution account) to its origin wallet. Pass options.chain to treat as CEA from a specific chain.", "returns": "Promise", "safe_for_autonomous_execution": true }, { "name": "convertOriginToExecutor", "signature": "PushChain.utils.account.convertOriginToExecutor(account: UniversalAccount, options?: { onlyCompute?: boolean }): Promise<{ address: string, isDeployed: boolean }>", "description": "Maps an origin UniversalAccount to its executor account (UEA) address on Push Chain. Use onlyCompute:true to get address without deployment check.", "returns": "Promise<{ address: string, isDeployed: boolean }>", "safe_for_autonomous_execution": true } ] }, { "namespace": "PushChain.utils.helpers", "description": "Common utility functions for data formatting and encoding", "methods": [ { "name": "parseUnits", "signature": "PushChain.utils.helpers.parseUnits(value: string, decimals: number | { decimals: number }): bigint", "description": "Parses decimal string to smallest unit bigint. Accepts decimals as a number (e.g., 18) or object (e.g., { decimals: 18 })", "returns": "bigint", "safe_for_autonomous_execution": true }, { "name": "formatUnits", "signature": "PushChain.utils.helpers.formatUnits(value: string | bigint, decimals: number | { decimals: number, precision?: number }): string", "description": "Converts smallest unit value back to human-readable string. Inverse of parseUnits.", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "encodeTxData", "signature": "PushChain.utils.helpers.encodeTxData({ abi: AbiFragment[], functionName: string, args?: any[] }): string", "description": "ABI-encodes a contract function call into hex calldata", "returns": "string", "safe_for_autonomous_execution": true } ] }, { "namespace": "PushChain.utils.chains", "description": "Chain metadata utilities for querying supported chains and identifiers", "methods": [ { "name": "getSupportedChains", "signature": "PushChain.utils.chains.getSupportedChains(network: PUSH_NETWORK): { chains: CHAIN[] }", "description": "Returns array of CAIP-2 chain identifiers supported on the given network", "returns": "{ chains: CHAIN[] }", "safe_for_autonomous_execution": true }, { "name": "getSupportedChainsByName", "signature": "PushChain.utils.chains.getSupportedChainsByName(network: PUSH_NETWORK): { chains: string[] }", "description": "Returns human-readable chain name strings supported on the given network, e.g. ['PUSH_TESTNET_DONUT', 'ETHEREUM_SEPOLIA']", "returns": "{ chains: string[] }", "safe_for_autonomous_execution": true }, { "name": "getChainName", "signature": "PushChain.utils.chains.getChainName(chainNamespace: string): string", "description": "Returns human-readable chain name from a CAIP-2 chain identifier", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "getChainNamespace", "signature": "PushChain.utils.chains.getChainNamespace(chain: CHAIN): string", "description": "Returns the namespace portion of a CAIP-2 chain identifier (e.g., 'eip155' or 'solana')", "returns": "string", "safe_for_autonomous_execution": true } ] }, { "namespace": "PushChain.utils.tokens", "description": "Token utilities for querying moveable and payable tokens per chain", "methods": [ { "name": "getMoveableTokens", "signature": "PushChain.utils.tokens.getMoveableTokens(chain: CHAIN): { tokens: MoveableToken[] }", "description": "Returns list of tokens that can be moved cross-chain via tx.funds for a given origin chain", "returns": "{ tokens: MoveableToken[] }", "safe_for_autonomous_execution": true }, { "name": "getPayableTokens", "signature": "PushChain.utils.tokens.getPayableTokens(chain: CHAIN): { tokens: PayableToken[] }", "description": "Returns list of tokens accepted for gas fee payment via tx.payGasWith for a given origin chain", "returns": "{ tokens: PayableToken[] }", "safe_for_autonomous_execution": true }, { "name": "getPRC20Address", "signature": "PushChain.utils.tokens.getPRC20Address(token: MoveableToken | { chain: CHAIN, address: string }, options?: { network?: PUSH_NETWORK }): { address: `0x${string}`; chain: CHAIN; symbol: string; decimals: number; network: PUSH_NETWORK }", "description": "Returns the full PRC-20 token descriptor on Push Chain corresponding to a moveable token (address, chain, symbol, decimals, network). PRC-20 = a token born on an EXTERNAL chain, mirrored inward as a synthetic on Push Chain (USDC.eth, pETH). Synchronous — resolved from the SDK's static token table. For tokens born ON Push Chain (PC-20), use the async getPC20Address instead.", "returns": "{ address: `0x${string}`; chain: CHAIN; symbol: string; decimals: number; network: PUSH_NETWORK }", "safe_for_autonomous_execution": true }, { "name": "getPC20Address", "signature": "PushChain.utils.tokens.getPC20Address(address: string, options: { network: PUSH_NETWORK; chain?: CHAIN; rpcUrls?: Partial>; strict?: boolean }): Promise", "description": "Resolves a PC-20 token (a token born ON Push Chain, mirrored outward as wrappers on external chains) against UniversalCore's on-chain registry, and lists every confirmed deployment. Accepts either end of the mapping — an external wrapper or the canonical Push-native token — and always returns the canonical token at .address, with every known deployment in .registry (confirmed only; a predicted first-export wrapper address never appears). Asynchronous, unlike getPRC20Address: PC-20 mappings are dynamic and live on chain. Never symbol-based — identity is address-and-chain only. options.chain is optional for lookup (SDK works out which chain the address belongs to; throws PC20AmbiguousAddressError if several chains claim it) but funds.token.chain is REQUIRED when spending. Resolve wrapper addresses from getPC20Address(...).registry — the authoritative record. receipt.externalAssetAddr is a best-effort mirror: the raw chain field is only observed when a wrapper is newly deployed, and although the SDK backfills it from UniversalCore it is undefined while an outbound is still in flight. Throws PC20WrapperNotRegisteredError, PC20RegistryMismatchError, PC20ExpectedButPRC20Error, PC20AmbiguousAddressError — see agents/errors.json for the full typed PC-20 error family.", "returns": "Promise<{ address: `0x${string}`; name: string; symbol: string; decimals: number; network: PUSH_NETWORK; registry: Array<{ address: string; chain: CHAIN; chainName: string }> }>", "safe_for_autonomous_execution": true } ] }, { "namespace": "PushChain.utils.conversion", "description": "Conversion utilities for slippage and amount calculations", "methods": [ { "name": "slippageToMinAmount", "signature": "PushChain.utils.conversion.slippageToMinAmount(amount: string, options: { slippageBps: number }): string", "description": "Calculates minimum acceptable output amount after applying slippage. slippageBps: 100 = 1%, 50 = 0.5%. Use result as tx.payGasWith.minAmountOut.", "returns": "string", "safe_for_autonomous_execution": true } ] }, { "namespace": "pushChainClient", "description": "Initialized client instance methods", "methods": [ { "name": "getAccountStatus", "signature": "pushChainClient.getAccountStatus(options?: { forceRefresh?: boolean }): Promise", "description": "Returns UEA deployment status, version, and upgrade requirements", "returns": "AccountStatus", "safe_for_autonomous_execution": true }, { "name": "upgradeAccount", "signature": "pushChainClient.upgradeAccount(options?: { progressHook?: (event) => void }): Promise", "description": "Upgrades UEA to latest required version (gasless signature operation)", "returns": "void", "safe_for_autonomous_execution": false }, { "name": "reinitialize", "signature": "pushChainClient.reinitialize(signerOrAccount: UniversalSigner | UniversalAccount, options?: InitializeOptions): Promise", "description": "Creates new client with different signer/account or updated config", "returns": "PushChainClient", "safe_for_autonomous_execution": true } ] }, { "namespace": "pushChainClient.universal", "description": "Universal transaction and signing operations", "methods": [ { "name": "origin", "signature": "pushChainClient.universal.origin: UniversalAccount", "description": "Getter for origin account (source chain wallet identity)", "returns": "UniversalAccount", "safe_for_autonomous_execution": true }, { "name": "account", "signature": "pushChainClient.universal.account: UniversalAccount", "description": "Getter for execution account (UEA on Push Chain)", "returns": "UniversalAccount", "safe_for_autonomous_execution": true }, { "name": "sendTransaction", "signature": "pushChainClient.universal.sendTransaction(tx: { to, from?, value?, data?, funds?, progressHook?, gasLimit?, maxFeePerGas?, maxPriorityFeePerGas?, payGasWith?, deadline?, options?: { enforceGasCheck?: boolean } }): Promise", "description": "Sends universal transaction. Advanced args: gasLimit/maxFeePerGas/maxPriorityFeePerGas override gas; payGasWith pays fees in supported token; deadline sets execution expiry; options.enforceGasCheck (default false) — when true, the SDK throws InsufficientUEABalanceError on pre-flight gas/balance shortfall instead of emitting a WARNING progress event and proceeding. Solana targets use encodeTxData({ idl, functionName, args }) passed as tx.data — there is no svmExecute field. Multicall (outer tx.to = zero address, tx.data = Array<{to, value, data}>): from a native Push Chain EOA the batch executes atomically in a single EIP-7702 type-4 (SetCode) transaction when the signer supports signAuthorization (v6.0.19+; requires the batch executor to be deployed on the chain — Donut: yes, mainnet: not yet); if the signer cannot sign an authorization the SDK logs a warning and falls back to the legacy non-atomic sequential per-call loop before any broadcast. External-origin batches are unchanged and always atomic via UEA_MULTICALL. Every inner multicall entry must have a non-zero `to` (only the outer tx.to stays the zero address to signal multicall mode). The UniversalTxResponse includes `atomic: boolean` — false only when a native-EOA multicall fell back to sequential execution.", "returns": "UniversalTxResponse", "safe_for_autonomous_execution": false }, { "name": "prepareTransaction", "signature": "pushChainClient.universal.prepareTransaction(tx: { to, from?, value?, data?, funds?, gasLimit?, maxFeePerGas?, maxPriorityFeePerGas?, payGasWith?, deadline?, options?: { enforceGasCheck?: boolean } }): Promise", "description": "Prepares a transaction without executing it. Returns PreparedUniversalTx with route, estimatedGas, nonce, deadline, payload. Pass result to executeTransactions for multi-hop cascades. options.enforceGasCheck (default false) carries strict pre-flight gas/balance enforcement into executeTransactions — setting it on any single hop opts the entire cascade into strict mode.", "returns": "PreparedUniversalTx", "safe_for_autonomous_execution": true }, { "name": "executeTransactions", "signature": "pushChainClient.universal.executeTransactions(txs: PreparedUniversalTx[]): Promise", "description": "Executes ordered array of prepared transactions as a single-signature multi-hop cascade. Returns CascadedTxResponse with initialTxHash, hops[], hopCount, wait(opts?), waitForAll(opts?).", "returns": "CascadedTxResponse", "safe_for_autonomous_execution": false }, { "name": "trackTransaction", "signature": "pushChainClient.universal.trackTransaction(txHash: string, options?: { chain?: CHAIN, progressHook?: (event: ProgressEvent) => void, waitForCompletion?: boolean, advanced?: { pollingIntervalMs?: number, timeout?: number, rpcUrls?: Partial> } }): Promise", "description": "Resumes tracking any universal transaction by hash and origin chain. Works independently of sendTransaction — pass any stored hash. Defaults chain to PUSH_TESTNET_DONUT. Set waitForCompletion:false for a snapshot status check without waiting. On Push Chain Donut, history-sensitive reads (transactions, receipts, universal-tx status) query the default pruned RPC first and automatically retry the archive endpoints on a pruned-history miss (v6.0.19+) — old transactions no longer fail to resolve; no new option needed.", "arguments": [ { "name": "txHash", "type": "string", "required": true, "description": "Transaction hash on the origin chain" }, { "name": "options.chain", "type": "CHAIN", "required": false, "description": "Origin chain — defaults to PUSH_TESTNET_DONUT" }, { "name": "options.progressHook", "type": "(event: ProgressEvent) => void", "required": false, "description": "Callback invoked at each tracking step" }, { "name": "options.waitForCompletion", "type": "boolean", "required": false, "description": "true = poll until confirmed (default), false = return current status snapshot" }, { "name": "options.advanced.pollingIntervalMs", "type": "number", "required": false, "description": "Poll interval in ms (default 2000, min 500)" }, { "name": "options.advanced.timeout", "type": "number", "required": false, "description": "Max wait in ms before timeout (default 60000)" }, { "name": "options.advanced.rpcUrls", "type": "Partial>", "required": false, "description": "Custom RPC URLs for status queries" } ], "returns": "UniversalTxResponse", "safe_for_autonomous_execution": true }, { "name": "migrateCEA", "signature": "pushChainClient.universal.migrateCEA(chain: CHAIN): Promise", "description": "Migrates the Chain Executor Account (CEA) contract on an external chain to the latest implementation. Sends a MIGRATION_SELECTOR payload via Route 2. Pass the external chain whose CEA should be upgraded (e.g. PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA).", "returns": "UniversalTxResponse", "safe_for_autonomous_execution": false }, { "name": "rescueFunds", "signature": "pushChainClient.universal.rescueFunds(params: { universalTxId: `0x${string}`, prc20: `0x${string}` }): Promise", "description": "Recovers funds locked in the source-chain Vault after a CEA-to-Push (Route 3) inbound transaction fails, leaving the bridged tokens stuck. Triggers a manual TSS revert that releases them back to the user. universalTxId is the bytes32 hash of the failed inbound transaction; prc20 is the Push Chain PRC-20 token address whose source-chain counterpart is locked.", "returns": "UniversalTxResponse", "safe_for_autonomous_execution": false }, { "name": "signMessage", "signature": "pushChainClient.universal.signMessage(message: string | Uint8Array): Promise", "description": "Signs arbitrary message bytes", "returns": "Uint8Array", "safe_for_autonomous_execution": false }, { "name": "signTypedData", "signature": "pushChainClient.universal.signTypedData(typedDataArgs: TypedDataArgs): Promise", "description": "Signs EIP-712 typed data", "returns": "Uint8Array", "safe_for_autonomous_execution": false }, { "name": "read", "signature": "pushChainClient.universal.read(subject: string, options: { chain: CHAIN, token?: string, abi?: any[], idl?: any, functionName?: string, args?: any[], storageSlot?: bigint | Hex, web2?: { extract: Array<{ path: string, valueType: 'uint256' | 'int256' | 'bool' | 'string' | 'bytes', decimals?: number }>, method?: 'GET' | 'POST', headers?: Record, body?: string | Uint8Array, timeoutMs?: number }, callback?: { target: string, gasLimit: bigint, abi: Abi, functionName: string, args?: (spec, gasLimit) => unknown[] }, waitForCompletion?: boolean, progressHook?: (progress: ProgressEvent) => void, blockNumber?: bigint, minConfirmations?: number, expiryBlocks?: bigint, maxFee?: bigint, refundTo?: string, advanced?: { pollingIntervalMs?: number, timeout?: number, enforceGasCheck?: boolean } }): Promise", "description": "Requests state from an EVM chain, Solana or an HTTPS endpoint and has validators deliver the agreed result on-chain to Push Chain: to the Universal Read Registry (0x00000000000000000000000000000000000000b2, the default) or to your own UniversalReadClient receiver via callback. One query option picks the read: none = native balance, token = ERC-20 or SPL balance, abi or idl + functionName (+ args) = typed contract call or Solana program account, storageSlot = EVM storage word, web2 = JSON fields from an HTTPS endpoint (chain: CHAIN.WEB2). Paid and asynchronous. value is the success signal; when it is undefined, check status, raw.status, callbackDelivered and decodeError. Response: requestId, requestIdUint, txHash, chain, status (READ.STATUS), isTerminal, callbackDelivered, callbackFailReason, value, decodeError, raw { status, resultData, errorCode }, errorMsg, fees, request, pcTx, explorerUrl, wait(), refresh().", "arguments": [ { "name": "subject", "type": "string", "required": true, "description": "What to read: an account address for a balance, a contract address for a contract call or storage slot, or a URL for a Web2 read. Solana subjects are base58." }, { "name": "options.chain", "type": "CHAIN", "required": true, "description": "Where to read from: any supported EVM or Solana chain, or CHAIN.WEB2 for an HTTPS endpoint. Pass at most one query option; with none, read returns the subject's native balance." }, { "name": "options.token", "type": "string", "required": false, "description": "Web3 chains. Token balance of subject. EVM: the ERC-20 contract address, read via balanceOf. Solana: the SPL mint address; the SDK derives the associated token account." }, { "name": "options.abi | options.idl", "type": "any[]", "required": false, "description": "Web3 chains. An EVM ABI array or an Anchor IDL object. The input shape determines the encoding and how value is decoded, so the result is typed. With an IDL and no functionName, a Solana program account is read and decoded." }, { "name": "options.functionName", "type": "string", "required": false, "description": "Web3 chains. The function (EVM) or instruction (Solana) to encode. snake_case and camelCase are both accepted and matched against the IDL." }, { "name": "options.args", "type": "any[]", "required": false, "description": "Web3 chains. Positional arguments. Use BigInt for u64/u128; 0x-hex 32-byte strings become Solana PublicKey when the IDL declares a pubkey arg." }, { "name": "options.storageSlot", "type": "bigint | Hex", "required": false, "description": "EVM only. One storage word from the subject contract." }, { "name": "options.web2", "type": "{ extract, method?, headers?, body?, timeoutMs? }", "required": false, "description": "Required when chain is CHAIN.WEB2. extract: 1 to 16 entries of { path (JSONPath), valueType ('uint256' | 'int256' | 'bool' | 'string' | 'bytes'), decimals? }; results come back as an array in the same order. method defaults to GET; body is POST only; timeoutMs defaults to 5000. URL, headers and body are written to a public event log, so never include secrets." }, { "name": "options.callback", "type": "{ target, gasLimit, abi, functionName, args? }", "required": false, "description": "Routes the request through your own receiver contract (inherits UniversalReadClient) instead of the Universal Read Registry. gasLimit is the gas for _onReadResult (default 500_000n, at most 1_000_000n); functionName is the payable request entrypoint, which must emit exactly one ReadRequested per prepared read; args maps (spec, gasLimit) onto a different entrypoint argument order." }, { "name": "options.waitForCompletion", "type": "boolean", "required": false, "description": "Default true. false resolves once the request is confirmed on Push Chain, before validators vote; call wait() on the response to finish." }, { "name": "options.progressHook", "type": "(progress: ProgressEvent) => void", "required": false, "description": "Progress events READ-TX-101 through READ-TX-199-99." }, { "name": "options.blockNumber", "type": "bigint", "required": false, "description": "EVM only. Pins the read to a destination block. Default: oracle height minus minConfirmations." }, { "name": "options.minConfirmations", "type": "number", "required": false, "description": "EVM only. Confirmations the destination block must have. Default 1." }, { "name": "options.expiryBlocks", "type": "bigint", "required": false, "description": "Request lifetime in Push Chain blocks. Default 300n. An unfulfilled request expires and refunds the unused callback budget." }, { "name": "options.maxFee", "type": "bigint", "required": false, "description": "Cap on the upfront payment (protocol fee plus callback budget). Default: SDK estimated." }, { "name": "options.refundTo", "type": "string", "required": false, "description": "Where unused callback budget is sent. Default: your Push account. Must accept native transfers." }, { "name": "options.advanced.pollingIntervalMs", "type": "number", "required": false, "description": "Milliseconds between status polls. Default 2000, minimum 500." }, { "name": "options.advanced.timeout", "type": "number", "required": false, "description": "Maximum milliseconds this caller waits. Default derived from expiry, at most 180000. Timing out does not cancel the request; resume with trackRead." }, { "name": "options.advanced.enforceGasCheck", "type": "boolean", "required": false, "description": "Default false: warn and proceed when the pre-flight balance check finds a shortfall. true throws before broadcasting." } ], "returns": "UniversalReadResponse", "safe_for_autonomous_execution": false, "docs_url": "https://push.org/docs/chain/build/universal-read/" }, { "name": "prepareRead", "signature": "pushChainClient.universal.prepareRead(subject: string, options: { chain: CHAIN, token? | abi? | idl? + functionName? + args? | storageSlot? | web2?, callback?, blockNumber?, minConfirmations?, expiryBlocks?, maxFee?, refundTo? }): Promise", "description": "Prepares a read without executing it: nothing is broadcast and nothing is paid, so no funds are needed. Takes the same subject and query options as read, but not waitForCompletion, progressHook or advanced (those belong to executeReads). Returns PreparedRead { queryKey, chain, spec, specTuple, encodedSpec, value, fees { protocolFee, callbackBudget, total }, callbackGasLimit, callback, resultShape, preflight, warnings }. value (equal to fees.total) is the msg.value the request carries; specTuple is the positional ReadSpec for a hand-built call to your own entrypoint.", "arguments": [ { "name": "subject", "type": "string", "required": true, "description": "What to read: an account address for a balance, a contract address for a contract call or storage slot, or a URL for a Web2 read. Solana subjects are base58." }, { "name": "options.chain", "type": "CHAIN", "required": true, "description": "Where to read from: any supported EVM or Solana chain, or CHAIN.WEB2 for an HTTPS endpoint. Pass at most one query option; with none, read returns the subject's native balance." }, { "name": "options.token", "type": "string", "required": false, "description": "Web3 chains. Token balance of subject. EVM: the ERC-20 contract address, read via balanceOf. Solana: the SPL mint address; the SDK derives the associated token account." }, { "name": "options.abi | options.idl", "type": "any[]", "required": false, "description": "Web3 chains. An EVM ABI array or an Anchor IDL object. The input shape determines the encoding and how value is decoded, so the result is typed. With an IDL and no functionName, a Solana program account is read and decoded." }, { "name": "options.functionName", "type": "string", "required": false, "description": "Web3 chains. The function (EVM) or instruction (Solana) to encode. snake_case and camelCase are both accepted and matched against the IDL." }, { "name": "options.args", "type": "any[]", "required": false, "description": "Web3 chains. Positional arguments. Use BigInt for u64/u128; 0x-hex 32-byte strings become Solana PublicKey when the IDL declares a pubkey arg." }, { "name": "options.storageSlot", "type": "bigint | Hex", "required": false, "description": "EVM only. One storage word from the subject contract." }, { "name": "options.web2", "type": "{ extract, method?, headers?, body?, timeoutMs? }", "required": false, "description": "Required when chain is CHAIN.WEB2. extract: 1 to 16 entries of { path (JSONPath), valueType ('uint256' | 'int256' | 'bool' | 'string' | 'bytes'), decimals? }; results come back as an array in the same order. method defaults to GET; body is POST only; timeoutMs defaults to 5000. URL, headers and body are written to a public event log, so never include secrets." }, { "name": "options.callback", "type": "{ target, gasLimit, abi, functionName, args? }", "required": false, "description": "Routes the request through your own receiver contract (inherits UniversalReadClient) instead of the Universal Read Registry. gasLimit is the gas for _onReadResult (default 500_000n, at most 1_000_000n); functionName is the payable request entrypoint, which must emit exactly one ReadRequested per prepared read; args maps (spec, gasLimit) onto a different entrypoint argument order." }, { "name": "options.blockNumber", "type": "bigint", "required": false, "description": "EVM only. Pins the read to a destination block. Default: oracle height minus minConfirmations." }, { "name": "options.minConfirmations", "type": "number", "required": false, "description": "EVM only. Confirmations the destination block must have. Default 1." }, { "name": "options.expiryBlocks", "type": "bigint", "required": false, "description": "Request lifetime in Push Chain blocks. Default 300n. An unfulfilled request expires and refunds the unused callback budget." }, { "name": "options.maxFee", "type": "bigint", "required": false, "description": "Cap on the upfront payment (protocol fee plus callback budget). Default: SDK estimated." }, { "name": "options.refundTo", "type": "string", "required": false, "description": "Where unused callback budget is sent. Default: your Push account. Must accept native transfers." } ], "returns": "PreparedRead", "safe_for_autonomous_execution": true, "docs_url": "https://push.org/docs/chain/build/read-multiple-universal-states/" }, { "name": "executeReads", "signature": "pushChainClient.universal.executeReads(preparedReads: PreparedRead[], options?: { waitForCompletion?: boolean, progressHook?: (progress: ProgressEvent) => void, advanced?: { pollingIntervalMs?: number, timeout?: number, enforceGasCheck?: boolean } }): Promise", "description": "Executes an ordered array of prepared reads as one flow: a single transaction (one signature) where the wallet supports atomic batching, otherwise sequential transactions listed in transactionHashes. Returns BatchReadResponse { txHash, transactionHashes, reads, count, atomic, wait() }; wait() returns the UniversalReadResponse array in prepared order. atomic describes submission only; validators fulfill each read on its own, so check value on every response. With sequential submission, check the hashes on an error before resubmitting.", "arguments": [ { "name": "preparedReads", "type": "PreparedRead[]", "required": true, "description": "Reads returned by prepareRead. Results come back in this order." }, { "name": "options.waitForCompletion", "type": "boolean", "required": false, "description": "Default true. false returns once the requests are submitted; call wait() to finish." }, { "name": "options.progressHook", "type": "(progress: ProgressEvent) => void", "required": false, "description": "Batch events READ-TX-001 to READ-TX-999-03 plus each read's own READ-TX-1xx events." }, { "name": "options.advanced.pollingIntervalMs", "type": "number", "required": false, "description": "Milliseconds between status polls. Default 2000, minimum 500." }, { "name": "options.advanced.timeout", "type": "number", "required": false, "description": "Maximum milliseconds this caller waits. Timing out cancels nothing." }, { "name": "options.advanced.enforceGasCheck", "type": "boolean", "required": false, "description": "true throws before broadcasting when the balance check finds a shortfall." } ], "returns": "BatchReadResponse", "safe_for_autonomous_execution": false, "docs_url": "https://push.org/docs/chain/build/read-multiple-universal-states/" }, { "name": "trackRead", "signature": "pushChainClient.universal.trackRead({ requestId } | { txHash }, options?: { resultShape?: { kind: 'evmCall', abi, functionName } | ..., progressHook?: (progress: ProgressEvent) => void, advanced?: { pollingIntervalMs?: number, timeout?: number } }): Promise", "description": "Returns the current state of a read by its request ID (hex or numeric), or of every read submitted by a Push Chain transaction (an array, since one transaction can carry several reads). Works with a read-only client that has no signer and no funds, from any session. Call wait() on a snapshot to poll to a terminal status, or refresh() for one fresh snapshot. Balances, storage and Web2 reads decode automatically; pass resultShape to decode a typed contract call resumed in a new session. A wait() timeout throws ReadTimeoutError (code READ_TIMEOUT) and cancels nothing.", "arguments": [ { "name": "ref.requestId | ref.txHash", "type": "string | bigint", "required": true, "description": "The read's request ID (hex or numeric), or the Push Chain transaction that submitted it. Pass one." }, { "name": "options.resultShape", "type": "{ kind: 'evmCall', abi, functionName } and others", "required": false, "description": "How to decode resultData. Inferred for balances, storage and Web2; a typed contract call resumed in a new session needs it, or value stays raw bytes." }, { "name": "options.progressHook", "type": "(progress: ProgressEvent) => void", "required": false, "description": "Invoked at each lifecycle step while wait() polls." }, { "name": "options.advanced.pollingIntervalMs", "type": "number", "required": false, "description": "Milliseconds between polls in wait(). Default 2000, minimum 500." }, { "name": "options.advanced.timeout", "type": "number", "required": false, "description": "Maximum milliseconds wait() polls before throwing ReadTimeoutError. Default derived from expiry, at most 180000." } ], "returns": "UniversalReadResponse | UniversalReadResponse[]", "safe_for_autonomous_execution": true, "docs_url": "https://push.org/docs/chain/build/track-universal-read/" } ] }, { "namespace": "pushChainClient.explorer", "description": "Block explorer URL utilities", "methods": [ { "name": "getTransactionUrl", "signature": "pushChainClient.explorer.getTransactionUrl(txHash: string, options?: { chain?: CHAIN }): string", "description": "Returns a block explorer URL for the given transaction hash. Defaults to the Push Chain explorer; pass options.chain to get the URL on a specific external chain instead.", "returns": "string", "safe_for_autonomous_execution": true }, { "name": "listUrls", "signature": "pushChainClient.explorer.listUrls(options?: { chain?: CHAIN }): { explorers: Array<{ chain: string; chainName: string; urls: string[] }> }", "description": "Lists configured block explorer URLs. Defaults to client's origin chain; pass options.chain to list explorers for a specific chain.", "returns": "{ explorers: Array<{ chain: string; chainName: string; urls: string[] }> }", "safe_for_autonomous_execution": true }, { "name": "listAllUrls", "signature": "pushChainClient.explorer.listAllUrls(): { explorers: Array<{ chain: string; chainName: string; urls: string[] }> }", "description": "Lists block explorer URLs for ALL supported chains at once. Useful for building explorer link pickers or cross-chain dashboards.", "returns": "{ explorers: Array<{ chain: string; chainName: string; urls: string[] }> }", "safe_for_autonomous_execution": true } ] }, { "namespace": "pushChainClient.funds", "description": "Conversion quote utilities for cross-chain token swaps", "methods": [ { "name": "getConversionQuote", "signature": "pushChainClient.funds.getConversionQuote(amountIn: bigint, options: { from: PayableToken, to: MoveableToken }): Promise", "description": "Returns a conversion quote for swapping one token to another. from = payable token (what you pay with), to = moveable token (what you move). Returns amountIn, amountOut, rate, route, timestamp.", "returns": "Promise<{ amountIn: string, amountOut: string, rate: number, route?: string[], timestamp: number }>", "safe_for_autonomous_execution": true } ] }, { "namespace": "pushChainClient.orchestrator", "description": "Internal orchestration layer (typically not called directly)", "methods": [ { "name": "orchestrator", "signature": "pushChainClient.orchestrator", "description": "Handles RPC resolution, UEA management, and gas orchestration internally (internal use)", "returns": "Orchestrator", "safe_for_autonomous_execution": true } ] } ], "ui_kit_exports": [ { "namespace": "@pushchain/ui-kit", "description": "React components and hooks for wallet integration. Bundles @pushchain/core — no separate install needed. Use usePushChainClient() to access PushChainClient and call sendTransaction, signMessage, prepareTransaction, executeTransactions directly from React.", "exports": [ { "name": "PushUniversalWalletProvider", "type": "component", "description": "React context provider for wallet state management", "safe_for_autonomous_execution": true }, { "name": "PushUniversalAccountButton", "type": "component", "description": "Pre-built connect/disconnect wallet button", "safe_for_autonomous_execution": true }, { "name": "usePushWalletContext", "type": "hook", "description": "Access wallet connection status and actions", "safe_for_autonomous_execution": true }, { "name": "usePushChainClient", "type": "hook", "description": "Returns the initialized PushChainClient (from @pushchain/core) after wallet connection. Exposes all core transaction methods: sendTransaction, signMessage, prepareTransaction, executeTransactions, and the Universal Read methods read, prepareRead, executeReads and trackRead. This is the primary way to execute universal transactions in a React app. Note on multicall: browser wallets connect as JSON-RPC accounts and cannot sign EIP-7702 authorizations, so a native-Push-EOA batch sent from the browser falls back to sequential (non-atomic) execution; check response.atomic to see which path ran. Push Wallet email/google logins and backend local-key signers can use the atomic path.", "safe_for_autonomous_execution": true }, { "name": "usePushChain", "type": "hook", "description": "Combined hook for Push Chain state and actions", "safe_for_autonomous_execution": true }, { "name": "PushUI.CONSTANTS", "type": "object", "description": "UI Kit constants including PUSH_NETWORK and CONNECTION.STATUS", "safe_for_autonomous_execution": true } ] } ] }