@bosonprotocol/x402-evm 0.1.0-alpha-0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Boson Protocol
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,83 @@
+# @bosonprotocol/x402-evm
+
+EVM-specific calldata builders for the Boson Protocol [`escrow`](https://github.com/bosonprotocol/x402-escrow-schema)
+scheme — the EVM half of the
+[x402B](https://github.com/bosonprotocol/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`](https://github.com/bosonprotocol/core-components)
+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)`.
+
+```ts
+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:
+
+```ts
+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`](../core):
+
+```ts
+import {
+  createErc20ApprovalTx,
+  createPermit2ApprovalTx,
+} from "@bosonprotocol/x402-core/eip712/token-auth";
+```

package/dist/cjs/actions/index.d.ts

@@ -0,0 +1,61 @@
+import { Hex, Address } from 'viem';
+import { FullOfferArgs } from '@bosonprotocol/common';
+
+/**
+ * Minimal calldata payload for a `MetaTransactionsHandlerFacet.executeMetaTransaction`
+ * inner action — what the buyer signs over inside the meta-tx envelope.
+ *
+ * - `functionName` is the Solidity function selector string the protocol uses
+ *   when recovering the buyer's signature (e.g.
+ *   `"createOfferAndCommit((... long tuple ...),address,address,bytes,uint256,...)"`).
+ *   Must match byte-for-byte the literal core-sdk's
+ *   `meta-tx/handler.ts` uses for the same action, since the meta-tx
+ *   typed-data hashes it as a `string`.
+ * - `functionSignature` is the ABI-encoded call data (selector + args) for
+ *   the action itself.
+ */
+interface InnerActionCalldata {
+    functionName: string;
+    functionSignature: Hex;
+}
+/** Minimal viem-style transaction request that any wallet client can submit. */
+interface TxRequest {
+    to: Address;
+    data: Hex;
+    /** Optional ETH value attached to the call. Defaults to 0n; only present for `payable` functions. */
+    value?: bigint;
+}
+
+interface BuildCreateOfferAndCommitCalldataArgs {
+    /**
+     * Full BPIP-10 offer payload, identical in shape to what core-sdk's
+     * `exchanges.iface.encodeCreateOfferAndCommit` accepts. The seller's
+     * `signature` field is embedded inside this struct and is verified
+     * on-chain by `verifyOffer`.
+     */
+    fullOffer: FullOfferArgs;
+}
+/**
+ * Build the `{ functionName, functionSignature }` calldata pair for the
+ * `createOfferAndCommit` inner action. The result feeds
+ * `@bosonprotocol/x402-core/eip712`'s `metaTransactionTypedData`
+ * builder to produce the EIP-712 typed-data the buyer signs.
+ */
+declare function buildCreateOfferAndCommitCalldata(args: BuildCreateOfferAndCommitCalldataArgs): Promise<InnerActionCalldata>;
+
+interface BuildCreateOfferCommitAndRedeemCalldataArgs {
+    /**
+     * Full BPIP-10 offer payload, identical in shape to what core-sdk's
+     * `orchestration.iface.encodeCreateOfferCommitAndRedeem` accepts. The
+     * seller's `signature` field is embedded inside this struct and is
+     * verified on-chain by `verifyOffer`.
+     */
+    fullOffer: FullOfferArgs;
+}
+/**
+ * Build the `{ functionName, functionSignature }` calldata pair for the
+ * `createOfferCommitAndRedeem` inner action.
+ */
+declare function buildCreateOfferCommitAndRedeemCalldata(args: BuildCreateOfferCommitAndRedeemCalldataArgs): Promise<InnerActionCalldata>;
+
+export { type BuildCreateOfferAndCommitCalldataArgs, type BuildCreateOfferCommitAndRedeemCalldataArgs, type InnerActionCalldata, type TxRequest, buildCreateOfferAndCommitCalldata, buildCreateOfferCommitAndRedeemCalldata };

package/dist/cjs/actions/index.js

@@ -0,0 +1,70 @@
+'use strict';
+
+var coreSdk = require('@bosonprotocol/core-sdk');
+
+// src/actions/create-offer-and-commit.ts
+
+// src/internal/metatx-calldata-constants.ts
+var DUMMY_CHAIN_ID = 1;
+var DUMMY_METATX_HANDLER_ADDRESS = "0x0000000000000000000000000000000000000000";
+var DUMMY_NONCE = "0";
+
+// src/internal/web3lib-stub.ts
+var DUMMY_SIGNER_ADDRESS = "0x0000000000000000000000000000000000000001";
+function unreachable(callerTag, method) {
+  return new Error(
+    `${callerTag}: stub Web3LibAdapter.${method}() should never be called. If you see this, core-sdk changed its typed-data-only behavior.`
+  );
+}
+function createCalldataOnlyWeb3LibAdapter(callerTag) {
+  return {
+    uuid: `${callerTag}:stub`,
+    getSignerAddress: () => Promise.resolve(DUMMY_SIGNER_ADDRESS),
+    isSignerContract: () => Promise.resolve(false),
+    getChainId: () => Promise.reject(unreachable(callerTag, "getChainId")),
+    getBalance: () => Promise.reject(unreachable(callerTag, "getBalance")),
+    estimateGas: () => Promise.reject(unreachable(callerTag, "estimateGas")),
+    sendTransaction: () => Promise.reject(unreachable(callerTag, "sendTransaction")),
+    call: () => Promise.reject(unreachable(callerTag, "call")),
+    send: () => Promise.reject(unreachable(callerTag, "send")),
+    getTransactionReceipt: () => Promise.reject(unreachable(callerTag, "getTransactionReceipt")),
+    getCurrentTimeMs: () => Promise.reject(unreachable(callerTag, "getCurrentTimeMs"))
+  };
+}
+
+// src/actions/create-offer-and-commit.ts
+var STUB_CALLER_TAG = "@bosonprotocol/x402-evm:create-offer-and-commit";
+async function buildCreateOfferAndCommitCalldata(args) {
+  const result = await coreSdk.metaTx.handler.signMetaTxCreateOfferAndCommit({
+    web3Lib: createCalldataOnlyWeb3LibAdapter(STUB_CALLER_TAG),
+    metaTxHandlerAddress: DUMMY_METATX_HANDLER_ADDRESS,
+    chainId: DUMMY_CHAIN_ID,
+    nonce: DUMMY_NONCE,
+    createOfferAndCommitArgs: args.fullOffer,
+    returnTypedDataToSign: true
+  });
+  return {
+    functionName: result.functionName,
+    functionSignature: result.functionSignature
+  };
+}
+var STUB_CALLER_TAG2 = "@bosonprotocol/x402-evm:create-offer-commit-and-redeem";
+async function buildCreateOfferCommitAndRedeemCalldata(args) {
+  const result = await coreSdk.metaTx.handler.signMetaTxCreateOfferCommitAndRedeem({
+    web3Lib: createCalldataOnlyWeb3LibAdapter(STUB_CALLER_TAG2),
+    metaTxHandlerAddress: DUMMY_METATX_HANDLER_ADDRESS,
+    chainId: DUMMY_CHAIN_ID,
+    nonce: DUMMY_NONCE,
+    createOfferAndCommitArgs: args.fullOffer,
+    returnTypedDataToSign: true
+  });
+  return {
+    functionName: result.functionName,
+    functionSignature: result.functionSignature
+  };
+}
+
+exports.buildCreateOfferAndCommitCalldata = buildCreateOfferAndCommitCalldata;
+exports.buildCreateOfferCommitAndRedeemCalldata = buildCreateOfferCommitAndRedeemCalldata;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/cjs/actions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/internal/metatx-calldata-constants.ts","../../../src/internal/web3lib-stub.ts","../../../src/actions/create-offer-and-commit.ts","../../../src/actions/create-offer-commit-and-redeem.ts"],"names":["metaTx","STUB_CALLER_TAG"],"mappings":";;;;;;;AAUO,IAAM,cAAA,GAAiB,CAAA;AACvB,IAAM,4BAAA,GAA+B,4CAAA;AACrC,IAAM,WAAA,GAAc,GAAA;;;ACA3B,IAAM,oBAAA,GAAuB,4CAAA;AAE7B,SAAS,WAAA,CAAY,WAAmB,MAAA,EAAuB;AAC7D,EAAA,OAAO,IAAI,KAAA;AAAA,IACT,CAAA,EAAG,SAAS,CAAA,sBAAA,EAAyB,MAAM,CAAA,0FAAA;AAAA,GAE7C;AACF;AAEO,SAAS,iCAAiC,SAAA,EAAmC;AAClF,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,GAAG,SAAS,CAAA,KAAA,CAAA;AAAA,IAClB,gBAAA,EAAkB,MAAM,OAAA,CAAQ,OAAA,CAAQ,oBAAoB,CAAA;AAAA,IAC5D,gBAAA,EAAkB,MAAM,OAAA,CAAQ,OAAA,CAAQ,KAAK,CAAA;AAAA,IAC7C,YAAY,MAAM,OAAA,CAAQ,OAAO,WAAA,CAAY,SAAA,EAAW,YAAY,CAAC,CAAA;AAAA,IACrE,YAAY,MAAM,OAAA,CAAQ,OAAO,WAAA,CAAY,SAAA,EAAW,YAAY,CAAC,CAAA;AAAA,IACrE,aAAa,MAAM,OAAA,CAAQ,OAAO,WAAA,CAAY,SAAA,EAAW,aAAa,CAAC,CAAA;AAAA,IACvE,iBAAiB,MAAM,OAAA,CAAQ,OAAO,WAAA,CAAY,SAAA,EAAW,iBAAiB,CAAC,CAAA;AAAA,IAC/E,MAAM,MAAM,OAAA,CAAQ,OAAO,WAAA,CAAY,SAAA,EAAW,MAAM,CAAC,CAAA;AAAA,IACzD,MAAM,MAAM,OAAA,CAAQ,OAAO,WAAA,CAAY,SAAA,EAAW,MAAM,CAAC,CAAA;AAAA,IACzD,uBAAuB,MAAM,OAAA,CAAQ,OAAO,WAAA,CAAY,SAAA,EAAW,uBAAuB,CAAC,CAAA;AAAA,IAC3F,kBAAkB,MAAM,OAAA,CAAQ,OAAO,WAAA,CAAY,SAAA,EAAW,kBAAkB,CAAC;AAAA,GACnF;AACF;;;ACKA,IAAM,eAAA,GAAkB,iDAAA;AAQxB,eAAsB,kCACpB,IAAA,EAC8B;AAC9B,EAAA,MAAM,MAAA,GAAS,MAAMA,cAAA,CAAO,OAAA,CAAQ,8BAAA,CAA+B;AAAA,IACjE,OAAA,EAAS,iCAAiC,eAAe,CAAA;AAAA,IACzD,oBAAA,EAAsB,4BAAA;AAAA,IACtB,OAAA,EAAS,cAAA;AAAA,IACT,KAAA,EAAO,WAAA;AAAA,IACP,0BAA0B,IAAA,CAAK,SAAA;AAAA,IAC/B,qBAAA,EAAuB;AAAA,GACxB,CAAA;AAED,EAAA,OAAO;AAAA,IACL,cAAc,MAAA,CAAO,YAAA;AAAA,IACrB,mBAAmB,MAAA,CAAO;AAAA,GAC5B;AACF;ACzBA,IAAMC,gBAAAA,GAAkB,wDAAA;AAMxB,eAAsB,wCACpB,IAAA,EAC8B;AAC9B,EAAA,MAAM,MAAA,GAAS,MAAMD,cAAAA,CAAO,OAAA,CAAQ,oCAAA,CAAqC;AAAA,IACvE,OAAA,EAAS,iCAAiCC,gBAAe,CAAA;AAAA,IACzD,oBAAA,EAAsB,4BAAA;AAAA,IACtB,OAAA,EAAS,cAAA;AAAA,IACT,KAAA,EAAO,WAAA;AAAA,IACP,0BAA0B,IAAA,CAAK,SAAA;AAAA,IAC/B,qBAAA,EAAuB;AAAA,GACxB,CAAA;AAED,EAAA,OAAO;AAAA,IACL,cAAc,MAAA,CAAO,YAAA;AAAA,IACrB,mBAAmB,MAAA,CAAO;AAAA,GAC5B;AACF","file":"index.js","sourcesContent":["// Placeholder values for the meta-tx fields the SDK's `signMetaTx*` helpers\n// require but the calldata-builder modules don't care about.\n//\n// The builders delegate the `{ functionName, functionSignature }` pair to\n// `metaTx.handler.signMetaTx*({ returnTypedDataToSign: true })`. The SDK\n// requires `chainId`, `metaTxHandlerAddress`, and `nonce` to build the\n// meta-tx typed-data domain, but those affect only the typed-data portion\n// of the response; the selector literal and ABI-encoded calldata we read\n// back are independent of all three.\n\nexport const DUMMY_CHAIN_ID = 1;\nexport const DUMMY_METATX_HANDLER_ADDRESS = \"0x0000000000000000000000000000000000000000\";\nexport const DUMMY_NONCE = \"0\";\n","// Calldata-only `Web3LibAdapter` for the calldata-builder modules.\n//\n// Core-sdk's `signMetaTx` calls `web3Lib.getSignerAddress()` even in\n// `returnTypedDataToSign: true` mode to fill the message's `from` field.\n// We return a deterministic dummy address; the typed-data message is\n// discarded and only `{ functionName, functionSignature }` is consumed.\n//\n// All signing and transaction methods reject so the stub fails loudly if\n// it ever leaks into a path that needs more than typed-data construction.\n\nimport type { Web3LibAdapter } from \"@bosonprotocol/common\";\n\nconst DUMMY_SIGNER_ADDRESS = \"0x0000000000000000000000000000000000000001\";\n\nfunction unreachable(callerTag: string, method: string): Error {\n  return new Error(\n    `${callerTag}: stub Web3LibAdapter.${method}() should never be called. ` +\n      \"If you see this, core-sdk changed its typed-data-only behavior.\",\n  );\n}\n\nexport function createCalldataOnlyWeb3LibAdapter(callerTag: string): Web3LibAdapter {\n  return {\n    uuid: `${callerTag}:stub`,\n    getSignerAddress: () => Promise.resolve(DUMMY_SIGNER_ADDRESS),\n    isSignerContract: () => Promise.resolve(false),\n    getChainId: () => Promise.reject(unreachable(callerTag, \"getChainId\")),\n    getBalance: () => Promise.reject(unreachable(callerTag, \"getBalance\")),\n    estimateGas: () => Promise.reject(unreachable(callerTag, \"estimateGas\")),\n    sendTransaction: () => Promise.reject(unreachable(callerTag, \"sendTransaction\")),\n    call: () => Promise.reject(unreachable(callerTag, \"call\")),\n    send: () => Promise.reject(unreachable(callerTag, \"send\")),\n    getTransactionReceipt: () => Promise.reject(unreachable(callerTag, \"getTransactionReceipt\")),\n    getCurrentTimeMs: () => Promise.reject(unreachable(callerTag, \"getCurrentTimeMs\")),\n  };\n}\n","// Calldata builder for `ExchangeCommitFacet.createOfferAndCommit` —\n// the \"deferred-redemption\" Boson action (Flow A in\n// docs/boson-impl-02-flows.md).\n//\n// Returns the `{ functionName, functionSignature }` pair the buyer's\n// meta-tx typed-data is built over — same pair the on-chain\n// `MetaTransactionsHandlerFacet` recovers signatures against.\n//\n// Implementation note: rather than hand-pin the `functionName` selector\n// string and call `exchanges.iface.encodeCreateOfferAndCommit` here\n// directly, we delegate the whole pair to\n// `@bosonprotocol/core-sdk`'s `metaTx.handler.signMetaTxCreateOfferAndCommit`\n// in `returnTypedDataToSign: true` mode. That's the same helper the\n// client uses to sign, so signing and verification source the\n// `functionName` literal + `functionSignature` bytes from one place.\n// If a future SDK release changes either, both paths track the change\n// automatically.\n\nimport type { FullOfferArgs } from \"@bosonprotocol/common\";\nimport { metaTx } from \"@bosonprotocol/core-sdk\";\nimport type { Hex } from \"viem\";\n\nimport {\n  DUMMY_CHAIN_ID,\n  DUMMY_METATX_HANDLER_ADDRESS,\n  DUMMY_NONCE,\n} from \"../internal/metatx-calldata-constants.js\";\nimport { createCalldataOnlyWeb3LibAdapter } from \"../internal/web3lib-stub.js\";\nimport type { InnerActionCalldata } from \"../types.js\";\n\nexport interface BuildCreateOfferAndCommitCalldataArgs {\n  /**\n   * Full BPIP-10 offer payload, identical in shape to what core-sdk's\n   * `exchanges.iface.encodeCreateOfferAndCommit` accepts. The seller's\n   * `signature` field is embedded inside this struct and is verified\n   * on-chain by `verifyOffer`.\n   */\n  fullOffer: FullOfferArgs;\n}\n\nconst STUB_CALLER_TAG = \"@bosonprotocol/x402-evm:create-offer-and-commit\";\n\n/**\n * Build the `{ functionName, functionSignature }` calldata pair for the\n * `createOfferAndCommit` inner action. The result feeds\n * `@bosonprotocol/x402-core/eip712`'s `metaTransactionTypedData`\n * builder to produce the EIP-712 typed-data the buyer signs.\n */\nexport async function buildCreateOfferAndCommitCalldata(\n  args: BuildCreateOfferAndCommitCalldataArgs,\n): Promise<InnerActionCalldata> {\n  const result = await metaTx.handler.signMetaTxCreateOfferAndCommit({\n    web3Lib: createCalldataOnlyWeb3LibAdapter(STUB_CALLER_TAG),\n    metaTxHandlerAddress: DUMMY_METATX_HANDLER_ADDRESS,\n    chainId: DUMMY_CHAIN_ID,\n    nonce: DUMMY_NONCE,\n    createOfferAndCommitArgs: args.fullOffer,\n    returnTypedDataToSign: true,\n  });\n\n  return {\n    functionName: result.functionName,\n    functionSignature: result.functionSignature as Hex,\n  };\n}\n","// Calldata builder for `OrchestrationHandlerFacet2.createOfferCommitAndRedeem` —\n// the atomic \"create offer + commit + redeem\" Boson action (Flow B in\n// docs/boson-impl-02-flows.md).\n//\n// Same delegation pattern as `./create-offer-and-commit.ts`: rather than\n// hand-pin the `functionName` selector here, we route the whole\n// `{ functionName, functionSignature }` pair through\n// `@bosonprotocol/core-sdk`'s `metaTx.handler.signMetaTxCreateOfferCommitAndRedeem`\n// in `returnTypedDataToSign: true` mode. That's the same helper the\n// client uses to sign, so signing and verification share one source of\n// truth.\n//\n// Note: the function-argument arity differs from `createOfferAndCommit`\n// (this variant takes `(fullOfferStruct, address offerCreator, bytes\n// sellerSig, uint256 conditionalTokenId)` rather than the\n// deferred-redeem path's longer signature).\n\nimport type { FullOfferArgs } from \"@bosonprotocol/common\";\nimport { metaTx } from \"@bosonprotocol/core-sdk\";\nimport type { Hex } from \"viem\";\n\nimport {\n  DUMMY_CHAIN_ID,\n  DUMMY_METATX_HANDLER_ADDRESS,\n  DUMMY_NONCE,\n} from \"../internal/metatx-calldata-constants.js\";\nimport { createCalldataOnlyWeb3LibAdapter } from \"../internal/web3lib-stub.js\";\nimport type { InnerActionCalldata } from \"../types.js\";\n\nexport interface BuildCreateOfferCommitAndRedeemCalldataArgs {\n  /**\n   * Full BPIP-10 offer payload, identical in shape to what core-sdk's\n   * `orchestration.iface.encodeCreateOfferCommitAndRedeem` accepts. The\n   * seller's `signature` field is embedded inside this struct and is\n   * verified on-chain by `verifyOffer`.\n   */\n  fullOffer: FullOfferArgs;\n}\n\nconst STUB_CALLER_TAG = \"@bosonprotocol/x402-evm:create-offer-commit-and-redeem\";\n\n/**\n * Build the `{ functionName, functionSignature }` calldata pair for the\n * `createOfferCommitAndRedeem` inner action.\n */\nexport async function buildCreateOfferCommitAndRedeemCalldata(\n  args: BuildCreateOfferCommitAndRedeemCalldataArgs,\n): Promise<InnerActionCalldata> {\n  const result = await metaTx.handler.signMetaTxCreateOfferCommitAndRedeem({\n    web3Lib: createCalldataOnlyWeb3LibAdapter(STUB_CALLER_TAG),\n    metaTxHandlerAddress: DUMMY_METATX_HANDLER_ADDRESS,\n    chainId: DUMMY_CHAIN_ID,\n    nonce: DUMMY_NONCE,\n    createOfferAndCommitArgs: args.fullOffer,\n    returnTypedDataToSign: true,\n  });\n\n  return {\n    functionName: result.functionName,\n    functionSignature: result.functionSignature as Hex,\n  };\n}\n"]}

package/dist/cjs/adapters/index.d.ts

@@ -0,0 +1,50 @@
+import { Web3LibAdapter } from '@bosonprotocol/common';
+import { WalletClient, PublicClient } from 'viem';
+
+/** Tagged error thrown by the adapter when `walletClient.sendTransaction` rejects. */
+declare class RelayerSubmitError extends Error {
+    readonly code: RelayerSubmitErrorCode;
+    constructor(code: RelayerSubmitErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Stable identifiers callers can map to their own error-code vocabulary. */
+type RelayerSubmitErrorCode = "INSUFFICIENT_FUNDS_FOR_GAS" | "ONCHAIN_REVERT" | "INTERNAL_ERROR";
+/**
+ * Build the `Web3LibAdapter` that `@bosonprotocol/core-sdk`'s `CoreSDK`
+ * accepts for relayer-driven flows.
+ *
+ * - Writes flow through `walletClient.sendTransaction`; viem errors are
+ *   re-thrown as a tagged `RelayerSubmitError` so the caller can keep
+ *   precise classification (insufficient gas funds vs. on-chain revert
+ *   vs. transport failure).
+ * - Reads (`call`, `getBalance`, `estimateGas`, `getTransactionReceipt`)
+ *   flow through `publicClient`.
+ * - `send` rejects: the relayer never signs typed data through the
+ *   adapter (the buyer already signed off-chain).
+ *
+ * If either client carries a `chain` (viem populates it when the client
+ * was built with an explicit chain) the factory cross-checks its id
+ * against the supplied `chainId` and rejects mismatches up-front, so a
+ * misconfigured pair fails loudly rather than silently targeting the
+ * wrong network.
+ */
+declare function walletClientToWeb3LibAdapter(params: {
+    walletClient: WalletClient;
+    publicClient: PublicClient;
+    chainId: number;
+    /**
+     * Per-call timeout (ms) passed to `publicClient.waitForTransactionReceipt`
+     * inside the adapter's `wait()` method, so callers that route through
+     * core-sdk's `TransactionResponse.wait()` don't hang indefinitely on a
+     * stalled RPC. Defaults to 60s. Direct callers that drive their own
+     * receipt polling can ignore it.
+     */
+    receiptTimeoutMs?: number;
+}): Web3LibAdapter;
+/** Classify a viem error thrown by `walletClient.sendTransaction`. */
+declare function classifyViemSendError(e: unknown): RelayerSubmitError;
+
+declare function createCalldataOnlyWeb3LibAdapter(callerTag: string): Web3LibAdapter;
+
+export { RelayerSubmitError, type RelayerSubmitErrorCode, classifyViemSendError, createCalldataOnlyWeb3LibAdapter, walletClientToWeb3LibAdapter };

package/dist/cjs/adapters/index.js

@@ -0,0 +1,165 @@
+'use strict';
+
+var viem = require('viem');
+
+// src/adapters/viem-relayer.ts
+var RelayerSubmitError = class extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "RelayerSubmitError";
+    this.code = code;
+  }
+};
+var DEFAULT_RECEIPT_TIMEOUT_MS = 6e4;
+function walletClientToWeb3LibAdapter(params) {
+  const { walletClient, publicClient, chainId } = params;
+  const receiptTimeoutMs = params.receiptTimeoutMs ?? DEFAULT_RECEIPT_TIMEOUT_MS;
+  if (walletClient.chain && walletClient.chain.id !== chainId) {
+    throw new RelayerSubmitError(
+      "INTERNAL_ERROR",
+      `walletClient.chain.id (${walletClient.chain.id}) does not match adapter chainId (${chainId})`
+    );
+  }
+  if (publicClient.chain && publicClient.chain.id !== chainId) {
+    throw new RelayerSubmitError(
+      "INTERNAL_ERROR",
+      `publicClient.chain.id (${publicClient.chain.id}) does not match adapter chainId (${chainId})`
+    );
+  }
+  return {
+    uuid: "x402-evm:viem-relayer-adapter",
+    getSignerAddress: async () => {
+      const account = walletClient.account;
+      if (!account) {
+        throw new RelayerSubmitError(
+          "INTERNAL_ERROR",
+          "walletClient has no account; cannot resolve signer address"
+        );
+      }
+      return account.address;
+    },
+    isSignerContract: async () => false,
+    getChainId: async () => chainId,
+    getBalance: async (addressOrName) => {
+      const balance = await publicClient.getBalance({ address: addressOrName });
+      return balance;
+    },
+    estimateGas: async (req) => {
+      const account = walletClient.account;
+      const gas = await publicClient.estimateGas({
+        account: account ?? void 0,
+        to: req.to,
+        data: req.data,
+        value: req.value === void 0 ? void 0 : BigInt(req.value.toString())
+      });
+      return gas;
+    },
+    sendTransaction: async (req) => {
+      const account = walletClient.account;
+      if (!account) {
+        throw new RelayerSubmitError(
+          "INTERNAL_ERROR",
+          "walletClient has no account; cannot send transaction"
+        );
+      }
+      let hash;
+      try {
+        hash = await walletClient.sendTransaction({
+          account,
+          chain: walletClient.chain ?? null,
+          to: req.to,
+          data: req.data,
+          value: req.value === void 0 ? 0n : BigInt(req.value.toString())
+        });
+      } catch (e) {
+        throw classifyViemSendError(e);
+      }
+      return {
+        hash,
+        wait: async (confirmations) => {
+          const receipt = await publicClient.waitForTransactionReceipt({
+            hash,
+            confirmations,
+            timeout: receiptTimeoutMs
+          });
+          return mapReceipt(receipt);
+        }
+      };
+    },
+    call: async (req) => {
+      const result = await publicClient.call({
+        to: req.to,
+        data: req.data
+      });
+      return result.data ?? "0x";
+    },
+    send: async (method) => {
+      throw new RelayerSubmitError(
+        "INTERNAL_ERROR",
+        `x402-evm: relayer adapter does not support RPC method '${method}'; the relayer never signs typed data`
+      );
+    },
+    getTransactionReceipt: async (txHash) => {
+      const receipt = await publicClient.getTransactionReceipt({ hash: txHash });
+      return mapReceipt(receipt);
+    },
+    getCurrentTimeMs: async () => Date.now()
+  };
+}
+function mapReceipt(receipt) {
+  return {
+    from: receipt.from,
+    to: receipt.to ?? "",
+    status: receipt.status === "success" ? 1 : 0,
+    logs: receipt.logs.map((log) => ({ data: log.data, topics: [...log.topics] })),
+    transactionHash: receipt.transactionHash,
+    effectiveGasPrice: receipt.effectiveGasPrice,
+    blockNumber: Number(receipt.blockNumber),
+    gasUsed: receipt.gasUsed
+  };
+}
+function classifyViemSendError(e) {
+  const reason = e instanceof Error ? `sendTransaction failed: ${e.message}` : "sendTransaction failed";
+  if (hasViemCause(e, viem.InsufficientFundsError)) {
+    return new RelayerSubmitError("INSUFFICIENT_FUNDS_FOR_GAS", reason, { cause: e });
+  }
+  if (hasViemCause(e, viem.ExecutionRevertedError) || hasViemCause(e, viem.ContractFunctionRevertedError) || hasViemCause(e, viem.RawContractError)) {
+    return new RelayerSubmitError("ONCHAIN_REVERT", reason, { cause: e });
+  }
+  return new RelayerSubmitError("INTERNAL_ERROR", reason, { cause: e });
+}
+function hasViemCause(e, ctor) {
+  if (e instanceof ctor) return true;
+  if (!(e instanceof viem.BaseError)) return false;
+  return e.walk((err) => err instanceof ctor) !== null;
+}
+
+// src/internal/web3lib-stub.ts
+var DUMMY_SIGNER_ADDRESS = "0x0000000000000000000000000000000000000001";
+function unreachable(callerTag, method) {
+  return new Error(
+    `${callerTag}: stub Web3LibAdapter.${method}() should never be called. If you see this, core-sdk changed its typed-data-only behavior.`
+  );
+}
+function createCalldataOnlyWeb3LibAdapter(callerTag) {
+  return {
+    uuid: `${callerTag}:stub`,
+    getSignerAddress: () => Promise.resolve(DUMMY_SIGNER_ADDRESS),
+    isSignerContract: () => Promise.resolve(false),
+    getChainId: () => Promise.reject(unreachable(callerTag, "getChainId")),
+    getBalance: () => Promise.reject(unreachable(callerTag, "getBalance")),
+    estimateGas: () => Promise.reject(unreachable(callerTag, "estimateGas")),
+    sendTransaction: () => Promise.reject(unreachable(callerTag, "sendTransaction")),
+    call: () => Promise.reject(unreachable(callerTag, "call")),
+    send: () => Promise.reject(unreachable(callerTag, "send")),
+    getTransactionReceipt: () => Promise.reject(unreachable(callerTag, "getTransactionReceipt")),
+    getCurrentTimeMs: () => Promise.reject(unreachable(callerTag, "getCurrentTimeMs"))
+  };
+}
+
+exports.RelayerSubmitError = RelayerSubmitError;
+exports.classifyViemSendError = classifyViemSendError;
+exports.createCalldataOnlyWeb3LibAdapter = createCalldataOnlyWeb3LibAdapter;
+exports.walletClientToWeb3LibAdapter = walletClientToWeb3LibAdapter;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map