@piprail/sdk 1.0.0

package/dist/xrpl-7GWXDAVZ.js

@@ -0,0 +1,449 @@
+import {
+  delay
+} from "./chunk-FURB5RP7.js";
+import {
+  ConfirmationTimeoutError,
+  InsufficientFundsError,
+  UnknownTokenError,
+  WrongFamilyError,
+  floorUnits,
+  nativeCost,
+  rejectForeignToken,
+  toInsufficientFundsError
+} from "./chunk-3TQJJ4SQ.js";
+
+// src/drivers/xrpl/index.ts
+import { isValidClassicAddress } from "xrpl";
+
+// src/drivers/xrpl/chains.ts
+var XRP_DECIMALS = 6;
+var XRP_SYMBOL = "XRP";
+var XRPL_MAINNET = {
+  caip2: "xrpl:0",
+  // Public community cluster (serves HTTPS JSON-RPC). Not for sustained
+  // business use — pass your own `rpcUrl` in production.
+  defaultRpc: "https://xrplcluster.com/",
+  tokens: {
+    // Circle USDC — issuer Domain (`https://circle.com`) + currency code verified
+    // live on mainnet (gateway_balances) before shipping.
+    USDC: {
+      issuer: "rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE",
+      currencyHex: "5553444300000000000000000000000000000000",
+      decimals: 6,
+      symbol: "USDC"
+    },
+    // Ripple RLUSD — issuer Domain (`https://ripple.com/`) + currency code
+    // verified live on mainnet before shipping. Note: the RLUSD issuer sets
+    // requireDestinationTag, so payments always carry a DestinationTag (set below).
+    RLUSD: {
+      issuer: "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De",
+      currencyHex: "524C555344000000000000000000000000000000",
+      decimals: 6,
+      symbol: "RLUSD"
+    }
+  }
+};
+function xrplAssetId(currencyHex, issuer) {
+  return `${currencyHex}:${issuer}`;
+}
+function parseXrplAssetId(asset) {
+  if (asset === "native") return null;
+  const i = asset.indexOf(":");
+  if (i <= 0 || i === asset.length - 1) return null;
+  return { currencyHex: asset.slice(0, i), issuer: asset.slice(i + 1) };
+}
+
+// src/drivers/xrpl/pay.ts
+function nonceToMemoHex(nonce) {
+  return Buffer.from(nonce, "utf8").toString("hex").toUpperCase();
+}
+function nonceToDestinationTag(nonce) {
+  let h = 2166136261;
+  for (let i = 0; i < nonce.length; i += 1) {
+    h ^= nonce.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  const tag = h >>> 0;
+  return tag === 0 ? 1 : tag;
+}
+async function payXrpl(params) {
+  const { client, wallet, accept } = params;
+  try {
+    const [sequence, feeDrops, ledgerIndex] = await Promise.all([
+      client.accountSequence(wallet.classicAddress),
+      client.feeDrops(),
+      client.currentLedgerIndex()
+    ]);
+    const tx = {
+      TransactionType: "Payment",
+      Account: wallet.classicAddress,
+      Destination: accept.payTo,
+      DestinationTag: nonceToDestinationTag(accept.extra.nonce),
+      Amount: amountForAccept(accept),
+      Memos: [{ Memo: { MemoData: nonceToMemoHex(accept.extra.nonce) } }],
+      Sequence: sequence,
+      Fee: feeForSubmit(feeDrops),
+      LastLedgerSequence: ledgerIndex + 20,
+      Flags: 0
+      // NOT tfPartialPayment — require full delivery
+    };
+    const signed = wallet.sign(tx);
+    const res = await client.submit(signed.tx_blob);
+    const code = res.engine_result;
+    if (code.startsWith("tes")) return res.tx_json?.hash ?? signed.hash;
+    if (isAffordabilityCode(code)) {
+      throw new InsufficientFundsError(
+        `XRPL payment rejected (${code}): insufficient balance/reserve, or no trustline for this asset.`
+      );
+    }
+    throw new Error(
+      `XRPL payment rejected: ${code}${res.engine_result_message ? ` \u2014 ${res.engine_result_message}` : ""}`
+    );
+  } catch (err) {
+    if (err instanceof InsufficientFundsError) throw err;
+    throw toInsufficientFundsError(err) ?? err;
+  }
+}
+function amountForAccept(accept) {
+  if (accept.asset === "native") return accept.amount;
+  const parts = parseXrplAssetId(accept.asset);
+  if (!parts) throw new Error(`XRPL: malformed asset id "${accept.asset}".`);
+  return {
+    currency: parts.currencyHex,
+    issuer: parts.issuer,
+    value: accept.extra.amountFormatted
+  };
+}
+function feeForSubmit(openLedgerFee) {
+  const fee = Number(openLedgerFee);
+  return String(Number.isFinite(fee) && fee > 12 ? Math.ceil(fee) : 12);
+}
+function isAffordabilityCode(code) {
+  return /^(tecUNFUNDED|tecPATH_DRY|tecPATH_PARTIAL|tecINSUFF|tecNO_LINE_INSUF|terINSUF|tecNO_LINE)/.test(
+    code
+  );
+}
+
+// src/drivers/xrpl/verify.ts
+var RIPPLE_EPOCH_OFFSET = 946684800;
+async function verifyXrpl(params) {
+  const { reader, accept } = params;
+  const required = BigInt(accept.amount);
+  const nonce = accept.extra.nonce;
+  const wantMemo = nonceToMemoHex(nonce);
+  const wantAsset = parseXrplAssetId(accept.asset);
+  let txs;
+  try {
+    txs = await reader.transactionsForAccount(accept.payTo, 50);
+  } catch {
+    return rpcFailed(nonce);
+  }
+  const tx = txs.find(
+    (t) => t.TransactionType === "Payment" && t.Destination === accept.payTo && hasNonceMemo(t.Memos, wantMemo)
+  );
+  if (!tx) return notFound(nonce);
+  if (!tx.validated) {
+    return {
+      ok: false,
+      error: "insufficient_confirmations",
+      detail: `XRPL tx ${tx.hash} for nonce ${nonce} is not yet validated \u2014 retry.`
+    };
+  }
+  if (tx.result !== "tesSUCCESS") {
+    return {
+      ok: false,
+      error: "tx_reverted",
+      detail: `XRPL tx ${tx.hash} for nonce ${nonce} failed on-ledger (${tx.result}).`
+    };
+  }
+  if (typeof tx.date === "number") {
+    const ageSeconds = Math.floor(Date.now() / 1e3) - (tx.date + RIPPLE_EPOCH_OFFSET);
+    if (ageSeconds > accept.maxTimeoutSeconds) {
+      return {
+        ok: false,
+        error: "payment_expired",
+        detail: `Payment is ${ageSeconds}s old; max allowed is ${accept.maxTimeoutSeconds}s.`
+      };
+    }
+  }
+  const paid = deliveredBaseUnits(tx.delivered_amount, wantAsset, accept.extra.decimals);
+  if (paid === null) {
+    return {
+      ok: false,
+      error: "transfer_not_found",
+      detail: `XRPL tx ${tx.hash} carries our nonce but delivered no matching ${wantAsset ? "IOU" : "XRP"} to ${accept.payTo} (wrong asset, or delivered_amount unavailable).`
+    };
+  }
+  if (paid < required) {
+    return {
+      ok: false,
+      error: "amount_too_low",
+      detail: `Delivered ${paid}, required ${required}.`
+    };
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "onchain-proof",
+      success: true,
+      network: accept.network,
+      transaction: tx.hash,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer: tx.Account,
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function hasNonceMemo(memos, wantMemo) {
+  if (!memos) return false;
+  return memos.some((m) => (m.Memo?.MemoData ?? "").toUpperCase() === wantMemo);
+}
+function deliveredBaseUnits(delivered, want, decimals) {
+  if (delivered === void 0) return null;
+  if (want === null) {
+    if (typeof delivered !== "string") return null;
+    if (!/^\d+$/.test(delivered)) return null;
+    return BigInt(delivered);
+  }
+  if (typeof delivered === "string") return null;
+  if (delivered.currency.toUpperCase() !== want.currencyHex.toUpperCase() || delivered.issuer !== want.issuer) {
+    return null;
+  }
+  try {
+    return floorUnits(delivered.value, decimals);
+  } catch {
+    return null;
+  }
+}
+function notFound(nonce) {
+  return {
+    ok: false,
+    error: "transfer_not_found",
+    detail: `No matching XRPL payment found for nonce ${nonce} (not yet validated, or wrong recipient/amount/asset/memo).`
+  };
+}
+function rpcFailed(nonce) {
+  return {
+    ok: false,
+    error: "tx_not_found",
+    detail: `Could not read XRPL for nonce ${nonce} (transient RPC failure) \u2014 retry.`
+  };
+}
+
+// src/drivers/xrpl/wallet.ts
+import { Wallet, isValidSecret } from "xrpl";
+function assertXrplWallet(wallet, network) {
+  if (typeof wallet !== "object" || wallet === null) {
+    throw new WrongFamilyError(
+      `chain ${network} is XRPL; wallet must be { seed } (s\u2026 seed) or { wallet }.`
+    );
+  }
+  if ("privateKey" in wallet || "walletClient" in wallet) {
+    throw new WrongFamilyError(
+      `chain ${network} is XRPL; an EVM wallet can't be used \u2014 pass { seed } (s\u2026 seed) or { wallet }.`
+    );
+  }
+  if ("secretKey" in wallet || "signer" in wallet || "mnemonic" in wallet || "keyPair" in wallet || "secret" in wallet || "keypair" in wallet) {
+    throw new WrongFamilyError(
+      `chain ${network} is XRPL; that looks like a Solana/TON/Stellar wallet \u2014 pass { seed } (s\u2026 seed) or { wallet }.`
+    );
+  }
+  if (!("seed" in wallet) && !("wallet" in wallet)) {
+    throw new WrongFamilyError(
+      `chain ${network} is XRPL; wallet must be { seed } (s\u2026 seed) or { wallet }.`
+    );
+  }
+  return wallet;
+}
+function resolveXrplWallet(config) {
+  if (config.wallet) return config.wallet;
+  if (config.seed) {
+    if (!isValidSecret(config.seed)) {
+      throw new WrongFamilyError("XRPL wallet { seed } is not a valid s\u2026 secret seed.");
+    }
+    return Wallet.fromSeed(config.seed);
+  }
+  throw new WrongFamilyError("XRPL wallet needs { seed } (s\u2026 seed) or { wallet }.");
+}
+
+// src/drivers/xrpl/index.ts
+var xrplDriver = {
+  family: "xrpl",
+  resolve(opts) {
+    if (opts.chain !== "xrpl") return null;
+    const rpcUrl = opts.rpcUrl ?? XRPL_MAINNET.defaultRpc;
+    return makeXrplNetwork(XRPL_MAINNET, rpcUrl);
+  }
+};
+function makeXrplNetwork(preset, rpcUrl) {
+  const network = preset.caip2;
+  async function rpc(method, params) {
+    const res = await fetch(rpcUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ method, params: [params] })
+    });
+    if (!res.ok) throw new Error(`XRPL RPC ${method} HTTP ${res.status}`);
+    const json = await res.json();
+    const result = json.result;
+    if (!result || result.status === "error" || result.error) {
+      throw new Error(`XRPL RPC ${method} error: ${result?.error ?? "unknown"}`);
+    }
+    return result;
+  }
+  const payClient = {
+    async accountSequence(account) {
+      const r = await rpc("account_info", {
+        account,
+        ledger_index: "current"
+      });
+      return r.account_data.Sequence;
+    },
+    async feeDrops() {
+      const r = await rpc("fee", {});
+      return r.drops.open_ledger_fee;
+    },
+    async currentLedgerIndex() {
+      const r = await rpc("ledger_current", {});
+      return r.ledger_current_index;
+    },
+    async submit(txBlob) {
+      return rpc("submit", { tx_blob: txBlob });
+    }
+  };
+  const reader = {
+    async transactionsForAccount(account, limit) {
+      const r = await rpc("account_tx", {
+        account,
+        ledger_index_min: -1,
+        ledger_index_max: -1,
+        forward: false,
+        limit
+      });
+      return r.transactions.map(mapAccountTxEntry);
+    }
+  };
+  return {
+    family: "xrpl",
+    network,
+    supports: (n) => n === network,
+    resolveToken(token) {
+      if (token === "native") {
+        return { asset: "native", decimals: XRP_DECIMALS, symbol: XRP_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 XRPL (known: ${known}). Pass { issuer, currencyHex, decimals } for a custom IOU, or use 'native'.`
+          );
+        }
+        return {
+          asset: xrplAssetId(info.currencyHex, info.issuer),
+          decimals: info.decimals,
+          symbol: info.symbol
+        };
+      }
+      rejectForeignToken(token, "xrpl", network);
+      const t = token;
+      if (!t.issuer || !t.currencyHex || typeof t.decimals !== "number") {
+        throw new WrongFamilyError(
+          `chain ${network} is XRPL; a custom token must be { issuer, currencyHex, decimals }.`
+        );
+      }
+      return {
+        asset: xrplAssetId(t.currencyHex, t.issuer),
+        decimals: t.decimals,
+        symbol: t.symbol ?? t.currencyHex
+      };
+    },
+    describeAsset(asset) {
+      if (asset === "native") return { symbol: XRP_SYMBOL, decimals: XRP_DECIMALS };
+      for (const info of Object.values(preset.tokens)) {
+        if (xrplAssetId(info.currencyHex, info.issuer) === asset) {
+          return { symbol: info.symbol, decimals: info.decimals };
+        }
+      }
+      return null;
+    },
+    assertValidPayTo(payTo) {
+      if (payTo.startsWith("0x")) {
+        throw new WrongFamilyError(
+          `chain ${network} is XRPL, but payTo "${payTo}" looks like an EVM address.`
+        );
+      }
+      if (!isValidClassicAddress(payTo)) {
+        throw new WrongFamilyError(
+          `chain ${network} is XRPL, but payTo "${payTo}" is not a valid XRPL account (r\u2026).`
+        );
+      }
+    },
+    bindWallet(wallet) {
+      return { _native: assertXrplWallet(wallet, network) };
+    },
+    async send(wallet, accept) {
+      const w = resolveXrplWallet(wallet._native);
+      return payXrpl({ client: payClient, wallet: w, accept });
+    },
+    async confirm(ref) {
+      for (let i = 0; i < 12; i += 1) {
+        try {
+          const tx = await rpc("tx", {
+            transaction: ref
+          });
+          if (tx.validated) return { height: String(tx.ledger_index ?? 0) };
+        } catch {
+        }
+        await delay(1500);
+      }
+      throw new ConfirmationTimeoutError(`XRPL tx ${ref} not validated on-ledger in time.`);
+    },
+    async estimateCost() {
+      try {
+        const drops = await payClient.feeDrops();
+        const n = Number(drops);
+        const fee = BigInt(Number.isFinite(n) && n > 12 ? Math.ceil(n) : 12);
+        return nativeCost({
+          symbol: XRP_SYMBOL,
+          decimals: XRP_DECIMALS,
+          fee,
+          basis: "estimated",
+          detail: `network fee ${fee} drops`
+        });
+      } catch {
+        return nativeCost({
+          symbol: XRP_SYMBOL,
+          decimals: XRP_DECIMALS,
+          fee: 12n,
+          basis: "heuristic",
+          detail: "~12 drops (open-ledger fee unavailable)"
+        });
+      }
+    },
+    async verify(_ref, accept) {
+      return verifyXrpl({ reader, accept });
+    }
+  };
+}
+function mapAccountTxEntry(entry) {
+  const e = entry;
+  const t = e.tx_json ?? e.tx ?? {};
+  const meta = e.meta ?? e.metaData ?? {};
+  return {
+    hash: e.hash ?? t.hash ?? "",
+    validated: Boolean(e.validated),
+    result: meta.TransactionResult ?? "",
+    TransactionType: t.TransactionType ?? "",
+    Account: t.Account ?? "",
+    Destination: t.Destination,
+    Memos: t.Memos,
+    delivered_amount: meta.delivered_amount ?? meta.DeliveredAmount,
+    date: typeof t.date === "number" ? t.date : void 0
+  };
+}
+export {
+  xrplDriver
+};

package/package.json

@@ -0,0 +1,143 @@
+{
+  "name": "@piprail/sdk",
+  "version": "1.0.0",
+  "description": "Accept x402 crypto payments across 24 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, 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",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "ERRORS.md",
+    "STANDARDS.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json",
+    "prepublishOnly": "npm run build && npm test && npm run typecheck && npm run typecheck:test"
+  },
+  "keywords": [
+    "piprail",
+    "x402",
+    "402",
+    "payment-required",
+    "multichain",
+    "evm",
+    "solana",
+    "ton",
+    "tron",
+    "near",
+    "sui",
+    "stellar",
+    "xrpl",
+    "base",
+    "bnb-chain",
+    "ethereum",
+    "usdc",
+    "usdt",
+    "stablecoin",
+    "crypto-payments",
+    "agent-payments",
+    "ai-agent",
+    "express-middleware",
+    "payment-middleware"
+  ],
+  "author": "PipRail",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/piprail/piprail.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://piprail.com",
+  "bugs": "https://github.com/piprail/piprail/issues",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@mysten/sui": ">=2 <3",
+    "@solana/spl-token": "^0.4.0",
+    "@solana/web3.js": "^1.95.0",
+    "@stellar/stellar-sdk": ">=13 <16",
+    "@ton/core": ">=0.59 <1",
+    "@ton/crypto": ">=3 <4",
+    "@ton/ton": ">=15 <17",
+    "bs58": "^5.0.0",
+    "near-api-js": ">=7 <8",
+    "tronweb": ">=6 <7",
+    "viem": "^2.21.0",
+    "xrpl": ">=4 <5"
+  },
+  "peerDependenciesMeta": {
+    "@solana/web3.js": {
+      "optional": true
+    },
+    "@solana/spl-token": {
+      "optional": true
+    },
+    "@stellar/stellar-sdk": {
+      "optional": true
+    },
+    "bs58": {
+      "optional": true
+    },
+    "@ton/ton": {
+      "optional": true
+    },
+    "@ton/core": {
+      "optional": true
+    },
+    "@ton/crypto": {
+      "optional": true
+    },
+    "xrpl": {
+      "optional": true
+    },
+    "tronweb": {
+      "optional": true
+    },
+    "@mysten/sui": {
+      "optional": true
+    },
+    "near-api-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mysten/sui": "^2.17.0",
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.98.4",
+    "@stellar/stellar-sdk": "^15.1.0",
+    "@ton/core": "^0.63.1",
+    "@ton/crypto": "^3.3.0",
+    "@ton/ton": "^16.2.4",
+    "@types/node": "^22.10.0",
+    "bs58": "^5.0.0",
+    "near-api-js": "^7.2.0",
+    "tronweb": "^6.3.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "viem": "^2.51.2",
+    "vitest": "^2.1.8",
+    "xrpl": "^4.6.0"
+  }
+}