@piprail/sdk 2.4.0 → 2.6.0

package/dist/{near-MTYBCUYM.js → near-OTPQD6BI.js}

@@ -2,7 +2,9 @@ import {
   ConfirmationTimeoutError,
   InsufficientFundsError,
   RecipientNotReadyError,
+  SettlementError,
   UnknownTokenError,
+  UnsupportedSchemeError,
   WrongFamilyError,
   assertNoLegacyWalletKey,
   nativeCost,
@@ -11,10 +13,15 @@ import {
 } from "./chunk-7XK22JSQ.js";
 
 // src/drivers/near/index.ts
-import { JsonRpcProvider, Account, actions } from "near-api-js";
+import { JsonRpcProvider, Account, actions as actions2 } from "near-api-js";
 
 // src/drivers/near/chains.ts
 var NEAR_DECIMALS = 24;
+function isValidNearAccountId(id) {
+  if (id.startsWith("0x")) return false;
+  if (id.length < 2 || id.length > 64) return false;
+  return /^(([a-z\d]+[-_])*[a-z\d]+\.)*([a-z\d]+[-_])*[a-z\d]+$/.test(id);
+}
 var NEAR_MAINNET = {
   caip2: "near:mainnet",
   defaultRpc: "https://free.rpc.fastnear.com",
@@ -92,6 +99,190 @@ function isNearAffordability(err) {
   return /not enough|doesn't have enough|does not have enough|lack ?balance|exceeds .*balance|insufficient/i.test(m);
 }
 
+// src/drivers/near/exact.ts
+import { actions, buildDelegateAction, encodeSignedDelegate, DelegateAction, SCHEMA } from "near-api-js";
+import { deserialize } from "borsh";
+var FT_TRANSFER_GAS2 = 30000000000000n;
+var ONE_YOCTO2 = 1n;
+var ESTIMATED_BLOCK_SECONDS = 1;
+var NONCE_BLOCK_MULTIPLIER = 1000000n;
+async function payExactNear(input) {
+  const { signer, senderId, blockHeight, accessKeyNonce, accept } = input;
+  if (accept.asset === "native") {
+    throw new UnsupportedSchemeError(
+      "NEAR exact is NEP-141-only (an ft_transfer); native NEAR is not exact-payable. Pay via onchain-proof."
+    );
+  }
+  if (!isValidNearAccountId(accept.asset)) {
+    throw new UnsupportedSchemeError(`NEAR exact: asset "${accept.asset}" must be a NEP-141 contract account id.`);
+  }
+  if (!isValidNearAccountId(accept.payTo)) {
+    throw new UnsupportedSchemeError(`NEAR exact: payTo "${accept.payTo}" is not a valid NEAR account id.`);
+  }
+  if (!isValidNearAccountId(senderId)) {
+    throw new UnsupportedSchemeError(`NEAR exact: sender "${senderId}" is not a valid NEAR account id.`);
+  }
+  const t = accept.maxTimeoutSeconds;
+  if (!Number.isInteger(t) || t <= 0) {
+    throw new UnsupportedSchemeError("NEAR exact: maxTimeoutSeconds must be a positive integer.");
+  }
+  const timeoutBlocks = BigInt(Math.max(1, Math.ceil(t / ESTIMATED_BLOCK_SECONDS)));
+  const maxBlockHeight = blockHeight + timeoutBlocks;
+  const nonce = accessKeyNonce + 1n;
+  if (nonce >= blockHeight * NONCE_BLOCK_MULTIPLIER) {
+    throw new UnsupportedSchemeError(
+      "NEAR exact: the access-key nonce is at the protocol ceiling for this block height; cannot build a delegate action."
+    );
+  }
+  const publicKey = await signer.getPublicKey();
+  const action = actions.functionCall(
+    "ft_transfer",
+    { receiver_id: accept.payTo, amount: accept.amount },
+    FT_TRANSFER_GAS2,
+    ONE_YOCTO2
+  );
+  const delegateAction = buildDelegateAction({
+    senderId,
+    receiverId: accept.asset,
+    actions: [action],
+    nonce,
+    maxBlockHeight,
+    publicKey
+  });
+  const { signedDelegate } = await signer.signDelegateAction(delegateAction);
+  const encoded = encodeSignedDelegate(signedDelegate);
+  return {
+    payload: { signedDelegateAction: Buffer.from(encoded).toString("base64") },
+    payerFrom: senderId,
+    // A stable id for THIS authorization (single-use on-chain via the access-key nonce): the
+    // client records it as the spend ref and re-presents the SAME signed action on a retry.
+    nonce: `${senderId}:${nonce.toString()}`
+  };
+}
+var MAX_RELAY_GAS = 300000000000000n;
+var b64decode = (s) => new Uint8Array(Buffer.from(s, "base64"));
+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 verifyExactNear(payload, accept, currentBlockHeight) {
+  if (accept.asset === "native" || !isValidNearAccountId(accept.asset)) {
+    return fail("transfer_not_found", `NEAR exact rail asset "${accept.asset}" is not a NEP-141 contract.`);
+  }
+  if (typeof payload?.signedDelegateAction !== "string") {
+    return fail("signature_invalid", "NEAR exact payload is missing signedDelegateAction.");
+  }
+  let decoded;
+  try {
+    decoded = deserialize(SCHEMA.SignedDelegate, b64decode(payload.signedDelegateAction));
+  } catch (err) {
+    return fail("signature_invalid", `Unparseable SignedDelegateAction: ${shorten(err instanceof Error ? err.message : String(err))}.`);
+  }
+  const da = decoded?.delegateAction;
+  const sig = decoded?.signature;
+  if (!da || sig == null) return fail("signature_invalid", "SignedDelegateAction is missing its delegate action or signature.");
+  if (!Array.isArray(da.actions) || da.actions.length !== 1) {
+    return fail("transfer_not_found", `the delegate must carry exactly one action, got ${da.actions?.length ?? 0}.`);
+  }
+  const fc = da.actions[0]?.functionCall;
+  if (!fc || fc.methodName !== "ft_transfer") {
+    return fail("transfer_not_found", `the delegated action is not an ft_transfer (got "${fc?.methodName ?? "none"}").`);
+  }
+  if (da.receiverId !== accept.asset) {
+    return fail("transfer_not_found", `delegate receiver ${da.receiverId} \u2260 token contract ${accept.asset}.`);
+  }
+  let args;
+  try {
+    args = JSON.parse(Buffer.from(fc.args ?? new Uint8Array()).toString());
+  } catch {
+    return fail("transfer_not_found", "the ft_transfer args are not valid JSON.");
+  }
+  if (args.receiver_id !== accept.payTo) {
+    return fail("wrong_recipient", `ft_transfer pays ${String(args.receiver_id)}, not payTo ${accept.payTo}.`);
+  }
+  if (typeof args.amount !== "string" || !/^\d+$/.test(args.amount) || BigInt(args.amount) < BigInt(accept.amount)) {
+    return fail("amount_too_low", `ft_transfer pays ${String(args.amount)} of the token, required ${accept.amount}.`);
+  }
+  let deposit;
+  let gas;
+  try {
+    deposit = BigInt(fc.deposit ?? 0);
+    gas = BigInt(fc.gas ?? 0);
+  } catch {
+    return fail("signature_invalid", "the ft_transfer has a malformed gas/deposit.");
+  }
+  if (deposit !== ONE_YOCTO2) {
+    return fail("signature_invalid", `attached deposit ${deposit} \u2260 the required 1 yoctoNEAR (relayer drain guard).`);
+  }
+  if (gas > MAX_RELAY_GAS) {
+    return fail("signature_invalid", `delegated gas ${gas} exceeds the ${MAX_RELAY_GAS} cap (relayer drain guard).`);
+  }
+  if (currentBlockHeight !== null) {
+    let maxBlock;
+    try {
+      maxBlock = BigInt(da.maxBlockHeight ?? 0);
+    } catch {
+      return fail("signature_invalid", "the delegate has a malformed max_block_height.");
+    }
+    if (maxBlock <= currentBlockHeight) {
+      return fail("payment_expired", `the delegate expired (max_block_height ${maxBlock} \u2264 current ${currentBlockHeight}).`);
+    }
+  }
+  if (!da.senderId || !isValidNearAccountId(String(da.senderId))) {
+    return fail("signature_invalid", `the delegate sender "${String(da.senderId)}" is not a valid NEAR account id.`);
+  }
+  return { ok: true, senderId: String(da.senderId), delegateAction: new DelegateAction(da), signature: sig };
+}
+async function verifyAndSettleExactNear(input) {
+  const { client, payload, accept } = input;
+  let height = null;
+  try {
+    height = await client.currentBlockHeight();
+  } catch {
+  }
+  const v = verifyExactNear(payload, accept, height);
+  if (!v.ok) return v;
+  let result;
+  try {
+    result = await client.relay({ senderId: v.senderId, delegateAction: v.delegateAction, signature: v.signature });
+  } catch (err) {
+    const m = err instanceof Error ? err.message : String(err);
+    if (/invalid.*nonce|nonce.*used|DelegateActionInvalidNonce/i.test(m)) {
+      return fail("tx_already_used", `this delegate was already used (single-use nonce): ${shorten(m)}.`);
+    }
+    if (/expired|DelegateActionExpired|max_block_height|deadline/i.test(m)) {
+      return fail("payment_expired", `the delegate expired before it landed: ${shorten(m)}.`);
+    }
+    if (/not enough|insufficient|exceeded the prepaid gas|NotEnoughBalance|doesn't have enough|is not registered/i.test(m)) {
+      return fail("tx_reverted", `the ft_transfer would fail on chain: ${shorten(m)}.`);
+    }
+    throw new SettlementError(
+      `NEAR exact settle: the relayer could not submit the delegate (${shorten(m)}). The buyer's signed delegate is still valid \u2014 fund/fix the relayer and the buyer can re-present it.`,
+      { cause: err }
+    );
+  }
+  if (!result.innerSuccess) {
+    return fail("tx_reverted", `the ft_transfer receipt did not succeed on chain (tx ${result.txHash}).`);
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "exact",
+      success: true,
+      network: accept.network,
+      transaction: result.txHash,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer: v.senderId,
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
 // src/drivers/near/verify.ts
 function parseFtTransferEvent(line) {
   const marker = "EVENT_JSON:";
@@ -253,11 +444,6 @@ var nearDriver = {
     return makeNearNetwork(NEAR_MAINNET, rpcUrl);
   }
 };
-function isValidNearAccountId(id) {
-  if (id.startsWith("0x")) return false;
-  if (id.length < 2 || id.length > 64) return false;
-  return /^(([a-z\d]+[-_])*[a-z\d]+\.)*([a-z\d]+[-_])*[a-z\d]+$/.test(id);
-}
 function makeNearNetwork(preset, rpcUrl) {
   const provider = new JsonRpcProvider({ url: rpcUrl });
   const network = preset.caip2;
@@ -358,7 +544,7 @@ function makeNearNetwork(preset, rpcUrl) {
           const outcome = await account.signAndSendTransaction({
             receiverId: contractId,
             actions: [
-              actions.functionCall("ft_transfer", { receiver_id: receiverId, amount, memo }, gas, deposit)
+              actions2.functionCall("ft_transfer", { receiver_id: receiverId, amount, memo }, gas, deposit)
             ]
           });
           return { hash: hashOf(outcome) };
@@ -366,7 +552,7 @@ function makeNearNetwork(preset, rpcUrl) {
         async nativeTransfer({ receiverId, amount }) {
           const outcome = await account.signAndSendTransaction({
             receiverId,
-            actions: [actions.transfer(BigInt(amount))]
+            actions: [actions2.transfer(BigInt(amount))]
           });
           return { hash: hashOf(outcome) };
         }
@@ -445,6 +631,96 @@ function makeNearNetwork(preset, rpcUrl) {
     async verify(ref, accept) {
       const { senderId, hash } = decodeRef(ref);
       return verifyNear({ reader, hash, senderId, accept });
+    },
+    // Standard x402 `exact` rail, BUYER side — build a NEP-366 SignedDelegateAction authorizing one
+    // NEP-141 ft_transfer (per scheme_exact_near.md). The buyer signs with its FULL-ACCESS key and
+    // spends ZERO NEAR; a keyless facilitator's relayer prepays the gas + 1 yoctoNEAR and submits.
+    // NEAR exact is NEP-141-only + facilitator-settled (see ./exact.ts for why) — native NEAR isn't
+    // exact-payable. Pre-reads the access-key nonce + final block height, then defers to payExactNear.
+    async payExact(wallet, accept) {
+      const { accountId, signer } = resolveNearWallet(wallet._native);
+      const publicKey = await signer.getPublicKey();
+      const [accessKey, block] = await Promise.all([
+        provider.query({
+          request_type: "view_access_key",
+          finality: "final",
+          account_id: accountId,
+          public_key: publicKey.toString()
+        }),
+        provider.viewBlock({ finality: "final" })
+      ]);
+      const accessKeyNonce = BigInt(accessKey.nonce ?? 0);
+      const blockHeight = BigInt(block.header?.height ?? 0);
+      const { payload, payerFrom, nonce } = await payExactNear({
+        signer,
+        senderId: accountId,
+        blockHeight,
+        accessKeyNonce,
+        accept
+      });
+      return { payload, accepted: accept, payerFrom, nonce };
+    },
+    // The gate's rail-advertisement SPI. NEAR exact is NEP-141-only. The fee payer (the relayer that
+    // prepays gas + the 1 yocto, so the BUYER pays nothing) comes from EITHER the merchant's own bound
+    // `relayer` (SELF mode — what works today) OR a facilitator-provided `feePayer` (facilitator mode —
+    // for when a NEAR x402 facilitator ships; none does yet). `null` for native / non-NEP-141 / when no
+    // fee payer is available. The buyer's SignedDelegateAction is self-contained, so `feePayer` rides in
+    // `extra` only for observability + (future) facilitator forwarding.
+    async resolveExactRail({ asset, relayer, feePayer }) {
+      if (asset === "native" || !isValidNearAccountId(asset)) return null;
+      let fp = feePayer;
+      if (!fp && relayer) {
+        try {
+          fp = resolveNearWallet(relayer._native).accountId;
+        } catch {
+          return null;
+        }
+      }
+      if (!fp) return null;
+      return { method: "near", extra: { feePayer: fp } };
+    },
+    // Standard x402 `exact` rail, SELLER side (SELF-SETTLE) — decode + verify the inbound delegate
+    // against the trusted accept, then RELAY it from the merchant's own NEAR relayer (which prepays the
+    // sub-cent gas + the 1 yocto). The buyer stays gasless. THIS is how a NEAR gate gets paid today
+    // (no third-party facilitator settles NEAR yet). The drain guard (gas/deposit caps) lives in
+    // verifyAndSettleExactNear, invisible to the gate.
+    async settleExactSelf({ relayer, payload, accept }) {
+      if (!("signedDelegateAction" in payload)) {
+        return { ok: false, error: "signature_invalid", detail: "NEAR exact expects a { signedDelegateAction } payload." };
+      }
+      let relayerWallet;
+      try {
+        relayerWallet = resolveNearWallet(relayer._native);
+      } catch (err) {
+        throw new SettlementError(
+          `NEAR exact settle: the relayer wallet is invalid (${err instanceof Error ? err.message : String(err)}).`,
+          { cause: err }
+        );
+      }
+      const relayerAccount = new Account(relayerWallet.accountId, provider, relayerWallet.signer);
+      const isSuccess = (s) => typeof s === "object" && s !== null && "SuccessValue" in s;
+      const client = {
+        async currentBlockHeight() {
+          try {
+            const b = await provider.viewBlock({ finality: "final" });
+            return b.header?.height != null ? BigInt(b.header.height) : null;
+          } catch {
+            return null;
+          }
+        },
+        async relay({ senderId, delegateAction, signature }) {
+          const outcome = await relayerAccount.signAndSendTransaction({
+            receiverId: senderId,
+            actions: [actions2.signedDelegate({ delegateAction, signature })],
+            waitUntil: "FINAL"
+          });
+          const txHash = outcome.transaction?.hash ?? "";
+          const tokenReceipt = (outcome.receipts_outcome ?? []).find((r) => r.outcome?.executor_id === accept.asset);
+          const innerSuccess = tokenReceipt ? isSuccess(tokenReceipt.outcome?.status) : isSuccess(outcome.status);
+          return { txHash, innerSuccess };
+        }
+      };
+      return verifyAndSettleExactNear({ client, payload, accept });
     }
   };
 }
@@ -456,10 +732,10 @@ function decodeRef(ref) {
   if (i < 0) return { senderId: "", hash: ref };
   return { senderId: ref.slice(0, i), hash: ref.slice(i + 1) };
 }
-function sumTransferDeposits(actions2) {
-  if (!Array.isArray(actions2)) return 0n;
+function sumTransferDeposits(actions3) {
+  if (!Array.isArray(actions3)) return 0n;
   let sum = 0n;
-  for (const a of actions2) {
+  for (const a of actions3) {
     const t = a.Transfer ?? a.transfer;
     if (t && t.deposit != null) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -86,6 +86,7 @@
     "@ton/crypto": ">=3 <4",
     "@ton/ton": ">=15 <17",
     "algosdk": ">=3 <4",
+    "borsh": ">=2 <3",
     "bs58": "^5.0.0",
     "near-api-js": ">=7 <8",
     "tronweb": ">=6 <7",
@@ -131,6 +132,9 @@
     },
     "algosdk": {
       "optional": true
+    },
+    "borsh": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -144,6 +148,7 @@
     "@ton/ton": "^16.2.4",
     "@types/node": "^22.10.0",
     "algosdk": "^3.5.2",
+    "borsh": "^2.0.0",
     "bs58": "^5.0.0",
     "near-api-js": "^7.2.0",
     "tronweb": "^6.3.0",