@pushchain/core 4.0.14-alpha.0 → 5.1.0

package/src/lib/orchestrator/payload-builders.d.ts

@@ -1,6 +1,215 @@
-import { ExecuteParams, MultiCall } from './orchestrator.types';
+import { CHAIN } from '../constants/enums';
+import type { ExecuteParams, MultiCall, UniversalOutboundTxRequest, SvmExecutePayloadFields } from './orchestrator.types';
 export declare function buildExecuteMulticall({ execute, ueaAddress, logger, }: {
     execute: ExecuteParams;
     ueaAddress: `0x${string}`;
     logger?: (msg: string) => void;
 }): MultiCall[];
+/**
+ * Build CEA multicall payload for outbound transactions
+ * Format: UEA_MULTICALL_SELECTOR + abi.encode(Multicall[])
+ *
+ * The CEA contract checks for UEA_MULTICALL_SELECTOR (0x2cc2842d) at the
+ * start of the payload to route to _handleMulticall. Without this prefix,
+ * the CEA treats it as a single call and fails with InvalidRecipient.
+ *
+ * @param multicalls - Array of multicall operations to execute on external chain
+ * @returns UEA_MULTICALL_SELECTOR + ABI-encoded Multicall[] array
+ */
+export declare function buildCeaMulticallPayload(multicalls: MultiCall[]): `0x${string}`;
+/**
+ * Build an ABI-encoded UniversalPayload struct for inbound relay (Route 3 CEA→Push).
+ *
+ * The relay and Push Chain gateway expect the payload parameter of sendUniversalTxToUEA
+ * to be a full UniversalPayload struct: (address to, uint256 value, bytes data, uint256 gasLimit,
+ * uint256 maxFeePerGas, uint256 maxPriorityFeePerGas, uint256 nonce, uint256 deadline, uint8 vType).
+ *
+ * The `data` field inside the struct contains the multicall payload (with UEA_MULTICALL_SELECTOR prefix)
+ * which the UEA uses to execute calls on Push Chain.
+ *
+ * @param multicallData - The multicall payload (selector + abi.encode(Multicall[]))
+ * @param opts - Optional overrides for gasLimit, nonce, deadline
+ * @returns ABI-encoded UniversalPayload struct
+ */
+export declare function buildInboundUniversalPayload(multicallData: `0x${string}`, opts?: {
+    gasLimit?: bigint;
+    nonce?: bigint;
+    deadline?: bigint;
+}): `0x${string}`;
+/**
+ * Build a single call as CEA multicall payload
+ *
+ * @param target - Target contract address
+ * @param value - Native value to send
+ * @param data - Calldata to execute
+ * @returns Encoded payload with selector prefix
+ */
+export declare function buildSingleCeaCall(target: `0x${string}`, value: bigint, data: `0x${string}`): `0x${string}`;
+/**
+ * Build approve + interact pattern for ERC20 operations on external chains
+ *
+ * @param tokenAddress - ERC20 token address
+ * @param spender - Address to approve (e.g., DEX router)
+ * @param amount - Amount to approve
+ * @param interactCall - The interaction call (e.g., swap)
+ * @returns Array of multicall operations
+ */
+export declare function buildApproveAndInteract(tokenAddress: `0x${string}`, spender: `0x${string}`, amount: bigint, interactCall: MultiCall): MultiCall[];
+/**
+ * Build sendUniversalTxFromCEA call for CEA → Push routing (Route 3)
+ *
+ * @param gatewayAddress - UniversalGateway address on external chain
+ * @param recipient - Recipient on Push Chain (usually UEA)
+ * @param token - Token address (address(0) for native)
+ * @param amount - Amount to send
+ * @param payload - Payload for Push Chain execution
+ * @param revertRecipient - Address to receive funds on revert
+ * @param signatureData - Signature data (usually empty for CEA calls)
+ * @param nativeValue - Native value to send with the call
+ * @returns MultiCall for sendUniversalTxFromCEA
+ */
+export declare function buildSendUniversalTxFromCEA(gatewayAddress: `0x${string}`, recipient: `0x${string}`, token: `0x${string}`, amount: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`, signatureData?: `0x${string}`, nativeValue?: bigint): MultiCall;
+/**
+ * Build sendUniversalTxToUEA call for CEA self-call (Route 3)
+ *
+ * The CEA contract has a `sendUniversalTxToUEA(token, amount, payload, revertRecipient)` function
+ * that is only callable via self-call (multicall with to=CEA, value=0).
+ * It internally calls `gateway.sendUniversalTxFromCEA(...)`.
+ *
+ * @param ceaAddress - CEA contract address (multicall target = self)
+ * @param token - Token address (address(0) for native)
+ * @param amount - Amount to send
+ * @param payload - Payload for Push Chain execution
+ * @param revertRecipient - Address to receive funds on revert (on source chain)
+ * @returns MultiCall for sendUniversalTxToUEA (to=CEA, value=0)
+ */
+export declare function buildSendUniversalTxToUEA(ceaAddress: `0x${string}`, token: `0x${string}`, amount: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`): MultiCall;
+/**
+ * Build UniversalOutboundTxRequest for Push Chain outbound
+ *
+ * @param target - LEGACY/DUMMY: Any non-zero address for contract compatibility.
+ *                 This value is NOT used by the relay to determine the actual destination.
+ *                 The relay determines the destination from the PRC-20 token's SOURCE_CHAIN_NAMESPACE.
+ *                 Will be removed in future contract upgrades.
+ * @param prc20Token - PRC20 token address to burn (or address(0) for native)
+ * @param amount - Amount to burn
+ * @param gasLimit - Gas limit for fee calculation
+ * @param payload - CEA multicall payload
+ * @param revertRecipient - Address to receive funds on revert
+ * @returns UniversalOutboundTxRequest object
+ */
+export declare function buildOutboundRequest(target: `0x${string}`, prc20Token: `0x${string}`, amount: bigint, gasLimit: bigint, payload: `0x${string}`, revertRecipient: `0x${string}`): UniversalOutboundTxRequest;
+/**
+ * Build native transfer multicall
+ *
+ * @param to - Recipient address
+ * @param value - Native value to transfer
+ * @returns MultiCall for native transfer
+ */
+export declare function buildNativeTransfer(to: `0x${string}`, value: bigint): MultiCall;
+/**
+ * Build ERC20 transfer multicall
+ *
+ * @param tokenAddress - ERC20 token address
+ * @param to - Recipient address
+ * @param amount - Amount to transfer
+ * @returns MultiCall for ERC20 transfer
+ */
+export declare function buildErc20Transfer(tokenAddress: `0x${string}`, to: `0x${string}`, amount: bigint): MultiCall;
+/**
+ * Build a single-element MultiCall[] for an ERC20 withdrawal (Flow 2.2).
+ * Wraps buildErc20Transfer so callers of Route 2 (executeUoaToCea) don't
+ * need to manually construct the transfer() multicall step.
+ *
+ * @param tokenAddress - ERC20 token contract on the external chain
+ * @param recipientAddress - Withdrawal recipient on the external chain
+ * @param amount - Amount of tokens to transfer
+ * @returns MultiCall[] with a single ERC20 transfer call
+ */
+export declare function buildErc20WithdrawalMulticall(tokenAddress: `0x${string}`, recipientAddress: `0x${string}`, amount: bigint): MultiCall[];
+/**
+ * Build the 4-byte migration payload for CEA upgrade (Migration flow).
+ * Returns exactly MIGRATION_SELECTOR — no Multicall wrapping.
+ *
+ * @returns 4-byte hex string `0xcac656d6`
+ */
+export declare function buildMigrationPayload(): `0x${string}`;
+/**
+ * Check if an address is the zero address
+ */
+export declare function isZeroAddress(address: `0x${string}`): boolean;
+/**
+ * Build approval multicalls + sendUniversalTxOutbound call for Push Chain.
+ *
+ * Extracted from executeUoaToCea to be reusable in cascade composition.
+ * Handles two cases:
+ * - gasToken === prc20Token: single approval for burnAmount + gasFee
+ * - gasToken !== prc20Token: two separate approvals
+ *
+ * @param opts.prc20Token - PRC-20 token to burn
+ * @param opts.gasToken - Gas token for fee payment
+ * @param opts.burnAmount - Amount to burn
+ * @param opts.gasFee - Gas fee amount
+ * @param opts.gatewayPcAddress - UniversalGatewayPC precompile address
+ * @param opts.outboundRequest - The outbound request struct
+ * @returns Array of MultiCall operations (approvals + outbound call)
+ */
+export declare function buildOutboundApprovalAndCall(opts: {
+    prc20Token: `0x${string}`;
+    gasToken: `0x${string}`;
+    burnAmount: bigint;
+    gasFee: bigint;
+    nativeValueForGas?: bigint;
+    gatewayPcAddress: `0x${string}`;
+    outboundRequest: UniversalOutboundTxRequest;
+}): MultiCall[];
+/**
+ * Check if a chain targets the SVM (Solana) virtual machine
+ */
+export declare function isSvmChain(chain: CHAIN): boolean;
+/**
+ * Validate a Solana address in 0x-prefixed hex format.
+ * Must be exactly 32 bytes (0x + 64 hex chars = 66 characters total).
+ */
+export declare function isValidSolanaHexAddress(address: string): boolean;
+/**
+ * Encode SVM execute payload for CPI execution on Solana.
+ *
+ * Binary format (matching the Solana gateway contract expectation):
+ * ```
+ * [accounts_count: 4 bytes (u32 BE)]
+ * [account[i].pubkey: 32 bytes][account[i].is_writable: 1 byte] × N
+ * [ix_data_length: 4 bytes (u32 BE)]
+ * [ix_data: variable bytes]
+ * [instruction_id: 1 byte (u8)]
+ * [target_program: 32 bytes]
+ * ```
+ *
+ * @param fields - SVM execute payload fields
+ * @returns 0x-prefixed hex string of the encoded payload
+ */
+export declare function encodeSvmExecutePayload(fields: SvmExecutePayloadFields): `0x${string}`;
+/**
+ * Encode the SVM CEA-to-UEA payload for Route 3 on Solana.
+ *
+ * This builds a `send_universal_tx_to_uea` instruction wrapped in
+ * `encodeSvmExecutePayload`, targeting the gateway program as a self-call.
+ *
+ * Borsh ixData layout:
+ * ```
+ * [discriminator: 8 bytes (SHA-256("global:send_universal_tx_to_uea")[0..8])]
+ * [token: 32 bytes (PublicKey::default for SOL, mint pubkey for SPL)]
+ * [amount: 8 bytes (u64 LE)]
+ * [payload_len: 4 bytes (u32 LE)]
+ * [payload_bytes: variable]
+ * [revert_recipient: 32 bytes (PublicKey)]
+ * ```
+ */
+export declare function encodeSvmCeaToUeaPayload({ gatewayProgramHex, drainAmount, tokenMintHex, extraPayload, revertRecipientHex, }: {
+    gatewayProgramHex: `0x${string}`;
+    drainAmount: bigint;
+    tokenMintHex?: `0x${string}`;
+    extraPayload?: Uint8Array;
+    /** 32-byte Solana pubkey as 0x-hex for revert recipient (required) */
+    revertRecipientHex: `0x${string}`;
+}): `0x${string}`;