@bosonprotocol/x402-server 0.1.0-alpha-0

package/dist/cjs/index.js

@@ -0,0 +1,1643 @@
+'use strict';
+
+var coreSdk = require('@bosonprotocol/core-sdk');
+var x402Actions = require('@bosonprotocol/x402-actions');
+var escrow = require('@bosonprotocol/x402-core/schemes/escrow');
+var zod = require('zod');
+var eip712 = require('@bosonprotocol/x402-core/eip712');
+var x402Evm = require('@bosonprotocol/x402-evm');
+var stateMachine = require('@bosonprotocol/x402-core/state-machine');
+
+// src/server.ts
+
+// src/onchain/web3lib-read-stub.ts
+var TAG = "x402-server:read";
+function unreachable(method) {
+  return new Error(
+    `${TAG}: stub Web3LibAdapter.${method}() should never be called from the read-only CoreSDK instance. If you see this, a non-subgraph code path leaked through.`
+  );
+}
+function createReadOnlyWeb3LibStub() {
+  return {
+    uuid: `${TAG}:stub`,
+    getSignerAddress: () => Promise.reject(unreachable("getSignerAddress")),
+    isSignerContract: () => Promise.reject(unreachable("isSignerContract")),
+    getChainId: () => Promise.reject(unreachable("getChainId")),
+    getBalance: () => Promise.reject(unreachable("getBalance")),
+    estimateGas: () => Promise.reject(unreachable("estimateGas")),
+    sendTransaction: () => Promise.reject(unreachable("sendTransaction")),
+    call: () => Promise.reject(unreachable("call")),
+    send: () => Promise.reject(unreachable("send")),
+    getTransactionReceipt: () => Promise.reject(unreachable("getTransactionReceipt")),
+    getCurrentTimeMs: () => Promise.reject(unreachable("getCurrentTimeMs"))
+  };
+}
+function buildPaymentRequirements(args) {
+  const {
+    offer,
+    asset,
+    amount,
+    tokenAuthStrategies,
+    recipientId,
+    maxTimeoutSeconds,
+    fulfillment,
+    network,
+    escrow: escrow$1,
+    channelRegistry
+  } = args;
+  const actions = x402Actions.deriveInitialNextActions(channelRegistry);
+  const requirements = {
+    scheme: "escrow",
+    network,
+    asset,
+    amount,
+    escrowAddress: escrow$1,
+    recipientId,
+    maxTimeoutSeconds,
+    offer,
+    tokenAuthStrategies: [...tokenAuthStrategies],
+    ...fulfillment !== void 0 ? { fulfillment } : {},
+    actions
+  };
+  return escrow.escrowPaymentRequirementsSchema.parse(requirements);
+}
+var STUB_CALLER_TAG = "@bosonprotocol/x402-server:sign-full-offer";
+async function signFullOffer({
+  fullOffer,
+  signer,
+  escrow,
+  chainId
+}) {
+  const web3Lib = buildForwardingAdapter(signer, chainId);
+  const result = await coreSdk.exchanges.handler.signFullOffer({
+    fullOfferArgsUnsigned: fullOffer,
+    contractAddress: escrow,
+    chainId,
+    web3Lib
+  });
+  return {
+    fullOffer,
+    sellerSig: result.signature,
+    creator: signer.address
+  };
+}
+function buildForwardingAdapter(signer, chainId) {
+  const unreachable2 = (method) => Promise.reject(
+    new Error(
+      `${STUB_CALLER_TAG}: Web3LibAdapter.${method}() called unexpectedly \u2014 sign-full-offer is a signing-only path.`
+    )
+  );
+  return {
+    uuid: `${STUB_CALLER_TAG}:forward`,
+    getSignerAddress: () => Promise.resolve(signer.address),
+    isSignerContract: () => Promise.resolve(false),
+    getChainId: () => Promise.resolve(chainId),
+    send: async (method, params) => {
+      if (method !== "eth_signTypedData_v4") {
+        throw new Error(`${STUB_CALLER_TAG}: unexpected RPC method: ${method}`);
+      }
+      const [, json] = params;
+      if (typeof json !== "string") {
+        throw new Error(`${STUB_CALLER_TAG}: eth_signTypedData_v4 payload is not a JSON string`);
+      }
+      const td = JSON.parse(json);
+      return signer.signTypedData({
+        domain: td.domain,
+        types: td.types,
+        primaryType: td.primaryType,
+        message: td.message
+      });
+    },
+    getBalance: () => unreachable2("getBalance"),
+    estimateGas: () => unreachable2("estimateGas"),
+    sendTransaction: () => unreachable2("sendTransaction"),
+    call: () => unreachable2("call"),
+    getTransactionReceipt: () => unreachable2("getTransactionReceipt"),
+    getCurrentTimeMs: () => unreachable2("getCurrentTimeMs")
+  };
+}
+var httpUrlSchema = zod.z.string().url().refine((url) => url.startsWith("http://") || url.startsWith("https://"), {
+  message: "must be an http(s) URL"
+});
+var sellerSignerSchema = zod.z.object({
+  address: escrow.addressSchema,
+  // `SellerSigner.signTypedData` is typed `Promise<Hex>` in the TS
+  // interface — tighten the zod return wrapper to match so a signer
+  // that resolves to a non-hex string fails loudly at call time
+  // rather than silently producing a bad `BosonOfferRef.sellerSig`.
+  signTypedData: zod.z.function().args(zod.z.unknown()).returns(zod.z.promise(escrow.hexSchema))
+}).passthrough();
+var exchangeReaderShallowSchema = zod.z.object({
+  read: zod.z.function().args(zod.z.string()).returns(zod.z.unknown())
+}).passthrough();
+var coreSdkReadShallowSchema = zod.z.object({
+  getFunds: zod.z.function().args(zod.z.unknown()).returns(zod.z.unknown()),
+  getSellersByAddress: zod.z.function().args(zod.z.unknown()).returns(zod.z.unknown()),
+  getBuyers: zod.z.function().args(zod.z.unknown()).returns(zod.z.unknown())
+}).passthrough();
+var fulfillmentChannelShallowSchema = zod.z.object({
+  id: zod.z.string().min(1),
+  validate: zod.z.function(),
+  onCommit: zod.z.function()
+}).passthrough();
+var x402bServerConfigSchema = zod.z.object({
+  network: escrow.evmNetworkSchema,
+  chainId: zod.z.number().int().positive(),
+  escrow: escrow.addressSchema,
+  signer: sellerSignerSchema,
+  facilitator: zod.z.object({
+    url: httpUrlSchema
+  }).strict(),
+  channelRegistry: x402Actions.channelRegistryZodSchema,
+  exchangeReader: exchangeReaderShallowSchema.optional(),
+  subgraphUrl: httpUrlSchema.optional(),
+  coreSdkRead: coreSdkReadShallowSchema.optional(),
+  exchangeFulfillmentOptionStore: zod.z.instanceof(Map).optional(),
+  fulfillmentRecoveryStore: zod.z.instanceof(Map).optional(),
+  fulfillmentChannels: zod.z.array(fulfillmentChannelShallowSchema).superRefine((channels, ctx) => {
+    const seen = /* @__PURE__ */ new Set();
+    const duplicates = /* @__PURE__ */ new Set();
+    for (const c of channels) {
+      if (seen.has(c.id)) duplicates.add(c.id);
+      seen.add(c.id);
+    }
+    if (duplicates.size > 0) {
+      ctx.addIssue({
+        code: zod.z.ZodIssueCode.custom,
+        message: `fulfillmentChannels has duplicate id(s): ${[...duplicates].join(", ")}`
+      });
+    }
+  }).optional()
+}).strict().superRefine((cfg, ctx) => {
+  const networkChainId = Number(cfg.network.split(":")[1]);
+  if (networkChainId !== cfg.chainId) {
+    ctx.addIssue({
+      code: zod.z.ZodIssueCode.custom,
+      path: ["chainId"],
+      message: `chainId (${cfg.chainId}) must match network (${cfg.network})`
+    });
+  }
+});
+function assertChannelRegistryEscrowMatch(config) {
+  if (config.escrow.toLowerCase() !== config.channelRegistry.escrow.toLowerCase()) {
+    throw new Error(
+      `x402-server config: escrow (${config.escrow}) does not match channelRegistry.escrow (${config.channelRegistry.escrow})`
+    );
+  }
+}
+
+// src/facilitator/errors.ts
+var FacilitatorHttpError = class extends Error {
+  constructor(message, init) {
+    super(message, init.cause !== void 0 ? { cause: init.cause } : void 0);
+    this.name = "FacilitatorHttpError";
+    this.code = init.code;
+    if (init.status !== void 0) this.status = init.status;
+    if (init.facilitatorCode !== void 0) this.facilitatorCode = init.facilitatorCode;
+  }
+};
+
+// src/facilitator/client.ts
+function createFacilitatorClient(opts) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  if (fetchImpl === void 0) {
+    throw new Error(
+      "createFacilitatorClient: no `fetch` implementation available. Pass `opts.fetch` explicitly."
+    );
+  }
+  const baseUrl = opts.url.replace(/\/+$/, "");
+  const baseHeaders = { "content-type": "application/json", ...opts.headers ?? {} };
+  const post = async (path, body, validate) => {
+    let res;
+    try {
+      res = await fetchImpl(`${baseUrl}${path}`, {
+        method: "POST",
+        headers: baseHeaders,
+        body: JSON.stringify(body)
+      });
+    } catch (cause) {
+      throw new FacilitatorHttpError(`facilitator network error (${path})`, {
+        code: "NETWORK_ERROR",
+        cause
+      });
+    }
+    let text;
+    try {
+      text = await res.text();
+    } catch (cause) {
+      throw new FacilitatorHttpError(`facilitator response body could not be read (${path})`, {
+        code: "BAD_RESPONSE_BODY",
+        status: res.status,
+        cause
+      });
+    }
+    let parsed;
+    try {
+      parsed = text.length === 0 ? null : JSON.parse(text);
+    } catch (cause) {
+      throw new FacilitatorHttpError(`facilitator returned non-JSON body (${path})`, {
+        code: "BAD_RESPONSE_BODY",
+        status: res.status,
+        cause
+      });
+    }
+    if (!res.ok) {
+      if (res.status === 400 && isFailureBranch(parsed) && validate(parsed)) {
+        return parsed;
+      }
+      const facilitatorCode = extractFacilitatorCode(parsed);
+      throw new FacilitatorHttpError(
+        `facilitator HTTP ${res.status} (${path}): ${reasonString(parsed) ?? text}`,
+        {
+          code: "BAD_HTTP_STATUS",
+          status: res.status,
+          ...facilitatorCode !== void 0 ? { facilitatorCode } : {}
+        }
+      );
+    }
+    if (!validate(parsed)) {
+      throw new FacilitatorHttpError(`facilitator returned unexpected body shape (${path})`, {
+        code: "BAD_RESPONSE_BODY",
+        status: res.status
+      });
+    }
+    return parsed;
+  };
+  return {
+    verify: (input) => post("/verify", input, isVerifyResult),
+    settle: (input) => post("/settle", input, isSettleResult),
+    performAction: (input) => post(
+      `/perform-action?action=${encodeURIComponent(input.action)}`,
+      input,
+      isPerformActionResult
+    )
+  };
+}
+function isObject(v) {
+  return v !== null && typeof v === "object";
+}
+function isFailureBranch(v) {
+  return isObject(v) && v.ok === false && typeof v.code === "string" && typeof v.reason === "string";
+}
+function isVerifyResult(parsed) {
+  if (!isObject(parsed)) return false;
+  if (parsed.ok === true) return true;
+  return isFailureBranch(parsed);
+}
+function isSettleResult(parsed) {
+  if (!isObject(parsed)) return false;
+  if (parsed.ok === true) {
+    return typeof parsed.exchangeId === "string" && typeof parsed.txHash === "string";
+  }
+  return isFailureBranch(parsed);
+}
+function isPerformActionResult(parsed) {
+  if (!isObject(parsed)) return false;
+  if (parsed.ok === true) {
+    if (typeof parsed.txHash !== "string") return false;
+    if (parsed.newExchangeState !== void 0 && typeof parsed.newExchangeState !== "string") {
+      return false;
+    }
+    if (parsed.newDisputeState !== void 0 && typeof parsed.newDisputeState !== "string") {
+      return false;
+    }
+    return true;
+  }
+  return isFailureBranch(parsed);
+}
+function extractFacilitatorCode(body) {
+  if (body === null || typeof body !== "object") return void 0;
+  const code = body.code;
+  return typeof code === "string" ? code : void 0;
+}
+function reasonString(body) {
+  if (body === null || typeof body !== "object") return void 0;
+  const reason = body.reason;
+  return typeof reason === "string" ? reason : void 0;
+}
+
+// src/internal/facilitator-endpoints.ts
+var COMMIT_ACTION_IDS = /* @__PURE__ */ new Set([
+  "boson-createOfferAndCommit",
+  "boson-createOfferCommitAndRedeem"
+]);
+function facilitatorEndpointFor(actionId, facilitatorUrl) {
+  const base = facilitatorUrl.replace(/\/+$/, "");
+  if (COMMIT_ACTION_IDS.has(actionId)) {
+    return `${base}/settle`;
+  }
+  return `${base}/perform-action?action=${encodeURIComponent(actionId)}`;
+}
+function stampFacilitatorEndpoints(next, facilitatorUrl) {
+  return next.map((entry) => {
+    if (!entry.channels.includes("facilitator")) {
+      return entry;
+    }
+    if (entry.endpoints?.facilitator !== void 0) {
+      return entry;
+    }
+    return {
+      ...entry,
+      endpoints: {
+        ...entry.endpoints,
+        facilitator: facilitatorEndpointFor(entry.id, facilitatorUrl)
+      }
+    };
+  });
+}
+
+// src/handlers/next-actions.ts
+function emitNextActions(input, registry, facilitatorUrl) {
+  const derived = input.exchangeState === x402Actions.ExchangeState.DISPUTED ? x402Actions.deriveNextActions(
+    {
+      exchangeId: input.exchangeId,
+      exchangeState: x402Actions.ExchangeState.DISPUTED,
+      disputeState: input.disputeState
+    },
+    registry
+  ) : x402Actions.deriveNextActions(
+    { exchangeId: input.exchangeId, exchangeState: input.exchangeState },
+    registry
+  );
+  if (facilitatorUrl === void 0) {
+    return derived;
+  }
+  return {
+    ...derived,
+    next: stampFacilitatorEndpoints(derived.next, facilitatorUrl)
+  };
+}
+
+// src/handlers/types.ts
+function handlerOk(body) {
+  return { ok: true, status: 200, body };
+}
+function plainHandlerOk(body) {
+  return { ok: true, status: 200, body };
+}
+function handlerErr(status, code, reason, details) {
+  const body = { code, reason };
+  if (details !== void 0) body.details = details;
+  return { ok: false, status, body };
+}
+function decodeXPaymentHeader(header) {
+  if (header === void 0 || header === null || header.length === 0) {
+    return { ok: false, code: "MISSING_HEADER", reason: "X-PAYMENT header is missing" };
+  }
+  const padded = base64UrlToBase64(header);
+  let decoded;
+  try {
+    if (typeof atob === "function") {
+      const binary = atob(padded);
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+      decoded = new TextDecoder().decode(bytes);
+    } else {
+      decoded = Buffer.from(padded, "base64").toString("utf8");
+    }
+  } catch (e) {
+    return { ok: false, code: "INVALID_BASE64", reason: e.message };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch (e) {
+    return { ok: false, code: "INVALID_JSON", reason: e.message };
+  }
+  try {
+    const payload = escrow.parseEscrowPaymentPayload(parsed);
+    return { ok: true, payload };
+  } catch (e) {
+    return { ok: false, code: "INVALID_PAYLOAD", reason: e.message };
+  }
+}
+function base64UrlToBase64(input) {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - normalized.length % 4);
+  return normalized + padding;
+}
+async function validatePaymentPayload(args) {
+  const { payload, requirements } = args;
+  if (payload.scheme !== "escrow" || requirements.scheme !== "escrow") {
+    return failure(1, "SCHEME_MISMATCH", "scheme", "escrow", payload.scheme);
+  }
+  if (payload.network !== requirements.network) {
+    return failure(2, "NETWORK_MISMATCH", "network", requirements.network, payload.network);
+  }
+  if (!deepEqual(payload.payload.offerRef.fullOffer, requirements.offer.fullOffer)) {
+    return failure(
+      3,
+      "FULL_OFFER_MISMATCH",
+      "payload.offerRef.fullOffer",
+      "<requirements.offer.fullOffer>",
+      "<payload.offerRef.fullOffer>"
+    );
+  }
+  if (payload.payload.offerRef.sellerSig !== requirements.offer.sellerSig) {
+    return failure(
+      4,
+      "SELLER_SIG_MISMATCH",
+      "payload.offerRef.sellerSig",
+      requirements.offer.sellerSig,
+      payload.payload.offerRef.sellerSig
+    );
+  }
+  const advertisedActions = requirements.actions.next.map((entry) => entry.id);
+  if (!advertisedActions.includes(payload.payload.action)) {
+    return failure(
+      5,
+      "ACTION_NOT_IN_REQUIREMENTS",
+      "payload.action",
+      advertisedActions,
+      payload.payload.action
+    );
+  }
+  if (!requirements.tokenAuthStrategies.includes(payload.payload.tokenAuthStrategy)) {
+    return failure(
+      6,
+      "TOKEN_AUTH_NOT_IN_REQUIREMENTS",
+      "payload.tokenAuthStrategy",
+      requirements.tokenAuthStrategies,
+      payload.payload.tokenAuthStrategy
+    );
+  }
+  const calldataResult = await checkFunctionSignatureAndCalldataEquality(payload);
+  if (calldataResult !== null) return calldataResult;
+  if (payload.payload.buyer.toLowerCase() !== payload.payload.metaTx.from.toLowerCase()) {
+    return failure(
+      8,
+      "BAD_META_TX_SIGNATURE",
+      "payload.metaTx.from",
+      payload.payload.buyer,
+      payload.payload.metaTx.from
+    );
+  }
+  let recovered;
+  try {
+    recovered = await eip712.recoverMetaTransactionSigner({
+      chainId: args.chainId,
+      verifyingContract: requirements.escrowAddress,
+      message: {
+        nonce: BigInt(payload.payload.metaTx.nonce),
+        from: payload.payload.metaTx.from,
+        contractAddress: requirements.escrowAddress,
+        functionName: payload.payload.metaTx.functionName,
+        functionSignature: payload.payload.metaTx.functionSignature
+      },
+      signature: encodeRsv(payload.payload.metaTx.sig)
+    });
+  } catch (e) {
+    return failure(
+      8,
+      "BAD_META_TX_SIGNATURE",
+      "payload.metaTx.sig",
+      "recoverable ECDSA signature",
+      payload.payload.metaTx.sig,
+      e.message
+    );
+  }
+  if (recovered.toLowerCase() !== payload.payload.buyer.toLowerCase()) {
+    return failure(
+      8,
+      "BAD_META_TX_SIGNATURE",
+      "payload.metaTx.sig",
+      payload.payload.buyer,
+      recovered
+    );
+  }
+  const strategyResult = checkTokenAuthRules(payload, requirements, args.now);
+  if (strategyResult !== null) return strategyResult;
+  const fulfillmentResult = checkFulfillment(payload, requirements, args.validateFulfillmentData);
+  if (fulfillmentResult !== null) return fulfillmentResult;
+  return { ok: true };
+}
+async function checkFunctionSignatureAndCalldataEquality(payload) {
+  const action = payload.payload.action;
+  const buildCalldata = action === "boson-createOfferAndCommit" ? x402Evm.buildCreateOfferAndCommitCalldata : action === "boson-createOfferCommitAndRedeem" ? x402Evm.buildCreateOfferCommitAndRedeemCalldata : void 0;
+  if (!buildCalldata) {
+    return failure(
+      7,
+      "CALLDATA_MISMATCH",
+      "payload.action",
+      "boson-createOfferAndCommit | boson-createOfferCommitAndRedeem",
+      action,
+      "rule-7 calldata reconstruction is only defined for commit-time actions"
+    );
+  }
+  const fullOfferWithSig = {
+    ...payload.payload.offerRef.fullOffer,
+    committer: payload.payload.buyer,
+    signature: payload.payload.offerRef.sellerSig
+  };
+  let expected;
+  try {
+    expected = await buildCalldata({ fullOffer: fullOfferWithSig });
+  } catch (e) {
+    return failure(
+      7,
+      "CALLDATA_MISMATCH",
+      "payload.metaTx.functionSignature",
+      void 0,
+      void 0,
+      e.message
+    );
+  }
+  if (expected.functionName !== payload.payload.metaTx.functionName) {
+    return failure(
+      7,
+      "CALLDATA_MISMATCH",
+      "payload.metaTx.functionName",
+      expected.functionName,
+      payload.payload.metaTx.functionName
+    );
+  }
+  if (expected.functionSignature.toLowerCase() !== payload.payload.metaTx.functionSignature.toLowerCase()) {
+    return failure(
+      7,
+      "CALLDATA_MISMATCH",
+      "payload.metaTx.functionSignature",
+      expected.functionSignature,
+      payload.payload.metaTx.functionSignature
+    );
+  }
+  return null;
+}
+function checkTokenAuthRules(payload, requirements, nowSec) {
+  const strategy = payload.payload.tokenAuthStrategy;
+  const tokenAuth = payload.payload.tokenAuth;
+  const now = nowSec ?? Math.floor(Date.now() / 1e3);
+  const horizon = now + requirements.maxTimeoutSeconds;
+  if (strategy === "none") {
+    if (tokenAuth !== void 0) {
+      return failure(
+        9,
+        "TOKEN_AUTH_UNEXPECTED",
+        "payload.tokenAuth",
+        "undefined (strategy=none)",
+        tokenAuth.kind
+      );
+    }
+    return null;
+  }
+  if (tokenAuth === void 0) {
+    return failure(
+      9,
+      "TOKEN_AUTH_MISSING",
+      "payload.tokenAuth",
+      `<${strategy} authorization>`,
+      "undefined"
+    );
+  }
+  if (tokenAuth.kind !== strategy) {
+    return failure(9, "TOKEN_AUTH_MISSING", "payload.tokenAuth.kind", strategy, tokenAuth.kind);
+  }
+  switch (tokenAuth.kind) {
+    case "erc3009": {
+      if (tokenAuth.data.value !== requirements.amount) {
+        return failure(
+          9,
+          "TOKEN_AUTH_AMOUNT_MISMATCH",
+          "payload.tokenAuth.data.value",
+          requirements.amount,
+          tokenAuth.data.value
+        );
+      }
+      if (tokenAuth.data.to.toLowerCase() !== requirements.escrowAddress.toLowerCase()) {
+        return failure(
+          9,
+          "TOKEN_AUTH_RECIPIENT_MISMATCH",
+          "payload.tokenAuth.data.to",
+          requirements.escrowAddress,
+          tokenAuth.data.to
+        );
+      }
+      if (tokenAuth.data.validBefore > horizon) {
+        return failure(
+          9,
+          "TOKEN_AUTH_DEADLINE_EXCEEDED",
+          "payload.tokenAuth.data.validBefore",
+          `<= ${horizon}`,
+          tokenAuth.data.validBefore
+        );
+      }
+      return null;
+    }
+    case "permit": {
+      if (tokenAuth.data.value !== requirements.amount) {
+        return failure(
+          10,
+          "TOKEN_AUTH_AMOUNT_MISMATCH",
+          "payload.tokenAuth.data.value",
+          requirements.amount,
+          tokenAuth.data.value
+        );
+      }
+      if (tokenAuth.data.spender.toLowerCase() !== requirements.escrowAddress.toLowerCase()) {
+        return failure(
+          10,
+          "TOKEN_AUTH_SPENDER_MISMATCH",
+          "payload.tokenAuth.data.spender",
+          requirements.escrowAddress,
+          tokenAuth.data.spender
+        );
+      }
+      if (tokenAuth.data.deadline > horizon) {
+        return failure(
+          10,
+          "TOKEN_AUTH_DEADLINE_EXCEEDED",
+          "payload.tokenAuth.data.deadline",
+          `<= ${horizon}`,
+          tokenAuth.data.deadline
+        );
+      }
+      return null;
+    }
+    case "permit2": {
+      if (tokenAuth.data.permitted.amount !== requirements.amount) {
+        return failure(
+          11,
+          "TOKEN_AUTH_AMOUNT_MISMATCH",
+          "payload.tokenAuth.data.permitted.amount",
+          requirements.amount,
+          tokenAuth.data.permitted.amount
+        );
+      }
+      if (tokenAuth.data.permitted.token.toLowerCase() !== requirements.asset.toLowerCase()) {
+        return failure(
+          11,
+          "TOKEN_AUTH_TOKEN_MISMATCH",
+          "payload.tokenAuth.data.permitted.token",
+          requirements.asset,
+          tokenAuth.data.permitted.token
+        );
+      }
+      if (tokenAuth.data.spender.toLowerCase() !== requirements.escrowAddress.toLowerCase()) {
+        return failure(
+          11,
+          "TOKEN_AUTH_SPENDER_MISMATCH",
+          "payload.tokenAuth.data.spender",
+          requirements.escrowAddress,
+          tokenAuth.data.spender
+        );
+      }
+      if (tokenAuth.data.deadline > horizon) {
+        return failure(
+          11,
+          "TOKEN_AUTH_DEADLINE_EXCEEDED",
+          "payload.tokenAuth.data.deadline",
+          `<= ${horizon}`,
+          tokenAuth.data.deadline
+        );
+      }
+      return null;
+    }
+    default:
+      return failure(
+        9,
+        "TOKEN_AUTH_UNKNOWN_STRATEGY",
+        "payload.tokenAuth.kind",
+        "erc3009 | permit | permit2",
+        tokenAuth.kind
+      );
+  }
+}
+function checkFulfillment(payload, requirements, validator) {
+  const required = requirements.fulfillment?.required === true;
+  const carried = payload.fulfillment;
+  if (carried === void 0) {
+    return required ? failure(13, "FULFILLMENT_REQUIRED", "payload.fulfillment", "<option>", "undefined") : null;
+  }
+  const advertised = requirements.fulfillment?.options ?? [];
+  const matched = advertised.find((option) => option.id === carried.option);
+  if (!matched) {
+    return failure(
+      13,
+      "FULFILLMENT_OPTION_NOT_ADVERTISED",
+      "payload.fulfillment.option",
+      advertised.map((o) => o.id),
+      carried.option
+    );
+  }
+  const action = payload.payload.action;
+  if (action === "boson-createOfferCommitAndRedeem") {
+    if (carried.data === void 0) {
+      return failure(
+        13,
+        "FULFILLMENT_DATA_REQUIRED",
+        "payload.fulfillment.data",
+        matched.schema ?? "null",
+        "undefined",
+        "atomic createOfferCommitAndRedeem requires fulfillment.data at commit time"
+      );
+    }
+    if (validator !== void 0) {
+      const result = validator(matched.id, carried.data);
+      if (!result.ok) {
+        return failure(
+          13,
+          "FULFILLMENT_DATA_INVALID",
+          "payload.fulfillment.data",
+          matched.schema,
+          carried.data,
+          result.reason
+        );
+      }
+    }
+    return null;
+  }
+  if (carried.data !== void 0) {
+    return failure(
+      13,
+      "FULFILLMENT_DATA_UNEXPECTED",
+      "payload.fulfillment.data",
+      "undefined",
+      carried.data,
+      "two-step boson-createOfferAndCommit defers fulfillment.data to the redeem POST body"
+    );
+  }
+  return null;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const ao = a;
+  const bo = b;
+  const aKeys = Object.keys(ao);
+  const bKeys = Object.keys(bo);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(bo, k)) return false;
+    if (!deepEqual(ao[k], bo[k])) return false;
+  }
+  return true;
+}
+function encodeRsv(sig) {
+  if (sig.v !== 0 && sig.v !== 1 && sig.v !== 27 && sig.v !== 28) {
+    throw new Error("signature v must be 0, 1, 27, or 28");
+  }
+  const r = sig.r.replace(/^0x/, "").padStart(64, "0");
+  const s = sig.s.replace(/^0x/, "").padStart(64, "0");
+  const normalizedV = sig.v === 0 || sig.v === 1 ? sig.v + 27 : sig.v;
+  const v = normalizedV.toString(16).padStart(2, "0");
+  return `0x${r}${s}${v}`;
+}
+function failure(rule, code, field, expected, got, reason) {
+  const out = { ok: false, rule, code };
+  if (field !== void 0) out.field = field;
+  if (expected !== void 0) out.expected = expected;
+  if (got !== void 0) out.got = got;
+  if (reason !== void 0) out.reason = reason;
+  return out;
+}
+function verifyExchangeSnapshot(snapshot, expected) {
+  if (snapshot === null) {
+    return { ok: false, code: "EXCHANGE_NOT_FOUND" };
+  }
+  if (snapshot.state !== expected.state) {
+    return {
+      ok: false,
+      code: "STATE_MISMATCH",
+      field: "state",
+      expected: expected.state,
+      got: snapshot.state
+    };
+  }
+  if (expected.state === x402Actions.ExchangeState.DISPUTED) {
+    if (snapshot.disputeState !== expected.disputeState) {
+      return {
+        ok: false,
+        code: "DISPUTE_STATE_MISMATCH",
+        field: "disputeState",
+        expected: expected.disputeState,
+        got: snapshot.disputeState
+      };
+    }
+  }
+  if (snapshot.seller.toLowerCase() !== expected.seller.toLowerCase()) {
+    return {
+      ok: false,
+      code: "SELLER_MISMATCH",
+      field: "seller",
+      expected: expected.seller,
+      got: snapshot.seller
+    };
+  }
+  if (snapshot.exchangeToken.toLowerCase() !== expected.exchangeToken.toLowerCase()) {
+    return {
+      ok: false,
+      code: "TOKEN_MISMATCH",
+      field: "exchangeToken",
+      expected: expected.exchangeToken,
+      got: snapshot.exchangeToken
+    };
+  }
+  if (snapshot.price !== expected.price) {
+    return {
+      ok: false,
+      code: "PRICE_MISMATCH",
+      field: "price",
+      expected: expected.price,
+      got: snapshot.price
+    };
+  }
+  return { ok: true };
+}
+async function verifyExchange(reader, exchangeId, expected, options = {}) {
+  const attempts = Math.max(1, Math.floor(options.attempts ?? 3));
+  const delayMs = Math.max(0, Math.floor(options.delayMs ?? 50));
+  let result = { ok: false, code: "EXCHANGE_NOT_FOUND" };
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const snapshot = await reader.read(exchangeId);
+    result = verifyExchangeSnapshot(snapshot, expected);
+    if (result.ok || !isRetryableVerifyResult(result) || attempt === attempts) {
+      return result;
+    }
+    if (delayMs > 0) {
+      await delay(delayMs);
+    }
+  }
+  return result;
+}
+function isRetryableVerifyResult(result) {
+  return !result.ok && (result.code === "EXCHANGE_NOT_FOUND" || result.code === "STATE_MISMATCH" || result.code === "DISPUTE_STATE_MISMATCH");
+}
+async function delay(ms) {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+// src/handlers/commit-and-redeem.ts
+async function handleCommit(input, ctx) {
+  return await handleCommitImpl(input, ctx, {
+    expectedAction: "boson-createOfferAndCommit",
+    expectedState: x402Actions.ExchangeState.COMMITTED
+  });
+}
+async function handleCommitAndRedeem(input, ctx) {
+  return await handleCommitImpl(input, ctx, {
+    expectedAction: "boson-createOfferCommitAndRedeem",
+    expectedState: x402Actions.ExchangeState.REDEEMED
+  });
+}
+async function handleCommitImpl(input, ctx, expected) {
+  const decoded = decodeXPaymentHeader(input.paymentHeader);
+  if (!decoded.ok) {
+    const status = decoded.code === "MISSING_HEADER" ? 402 : 400;
+    return handlerErr(status, decoded.code, decoded.reason);
+  }
+  if (decoded.payload.payload.action !== expected.expectedAction) {
+    return handlerErr(
+      400,
+      "ACTION_ROUTE_MISMATCH",
+      `handler expected action ${expected.expectedAction}, got ${decoded.payload.payload.action}`,
+      {
+        expected: expected.expectedAction,
+        got: decoded.payload.payload.action
+      }
+    );
+  }
+  const channels = ctx.config.fulfillmentChannels ?? [];
+  const channelById = new Map(channels.map((c) => [c.id, c]));
+  const validation = await validatePaymentPayload({
+    payload: decoded.payload,
+    requirements: input.requirements,
+    chainId: ctx.config.chainId,
+    validateFulfillmentData: (option, data) => {
+      const channel = channelById.get(option);
+      if (channel === void 0) {
+        return {
+          ok: false,
+          reason: `fulfillment.option '${option}' has no registered channel adapter on this server`
+        };
+      }
+      try {
+        return channel.validate(data);
+      } catch (e) {
+        return { ok: false, reason: e instanceof Error ? e.message : String(e) };
+      }
+    }
+  });
+  if (!validation.ok) {
+    return handlerErr(400, validation.code, validation.reason ?? `rule ${validation.rule} failed`, {
+      rule: validation.rule,
+      field: validation.field,
+      expected: validation.expected,
+      got: validation.got
+    });
+  }
+  let settleResult;
+  try {
+    settleResult = await ctx.facilitator.settle({
+      scheme: "escrow",
+      network: input.requirements.network,
+      payload: decoded.payload,
+      requirements: input.requirements
+    });
+  } catch (e) {
+    if (e instanceof FacilitatorHttpError) {
+      return handlerErr(502, "FACILITATOR_UNREACHABLE", e.message, {
+        code: e.code,
+        status: e.status,
+        facilitatorCode: e.facilitatorCode
+      });
+    }
+    throw e;
+  }
+  if (!settleResult.ok) {
+    return handlerErr(502, "FACILITATOR_REJECTED", settleResult.reason, {
+      facilitatorCode: settleResult.code
+    });
+  }
+  const verifyResult = await verifyExchange(
+    ctx.exchangeReader,
+    settleResult.exchangeId,
+    buildExpectedFromRequirements(input.requirements, expected.expectedState)
+  );
+  if (!verifyResult.ok) {
+    return handlerErr(
+      502,
+      `STATE_VERIFY_${verifyResult.code}`,
+      "post-settle state verification failed",
+      {
+        exchangeId: settleResult.exchangeId,
+        txHash: settleResult.txHash,
+        field: verifyResult.field,
+        expected: verifyResult.expected,
+        got: verifyResult.got
+      }
+    );
+  }
+  if (expected.expectedState === x402Actions.ExchangeState.COMMITTED) {
+    ctx.exchangeFulfillmentOptionStore.set(
+      settleResult.exchangeId,
+      input.requirements.fulfillment?.options.map((option) => option.id) ?? []
+    );
+  }
+  const warnings = [];
+  if (expected.expectedState === x402Actions.ExchangeState.REDEEMED && decoded.payload.fulfillment !== void 0 && decoded.payload.fulfillment.data !== void 0) {
+    const pending = {
+      exchangeId: settleResult.exchangeId,
+      option: decoded.payload.fulfillment.option,
+      data: decoded.payload.fulfillment.data,
+      redeemer: decoded.payload.payload.buyer,
+      recordedAt: Date.now()
+    };
+    ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, pending);
+    const channel = channelById.get(decoded.payload.fulfillment.option);
+    if (channel === void 0) {
+      const reason = "no channel adapter is registered";
+      ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+        ...pending,
+        error: reason
+      });
+      warnings.push({
+        code: "FULFILLMENT_COMMIT_DEFERRED",
+        reason: "atomic redeem succeeded on-chain, but no channel adapter is registered",
+        details: {
+          exchangeId: settleResult.exchangeId,
+          option: decoded.payload.fulfillment.option,
+          error: reason
+        }
+      });
+    } else {
+      try {
+        await channel.onCommit(settleResult.exchangeId, decoded.payload.fulfillment.data);
+        ctx.fulfillmentRecoveryStore.delete(settleResult.exchangeId);
+      } catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+          ...pending,
+          error: reason
+        });
+        warnings.push({
+          code: "FULFILLMENT_COMMIT_DEFERRED",
+          reason: "atomic redeem succeeded on-chain, but the channel adapter rejected the data",
+          details: {
+            exchangeId: settleResult.exchangeId,
+            option: decoded.payload.fulfillment.option,
+            error: reason
+          }
+        });
+      }
+    }
+  }
+  const nextActions = emitNextActions(
+    {
+      exchangeId: settleResult.exchangeId,
+      exchangeState: expected.expectedState
+    },
+    ctx.config.channelRegistry,
+    ctx.config.facilitator.url
+  );
+  return handlerOk({
+    exchangeId: settleResult.exchangeId,
+    txHash: settleResult.txHash,
+    nextActions,
+    ...warnings.length > 0 ? { warnings } : {}
+  });
+}
+function buildExpectedFromRequirements(requirements, state) {
+  return {
+    state,
+    seller: requirements.offer.creator,
+    exchangeToken: requirements.asset,
+    price: requirements.amount
+  };
+}
+async function handlePerformAction(action, input, ctx) {
+  const reference = await ctx.exchangeReader.read(input.exchangeId);
+  if (reference === null) {
+    return handlerErr(
+      502,
+      "STATE_VERIFY_EXCHANGE_NOT_FOUND",
+      "pre-action exchange reference could not be read",
+      { action, exchangeId: input.exchangeId }
+    );
+  }
+  let result;
+  try {
+    result = await ctx.facilitator.performAction({
+      network: ctx.config.network,
+      escrowAddress: ctx.config.escrow,
+      exchangeId: input.exchangeId,
+      action,
+      signedPayload: input.signedPayload
+    });
+  } catch (e) {
+    if (e instanceof FacilitatorHttpError) {
+      return handlerErr(502, "FACILITATOR_UNREACHABLE", e.message, {
+        code: e.code,
+        status: e.status,
+        facilitatorCode: e.facilitatorCode
+      });
+    }
+    throw e;
+  }
+  if (!result.ok) {
+    return handlerErr(502, "FACILITATOR_REJECTED", result.reason, {
+      facilitatorCode: result.code
+    });
+  }
+  const postState = stateMachine.ACTION_POST_STATE[action];
+  const expected = {
+    state: postState.exchange,
+    ...postState.dispute !== void 0 ? { disputeState: postState.dispute } : {},
+    seller: reference.seller,
+    exchangeToken: reference.exchangeToken,
+    price: reference.price
+  };
+  const verifyResult = await verifyExchange(ctx.exchangeReader, input.exchangeId, expected);
+  if (!verifyResult.ok) {
+    return handlerErr(
+      502,
+      `STATE_VERIFY_${verifyResult.code}`,
+      "post-action state verification failed",
+      {
+        action,
+        exchangeId: input.exchangeId,
+        txHash: result.txHash,
+        field: verifyResult.field,
+        expected: verifyResult.expected,
+        got: verifyResult.got
+      }
+    );
+  }
+  const nextActions = postState.exchange === x402Actions.ExchangeState.DISPUTED && postState.dispute !== void 0 ? emitNextActions(
+    {
+      exchangeId: input.exchangeId,
+      exchangeState: x402Actions.ExchangeState.DISPUTED,
+      disputeState: postState.dispute
+    },
+    ctx.config.channelRegistry,
+    ctx.config.facilitator.url
+  ) : emitNextActions(
+    {
+      exchangeId: input.exchangeId,
+      exchangeState: postState.exchange
+    },
+    ctx.config.channelRegistry,
+    ctx.config.facilitator.url
+  );
+  return handlerOk({ txHash: result.txHash, nextActions });
+}
+async function handleRedeem(input, ctx) {
+  let redeemer;
+  try {
+    redeemer = x402Evm.decodeSignedPayload(input.signedPayload).from;
+  } catch (e) {
+    return handlerErr(
+      400,
+      "SIGNED_PAYLOAD_DECODE_FAILED",
+      e instanceof Error ? e.message : "signedPayload could not be decoded"
+    );
+  }
+  let resolvedChannel;
+  if (input.fulfillment !== void 0) {
+    const advertisedOptions = ctx.exchangeFulfillmentOptionStore.get(input.exchangeId);
+    if (advertisedOptions !== void 0 && !advertisedOptions.includes(input.fulfillment.option)) {
+      return handlerErr(
+        400,
+        "FULFILLMENT_OPTION_NOT_ADVERTISED",
+        `fulfillment.option '${input.fulfillment.option}' was not advertised for this exchange`,
+        { option: input.fulfillment.option, advertised: advertisedOptions }
+      );
+    }
+    const channels = ctx.config.fulfillmentChannels;
+    if (channels === void 0) {
+      return handlerErr(
+        400,
+        "FULFILLMENT_CHANNELS_NOT_CONFIGURED",
+        "server received redeem-time fulfillment data but has no fulfillmentChannels registered"
+      );
+    }
+    const channel = channels.find((c) => c.id === input.fulfillment.option);
+    if (channel === void 0) {
+      return handlerErr(
+        400,
+        "FULFILLMENT_OPTION_UNKNOWN",
+        `fulfillment.option '${input.fulfillment.option}' is not registered with the server`,
+        { option: input.fulfillment.option, registered: channels.map((c) => c.id) }
+      );
+    }
+    let validation;
+    try {
+      validation = channel.validate(input.fulfillment.data);
+    } catch (e) {
+      return handlerErr(400, "FULFILLMENT_DATA_INVALID", errorMessage(e), {
+        option: input.fulfillment.option
+      });
+    }
+    if (!validation.ok) {
+      return handlerErr(400, "FULFILLMENT_DATA_INVALID", validation.reason, {
+        option: input.fulfillment.option
+      });
+    }
+    resolvedChannel = channel;
+  }
+  const result = await handlePerformAction("boson-redeem", input, ctx);
+  if (!result.ok) return result;
+  let warning;
+  if (resolvedChannel !== void 0 && input.fulfillment !== void 0) {
+    const pending = {
+      exchangeId: input.exchangeId,
+      option: input.fulfillment.option,
+      data: input.fulfillment.data,
+      redeemer,
+      recordedAt: Date.now()
+    };
+    ctx.fulfillmentRecoveryStore.set(input.exchangeId, pending);
+    try {
+      await resolvedChannel.onCommit(input.exchangeId, input.fulfillment.data);
+      ctx.fulfillmentRecoveryStore.delete(input.exchangeId);
+    } catch (e) {
+      const reason = errorMessage(e);
+      ctx.fulfillmentRecoveryStore.set(input.exchangeId, { ...pending, error: reason });
+      warning = {
+        code: "FULFILLMENT_UPDATE_DEFERRED",
+        reason: "redeem succeeded on-chain, but the server could not persist the fulfillment update",
+        details: {
+          exchangeId: input.exchangeId,
+          option: input.fulfillment.option,
+          error: reason
+        }
+      };
+    }
+  }
+  ctx.exchangeFulfillmentOptionStore.delete(input.exchangeId);
+  if (warning !== void 0) {
+    return {
+      ...result,
+      body: {
+        ...result.body,
+        warnings: [...result.body.warnings ?? [], warning]
+      }
+    };
+  }
+  return result;
+}
+function errorMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+var handleComplete = (input, ctx) => handlePerformAction("boson-completeExchange", input, ctx);
+var handleDisputeRaise = (input, ctx) => handlePerformAction("boson-raiseDispute", input, ctx);
+var handleDisputeResolve = (input, ctx) => handlePerformAction("boson-resolveDispute", input, ctx);
+var handleDisputeRetract = (input, ctx) => handlePerformAction("boson-retractDispute", input, ctx);
+var handleDisputeEscalate = (input, ctx) => handlePerformAction("boson-escalateDispute", input, ctx);
+var DECIMAL_UINT_RE = escrow.DECIMAL_UINT;
+var ADDRESS_RE = escrow.ADDRESS;
+var HEX_BYTES_RE = /^0x([0-9a-fA-F]{2})*$/;
+
+// src/handlers/resolve-entity.ts
+async function resolveEntityId(coreSdk, input) {
+  const address = input.address.toLowerCase();
+  let sellers = [];
+  let buyers = [];
+  try {
+    [sellers, buyers] = await Promise.all([
+      input.role === "buyer" ? Promise.resolve([]) : coreSdk.getSellersByAddress(address),
+      input.role === "seller" ? Promise.resolve([]) : coreSdk.getBuyers({ buyersFilter: { wallet: address } })
+    ]);
+  } catch (e) {
+    return {
+      ok: false,
+      code: "SUBGRAPH_FAILURE",
+      reason: e instanceof Error ? e.message : "subgraph lookup failed"
+    };
+  }
+  const sellerIds = sellers.map((s) => s.id);
+  const buyerIds = buyers.map((b) => b.id);
+  if (input.role === "seller") {
+    if (sellerIds.length === 0) {
+      return {
+        ok: false,
+        code: "NOT_FOUND",
+        reason: `no seller entity found for address ${address}`
+      };
+    }
+    if (sellerIds.length > 1) {
+      return {
+        ok: false,
+        code: "AMBIGUOUS",
+        reason: `address ${address} resolves to multiple seller entities (ids ${sellerIds.join(", ")}); pass entityId to disambiguate`,
+        sellerIds
+      };
+    }
+    return { ok: true, entityId: sellerIds[0], role: "seller" };
+  }
+  if (input.role === "buyer") {
+    if (buyerIds.length === 0) {
+      return {
+        ok: false,
+        code: "NOT_FOUND",
+        reason: `no buyer entity found for address ${address}`
+      };
+    }
+    if (buyerIds.length > 1) {
+      return {
+        ok: false,
+        code: "AMBIGUOUS",
+        reason: `address ${address} resolves to multiple buyer entities (ids ${buyerIds.join(", ")}); pass entityId to disambiguate`,
+        buyerIds
+      };
+    }
+    return { ok: true, entityId: buyerIds[0], role: "buyer" };
+  }
+  const totalMatches = sellerIds.length + buyerIds.length;
+  if (totalMatches === 0) {
+    return {
+      ok: false,
+      code: "NOT_FOUND",
+      reason: `no seller or buyer entity found for address ${address}`
+    };
+  }
+  if (totalMatches > 1) {
+    return {
+      ok: false,
+      code: "AMBIGUOUS",
+      reason: `address ${address} resolves to ${describeMatches(sellerIds, buyerIds)}; pass role and/or entityId to disambiguate`,
+      ...sellerIds.length > 0 ? { sellerIds } : {},
+      ...buyerIds.length > 0 ? { buyerIds } : {}
+    };
+  }
+  if (sellerIds.length === 1) return { ok: true, entityId: sellerIds[0], role: "seller" };
+  return { ok: true, entityId: buyerIds[0], role: "buyer" };
+}
+function describeMatches(sellerIds, buyerIds) {
+  const parts = [];
+  if (sellerIds.length > 0) {
+    parts.push(
+      sellerIds.length === 1 ? `seller (id ${sellerIds[0]})` : `${sellerIds.length} sellers (ids ${sellerIds.join(", ")})`
+    );
+  }
+  if (buyerIds.length > 0) {
+    parts.push(
+      buyerIds.length === 1 ? `buyer (id ${buyerIds[0]})` : `${buyerIds.length} buyers (ids ${buyerIds.join(", ")})`
+    );
+  }
+  return parts.join(" and ");
+}
+
+// src/handlers/withdraw-funds.ts
+async function handleWithdrawFunds(input, ctx) {
+  let entityId;
+  let role;
+  if ("entityId" in input) {
+    if (!DECIMAL_UINT_RE.test(input.entityId)) {
+      return handlerErr(
+        400,
+        "INVALID_ENTITY_ID",
+        `entityId must be a decimal uint256 string, got "${input.entityId}"`
+      );
+    }
+    entityId = input.entityId;
+  } else {
+    if (!ADDRESS_RE.test(input.address)) {
+      return handlerErr(
+        400,
+        "INVALID_ADDRESS",
+        `address must be a 20-byte 0x-prefixed hex string, got "${input.address}"`
+      );
+    }
+    const resolved = await resolveEntityId(ctx.coreSdkRead, {
+      address: input.address,
+      ...input.role !== void 0 ? { role: input.role } : {}
+    });
+    if (!resolved.ok) {
+      const status = resolved.code === "NOT_FOUND" ? 404 : resolved.code === "AMBIGUOUS" ? 409 : 502;
+      const details = resolved.code === "AMBIGUOUS" ? {
+        ...resolved.sellerIds !== void 0 ? { sellerIds: resolved.sellerIds } : {},
+        ...resolved.buyerIds !== void 0 ? { buyerIds: resolved.buyerIds } : {}
+      } : void 0;
+      return handlerErr(status, resolved.code, resolved.reason, details);
+    }
+    entityId = resolved.entityId;
+    role = resolved.role;
+  }
+  let result;
+  try {
+    result = await ctx.facilitator.performAction({
+      network: ctx.config.network,
+      escrowAddress: ctx.config.escrow,
+      entityId,
+      action: "boson-withdrawFunds",
+      signedPayload: input.signedPayload
+    });
+  } catch (e) {
+    if (e instanceof FacilitatorHttpError) {
+      return handlerErr(502, "FACILITATOR_UNREACHABLE", e.message, {
+        code: e.code,
+        status: e.status,
+        facilitatorCode: e.facilitatorCode
+      });
+    }
+    throw e;
+  }
+  if (!result.ok) {
+    return handlerErr(502, "FACILITATOR_REJECTED", result.reason, {
+      facilitatorCode: result.code
+    });
+  }
+  return plainHandlerOk({
+    txHash: result.txHash,
+    entityId,
+    ...role !== void 0 ? { role } : {}
+  });
+}
+
+// src/handlers/available-funds.ts
+async function handleGetAvailableFunds(query, ctx) {
+  let entityId;
+  let role;
+  if ("entityId" in query) {
+    if (!DECIMAL_UINT_RE.test(query.entityId)) {
+      return handlerErr(
+        400,
+        "INVALID_ENTITY_ID",
+        `entityId must be a decimal uint256 string, got "${query.entityId}"`
+      );
+    }
+    entityId = query.entityId;
+  } else {
+    if (!ADDRESS_RE.test(query.address)) {
+      return handlerErr(
+        400,
+        "INVALID_ADDRESS",
+        `address must be a 20-byte 0x-prefixed hex string, got "${query.address}"`
+      );
+    }
+    const resolved = await resolveEntityId(ctx.coreSdkRead, {
+      address: query.address,
+      ...query.role !== void 0 ? { role: query.role } : {}
+    });
+    if (!resolved.ok) {
+      const status = resolved.code === "NOT_FOUND" ? 404 : resolved.code === "AMBIGUOUS" ? 409 : 502;
+      return handlerErr(status, resolved.code, resolved.reason, omitErrorMetadata(resolved));
+    }
+    entityId = resolved.entityId;
+    role = resolved.role;
+  }
+  let raw;
+  try {
+    raw = await ctx.coreSdkRead.getFunds({ fundsFilter: { accountId: entityId } });
+  } catch (e) {
+    return handlerErr(
+      502,
+      "SUBGRAPH_FAILURE",
+      e instanceof Error ? e.message : "subgraph getFunds lookup failed"
+    );
+  }
+  const funds = raw.map((entry) => ({
+    tokenAddress: entry.token.address,
+    tokenSymbol: entry.token.symbol,
+    tokenName: entry.token.name,
+    decimals: Number(entry.token.decimals),
+    availableAmount: entry.availableAmount
+  }));
+  return plainHandlerOk({
+    entityId,
+    ...role !== void 0 ? { role } : {},
+    funds
+  });
+}
+function omitErrorMetadata(resolved) {
+  if (resolved.code !== "AMBIGUOUS") return void 0;
+  const details = {};
+  if (resolved.sellerIds !== void 0) details.sellerIds = resolved.sellerIds;
+  if (resolved.buyerIds !== void 0) details.buyerIds = resolved.buyerIds;
+  return Object.keys(details).length > 0 ? details : void 0;
+}
+
+// src/onchain/core-sdk-read.ts
+function asCoreSdkReadAdapter(coreSdk) {
+  return coreSdk;
+}
+
+// src/server.ts
+function withFacilitatorEndpoints(requirements, facilitatorUrl) {
+  return {
+    ...requirements,
+    actions: {
+      ...requirements.actions,
+      next: stampFacilitatorEndpoints(requirements.actions.next, facilitatorUrl)
+    }
+  };
+}
+function createX402bServer(config) {
+  const validated = x402bServerConfigSchema.parse(config);
+  assertChannelRegistryEscrowMatch(validated);
+  const facilitator = createFacilitatorClient({ url: validated.facilitator.url });
+  const exchangeFulfillmentOptionStore = validated.exchangeFulfillmentOptionStore ?? /* @__PURE__ */ new Map();
+  const fulfillmentRecoveryStore = validated.fulfillmentRecoveryStore ?? /* @__PURE__ */ new Map();
+  validated.exchangeFulfillmentOptionStore = exchangeFulfillmentOptionStore;
+  validated.fulfillmentRecoveryStore = fulfillmentRecoveryStore;
+  const signOffer = (unsigned) => signFullOffer({
+    fullOffer: unsigned,
+    signer: validated.signer,
+    escrow: validated.escrow,
+    chainId: validated.chainId
+  });
+  const requireReader = async (action) => {
+    if (validated.exchangeReader === void 0) {
+      throw new Error(
+        `x402-server: handlers.${action}() requires \`exchangeReader\` in config (post-settle state verification step).`
+      );
+    }
+    return validated.exchangeReader;
+  };
+  let cachedCoreSdkRead;
+  const requireCoreSdkRead = (action) => {
+    if (validated.coreSdkRead !== void 0) return validated.coreSdkRead;
+    if (cachedCoreSdkRead !== void 0) return cachedCoreSdkRead;
+    if (validated.subgraphUrl === void 0) {
+      throw new Error(
+        `x402-server: handlers.${action}() requires either \`coreSdkRead\` or \`subgraphUrl\` in config (subgraph read step).`
+      );
+    }
+    cachedCoreSdkRead = asCoreSdkReadAdapter(
+      new coreSdk.CoreSDK({
+        web3Lib: createReadOnlyWeb3LibStub(),
+        subgraphUrl: validated.subgraphUrl,
+        protocolDiamond: validated.escrow,
+        chainId: validated.chainId
+      })
+    );
+    return cachedCoreSdkRead;
+  };
+  return {
+    config: validated,
+    facilitator,
+    signOffer,
+    async buildPaymentRequirements(input) {
+      const offer = "unsigned" in input.offer ? await signOffer(input.offer.unsigned) : input.offer;
+      const requirements = buildPaymentRequirements({
+        offer,
+        asset: input.offer && "unsigned" in input.offer ? input.asset : input.asset,
+        amount: input.amount,
+        tokenAuthStrategies: input.tokenAuthStrategies,
+        recipientId: input.recipientId,
+        maxTimeoutSeconds: input.maxTimeoutSeconds,
+        ...input.fulfillment !== void 0 ? { fulfillment: input.fulfillment } : {},
+        network: validated.network,
+        escrow: validated.escrow,
+        channelRegistry: validated.channelRegistry
+      });
+      return withFacilitatorEndpoints(requirements, validated.facilitator.url);
+    },
+    handlers: {
+      commit: async (input) => handleCommit(input, {
+        config: validated,
+        facilitator,
+        exchangeReader: await requireReader("commit"),
+        fulfillmentRecoveryStore,
+        exchangeFulfillmentOptionStore
+      }),
+      commitAndRedeem: async (input) => handleCommitAndRedeem(input, {
+        config: validated,
+        facilitator,
+        exchangeReader: await requireReader("commitAndRedeem"),
+        fulfillmentRecoveryStore,
+        exchangeFulfillmentOptionStore
+      }),
+      redeem: async (input) => handleRedeem(input, {
+        config: validated,
+        facilitator,
+        exchangeReader: await requireReader("redeem"),
+        exchangeFulfillmentOptionStore,
+        fulfillmentRecoveryStore
+      }),
+      complete: async (input) => handleComplete(input, {
+        config: validated,
+        facilitator,
+        exchangeReader: await requireReader("complete")
+      }),
+      disputeRaise: async (input) => handleDisputeRaise(input, {
+        config: validated,
+        facilitator,
+        exchangeReader: await requireReader("disputeRaise")
+      }),
+      disputeResolve: async (input) => handleDisputeResolve(input, {
+        config: validated,
+        facilitator,
+        exchangeReader: await requireReader("disputeResolve")
+      }),
+      disputeRetract: async (input) => handleDisputeRetract(input, {
+        config: validated,
+        facilitator,
+        exchangeReader: await requireReader("disputeRetract")
+      }),
+      disputeEscalate: async (input) => handleDisputeEscalate(input, {
+        config: validated,
+        facilitator,
+        exchangeReader: await requireReader("disputeEscalate")
+      }),
+      withdrawFunds: async (input) => handleWithdrawFunds(input, {
+        config: validated,
+        facilitator,
+        coreSdkRead: requireCoreSdkRead("withdrawFunds")
+      }),
+      getAvailableFunds: async (query) => handleGetAvailableFunds(query, {
+        coreSdkRead: requireCoreSdkRead("getAvailableFunds")
+      })
+    }
+  };
+}
+
+// src/internal/x-payment-response.ts
+function encodeXPaymentResponse(body) {
+  const json = JSON.stringify(body);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(json, "utf8").toString("base64");
+  }
+  const bytes = new TextEncoder().encode(json);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+var X_PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+
+exports.ADDRESS_RE = ADDRESS_RE;
+exports.DECIMAL_UINT_RE = DECIMAL_UINT_RE;
+exports.FacilitatorHttpError = FacilitatorHttpError;
+exports.HEX_BYTES_RE = HEX_BYTES_RE;
+exports.X_PAYMENT_RESPONSE_HEADER = X_PAYMENT_RESPONSE_HEADER;
+exports.asCoreSdkReadAdapter = asCoreSdkReadAdapter;
+exports.assertChannelRegistryEscrowMatch = assertChannelRegistryEscrowMatch;
+exports.buildPaymentRequirements = buildPaymentRequirements;
+exports.createFacilitatorClient = createFacilitatorClient;
+exports.createX402bServer = createX402bServer;
+exports.decodeXPaymentHeader = decodeXPaymentHeader;
+exports.emitNextActions = emitNextActions;
+exports.encodeXPaymentResponse = encodeXPaymentResponse;
+exports.handleCommit = handleCommit;
+exports.handleCommitAndRedeem = handleCommitAndRedeem;
+exports.handleComplete = handleComplete;
+exports.handleDisputeEscalate = handleDisputeEscalate;
+exports.handleDisputeRaise = handleDisputeRaise;
+exports.handleDisputeResolve = handleDisputeResolve;
+exports.handleDisputeRetract = handleDisputeRetract;
+exports.handleGetAvailableFunds = handleGetAvailableFunds;
+exports.handlePerformAction = handlePerformAction;
+exports.handleRedeem = handleRedeem;
+exports.handleWithdrawFunds = handleWithdrawFunds;
+exports.handlerErr = handlerErr;
+exports.handlerOk = handlerOk;
+exports.plainHandlerOk = plainHandlerOk;
+exports.resolveEntityId = resolveEntityId;
+exports.signFullOffer = signFullOffer;
+exports.validatePaymentPayload = validatePaymentPayload;
+exports.verifyExchange = verifyExchange;
+exports.verifyExchangeSnapshot = verifyExchangeSnapshot;
+exports.x402bServerConfigSchema = x402bServerConfigSchema;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map