@cmdoss/suipay-mcp 0.2.2-dev.2 → 0.2.2-dev.20

package/dist/{chunk-62LFIYB7.js → chunk-6VFKI2BY.js}

@@ -103,7 +103,7 @@ function wrapFailover(clients) {
 
 // ../sdk/dist/buyer-control/chain.js
 import { Transaction as Transaction2, coinWithBalance } from "@mysten/sui/transactions";
-import { normalizeStructTag as normalizeStructTag3, normalizeSuiAddress as normalizeSuiAddress2, toBase64 } from "@mysten/sui/utils";
+import { fromBase64 as fromBase642, normalizeStructTag as normalizeStructTag3, normalizeSuiAddress as normalizeSuiAddress2, toBase64 } from "@mysten/sui/utils";
 
 // ../core/dist/chain/address.js
 function hexOf(address) {
@@ -538,6 +538,32 @@ function createSpendAccountChain(options) {
       kindBytes: toBase64(await tx.build({ client, onlyTransactionKind: true }))
     };
   }
+  function appendCreatePolicyGrant(tx, input) {
+    if (!input.onChainPolicyIds.length) {
+      throw new Error("create_grant requires at least one on-chain policy id");
+    }
+    if (!input.maxPerPayment || BigInt(input.maxPerPayment) <= 0n) {
+      throw new Error("create_grant requires a non-zero max_per_payment");
+    }
+    if (!input.sessionCap || BigInt(input.sessionCap) <= 0n) {
+      throw new Error("create_grant requires a non-zero session_cap");
+    }
+    const expires = input.expiresAtMs === void 0 || input.expiresAtMs === null ? 0n : BigInt(input.expiresAtMs);
+    tx.moveCall({
+      target: target("create_policy_grant"),
+      typeArguments: [input.coinType],
+      arguments: [
+        tx.object(input.poolObjectId),
+        tx.pure.address(input.delegate),
+        // The unified Grant<T> takes Option<u64> caps. This builder rejects
+        // absent or zero caps above, so both are always Some here.
+        tx.pure.option("u64", BigInt(input.sessionCap)),
+        tx.pure.option("u64", BigInt(input.maxPerPayment)),
+        tx.pure.u64(expires),
+        tx.pure.vector("u64", input.onChainPolicyIds.map((id) => BigInt(id)))
+      ]
+    });
+  }
   async function fundingCoin(tx, owner, coinType, amount) {
     if (!isSuiCoinType(coinType)) {
       return coinWithBalance({ type: coinType, balance: amount });
@@ -636,7 +662,7 @@ function createSpendAccountChain(options) {
       const tx = new Transaction2();
       tx.setSender(input.owner);
       tx.moveCall({
-        target: target("withdraw"),
+        target: target("withdraw_to_owner"),
         typeArguments: [input.coinType],
         arguments: [
           tx.object(input.poolObjectId),
@@ -737,32 +763,23 @@ function createSpendAccountChain(options) {
       return kindBytes(tx);
     },
     async buildCreateGrantKind(input) {
-      if (!input.onChainPolicyIds.length) {
-        throw new Error("create_grant requires at least one on-chain policy id");
-      }
-      if (!input.maxPerPayment || BigInt(input.maxPerPayment) <= 0n) {
-        throw new Error("create_grant requires a non-zero max_per_payment");
+      const tx = new Transaction2();
+      tx.setSender(input.owner);
+      appendCreatePolicyGrant(tx, input);
+      return kindBytes(tx);
+    },
+    async buildCreateGrantBatchKind(inputs) {
+      if (!inputs.length) {
+        throw new Error("create_grant batch requires at least one grant");
       }
-      if (!input.sessionCap || BigInt(input.sessionCap) <= 0n) {
-        throw new Error("create_grant requires a non-zero session_cap");
+      const owner = inputs[0].owner;
+      if (inputs.some((input) => input.owner !== owner)) {
+        throw new Error("create_grant batch requires one owner");
       }
       const tx = new Transaction2();
-      tx.setSender(input.owner);
-      const expires = input.expiresAtMs === void 0 || input.expiresAtMs === null ? 0n : BigInt(input.expiresAtMs);
-      tx.moveCall({
-        target: target("create_policy_grant"),
-        typeArguments: [input.coinType],
-        arguments: [
-          tx.object(input.poolObjectId),
-          tx.pure.address(input.delegate),
-          // The unified Grant<T> takes Option<u64> caps. This builder rejects
-          // absent or zero caps above, so both are always Some here.
-          tx.pure.option("u64", BigInt(input.sessionCap)),
-          tx.pure.option("u64", BigInt(input.maxPerPayment)),
-          tx.pure.u64(expires),
-          tx.pure.vector("u64", input.onChainPolicyIds.map((id) => BigInt(id)))
-        ]
-      });
+      tx.setSender(owner);
+      for (const input of inputs)
+        appendCreatePolicyGrant(tx, input);
       return kindBytes(tx);
     },
     async buildCreateSpendGrantKind(input) {
@@ -823,24 +840,27 @@ function createSpendAccountChain(options) {
     },
     async buildSettleOpenRecipientKind(input) {
       if (!input.termsHash || input.termsHash.length === 0) {
-        throw new Error("termsHash must be non-empty for spend_account::settle_open_recipient_payment");
+        throw new Error("termsHash must be non-empty for spend_account::settle_any_recipient");
       }
       if (!input.paymentIdHash || input.paymentIdHash.length === 0) {
-        throw new Error("paymentIdHash must be non-empty for spend_account::settle_open_recipient_payment");
+        throw new Error("paymentIdHash must be non-empty for spend_account::settle_any_recipient");
       }
       if (!input.recipient || isZeroAddress(input.recipient)) {
-        throw new Error("settle_open_recipient_payment recipient must be a non-zero address");
+        throw new Error("settle_any_recipient recipient must be a non-zero address");
       }
       if (!input.amount || BigInt(input.amount) <= 0n) {
-        throw new Error("settle_open_recipient_payment amount must be > 0");
+        throw new Error("settle_any_recipient amount must be > 0");
       }
+      const guarded = resolveGuardedInputs(input, "settle_any_recipient");
       const hash = targetHashBytes(input.targetHash);
       const tx = new Transaction2();
       tx.setSender(input.delegate);
       tx.moveCall({
-        target: target("settle_open_recipient_payment"),
+        target: target("settle_any_recipient"),
         typeArguments: [input.coinType],
         arguments: [
+          tx.object(guarded.exclusionDirectoryId),
+          tx.object(guarded.recipientRegistryId),
           tx.object(input.poolObjectId),
           tx.object(input.grantObjectId),
           tx.pure.address(input.recipient),
@@ -848,6 +868,7 @@ function createSpendAccountChain(options) {
           tx.pure.vector("u8", Array.from(input.paymentIdHash)),
           tx.pure.vector("u8", Array.from(input.termsHash)),
           tx.pure.vector("u8", Array.from(hash)),
+          tx.pure.u64(guarded.expiresAtMs),
           tx.object(input.clockId ?? SUI_CLOCK)
         ]
       });
@@ -858,6 +879,7 @@ function createSpendAccountChain(options) {
       tx.setSender(input.owner);
       tx.moveCall({
         target: target("pause_grant"),
+        typeArguments: [input.coinType],
         arguments: [tx.object(input.grantObjectId)]
       });
       return kindBytes(tx);
@@ -867,6 +889,7 @@ function createSpendAccountChain(options) {
       tx.setSender(input.owner);
       tx.moveCall({
         target: target("resume_grant"),
+        typeArguments: [input.coinType],
         arguments: [tx.object(input.grantObjectId)]
       });
       return kindBytes(tx);
@@ -876,6 +899,7 @@ function createSpendAccountChain(options) {
       tx.setSender(input.owner);
       tx.moveCall({
         target: target("revoke_grant"),
+        typeArguments: [input.coinType],
         arguments: [tx.object(input.grantObjectId)]
       });
       return kindBytes(tx);
@@ -944,30 +968,57 @@ function createSpendAccountChain(options) {
       const tx = new Transaction2();
       tx.setSender(input.owner);
       const expires = input.newExpiresAtMs === void 0 || input.newExpiresAtMs === null ? 0n : BigInt(input.newExpiresAtMs);
+      const totalBudget = input.newTotalBudget === null || input.newTotalBudget === void 0 ? null : BigInt(input.newTotalBudget);
       tx.moveCall({
         target: target("tighten_grant_limits"),
+        // Grant<T> is generic; every sibling grant builder passes the coin type.
+        typeArguments: [input.coinType],
         arguments: [
           tx.object(input.grantObjectId),
-          tx.pure.u64(BigInt(input.newSessionCap)),
+          tx.pure.option("u64", totalBudget),
           tx.pure.u64(expires)
         ]
       });
       return kindBytes(tx);
     },
+    async readGrantTotalSpent(grantObjectId) {
+      try {
+        const { object } = await client.core.getObject({
+          objectId: grantObjectId,
+          include: { json: true }
+        });
+        const json = object?.json;
+        if (!json || typeof json !== "object")
+          return null;
+        const spent = json.total_spent;
+        if (typeof spent === "string" && /^\d+$/.test(spent))
+          return BigInt(spent);
+        if (typeof spent === "number" && Number.isFinite(spent))
+          return BigInt(Math.trunc(spent));
+        if (typeof spent === "bigint")
+          return spent;
+        return null;
+      } catch {
+        return null;
+      }
+    },
     async buildPayKind(input) {
       if (!input.termsHash || input.termsHash.length === 0) {
-        throw new Error("termsHash must be non-empty for spend_account::settle_policy_payment");
+        throw new Error("termsHash must be non-empty for spend_account::settle_policy");
       }
       if (!input.paymentIdHash || input.paymentIdHash.length === 0) {
-        throw new Error("paymentIdHash must be non-empty for spend_account::settle_policy_payment");
+        throw new Error("paymentIdHash must be non-empty for spend_account::settle_policy");
       }
+      const guarded = resolveGuardedInputs(input, "settle_policy");
       const hash = targetHashBytes(input.targetHash);
       const tx = new Transaction2();
       tx.setSender(input.delegate);
       tx.moveCall({
-        target: target("settle_policy_payment"),
+        target: target("settle_policy"),
         typeArguments: [input.coinType],
         arguments: [
+          tx.object(guarded.exclusionDirectoryId),
+          tx.object(guarded.recipientRegistryId),
           tx.object(input.poolObjectId),
           tx.object(input.grantObjectId),
           tx.pure.u64(BigInt(input.policyId)),
@@ -975,6 +1026,7 @@ function createSpendAccountChain(options) {
           tx.pure.u64(BigInt(input.amount)),
           tx.pure.vector("u8", Array.from(input.paymentIdHash)),
           tx.pure.vector("u8", Array.from(input.termsHash)),
+          tx.pure.u64(guarded.expiresAtMs),
           tx.object(input.clockId ?? SUI_CLOCK)
         ]
       });
@@ -982,6 +1034,28 @@ function createSpendAccountChain(options) {
     }
   };
 }
+function resolveGuardedInputs(input, fn) {
+  const present = [
+    input.exclusionDirectoryId,
+    input.recipientRegistryId,
+    input.expiresAtMs
+  ].filter((v) => v !== void 0).length;
+  if (present !== 3) {
+    throw new Error(`${fn} on the fresh lineage requires exclusionDirectoryId, recipientRegistryId and expiresAtMs (mandatory guarded settlement \u2014 there is no unguarded twin)`);
+  }
+  const expires = BigInt(input.expiresAtMs);
+  if (expires <= 0n) {
+    throw new Error(`guarded ${fn} expiresAtMs must be a positive epoch-ms value`);
+  }
+  if (isZeroAddress(input.exclusionDirectoryId) || isZeroAddress(input.recipientRegistryId)) {
+    throw new Error(`guarded ${fn} directory and registry ids must be non-zero`);
+  }
+  return {
+    exclusionDirectoryId: input.exclusionDirectoryId,
+    recipientRegistryId: input.recipientRegistryId,
+    expiresAtMs: expires
+  };
+}
 var SUI_NETWORKS = ["testnet", "devnet", "localnet", "mainnet"];
 function toGrpcNetwork(network) {
   const short = (network ?? "testnet").replace(/^sui:/, "");
@@ -990,18 +1064,132 @@ function toGrpcNetwork(network) {
   }
   return short;
 }
-function createSpendAccountFinalityReader(options) {
+var GUARDED_DELEGATE_ARG_LAYOUT = {
+  settle_policy: {
+    recipient: null,
+    amount: 6,
+    paymentIdHash: 7,
+    expiresAtMs: 9
+  },
+  settle_any_recipient: {
+    recipient: 4,
+    amount: 5,
+    paymentIdHash: 6,
+    expiresAtMs: 9
+  },
+  settle_policy_to_refund_vault: {
+    recipient: null,
+    amount: 6,
+    paymentIdHash: 7,
+    expiresAtMs: 9
+  },
+  settle_any_recipient_to_refund_vault: {
+    recipient: 4,
+    amount: 5,
+    paymentIdHash: 6,
+    expiresAtMs: 9
+  }
+};
+function pureBytesOf(data, arg) {
+  if (!arg || arg.$kind !== "Input" || arg.Input === void 0)
+    return null;
+  const input = data.inputs?.[arg.Input];
+  if (!input || input.$kind !== "Pure" || !input.Pure)
+    return null;
+  return input.Pure.bytes;
+}
+function readPureU64(data, arg) {
+  const raw = pureBytesOf(data, arg);
+  if (raw === null)
+    return null;
+  try {
+    return bcs.u64().parse(fromBase642(raw));
+  } catch {
+    return null;
+  }
+}
+function readPureVectorU8Hex(data, arg) {
+  const raw = pureBytesOf(data, arg);
+  if (raw === null)
+    return null;
+  try {
+    const bytes = bcs.vector(bcs.u8()).parse(fromBase642(raw));
+    return Buffer.from(bytes).toString("hex");
+  } catch {
+    return null;
+  }
+}
+function readPureAddress(data, arg) {
+  const raw = pureBytesOf(data, arg);
+  if (raw === null)
+    return null;
+  try {
+    return normalizeSuiAddress2(bcs.Address.parse(fromBase642(raw)));
+  } catch {
+    return null;
+  }
+}
+function recoverGuardedDelegateCalls(finalized) {
+  const raw = finalized?.bcs;
+  let bytes;
+  if (raw instanceof Uint8Array) {
+    bytes = raw;
+  } else if (typeof raw === "string") {
+    try {
+      bytes = fromBase642(raw);
+    } catch {
+      return [];
+    }
+  } else {
+    return [];
+  }
+  let data;
+  try {
+    data = Transaction2.from(bytes).getData();
+  } catch {
+    return [];
+  }
+  const calls = [];
+  for (const command of data.commands) {
+    if (command.$kind !== "MoveCall")
+      continue;
+    const mc = command.MoveCall;
+    if (!mc || mc.module !== "spend_account")
+      continue;
+    if (!(mc.function in GUARDED_DELEGATE_ARG_LAYOUT))
+      continue;
+    const fn = mc.function;
+    const layout = GUARDED_DELEGATE_ARG_LAYOUT[fn];
+    const args = mc.arguments ?? [];
+    calls.push({
+      packageId: normalizeSuiAddress2(mc.package),
+      function: fn,
+      paymentIdHash: readPureVectorU8Hex(data, args[layout.paymentIdHash]),
+      amount: readPureU64(data, args[layout.amount]),
+      recipient: layout.recipient === null ? null : readPureAddress(data, args[layout.recipient]),
+      expiresAtMs: readPureU64(data, args[layout.expiresAtMs])
+    });
+  }
+  return calls;
+}
+function createSpendAccountSettledTxReader(options) {
   const network = toGrpcNetwork(options.network);
   const client = options.client ?? createFailoverGrpcClient({
     network,
     url: options.url ?? `https://fullnode.${network}.sui.io:443`
   });
   return {
-    async getFinalizedTx(digest) {
+    async getSettledTx(digest) {
       const result = await fetchGrpcTransaction(client, digest, {
         events: true,
         effects: true,
-        transaction: true
+        transaction: true,
+        // The guarded delegate recovery below decodes the authoritative
+        // serialized transaction. Those bytes are a separate read-mask path
+        // from the parsed `transaction` projection — without asking for them
+        // the response carries none, recovery finds no guarded call, and every
+        // delegate payment is refused after the funds already moved.
+        bcs: true
       });
       if (!result)
         return null;
@@ -1037,26 +1225,28 @@ function createSpendAccountFinalityReader(options) {
         type: e.eventType,
         kind: e.eventType.split("::").pop() ?? e.eventType
       }));
+      const guardedDelegateCalls = recoverGuardedDelegateCalls(finalized);
       return {
         status: "success",
         txDigest: digest,
         sender,
         moveCalls,
         objectIds,
-        events
+        events,
+        guardedDelegateCalls
       };
     }
   };
 }
 
 // ../sdk/dist/delegated-signer/payer.js
-import { bcs as bcs4 } from "@mysten/sui/bcs";
+import { bcs as bcs5 } from "@mysten/sui/bcs";
 import { Transaction as Transaction4 } from "@mysten/sui/transactions";
-import { fromBase64 as fromBase643, normalizeStructTag as normalizeStructTag5, normalizeSuiAddress as normalizeSuiAddress6, toBase64 as toBase643 } from "@mysten/sui/utils";
+import { fromBase64 as fromBase646, normalizeStructTag as normalizeStructTag6, normalizeSuiAddress as normalizeSuiAddress6, toBase64 as toBase645 } from "@mysten/sui/utils";
 import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
 
 // ../sdk/dist/pay-operation/operation.js
-import { normalizeStructTag as normalizeStructTag4, normalizeSuiAddress as normalizeSuiAddress3 } from "@mysten/sui/utils";
+import { normalizeStructTag as normalizeStructTag5, normalizeSuiAddress as normalizeSuiAddress3 } from "@mysten/sui/utils";
 
 // ../core/dist/policy/grant-target.js
 function normalizeHash(hex) {
@@ -1139,6 +1329,9 @@ function resolveGrantTarget(snapshot, offerTargetHash) {
   };
 }
 
+// ../sdk/dist/protocol/carrier.js
+import { fromBase64 as fromBase644, toBase64 as toBase643 } from "@mysten/sui/utils";
+
 // ../sdk/dist/protocol/auth-params.js
 var TOKEN = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
 function formatAuthParams(params) {
@@ -1230,8 +1423,11 @@ function bytesToBase64Url(bytes) {
 var SETTLEMENT_RAILS = [
   "direct",
   "delegate",
-  "subscription"
+  "recurring"
 ];
+function mintLiveRail(rail) {
+  return rail;
+}
 function isDelegateRail(rail) {
   return rail === "delegate";
 }
@@ -1239,6 +1435,29 @@ var DIALECT_ORDER = ["mpp", "x402"];
 function isSettlementRail(value) {
   return typeof value === "string" && SETTLEMENT_RAILS.includes(value);
 }
+function decodeWireRail(value) {
+  if (isSettlementRail(value))
+    return value;
+  if (value === "subscription")
+    return "recurring";
+  return null;
+}
+function decodeAcceptedRails(rails) {
+  if (rails.length === 0)
+    return null;
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of rails) {
+    const decoded = decodeWireRail(r);
+    if (!decoded)
+      return null;
+    if (seen.has(decoded))
+      continue;
+    seen.add(decoded);
+    out.push(decoded);
+  }
+  return out;
+}
 function assertSettlementRail(value) {
   if (!isSettlementRail(value)) {
     throw new Error(`invalid settlement rail: ${String(value)} (expected ${SETTLEMENT_RAILS.join(" | ")})`);
@@ -1249,7 +1468,7 @@ function isDialect(value) {
   return value === "mpp" || value === "x402";
 }
 function isSettlementMode(value) {
-  return value === "transaction" || value === "finalized-proof";
+  return value === "gateway-settled" || value === "self-settled";
 }
 function dialectsFromModes(modes) {
   return DIALECT_ORDER.filter((d) => modes[d] != null);
@@ -1287,7 +1506,7 @@ function createSettlementRailAuthority(input) {
   }
   const dialectModes = Object.freeze({ ...input.dialectModes });
   const supportedDialects = Object.freeze(dialectsFromModes(dialectModes));
-  const proofMode = dialectModes.mpp ?? dialectModes.x402 ?? "transaction";
+  const proofMode = dialectModes.mpp ?? dialectModes.x402 ?? "gateway-settled";
   return Object.freeze({
     rail: input.rail,
     packageId: input.packageId.trim(),
@@ -1302,12 +1521,12 @@ function spendAccountDebitFunction(input) {
   const open2 = input?.accessMode === "open";
   const refundable = input?.refundable === true;
   if (open2 && refundable)
-    return "settle_open_recipient_payment_to_refund_vault";
+    return "settle_any_recipient_to_refund_vault";
   if (open2)
-    return "settle_open_recipient_payment";
+    return "settle_any_recipient";
   if (refundable)
-    return "settle_policy_payment_to_refund_vault";
-  return "settle_policy_payment";
+    return "settle_policy_to_refund_vault";
+  return "settle_policy";
 }
 function defaultAuthorityForRail(rail, packageId, opts) {
   switch (rail) {
@@ -1318,20 +1537,22 @@ function defaultAuthorityForRail(rail, packageId, opts) {
         packageId,
         module: "spend_account",
         payFunction: spendAccountDebitFunction(),
-        dialectModes: dual ? { mpp: "finalized-proof", x402: "transaction" } : { mpp: "finalized-proof" }
+        dialectModes: dual ? { mpp: "self-settled", x402: "gateway-settled" } : { mpp: "self-settled" }
       });
     }
-    case "subscription":
+    case "recurring":
       return createSettlementRailAuthority({
-        rail: "subscription",
+        rail: "recurring",
         packageId,
         module: "subscription",
         // Real Move entry function is `subscription::settle_period`; `charge`
-        // never existed on-chain (a Move call to it would abort).
+        // never existed on-chain (a Move call to it would abort). HTTP
+        // `recurring` is the Move `RAIL_TAG`; the module name stays
+        // `subscription`.
         payFunction: "settle_period",
         dialectModes: {
-          mpp: "transaction",
-          x402: "transaction"
+          mpp: "gateway-settled",
+          x402: "gateway-settled"
         }
       });
     case "direct":
@@ -1339,10 +1560,12 @@ function defaultAuthorityForRail(rail, packageId, opts) {
         rail: "direct",
         packageId,
         module: "payment",
-        payFunction: "pay",
+        // Fresh lineage (ADR-0048 Option B): the canonical guarded direct settle
+        // is `payment::settle` (guard folded in; no `pay`/`settle_guarded` twin).
+        payFunction: "settle",
         dialectModes: {
-          mpp: "transaction",
-          x402: "transaction"
+          mpp: "gateway-settled",
+          x402: "gateway-settled"
         }
       });
     default: {
@@ -1351,9 +1574,24 @@ function defaultAuthorityForRail(rail, packageId, opts) {
     }
   }
 }
+function railSelfSettles(rail, opts) {
+  const authority = defaultAuthorityForRail(rail, "0x0", opts);
+  return Object.values(authority.dialectModes).some((mode) => mode === "self-settled");
+}
 
 // ../sdk/dist/protocol/challenge.js
 import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+
+// ../sdk/dist/protocol/refund-approval.js
+import { createHash as createHash3 } from "crypto";
+import { bcs as bcs2 } from "@mysten/sui/bcs";
+import { fromHex } from "@mysten/sui/utils";
+
+// ../sdk/dist/protocol/coin-type-hash.js
+import { createHash as createHash2 } from "crypto";
+import { normalizeStructTag as normalizeStructTag4 } from "@mysten/sui/utils";
+
+// ../sdk/dist/protocol/challenge.js
 var SIGNED_FIELDS_V1 = [
   "challengeId",
   "resource",
@@ -1402,6 +1640,12 @@ var SIGNED_FIELDS_V3 = [
   "refundTo",
   "settlementRef"
 ];
+var SIGNED_FIELDS_V4 = [
+  ...SIGNED_FIELDS_V3,
+  "acceptedRails",
+  "exclusionProtocolVersion",
+  "registryIdentity"
+];
 var V3_OMIT_WHEN_ABSENT = /* @__PURE__ */ new Set([
   "intent",
   "periodMs",
@@ -1419,6 +1663,15 @@ var V3_OMIT_WHEN_ABSENT = /* @__PURE__ */ new Set([
   "sponsorGasPrice",
   "sponsorGasPayment"
 ]);
+var V4_OMIT_WHEN_ABSENT = /* @__PURE__ */ new Set([
+  "acceptedRails",
+  "exclusionProtocolVersion",
+  "registryIdentity"
+]);
+var OMIT_WHEN_ABSENT = /* @__PURE__ */ new Set([
+  ...V3_OMIT_WHEN_ABSENT,
+  ...V4_OMIT_WHEN_ABSENT
+]);
 var BODY_HASH_RE = /^[A-Za-z0-9_-]{43}$/;
 var CONTENT_TYPE_RE = /^[a-z0-9!#$%&'*+.^_`|~-]+\/[a-z0-9!#$%&'*+.^_`|~-]+(?:; ?[a-z0-9!#$%&'*+.^_`|~-]+=(?:[a-zA-Z0-9!#$%&'*+.^_`|~-]+|"[^"\n\r]*"))*$/;
 function isBodyHash(value) {
@@ -1446,10 +1699,43 @@ function presentV3OnlyFields(bearer) {
 function carriesV3OnlyFields(bearer) {
   return presentV3OnlyFields(bearer).length > 0;
 }
+function presentV4OnlyFields(bearer) {
+  return [
+    bearer.acceptedRails !== void 0 ? "acceptedRails" : void 0,
+    bearer.exclusionProtocolVersion !== void 0 ? "exclusionProtocolVersion" : void 0,
+    bearer.registryIdentity !== void 0 ? "registryIdentity" : void 0
+  ].filter((f) => f !== void 0);
+}
+function carriesV4OnlyFields(bearer) {
+  return presentV4OnlyFields(bearer).length > 0;
+}
+function offerRequiresGuardedSettle(offer) {
+  const rails = [
+    ...offer.acceptedRails ?? [],
+    ...offer.settlementRail ? [offer.settlementRail] : []
+  ];
+  if (!rails.length)
+    return false;
+  return [...new Set(rails)].some((r) => railSelfSettles(r, { x402DialectEnabled: false }));
+}
+function parseRegistryIdentity(registryIdentity) {
+  if (!registryIdentity)
+    return null;
+  const idx = registryIdentity.indexOf("::");
+  if (idx <= 0)
+    return null;
+  const packageId = registryIdentity.slice(0, idx);
+  const directoryId = registryIdentity.slice(idx + 2);
+  if (!packageId || !directoryId || directoryId.includes("::"))
+    return null;
+  return { packageId, directoryId };
+}
 function resolveDigestVersion(offer) {
+  if (carriesV4OnlyFields(offer))
+    return 4;
   if (carriesV3OnlyFields(offer))
     return 3;
-  if (offer.digestVersion === 3 || offer.digestVersion === 2 || offer.digestVersion === 1) {
+  if (offer.digestVersion === 4 || offer.digestVersion === 3 || offer.digestVersion === 2 || offer.digestVersion === 1) {
     return offer.digestVersion;
   }
   if (offer.settlementRail)
@@ -1457,6 +1743,8 @@ function resolveDigestVersion(offer) {
   return 1;
 }
 function signedFieldsFor(version) {
+  if (version === 4)
+    return SIGNED_FIELDS_V4;
   if (version === 3)
     return SIGNED_FIELDS_V3;
   if (version === 2)
@@ -1467,12 +1755,14 @@ function fieldValue(offer, key) {
   const v = offer[key];
   if (v === void 0 || v === null)
     return "";
+  if (Array.isArray(v))
+    return v.join(",");
   return String(v);
 }
 function canonicalOffer(offer, version = resolveDigestVersion(offer)) {
   const lines = [];
   for (const f of signedFieldsFor(version)) {
-    if (V3_OMIT_WHEN_ABSENT.has(f) && (offer[f] === void 0 || offer[f] === null))
+    if (OMIT_WHEN_ABSENT.has(f) && (offer[f] === void 0 || offer[f] === null))
       continue;
     lines.push(`${f}=${fieldValue(offer, f)}`);
   }
@@ -1482,15 +1772,73 @@ function signOffer(offer, secret, version) {
   const v = version ?? resolveDigestVersion(offer);
   return createHmac("sha256", secret).update(canonicalOffer(offer, v)).digest("base64url");
 }
-function verifyOfferDigest(offer, secret) {
+function digestMatches(offer, secret) {
   const version = resolveDigestVersion(offer);
   const expected = Buffer.from(signOffer(offer, secret, version));
   const actual = Buffer.from(offer.digest ?? "");
   return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
+function withLegacySubscriptionSpelling(offer) {
+  const railIsRecurring = offer.settlementRail === "recurring";
+  const railsHaveRecurring = offer.acceptedRails?.includes("recurring") === true;
+  if (!railIsRecurring && !railsHaveRecurring)
+    return null;
+  return {
+    ...offer,
+    ...railIsRecurring ? { settlementRail: "subscription" } : {},
+    ...railsHaveRecurring ? {
+      acceptedRails: offer.acceptedRails.map((r) => r === "recurring" ? "subscription" : r)
+    } : {}
+  };
+}
+function verifyOfferDigest(offer, secret) {
+  if (digestMatches(offer, secret))
+    return true;
+  const legacy = withLegacySubscriptionSpelling(offer);
+  return legacy !== null && digestMatches(legacy, secret);
+}
 function isExpired(offer, now = Date.now()) {
   return now >= offer.expiresAt;
 }
+function decodeSponsorGasPayment(encoded) {
+  if (typeof encoded !== "string" || !encoded.trim()) {
+    throw new Error("sponsorGasPayment is required");
+  }
+  return encoded.split(",").map((part) => {
+    const bits = part.split("@");
+    if (bits.length !== 3 || !bits[0] || !bits[1] || !bits[2]) {
+      throw new Error(`malformed sponsorGasPayment segment: ${part}`);
+    }
+    return { objectId: bits[0], version: bits[1], digest: bits[2] };
+  });
+}
+var SPONSOR_GAS_ADDRESS_BALANCE = "address-balance";
+function decodeSponsorGasPin(encoded) {
+  if (encoded === SPONSOR_GAS_ADDRESS_BALANCE)
+    return [];
+  return decodeSponsorGasPayment(encoded);
+}
+var ADDRESS_BALANCE_VALIDITY_EPOCHS = 1n;
+function addressBalanceGasExpiration(input) {
+  const chain = input.chainIdentifier.trim();
+  if (!chain)
+    throw new Error("address-balance gas needs a chain identifier");
+  if (input.epoch < 0n)
+    throw new Error("address-balance gas needs a non-negative epoch");
+  if (!Number.isInteger(input.nonce) || input.nonce < 0 || input.nonce > 4294967295) {
+    throw new Error("address-balance gas nonce must be a u32");
+  }
+  return {
+    ValidDuring: {
+      minEpoch: String(input.epoch),
+      maxEpoch: String(input.epoch + ADDRESS_BALANCE_VALIDITY_EPOCHS),
+      minTimestamp: null,
+      maxTimestamp: null,
+      chain,
+      nonce: input.nonce
+    }
+  };
+}
 
 // ../sdk/dist/protocol/mpp.js
 function offerToBase64Url(offer) {
@@ -1501,7 +1849,66 @@ var MPP_METHOD = "sui.charge";
 var MPP_CHALLENGE_HEADER = "WWW-Authenticate";
 var MPP_CREDENTIAL_HEADER = "Authorization";
 var MPP_RECEIPT_HEADER = "Payment-Receipt";
-function decodeChallenge(header) {
+function splitChallenges(header) {
+  const scheme = `${MPP_SCHEME} `;
+  const value = header.trim();
+  const starts = [];
+  let inQuote = false;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (inQuote) {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === '"')
+        inQuote = false;
+      continue;
+    }
+    if (ch === '"') {
+      inQuote = true;
+      continue;
+    }
+    if (value.startsWith(scheme, i)) {
+      let j = i - 1;
+      while (j >= 0 && (value[j] === " " || value[j] === "	"))
+        j--;
+      if (j < 0 || value[j] === ",")
+        starts.push(i);
+    }
+  }
+  if (starts.length === 0)
+    return [];
+  const parts = [];
+  for (let k = 0; k < starts.length; k++) {
+    const from = starts[k];
+    const to = k + 1 < starts.length ? starts[k + 1] : value.length;
+    parts.push(value.slice(from, to).replace(/,\s*$/, "").trim());
+  }
+  return parts;
+}
+function decodeChallenge(header, opts) {
+  const parts = splitChallenges(header);
+  if (parts.length <= 1) {
+    return decodeSingleChallenge(header);
+  }
+  if (opts?.rail !== void 0) {
+    for (const part of parts) {
+      const offer = decodeSingleChallenge(part);
+      if (offer && mintLiveRail(offer.settlementRail ?? "direct") === mintLiveRail(opts.rail)) {
+        return offer;
+      }
+    }
+    return null;
+  }
+  for (const part of parts) {
+    const offer = decodeSingleChallenge(part);
+    if (offer)
+      return offer;
+  }
+  return null;
+}
+function decodeSingleChallenge(header) {
   const parsed = parseAuthHeader(header);
   if (!parsed || parsed.scheme !== MPP_SCHEME)
     return null;
@@ -1549,13 +1956,14 @@ function decodeChallenge(header) {
     offer.platformFee = p.platform_fee;
   if (p.digest_version !== void 0) {
     const v = Number(p.digest_version);
-    if (v === 1 || v === 2 || v === 3)
+    if (v === 1 || v === 2 || v === 3 || v === 4)
       offer.digestVersion = v;
   }
   if (p.settlement_rail !== void 0) {
-    if (!isSettlementRail(p.settlement_rail))
+    const rail = decodeWireRail(p.settlement_rail);
+    if (!rail)
       return null;
-    offer.settlementRail = p.settlement_rail;
+    offer.settlementRail = rail;
   }
   if (p.service_id !== void 0)
     offer.serviceId = p.service_id;
@@ -1632,6 +2040,21 @@ function decodeChallenge(header) {
   if (p.sponsor_gas_payment !== void 0) {
     offer.sponsorGasPayment = p.sponsor_gas_payment;
   }
+  if (p.accepted_rails !== void 0) {
+    const rails = decodeAcceptedRails(p.accepted_rails.split(","));
+    if (!rails)
+      return null;
+    offer.acceptedRails = rails;
+  }
+  if (p.exclusion_protocol_version !== void 0) {
+    const raw = p.exclusion_protocol_version;
+    const v = Number(raw);
+    if (raw.trim() === "" || !Number.isFinite(v))
+      return null;
+    offer.exclusionProtocolVersion = v;
+  }
+  if (p.registry_identity !== void 0)
+    offer.registryIdentity = p.registry_identity;
   return offer;
 }
 function encodeProof(proof) {
@@ -1675,12 +2098,128 @@ function decodeReceipt(header) {
 }
 
 // ../sdk/dist/protocol/x402.js
+import { fromBase64 as fromBase643, toBase64 as toBase642 } from "@mysten/sui/utils";
+function utf8ToBase64(text2) {
+  return toBase642(new TextEncoder().encode(text2));
+}
+function base64ToUtf8(value) {
+  return new TextDecoder().decode(fromBase643(value));
+}
+var X402_VERSION = 2;
 var X402_SCHEME = "exact";
+var X402_PAYMENT_FLOW = "upfront";
+var X402_ERROR_REASON = {
+  MALFORMED_CREDENTIAL: "invalid_payload",
+  UNKNOWN_CHALLENGE: "invalid_payment_requirements",
+  CHALLENGE_TAMPERED: "invalid_payment_requirements",
+  CHALLENGE_EXPIRED: "invalid_payment_requirements",
+  CHALLENGE_ALREADY_USED: "invalid_transaction_state",
+  CHALLENGE_IN_FLIGHT: "invalid_transaction_state",
+  TRANSACTION_INVALID: "invalid_payload",
+  NETWORK_MISMATCH: "invalid_network",
+  SIGNATURE_INVALID: "invalid_payload",
+  INSUFFICIENT_FUNDS: "insufficient_funds",
+  PAYER_MISMATCH: "invalid_payload",
+  SETTLEMENT_REJECTED: "invalid_transaction_state",
+  SETTLEMENT_MISMATCH: "unexpected_settle_error",
+  AMBIGUOUS: "settlement_pending"
+};
 var X402_CHALLENGE_HEADER = "PAYMENT-REQUIRED";
+var X402_PAYMENT_HEADER = "PAYMENT-SIGNATURE";
 var X402_RESPONSE_HEADER = "PAYMENT-RESPONSE";
 var X402_RECEIPT_HEADER = "X-PAYMENT-RESPONSE";
+function toAccept(offer, authority, opts) {
+  const auth = authority ?? defaultAuthorityForRail(offer.settlementRail ?? "direct", offer.packageId);
+  const payFunction = auth.payFunction;
+  const suipay = {
+    challengeId: offer.challengeId,
+    packageId: offer.packageId,
+    module: auth.module,
+    function: payFunction,
+    decimals: offer.decimals,
+    issuedAt: offer.issuedAt,
+    expiresAt: offer.expiresAt,
+    digest: offer.digest
+  };
+  if (offer.netAmount !== void 0)
+    suipay.netAmount = offer.netAmount;
+  if (offer.platformFee !== void 0)
+    suipay.platformFee = offer.platformFee;
+  if (offer.digestVersion !== void 0)
+    suipay.digestVersion = offer.digestVersion;
+  if (offer.settlementRail !== void 0)
+    suipay.settlementRail = offer.settlementRail;
+  if (offer.serviceId !== void 0)
+    suipay.serviceId = offer.serviceId;
+  if (offer.serviceRevision !== void 0)
+    suipay.serviceRevision = offer.serviceRevision;
+  if (offer.targetHash !== void 0)
+    suipay.targetHash = offer.targetHash;
+  if (offer.authorizationEpoch !== void 0) {
+    suipay.authorizationEpoch = offer.authorizationEpoch;
+  }
+  if (offer.method !== void 0)
+    suipay.method = offer.method;
+  if (offer.path !== void 0)
+    suipay.path = offer.path;
+  if (offer.bodyHash !== void 0)
+    suipay.bodyHash = offer.bodyHash;
+  if (offer.contentType !== void 0)
+    suipay.contentType = offer.contentType;
+  if (offer.intent !== void 0)
+    suipay.intent = offer.intent;
+  if (offer.periodMs !== void 0)
+    suipay.periodMs = offer.periodMs;
+  if (offer.periodCount !== void 0)
+    suipay.periodCount = offer.periodCount;
+  if (offer.refundable !== void 0)
+    suipay.refundable = offer.refundable;
+  if (offer.refundWindowMs !== void 0)
+    suipay.refundWindowMs = offer.refundWindowMs;
+  if (offer.decideWindowMs !== void 0)
+    suipay.decideWindowMs = offer.decideWindowMs;
+  if (offer.chainId !== void 0)
+    suipay.chainId = offer.chainId;
+  if (offer.paymentSalt !== void 0)
+    suipay.paymentSalt = offer.paymentSalt;
+  if (offer.refundTo !== void 0)
+    suipay.refundTo = offer.refundTo;
+  if (offer.sponsorGasOwner !== void 0) {
+    suipay.sponsorGasOwner = offer.sponsorGasOwner;
+  }
+  if (offer.sponsorGasBudget !== void 0) {
+    suipay.sponsorGasBudget = offer.sponsorGasBudget;
+  }
+  if (offer.sponsorGasPrice !== void 0) {
+    suipay.sponsorGasPrice = offer.sponsorGasPrice;
+  }
+  if (offer.sponsorGasPayment !== void 0) {
+    suipay.sponsorGasPayment = offer.sponsorGasPayment;
+  }
+  if (offer.acceptedRails !== void 0)
+    suipay.acceptedRails = offer.acceptedRails;
+  if (offer.exclusionProtocolVersion !== void 0) {
+    suipay.exclusionProtocolVersion = offer.exclusionProtocolVersion;
+  }
+  if (offer.registryIdentity !== void 0)
+    suipay.registryIdentity = offer.registryIdentity;
+  return {
+    scheme: X402_SCHEME,
+    network: offer.network,
+    amount: offer.amount,
+    asset: offer.asset,
+    payTo: offer.payTo,
+    maxTimeoutSeconds: Math.max(1, Math.round((offer.expiresAt - offer.issuedAt) / 1e3)),
+    extra: {
+      paymentFlow: X402_PAYMENT_FLOW,
+      ...opts?.gasStation ? { gasStation: opts.gasStation } : {},
+      suipay
+    }
+  };
+}
 function railOf(offer) {
-  return offer.settlementRail ?? "direct";
+  const rail = offer.settlementRail ?? "direct";
+  return mintLiveRail(rail);
 }
 function decodeChallenge2(body, opts) {
   const b = body;
@@ -1691,7 +2230,7 @@ function decodeChallenge2(body, opts) {
       if (a?.scheme !== X402_SCHEME || !a?.extra?.suipay)
         continue;
       const offer = fromAccept(a, b.resource);
-      if (offer && railOf(offer) === opts.rail)
+      if (offer && railOf(offer) === mintLiveRail(opts.rail))
         return offer;
     }
     return null;
@@ -1726,13 +2265,14 @@ function fromAccept(accept, resource) {
     offer.netAmount = s.netAmount;
   if (s.platformFee !== void 0)
     offer.platformFee = s.platformFee;
-  if (s.digestVersion === 1 || s.digestVersion === 2 || s.digestVersion === 3) {
+  if (s.digestVersion === 1 || s.digestVersion === 2 || s.digestVersion === 3 || s.digestVersion === 4) {
     offer.digestVersion = s.digestVersion;
   }
   if (s.settlementRail !== void 0) {
-    if (!isSettlementRail(s.settlementRail))
+    const rail = decodeWireRail(s.settlementRail);
+    if (!rail)
       return null;
-    offer.settlementRail = s.settlementRail;
+    offer.settlementRail = rail;
   }
   if (s.serviceId !== void 0)
     offer.serviceId = s.serviceId;
@@ -1784,11 +2324,71 @@ function fromAccept(accept, resource) {
   if (s.sponsorGasPayment !== void 0) {
     offer.sponsorGasPayment = s.sponsorGasPayment;
   }
+  if (s.acceptedRails !== void 0) {
+    if (!Array.isArray(s.acceptedRails))
+      return null;
+    const rails = decodeAcceptedRails(s.acceptedRails);
+    if (!rails)
+      return null;
+    offer.acceptedRails = rails;
+  }
+  if (s.exclusionProtocolVersion !== void 0) {
+    const v = s.exclusionProtocolVersion;
+    if (typeof v !== "number" || !Number.isFinite(v))
+      return null;
+    offer.exclusionProtocolVersion = v;
+  }
+  if (s.registryIdentity !== void 0)
+    offer.registryIdentity = s.registryIdentity;
   return offer;
 }
+function encodeCredential(cred) {
+  const payload = {
+    x402Version: X402_VERSION,
+    resource: {
+      url: cred.offer.resource,
+      description: cred.offer.description,
+      mimeType: cred.offer.mimeType
+    },
+    accepted: toAccept(cred.offer),
+    payload: {
+      challengeId: cred.challengeId,
+      payer: cred.payer ?? void 0,
+      transaction: cred.txBytes,
+      signature: cred.signature
+    }
+  };
+  return utf8ToBase64(JSON.stringify(payload));
+}
+var X402_ERROR_REASONS = new Set(Object.values(X402_ERROR_REASON));
+function decodeSettlementResponse(header) {
+  const receipt = decodeReceipt2(header);
+  if (receipt)
+    return receipt;
+  try {
+    const r = JSON.parse(base64ToUtf8(header));
+    if (!r || typeof r !== "object" || r.success !== false)
+      return null;
+    if (typeof r.errorReason !== "string" || !X402_ERROR_REASONS.has(r.errorReason))
+      return null;
+    if (typeof r.network !== "string" || typeof r.transaction !== "string")
+      return null;
+    const failure = {
+      success: false,
+      errorReason: r.errorReason,
+      transaction: r.transaction,
+      network: r.network
+    };
+    if (typeof r.payer === "string")
+      failure.payer = r.payer;
+    return failure;
+  } catch {
+    return null;
+  }
+}
 function decodeReceipt2(header) {
   try {
-    const r = JSON.parse(Buffer.from(header, "base64").toString("utf8"));
+    const r = JSON.parse(base64ToUtf8(header));
     if (!r?.success || !r.transaction)
       return null;
     const receipt = {
@@ -1813,22 +2413,22 @@ function decodeReceipt2(header) {
 }
 
 // ../sdk/dist/protocol/carrier.js
-async function readChallenge(res, dialect) {
+async function readChallenge(res, dialect, opts) {
   if (dialect === "mpp") {
     const header = res.headers.get(MPP_CHALLENGE_HEADER);
-    return header ? decodeChallenge(header) : null;
+    return header ? decodeChallenge(header, opts) : null;
   }
   const headerVal = res.headers.get(X402_CHALLENGE_HEADER);
   if (headerVal) {
     try {
-      const parsed = JSON.parse(Buffer.from(headerVal, "base64").toString("utf8"));
-      const offer = decodeChallenge2(parsed);
+      const parsed = JSON.parse(new TextDecoder().decode(fromBase644(headerVal)));
+      const offer = decodeChallenge2(parsed, opts);
       if (offer)
         return offer;
     } catch {
     }
   }
-  return decodeChallenge2(await readBody(res));
+  return decodeChallenge2(await readBody(res), opts);
 }
 function readReceipt(res, dialect) {
   const header = dialect === "mpp" ? res.headers.get(MPP_RECEIPT_HEADER) : res.headers.get(X402_RESPONSE_HEADER) ?? res.headers.get(X402_RECEIPT_HEADER);
@@ -1871,7 +2471,7 @@ async function readBody(res) {
     configurable: false
   });
   if (bytes.byteLength <= MAX_INLINE_BINARY_BYTES) {
-    binary.base64 = Buffer.from(bytes).toString("base64");
+    binary.base64 = toBase643(bytes);
   }
   return binary;
 }
@@ -1923,10 +2523,10 @@ function requestBindingViolation(offer, request) {
     if (offer.intent === "subscription" && offer.bodyHash === void 0 && offer.contentType === void 0) {
       return null;
     }
-    if (offer.digestVersion !== 3) {
+    if ((offer.digestVersion ?? 1) < 3) {
       return {
         code: "OFFER_NOT_BODY_BOUND",
-        reason: "a paid POST requires an offer digest v3 that signs the request body"
+        reason: "a paid POST requires an offer digest that signs the request body"
       };
     }
     if (offer.bodyHash !== request.bodyHash) {
@@ -2157,24 +2757,74 @@ var PAY_OPERATION_ERROR_CODES = {
   /** The payment ledger reserve CAS lost (another attempt owns this id). */
   PAYMENT_ATTEMPT_IN_FLIGHT: "PAYMENT_ATTEMPT_IN_FLIGHT",
   /** The payment ledger could not persist the reservation. */
-  PAYMENT_LEDGER_FAILED: "PAYMENT_LEDGER_FAILED"
+  PAYMENT_LEDGER_FAILED: "PAYMENT_LEDGER_FAILED",
+  /** The offer's HMAC digest failed verification — tampered or wrong secret. */
+  DIGEST_INVALID: "DIGEST_INVALID",
+  /** The offer's expiry is in the past (or issuedAt/expiresAt are incoherent). */
+  OFFER_EXPIRED: "OFFER_EXPIRED",
+  /**
+   * The offer's pinned sponsor gas fields are incomplete or inconsistent
+   * (partial pin, non-numeric budget/price, empty payment) — reject before
+   * building a tx against a gas pin that cannot be honored.
+   */
+  SPONSOR_GAS_INVALID: "SPONSOR_GAS_INVALID",
+  /**
+   * The recipient / amount / payment_id embedded in the built transaction does
+   * not match the offer — the pre-sign verify-by-rebuild backstop. Nothing may
+   * be signed once this fires.
+   */
+  TX_OFFER_MISMATCH: "TX_OFFER_MISMATCH",
+  /**
+   * Open-grant x402 is refused. This is PERMANENT and architectural: an open
+   * grant does not pre-bind a recipient, so a buyer cannot verify the recipient
+   * before signing (ADR-0002 / support matrix `open × x402` = unsupported). Do
+   * not conflate with a rail that is merely not built yet.
+   */
+  UNSUPPORTED_SCOPE: "UNSUPPORTED_SCOPE",
+  /**
+   * A rail/dialect combination that is SUPPORTED by design but not yet
+   * implemented in this build — currently scoped-grant spend_account x402
+   * (the buyer credential-submit flow). Distinct from UNSUPPORTED_SCOPE so an
+   * integrator reads "coming, not yet wired" rather than "permanently refused".
+   * See docs/decisions/ADR-0047-buyer-side-x402-two-paths-one-entrypoint.md.
+   */
+  RAIL_NOT_YET_IMPLEMENTED: "RAIL_NOT_YET_IMPLEMENTED",
+  /**
+   * Grant rail is configured but required verify-kind RPC context (getObjectJson)
+   * is missing — distinct from RAIL_NOT_YET_IMPLEMENTED, which means the rail
+   * itself is not wired.
+   */
+  GRANT_VERIFY_MISCONFIGURED: "GRANT_VERIFY_MISCONFIGURED",
+  /** The request URL or method is invalid and cannot be normalized. */
+  REQUEST_INVALID: "REQUEST_INVALID",
+  /** The 402 response body stream failed while reading the challenge. */
+  CHALLENGE_READ_ERROR: "CHALLENGE_READ_ERROR",
+  /**
+   * Pre-sign transaction verification could not reach a verdict due to an RPC
+   * or chain read outage (retryable, not tampering).
+   */
+  VERIFICATION_UNAVAILABLE: "VERIFICATION_UNAVAILABLE"
 };
 var CODE_SET = new Set(Object.values(PAY_OPERATION_ERROR_CODES));
 
 // ../sdk/dist/pay-operation/operation.js
 async function resolvePayment(input, deps) {
   const { url, gatewayUrl, packageId, network, authority, assertLive } = input;
-  const { fetchImpl = fetch, preferredDialect = "mpp", validateOffer, buildPayKind } = deps;
+  const { fetchImpl = fetch, preferredDialect = "mpp", validateOffer, buildPayKind, resolveExclusionRegistry: resolveExclusionRegistry2 } = deps;
   const request = input.request ?? normalizePaidHttpRequest({ url, method: "GET" });
-  const originViolation = validateOrigin(url, gatewayUrl);
-  if (originViolation) {
-    return failed(PAY_OPERATION_ERROR_CODES.ORIGIN_MISMATCH, originViolation);
+  const originViolation2 = validateOrigin(url, gatewayUrl);
+  if (originViolation2) {
+    return failed(PAY_OPERATION_ERROR_CODES.ORIGIN_MISMATCH, originViolation2);
   }
   let response;
-  try {
-    response = await fetchImpl(url, paidRequestInit(request));
-  } catch (e) {
-    return failed(PAY_OPERATION_ERROR_CODES.RESOURCE_UNAVAILABLE, `fetch failed: ${e instanceof Error ? e.message : String(e)}`);
+  if (deps.prefetchedResponse) {
+    response = deps.prefetchedResponse;
+  } else {
+    try {
+      response = await fetchImpl(url, paidRequestInit(request));
+    } catch (e) {
+      return failed(PAY_OPERATION_ERROR_CODES.RESOURCE_UNAVAILABLE, `fetch failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
   }
   if (response.status !== 402) {
     if (response.status >= 200 && response.status < 300) {
@@ -2203,7 +2853,7 @@ async function resolvePayment(input, deps) {
     return failed(PAY_OPERATION_ERROR_CODES.REQUEST_BINDING_VIOLATED, bindingViolation.reason, challengeId);
   }
   if (!isDelegateRail(offer.settlementRail)) {
-    return failed(PAY_OPERATION_ERROR_CODES.UNSUPPORTED_RAIL, `rail ${offer.settlementRail ?? "none"} is not a spend-account rail`, challengeId);
+    return failed(PAY_OPERATION_ERROR_CODES.UNSUPPORTED_RAIL, `rail ${offer.settlementRail ?? "none"} is not a delegate rail`, challengeId);
   }
   let packageMatches;
   try {
@@ -2248,6 +2898,41 @@ async function resolvePayment(input, deps) {
     recipient: resolved.authority.recipient,
     accessMode: resolved.authority.accessMode
   };
+  let guarded;
+  if (offerRequiresGuardedSettle(offer)) {
+    const identity = parseRegistryIdentity(offer.registryIdentity);
+    if (!identity) {
+      return failed(PAY_OPERATION_ERROR_CODES.BUILD_FAILED, "guarded offer carries no valid registry identity", challengeId);
+    }
+    if (normalizeSuiAddress3(identity.packageId) !== normalizeSuiAddress3(offer.packageId)) {
+      return failed(PAY_OPERATION_ERROR_CODES.BUILD_FAILED, `guarded registry identity package ${identity.packageId} does not match offer package ${offer.packageId}`, challengeId);
+    }
+    if (!resolveExclusionRegistry2) {
+      return failed(PAY_OPERATION_ERROR_CODES.BUILD_FAILED, "a guarded delegate offer requires an exclusion registry resolver", challengeId);
+    }
+    let registryResolution;
+    try {
+      registryResolution = await resolveExclusionRegistry2({
+        directoryId: identity.directoryId,
+        packageId: offer.packageId,
+        recipient: resolved.authority.recipient
+      });
+    } catch (e) {
+      return failed(PAY_OPERATION_ERROR_CODES.BUILD_FAILED, e instanceof Error ? e.message : String(e), challengeId);
+    }
+    kindInput.exclusionDirectoryId = identity.directoryId;
+    kindInput.recipientRegistryId = registryResolution.recipientRegistryId;
+    kindInput.expiresAtMs = offer.expiresAt;
+    kindInput.exclusionDirectoryInitialSharedVersion = registryResolution.directoryInitialSharedVersion;
+    kindInput.recipientRegistryInitialSharedVersion = registryResolution.registryInitialSharedVersion;
+    guarded = {
+      exclusionDirectoryId: identity.directoryId,
+      recipientRegistryId: registryResolution.recipientRegistryId,
+      expiresAtMs: offer.expiresAt,
+      exclusionDirectoryInitialSharedVersion: registryResolution.directoryInitialSharedVersion,
+      recipientRegistryInitialSharedVersion: registryResolution.registryInitialSharedVersion
+    };
+  }
   let kindBytes;
   try {
     const result = await buildPayKind(kindInput);
@@ -2264,7 +2949,8 @@ async function resolvePayment(input, deps) {
     termsHash: tHash,
     kindBytes,
     paymentId: challengeId,
-    request
+    request,
+    ...guarded ? { guarded } : {}
   };
 }
 function failed(code, detail, paymentId) {
@@ -2314,7 +3000,11 @@ function resolveAuthority(authority, offer) {
     };
   }
   if (!offer.targetHash) {
-    return { ok: false, code: PAY_OPERATION_ERROR_CODES.POLICY_REJECTED, reason: "offer has no targetHash for scoped resolution" };
+    return {
+      ok: false,
+      code: PAY_OPERATION_ERROR_CODES.POLICY_REJECTED,
+      reason: "offer has no targetHash for scoped resolution"
+    };
   }
   const result = resolveGrantTarget(authority, offer.targetHash);
   if (!result.ok) {
@@ -2337,8 +3027,8 @@ function resolveAuthority(authority, offer) {
   };
 }
 function validateAmount(offer, resolved) {
-  const offerCoinType = normalizeStructTag4(offer.asset);
-  const grantCoinType = normalizeStructTag4(resolved.coinType);
+  const offerCoinType = normalizeStructTag5(offer.asset);
+  const grantCoinType = normalizeStructTag5(resolved.coinType);
   if (offerCoinType !== grantCoinType) {
     return {
       code: PAY_OPERATION_ERROR_CODES.COIN_TYPE_MISMATCH,
@@ -2383,9 +3073,9 @@ function validateAmount(offer, resolved) {
 // ../sdk/dist/sponsor/personal-message.js
 import { randomBytes as randomBytes2 } from "crypto";
 import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
-import { bcs as bcs2 } from "@mysten/sui/bcs";
+import { bcs as bcs3 } from "@mysten/sui/bcs";
 import { isValidPersonalMessageSignature, verifyPersonalMessageSignature } from "@mysten/sui/verify";
-import { fromBase64 as fromBase642, normalizeSuiAddress as normalizeSuiAddress4, toBase64 as toBase642 } from "@mysten/sui/utils";
+import { fromBase64 as fromBase645, normalizeSuiAddress as normalizeSuiAddress4, toBase64 as toBase644 } from "@mysten/sui/utils";
 import { Transaction as Transaction3 } from "@mysten/sui/transactions";
 var SPONSOR_PERSONAL_MESSAGE_DOMAIN = "suipay:sponsor-personal-message:v1";
 function encodeSponsorPersonalMessagePayload(payload) {
@@ -2406,20 +3096,20 @@ function encodeSponsorPersonalMessagePayload(payload) {
     throw new Error("network is required");
   const parts = [];
   const push = (u) => parts.push(u);
-  push(bcs2.vector(bcs2.u8()).serialize([...Buffer.from(payload.domain, "utf8")]).toBytes());
-  push(bcs2.vector(bcs2.u8()).serialize([...Buffer.from(payload.nonce, "utf8")]).toBytes());
-  push(bcs2.u64().serialize(BigInt(payload.expiryMs)).toBytes());
-  push(bcs2.Address.serialize(normalizeSuiAddress4(payload.delegate)).toBytes());
-  push(bcs2.Address.serialize(normalizeSuiAddress4(payload.poolId)).toBytes());
-  push(bcs2.Address.serialize(normalizeSuiAddress4(payload.grantId)).toBytes());
-  push(bcs2.vector(bcs2.u8()).serialize([...Buffer.from(payload.network, "utf8")]).toBytes());
-  push(bcs2.Address.serialize(normalizeSuiAddress4(payload.packageId)).toBytes());
-  push(bcs2.vector(bcs2.u8()).serialize([...Buffer.from(payload.requestId, "utf8")]).toBytes());
-  push(bcs2.vector(bcs2.u8()).serialize([...payload.txKindHash]).toBytes());
+  push(bcs3.vector(bcs3.u8()).serialize([...Buffer.from(payload.domain, "utf8")]).toBytes());
+  push(bcs3.vector(bcs3.u8()).serialize([...Buffer.from(payload.nonce, "utf8")]).toBytes());
+  push(bcs3.u64().serialize(BigInt(payload.expiryMs)).toBytes());
+  push(bcs3.Address.serialize(normalizeSuiAddress4(payload.delegate)).toBytes());
+  push(bcs3.Address.serialize(normalizeSuiAddress4(payload.poolId)).toBytes());
+  push(bcs3.Address.serialize(normalizeSuiAddress4(payload.grantId)).toBytes());
+  push(bcs3.vector(bcs3.u8()).serialize([...Buffer.from(payload.network, "utf8")]).toBytes());
+  push(bcs3.Address.serialize(normalizeSuiAddress4(payload.packageId)).toBytes());
+  push(bcs3.vector(bcs3.u8()).serialize([...Buffer.from(payload.requestId, "utf8")]).toBytes());
+  push(bcs3.vector(bcs3.u8()).serialize([...payload.txKindHash]).toBytes());
   return Buffer.concat(parts.map((p) => Buffer.from(p)));
 }
 function hashTransactionKindBytes(kindBytes) {
-  const raw = typeof kindBytes === "string" ? fromBase642(kindBytes) : kindBytes;
+  const raw = typeof kindBytes === "string" ? fromBase645(kindBytes) : kindBytes;
   return sha2563(raw);
 }
 function buildSponsorPersonalMessagePayload(input) {
@@ -2444,7 +3134,7 @@ async function signSponsorPersonalMessagePayload(input) {
 // ../sdk/dist/protocol/signed-request.js
 import { sha256 as sha2564 } from "@noble/hashes/sha2.js";
 import { bytesToHex as bytesToHex2 } from "@noble/hashes/utils.js";
-import { bcs as bcs3 } from "@mysten/sui/bcs";
+import { bcs as bcs4 } from "@mysten/sui/bcs";
 import { messageWithIntent } from "@mysten/sui/cryptography";
 import { isValidPersonalMessageSignature as isValidPersonalMessageSignature2, verifyPersonalMessageSignature as verifyPersonalMessageSignature2 } from "@mysten/sui/verify";
 import { normalizeSuiAddress as normalizeSuiAddress5 } from "@mysten/sui/utils";
@@ -2478,8 +3168,8 @@ function encodeBootstrapRequest(payload) {
   if (payload.domain !== BOOTSTRAP_REQUEST_DOMAIN) {
     throw new Error(`domain must be ${BOOTSTRAP_REQUEST_DOMAIN}`);
   }
-  const utf8Vec = (s) => bcs3.vector(bcs3.u8()).serialize([...Buffer.from(s, "utf8")]).toBytes();
-  const addr = (a) => bcs3.Address.serialize(normalizeSuiAddress5(a)).toBytes();
+  const utf8Vec = (s) => bcs4.vector(bcs4.u8()).serialize([...Buffer.from(s, "utf8")]).toBytes();
+  const addr = (a) => bcs4.Address.serialize(normalizeSuiAddress5(a)).toBytes();
   const parts = [
     utf8Vec(payload.domain),
     utf8Vec(payload.network),
@@ -2488,8 +3178,8 @@ function encodeBootstrapRequest(payload) {
     utf8Vec(payload.method),
     utf8Vec(payload.path),
     utf8Vec(payload.query),
-    bcs3.vector(bcs3.u8()).serialize([...hexToBytes32(payload.bodyHash)]).toBytes(),
-    bcs3.u64().serialize(BigInt(payload.timestampMs)).toBytes(),
+    bcs4.vector(bcs4.u8()).serialize([...hexToBytes32(payload.bodyHash)]).toBytes(),
+    bcs4.u64().serialize(BigInt(payload.timestampMs)).toBytes(),
     utf8Vec(payload.nonce)
   ];
   return Buffer.concat(parts.map((p) => Buffer.from(p)));
@@ -2498,8 +3188,8 @@ function encodeSignedRequest(payload) {
   if (payload.domain !== SIGNED_REQUEST_DOMAIN) {
     throw new Error(`domain must be ${SIGNED_REQUEST_DOMAIN}`);
   }
-  const utf8Vec = (s) => bcs3.vector(bcs3.u8()).serialize([...Buffer.from(s, "utf8")]).toBytes();
-  const addr = (a) => bcs3.Address.serialize(normalizeSuiAddress5(a)).toBytes();
+  const utf8Vec = (s) => bcs4.vector(bcs4.u8()).serialize([...Buffer.from(s, "utf8")]).toBytes();
+  const addr = (a) => bcs4.Address.serialize(normalizeSuiAddress5(a)).toBytes();
   const parts = [
     utf8Vec(payload.domain),
     utf8Vec(payload.network),
@@ -2509,8 +3199,8 @@ function encodeSignedRequest(payload) {
     utf8Vec(payload.method),
     utf8Vec(payload.path),
     utf8Vec(payload.query),
-    bcs3.vector(bcs3.u8()).serialize([...hexToBytes32(payload.bodyHash)]).toBytes(),
-    bcs3.u64().serialize(BigInt(payload.timestampMs)).toBytes(),
+    bcs4.vector(bcs4.u8()).serialize([...hexToBytes32(payload.bodyHash)]).toBytes(),
+    bcs4.u64().serialize(BigInt(payload.timestampMs)).toBytes(),
     utf8Vec(payload.nonce)
   ];
   return Buffer.concat(parts.map((p) => Buffer.from(p)));
@@ -2869,7 +3559,7 @@ async function readPublicSessionState(getObjectJson, grantObjectId) {
   const g = json;
   return {
     grantObjectId,
-    // Field names are the Move struct's, and SAIP-121 renamed three of them:
+    // Field names are the Move struct's; three were renamed:
     // pool_id -> account_id, session_cap -> total_budget, session_spent ->
     // total_spent. Reading the old names yielded undefined, which the grant
     // verifier then read as "this grant names no pool" and refused every
@@ -2929,6 +3619,9 @@ var bootstrapPayerGrants = bootstrapPayerSessions;
 // ../sdk/dist/delegated-signer/payer.js
 var FINALIZATION_ATTEMPTS = 20;
 var FINALIZATION_DELAY_MS = 250;
+var X402_EXPIRATION_EPOCHS = 32n;
+var X402_PRESENT_ATTEMPTS = 10;
+var X402_PRESENT_DELAY_MS = 1e3;
 function delay(ms) {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
@@ -2996,7 +3689,16 @@ var DELEGATED_PAY_ERROR_CODES = {
    * AGENT's own ceiling, and it is the check that does not need the gateway's
    * secret to be meaningful.
    */
-  SPEND_INTENT_VIOLATED: "SPEND_INTENT_VIOLATED"
+  SPEND_INTENT_VIOLATED: "SPEND_INTENT_VIOLATED",
+  /**
+   * x402 was asked for and cannot be paid from the spend account: the 402
+   * carried no x402 offer (the gateway strips it when it has no gas lease), a
+   * sponsor gas pin is missing or unreadable, or no current epoch could be read
+   * to bound the transaction. Nothing was reserved or signed.
+   */
+  X402_UNAVAILABLE: "X402_UNAVAILABLE",
+  /** The grant's scope cannot pay in the requested dialect (open-recipient over x402). */
+  UNSUPPORTED_SCOPE: "UNSUPPORTED_SCOPE"
 };
 var DELEGATED_PAY_ERROR_CODE_SET = new Set(Object.values(DELEGATED_PAY_ERROR_CODES));
 function isDelegatedPayErrorCode(value) {
@@ -3033,7 +3735,9 @@ var PUBLIC_DETAIL = {
   FINALITY_UNAVAILABLE: "no finality reader configured; refusing to sign a pay whose settlement cannot be confirmed",
   PREPARED_OFFER_DIVERGED: "settlement offer does not match the terms verified before signing",
   PREPARED_VERIFY_UNAVAILABLE: "the pre-sign verification could not be completed; no signature was produced",
-  SPEND_INTENT_VIOLATED: "offer does not match what this agent said it was buying"
+  SPEND_INTENT_VIOLATED: "offer does not match what this agent said it was buying",
+  X402_UNAVAILABLE: "offer cannot be paid over x402 from the spend account (no x402 offer, sponsor gas pin, or current epoch)",
+  UNSUPPORTED_SCOPE: "open-recipient grants cannot pay over x402"
 };
 function classifyNon402Status(status) {
   if (status >= 200 && status < 300)
@@ -3138,6 +3842,13 @@ function mapPayOpErrorToDelegated(code, detail) {
       return { code: "RESOURCE_REJECTED", detail: PUBLIC_DETAIL.RESOURCE_REJECTED };
     case PAY_OPERATION_ERROR_CODES.RESOURCE_UNAVAILABLE:
       return { code: "RESOURCE_UNAVAILABLE", detail: PUBLIC_DETAIL.RESOURCE_UNAVAILABLE };
+    case PAY_OPERATION_ERROR_CODES.DIGEST_INVALID:
+      return { code: "CHALLENGE_TAMPERED", detail: PUBLIC_DETAIL.CHALLENGE_TAMPERED };
+    case PAY_OPERATION_ERROR_CODES.OFFER_EXPIRED:
+      return { code: "CHALLENGE_EXPIRED", detail: PUBLIC_DETAIL.CHALLENGE_EXPIRED };
+    // SPONSOR_GAS_INVALID and TX_OFFER_MISMATCH fall through to POLICY_REJECTED
+    // for now; the caller that surfaces them (the tx-build/sign path) picks
+    // their final outward code when it lands.
     // REQUEST_BINDING_VIOLATED, UNSUPPORTED_RAIL, PACKAGE_MISMATCH,
     // NETWORK_MISMATCH, COIN_TYPE_MISMATCH, OVERPAY_REJECTED, UNDERPAY_REJECTED,
     // ORIGIN_MISMATCH, and any unknown code all fall through to POLICY_REJECTED.
@@ -3145,7 +3856,7 @@ function mapPayOpErrorToDelegated(code, detail) {
       return { code: "POLICY_REJECTED", detail: PUBLIC_DETAIL.POLICY_REJECTED };
   }
 }
-function sameAddress(a, b) {
+function sameAddress2(a, b) {
   try {
     return normalizeSuiAddress6(a) === normalizeSuiAddress6(b);
   } catch {
@@ -3161,7 +3872,7 @@ function atomicAmount(value) {
 }
 function sameStructTag(a, b) {
   try {
-    return normalizeStructTag5(a) === normalizeStructTag5(b);
+    return normalizeStructTag6(a) === normalizeStructTag6(b);
   } catch {
     return false;
   }
@@ -3220,7 +3931,7 @@ async function resolveSigner(input) {
     return {
       address: kp.getPublicKey().toSuiAddress(),
       async signTransaction(txBytes) {
-        const { signature } = await kp.signTransaction(fromBase643(txBytes));
+        const { signature } = await kp.signTransaction(fromBase646(txBytes));
         return signature;
       },
       async signPersonalMessage(message) {
@@ -3287,6 +3998,7 @@ async function buildSpendAccountPayKind(input) {
     throw new Error("grantInitialSharedVersion is required");
   }
   const hash = targetHashBytes(input.targetHash);
+  const guarded = resolveGuardedSettleOfflineInputs(input);
   const target = payMoveCallTarget(input.packageId, "scoped");
   const clockVersion = input.clockInitialSharedVersion?.trim() || SUI_CLOCK_INITIAL_SHARED_VERSION;
   const tx = new Transaction4();
@@ -3295,6 +4007,16 @@ async function buildSpendAccountPayKind(input) {
     target,
     typeArguments: [input.coinType],
     arguments: [
+      tx.sharedObjectRef({
+        objectId: guarded.exclusionDirectoryId,
+        initialSharedVersion: guarded.exclusionDirectoryInitialSharedVersion,
+        mutable: false
+      }),
+      tx.sharedObjectRef({
+        objectId: guarded.recipientRegistryId,
+        initialSharedVersion: guarded.recipientRegistryInitialSharedVersion,
+        mutable: true
+      }),
       tx.sharedObjectRef({
         objectId: input.poolObjectId,
         initialSharedVersion: String(input.poolInitialSharedVersion),
@@ -3310,6 +4032,7 @@ async function buildSpendAccountPayKind(input) {
       tx.pure.u64(BigInt(input.amount)),
       tx.pure.vector("u8", Array.from(input.paymentIdHash)),
       tx.pure.vector("u8", Array.from(input.termsHash)),
+      tx.pure.u64(BigInt(guarded.expiresAtMs)),
       tx.sharedObjectRef({
         objectId: SUI_CLOCK2,
         initialSharedVersion: clockVersion,
@@ -3318,7 +4041,7 @@ async function buildSpendAccountPayKind(input) {
     ]
   });
   const bytes = await tx.build({ onlyTransactionKind: true });
-  return { kindBytes: toBase643(bytes) };
+  return { kindBytes: toBase645(bytes) };
 }
 async function buildSpendAccountSettleOpenRecipientKind(input) {
   if (!input.termsHash.length)
@@ -3333,9 +4056,10 @@ async function buildSpendAccountSettleOpenRecipientKind(input) {
     throw new Error("grantInitialSharedVersion is required");
   }
   if (!input.recipient || /^0x0+$/i.test(input.recipient)) {
-    throw new Error("settle_open_recipient_payment recipient must be a non-zero address");
+    throw new Error("settle_any_recipient recipient must be a non-zero address");
   }
   const hash = targetHashBytes(input.targetHash);
+  const guarded = resolveGuardedSettleOfflineInputs(input);
   const target = payMoveCallTarget(input.packageId, "open");
   const clockVersion = input.clockInitialSharedVersion?.trim() || SUI_CLOCK_INITIAL_SHARED_VERSION;
   const tx = new Transaction4();
@@ -3344,6 +4068,16 @@ async function buildSpendAccountSettleOpenRecipientKind(input) {
     target,
     typeArguments: [input.coinType],
     arguments: [
+      tx.sharedObjectRef({
+        objectId: guarded.exclusionDirectoryId,
+        initialSharedVersion: guarded.exclusionDirectoryInitialSharedVersion,
+        mutable: false
+      }),
+      tx.sharedObjectRef({
+        objectId: guarded.recipientRegistryId,
+        initialSharedVersion: guarded.recipientRegistryInitialSharedVersion,
+        mutable: true
+      }),
       tx.sharedObjectRef({
         objectId: input.poolObjectId,
         initialSharedVersion: String(input.poolInitialSharedVersion),
@@ -3359,6 +4093,7 @@ async function buildSpendAccountSettleOpenRecipientKind(input) {
       tx.pure.vector("u8", Array.from(input.paymentIdHash)),
       tx.pure.vector("u8", Array.from(input.termsHash)),
       tx.pure.vector("u8", Array.from(hash)),
+      tx.pure.u64(BigInt(guarded.expiresAtMs)),
       tx.sharedObjectRef({
         objectId: SUI_CLOCK2,
         initialSharedVersion: clockVersion,
@@ -3367,14 +4102,14 @@ async function buildSpendAccountSettleOpenRecipientKind(input) {
     ]
   });
   const bytes = await tx.build({ onlyTransactionKind: true });
-  return { kindBytes: toBase643(bytes) };
+  return { kindBytes: toBase645(bytes) };
 }
 async function buildSpendAccountPayTx(input) {
   if (!input.gas?.payment?.length) {
     throw new Error("agent gas payment objects are required for executable pay");
   }
   const { kindBytes } = await buildSpendAccountPayKind(input);
-  const tx = Transaction4.fromKind(fromBase643(kindBytes));
+  const tx = Transaction4.fromKind(fromBase646(kindBytes));
   tx.setSender(input.delegate);
   tx.setGasOwner(input.gas.owner ?? input.delegate);
   tx.setGasBudget(BigInt(input.gas.budget ?? DEFAULT_GAS_BUDGET));
@@ -3384,7 +4119,7 @@ async function buildSpendAccountPayTx(input) {
     version: String(c.version),
     digest: c.digest
   })));
-  const txBytes = toBase643(await tx.build());
+  const txBytes = toBase645(await tx.build());
   return { txBytes, kindBytes };
 }
 async function buildSpendAccountSettleOpenRecipientTx(input) {
@@ -3392,7 +4127,7 @@ async function buildSpendAccountSettleOpenRecipientTx(input) {
     throw new Error("agent gas payment objects are required for executable pay");
   }
   const { kindBytes } = await buildSpendAccountSettleOpenRecipientKind(input);
-  const tx = Transaction4.fromKind(fromBase643(kindBytes));
+  const tx = Transaction4.fromKind(fromBase646(kindBytes));
   tx.setSender(input.delegate);
   tx.setGasOwner(input.gas.owner ?? input.delegate);
   tx.setGasBudget(BigInt(input.gas.budget ?? DEFAULT_GAS_BUDGET));
@@ -3402,23 +4137,76 @@ async function buildSpendAccountSettleOpenRecipientTx(input) {
     version: String(c.version),
     digest: c.digest
   })));
-  const txBytes = toBase643(await tx.build());
+  const txBytes = toBase645(await tx.build());
   return { txBytes, kindBytes };
 }
+function readX402GasPin(offer) {
+  const owner = offer.sponsorGasOwner?.trim();
+  const budget = atomicAmount(offer.sponsorGasBudget ?? "");
+  const price = atomicAmount(offer.sponsorGasPrice ?? "");
+  if (!owner || budget === null || price === null || budget <= 0n || price <= 0n) {
+    return null;
+  }
+  try {
+    return {
+      owner,
+      budget,
+      price,
+      payment: decodeSponsorGasPin(offer.sponsorGasPayment ?? "")
+    };
+  } catch {
+    return null;
+  }
+}
+async function buildSpendAccountX402PayTx(input) {
+  const { kindBytes } = await buildSpendAccountPayKind(input);
+  const tx = Transaction4.fromKind(fromBase646(kindBytes));
+  tx.setSender(input.delegate);
+  tx.setGasOwner(input.gas.owner);
+  tx.setGasBudget(input.gas.budget);
+  tx.setGasPrice(input.gas.price);
+  tx.setGasPayment(input.gas.payment);
+  if (input.gas.payment.length === 0) {
+    if (!input.chainIdentifier) {
+      throw new Error("address-balance sponsor gas needs a chain identifier");
+    }
+    tx.setExpiration(addressBalanceGasExpiration({
+      epoch: input.currentEpoch,
+      chainIdentifier: input.chainIdentifier,
+      nonce: input.nonce ?? randomU32()
+    }));
+  } else {
+    tx.setExpiration({ Epoch: String(input.currentEpoch + X402_EXPIRATION_EPOCHS) });
+  }
+  const txBytes = toBase645(await tx.build());
+  return { txBytes, kindBytes };
+}
+function randomU32() {
+  return globalThis.crypto.getRandomValues(new Uint32Array(1))[0];
+}
+function currentEpochReader(client) {
+  return async () => {
+    const { systemState } = await client.core.getCurrentSystemState();
+    return BigInt(systemState.epoch);
+  };
+}
+function chainIdentifierReader(client) {
+  return async () => (await client.core.getChainIdentifier()).chainIdentifier;
+}
 function assertPayTransaction(txBytes, expected) {
   let data;
   try {
-    data = Transaction4.from(fromBase643(txBytes)).getData();
+    data = Transaction4.from(fromBase646(txBytes)).getData();
   } catch {
     throw new Error("transaction is not valid Sui transaction bytes");
   }
-  if (!data.sender || !sameAddress(data.sender, expected.delegate)) {
+  if (!data.sender || !sameAddress2(data.sender, expected.delegate)) {
     throw new Error("transaction sender does not match delegate");
   }
   if (!data.commands || data.commands.length !== 1) {
     throw new Error("transaction must contain exactly one command");
   }
-  const wanted = payMoveCallTarget(expected.packageId, expected.accessMode);
+  const wanted = payMoveCallTarget(expected.packageId, expected.accessMode, expected.guarded === true);
   const cmd = data.commands[0];
   if (cmd.$kind !== "MoveCall" || !cmd.MoveCall) {
     throw new Error("transaction is not a MoveCall");
@@ -3429,7 +4217,7 @@ function assertPayTransaction(txBytes, expected) {
   }
   let expectedKind;
   try {
-    expectedKind = Transaction4.fromKind(fromBase643(expected.kindBytes)).getData();
+    expectedKind = Transaction4.fromKind(fromBase646(expected.kindBytes)).getData();
   } catch {
     throw new Error("intended pay kind baseline is invalid");
   }
@@ -3450,9 +4238,10 @@ function assertPayTransaction(txBytes, expected) {
   if (!expected.paymentIdHash.length || !expected.termsHash.length) {
     throw new Error("expected paymentIdHash and termsHash must be non-empty");
   }
+  const expectedArgc = 11;
   const args = cmd.MoveCall.arguments;
-  if (args && args.length !== 8) {
-    throw new Error(`pay expects 8 arguments; got ${args.length}`);
+  if (args && args.length !== expectedArgc) {
+    throw new Error(`pay expects ${expectedArgc} arguments; got ${args.length}`);
   }
 }
 function asValidatedReceipt(value) {
@@ -3635,13 +4424,13 @@ function spendIntentViolation(offer, intent) {
   const ceiling = atomicAmount(intent.maxAmount);
   if (offered === null || ceiling === null || offered > ceiling)
     return "amount";
-  if (intent.recipient !== void 0 && !sameAddress(offer.payTo, intent.recipient)) {
+  if (intent.recipient !== void 0 && !sameAddress2(offer.payTo, intent.recipient)) {
     return "recipient";
   }
   return null;
 }
 function preparedTermsDivergence(offer, terms) {
-  if (!sameAddress(offer.payTo, terms.recipient))
+  if (!sameAddress2(offer.payTo, terms.recipient))
     return "recipient";
   const offered = atomicAmount(offer.amount);
   const verified = atomicAmount(terms.amount);
@@ -3724,6 +4513,10 @@ async function payDelegatedSpendAccount(args) {
     logInternal(logError, "resolve authority failed", err);
     return failed2("GRANT_DENIED", PUBLIC_DETAIL.GRANT_DENIED);
   }
+  const x402Requested = args.dialect === "x402";
+  if (x402Requested && snapshot.accessMode === "open") {
+    return failed2("UNSUPPORTED_SCOPE", PUBLIC_DETAIL.UNSUPPORTED_SCOPE);
+  }
   let poolInitialSharedVersion;
   let grantInitialSharedVersion;
   let clockInitialSharedVersion;
@@ -3797,7 +4590,7 @@ async function payDelegatedSpendAccount(args) {
       throw new Error("POLICY:no_target");
     }
     try {
-      normalizeStructTag5(offer2.asset);
+      normalizeStructTag6(offer2.asset);
     } catch {
       throw new Error("POLICY:bad_asset");
     }
@@ -3817,7 +4610,15 @@ async function payDelegatedSpendAccount(args) {
       amount: input.amount,
       paymentIdHash: input.paymentIdHash,
       termsHash: input.termsHash,
-      recipient: input.recipient
+      recipient: input.recipient,
+      // Guarded settle inputs (undefined for an unguarded offer, which then
+      // builds without the exclusion objects). resolvePayment set
+      // these from the resolved exclusion registry.
+      exclusionDirectoryId: input.exclusionDirectoryId,
+      recipientRegistryId: input.recipientRegistryId,
+      exclusionDirectoryInitialSharedVersion: input.exclusionDirectoryInitialSharedVersion,
+      recipientRegistryInitialSharedVersion: input.recipientRegistryInitialSharedVersion,
+      expiresAtMs: input.expiresAtMs
     };
     if (input.accessMode === "open") {
       return buildSpendAccountSettleOpenRecipientKind(kindInput);
@@ -3825,7 +4626,7 @@ async function payDelegatedSpendAccount(args) {
     return buildSpendAccountPayKind(kindInput);
   };
   try {
-    normalizeStructTag5(snapshot.coinType);
+    normalizeStructTag6(snapshot.coinType);
   } catch {
     return failed2("POLICY_REJECTED", PUBLIC_DETAIL.POLICY_REJECTED);
   }
@@ -3839,22 +4640,37 @@ async function payDelegatedSpendAccount(args) {
   };
   const resolveDeps = {
     fetchImpl: memoizedFetch,
-    preferredDialect: "mpp",
+    preferredDialect: x402Requested ? "x402" : "mpp",
     validateOffer: validateOfferCallback,
-    buildPayKind
+    buildPayKind,
+    // Guarded offers resolve the per-recipient exclusion registry
+    // here; absent, resolvePayment fails closed (BUILD_FAILED) for such an offer
+    // and never builds an unguarded settle. Unguarded offers never call it.
+    resolveExclusionRegistry: deps.resolveExclusionRegistry
   };
   const resolution = await resolvePayment(resolveInput, resolveDeps);
   if (resolution.status === "unpaid_ok") {
     return { status: "ok", paid: false, body: resolution.body };
   }
   if (resolution.status === "failed") {
+    logInternal(logError, "resolve payment failed", {
+      code: resolution.code,
+      detail: resolution.detail
+    });
     const mapped = mapPayOpErrorToDelegated(resolution.code, resolution.detail);
     return failed2(mapped.code, mapped.detail, {
       paymentId: resolution.paymentId
     });
   }
-  const { offer, resolved: resolvedAuthority, kindBytes, paymentIdHash: payIdHash, termsHash: terms } = resolution;
+  const { offer, resolved: resolvedAuthority, kindBytes, paymentIdHash: payIdHash, termsHash: terms, guarded: guardedResolution } = resolution;
   const paymentId = resolution.paymentId;
+  const guardedBuildFields = guardedResolution ? {
+    exclusionDirectoryId: guardedResolution.exclusionDirectoryId,
+    recipientRegistryId: guardedResolution.recipientRegistryId,
+    exclusionDirectoryInitialSharedVersion: guardedResolution.exclusionDirectoryInitialSharedVersion,
+    recipientRegistryInitialSharedVersion: guardedResolution.recipientRegistryInitialSharedVersion,
+    expiresAtMs: guardedResolution.expiresAtMs
+  } : {};
   const isOpen = snapshot.accessMode === "open";
   const resolved = {
     poolObjectId: resolvedAuthority.poolObjectId,
@@ -3866,6 +4682,13 @@ async function payDelegatedSpendAccount(args) {
     recipient: resolvedAuthority.recipient
   };
   const offerDigest = offer.digest.trim();
+  let x402Terms = null;
+  if (x402Requested) {
+    x402Terms = await x402Preflight(resolution.dialect, offer, deps, logError);
+    if (!x402Terms) {
+      return failed2("X402_UNAVAILABLE", PUBLIC_DETAIL.X402_UNAVAILABLE, { paymentId });
+    }
+  }
   const ledger = deps.paymentLedger;
   if (!ledger || typeof ledger.reserve !== "function" || typeof ledger.complete !== "function") {
     return failed2("PAYMENT_LEDGER_REQUIRED", PUBLIC_DETAIL.PAYMENT_LEDGER_REQUIRED, { paymentId });
@@ -3882,7 +4705,9 @@ async function payDelegatedSpendAccount(args) {
   if (reserveOutcome.state === "done") {
     const prior = asValidatedLedgerResult(reserveOutcome.prior, paymentId);
     if (!prior) {
-      return ambiguous("PAYMENT_ATTEMPT_IN_FLIGHT", PUBLIC_DETAIL.PAYMENT_ATTEMPT_IN_FLIGHT, { paymentId });
+      return ambiguous("PAYMENT_ATTEMPT_IN_FLIGHT", PUBLIC_DETAIL.PAYMENT_ATTEMPT_IN_FLIGHT, {
+        paymentId
+      });
     }
     return {
       ...prior,
@@ -3892,10 +4717,14 @@ async function payDelegatedSpendAccount(args) {
     };
   }
   if (reserveOutcome.state === "in_flight") {
-    return ambiguous("PAYMENT_ATTEMPT_IN_FLIGHT", PUBLIC_DETAIL.PAYMENT_ATTEMPT_IN_FLIGHT, { paymentId });
+    return ambiguous("PAYMENT_ATTEMPT_IN_FLIGHT", PUBLIC_DETAIL.PAYMENT_ATTEMPT_IN_FLIGHT, {
+      paymentId
+    });
   }
   if (reserveOutcome.state !== "reserved") {
-    logInternal(logError, "payment attempt ledger reserve returned unexpected state", { state: reserveOutcome.state });
+    logInternal(logError, "payment attempt ledger reserve returned unexpected state", {
+      state: reserveOutcome.state
+    });
     return failed2("PAYMENT_LEDGER_FAILED", PUBLIC_DETAIL.PAYMENT_LEDGER_FAILED, {
       paymentId
     });
@@ -3905,27 +4734,6 @@ async function payDelegatedSpendAccount(args) {
     await releaseReservation(ledger, ownedPaymentId, logError);
     return failed2(code, detail, { paymentId });
   };
-  const gasMode = resolveGasMode(deps);
-  const execute = deps.executeTx;
-  if (gasMode === "none") {
-    return abortBeforeSign("EXECUTE_UNAVAILABLE", PUBLIC_DETAIL.EXECUTE_UNAVAILABLE);
-  }
-  if (gasMode === "agent" && !execute) {
-    return abortBeforeSign("EXECUTE_UNAVAILABLE", PUBLIC_DETAIL.EXECUTE_UNAVAILABLE);
-  }
-  if (typeof deps.getFinalizedTx !== "function") {
-    return abortBeforeSign("FINALITY_UNAVAILABLE", PUBLIC_DETAIL.FINALITY_UNAVAILABLE);
-  }
-  let signer;
-  try {
-    signer = await resolveSigner(session.signer);
-  } catch (err) {
-    logInternal(logError, "resolve signer failed", err);
-    return abortBeforeSign("SIGN_FAILED", PUBLIC_DETAIL.SIGN_FAILED);
-  }
-  if (!sameAddress(signer.address, resolved.delegateAddress)) {
-    return abortBeforeSign("POLICY_REJECTED", PUBLIC_DETAIL.POLICY_REJECTED);
-  }
   const kindBuildInput = {
     packageId: session.packageId,
     delegate: resolved.delegateAddress,
@@ -3940,8 +4748,70 @@ async function payDelegatedSpendAccount(args) {
     amount: offer.amount,
     paymentIdHash: payIdHash,
     termsHash: terms,
-    recipient: resolved.recipient
+    recipient: resolved.recipient,
+    ...guardedBuildFields
+  };
+  const expectedPay = {
+    packageId: session.packageId,
+    delegate: resolved.delegateAddress,
+    poolObjectId: resolved.poolObjectId,
+    grantObjectId: resolved.grantObjectId,
+    policyId: resolved.onChainPolicyId,
+    targetHash: resolved.targetHash,
+    amount: offer.amount,
+    paymentIdHash: payIdHash,
+    termsHash: terms,
+    coinType: resolved.coinType,
+    kindBytes,
+    accessMode: snapshot.accessMode,
+    recipient: resolved.recipient,
+    guarded: guardedResolution !== void 0
   };
+  if (x402Terms) {
+    return payX402Reserved({
+      session,
+      deps,
+      fetchImpl,
+      resourceUrl,
+      request,
+      ledger,
+      paymentId,
+      offer,
+      expected: expectedPay,
+      buildInput: {
+        ...kindBuildInput,
+        gas: x402Terms.gas,
+        currentEpoch: x402Terms.currentEpoch,
+        ...x402Terms.chainIdentifier !== void 0 ? { chainIdentifier: x402Terms.chainIdentifier } : {}
+      },
+      settlement: {
+        status: "success",
+        amount: offer.amount,
+        recipient: resolved.recipient,
+        coinType: resolved.coinType,
+        asset: offer.asset,
+        grantObjectId: resolved.grantObjectId,
+        poolObjectId: resolved.poolObjectId
+      },
+      onProgress: args.onX402Progress,
+      abort: abortBeforeSign
+    });
+  }
+  const gasMode = resolveGasMode(deps);
+  const execute = deps.executeTx;
+  if (gasMode === "none") {
+    return abortBeforeSign("EXECUTE_UNAVAILABLE", PUBLIC_DETAIL.EXECUTE_UNAVAILABLE);
+  }
+  if (gasMode === "agent" && !execute) {
+    return abortBeforeSign("EXECUTE_UNAVAILABLE", PUBLIC_DETAIL.EXECUTE_UNAVAILABLE);
+  }
+  if (typeof deps.getSettledTx !== "function") {
+    return abortBeforeSign("FINALITY_UNAVAILABLE", PUBLIC_DETAIL.FINALITY_UNAVAILABLE);
+  }
+  const signer = await resolveDelegateSigner(session.signer, resolved.delegateAddress, logError);
+  if (typeof signer === "string") {
+    return abortBeforeSign(signer, PUBLIC_DETAIL[signer]);
+  }
   let txBytes;
   let sponsoredExecuteToken;
   let sponsoredCreateDigest;
@@ -4015,7 +4885,7 @@ async function payDelegatedSpendAccount(args) {
         return abortBeforeSign("GRANT_DENIED", grantDeniedDetail(err));
       }
     }
-    const allowedPayTarget = payMoveCallTarget(session.packageId, snapshot.accessMode);
+    const allowedPayTarget = payMoveCallTarget(session.packageId, snapshot.accessMode, guardedResolution !== void 0);
     try {
       const createRes = await fetchSponsor(`${base}/api/sponsor`, {
         method: "POST",
@@ -4080,21 +4950,7 @@ async function payDelegatedSpendAccount(args) {
     }
   }
   try {
-    assertPayTransaction(txBytes, {
-      packageId: session.packageId,
-      delegate: resolved.delegateAddress,
-      poolObjectId: resolved.poolObjectId,
-      grantObjectId: resolved.grantObjectId,
-      policyId: resolved.onChainPolicyId,
-      targetHash: resolved.targetHash,
-      amount: offer.amount,
-      paymentIdHash: payIdHash,
-      termsHash: terms,
-      coinType: resolved.coinType,
-      kindBytes,
-      accessMode: snapshot.accessMode,
-      recipient: resolved.recipient
-    });
+    assertPayTransaction(txBytes, expectedPay);
   } catch (err) {
     logInternal(logError, "pre-sign pay validation failed", err);
     return abortBeforeSign(gasMode === "sponsored" ? "SPONSORED_TX_MISMATCH" : "TX_MISMATCH", gasMode === "sponsored" ? PUBLIC_DETAIL.SPONSORED_TX_MISMATCH : PUBLIC_DETAIL.TX_MISMATCH);
@@ -4166,7 +5022,7 @@ async function payDelegatedSpendAccount(args) {
       txDigest: errDigest ?? finalDigest
     }), logError);
   }
-  const getFinalized = deps.getFinalizedTx;
+  const getFinalized = deps.getSettledTx;
   let finalized = null;
   try {
     for (let attempt = 0; attempt < FINALIZATION_ATTEMPTS; attempt += 1) {
@@ -4177,7 +5033,7 @@ async function payDelegatedSpendAccount(args) {
         await delay(FINALIZATION_DELAY_MS);
     }
   } catch (err) {
-    logInternal(logError, "getFinalizedTx threw after broadcast", err);
+    logInternal(logError, "getSettledTx threw after broadcast", err);
     return completeAttempt(ledger, paymentId, ambiguous("FINALITY_AMBIGUOUS", PUBLIC_DETAIL.FINALITY_AMBIGUOUS, {
       paymentId,
       txDigest: finalDigest
@@ -4232,10 +5088,18 @@ async function payDelegatedSpendAccount(args) {
     second = await fetchImpl(resourceUrl, paidRequestInit(request, { [MPP_CREDENTIAL_HEADER]: proof }));
   } catch (err) {
     logInternal(logError, "proof presentation failed", err);
-    return completeAttempt(ledger, paymentId, ambiguous("PROOF_PRESENTATION_FAILED", PUBLIC_DETAIL.PROOF_PRESENTATION_FAILED, { paymentId, txDigest: finalDigest, settlement }), logError);
+    return completeAttempt(ledger, paymentId, ambiguous("PROOF_PRESENTATION_FAILED", PUBLIC_DETAIL.PROOF_PRESENTATION_FAILED, {
+      paymentId,
+      txDigest: finalDigest,
+      settlement
+    }), logError);
   }
   if (second.status === 503) {
-    return completeAttempt(ledger, paymentId, ambiguous(gatewayRefusedCode(second, logError), PUBLIC_DETAIL.PROOF_PRESENTATION_FAILED, { paymentId, txDigest: finalDigest, settlement }), logError);
+    return completeAttempt(ledger, paymentId, ambiguous(gatewayRefusedCode(second, logError), PUBLIC_DETAIL.PROOF_PRESENTATION_FAILED, {
+      paymentId,
+      txDigest: finalDigest,
+      settlement
+    }), logError);
   }
   let receipt = null;
   try {
@@ -4244,14 +5108,22 @@ async function payDelegatedSpendAccount(args) {
     logInternal(logError, "read receipt failed", err);
   }
   if (second.status !== 200) {
-    return completeAttempt(ledger, paymentId, ambiguous(gatewayRefusedCode(second, logError), PUBLIC_DETAIL.GATEWAY_REFUSED, { paymentId, txDigest: finalDigest, settlement }), logError);
+    return completeAttempt(ledger, paymentId, ambiguous(gatewayRefusedCode(second, logError), PUBLIC_DETAIL.GATEWAY_REFUSED, {
+      paymentId,
+      txDigest: finalDigest,
+      settlement
+    }), logError);
   }
   let body;
   try {
     body = await readBody(second);
   } catch (err) {
     logInternal(logError, "read delivery body failed", err);
-    return completeAttempt(ledger, paymentId, ambiguous("PROOF_PRESENTATION_FAILED", PUBLIC_DETAIL.PROOF_PRESENTATION_FAILED, { paymentId, txDigest: finalDigest, settlement }), logError);
+    return completeAttempt(ledger, paymentId, ambiguous("PROOF_PRESENTATION_FAILED", PUBLIC_DETAIL.PROOF_PRESENTATION_FAILED, {
+      paymentId,
+      txDigest: finalDigest,
+      settlement
+    }), logError);
   }
   return completeAttempt(ledger, paymentId, {
     status: "ok",
@@ -4263,6 +5135,195 @@ async function payDelegatedSpendAccount(args) {
     settlement
   }, logError);
 }
+async function resolveDelegateSigner(input, delegateAddress, logError) {
+  let signer;
+  try {
+    signer = await resolveSigner(input);
+  } catch (err) {
+    logInternal(logError, "resolve signer failed", err);
+    return "SIGN_FAILED";
+  }
+  return sameAddress2(signer.address, delegateAddress) ? signer : "POLICY_REJECTED";
+}
+async function x402Preflight(dialect, offer, deps, logError) {
+  if (dialect !== "x402") {
+    logInternal(logError, "x402 requested but the 402 carried no x402 offer");
+    return null;
+  }
+  const gas = readX402GasPin(offer);
+  if (!gas) {
+    logInternal(logError, "x402 offer lacks readable sponsor gas pins");
+    return null;
+  }
+  if (typeof deps.getCurrentEpoch !== "function") {
+    logInternal(logError, "x402 needs a current-epoch reader");
+    return null;
+  }
+  let currentEpoch;
+  try {
+    currentEpoch = BigInt(await deps.getCurrentEpoch());
+  } catch (err) {
+    logInternal(logError, "read current epoch failed", err);
+    return null;
+  }
+  if (gas.payment.length > 0)
+    return { gas, currentEpoch };
+  if (typeof deps.getChainIdentifier !== "function") {
+    logInternal(logError, "address-balance x402 gas needs a chain-identifier reader");
+    return null;
+  }
+  try {
+    const chainIdentifier = await deps.getChainIdentifier();
+    if (!chainIdentifier.trim())
+      throw new Error("chain identifier is blank");
+    return { gas, currentEpoch, chainIdentifier };
+  } catch (err) {
+    logInternal(logError, "read chain identifier failed", err);
+    return null;
+  }
+}
+function emitX402Progress(ctx, event) {
+  if (!ctx.onProgress)
+    return;
+  try {
+    ctx.onProgress(event);
+  } catch (err) {
+    logInternal(ctx.deps.logError, "x402 progress callback threw", err);
+  }
+}
+async function payX402Reserved(ctx) {
+  const logError = ctx.deps.logError;
+  const signer = await resolveDelegateSigner(ctx.session.signer, ctx.expected.delegate, logError);
+  if (typeof signer === "string")
+    return ctx.abort(signer, PUBLIC_DETAIL[signer]);
+  let txBytes;
+  try {
+    const build = ctx.deps.buildX402PayTx ?? buildSpendAccountX402PayTx;
+    txBytes = (await build(ctx.buildInput)).txBytes;
+  } catch (err) {
+    logInternal(logError, "x402 pay build failed", err);
+    return ctx.abort("BUILD_FAILED", PUBLIC_DETAIL.BUILD_FAILED);
+  }
+  try {
+    assertPayTransaction(txBytes, ctx.expected);
+  } catch (err) {
+    logInternal(logError, "pre-sign x402 pay validation failed", err);
+    return ctx.abort("TX_MISMATCH", PUBLIC_DETAIL.TX_MISMATCH);
+  }
+  emitX402Progress(ctx, { stage: "built", txBytes });
+  if (ctx.session.assertLive) {
+    try {
+      await ctx.session.assertLive();
+    } catch (err) {
+      logInternal(logError, "assertLive failed at sign", err);
+      return ctx.abort("GRANT_DENIED", grantDeniedDetail(err));
+    }
+  }
+  let signature;
+  try {
+    signature = await signer.signTransaction(txBytes);
+  } catch (err) {
+    logInternal(logError, "delegate sign failed", err);
+    return ctx.abort("SIGN_FAILED", PUBLIC_DETAIL.SIGN_FAILED);
+  }
+  emitX402Progress(ctx, { stage: "signed", signature });
+  let header;
+  try {
+    header = encodeCredential({
+      challengeId: ctx.offer.challengeId,
+      offer: ctx.offer,
+      txBytes,
+      signature,
+      payer: ctx.expected.delegate
+    });
+  } catch (err) {
+    logInternal(logError, "encode x402 credential failed", err);
+    return ctx.abort("BUILD_FAILED", PUBLIC_DETAIL.BUILD_FAILED);
+  }
+  return recordX402Answer(ctx, await presentX402Credential(ctx, header));
+}
+function isX402Failure(value) {
+  return value.success === false;
+}
+async function presentX402Credential(ctx, header) {
+  const attempts = ctx.deps.x402PresentAttempts ?? X402_PRESENT_ATTEMPTS;
+  const sleep = ctx.deps.sleep ?? delay;
+  let txDigest;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    emitX402Progress(ctx, { stage: "presented", header, attempt });
+    let response;
+    try {
+      response = await ctx.fetchImpl(ctx.resourceUrl, paidRequestInit(ctx.request, { [X402_PAYMENT_HEADER]: header }));
+    } catch (err) {
+      logInternal(ctx.deps.logError, "x402 credential presentation failed", err);
+      return { kind: "unresolved", txDigest };
+    }
+    const paymentResponse = response.headers.get(X402_RESPONSE_HEADER);
+    emitX402Progress(ctx, {
+      stage: "answered",
+      status: response.status,
+      paymentResponse,
+      attempt
+    });
+    const decoded = paymentResponse ? decodeSettlementResponse(paymentResponse) : null;
+    if (decoded && isX402Failure(decoded) && decoded.transaction.trim()) {
+      txDigest = decoded.transaction.trim();
+    }
+    if (response.status !== 503) {
+      return classifyX402Answer(response, decoded, {
+        challengeId: ctx.offer.challengeId,
+        txDigest,
+        firstPresentation: attempt === 1
+      });
+    }
+    if (attempt < attempts)
+      await sleep(X402_PRESENT_DELAY_MS);
+  }
+  return { kind: "unresolved", txDigest };
+}
+function classifyX402Answer(response, decoded, seen) {
+  const receipt = asValidatedReceipt(decoded);
+  if (response.ok && receipt && receipt.challengeId === seen.challengeId) {
+    return { kind: "settled", receipt, response };
+  }
+  if (seen.firstPresentation && response.status === 402 && decoded && isX402Failure(decoded) && !decoded.transaction.trim()) {
+    return { kind: "refused", response };
+  }
+  return { kind: "unresolved", txDigest: seen.txDigest };
+}
+async function recordX402Answer(ctx, answer) {
+  const { ledger, paymentId } = ctx;
+  const logError = ctx.deps.logError;
+  if (answer.kind === "unresolved") {
+    return completeAttempt(ledger, paymentId, ambiguous("EXECUTE_AMBIGUOUS", PUBLIC_DETAIL.EXECUTE_AMBIGUOUS, {
+      paymentId,
+      txDigest: answer.txDigest
+    }), logError);
+  }
+  if (answer.kind === "refused") {
+    return ctx.abort(gatewayRefusedCode(answer.response, logError), PUBLIC_DETAIL.GATEWAY_REFUSED);
+  }
+  const settlement = {
+    ...ctx.settlement,
+    txDigest: answer.receipt.txDigest
+  };
+  let body;
+  try {
+    body = await readBody(answer.response);
+  } catch (err) {
+    logInternal(logError, "read delivery body failed", err);
+    return completeAttempt(ledger, paymentId, ambiguous("PROOF_PRESENTATION_FAILED", PUBLIC_DETAIL.PROOF_PRESENTATION_FAILED, { paymentId, txDigest: settlement.txDigest, settlement }), logError);
+  }
+  return completeAttempt(ledger, paymentId, {
+    status: "ok",
+    paid: true,
+    body,
+    receipt: answer.receipt,
+    txDigest: settlement.txDigest,
+    paymentId,
+    settlement
+  }, logError);
+}
 function extractDigestFromError(err) {
   if (!err || typeof err !== "object")
     return void 0;
@@ -4279,9 +5340,35 @@ function settleOpenRecipientTarget(packageId) {
   const fn = spendAccountDebitFunction({ accessMode: "open" });
   return `${normalizeSuiAddress6(packageId)}::spend_account::${fn}`;
 }
-function payMoveCallTarget(packageId, accessMode = "scoped") {
+function payMoveCallTarget(packageId, accessMode = "scoped", _guarded = false) {
   return accessMode === "open" ? settleOpenRecipientTarget(packageId) : payTarget(packageId);
 }
+function resolveGuardedSettleOfflineInputs(input) {
+  const core = [input.exclusionDirectoryId, input.recipientRegistryId, input.expiresAtMs];
+  const present = core.filter((v) => v !== void 0).length;
+  if (present !== 3) {
+    throw new Error("guarded settle requires exclusionDirectoryId, recipientRegistryId and expiresAtMs together (all or none)");
+  }
+  const expires = BigInt(input.expiresAtMs);
+  if (expires <= 0n) {
+    throw new Error("guarded settle expiresAtMs must be a positive epoch-ms value");
+  }
+  if (/^0x0+$/i.test(input.exclusionDirectoryId) || /^0x0+$/i.test(input.recipientRegistryId)) {
+    throw new Error("guarded settle directory and registry ids must be non-zero");
+  }
+  const dirVer = input.exclusionDirectoryInitialSharedVersion;
+  const regVer = input.recipientRegistryInitialSharedVersion;
+  if (!dirVer || !String(dirVer).trim() || !regVer || !String(regVer).trim()) {
+    throw new Error("guarded offline settle requires directory and registry initial shared versions");
+  }
+  return {
+    exclusionDirectoryId: input.exclusionDirectoryId,
+    recipientRegistryId: input.recipientRegistryId,
+    exclusionDirectoryInitialSharedVersion: String(dirVer),
+    recipientRegistryInitialSharedVersion: String(regVer),
+    expiresAtMs: input.expiresAtMs
+  };
+}
 var PreparedVerificationUnavailableError = class extends Error {
   code = DELEGATED_PAY_ERROR_CODES.PREPARED_VERIFY_UNAVAILABLE;
   constructor(message, options) {
@@ -4299,17 +5386,42 @@ function preparedPureBytes(input) {
   if (!input || input.$kind !== "Pure" || !input.Pure?.bytes)
     return null;
   try {
-    return fromBase643(input.Pure.bytes);
+    return fromBase646(input.Pure.bytes);
   } catch {
     return null;
   }
 }
+function preparedPureVectorU8(input) {
+  const raw = preparedPureBytes(input);
+  try {
+    return Uint8Array.from(bcs5.vector(bcs5.u8()).parse(raw));
+  } catch {
+  }
+  return null;
+}
+function sameBytes(a, b) {
+  return Buffer.from(a).equals(Buffer.from(b));
+}
+function toHashBytes(val) {
+  if (typeof val === "string") {
+    const clean = val.startsWith("0x") ? val.slice(2) : val;
+    return Uint8Array.from(Buffer.from(clean, "hex"));
+  }
+  return val;
+}
+function toTargetHashBytes(val) {
+  if (typeof val === "string") {
+    const clean = val.startsWith("0x") ? val.slice(2) : val;
+    return targetHashBytes(clean);
+  }
+  return val;
+}
 function preparedPureAddress(input) {
   const raw = preparedPureBytes(input);
   if (!raw)
     return null;
   try {
-    return normalizeSuiAddress6(bcs4.Address.parse(raw));
+    return normalizeSuiAddress6(bcs5.Address.parse(raw));
   } catch {
     return null;
   }
@@ -4319,7 +5431,7 @@ function preparedPureU64(input) {
   if (!raw)
     return null;
   try {
-    return BigInt(bcs4.u64().parse(raw));
+    return BigInt(bcs5.u64().parse(raw));
   } catch {
     return null;
   }
@@ -4339,9 +5451,12 @@ function preparedSharedObjectId(input) {
 }
 async function verifyPreparedSettlementKind(input) {
   const accessMode = input.expected.accessMode ?? "open";
+  if (accessMode !== "scoped" && accessMode !== "open") {
+    throw new Error(`unsupported accessMode: ${String(accessMode)}`);
+  }
   let data;
   try {
-    data = Transaction4.fromKind(fromBase643(input.kindBytes)).getData();
+    data = Transaction4.fromKind(fromBase646(input.kindBytes)).getData();
   } catch {
     throw new Error("prepared transaction is not a valid settlement kind");
   }
@@ -4365,16 +5480,25 @@ async function verifyPreparedSettlementKind(input) {
       return void 0;
     return inputs[idx];
   };
-  const grantObjectId = preparedSharedObjectId(resolve(1));
+  const poolObjectId = preparedSharedObjectId(resolve(2));
+  if (input.expected.poolObjectId) {
+    if (!poolObjectId || !sameAddress2(poolObjectId, input.expected.poolObjectId)) {
+      throw new Error(`prepared pool ${poolObjectId ?? "(missing)"} does not match expected pool ${input.expected.poolObjectId}`);
+    }
+  }
+  const grantObjectId = preparedSharedObjectId(resolve(3));
   if (!grantObjectId) {
     throw new Error("prepared transaction does not name a grant object");
   }
+  if (input.expected.grantObjectId && !sameAddress2(grantObjectId, input.expected.grantObjectId)) {
+    throw new Error(`prepared grant ${grantObjectId} does not match expected grant ${input.expected.grantObjectId}`);
+  }
   if (accessMode === "open") {
-    const recipient = preparedPureAddress(resolve(2));
-    if (!recipient || !sameAddress(recipient, input.expected.recipient)) {
+    const recipient = preparedPureAddress(resolve(4));
+    if (!recipient || !sameAddress2(recipient, input.expected.recipient)) {
       throw new Error(`prepared recipient ${recipient ?? "(missing)"} does not match the requested recipient`);
     }
-    const amount = preparedPureU64(resolve(3));
+    const amount = preparedPureU64(resolve(5));
     let expectedAmount;
     try {
       expectedAmount = BigInt(input.expected.amount);
@@ -4385,7 +5509,21 @@ async function verifyPreparedSettlementKind(input) {
       throw new Error(`prepared amount ${amount ?? "(missing)"} does not match the requested amount`);
     }
   } else {
-    const amount = preparedPureU64(resolve(4));
+    if (input.expected.onChainPolicyId !== void 0) {
+      const policyId = preparedPureU64(resolve(4));
+      const expectedPolicyId = BigInt(input.expected.onChainPolicyId);
+      if (policyId !== expectedPolicyId) {
+        throw new Error(`prepared policy_id ${policyId ?? "(missing)"} does not match expected onChainPolicyId`);
+      }
+    }
+    if (input.expected.targetHash) {
+      const targetHash = preparedPureVectorU8(resolve(5));
+      const expectedBytes = toTargetHashBytes(input.expected.targetHash);
+      if (!targetHash || !sameBytes(targetHash, expectedBytes)) {
+        throw new Error("prepared target_hash does not match expected targetHash");
+      }
+    }
+    const amount = preparedPureU64(resolve(6));
     let expectedAmount;
     try {
       expectedAmount = BigInt(input.expected.amount);
@@ -4395,6 +5533,20 @@ async function verifyPreparedSettlementKind(input) {
     if (amount === null || amount !== expectedAmount) {
       throw new Error(`prepared amount ${amount ?? "(missing)"} does not match the requested amount`);
     }
+    if (input.expected.paymentIdHash) {
+      const paymentIdHash2 = preparedPureVectorU8(resolve(7));
+      const expectedBytes = toHashBytes(input.expected.paymentIdHash);
+      if (!paymentIdHash2 || !sameBytes(paymentIdHash2, expectedBytes)) {
+        throw new Error("prepared payment_id_hash does not match expected paymentIdHash");
+      }
+    }
+    if (input.expected.termsHash) {
+      const termsHash2 = preparedPureVectorU8(resolve(8));
+      const expectedBytes = toHashBytes(input.expected.termsHash);
+      if (!termsHash2 || !sameBytes(termsHash2, expectedBytes)) {
+        throw new Error("prepared terms_hash does not match expected termsHash");
+      }
+    }
   }
   let grant;
   try {
@@ -4405,9 +5557,12 @@ async function verifyPreparedSettlementKind(input) {
   if (!grant) {
     throw new Error("unsigned getObject could not read the named grant");
   }
-  if (!grant.delegateAddress || !sameAddress(grant.delegateAddress, input.expected.delegateAddress)) {
+  if (!grant.delegateAddress || !sameAddress2(grant.delegateAddress, input.expected.delegateAddress)) {
     throw new Error(`grant delegate ${grant.delegateAddress ?? "(missing)"} does not match the agent address`);
   }
+  if (input.expected.poolObjectId && grant.poolObjectId && !sameAddress2(grant.poolObjectId, input.expected.poolObjectId)) {
+    throw new Error(`grant pool ${grant.poolObjectId} does not match expected pool ${input.expected.poolObjectId}`);
+  }
 }
 function createMemoryLedger() {
   const map = /* @__PURE__ */ new Map();
@@ -4457,10 +5612,10 @@ function createMemoryLedger() {
 }
 
 // src/auth.ts
-import { dirname, join as join2 } from "path";
+import { dirname as dirname2, join as join3 } from "path";
 import {
   mkdirSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   renameSync,
   chmodSync,
   unlinkSync,
@@ -4472,17 +5627,75 @@ import {
 } from "fs";
 import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
 import { Ed25519Keypair as Ed25519Keypair2 } from "@mysten/sui/keypairs/ed25519";
-import { fromBase64 as fromBase644 } from "@mysten/sui/utils";
+import { fromBase64 as fromBase647 } from "@mysten/sui/utils";
 import { bytesToHex as bytesToHex4 } from "@noble/hashes/utils.js";
 
 // src/config.ts
 import { homedir } from "os";
-import { join } from "path";
+import { join as join2 } from "path";
 import { SuiGrpcClient as SuiGrpcClient2 } from "@mysten/sui/grpc";
 import { normalizeSuiAddress as normalizeSuiAddress7 } from "@mysten/sui/utils";
+
+// src/hosted-defaults.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var MCP_LOCAL_GATEWAY_URL = "https://gateway-dev-ba84.up.railway.app";
+var MCP_LOCAL_CONSOLE_URL = "https://suipay-dev.up.railway.app";
+var MCP_DEV_GATEWAY_URL = "https://gateway-dev-ba84.up.railway.app";
+var MCP_DEV_CONSOLE_URL = "https://suipay-dev.up.railway.app";
+var MCP_PROD_GATEWAY_URL = "https://gateway.suipay.dev";
+var MCP_PROD_CONSOLE_URL = "https://www.sui.io/agentpayments";
+var MCP_CHANNEL_DEFAULTS = {
+  local: { gatewayUrl: MCP_LOCAL_GATEWAY_URL, consoleUrl: MCP_LOCAL_CONSOLE_URL },
+  dev: { gatewayUrl: MCP_DEV_GATEWAY_URL, consoleUrl: MCP_DEV_CONSOLE_URL },
+  prod: { gatewayUrl: MCP_PROD_GATEWAY_URL, consoleUrl: MCP_PROD_CONSOLE_URL }
+};
+function isNodeModulesInstall(moduleUrl) {
+  const text2 = moduleUrl.replace(/\\/g, "/");
+  if (text2.includes("/packages/mcp/")) return false;
+  return text2.includes("/node_modules/");
+}
+function detectMcpDefaultChannel(opts) {
+  if (!isNodeModulesInstall(opts.moduleUrl)) return "local";
+  if (typeof opts.version === "string" && opts.version.includes("-dev.")) return "dev";
+  if (!opts.version) return "local";
+  return "prod";
+}
+function readOwnPackageVersion(moduleUrl = import.meta.url) {
+  let dir = dirname(fileURLToPath(moduleUrl));
+  for (let i = 0; i < 6; i += 1) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+        if (pkg.name === "@cmdoss/suipay-mcp" && typeof pkg.version === "string") {
+          return pkg.version;
+        }
+      } catch {
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "";
+}
+function resolveMcpHostedDefaults(opts = {}) {
+  const env = opts.env ?? process.env;
+  const moduleUrl = opts.moduleUrl ?? import.meta.url;
+  const version = opts.version ?? readOwnPackageVersion(moduleUrl);
+  const defaults = MCP_CHANNEL_DEFAULTS[detectMcpDefaultChannel({ moduleUrl, version })];
+  return {
+    gatewayUrl: env.SUIPAY_GATEWAY_URL ?? defaults.gatewayUrl,
+    consoleUrl: env.SUIPAY_CONSOLE_URL ?? defaults.consoleUrl
+  };
+}
+
+// src/config.ts
 function mcpCredentialsPath() {
   const home = process.env.HOME ?? process.env.USERPROFILE ?? homedir();
-  return join(home, ".suipay", "credentials.json");
+  return join2(home, ".suipay", "credentials.json");
 }
 var MCP_TARGET_PRESETS = {
   dev: {
@@ -4490,7 +5703,7 @@ var MCP_TARGET_PRESETS = {
     gatewayUrl: "https://gateway-dev-ba84.up.railway.app"
   },
   local: {
-    consoleUrl: "http://localhost:3000",
+    consoleUrl: "https://suipay-dev.up.railway.app",
     gatewayUrl: "http://127.0.0.1:4340"
   }
 };
@@ -4580,12 +5793,15 @@ function sameMcpGateway(a, b) {
 }
 function loadMcpConfig(env = process.env, argv = []) {
   const network = env.SUIPAY_NETWORK ?? "testnet";
-  const target = resolveMcpTarget(env, argv);
-  const preset = MCP_TARGET_PRESETS[target];
-  const gatewayUrl = env.SUIPAY_GATEWAY_URL?.trim() || preset.gatewayUrl;
-  const consoleUrl = env.SUIPAY_CONSOLE_URL?.trim() || preset.consoleUrl;
+  const explicit = parseMcpTargetFlag(argv) ?? parseMcpTargetName(env.SUIPAY_MCP_TARGET);
+  const hosted = resolveMcpHostedDefaults({ env });
+  const preset = explicit ? MCP_TARGET_PRESETS[explicit] : null;
+  const gatewayUrl = preset ? env.SUIPAY_GATEWAY_URL?.trim() || preset.gatewayUrl : hosted.gatewayUrl;
+  const consoleUrl = preset ? env.SUIPAY_CONSOLE_URL?.trim() || preset.consoleUrl : hosted.consoleUrl;
+  const rawDir = env.SUIPAY_EXCLUSION_DIRECTORY_OBJECT_ID?.trim();
+  if (rawDir) assertValidPackageId("SUIPAY_EXCLUSION_DIRECTORY_OBJECT_ID", rawDir);
   return {
-    target,
+    ...explicit ? { target: explicit } : {},
     consoleUrl,
     gatewayUrl,
     rpcUrl: env.SUIPAY_RPC_URL ?? GRPC_URLS[network],
@@ -4596,9 +5812,42 @@ function loadMcpConfig(env = process.env, argv = []) {
     sponsorUrl: env.SUIPAY_SPONSOR_URL ?? `${gatewayUrl.replace(/\/$/, "")}/api/sponsor`,
     minFunded: BigInt(env.SUIPAY_MIN_FUNDED ?? "0"),
     minMaxPerPayment: BigInt(env.SUIPAY_MIN_MAX_PER_PAYMENT ?? "0"),
-    label: env.SUIPAY_LABEL ?? "SuiPay MCP"
+    label: env.SUIPAY_LABEL ?? "SuiPay MCP",
+    exclusionDirectoryObjectId: rawDir || null
   };
 }
+var OBJECT_ID = /^0x(?:[0-9a-fA-F]{1,64})$/;
+async function publishedExclusionDirectoryId(gatewayUrl, fetchImpl = fetch) {
+  let url;
+  try {
+    url = new URL("/v1/delegate/deployment", gatewayUrl).toString();
+  } catch {
+    return null;
+  }
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "GET",
+      redirect: "manual",
+      signal: AbortSignal.timeout(1500)
+    });
+  } catch {
+    return null;
+  }
+  if (response.status !== 200) return null;
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return null;
+  }
+  const id = body && typeof body === "object" && "exclusionDirectoryObjectId" in body ? body.exclusionDirectoryObjectId : void 0;
+  if (typeof id !== "string" || !OBJECT_ID.test(id.trim())) return null;
+  return id.trim();
+}
+function rpcClient(cfg) {
+  return new SuiGrpcClient2({ network: cfg.network, baseUrl: cfg.rpcUrl });
+}
 
 // src/crypto.ts
 import { getPublicKeyAsync, utils } from "@noble/ed25519";
@@ -4626,7 +5875,7 @@ function credsPath() {
   return mcpCredentialsPath();
 }
 function credsDir() {
-  return dirname(credsPath());
+  return dirname2(credsPath());
 }
 var HEX64 = /^[0-9a-fA-F]{64}$/;
 var ADDR = /^0x[0-9a-fA-F]{64}$/;
@@ -4657,7 +5906,7 @@ function readCredentialsJson() {
   const path = credsPath();
   let raw;
   try {
-    raw = readFileSync(path, "utf8");
+    raw = readFileSync2(path, "utf8");
   } catch (error2) {
     const code = error2.code;
     if (code === "ENOENT" || code === "ENOTDIR") return null;
@@ -4699,7 +5948,7 @@ function fsyncDir(dir) {
   }
 }
 function writeTmpCredentials(dir, payload) {
-  const tmp = join2(dir, `.credentials.${process.pid}.${randomSuffix()}.tmp`);
+  const tmp = join3(dir, `.credentials.${process.pid}.${randomSuffix()}.tmp`);
   const fd = openSync(tmp, "w", 384);
   try {
     writeSync(fd, JSON.stringify(payload, null, 2));
@@ -4774,7 +6023,7 @@ function walletFromSeedHex(seedHex) {
   return {
     address: kp.getPublicKey().toSuiAddress(),
     async signTransaction(txBytes) {
-      const { signature } = await kp.signTransaction(fromBase644(txBytes));
+      const { signature } = await kp.signTransaction(fromBase647(txBytes));
       return signature;
     }
   };
@@ -4791,7 +6040,7 @@ function walletFromEnvSecret(raw) {
   return {
     address: kp.getPublicKey().toSuiAddress(),
     async signTransaction(txBytes) {
-      const { signature } = await kp.signTransaction(fromBase644(txBytes));
+      const { signature } = await kp.signTransaction(fromBase647(txBytes));
       return signature;
     }
   };
@@ -4888,9 +6137,29 @@ function recordFromKeypair(kp, opts = {}, existing, operatorSecret) {
   };
 }
 var ENV_KEY_MISMATCH = "SUIPAY_MCP_KEY does not match the stored delegate key - refusing to overwrite";
+function signingMaterial(parsed) {
+  if (!parsed || typeof parsed !== "object") return null;
+  if (isLocalSigningKeyRecord(parsed)) return parsed;
+  const c = parsed;
+  if (typeof c.delegatePrivateKey !== "string" || !HEX64.test(c.delegatePrivateKey) || typeof c.delegatePublicKeyHex !== "string" || !HEX64.test(c.delegatePublicKeyHex) || typeof c.delegateAddress !== "string" || !ADDR.test(c.delegateAddress)) {
+    return null;
+  }
+  const label = typeof c.label === "string" ? c.label.trim() : "";
+  return {
+    version: 2,
+    delegatePrivateKey: c.delegatePrivateKey,
+    delegatePublicKeyHex: c.delegatePublicKeyHex,
+    delegateAddress: c.delegateAddress,
+    createdAt: typeof c.createdAt === "string" && c.createdAt ? c.createdAt : (/* @__PURE__ */ new Date(0)).toISOString(),
+    ...isHttpUrl(c.gatewayUrl) ? { gatewayUrl: c.gatewayUrl } : {},
+    ...label ? { label } : {}
+  };
+}
 function existingRecordForEnv(parsed) {
   if (parsed === null) return null;
-  if (isLocalSigningKeyRecord(parsed) || isValid(parsed)) return parsed;
+  if (isValid(parsed)) return parsed;
+  const material = signingMaterial(parsed);
+  if (material) return material;
   throw new Error(
     `credentials file at ${credsPath()} failed schema validation - refusing to continue`
   );
@@ -4928,16 +6197,25 @@ async function ensureLocalSigningKey(opts = {}) {
   }
   const parsed = readCredentialsJson();
   if (parsed !== null) {
-    if (isLocalSigningKeyRecord(parsed)) {
-      return identityFromStored(
-        parsed.delegatePrivateKey,
-        parsed.delegatePublicKeyHex,
-        parsed.delegateAddress
-      );
-    }
-    if (isValid(parsed)) {
+    if (isValid(parsed) && !isLocalSigningKeyRecord(parsed)) {
       return rewriteV1ToLocalSigningKey(parsed, opts);
     }
+    const material = signingMaterial(parsed);
+    if (material) {
+      const identity = identityFromStored(
+        material.delegatePrivateKey,
+        material.delegatePublicKeyHex,
+        material.delegateAddress
+      );
+      if (!isLocalSigningKeyRecord(parsed)) {
+        const label = opts.label?.trim() || material.label;
+        writeCredentialsFile({
+          ...material,
+          ...label ? { label } : {}
+        });
+      }
+      return identity;
+    }
     throw new Error(`credentials file at ${credsPath()} failed schema validation - refusing to continue`);
   }
   const kp = await generateKeypair();
@@ -4986,7 +6264,7 @@ function loadLocalSigner() {
   return {
     address: parsed.delegateAddress,
     async signTransaction(txBytes) {
-      const { signature } = await kp.signTransaction(fromBase644(txBytes));
+      const { signature } = await kp.signTransaction(fromBase647(txBytes));
       return signature;
     },
     async signPersonalMessage(message) {
@@ -5028,6 +6306,32 @@ function loadLocalKeypair() {
     Uint8Array.from(Buffer.from(parsed.delegatePrivateKey, "hex"))
   );
 }
+function replaceLocalSigningKey(input) {
+  identityFromStored(
+    input.delegatePrivateKey,
+    input.delegatePublicKeyHex,
+    input.delegateAddress
+  );
+  const parsed = readCredentialsJson();
+  let gatewayUrl;
+  let label;
+  if (parsed && typeof parsed === "object") {
+    const record = parsed;
+    if (isHttpUrl(record.gatewayUrl)) gatewayUrl = record.gatewayUrl;
+    if (typeof record.label === "string" && record.label.trim()) {
+      label = record.label.trim();
+    }
+  }
+  writeCredentialsFile({
+    version: 2,
+    delegatePrivateKey: input.delegatePrivateKey,
+    delegatePublicKeyHex: input.delegatePublicKeyHex,
+    delegateAddress: input.delegateAddress,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...gatewayUrl ? { gatewayUrl } : {},
+    ...label ? { label } : {}
+  });
+}
 function persistGatewayUrl(gatewayUrl) {
   if (!isHttpUrl(gatewayUrl)) {
     throw new Error("gatewayUrl must be an http(s) origin");
@@ -5072,7 +6376,7 @@ function objectWithOwner(object) {
   }
   return { ...object.json, owner: object.owner };
 }
-function sameAddress2(a, b) {
+function sameAddress3(a, b) {
   try {
     return normalizeSuiAddress8(a) === normalizeSuiAddress8(b);
   } catch {
@@ -5088,7 +6392,7 @@ function resolveAgentHeldSettlement(cfg, spendAccountPay, env = process.env) {
   if (!secret) return null;
   const local = loadLocalSigner();
   if (!local) return null;
-  if (!sameAddress2(local.address, spendAccountPay.snapshot.delegateAddress)) {
+  if (!sameAddress3(local.address, spendAccountPay.snapshot.delegateAddress)) {
     return null;
   }
   const chain = createSpendAccountChain({
@@ -5096,7 +6400,7 @@ function resolveAgentHeldSettlement(cfg, spendAccountPay, env = process.env) {
     network: cfg.network,
     url: cfg.rpcUrl
   });
-  const finality = createSpendAccountFinalityReader({ client: chain.client });
+  const finality = createSpendAccountSettledTxReader({ client: chain.client });
   const getObjectJson = async (objectId) => {
     const { object } = await chain.client.core.getObject({
       objectId,
@@ -5119,7 +6423,7 @@ function resolveAgentHeldSettlement(cfg, spendAccountPay, env = process.env) {
       sponsor: { sponsorUrl: cfg.gatewayUrl },
       gasMode: "sponsored",
       resolveSharedObjectVersions: (ids) => resolveSharedObjectVersionsFromGetObject(getObjectJson, ids),
-      getFinalizedTx: (digest) => finality.getFinalizedTx(digest)
+      getSettledTx: (digest) => finality.getSettledTx(digest)
     }
   };
 }
@@ -5176,9 +6480,16 @@ function toolAllowedByScope(toolName, grantedScope) {
 }
 
 // src/tools.ts
-import { isValidSuiAddress, normalizeSuiAddress as normalizeSuiAddress12 } from "@mysten/sui/utils";
+import { isValidSuiAddress, normalizeSuiAddress as normalizeSuiAddress15 } from "@mysten/sui/utils";
 
 // src/settle.ts
+function accessModeFromMoveTarget(target) {
+  const fn = target.split("::").pop() ?? "";
+  if (fn === spendAccountDebitFunction({ accessMode: "open" }) || fn === spendAccountDebitFunction({ accessMode: "open", refundable: true })) {
+    return "open";
+  }
+  return "scoped";
+}
 async function settlePreparedMcpPayment(args) {
   try {
     await verifyPreparedSettlementKind({
@@ -5188,9 +6499,9 @@ async function settlePreparedMcpPayment(args) {
         delegateAddress: args.expected.delegateAddress,
         amount: args.expected.amount,
         recipient: args.expected.recipient,
-        accessMode: args.signingRequest.submit.moveCallTarget.endsWith(
-          "settle_open_recipient_payment"
-        ) ? "open" : "scoped"
+        accessMode: accessModeFromMoveTarget(
+          args.signingRequest.submit.moveCallTarget
+        )
       },
       getObjectJson: args.getObjectJson
     });
@@ -5236,12 +6547,104 @@ async function settlePreparedMcpPayment(args) {
 }
 
 // ../sdk/dist/agent-sdk/delegate-agent.js
-import { normalizeSuiAddress as normalizeSuiAddress10 } from "@mysten/sui/utils";
+import { normalizeSuiAddress as normalizeSuiAddress11 } from "@mysten/sui/utils";
 
-// ../sdk/dist/agent-sdk/verify-prepared-settlement.js
+// ../sdk/dist/buyer-control/exclusion-registry.js
+import { bcs as bcs6 } from "@mysten/sui/bcs";
 import { normalizeSuiAddress as normalizeSuiAddress9 } from "@mysten/sui/utils";
+var ExclusionRegistryResolutionError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ExclusionRegistryResolutionError";
+  }
+};
+async function resolveExclusionRegistry(input) {
+  const directoryObjectId = typeof input.directoryObjectId === "string" ? input.directoryObjectId.trim() : "";
+  if (!directoryObjectId) {
+    throw new ExclusionRegistryResolutionError("NO_DIRECTORY", "no exclusion directory object id configured for a guarded offer");
+  }
+  let registryId;
+  try {
+    registryId = await input.reader.boundRegistryId(directoryObjectId, input.recipient);
+  } catch (err) {
+    if (err instanceof ExclusionRegistryResolutionError)
+      throw err;
+    throw new ExclusionRegistryResolutionError("REGISTRY_UNREADABLE", "could not read the exclusion directory binding for this recipient");
+  }
+  if (!registryId || !registryId.trim()) {
+    throw new ExclusionRegistryResolutionError("REGISTRY_NOT_PROVISIONED", "no RecipientRegistry is bound for this recipient in the exclusion directory");
+  }
+  const directoryInitialSharedVersion = await input.reader.initialSharedVersion(directoryObjectId);
+  if (!directoryInitialSharedVersion || !directoryInitialSharedVersion.trim()) {
+    throw new ExclusionRegistryResolutionError("DIRECTORY_VERSION_UNRESOLVED", "could not resolve the exclusion directory initial shared version");
+  }
+  const registryInitialSharedVersion = await input.reader.initialSharedVersion(registryId);
+  if (!registryInitialSharedVersion || !registryInitialSharedVersion.trim()) {
+    throw new ExclusionRegistryResolutionError("REGISTRY_VERSION_UNRESOLVED", "could not resolve the recipient registry initial shared version");
+  }
+  return {
+    recipientRegistryId: normalizeSuiAddress9(registryId),
+    directoryInitialSharedVersion,
+    registryInitialSharedVersion
+  };
+}
+function initialSharedVersionFromOwner2(owner) {
+  if (!owner || typeof owner !== "object")
+    return null;
+  const shared = owner.Shared;
+  if (shared?.initialSharedVersion != null) {
+    return String(shared.initialSharedVersion);
+  }
+  return null;
+}
+function isAbsentDynamicFieldError(err) {
+  const text2 = (err instanceof Error ? err.message : String(err)).toLowerCase();
+  if (/timeout|timed out|unavailable|econnreset|econnrefused|network|fetch failed|socket| 502| 503| 429/.test(text2)) {
+    return false;
+  }
+  return /\bnot[_ ]found\b|dynamic field not found|no such.*field/.test(text2);
+}
+function createGrpcExclusionRegistryReader(client) {
+  return {
+    async boundRegistryId(directoryObjectId, recipient) {
+      let response;
+      try {
+        response = await client.core.getDynamicField({
+          parentId: directoryObjectId,
+          name: { type: "address", bcs: bcs6.Address.serialize(recipient).toBytes() }
+        });
+      } catch (err) {
+        if (isAbsentDynamicFieldError(err))
+          return null;
+        throw new ExclusionRegistryResolutionError("REGISTRY_UNREADABLE", "could not read the exclusion directory binding for this recipient");
+      }
+      const raw = response?.dynamicField?.value?.bcs;
+      if (!raw)
+        return null;
+      try {
+        return normalizeSuiAddress9(bcs6.Address.parse(raw));
+      } catch {
+        return null;
+      }
+    },
+    async initialSharedVersion(objectId) {
+      let response;
+      try {
+        response = await client.core.getObject({ objectId });
+      } catch {
+        return null;
+      }
+      return initialSharedVersionFromOwner2(response?.object?.owner);
+    }
+  };
+}
+
+// ../sdk/dist/agent-sdk/verify-prepared-settlement.js
+import { normalizeSuiAddress as normalizeSuiAddress10 } from "@mysten/sui/utils";
 import { Transaction as Transaction5 } from "@mysten/sui/transactions";
-import { fromBase64 as fromBase645 } from "@mysten/sui/utils";
+import { fromBase64 as fromBase648 } from "@mysten/sui/utils";
 
 // ../sdk/dist/protocol/prepared-settlement.js
 var PREPARED_SETTLEMENT_VERSION = 1;
@@ -5269,6 +6672,11 @@ function asPreparedSettlement(value) {
     "coinType",
     "amount",
     "recipient",
+    "exclusionDirectoryId",
+    "recipientRegistryId",
+    "exclusionDirectoryInitialSharedVersion",
+    "recipientRegistryInitialSharedVersion",
+    "expiresAtMs",
     "payUrl"
   ];
   for (const key of strings) {
@@ -5293,6 +6701,11 @@ function asPreparedSettlement(value) {
     coinType: v.coinType,
     amount: v.amount,
     recipient: v.recipient,
+    exclusionDirectoryId: v.exclusionDirectoryId,
+    recipientRegistryId: v.recipientRegistryId,
+    exclusionDirectoryInitialSharedVersion: v.exclusionDirectoryInitialSharedVersion,
+    recipientRegistryInitialSharedVersion: v.recipientRegistryInitialSharedVersion,
+    expiresAtMs: v.expiresAtMs,
     payUrl: v.payUrl
   };
 }
@@ -5311,9 +6724,9 @@ var PreparedSettlementRejected = class extends Error {
 function reject(field, message) {
   throw new PreparedSettlementRejected(field, message);
 }
-function sameAddress3(a, b) {
+function sameAddress4(a, b) {
   try {
-    return normalizeSuiAddress9(a) === normalizeSuiAddress9(b);
+    return normalizeSuiAddress10(a) === normalizeSuiAddress10(b);
   } catch {
     return false;
   }
@@ -5324,7 +6737,7 @@ function sameCoinType(a, b) {
     if (pkg === void 0 || rest.length !== 2)
       return value.trim();
     try {
-      return `${normalizeSuiAddress9(pkg)}::${rest.join("::")}`;
+      return `${normalizeSuiAddress10(pkg)}::${rest.join("::")}`;
     } catch {
       return value.trim();
     }
@@ -5344,26 +6757,26 @@ async function verifyPreparedPayment(input) {
     reject("shape", "the 402 carried no usable prepared settlement");
   }
   const { offer, delegateAddress } = input;
-  if (!sameAddress3(prepared.sender, delegateAddress)) {
+  if (!sameAddress4(prepared.sender, delegateAddress)) {
     reject("sender", `prepared sender ${prepared.sender} is not this agent's address`);
   }
   let data;
   try {
-    data = Transaction5.from(fromBase645(prepared.transactionBytes)).getData();
+    data = Transaction5.from(fromBase648(prepared.transactionBytes)).getData();
   } catch {
     reject("transactionBytes", "prepared transaction bytes are not a Sui transaction");
   }
   const gasOwner = data.gasData?.owner;
-  if (!gasOwner || sameAddress3(gasOwner, delegateAddress)) {
+  if (!gasOwner || sameAddress4(gasOwner, delegateAddress)) {
     reject("gasOwner", "prepared transaction is not sponsored: gas would be paid by this agent");
   }
-  if (input.expectedGrantObjectId && !sameAddress3(prepared.grantObjectId, input.expectedGrantObjectId)) {
+  if (input.expectedGrantObjectId && !sameAddress4(prepared.grantObjectId, input.expectedGrantObjectId)) {
     reject("grantObjectId", `prepared settlement draws on grant ${prepared.grantObjectId}, not the one this agent resolved`);
   }
-  if (input.expectedPoolObjectId && !sameAddress3(prepared.poolObjectId, input.expectedPoolObjectId)) {
+  if (input.expectedPoolObjectId && !sameAddress4(prepared.poolObjectId, input.expectedPoolObjectId)) {
     reject("poolObjectId", `prepared settlement draws on pool ${prepared.poolObjectId}, not the one this agent resolved`);
   }
-  if (!offer.packageId || !sameAddress3(prepared.packageId, offer.packageId)) {
+  if (!offer.packageId || !sameAddress4(prepared.packageId, offer.packageId)) {
     reject("packageId", "prepared package id does not match the offer");
   }
   const wantedTarget = payMoveCallTarget(offer.packageId, prepared.accessMode);
@@ -5376,9 +6789,19 @@ async function verifyPreparedPayment(input) {
   if (!sameAmount(prepared.amount, offer.amount)) {
     reject("amount", "prepared amount does not match the offer amount");
   }
-  if (!sameAddress3(prepared.recipient, offer.payTo)) {
+  if (!sameAddress4(prepared.recipient, offer.payTo)) {
     reject("recipient", "prepared recipient does not match the offer payTo");
   }
+  const identity = parseRegistryIdentity(offer.registryIdentity);
+  if (!identity) {
+    reject("registryIdentity", "offer carries no valid registry identity for a guarded settle");
+  }
+  if (!sameAddress4(prepared.exclusionDirectoryId, identity.directoryId)) {
+    reject("exclusionDirectoryId", "prepared exclusion directory is not the one the offer committed to");
+  }
+  if (prepared.expiresAtMs !== String(offer.expiresAt)) {
+    reject("expiresAtMs", "prepared guarded expiry does not match the offer expiry");
+  }
   const targetHash = offer.targetHash?.trim();
   if (!targetHash) {
     reject("targetHash", "offer carries no targetHash to bind the settlement to");
@@ -5398,7 +6821,14 @@ async function verifyPreparedPayment(input) {
     targetHash,
     amount: offer.amount,
     paymentIdHash: paymentIdHash(offer.challengeId),
-    termsHash: termsHash(offer)
+    termsHash: termsHash(offer),
+    // Guarded-settle inputs, rebuilt from the prepared bytes and validated
+    // against the offer above.
+    exclusionDirectoryId: prepared.exclusionDirectoryId,
+    recipientRegistryId: prepared.recipientRegistryId,
+    exclusionDirectoryInitialSharedVersion: prepared.exclusionDirectoryInitialSharedVersion,
+    recipientRegistryInitialSharedVersion: prepared.recipientRegistryInitialSharedVersion,
+    expiresAtMs: prepared.expiresAtMs
   };
   let rebuilt;
   try {
@@ -5733,7 +7163,23 @@ async function fetchGatewayDeployment(options) {
       }
     };
   }
-  return { ok: true, value: { network: d.network, packageId: d.packageId } };
+  if (d.exclusionDirectoryObjectId !== void 0 && !isNonEmptyString2(d.exclusionDirectoryObjectId)) {
+    return {
+      ok: false,
+      error: {
+        code: MANIFEST_ERROR_CODES.MALFORMED_MANIFEST,
+        detail: "gateway deployment identity carries an unusable exclusionDirectoryObjectId"
+      }
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      network: d.network,
+      packageId: d.packageId,
+      ...isNonEmptyString2(d.exclusionDirectoryObjectId) ? { exclusionDirectoryObjectId: d.exclusionDirectoryObjectId } : {}
+    }
+  };
 }
 function explainBlockedGrant(raw, error2) {
   if (error2.code !== MANIFEST_ERROR_CODES.MISSING_POLICY_BINDING)
@@ -5825,7 +7271,7 @@ async function resolvePayerSession(options) {
     ...options.select ? { select: options.select } : {}
   });
   if (whole.ok)
-    return whole;
+    return { ok: true, value: { ...whole.value, deployment } };
   const data = bootstrap.data;
   const rawGrants = Array.isArray(data.grants) ? data.grants : [];
   const usable = [];
@@ -5860,11 +7306,12 @@ async function resolvePayerSession(options) {
     const pick = scoped ?? blocked[0];
     return pick ? { ok: false, error: explainBlockedGrant(pick.raw, pick.error) } : whole;
   }
-  return manifestToSession({
+  const resolved = manifestToSession({
     manifest: { ...data, grants: usable },
     signer: options.signer,
     ...options.select ? { select: options.select } : {}
   });
+  return resolved.ok ? { ok: true, value: { ...resolved.value, deployment } } : resolved;
 }
 
 // ../sdk/dist/buyer/transport.js
@@ -5894,6 +7341,15 @@ function mergeObjectEnvelope(object) {
 var SECRET_KEY_SET = new Set(FORBIDDEN_SECRET_KEYS.map((k) => k.toLowerCase()));
 
 // ../sdk/dist/agent-sdk/delegate-agent.js
+function resolveExclusionDirectoryId(explicit, discovered) {
+  return explicit?.trim() ? explicit : discovered;
+}
+function createExclusionRegistryResolver(client, exclusionDirectoryObjectId) {
+  if (!exclusionDirectoryObjectId || !exclusionDirectoryObjectId.trim())
+    return void 0;
+  const reader = createGrpcExclusionRegistryReader(client);
+  return async ({ directoryId, recipient }) => resolveExclusionRegistry({ directoryObjectId: directoryId, recipient, reader });
+}
 async function verifyGrantOnChain(input) {
   let state;
   try {
@@ -5920,10 +7376,10 @@ async function verifyGrantOnChain(input) {
     ok: false,
     error: { code: MANIFEST_ERROR_CODES.GRANT_NOT_VERIFIED, detail }
   });
-  if (!state.delegateAddress || normalizeSuiAddress10(state.delegateAddress) !== normalizeSuiAddress10(input.delegateAddress)) {
+  if (!state.delegateAddress || normalizeSuiAddress11(state.delegateAddress) !== normalizeSuiAddress11(input.delegateAddress)) {
     return notVerified(`grant ${input.grantObjectId} does not name this delegate on chain`);
   }
-  if (!state.poolObjectId || normalizeSuiAddress10(state.poolObjectId) !== normalizeSuiAddress10(input.poolObjectId)) {
+  if (!state.poolObjectId || normalizeSuiAddress11(state.poolObjectId) !== normalizeSuiAddress11(input.poolObjectId)) {
     return notVerified(`grant ${input.grantObjectId} draws on a different pool than the one resolved`);
   }
   if (state.revoked === true) {
@@ -5956,8 +7412,17 @@ async function createPayer(options) {
   const { session, binding } = resolved.value;
   const deployment = {
     network: session.network,
-    packageId: session.packageId
+    packageId: session.packageId,
+    // What the GATEWAY published, not what this payer settled on: a caller
+    // override belongs to the payer's configuration, not to the deployment it
+    // is describing. Dropping this left the field permanently undefined on the
+    // one instance a consumer can reach, so anything asking the payer whether
+    // guarded settles are available got "no" while it was doing them.
+    ...resolved.value.deployment.exclusionDirectoryObjectId ? {
+      exclusionDirectoryObjectId: resolved.value.deployment.exclusionDirectoryObjectId
+    } : {}
   };
+  const exclusionDirectoryObjectId = resolveExclusionDirectoryId(options.exclusionDirectoryObjectId, resolved.value.deployment.exclusionDirectoryObjectId);
   let network;
   try {
     network = toGrpcNetwork(deployment.network);
@@ -5987,7 +7452,7 @@ async function createPayer(options) {
       }
     };
   }
-  const finality = createSpendAccountFinalityReader({ client: chain.client });
+  const finality = createSpendAccountSettledTxReader({ client: chain.client });
   const getObjectJson = async (objectId) => {
     const { object } = await chain.client.core.getObject({
       objectId,
@@ -6010,7 +7475,20 @@ async function createPayer(options) {
     sponsor: { sponsorUrl: options.gatewayUrl },
     gasMode: "sponsored",
     resolveSharedObjectVersions: (ids) => resolveSharedObjectVersionsFromGetObject(getObjectJson, ids),
-    getFinalizedTx: finality.getFinalizedTx,
+    getSettledTx: finality.getSettledTx,
+    // A guarded offer resolves its per-recipient exclusion registry
+    // through this dep, bound to the agent's own gRPC reader. Undefined when no
+    // directory id was configured, so such an offer fails closed (BUILD_FAILED)
+    // rather than building an unguarded settle. Unguarded offers never call it.
+    ...(() => {
+      const resolve = createExclusionRegistryResolver(chain.client, exclusionDirectoryObjectId);
+      return resolve ? { resolveExclusionRegistry: resolve } : {};
+    })(),
+    // x402 bounds the transaction's expiration by the current epoch, read from
+    // the same client as every other chain read here.
+    getCurrentEpoch: currentEpochReader(chain.client),
+    // Address-balance gas (ADR-0055) binds the expiration to the chain.
+    getChainIdentifier: chainIdentifierReader(chain.client),
     ...options.offerSecret ? { offerSecret: options.offerSecret } : {},
     ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {},
     ...options.logError ? { logError: options.logError } : {}
@@ -6040,7 +7518,9 @@ async function createPayer(options) {
       cfg: { gatewayUrl: options.gatewayUrl },
       deps,
       intent: input.intent,
-      ...input.preparedTerms ? { preparedTerms: input.preparedTerms } : {}
+      ...input.preparedTerms ? { preparedTerms: input.preparedTerms } : {},
+      dialect: input.dialect,
+      onX402Progress: input.onX402Progress
     });
   }
   async function verifySettlement(prepared, offer) {
@@ -6062,6 +7542,7 @@ async function createPayer(options) {
 import { createServer } from "http";
 import { randomBytes as randomBytes3, timingSafeEqual as timingSafeEqual2 } from "crypto";
 import open from "open";
+import { Ed25519Keypair as Ed25519Keypair3 } from "@mysten/sui/keypairs/ed25519";
 var HEX642 = /^[0-9a-f]{64}$/;
 var PUBHEX = /^[0-9a-fA-F]{64}$/;
 function isPreflight(obj) {
@@ -6069,6 +7550,11 @@ function isPreflight(obj) {
   const o = obj;
   return typeof o.state === "string" && HEX642.test(o.state) && typeof o.publicKey === "string" && PUBHEX.test(o.publicKey) && typeof o.delegateAddress === "string" && /^0x[0-9a-fA-F]{64}$/.test(o.delegateAddress) && typeof o.gateway === "string" && o.gateway.length > 0;
 }
+function isAdoptKey(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  const o = obj;
+  return typeof o.state === "string" && HEX642.test(o.state) && typeof o.delegatePrivateKey === "string" && HEX642.test(o.delegatePrivateKey) && typeof o.delegatePublicKeyHex === "string" && PUBHEX.test(o.delegatePublicKeyHex) && typeof o.delegateAddress === "string" && /^0x[0-9a-fA-F]{64}$/.test(o.delegateAddress);
+}
 function isCallback(obj) {
   if (!obj || typeof obj !== "object") return false;
   const o = obj;
@@ -6193,7 +7679,7 @@ async function startStdioLogin(opts) {
         res.writeHead(code, { "content-type": type, ...SECURITY_HEADERS, ...extra });
         res.end(body);
       };
-      const okPath = url.pathname === "/preflight" || url.pathname === "/callback";
+      const okPath = url.pathname === "/preflight" || url.pathname === "/callback" || url.pathname === "/key";
       if (req.method === "OPTIONS") {
         const extra = { ...cors };
         if (okHost && okOrigin && okPath && req.headers["access-control-request-private-network"] === "true") {
@@ -6264,6 +7750,55 @@ async function startStdioLogin(opts) {
           );
           return;
         }
+        if (url.pathname === "/key") {
+          if (!preflightVerified) {
+            res.writeHead(428, {
+              "content-type": "application/json",
+              ...cors,
+              ...SECURITY_HEADERS
+            });
+            res.end(JSON.stringify({ ok: false, error: "preflight required" }));
+            return;
+          }
+          if (!isAdoptKey(parsed) || !stateEquals(parsed.state, connectState)) {
+            res.writeHead(400, {
+              "content-type": "application/json",
+              ...cors,
+              ...SECURITY_HEADERS
+            });
+            res.end(JSON.stringify({ ok: false, error: "invalid key payload" }));
+            return;
+          }
+          try {
+            const kp = Ed25519Keypair3.fromSecretKey(
+              Uint8Array.from(Buffer.from(parsed.delegatePrivateKey, "hex"))
+            );
+            const derived = kp.getPublicKey().toSuiAddress();
+            if (derived.toLowerCase() !== parsed.delegateAddress.toLowerCase()) {
+              throw new Error("address mismatch");
+            }
+            replaceLocalSigningKey({
+              delegatePrivateKey: parsed.delegatePrivateKey,
+              delegatePublicKeyHex: parsed.delegatePublicKeyHex,
+              delegateAddress: derived
+            });
+          } catch {
+            res.writeHead(400, {
+              "content-type": "application/json",
+              ...cors,
+              ...SECURITY_HEADERS
+            });
+            res.end(JSON.stringify({ ok: false, error: "key rejected" }));
+            return;
+          }
+          res.writeHead(200, {
+            "content-type": "application/json",
+            ...cors,
+            ...SECURITY_HEADERS
+          });
+          res.end(JSON.stringify({ ok: true }));
+          return;
+        }
         if (!preflightVerified) {
           res.writeHead(428, {
             "content-type": "text/html",
@@ -6346,13 +7881,43 @@ async function startStdioLogin(opts) {
 }
 
 // src/spend-account-pay.ts
-import { Transaction as Transaction6 } from "@mysten/sui/transactions";
+import { Transaction as Transaction8 } from "@mysten/sui/transactions";
 import {
-  fromBase64 as fromBase646,
-  normalizeSuiAddress as normalizeSuiAddress11,
-  toBase64 as toBase644
+  fromBase64 as fromBase6411,
+  normalizeSuiAddress as normalizeSuiAddress14,
+  toBase64 as toBase647
 } from "@mysten/sui/utils";
+
+// ../sdk/dist/pay-operation/verify-x402-offer.js
+import { normalizeStructTag as normalizeStructTag7, normalizeSuiAddress as normalizeSuiAddress12 } from "@mysten/sui/utils";
+
+// ../sdk/dist/pay-operation/verify-direct-tx.js
+import { Transaction as Transaction6 } from "@mysten/sui/transactions";
+import { bcs as bcs7 } from "@mysten/sui/bcs";
+import { fromBase64 as fromBase649, normalizeStructTag as normalizeStructTag8, normalizeSuiAddress as normalizeSuiAddress13 } from "@mysten/sui/utils";
+
+// ../sdk/dist/pay-operation/resolve-grant-x402.js
+import { Transaction as Transaction7 } from "@mysten/sui/transactions";
+import { fromBase64 as fromBase6410, toBase64 as toBase646 } from "@mysten/sui/utils";
+
+// src/spend-account-pay.ts
 var SUI_CLOCK3 = "0x6";
+var sharedObjectReaderForTests = null;
+function chainSharedObjectReader(cfg, packageId) {
+  const chain = createSpendAccountChain({
+    packageId,
+    network: cfg.network,
+    url: cfg.rpcUrl
+  });
+  return async (objectId) => {
+    const { object } = await chain.client.core.getObject({
+      objectId,
+      include: { json: true }
+    });
+    if (!object?.owner) return null;
+    return { owner: object.owner };
+  };
+}
 function traceEmitter(trace) {
   if (!trace) return () => void 0;
   const now = trace.now ?? Date.now;
@@ -6386,25 +7951,38 @@ function toHex(bytes) {
 async function buildSpendAccountPayKind2(input) {
   if (!input.termsHash.length) throw new Error("termsHash must be non-empty");
   if (!input.paymentIdHash.length) throw new Error("paymentIdHash must be non-empty");
-  const auth = defaultAuthorityForRail("delegate", input.packageId);
-  const target = `${normalizeSuiAddress11(auth.packageId)}::${auth.module}::${auth.payFunction}`;
   const hashHex = input.targetHash.replace(/^0x/i, "").toLowerCase();
   if (!/^[0-9a-f]{64}$/.test(hashHex)) throw new Error("targetHash must be 32-byte hex");
   const hash = Uint8Array.from(Buffer.from(hashHex, "hex"));
-  const tx = new Transaction6();
+  const guarded = resolveGuardedSettleOfflineInputs(input);
+  const target = payMoveCallTarget(
+    input.packageId,
+    "scoped"
+  );
+  const tx = new Transaction8();
   tx.setSender(input.delegate);
   tx.moveCall({
     target,
     typeArguments: [input.coinType],
     arguments: [
+      tx.sharedObjectRef({
+        objectId: guarded.exclusionDirectoryId,
+        initialSharedVersion: guarded.exclusionDirectoryInitialSharedVersion,
+        mutable: false
+      }),
+      tx.sharedObjectRef({
+        objectId: guarded.recipientRegistryId,
+        initialSharedVersion: guarded.recipientRegistryInitialSharedVersion,
+        mutable: true
+      }),
       tx.sharedObjectRef({
         objectId: input.poolObjectId,
-        initialSharedVersion: "1",
+        initialSharedVersion: input.poolInitialSharedVersion?.trim() || "1",
         mutable: true
       }),
       tx.sharedObjectRef({
         objectId: input.grantObjectId,
-        initialSharedVersion: "1",
+        initialSharedVersion: input.grantInitialSharedVersion?.trim() || "1",
         mutable: true
       }),
       tx.pure.u64(BigInt(input.policyId)),
@@ -6412,42 +7990,43 @@ async function buildSpendAccountPayKind2(input) {
       tx.pure.u64(BigInt(input.amount)),
       tx.pure.vector("u8", Array.from(input.paymentIdHash)),
       tx.pure.vector("u8", Array.from(input.termsHash)),
+      tx.pure.u64(BigInt(guarded.expiresAtMs)),
       tx.sharedObjectRef({
         objectId: SUI_CLOCK3,
-        initialSharedVersion: "1",
+        initialSharedVersion: input.clockInitialSharedVersion?.trim() || "1",
         mutable: false
       })
     ]
   });
   const bytes = await tx.build({ onlyTransactionKind: true });
-  return { kindBytes: toBase644(bytes) };
+  return { kindBytes: toBase647(bytes) };
 }
 function verifySpendAccountPayReconstructs(bytes, expected) {
   let data;
   try {
-    data = Transaction6.from(fromBase646(bytes)).getData();
+    data = Transaction8.from(fromBase6411(bytes)).getData();
   } catch {
     throw new Error("sponsored transaction is not valid Sui transaction bytes");
   }
-  if (!data.sender || normalizeSuiAddress11(data.sender) !== normalizeSuiAddress11(expected.delegate)) {
+  if (!data.sender || normalizeSuiAddress14(data.sender) !== normalizeSuiAddress14(expected.delegate)) {
     throw new Error("sponsored transaction sender does not match delegate");
   }
   if (!data.commands || data.commands.length !== 1) {
     throw new Error("sponsored transaction must contain exactly one command");
   }
   const auth = defaultAuthorityForRail("delegate", expected.packageId);
-  const wanted = `${normalizeSuiAddress11(auth.packageId)}::${auth.module}::${auth.payFunction}`;
+  const wanted = `${normalizeSuiAddress14(auth.packageId)}::${auth.module}::${auth.payFunction}`;
   const cmd = data.commands[0];
   if (cmd.$kind !== "MoveCall" || !cmd.MoveCall) {
     throw new Error("sponsored transaction is not a MoveCall");
   }
-  const got = `${normalizeSuiAddress11(String(cmd.MoveCall.package))}::${cmd.MoveCall.module}::${cmd.MoveCall.function}`;
+  const got = `${normalizeSuiAddress14(String(cmd.MoveCall.package))}::${cmd.MoveCall.module}::${cmd.MoveCall.function}`;
   if (got !== wanted) {
     throw new Error(`sponsored transaction does not reconstruct ${wanted}`);
   }
   let expectedKind;
   try {
-    expectedKind = Transaction6.fromKind(fromBase646(expected.kindBytes)).getData();
+    expectedKind = Transaction8.fromKind(fromBase6411(expected.kindBytes)).getData();
   } catch {
     throw new Error("sponsored transaction kind baseline invalid");
   }
@@ -6479,6 +8058,13 @@ async function prepareSpendAccountPayment(args) {
   const isOpen = session.snapshot.accessMode === "open";
   const callerBuild = deps.buildPayKind;
   const buildPayKind = async (input) => {
+    const guardedFields = {
+      exclusionDirectoryId: input.exclusionDirectoryId,
+      recipientRegistryId: input.recipientRegistryId,
+      expiresAtMs: input.expiresAtMs,
+      exclusionDirectoryInitialSharedVersion: input.exclusionDirectoryInitialSharedVersion,
+      recipientRegistryInitialSharedVersion: input.recipientRegistryInitialSharedVersion
+    };
     if (callerBuild) {
       return callerBuild({
         delegate: input.delegate,
@@ -6491,9 +8077,16 @@ async function prepareSpendAccountPayment(args) {
         paymentIdHash: input.paymentIdHash,
         termsHash: input.termsHash,
         recipient: input.recipient,
-        accessMode: input.accessMode
+        accessMode: input.accessMode,
+        ...guardedFields
       });
     }
+    const readSharedObject = deps.readSharedObject ?? sharedObjectReaderForTests ?? chainSharedObjectReader(cfg, input.packageId);
+    const versions = await resolveSharedObjectVersionsFromGetObject(readSharedObject, {
+      poolObjectId: input.poolObjectId,
+      grantObjectId: input.grantObjectId,
+      clockObjectId: SUI_CLOCK3
+    });
     if (isOpen) {
       return buildSpendAccountSettleOpenRecipientKind({
         packageId: input.packageId,
@@ -6501,13 +8094,15 @@ async function prepareSpendAccountPayment(args) {
         coinType: input.coinType,
         poolObjectId: input.poolObjectId,
         grantObjectId: input.grantObjectId,
-        poolInitialSharedVersion: "1",
-        grantInitialSharedVersion: "1",
+        poolInitialSharedVersion: versions.poolInitialSharedVersion,
+        grantInitialSharedVersion: versions.grantInitialSharedVersion,
+        clockInitialSharedVersion: versions.clockInitialSharedVersion,
         recipient: input.recipient,
         targetHash: input.targetHash,
         amount: input.amount,
         paymentIdHash: input.paymentIdHash,
-        termsHash: input.termsHash
+        termsHash: input.termsHash,
+        ...guardedFields
       });
     }
     return buildSpendAccountPayKind2({
@@ -6520,7 +8115,11 @@ async function prepareSpendAccountPayment(args) {
       targetHash: input.targetHash,
       amount: input.amount,
       paymentIdHash: input.paymentIdHash,
-      termsHash: input.termsHash
+      termsHash: input.termsHash,
+      poolInitialSharedVersion: versions.poolInitialSharedVersion,
+      grantInitialSharedVersion: versions.grantInitialSharedVersion,
+      clockInitialSharedVersion: versions.clockInitialSharedVersion,
+      ...guardedFields
     });
   };
   const rawFetch = deps.fetchImpl ?? fetch;
@@ -6540,10 +8139,20 @@ async function prepareSpendAccountPayment(args) {
     authority: session.snapshot,
     assertLive: session.assertLive
   };
+  const directorySwitch = cfg.exclusionDirectoryObjectId ? cfg.exclusionDirectoryObjectId : deps.resolveExclusionRegistry ? null : await publishedExclusionDirectoryId(cfg.gatewayUrl);
+  const resolveExclusionRegistry2 = deps.resolveExclusionRegistry ?? (directorySwitch ? (() => {
+    const reader = createGrpcExclusionRegistryReader(rpcClient(cfg));
+    return async ({ directoryId, recipient }) => resolveExclusionRegistry({
+      directoryObjectId: directoryId,
+      recipient,
+      reader
+    });
+  })() : void 0);
   const resolveDeps = {
     fetchImpl: wrappedFetch,
     preferredDialect: preferred,
-    buildPayKind
+    buildPayKind,
+    ...resolveExclusionRegistry2 ? { resolveExclusionRegistry: resolveExclusionRegistry2 } : {}
   };
   const result = await resolvePayment(resolveInput, resolveDeps);
   if (result.status === "unpaid_ok") {
@@ -6604,7 +8213,7 @@ async function prepareSpendAccountPayment(args) {
   const signingRequest = {
     unsignedKindBytes: kindBytes,
     delegateAddress: resolved.delegateAddress,
-    packageId: normalizeSuiAddress11(authority.packageId),
+    packageId: normalizeSuiAddress14(authority.packageId),
     poolObjectId: resolved.poolObjectId,
     grantObjectId: resolved.grantObjectId,
     policyId: resolved.onChainPolicyId,
@@ -6686,11 +8295,11 @@ function mapErrorCode(code) {
 }
 
 // src/discover-afford.ts
-import { normalizeStructTag as normalizeStructTag6 } from "@mysten/sui/utils";
+import { normalizeStructTag as normalizeStructTag9 } from "@mysten/sui/utils";
 function sameCoinType2(rowAsset, grantCoin) {
   if (typeof rowAsset !== "string" || !grantCoin) return false;
   try {
-    return normalizeStructTag6(rowAsset) === normalizeStructTag6(grantCoin);
+    return normalizeStructTag9(rowAsset) === normalizeStructTag9(grantCoin);
   } catch {
     return false;
   }
@@ -6872,6 +8481,59 @@ function joinDiscoverCatalog(opts) {
   return scoped ? { accessMode: "scoped", count: services.length, services, allowedTargetHashes } : { accessMode: "open", count: services.length, services };
 }
 
+// src/tool-result.ts
+import { pathToFileURL } from "url";
+
+// src/delivery-file.ts
+import { mkdirSync as mkdirSync2, writeFileSync, chmodSync as chmodSync2 } from "fs";
+import { dirname as dirname3, join as join4 } from "path";
+function mcpDeliveriesDir() {
+  return join4(dirname3(mcpCredentialsPath()), "deliveries");
+}
+var EXT = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/jpg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "image/svg+xml": ".svg",
+  "audio/mpeg": ".mp3",
+  "audio/wav": ".wav",
+  "audio/ogg": ".ogg",
+  "video/mp4": ".mp4",
+  "application/pdf": ".pdf",
+  "application/json": ".json",
+  "text/plain": ".txt"
+};
+function extensionFor(contentType) {
+  const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return EXT[type] ?? ".bin";
+}
+function fileStem(digest, challengeId) {
+  const raw = (digest ?? challengeId ?? `delivery-${Date.now()}`).trim();
+  const safe = raw.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return (safe.slice(0, 80) || `delivery-${Date.now()}`).replace(/^\.+$/, "delivery");
+}
+function saveDeliveredBody(input) {
+  if (input.bytes.byteLength === 0) return void 0;
+  const dir = mcpDeliveriesDir();
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  try {
+    chmodSync2(dir, 448);
+  } catch {
+  }
+  const path = join4(
+    dir,
+    `${fileStem(input.digest, input.challengeId)}${extensionFor(input.contentType)}`
+  );
+  writeFileSync(path, input.bytes, { mode: 384 });
+  try {
+    chmodSync2(path, 384);
+  } catch {
+  }
+  return path;
+}
+
 // src/tool-result.ts
 var MAX_MCP_IMAGE_BYTES = 5 * 1024 * 1024;
 function text(value) {
@@ -6893,6 +8555,12 @@ function closedError(code, detail) {
 function closedPayError(code, detail) {
   return error({ status: "failed", paid: false, code, detail });
 }
+function receiptChallengeId(receipt) {
+  if (!receipt || typeof receipt !== "object") return void 0;
+  const id = receipt.challengeId;
+  return typeof id === "string" && id.length > 0 ? id : void 0;
+}
+var MCP_SAVE_ERROR = "delivery file was not written; do not call pay again";
 function paidResult(result) {
   if (!isBinaryBody(result.body)) return text(result);
   const body = result.body;
@@ -6901,8 +8569,33 @@ function paidResult(result) {
     contentType: body.contentType,
     byteLength: body.byteLength
   };
+  let savedTo;
+  try {
+    savedTo = saveDeliveredBody({
+      bytes: body.bytes,
+      contentType: body.contentType,
+      digest: result.txDigest,
+      challengeId: receiptChallengeId(result.receipt)
+    });
+  } catch {
+    savedTo = void 0;
+  }
+  const payload = savedTo ? {
+    savedTo,
+    savedToUrl: pathToFileURL(savedTo).href,
+    ...result,
+    body: shape
+  } : {
+    savedTo: null,
+    saveError: MCP_SAVE_ERROR,
+    ...result,
+    body: shape
+  };
   const content = [
-    { type: "text", text: JSON.stringify({ ...result, body: shape }, null, 2) }
+    {
+      type: "text",
+      text: JSON.stringify(payload, null, 2)
+    }
   ];
   if (body.contentType.startsWith("image/") && body.bytes.byteLength > 0 && body.bytes.byteLength <= MAX_MCP_IMAGE_BYTES) {
     content.push({
@@ -6919,14 +8612,27 @@ function settlePayResult(result) {
 }
 
 // src/pay-file.ts
-import { isAbsolute } from "path";
-import { openSync as openSync2, closeSync as closeSync2, fstatSync, readFileSync as readFileSync2, constants } from "fs";
-var MCP_MAX_FILE_FIELD_BYTES = 32 * 1024;
+import { isAbsolute, dirname as dirname4, sep } from "path";
+import {
+  openSync as openSync2,
+  closeSync as closeSync2,
+  fstatSync,
+  readFileSync as readFileSync3,
+  realpathSync,
+  constants
+} from "fs";
+var JSON_WRAP_SLACK_BYTES = 256;
+var MCP_MAX_FILE_FIELD_BYTES = Math.floor(
+  (MAX_PAID_BODY_BYTES - JSON_WRAP_SLACK_BYTES) * 3 / 4
+);
 var FIELD = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
-var FORBIDDEN = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var FORBIDDEN = /* @__PURE__ */ new Set(["constructor", "prototype"]);
 function fail2(code, detail) {
   return { code, detail };
 }
+function hasLocalFileArgs(input) {
+  return input.file !== void 0 && input.file !== null || input.fileField !== void 0 && input.fileField !== null;
+}
 function parseField(value) {
   if (typeof value !== "string" || !FIELD.test(value) || FORBIDDEN.has(value)) {
     return fail2("INVALID_FILE_FIELD", "fileField must be a simple JSON key");
@@ -6942,52 +8648,126 @@ function parsePath(value) {
   }
   return value;
 }
+function parseMethod(value) {
+  if (value === void 0 || value === null) return "GET";
+  if (typeof value !== "string") {
+    return fail2("MALFORMED_REQUEST", "method must be GET or POST");
+  }
+  const upper = value.trim().toUpperCase();
+  if (upper === "GET" || upper === "POST") return upper;
+  return fail2("MALFORMED_REQUEST", "method must be GET or POST");
+}
+function inside(root, candidate) {
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  return candidate === root || candidate.startsWith(prefix);
+}
+function resolveContainedPath(raw) {
+  const rootRaw = process.env.SUIPAY_MCP_FILE_ROOT;
+  if (typeof rootRaw !== "string" || rootRaw.trim() === "") {
+    return fail2(
+      "FILE_ROOT_UNSET",
+      "file attach requires SUIPAY_MCP_FILE_ROOT to be an absolute directory"
+    );
+  }
+  if (!isAbsolute(rootRaw) || rootRaw.includes("://")) {
+    return fail2(
+      "FILE_ROOT_UNSET",
+      "SUIPAY_MCP_FILE_ROOT must be an absolute filesystem path"
+    );
+  }
+  let rootReal;
+  let fileReal;
+  try {
+    rootReal = realpathSync(rootRaw);
+  } catch {
+    return fail2("FILE_ROOT_UNSET", "SUIPAY_MCP_FILE_ROOT is not a readable directory");
+  }
+  try {
+    fileReal = realpathSync(raw);
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return fail2("FILE_NOT_FOUND", "file does not exist");
+    }
+    if (code === "EACCES") {
+      return fail2("FILE_EACCES", "file is not readable");
+    }
+    return fail2(
+      "INVALID_FILE",
+      `file could not be read (${code ?? "unknown error"})`
+    );
+  }
+  if (!inside(rootReal, fileReal)) {
+    return fail2("FILE_OUTSIDE_ROOT", "file must be under SUIPAY_MCP_FILE_ROOT");
+  }
+  const credsDir2 = dirname4(mcpCredentialsPath());
+  let credsReal = credsDir2;
+  try {
+    credsReal = realpathSync(credsDir2);
+  } catch {
+  }
+  if (inside(credsReal, fileReal)) {
+    return fail2("FILE_FORBIDDEN", "file must not be under ~/.suipay");
+  }
+  return fileReal;
+}
 function readRegularFile(path) {
+  if (constants.O_NOFOLLOW === void 0 || constants.O_NONBLOCK === void 0) {
+    return fail2("INVALID_FILE", "symlink-safe nonblocking open is unavailable on this platform");
+  }
   let fd;
   try {
-    const flags = constants.O_RDONLY | (constants.O_NOFOLLOW !== void 0 ? constants.O_NOFOLLOW : 0);
+    const flags = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
     fd = openSync2(path, flags);
     const st = fstatSync(fd);
     if (!st.isFile()) {
       return fail2("INVALID_FILE", "file must be a regular file");
     }
-    if (st.size === 0) {
-      return fail2("EMPTY_FILE", "file is empty");
-    }
     if (st.size > MCP_MAX_FILE_FIELD_BYTES) {
       return fail2(
         "FILE_TOO_LARGE",
-        `file exceeds ${MCP_MAX_FILE_FIELD_BYTES} decoded bytes`
+        `file is ${st.size} bytes; exceeds ${MCP_MAX_FILE_FIELD_BYTES} decoded bytes`
       );
     }
-    const bytes = readFileSync2(fd);
+    const bytes = readFileSync3(fd);
     if (bytes.byteLength === 0) {
       return fail2("EMPTY_FILE", "file is empty");
     }
     if (bytes.byteLength > MCP_MAX_FILE_FIELD_BYTES) {
       return fail2(
         "FILE_TOO_LARGE",
-        `file exceeds ${MCP_MAX_FILE_FIELD_BYTES} decoded bytes`
+        `file is ${bytes.byteLength} bytes; exceeds ${MCP_MAX_FILE_FIELD_BYTES} decoded bytes`
       );
     }
     return bytes;
   } catch (err) {
     const code = err.code;
-    if (code === "ENOENT") return fail2("FILE_NOT_FOUND", "file does not exist");
-    if (code === "ELOOP" || code === "EMLINK") {
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return fail2("FILE_NOT_FOUND", "file does not exist");
+    }
+    if (code === "ELOOP" || code === "EMLINK" || code === "ENXIO") {
       return fail2("INVALID_FILE", "file must be a regular file");
     }
-    return fail2("INVALID_FILE", "file could not be read");
+    if (code === "EACCES") return fail2("FILE_EACCES", "file is not readable");
+    return fail2(
+      "INVALID_FILE",
+      `file could not be read (${code ?? "unknown error"})`
+    );
   } finally {
-    if (fd !== void 0) closeSync2(fd);
+    if (fd !== void 0) {
+      try {
+        closeSync2(fd);
+      } catch {
+      }
+    }
   }
 }
 function toCanonicalBase64(bytes) {
   return Buffer.from(bytes).toString("base64");
 }
 function jsonWithLocalFile(input) {
-  const hasFile = input.file !== void 0 && input.file !== null && input.file !== "";
-  const hasField = input.fileField !== void 0 && input.fileField !== null && input.fileField !== "";
+  const hasFile = input.file !== void 0 && input.file !== null;
+  const hasField = input.fileField !== void 0 && input.fileField !== null;
   if (!hasFile && !hasField) return { json: input.json };
   if (hasFile !== hasField) {
     return {
@@ -6997,7 +8777,8 @@ function jsonWithLocalFile(input) {
       )
     };
   }
-  const method = input.method === void 0 || input.method === null || input.method === "" ? "GET" : String(input.method).trim().toUpperCase();
+  const method = parseMethod(input.method);
+  if (typeof method !== "string") return { error: method };
   if (method !== "POST") {
     return { error: fail2("INVALID_FILE_ARGS", "file is only valid on POST") };
   }
@@ -7021,7 +8802,9 @@ function jsonWithLocalFile(input) {
       )
     };
   }
-  const bytes = readRegularFile(path);
+  const contained = resolveContainedPath(path);
+  if (typeof contained !== "string") return { error: contained };
+  const bytes = readRegularFile(contained);
   if (!(bytes instanceof Uint8Array)) return { error: bytes };
   json[field] = toCanonicalBase64(bytes);
   return { json };
@@ -7063,7 +8846,7 @@ function normalizePayIntent(args) {
     if (!/^0x[0-9a-fA-F]{1,64}$/.test(raw)) {
       throw new Error("recipient must be a 0x-prefixed Sui address");
     }
-    const normalized = normalizeSuiAddress12(raw);
+    const normalized = normalizeSuiAddress15(raw);
     if (!isValidSuiAddress(normalized) || /^0x0+$/.test(normalized)) {
       throw new Error("recipient must be a non-zero Sui address");
     }
@@ -7082,7 +8865,7 @@ function intentViolation(intent, prepared) {
   if (intent.recipient) {
     let preparedRecipient;
     try {
-      preparedRecipient = normalizeSuiAddress12(prepared.recipient);
+      preparedRecipient = normalizeSuiAddress15(prepared.recipient);
     } catch {
       return "prepared payment does not name a valid recipient";
     }
@@ -7105,8 +8888,7 @@ function intentViolation(intent, prepared) {
 }
 async function pay(args, cfg, deps = {}) {
   if (!args.url) return error("url is required");
-  const hasFileArg = args.file !== void 0 && args.file !== null && args.file !== "" || args.fileField !== void 0 && args.fileField !== null && args.fileField !== "";
-  if (hasFileArg && deps.auth) {
+  if (hasLocalFileArgs(args) && deps.transport === "http") {
     return closedPayError(
       "FILE_STDIO_ONLY",
       "file is stdio only; hosted /mcp does not read the buyer disk"
@@ -7118,7 +8900,12 @@ async function pay(args, cfg, deps = {}) {
   } catch {
     return closedPayError("INVALID_INTENT", "payment intent is invalid");
   }
-  const attached = jsonWithLocalFile(args);
+  let attached;
+  try {
+    attached = jsonWithLocalFile(args);
+  } catch {
+    return closedPayError("INVALID_FILE", "file could not be read");
+  }
   if ("error" in attached) {
     return closedPayError(attached.error.code, attached.error.detail);
   }
@@ -7128,7 +8915,7 @@ async function pay(args, cfg, deps = {}) {
     request = normalizeMcpPaidHttpRequest(paidArgs);
   } catch (err) {
     const raw = err instanceof Error ? err.message : "";
-    const detail = /method/i.test(raw) ? "method must be GET or POST" : /json/i.test(raw) ? "POST requires json" : "request could not be normalized";
+    const detail = /too large/i.test(raw) ? `paid request body exceeds ${MAX_PAID_BODY_BYTES} bytes` : /method/i.test(raw) ? "method must be GET or POST" : /json/i.test(raw) ? "POST requires json" : "request could not be normalized";
     return closedPayError("MALFORMED_REQUEST", detail);
   }
   if (deps.auth?.spendAccountPay) {
@@ -7153,6 +8940,7 @@ async function pay(args, cfg, deps = {}) {
       deps: {
         ...deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {},
         ...trace ? { trace } : {},
+        ...deps.resolveExclusionRegistry ? { resolveExclusionRegistry: deps.resolveExclusionRegistry } : {},
         ...deps.buildPayKind ? { buildPayKind: deps.buildPayKind } : liveKindBuilder ? {
           buildPayKind: (input) => sp.snapshot.accessMode === "open" && input.recipient ? liveKindBuilder.buildSettleOpenRecipientKind({
             ...input,
@@ -7572,10 +9360,15 @@ async function suipayLogin(args, cfg, deps = {}) {
       });
     }
     if (live.kind === "unknown") {
-      return error({
-        status: "failed",
+      return text({
+        status: "ok",
+        reused: true,
+        grantStatus: "unknown",
         code: "GRANT_STATUS_UNKNOWN",
-        detail: "Could not verify the existing grant. Credentials were not modified. Retry later; do not start a new consent (that would mint a second grant)."
+        target: target ?? cfg.target,
+        delegateAddress: identity.delegateAddress,
+        gatewayUrl: endpoints.gatewayUrl,
+        message: "Credentials are already saved for this agent. The existing grant could not be checked just now, so no new sign-in was started and the key file was left unchanged. Retry suipay_login in a moment."
       });
     }
   }
@@ -7585,13 +9378,13 @@ async function suipayLogin(args, cfg, deps = {}) {
     identity,
     label,
     timeoutMs: LOGIN_BG_TIMEOUT_MS,
-    openBrowser: false,
+    openBrowser: true,
     onUrl: deps.onUrl
   });
   const url = started.connectUrl;
   return text(
     [
-      `## ACTION REQUIRED: User must click this URL to sign in`,
+      `## ACTION REQUIRED: The sign-in page was opened in the browser`,
       ``,
       `**Target:** ${target ?? cfg.target ?? "custom"} \xB7 ${endpoints.gatewayUrl}`,
       ``,
@@ -7603,11 +9396,13 @@ async function suipayLogin(args, cfg, deps = {}) {
       ``,
       `[Click here to open SuiPay sign-in](${url})`,
       ``,
-      `**IMPORTANT for the assistant**: do NOT summarize or omit the URL above.`,
-      `The user CANNOT proceed without seeing the exact URL. Surface it verbatim.`,
+      `**IMPORTANT for the assistant**: the browser was already opened to this exact URL.`,
+      `Do NOT navigate to /connect/agent yourself. That path without these query`,
+      `parameters shows "Authorization link incomplete". If the page did not`,
+      `appear, surface the URL above verbatim and do not shorten it.`,
       ``,
-      `1. Open the URL in any browser`,
-      `2. Connect the owner wallet and approve the spend-account grant (Access keys / policies)`,
+      `1. Use the browser window that just opened, or open the URL above`,
+      `2. Connect the owner wallet, choose or create a key, then Authorize on the review step`,
       `3. Once Connected appears, retry the original request \u2014 credentials at \`~/.suipay/credentials.json\` are picked up on the next tool call`,
       ``,
       `_The login link stays valid for 5 minutes. If it expires, call \`suipay_login\` again._`,
@@ -7647,7 +9442,7 @@ var TOOLS = [
   },
   {
     name: "pay",
-    description: "Pay a HTTP resource via delegate. On hosted /mcp the gateway PREPARES an unsigned transaction and returns it (prepare-only \u2014 it never holds the delegate key and cannot settle). Only a process holding the delegate key the grant names can complete settlement (e.g. local stdio MCP, or any self-hosted process with the matching key). Pass recipient and/or maxAmount to state who you intend to pay and what you will spend; both are checked before anything is signed or handed back. Local V1 allowance pay is retired.",
+    description: "Pay a HTTP resource via delegate. On hosted /mcp the gateway PREPARES an unsigned transaction and returns it (prepare-only \u2014 it never holds the delegate key and cannot settle). Only a process holding the delegate key the grant names can complete settlement (e.g. local stdio MCP, or any self-hosted process with the matching key). Pass recipient and/or maxAmount to state who you intend to pay and what you will spend; both are checked before anything is signed or handed back. Local V1 allowance pay is retired. When this process settles a paid binary body, it writes the bytes under ~/.suipay/deliveries/ and names savedTo (absolute path) and savedToUrl (file://) first in the JSON. Hosted /mcp is prepare-only and does not write a buyer file. Always quote savedTo when present. If savedTo is null, quote saveError and do not call pay again. Do not assume the host rendered an image block. Never call pay again to display or save a delivery that already settled.",
     inputSchema: {
       type: "object",
       properties: {
@@ -7663,11 +9458,11 @@ var TOOLS = [
         },
         file: {
           type: "string",
-          description: "Absolute local path whose bytes fill json[fileField] as canonical base64. Stdio only; requires fileField. GET must omit this."
+          description: "Absolute path under SUIPAY_MCP_FILE_ROOT (unset disables attach). Stdio POST only; requires fileField. Regular non-empty file whose decoded size fits the paid-body ceiling. Not a URL, FIFO, device, or path under ~/.suipay. Bytes fill json[fileField] as canonical base64."
         },
         fileField: {
           type: "string",
-          description: "JSON key to set from file (e.g. contentBase64). Required with file. Must not already be present on json."
+          description: "JSON key to set from file (e.g. contentBase64). Required with file. Pattern [A-Za-z][A-Za-z0-9_]{0,63}. Must not already be present on json."
         },
         recipient: {
           type: "string",
@@ -7776,6 +9571,7 @@ function toolError(value) {
 }
 function createServer2(cfg, auth, trace, options = {}) {
   const resolveAgentHeld = options.resolveAgentHeld ?? resolveAgentHeldSettlement;
+  const transport = options.transport ?? "stdio";
   const server = new Server(
     { name: "suipay", version: "1.0.0" },
     {
@@ -7802,21 +9598,32 @@ function createServer2(cfg, auth, trace, options = {}) {
           return await accessContext({ auth }, cfg);
         case "pay": {
           const agentHeld = auth?.spendAccountPay ? resolveAgentHeld(cfg, auth.spendAccountPay) : null;
+          const fileArgs = {
+            ...args.file !== void 0 ? { file: args.file } : {},
+            ...args.fileField !== void 0 ? { fileField: args.fileField } : {}
+          };
+          if (transport === "http" && hasLocalFileArgs(fileArgs)) {
+            return closedPayError(
+              "FILE_STDIO_ONLY",
+              "file is stdio only; hosted /mcp does not read the buyer disk"
+            );
+          }
           return await pay(
             {
               url: String(args.url ?? ""),
               ...args.method !== void 0 ? { method: args.method } : {},
               ...args.json !== void 0 ? { json: args.json } : {},
-              ...args.file !== void 0 ? { file: args.file } : {},
-              ...args.fileField !== void 0 ? { fileField: args.fileField } : {},
+              ...transport === "stdio" ? fileArgs : {},
               ...args.recipient !== void 0 ? { recipient: args.recipient } : {},
               ...args.maxAmount !== void 0 ? { maxAmount: args.maxAmount } : {}
             },
             cfg,
             {
               auth,
+              transport,
               ...trace ? { trace } : {},
-              ...agentHeld ? { agentHeld } : {}
+              ...agentHeld ? { agentHeld } : {},
+              ...options.resolveExclusionRegistry ? { resolveExclusionRegistry: options.resolveExclusionRegistry } : {}
             }
           );
         }
@@ -7903,6 +9710,11 @@ function canonicalMcpRequestId(id) {
 function asRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
 }
+function redactPayFileArg(args) {
+  const record = asRecord(args);
+  if (!record || !("file" in record)) return args;
+  return { ...record, file: "[redacted]" };
+}
 function readEntry(message) {
   const record = asRecord(message);
   if (!record) return null;
@@ -7914,7 +9726,7 @@ function readEntry(message) {
     jsonRpcId: typeof rawId === "string" || typeof rawId === "number" ? rawId : null,
     requestId: canonicalMcpRequestId(rawId),
     toolName: params && typeof params.name === "string" ? params.name : null,
-    toolArguments: params ? params.arguments : void 0,
+    toolArguments: params ? redactPayFileArg(params.arguments) : void 0,
     clientName: clientInfo && typeof clientInfo.name === "string" ? clientInfo.name : null,
     clientVersion: clientInfo && typeof clientInfo.version === "string" ? clientInfo.version : null,
     protocolVersion: params && typeof params.protocolVersion === "string" ? params.protocolVersion : null
@@ -8344,7 +10156,10 @@ async function handleSuipayMcpHttpRequest(req, cfg, auth, trace, options) {
         sessionIdGenerator: void 0,
         enableJsonResponse: true
       });
-      const server = createServer2(cfg, auth, hooks, options);
+      const server = createServer2(cfg, auth, hooks, {
+        ...options,
+        transport: "http"
+      });
       await server.connect(transport);
       return transport.handleRequest(request);
     }