@piprail/sdk 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.3.1] — 2026-06-04
+
+Aptos pay-path fix surfaced by the live mainnet test — no API change, fully compatible with 1.3.0.
+
+### Fixed
+- **Aptos: cap `maxGasAmount` (50k) on the Fungible-Asset transfer.** Aptos validates
+  `max_gas_amount × gas_unit_price` against the sender's balance *before* execution, so the SDK
+  default (200k units) made a tiny transfer demand ~0.5 APT held just to be admitted — a wallet
+  with a modest APT balance was rejected with `INSUFFICIENT_BALANCE_FOR_TRANSACTION_FEE` even
+  though the transfer itself uses a fraction of that. A `primary_fungible_store::transfer` (even
+  one that creates the recipient's primary store) stays well under 50k gas units, so the cap keeps
+  ample gas headroom while the upfront fee requirement stays small. Live-validated on Aptos mainnet.
+
+## [1.3.0] — 2026-06-04
+
+A new chain **family** — **Aptos** — the **9th driver family** and the only Move L1 with BOTH
+canonical native stablecoins. Brings the built-in count to **27 chains across 9 families (19 EVM)**.
+Aptos has an official `exact` scheme merged into the canonical `coinbase/x402` repo and is a
+first-class x402 / agent-payments network. Fully backward-compatible; `@aptos-labs/ts-sdk` is a
+lazy-loaded optional peer, so pure-EVM (and other) installs never download it.
+
+### Added
+- **Aptos (`chain: 'aptos'`, CAIP-2 `aptos:1`)** — native Circle **USDC**
+  (`0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b`) + native Tether **USD₮**
+  (`0x357b0b74bc833e95a115ad22604854d6b0fca151cecd94111770e5d6ffc9dc2b`), both 6 dp, plus native
+  **APT** (8 dp). Both Fungible-Asset metadata addresses were verified on-chain
+  (`0x1::fungible_asset::Metadata` → matching symbol + decimals) before shipping.
+- **Template B (digest-bound, like Sui/Tron):** the proof ref is the tx hash; `verify()` re-derives
+  payTo's primary store for the required FA metadata from the **trusted accept** (never the client
+  ref) and matches `0x1::fungible_asset::Deposit` events to it (+ recency window + single-use proof
+  set). Every asset — native APT and both stablecoins — transfers via
+  `0x1::primary_fungible_store::transfer` (native = the APT FA at `0xa`), which auto-creates the
+  recipient's primary store, so there's **no opt-in / coin-store registration to receive** — even a
+  fresh recipient works. `@aptos-labs/ts-sdk` is an **optional peer (`>=2 <8`)**, lazy-loaded on
+  first use; the built EVM bundle stays free of any static `@aptos-labs/ts-sdk` import (its own chunk).
+
+Live mainnet smoke (a real APT + USDC/USDT round-trip) is the separate ship-gate, pending wallet
+funding; the driver is verified against the test contract (typecheck + 416 tests + build).
+
 ## [1.2.0] — 2026-06-04
 
 Two new EVM presets — **HyperEVM (Hyperliquid)** and **Monad** — bringing the built-in count to

package/ERRORS.md

@@ -2,7 +2,7 @@
 
 This is the **single source of truth** for how `@piprail/sdk` reports errors. It is
 deliberately small and uniform: every module — the client, the server gate, the registry,
-and every chain driver (all eight families: EVM, Solana, TON, Tron, NEAR, Sui, Stellar, XRPL,
+and every chain driver (all nine families: EVM, Solana, TON, Tron, NEAR, Sui, Stellar, XRPL, Aptos,
 and any future one) — follows it
 *exactly*, so a human developer, a merchant server, or an AI agent always gets a **typed,
 understandable** reason, never an opaque chain-library blob.

package/README.md

@@ -90,7 +90,7 @@ See [`examples/agent-tools.mjs`](../examples/agent-tools.mjs) for MCP / AI-SDK w
 
 ### Accept several chains at once
 
-`requirePayment` (and `createPaymentGate`) take an **`accept: [...]`** array — one challenge that's payable on **any** of several chains/tokens, across **all eight families** (EVM, Solana, TON, Tron, Stellar, XRPL, NEAR, Sui). The agent pays with whatever it holds:
+`requirePayment` (and `createPaymentGate`) take an **`accept: [...]`** array — one challenge that's payable on **any** of several chains/tokens, across **all nine families** (EVM, Solana, TON, Tron, Stellar, XRPL, NEAR, Sui, Aptos). The agent pays with whatever it holds:
 
 ```ts
 requirePayment({
@@ -133,7 +133,7 @@ requirePayment({ chain: 'ton',      token: 'native', amount: '1',     payTo }) /
 requirePayment({ chain: 'xrpl',     token: 'native', amount: '1',     payTo }) // XRP
 ```
 
-**Native or stablecoin — your choice, on every chain.** Every gate accepts the chain's native coin (ETH, BNB, POL, AVAX, SOL, TON, XLM, XRP, SUI, NEAR, **TRX**, …) just as readily as a stablecoin — set `token: 'native'` and the SDK fills in the right decimals (18 on EVM, 9 on Solana/TON/Sui, 7 on Stellar, 6 on XRPL/Tron, 24 on NEAR). Verification, replay protection, and self-custody are identical to the stablecoin path — across **all eight families, no exceptions**. (On **NEAR**, native is the zero-setup path — no `storage_deposit` — while the NEP-141 token path needs registration; see the NEAR note. On **Tron**, USD₮ is the default since TRX is volatile gas, but native TRX works too.)
+**Native or stablecoin — your choice, on every chain.** Every gate accepts the chain's native coin (ETH, BNB, POL, AVAX, SOL, TON, XLM, XRP, SUI, NEAR, **TRX**, …) just as readily as a stablecoin — set `token: 'native'` and the SDK fills in the right decimals (18 on EVM, 9 on Solana/TON/Sui, 7 on Stellar, 6 on XRPL/Tron, 24 on NEAR). Verification, replay protection, and self-custody are identical to the stablecoin path — across **all nine families, no exceptions**. (On **NEAR**, native is the zero-setup path — no `storage_deposit` — while the NEP-141 token path needs registration; see the NEAR note. On **Tron**, USD₮ is the default since TRX is volatile gas, but native TRX works too.)
 
 `token` is **required** — every gate states exactly what it accepts, so there's never any doubt whether a route takes USDC, USDT, or the native coin. Name a built-in symbol (`'USDC'`, `'USDT'`), use `'native'` for the chain's own coin (ETH, BNB, SOL, TON, XLM, …), or pass a custom token by address. The symbol is all you write — the SDK fills in the contract + decimals.
 
@@ -167,6 +167,7 @@ Every token address below was verified on-chain (symbol + decimals) before shipp
 | `'tron'` | Tron | USDT |
 | `'near'` | NEAR | USDC, USDT |
 | `'sui'` | Sui | USDC |
+| `'aptos'` | Aptos | USDC, USDT |
 | `'stellar'` | Stellar | USDC, EURC |
 | `'xrpl'` | XRP Ledger | USDC, RLUSD |
 

package/dist/aptos-DTAONNMM.js

@@ -0,0 +1,332 @@
+import {
+  ConfirmationTimeoutError,
+  InsufficientFundsError,
+  UnknownTokenError,
+  WrongFamilyError,
+  nativeCost,
+  rejectForeignToken,
+  toInsufficientFundsError
+} from "./chunk-AGKC3C7Y.js";
+
+// src/drivers/aptos/index.ts
+import { Aptos, AptosConfig, Network, AccountAddress } 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/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 { privateKey } (ed25519-priv-0x\u2026) or { account }.`
+    );
+  }
+  if ("walletClient" in wallet) {
+    throw new WrongFamilyError(
+      `chain ${network} is Aptos; a viem { walletClient } can't be used \u2014 pass { privateKey } (ed25519-priv-0x\u2026) or { account }.`
+    );
+  }
+  if ("secretKey" in wallet || "signer" in wallet || "mnemonic" in wallet || "keypair" in wallet || "keyPair" in wallet || "secret" in wallet || "seed" in wallet || "accountId" in wallet) {
+    throw new WrongFamilyError(
+      `chain ${network} is Aptos; that looks like another family's wallet \u2014 pass { privateKey } (ed25519-priv-0x\u2026) or { account }.`
+    );
+  }
+  if (!("privateKey" in wallet) && !("account" in wallet)) {
+    throw new WrongFamilyError(
+      `chain ${network} is Aptos; wallet must be { privateKey } (ed25519-priv-0x\u2026) or { account }.`
+    );
+  }
+  return wallet;
+}
+function resolveAptosAccount(config) {
+  if (config.account) return config.account;
+  if (config.privateKey != null) {
+    try {
+      return Account.fromPrivateKey({ privateKey: new Ed25519PrivateKey(config.privateKey) });
+    } catch (cause) {
+      throw new WrongFamilyError(
+        "Aptos wallet { privateKey } is not a valid ed25519 secret (ed25519-priv-0x\u2026 or 0x\u2026 hex).",
+        { cause }
+      );
+    }
+  }
+  throw new WrongFamilyError("Aptos wallet needs { privateKey } (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 AccountAddress.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 {
+        AccountAddress.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() {
+      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 verify(ref, accept) {
+      return verifyAptos({ reader, hash: ref, accept });
+    }
+  };
+}
+export {
+  aptosDriver
+};