Skip to main content
processBytecode is the required callback for production widget integrations. It receives bytecode transactions from Pods and must:
  1. Batch all legs on the same chainId into one atomic wallet submission (never one tx per leg).
  2. Ask the wallet to sign and submit the batch.
  3. Wait for on-chain confirmation.
  4. Emit lifecycle statuses back to the widget.
Sending each item in bytecodes[] as a separate transaction can leave async actions stuck in PENDING with funds in escrow. See Executing Bytecode.

Payload Shape

Required Success Status Path

Emit, in order:
  1. HOST_ACK
  2. SIGNATURE_PROMPTED
  3. TX_SUBMITTED
  4. TX_CONFIRMED
  5. TX_FINALIZED
txHash should be included on TX_SUBMITTED and TX_CONFIRMED when available.

Required Error Statuses

  • SIGNATURE_DECLINED for user-rejected signatures (4001, ACTION_REJECTED)
  • SIGNATURE_ERROR for non-rejection failures before tx submission
  • TX_REVERTED for reverted on-chain transactions
  • TX_FAILED for unsupported failure paths where revert reason is unavailable

Optional Advanced Statuses

  • TX_REPLACED
  • TX_DROPPED
  • SWAP_CROSSCHAIN_DESTINATION_CONFIRMED

Minimal Host Implementation

Group legs by chainId, then submit one batched transaction per chain (smart-wallet calls, EIP-7702 executeBatch, or equivalent):

Compatibility Fallback

If processBytecode is not provided, SDK falls back to window.parent.postMessage(...) (REQUEST_SIGNATURE). Use this only when your host already implements that message bridge. For new integrations, prefer explicit processBytecode.

Operational Recommendations

  1. Log clientTxId and wallet tx hash together in your backend.
  2. Batch all legs per chainId into one atomic submission — never one sendTransaction per leg.
  3. Enforce chain checks before requesting signatures.
  4. Persist failures and rejections for support/audit trails.