@bosonprotocol/x402-evm

EVM-specific calldata builders for the Boson Protocol escrow scheme — the EVM half of the x402B implementation.

See docs/boson-impl-00-overview.md in the monorepo root for context.

Scope

This package ships only what the x402B escrow scheme needs beyond what @bosonprotocol/core-sdk already provides:

| Subpath | Purpose | |---|---| | ./actions | Inner-action ABI encoding for the commit step. buildCreateOfferAndCommitCalldata (Flow A, deferred-redeem) and buildCreateOfferCommitAndRedeemCalldata (Flow B, atomic commit+redeem) each return the { functionName, functionSignature } pair that feeds the meta-tx typed-data the buyer signs. Both delegate to metaTx.handler.signMetaTx*({ returnTypedDataToSign: true }) in core-sdk so the selector literal and ABI encoding come from the same source the buyer signs against — no drift between signing and verification. | | ./adapters | viem ↔ Web3LibAdapter bridges. walletClientToWeb3LibAdapter wraps a viem WalletClient + PublicClient so coreSdk.executeMetaTransaction(...) (the unified entrypoint for the outer envelope) can submit through viem-configured transports. Submission failures surface as a tagged RelayerSubmitError so callers can preserve precise error codes (INSUFFICIENT_FUNDS_FOR_GAS, ONCHAIN_REVERT, INTERNAL_ERROR). |

The outer meta-tx envelope (executeMetaTransaction / executeMetaTransactionWithTokenTransferAuthorization) is not re-implemented here. Submit through core-sdk's coreSdk.executeMetaTransaction(metaTxParams), which accepts an optional transferAuthorizations array and routes to the right on-chain entrypoint internally.

What this package deliberately does NOT ship

Boson's meta-tx and direct-call flows for every other action are already fully covered by @bosonprotocol/core-sdk. Reach for it directly:

Meta-tx signing (default) — coreSdk.signMetaTxXxx

Each signMetaTxXxx method on a configured CoreSDK instance uses the bespoke EIP-712 type the protocol's MetaTransactionsHandlerFacet expects for that action family (MetaTxExchange for redeem/complete/cancel/revoke/raise/retract/escalate, MetaTxDisputeResolution for resolveDispute, generic MetaTransaction for createOfferAndCommit and friends). It returns SignedMetaTx = { functionName, functionSignature, r, s, v } — exactly the buyer-side payload the X-PAYMENT header carries, ready for the facilitator to submit via coreSdk.executeMetaTransaction(metaTxParams).

const signed = await coreSdk.signMetaTxRedeemVoucher({ nonce, exchangeId });
// signed = { functionName: "redeemVoucher(uint256)", functionSignature, r, s, v }

coreSdk fills web3Lib, metaTxHandlerAddress, and chainId from the SDK instance, so the call site stays minimal. The standalone metaTx.handler.signMetaTxXxx exports are also available if you need them without a CoreSDK instance.

Direct on-chain submission — coreSdk.xxx

For the on-chain channel (buyer paying their own gas, or the "onchain" fallback in nextActions[i].channels), use the same CoreSDK mixin methods that handle signing and submission in one call:

const tx = await coreSdk.redeemVoucher(exchangeId);
// → also: completeExchange, cancelVoucher, revokeVoucher,
//          raiseDispute, retractDispute, escalateDispute, resolveDispute
await tx.wait();

Pass returnTxInfo: true to get back a TransactionRequest for manual submission (e.g. when handing it to a relayer or batcher) instead of broadcasting through the SDK's web3Lib.

Token-side approve / Permit2 approval

Calldata builders for the buyer's pre-approval transaction (used by tokenAuthStrategy: "none") and the one-time Permit2 contract approval live in @bosonprotocol/x402-core:

import {
  createErc20ApprovalTx,
  createPermit2ApprovalTx,
} from "@bosonprotocol/x402-core/eip712/token-auth";