Chain Agnostic Address: {chainAgnostic}
; } ``` --- ## Send a Universal Transaction ```tsx // @pushchain/core is bundled in @pushchain/ui-kit - no separate install needed. // Use usePushChain() to access the SDK; do not add @pushchain/core to package.json. import { usePushChainClient, usePushChain } from '@pushchain/ui-kit'; function MyComponent() { const { pushChainClient } = usePushChainClient(); const { PushChain } = usePushChain(); const send = async () => { if (!pushChainClient) return; // guard: null before wallet connects try { const tx = await pushChainClient.universal.sendTransaction({ to: '0xRecipientAddress', value: PushChain.utils.helpers.parseUnits('0.01', 18), }); await tx.wait(); } catch (err) { // wallet rejection or network error - surface to user, don't swallow } }; return ; } ``` ## Send to an External Chain (Route 2 - via CEA) ```tsx const tx = await pushChainClient.universal.sendTransaction({ to: { address: '0xContractOnEthereum', chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA, }, data: encodedCalldata, funds: { amount: PushChain.utils.helpers.parseUnits('1', 6), // 1 USDT token: PushChain.CONSTANTS.MOVEABLE.TOKEN.ETHEREUM_SEPOLIA.USDT, }, }); ``` ## Route 3 - CEA Identity on Push Chain Add `from: { chain }` to use your CEA on an external chain as the execution origin on Push Chain. `msg.sender` inside the target contract will be the CEA, not the UEA. **Why CEAs exist.** When your Push Chain account first interacts with an external chain (e.g. calling Aave on Ethereum), the protocol deterministically deploys a **Chain Executor Account (CEA)** for you on that chain. This CEA: 1. **Preserves identity** - your actions on Ethereum are traceable to a stable, deterministic address derived from your Push Chain account. 2. **Isolates risk** - the CEA is a dedicated smart account, separate from your home wallet. External-chain actions can’t affect funds outside the CEA. 3. **Enables payload execution** - the CEA is what actually holds assets and executes calldata on the external chain. **When to use Route 3.** Use it when you need to bring state or assets _back_ to Push Chain from a CEA you’ve already deployed - because only the CEA can speak for what happened on that external chain. Example flow - a universal vault: 1. Route 2: vault calls Aave on Ethereum via your **Ethereum CEA** to withdraw USDC. 2. **Route 3**: the vault moves the withdrawn USDC from your Ethereum CEA back to Push Chain (`from: { chain: ETHEREUM_SEPOLIA }`) - `msg.sender` on Push Chain is your Ethereum CEA, which holds the tokens. 3. Route 2 again: Push Chain forwards to a Solana lending protocol via your **Solana CEA**. ```tsx // Bring assets/state back from the Ethereum CEA to Push Chain const tx = await pushChainClient.universal.sendTransaction({ from: { chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA }, // your Ethereum CEA as origin to: '0xVaultOnPushChain', data: PushChain.utils.helpers.encodeTxData({ abi, functionName: 'depositFromEthereum', }), }); await tx.wait(); // Inside 0xVaultOnPushChain: msg.sender === CEA(Ethereum Sepolia, userAddress) // The CEA is the only address that can prove “these assets came from your Ethereum side”. ``` ``` User → Push vault Route 2 → Ethereum CEA → Aave (withdraw USDC) Route 3 ← Ethereum CEA → Push vault (receive USDC, msg.sender = Ethereum CEA) Route 2 → Solana CEA → Solana lending (deposit) ``` > Route 3 isn’t for new outbound flows - use Route 2 for those. Route 3 is the return path from a CEA you’ve already deployed via prior Route 2 activity. ## Prepare + Execute (Cascade Pattern) Use when you need ordered multi-hop execution across chains in one user signature. Always use two or more hops - a single-element cascade adds overhead without benefit. ```tsx const hopA = await pushChainClient.universal.prepareTransaction({ to: { address: '0xContractA', chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA, }, data: callAData, }); const hopB = await pushChainClient.universal.prepareTransaction({ to: { address: '0xContractB', chain: PushChain.CONSTANTS.CHAIN.POLYGON_AMOY }, data: callBData, }); const result = await pushChainClient.universal.executeTransactions( [hopA, hopB], { progressHook: (progress) => setStatus(progress.message), // progress: { id, title, message, level, response, timestamp } } ); if (!result.success) throw new Error('Cascade failed'); // progressHook event IDs (SEND-TX-001, SEND-TX-999-01, etc.): https://push.org/agents/workflows/progress-hook-events.md ``` ## Sign a Message ```tsx const message = new TextEncoder().encode('Hello Push Chain'); // string also accepted; Uint8Array recommended const signature = await pushChainClient.universal.signMessage(message); // returns Uint8Array // To get a hex string: Buffer.from(signature).toString('hex') ``` ## EIP-712 Typed-Data Signing (Cross-Chain Wallets) Use this section when your dApp asks the **connected wallet** to sign an EIP-712 `PaymentRequest` (or any other typed-data payload) that will be verified by a contract on Push Chain. EVM origins only - Solana wallets cannot produce EIP-712 signatures and `signTypedData` will throw `Typed data signing is not supported for Solana`. ### The trap EIP-712's `domain` includes a `chainId` field. MetaMask (and most other injected wallets) enforce that **`domain.chainId` must equal the wallet's currently active chainId** at signing time. So a wallet sitting on Ethereum Sepolia (`11155111`) cannot directly sign a payload whose domain says `chainId: 42101` (Push Chain Donut). The wallet rejects with: ``` Provided chainId "42101" must match the active chainId "11155111" ``` This is correct anti-replay behavior on the wallet's side. It is the friction point that the universal-account model exists to remove. ### The pattern Sign with the wallet's **origin chainId** in the domain — never hardcode Push Chain's chainId. Verify on Push Chain by recovering the signer (which is the user's EOA on their origin chain) and resolving it to their UEA via `IUEAFactory.getUEAForOrigin(...)`. Use `pushChainClient.universal.signTypedData(...)` rather than calling the wallet directly. The SDK routes through the same signer the provider already holds, so it works for any connected EVM wallet (MetaMask, WalletConnect, ethers, viem) without grabbing `window.ethereum`. ```tsx import { usePushChainClient } from '@pushchain/ui-kit'; const { pushChainClient } = usePushChainClient(); if (!pushChainClient) return; // gate on connection - see canonical guard pattern above // 1. Read the wallet's origin chain from the SDK — DO NOT hardcode Push Chain's chainId. const origin = pushChainClient.universal.origin; // { address: '0x...', chain: CHAIN } const originChainId = Number(origin.chain.split(':')[1]); // CHAIN is a CAIP-2 string, e.g. 'eip155:11155111' // 2. Build EIP-712 domain with the wallet's *current* chainId, not Push Chain's. const domain = { name: 'MyApp', version: '1', chainId: originChainId, // the wallet's chain, not Push Chain's verifyingContract: '0xYourContractOnPushChain', }; const types = { PaymentRequest: [ { name: 'recipient', type: 'address' }, { name: 'amount', type: 'uint256' }, { name: 'nonce', type: 'uint256' }, { name: 'originChainId', type: 'uint256' }, ], }; // 3. Sign through the SDK - it delegates to the wallet's signTypedData. const sigHex = await pushChainClient.universal.signTypedData({ domain, types, primaryType: 'PaymentRequest', message: value, }); // 4. The signed payload must also carry the originChainId + origin address so the // Push Chain contract can rebuild the same domain during verification and resolve // the signer's UEA via the factory precompile. const requestForChain = { ...value, originChainId, originAddress: origin.address, signature: sigHex, }; ``` ### Verifying on Push Chain (Solidity) The companion contract must rebuild the EIP-712 domain with `req.originChainId`, recover the signer, and resolve their UEA via `IUEAFactory.getUEAForOrigin`. Skeleton: ```solidity bytes32 domainSeparator = keccak256(abi.encode( keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"), keccak256("MyApp"), keccak256("1"), req.originChainId, // dynamic, NOT block.chainid address(this) )); bytes32 digest = keccak256(abi.encodePacked("\x19\x01", domainSeparator, structHash)); address signer = ECDSA.recover(digest, sig); if (req.originChainId == block.chainid) { require(signer == req.recipient, "bad signer (push-native)"); // Push-native EOA — no UEA } else { (address uea, ) = IUEAFactory(0x00000000000000000000000000000000000000eA).getUEAForOrigin( UniversalAccountId({ chainNamespace: "eip155", chainId: Strings.toString(req.originChainId), owner: abi.encodePacked(signer) }) ); require(uea == req.recipient, "bad signer (cross-chain)"); } ``` > **Full contract pattern with replay protection, ERC-1271 fallback, and anti-patterns:** see [push-contracts skill — Verifying EIP-712 Signatures from Cross-Chain Wallets](https://push.org/agents/skills/push-contracts/SKILL.md#verifying-eip-712-signatures-from-cross-chain-wallets). ### Alternative: ERC-1271 For wallets that implement ERC-1271 (multisigs, account-abstraction wallets, UEAs themselves once they support it), skip the EOA-recover dance and call `IERC1271(recipient).isValidSignature(digest, sig)`. This is more general but the recipient address must be a contract that implements ERC-1271. ### Anti-patterns | Don't | Why | Do | | --- | --- | --- | | Hardcode `chainId: 42101` in the EIP-712 domain when the user signs from MetaMask | Wallet rejects — chainId mismatch with active chain | Read `originChainId` from `pushChainClient.universal.origin.chain` | | Ask the user to switch their wallet to Push Chain just to sign | Defeats the universal-account UX entirely | Sign on origin chain, verify cross-chain via UEAFactory | | Use `block.chainid` inside the contract's EIP-712 domain | Locks the contract to one chain and one signing path | Build domain dynamically from `req.originChainId` | | Sign the EIP-712 digest as a raw `signMessage` to bypass the chainId check | Loses EIP-712 structured display in the wallet (user sees opaque hex), and the verifier must use `eth_sign` style recovery | Use `signTypedData` properly with the right chainId | | Grab `window.ethereum` to sign typed data | Skips the SDK's signer abstraction, only works for injected wallets, breaks for WalletConnect / Push Wallet users | Call `pushChainClient.universal.signTypedData(...)` — same wallet, no provider gymnastics | ## Common Mistakes | Mistake | Fix | | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PushUniversalWalletProvider` wrapped inside `App` instead of at the tree root | Move to `main.tsx` / `index.tsx` - hooks won't resolve without it above every consumer | | Calling `sendTransaction` before `isInitialized === true` | Gate with `isInitialized && pushChainClient` check before any tx trigger | | Treating `signMessage` return value as a string | It returns `Uint8Array` - use `Buffer.from(sig).toString('hex')` if you need a hex string | | Forgetting `'use client'` in Next.js App Router | Add `'use client'` to the file that renders `PushUniversalWalletProvider` | | Expecting `pushChainClient` to be non-null on first render | It's `null` until wallet connects - always use the canonical guard pattern above | | Hooks bind to wrong provider or return stale state (`uid` mismatch across multiple providers) | Pass the **same** `uid` to `usePushChainClient('wallet-a')`, `usePushWalletContext('wallet-a')`, and `