@piprail/sdk 2.3.0 → 2.4.0

package/dist/aptos-QAAXIUY3.js

@@ -0,0 +1,673 @@
+import {
+  ConfirmationTimeoutError,
+  InsufficientFundsError,
+  SettlementError,
+  UnknownTokenError,
+  UnsupportedSchemeError,
+  WrongFamilyError,
+  assertNoLegacyWalletKey,
+  nativeCost,
+  rejectForeignToken,
+  toInsufficientFundsError
+} from "./chunk-7XK22JSQ.js";
+
+// src/drivers/aptos/index.ts
+import { Aptos, AptosConfig, Network, AccountAddress as AccountAddress2 } from "@aptos-labs/ts-sdk";
+
+// src/drivers/aptos/chains.ts
+var APT_DECIMALS = 8;
+var APT_SYMBOL = "APT";
+var APT_FA_METADATA = "0xa";
+var APTOS_MAINNET = {
+  caip2: "aptos:1",
+  defaultRpc: "https://fullnode.mainnet.aptoslabs.com/v1",
+  tokens: {
+    // Circle USDC — FA metadata + 6 decimals verified live on mainnet
+    // (0x1::fungible_asset::Metadata → symbol "USDC", decimals 6) before shipping.
+    USDC: {
+      metadata: "0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b",
+      decimals: 6,
+      symbol: "USDC"
+    },
+    // Tether USD₮ — use the FA *metadata* address (NOT the issuer/creator address
+    // 0xf73e…73cb). Verified live (Metadata → name "Tether USD", symbol "USDt", decimals 6).
+    USDT: {
+      metadata: "0x357b0b74bc833e95a115ad22604854d6b0fca151cecd94111770e5d6ffc9dc2b",
+      decimals: 6,
+      symbol: "USDT"
+    }
+  }
+};
+
+// src/drivers/aptos/pay.ts
+var MAX_GAS_AMOUNT = 5e4;
+async function payAptos(params) {
+  const { client, signer, sender, accept } = params;
+  const metadata = accept.asset === "native" ? APT_FA_METADATA : accept.asset;
+  try {
+    const transaction = await client.build({
+      sender,
+      data: {
+        function: "0x1::primary_fungible_store::transfer",
+        typeArguments: ["0x1::fungible_asset::Metadata"],
+        // u64 amount goes as a base-unit string; the FA metadata object + recipient are addresses.
+        functionArguments: [metadata, accept.payTo, accept.amount]
+      },
+      options: { maxGasAmount: MAX_GAS_AMOUNT }
+    });
+    const res = await client.signSubmit({ signer, transaction });
+    return res.hash;
+  } catch (err) {
+    if (err instanceof InsufficientFundsError) throw err;
+    if (isAptosAffordability(err)) {
+      throw new InsufficientFundsError(
+        err instanceof Error ? err.message : "Insufficient APT/token balance for the payment.",
+        { cause: err }
+      );
+    }
+    throw toInsufficientFundsError(err) ?? err;
+  }
+}
+function isAptosAffordability(err) {
+  const m = err instanceof Error ? err.message : String(err);
+  return /INSUFFICIENT_BALANCE|EINSUFFICIENT_BALANCE|insufficient.*(balance|gas|funds)|coin store|balance is too low|EINSUFFICIENT/i.test(
+    m
+  );
+}
+
+// src/drivers/aptos/exact.ts
+import {
+  AccountAddress,
+  AccountAuthenticator,
+  AccountAuthenticatorEd25519,
+  Deserializer,
+  SimpleTransaction,
+  TransactionPayloadEntryFunction,
+  generateSigningMessageForTransaction
+} from "@aptos-labs/ts-sdk";
+var TRANSFER_MODULE = "0x1::primary_fungible_store";
+var TRANSFER_FUNCTION = "transfer";
+var METADATA_TYPE = "0x1::fungible_asset::Metadata";
+var BUYER_MAX_GAS_AMOUNT = 5e4;
+var MAX_GAS_AMOUNT_CAP = 100000n;
+var MAX_GAS_UNIT_PRICE_CAP = 2000n;
+var b64encode = (bytes) => Buffer.from(bytes).toString("base64");
+var b64decode = (s) => new Uint8Array(Buffer.from(s, "base64"));
+function parseAddr(addr) {
+  try {
+    return AccountAddress.fromString(addr);
+  } catch {
+    return null;
+  }
+}
+async function payExactAptos(input) {
+  const { client, sender, accept } = input;
+  if (accept.asset === "native") {
+    throw new UnsupportedSchemeError(
+      "Aptos exact is Fungible-Asset only (a primary_fungible_store transfer); native APT is not exact-payable. Pay via onchain-proof."
+    );
+  }
+  const feePayer = accept.extra.feePayer;
+  if (!feePayer) {
+    throw new UnsupportedSchemeError("Aptos exact rail must advertise extra.feePayer (the gas sponsor address).");
+  }
+  const feePayerAddr = parseAddr(feePayer);
+  if (!feePayerAddr) throw new UnsupportedSchemeError(`Aptos exact: extra.feePayer "${feePayer}" is not a valid Aptos address.`);
+  const payToAddr = parseAddr(accept.payTo);
+  if (!payToAddr) throw new UnsupportedSchemeError(`Aptos exact: payTo "${accept.payTo}" is not a valid Aptos address.`);
+  const metadataAddr = parseAddr(accept.asset);
+  if (!metadataAddr) throw new UnsupportedSchemeError(`Aptos exact: asset "${accept.asset}" is not a valid FA metadata address.`);
+  const senderAddr = parseAddr(sender);
+  if (!senderAddr) throw new UnsupportedSchemeError(`Aptos exact: payer "${sender}" is not a valid Aptos address.`);
+  if (feePayerAddr.equals(senderAddr)) {
+    throw new UnsupportedSchemeError(
+      "Aptos exact: the fee payer must differ from the payer \u2014 the buyer must pay ZERO APT (the sponsor pays gas)."
+    );
+  }
+  const tx = await client.buildFeePayerTransfer({
+    sender,
+    metadata: metadataAddr.toString(),
+    payTo: payToAddr.toString(),
+    amount: accept.amount,
+    maxGasAmount: BUYER_MAX_GAS_AMOUNT
+  });
+  tx.feePayerAddress = feePayerAddr;
+  const senderAuth = client.signAsSender({ transaction: tx });
+  return {
+    payload: { transaction: b64encode(tx.bcsToBytes()), senderAuth: b64encode(senderAuth.bcsToBytes()) },
+    payerFrom: sender,
+    nonce: dedupeNonce(senderAuth)
+  };
+}
+function dedupeNonce(auth) {
+  if (auth instanceof AccountAuthenticatorEd25519) return auth.signature.toString();
+  return b64encode(auth.bcsToBytes());
+}
+function shorten(msg) {
+  const oneLine = msg.replace(/\s+/g, " ").trim();
+  return oneLine.length > 200 ? `${oneLine.slice(0, 200)}\u2026` : oneLine;
+}
+function fail(error, detail) {
+  return { ok: false, error, detail };
+}
+function argBytes(arg) {
+  const v = arg.value?.value;
+  if (v instanceof Uint8Array) return v;
+  throw new Error("unexpected entry-function argument shape");
+}
+async function verifyAndSettleExactAptos(input) {
+  const { client, feePayerAddr, payload, accept } = input;
+  const railFeePayer = accept.extra.feePayer;
+  if (!railFeePayer) throw new SettlementError("Aptos exact: rail is missing extra.feePayer.");
+  if (railFeePayer !== feePayerAddr) {
+    throw new SettlementError("Aptos exact: the gate relayer address does not match the rail extra.feePayer \u2014 misconfigured rail.");
+  }
+  if (accept.asset === "native") throw new SettlementError("Aptos exact: native APT is not exact-payable (misconfigured rail).");
+  const railFeePayerAddr = parseAddr(railFeePayer);
+  const railPayTo = parseAddr(accept.payTo);
+  const railMetadata = parseAddr(accept.asset);
+  if (!railFeePayerAddr || !railPayTo || !railMetadata) {
+    throw new SettlementError("Aptos exact: rail feePayer/payTo/asset is not a valid Aptos address (misconfigured rail).");
+  }
+  let tx;
+  let senderAuth;
+  try {
+    tx = SimpleTransaction.deserialize(new Deserializer(b64decode(payload.transaction)));
+    senderAuth = AccountAuthenticator.deserialize(new Deserializer(b64decode(payload.senderAuth)));
+  } catch (err) {
+    return fail("signature_invalid", `Unparseable Aptos transaction/authenticator: ${shorten(err instanceof Error ? err.message : String(err))}.`);
+  }
+  const raw = tx.rawTransaction;
+  if (!tx.feePayerAddress || !tx.feePayerAddress.equals(railFeePayerAddr)) {
+    return fail("signature_invalid", `The transaction fee payer ${tx.feePayerAddress?.toString() ?? "(none)"} is not the rail fee payer ${railFeePayer}.`);
+  }
+  const payloadKind = raw.payload;
+  if (!(payloadKind instanceof TransactionPayloadEntryFunction)) {
+    return fail("transfer_not_found", "The transaction is not an entry-function call.");
+  }
+  const ef = payloadKind.entryFunction;
+  const fnId = `${ef.module_name.address.toString()}::${ef.module_name.name.identifier}`;
+  if (fnId !== TRANSFER_MODULE || ef.function_name.identifier !== TRANSFER_FUNCTION) {
+    return fail("transfer_not_found", `Not a ${TRANSFER_MODULE}::${TRANSFER_FUNCTION} call (got ${fnId}::${ef.function_name.identifier}).`);
+  }
+  if (ef.type_args.length !== 1 || ef.type_args[0].toString() !== METADATA_TYPE) {
+    return fail("transfer_not_found", `Transfer type argument is not <${METADATA_TYPE}>.`);
+  }
+  if (ef.args.length !== 3) {
+    return fail("transfer_not_found", `Transfer expects 3 arguments (metadata, recipient, amount), got ${ef.args.length}.`);
+  }
+  let metadata, recipient, amount;
+  try {
+    metadata = AccountAddress.deserialize(new Deserializer(argBytes(ef.args[0])));
+    recipient = AccountAddress.deserialize(new Deserializer(argBytes(ef.args[1])));
+    amount = new Deserializer(argBytes(ef.args[2])).deserializeU64();
+  } catch (err) {
+    return fail("transfer_not_found", `Could not decode the transfer arguments: ${shorten(err instanceof Error ? err.message : String(err))}.`);
+  }
+  if (!metadata.equals(railMetadata)) {
+    return fail("transfer_not_found", `Transfer asset ${metadata.toString()} \u2260 rail asset ${accept.asset}.`);
+  }
+  if (!recipient.equals(railPayTo)) {
+    return fail("wrong_recipient", `Transfer pays ${recipient.toString()}, not payTo ${accept.payTo}.`);
+  }
+  if (amount < BigInt(accept.amount)) {
+    return fail("amount_too_low", `Transfer pays ${amount} of the FA, required ${accept.amount}.`);
+  }
+  if (raw.max_gas_amount > MAX_GAS_AMOUNT_CAP) {
+    return fail("signature_invalid", `max_gas_amount ${raw.max_gas_amount} exceeds the cap ${MAX_GAS_AMOUNT_CAP} (fee-payer drain guard).`);
+  }
+  if (raw.gas_unit_price > MAX_GAS_UNIT_PRICE_CAP) {
+    return fail("signature_invalid", `gas_unit_price ${raw.gas_unit_price} exceeds the cap ${MAX_GAS_UNIT_PRICE_CAP} (fee-payer drain guard).`);
+  }
+  const now = BigInt(Math.floor(Date.now() / 1e3));
+  if (raw.expiration_timestamp_secs <= now) {
+    return fail("payment_expired", `Transaction expired: expiration ${raw.expiration_timestamp_secs} <= now ${now}.`);
+  }
+  const payer = raw.sender.toString();
+  if (senderAuth instanceof AccountAuthenticatorEd25519) {
+    let sigOk = false;
+    try {
+      const message = generateSigningMessageForTransaction(tx);
+      sigOk = senderAuth.public_key.verifySignature({ message, signature: senderAuth.signature });
+    } catch (err) {
+      return fail("signature_invalid", `Could not verify the sender signature: ${shorten(err instanceof Error ? err.message : String(err))}.`);
+    }
+    if (!sigOk) return fail("signature_invalid", "The sender signature does not verify over the transaction.");
+    if (senderAuth.public_key.authKey().derivedAddress().toString() !== payer) {
+      return fail("signature_invalid", "The sender signature key does not derive to the transaction sender.");
+    }
+  }
+  let feePayerAuth;
+  try {
+    feePayerAuth = client.signAsFeePayer({ transaction: tx });
+  } catch (err) {
+    throw new SettlementError(`Aptos exact settle: the gate could not sign as fee payer (${shorten(err instanceof Error ? err.message : String(err))}).`, { cause: err });
+  }
+  if (senderAuth instanceof AccountAuthenticatorEd25519) {
+    try {
+      const sim = await client.simulate({ transaction: tx, senderPublicKey: senderAuth.public_key });
+      if (!sim.success) {
+        const m = sim.vmStatus;
+        if (/EXPIRED|expired/i.test(m)) return fail("payment_expired", `Transaction would fail: ${shorten(m)}.`);
+        if (/SEQUENCE_NUMBER_TOO_OLD|already/i.test(m)) return fail("tx_already_used", `This payment was already settled: ${shorten(m)}.`);
+        if (/INSUFFICIENT/i.test(m)) return fail("tx_reverted", `Insufficient balance to settle: ${shorten(m)}.`);
+        return fail("tx_reverted", `Transaction would fail on-chain: ${shorten(m)}.`);
+      }
+    } catch {
+    }
+  }
+  let hash;
+  try {
+    hash = await client.submit({ transaction: tx, senderAuthenticator: senderAuth, feePayerAuthenticator: feePayerAuth });
+  } catch (err) {
+    const m = err instanceof Error ? err.message : String(err);
+    if (/signature|invalid.*auth|INVALID_SIGNATURE/i.test(m)) return fail("signature_invalid", `Settle rejected \u2014 bad signature: ${shorten(m)}.`);
+    if (/SEQUENCE_NUMBER_TOO_OLD|already.*(committed|ledger)|duplicate/i.test(m)) return fail("tx_already_used", `This payment was already settled: ${shorten(m)}.`);
+    if (/EXPIRED|expired|TOO_NEW/i.test(m)) return fail("payment_expired", `Settle rejected \u2014 expired/stale: ${shorten(m)}.`);
+    throw new SettlementError(
+      `Aptos exact settle: the transaction failed to submit (${shorten(m)}). The buyer's signed transaction is still valid \u2014 fund/fix the fee payer (${railFeePayer}) and the buyer can re-present it.`,
+      { cause: err }
+    );
+  }
+  let confirmed;
+  try {
+    confirmed = await client.waitForConfirmation(hash);
+  } catch (err) {
+    throw new SettlementError(`Aptos exact settle: submitted ${hash} but confirmation read failed (${shorten(err instanceof Error ? err.message : String(err))}). It likely landed \u2014 re-verify before re-presenting; do NOT re-pay.`, { cause: err });
+  }
+  if (confirmed === null) {
+    throw new SettlementError(`Aptos exact settle: submitted ${hash} but it did not confirm in time. It likely landed \u2014 re-verify before re-presenting; do NOT re-pay.`);
+  }
+  if (!confirmed.success) {
+    return fail("tx_reverted", `Settle tx ${hash} reverted on-chain (a post-simulate race).`);
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "exact",
+      success: true,
+      network: accept.network,
+      transaction: hash,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer,
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
+// src/drivers/aptos/verify.ts
+async function verifyAptos(params) {
+  const { reader, hash, accept } = params;
+  const required = BigInt(accept.amount);
+  const wantMetadata = accept.asset === "native" ? APT_FA_METADATA : accept.asset;
+  let tx;
+  try {
+    tx = await reader.getTransaction(hash);
+  } catch {
+    return txNotFound(hash);
+  }
+  if (!tx) return txNotFound(hash);
+  if (!tx.success) {
+    return { ok: false, error: "tx_reverted", detail: `Aptos tx ${hash} did not succeed.` };
+  }
+  if (typeof tx.timestampSeconds === "number") {
+    const ageSeconds = Math.floor(Date.now() / 1e3) - tx.timestampSeconds;
+    if (ageSeconds > accept.maxTimeoutSeconds) {
+      return {
+        ok: false,
+        error: "payment_expired",
+        detail: `Payment is ${ageSeconds}s old; max allowed is ${accept.maxTimeoutSeconds}s.`
+      };
+    }
+  }
+  let wantStore;
+  try {
+    wantStore = await reader.primaryStore(accept.payTo, wantMetadata);
+  } catch {
+    return txNotFound(hash);
+  }
+  let paid = 0n;
+  for (const d of tx.deposits) {
+    if (d.store !== wantStore) continue;
+    try {
+      paid += BigInt(d.amount);
+    } catch {
+      continue;
+    }
+  }
+  if (paid < required) {
+    return {
+      ok: false,
+      error: "transfer_not_found",
+      detail: `No Aptos transfer of >= ${required} (${wantMetadata}) to ${accept.payTo} in ${hash}.`
+    };
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "onchain-proof",
+      success: true,
+      network: accept.network,
+      transaction: hash,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer: tx.sender,
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function txNotFound(hash) {
+  return {
+    ok: false,
+    error: "tx_not_found",
+    detail: `Aptos tx ${hash} not found or not yet propagated \u2014 retry.`
+  };
+}
+
+// src/drivers/aptos/wallet.ts
+import { Account, Ed25519PrivateKey } from "@aptos-labs/ts-sdk";
+function assertAptosWallet(wallet, network) {
+  if (typeof wallet !== "object" || wallet === null) {
+    throw new WrongFamilyError(
+      `chain ${network} is Aptos; wallet must be { key } (ed25519-priv-0x\u2026) or { account }.`
+    );
+  }
+  assertNoLegacyWalletKey(wallet, "Aptos");
+  if (!("key" in wallet) && !("account" in wallet)) {
+    throw new WrongFamilyError(
+      `chain ${network} is Aptos; wallet must be { key } (ed25519-priv-0x\u2026) or { account }.`
+    );
+  }
+  return wallet;
+}
+function resolveAptosAccount(config) {
+  if (config.account) return config.account;
+  if (config.key != null) {
+    try {
+      return Account.fromPrivateKey({ privateKey: new Ed25519PrivateKey(config.key) });
+    } catch (cause) {
+      throw new WrongFamilyError(
+        "Aptos wallet { key } is not a valid ed25519 secret (ed25519-priv-0x\u2026 or 0x\u2026 hex).",
+        { cause }
+      );
+    }
+  }
+  throw new WrongFamilyError("Aptos wallet needs { key } (ed25519-priv-0x\u2026) or { account }.");
+}
+
+// src/drivers/aptos/index.ts
+var aptosDriver = {
+  family: "aptos",
+  resolve(opts) {
+    if (opts.chain !== "aptos") return null;
+    const rpcUrl = opts.rpcUrl ?? APTOS_MAINNET.defaultRpc;
+    return makeAptosNetwork(APTOS_MAINNET, rpcUrl);
+  }
+};
+function norm(addr) {
+  try {
+    return AccountAddress2.from(addr).toString();
+  } catch {
+    return addr;
+  }
+}
+function makeAptosNetwork(preset, rpcUrl) {
+  const aptos = new Aptos(new AptosConfig({ network: Network.MAINNET, fullnode: rpcUrl }));
+  const network = preset.caip2;
+  const reader = {
+    async getTransaction(hash) {
+      const tx = await aptos.getTransactionByHash({ transactionHash: hash });
+      if (!tx || tx.type !== "user_transaction") return null;
+      const deposits = (tx.events ?? []).filter((e) => e.type === "0x1::fungible_asset::Deposit").map((e) => ({ store: norm(String(e.data.store)), amount: String(e.data.amount) }));
+      return {
+        success: tx.success === true,
+        // Aptos timestamps are microseconds since epoch.
+        timestampSeconds: tx.timestamp != null ? Math.floor(Number(tx.timestamp) / 1e6) : void 0,
+        sender: tx.sender ? norm(String(tx.sender)) : "",
+        deposits
+      };
+    },
+    async primaryStore(owner, metadata) {
+      const [addr] = await aptos.view({
+        payload: {
+          function: "0x1::primary_fungible_store::primary_store_address",
+          typeArguments: ["0x1::fungible_asset::Metadata"],
+          functionArguments: [owner, metadata]
+        }
+      });
+      return norm(String(addr));
+    }
+  };
+  const payClient = {
+    build: (input) => aptos.transaction.build.simple({
+      sender: input.sender,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      data: input.data,
+      ...input.options ? { options: input.options } : {}
+    }),
+    signSubmit: (input) => aptos.signAndSubmitTransaction({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      signer: input.signer,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      transaction: input.transaction
+    })
+  };
+  return {
+    family: "aptos",
+    network,
+    supports: (n) => n === network,
+    resolveToken(token) {
+      if (token === "native") {
+        return { asset: "native", decimals: APT_DECIMALS, symbol: APT_SYMBOL };
+      }
+      if (typeof token === "string") {
+        const info = preset.tokens[token.toUpperCase()];
+        if (!info) {
+          const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
+          throw new UnknownTokenError(
+            `token "${token}" isn't built in for Aptos (known: ${known}). Pass { metadata, decimals } for a custom Fungible Asset, or use 'native'.`
+          );
+        }
+        return { asset: info.metadata, decimals: info.decimals, symbol: info.symbol };
+      }
+      rejectForeignToken(token, "aptos", network);
+      const t = token;
+      if (!t.metadata || typeof t.decimals !== "number") {
+        throw new WrongFamilyError(
+          `chain ${network} is Aptos; a custom token must be { metadata, decimals }.`
+        );
+      }
+      return {
+        asset: t.metadata,
+        decimals: t.decimals,
+        ...t.symbol ? { symbol: t.symbol } : {}
+      };
+    },
+    describeAsset(asset) {
+      if (asset === "native") return { symbol: APT_SYMBOL, decimals: APT_DECIMALS };
+      for (const info of Object.values(preset.tokens)) {
+        if (info.metadata === asset) return { symbol: info.symbol, decimals: info.decimals };
+      }
+      return null;
+    },
+    assertValidPayTo(payTo) {
+      const evmLike = /^0x[0-9a-fA-F]{40}$/.test(payTo);
+      let valid = false;
+      try {
+        AccountAddress2.from(payTo);
+        valid = true;
+      } catch {
+        valid = false;
+      }
+      if (!valid || evmLike) {
+        throw new WrongFamilyError(
+          `chain ${network} is Aptos, but payTo "${payTo}" is not a valid Aptos address (0x + 32 bytes).`
+        );
+      }
+    },
+    bindWallet(wallet) {
+      return { _native: assertAptosWallet(wallet, network) };
+    },
+    async send(wallet, accept) {
+      const account = resolveAptosAccount(wallet._native);
+      return payAptos({
+        client: payClient,
+        signer: account,
+        sender: account.accountAddress.toString(),
+        accept
+      });
+    },
+    async confirm(ref) {
+      try {
+        const tx = await aptos.waitForTransaction({ transactionHash: ref });
+        return { height: String(tx.version ?? "0") };
+      } catch (err) {
+        throw new ConfirmationTimeoutError(`Aptos tx ${ref} did not finalize in time.`, { cause: err });
+      }
+    },
+    async estimateCost(accept) {
+      if (accept.scheme === "exact") {
+        return nativeCost({
+          symbol: APT_SYMBOL,
+          decimals: APT_DECIMALS,
+          fee: 0n,
+          basis: "estimated",
+          detail: "gasless \u2014 the fee payer (facilitator/relayer) sponsors gas; the buyer pays 0 APT"
+        });
+      }
+      return nativeCost({
+        symbol: APT_SYMBOL,
+        decimals: APT_DECIMALS,
+        fee: 100000n,
+        // ~0.001 APT
+        basis: "heuristic",
+        detail: "\u22480.001 APT (a simple Fungible-Asset transfer; Aptos gas is sub-cent)"
+      });
+    },
+    async balanceOf(wallet, asset) {
+      let owner;
+      try {
+        owner = resolveAptosAccount(wallet._native).accountAddress.toString();
+      } catch {
+        return { token: null, native: null };
+      }
+      const native = await aptos.getAccountAPTAmount({ accountAddress: owner }).then((n) => BigInt(n)).catch(() => null);
+      if (asset === "native") return { token: native, native };
+      let token = null;
+      try {
+        const [bal] = await aptos.view({
+          payload: {
+            function: "0x1::primary_fungible_store::balance",
+            typeArguments: ["0x1::fungible_asset::Metadata"],
+            functionArguments: [owner, asset]
+          }
+        });
+        token = BigInt(String(bal));
+      } catch {
+        token = null;
+      }
+      return { token, native };
+    },
+    // No receive prerequisite — the recipient's primary FA store auto-creates on receipt.
+    async recipientReady() {
+      return { ready: "n/a" };
+    },
+    async verify(ref, accept) {
+      return verifyAptos({ reader, hash: ref, accept });
+    },
+    // Standard x402 `exact` rail, BUYER side — build a fee-payer (sponsored, AIP-39) FA transfer,
+    // sign ONLY the sender slot (the buyer spends ZERO APT). Never submits. Throws
+    // UnsupportedSchemeError for native / a missing feePayer / a feePayer that equals the payer.
+    async payExact(wallet, accept) {
+      const account = resolveAptosAccount(wallet._native);
+      const payClient2 = {
+        buildFeePayerTransfer: ({ sender, metadata, payTo, amount, maxGasAmount }) => aptos.transaction.build.simple({
+          sender,
+          withFeePayer: true,
+          data: {
+            function: "0x1::primary_fungible_store::transfer",
+            typeArguments: ["0x1::fungible_asset::Metadata"],
+            functionArguments: [metadata, payTo, amount]
+          },
+          options: { maxGasAmount }
+        }),
+        signAsSender: ({ transaction }) => aptos.transaction.sign({ signer: account, transaction })
+      };
+      const { payload, payerFrom, nonce } = await payExactAptos({
+        client: payClient2,
+        sender: account.accountAddress.toString(),
+        accept
+      });
+      return { payload, accepted: accept, payerFrom, nonce };
+    },
+    // Standard x402 `exact` rail, SELLER side — verify the inbound sponsored tx against the trusted
+    // accept, then add the fee-payer signature + submit (self-settle, no facilitator). The buyer
+    // stays gasless; the merchant's relayer pays gas to receive.
+    async settleExactSelf({ relayer, payload, accept }) {
+      if (!("senderAuth" in payload) || !("transaction" in payload)) {
+        return { ok: false, error: "signature_invalid", detail: "Aptos exact expects a { transaction, senderAuth } payload." };
+      }
+      const feePayerAccount = resolveAptosAccount(relayer._native);
+      const settleClient = {
+        signAsFeePayer: ({ transaction }) => aptos.transaction.signAsFeePayer({ signer: feePayerAccount, transaction }),
+        async simulate({ transaction, senderPublicKey }) {
+          const [sim] = await aptos.transaction.simulate.simple({
+            signerPublicKey: senderPublicKey,
+            feePayerPublicKey: feePayerAccount.publicKey,
+            transaction
+          });
+          return { success: sim?.success === true, vmStatus: String(sim?.vm_status ?? "") };
+        },
+        async submit({ transaction, senderAuthenticator, feePayerAuthenticator }) {
+          const res = await aptos.transaction.submit.simple({ transaction, senderAuthenticator, feePayerAuthenticator });
+          return res.hash;
+        },
+        async waitForConfirmation(hash) {
+          try {
+            const tx = await aptos.waitForTransaction({
+              transactionHash: hash,
+              options: { checkSuccess: false }
+            });
+            return { success: tx.success === true };
+          } catch {
+            return null;
+          }
+        }
+      };
+      return verifyAndSettleExactAptos({
+        client: settleClient,
+        feePayerAddr: feePayerAccount.accountAddress.toString(),
+        payload,
+        accept
+      });
+    },
+    // The gate's rail-advertisement SPI. The fee payer is EITHER a keyless facilitator's sponsor
+    // address (`feePayer`) OR the merchant's own bound `relayer` (self mode); native APT isn't
+    // exact-payable. `null` ⇒ no exact rail. Aptos allows feePayer === payTo (the fee-payer
+    // signature is separate from the transfer, unlike Solana).
+    async resolveExactRail({ asset, relayer, feePayer }) {
+      if (asset === "native") return null;
+      let fp = feePayer;
+      if (!fp && relayer) {
+        try {
+          fp = resolveAptosAccount(relayer._native).accountAddress.toString();
+        } catch {
+          return null;
+        }
+      }
+      if (!fp) return null;
+      try {
+        AccountAddress2.fromString(fp);
+      } catch {
+        return null;
+      }
+      return { method: "aptos", extra: { feePayer: fp } };
+    }
+  };
+}
+export {
+  aptosDriver
+};