@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";