@piprail/sdk 2.3.0 → 2.4.0

package/dist/algorand-WB6PBJU4.js

@@ -0,0 +1,678 @@
+import {
+  ConfirmationTimeoutError,
+  InsufficientFundsError,
+  RecipientNotReadyError,
+  SettlementError,
+  UnknownTokenError,
+  UnsupportedSchemeError,
+  WrongFamilyError,
+  assertNoLegacyWalletKey,
+  nativeCost,
+  rejectForeignToken,
+  toInsufficientFundsError
+} from "./chunk-7XK22JSQ.js";
+
+// src/drivers/algorand/index.ts
+import algosdk3 from "algosdk";
+
+// src/drivers/algorand/chains.ts
+var ALGO_DECIMALS = 6;
+var ALGO_SYMBOL = "ALGO";
+var ALGORAND_MAINNET = {
+  caip2: "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
+  defaultAlgod: "https://mainnet-api.algonode.cloud",
+  defaultIndexer: "https://mainnet-idx.algonode.cloud",
+  tokens: {
+    // Circle USDC — ASA id + 6 decimals verified live on mainnet algod
+    // (/v2/assets/31566704 → unit-name "USDC", decimals 6, creator = Circle) before shipping.
+    // USDC-only: Tether deprecated USDT on Algorand, so it's intentionally omitted.
+    USDC: { assetId: 31566704, decimals: 6, symbol: "USDC" }
+  }
+};
+function algorandAssetId(assetId) {
+  return String(assetId);
+}
+function parseAlgorandAssetId(asset) {
+  if (asset === "native") return null;
+  if (!/^\d+$/.test(asset)) return null;
+  const n = Number(asset);
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
+// src/drivers/algorand/pay.ts
+async function payAlgorand(params) {
+  const { client, sk, sender, accept } = params;
+  const note = new TextEncoder().encode(accept.extra.nonce);
+  const amount = BigInt(accept.amount);
+  const assetId = parseAlgorandAssetId(accept.asset);
+  try {
+    const { txn, txId } = await client.build({
+      sender,
+      receiver: accept.payTo,
+      amount,
+      note,
+      ...assetId === null ? {} : { assetId }
+    });
+    await client.signSend({ txn, sk });
+    return txId;
+  } catch (err) {
+    const mapped = mapAlgorandError(err, accept.payTo);
+    if (mapped) throw mapped;
+    throw toInsufficientFundsError(err) ?? err;
+  }
+}
+function mapAlgorandError(err, payTo) {
+  const m = err instanceof Error ? err.message : String(err);
+  if (/must optin/i.test(m) || /missing from/i.test(m) && m.includes(payTo)) {
+    return new RecipientNotReadyError(
+      `Algorand recipient ${payTo} hasn't opted into this asset \u2014 it must opt in (a 0-amount asset transfer to itself) before it can receive. (Algorand: ${firstLine(m)})`,
+      { cause: err }
+    );
+  }
+  if (/overspend|below min|min(imum)? balance|tried to spend|balance \d+ below|asset \d+ missing from|insufficient|underflow/i.test(
+    m
+  )) {
+    return new InsufficientFundsError(
+      `Algorand payment failed: the sender can't cover it \u2014 token balance, ALGO for fees, the 0.1-ALGO minimum balance, or a missing asset opt-in on the sender. (Algorand: ${firstLine(m)})`,
+      { cause: err }
+    );
+  }
+  return null;
+}
+function firstLine(message) {
+  return message.split("\n")[0].slice(0, 160);
+}
+
+// src/drivers/algorand/exact.ts
+import algosdk from "algosdk";
+var ZERO_ADDRESS = algosdk.Address.zeroAddress().toString();
+var GROUP_SIZE = 2;
+var MAX_GROUP_FEE = 20000n;
+var b64encode = (bytes) => Buffer.from(bytes).toString("base64");
+var b64decode = (s) => new Uint8Array(Buffer.from(s, "base64"));
+function addrEq(a, b) {
+  return a != null && a.toString() === b;
+}
+function isSet(addr) {
+  return addr != null && addr.toString() !== ZERO_ADDRESS;
+}
+function randomNote() {
+  const g = globalThis.crypto;
+  if (!g?.getRandomValues) {
+    throw new UnsupportedSchemeError("Algorand exact: no Web Crypto CSPRNG available to generate a unique note.");
+  }
+  return g.getRandomValues(new Uint8Array(32));
+}
+async function payExactAlgorand(input) {
+  const { suggestedParams, sk, sender, accept } = input;
+  if (accept.asset === "native") {
+    throw new UnsupportedSchemeError(
+      "Algorand exact is ASA-only (an asset transfer); native ALGO is not exact-payable. Pay via onchain-proof."
+    );
+  }
+  const feePayer = accept.extra.feePayer;
+  if (!feePayer) {
+    throw new UnsupportedSchemeError("Algorand exact rail must advertise extra.feePayer (the fee sponsor address).");
+  }
+  const assetId = parseAlgorandAssetId(accept.asset);
+  if (assetId === null) {
+    throw new UnsupportedSchemeError(`Algorand exact rail asset "${accept.asset}" must be a numeric ASA id.`);
+  }
+  if (!algosdk.isValidAddress(feePayer)) {
+    throw new UnsupportedSchemeError(`Algorand exact: extra.feePayer "${feePayer}" is not a valid Algorand address.`);
+  }
+  if (!algosdk.isValidAddress(accept.payTo)) {
+    throw new UnsupportedSchemeError(`Algorand exact: payTo "${accept.payTo}" is not a valid Algorand address.`);
+  }
+  if (feePayer === sender) {
+    throw new UnsupportedSchemeError(
+      "Algorand exact: the fee payer must differ from the payer \u2014 the buyer must pay ZERO ALGO (the sponsor pays the pooled fee)."
+    );
+  }
+  const minFee = suggestedParams.minFee != null ? BigInt(suggestedParams.minFee) : 1000n;
+  const groupFee = minFee * BigInt(GROUP_SIZE);
+  const axfer = algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({
+    sender,
+    receiver: accept.payTo,
+    amount: BigInt(accept.amount),
+    assetIndex: assetId,
+    note: input.note ?? randomNote(),
+    suggestedParams: { ...suggestedParams, flatFee: true, fee: 0n }
+  });
+  const feeTxn = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+    sender: feePayer,
+    receiver: feePayer,
+    amount: 0n,
+    suggestedParams: { ...suggestedParams, flatFee: true, fee: groupFee }
+  });
+  algosdk.assignGroupID([axfer, feeTxn]);
+  const signedAxfer = axfer.signTxn(sk);
+  const unsignedFee = algosdk.encodeUnsignedTransaction(feeTxn);
+  return {
+    payload: { paymentIndex: 0, paymentGroup: [b64encode(signedAxfer), b64encode(unsignedFee)] },
+    payerFrom: sender,
+    nonce: axfer.txID()
+  };
+}
+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 decodeElement(bytes) {
+  try {
+    const st = algosdk.decodeSignedTransaction(bytes);
+    return { txn: st.txn, signed: st.sig != null || st.msig != null || st.lsig != null, raw: bytes };
+  } catch {
+    return { txn: algosdk.decodeUnsignedTransaction(bytes), signed: false, raw: bytes };
+  }
+}
+async function verifyAndSettleExactAlgorand(input) {
+  const { client, feePayerSk, feePayerAddr, payload, accept } = input;
+  const railFeePayer = accept.extra.feePayer;
+  if (!railFeePayer) throw new SettlementError("Algorand exact: rail is missing extra.feePayer.");
+  if (railFeePayer !== feePayerAddr) {
+    throw new SettlementError("Algorand exact: the gate relayer address does not match the rail extra.feePayer \u2014 misconfigured rail.");
+  }
+  const assetId = parseAlgorandAssetId(accept.asset);
+  if (assetId === null) throw new SettlementError(`Algorand exact: rail asset "${accept.asset}" is not a numeric ASA id.`);
+  if (!algosdk.isValidAddress(accept.payTo)) throw new SettlementError(`Algorand exact: rail payTo "${accept.payTo}" is invalid.`);
+  const { paymentIndex, paymentGroup } = payload;
+  if (paymentGroup.length !== GROUP_SIZE) {
+    return fail("signature_invalid", `Algorand exact expects a ${GROUP_SIZE}-transaction group (payment + fee), got ${paymentGroup.length}.`);
+  }
+  if (!Number.isInteger(paymentIndex) || paymentIndex < 0 || paymentIndex >= GROUP_SIZE) {
+    return fail("signature_invalid", `paymentIndex ${paymentIndex} is out of range for a ${GROUP_SIZE}-txn group.`);
+  }
+  let elements;
+  try {
+    elements = paymentGroup.map((b64) => decodeElement(b64decode(b64)));
+  } catch (err) {
+    return fail("signature_invalid", `Unparseable Algorand group: ${shorten(err instanceof Error ? err.message : String(err))}.`);
+  }
+  const payElement = elements[paymentIndex];
+  const feeElement = elements[paymentIndex === 0 ? 1 : 0];
+  if (!payElement.signed) {
+    return fail("signature_invalid", "The payment transaction is not signed by the buyer.");
+  }
+  const pay = payElement.txn;
+  if (pay.type !== "axfer" || !pay.assetTransfer) {
+    return fail("transfer_not_found", "The payment transaction is not an ASA asset-transfer (axfer).");
+  }
+  const at = pay.assetTransfer;
+  if (BigInt(at.assetIndex) !== BigInt(assetId)) {
+    return fail("transfer_not_found", `Transfer asset id ${at.assetIndex} \u2260 rail asset ${assetId}.`);
+  }
+  if (!addrEq(at.receiver, accept.payTo)) {
+    return fail("wrong_recipient", `Transfer pays ${at.receiver?.toString()}, not payTo ${accept.payTo}.`);
+  }
+  if (BigInt(at.amount) < BigInt(accept.amount)) {
+    return fail("amount_too_low", `Transfer pays ${at.amount} of the ASA, required ${accept.amount}.`);
+  }
+  if (isSet(at.closeRemainderTo)) return fail("signature_invalid", "The payment transaction has an asset-close \u2014 refused.");
+  if (isSet(pay.rekeyTo)) return fail("signature_invalid", "The payment transaction has a rekey \u2014 refused.");
+  if (feeElement.signed) {
+    return fail("signature_invalid", "The fee transaction must be left UNSIGNED for the sponsor to sign.");
+  }
+  const fee = feeElement.txn;
+  if (fee.type !== "pay" || !fee.payment) {
+    return fail("signature_invalid", "The fee transaction must be a payment (pay) transaction.");
+  }
+  if (!addrEq(fee.sender, railFeePayer)) {
+    return fail("signature_invalid", `The fee transaction sender ${fee.sender?.toString()} is not the rail fee payer ${railFeePayer}.`);
+  }
+  if (BigInt(fee.payment.amount) !== 0n) {
+    return fail("signature_invalid", "The fee transaction must move 0 ALGO (it only pools the group fee).");
+  }
+  const feeAmount = fee.fee != null ? BigInt(fee.fee) : 0n;
+  if (feeAmount > MAX_GROUP_FEE) {
+    return fail("signature_invalid", `The fee transaction fee ${feeAmount} \xB5ALGO exceeds the ${MAX_GROUP_FEE} cap (fee-payer drain guard).`);
+  }
+  if (isSet(fee.payment.closeRemainderTo)) return fail("signature_invalid", "The fee transaction has an account-close \u2014 refused.");
+  if (isSet(fee.rekeyTo)) return fail("signature_invalid", "The fee transaction has a rekey \u2014 refused.");
+  const payGid = pay.group;
+  const feeGid = fee.group;
+  if (!payGid || !feeGid || payGid.length === 0) {
+    return fail("signature_invalid", "The transactions are not part of an atomic group.");
+  }
+  if (Buffer.from(payGid).toString("hex") !== Buffer.from(feeGid).toString("hex")) {
+    return fail("signature_invalid", "The payment and fee transactions belong to different groups.");
+  }
+  let feeSigned;
+  try {
+    feeSigned = fee.signTxn(feePayerSk);
+  } catch (err) {
+    throw new SettlementError(`Algorand exact settle: the gate could not sign the fee transaction (${shorten(err instanceof Error ? err.message : String(err))}).`, { cause: err });
+  }
+  const signedGroup = elements.map((el, i) => i === paymentIndex ? payElement.raw : feeSigned);
+  try {
+    const sim = await client.simulate(signedGroup);
+    if (sim.failureMessage) {
+      const m = sim.failureMessage;
+      if (/signature|sig|auth/i.test(m)) return fail("signature_invalid", `Signature verification failed: ${shorten(m)}.`);
+      if (/\bround\b|expired|lifetime|validity|dead/i.test(m)) return fail("payment_expired", `Transaction validity window is no longer valid: ${shorten(m)}.`);
+      if (/overspend|below min|underflow|insufficient|asset|frozen|opt|missing/i.test(m)) return fail("tx_reverted", `Group would fail on-chain: ${shorten(m)}.`);
+      return fail("tx_reverted", `Group would fail on-chain: ${shorten(m)}.`);
+    }
+  } catch {
+  }
+  const buyerTxid = pay.txID();
+  try {
+    await client.submit(signedGroup);
+  } catch (err) {
+    const m = err instanceof Error ? err.message : String(err);
+    if (/signature|sig|auth|malformed/i.test(m)) return fail("signature_invalid", `Settle rejected \u2014 bad signature: ${shorten(m)}.`);
+    if (/already in ledger|already committed|duplicate/i.test(m)) return fail("tx_already_used", `This payment was already settled: ${shorten(m)}.`);
+    if (/\bround\b|expired|lifetime|stale|validity/i.test(m)) return fail("payment_expired", `Settle rejected \u2014 validity window expired: ${shorten(m)}.`);
+    throw new SettlementError(
+      `Algorand exact settle: the group 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 round;
+  try {
+    round = await client.waitForConfirmation(buyerTxid);
+  } catch (err) {
+    throw new SettlementError(`Algorand exact settle: submitted ${buyerTxid} 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 (round === null) {
+    throw new SettlementError(`Algorand exact settle: submitted ${buyerTxid} but it did not confirm in time. It likely landed \u2014 re-verify before re-presenting; do NOT re-pay.`);
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "exact",
+      success: true,
+      network: accept.network,
+      transaction: buyerTxid,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer: pay.sender.toString(),
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+
+// src/drivers/algorand/verify.ts
+async function verifyAlgorand(params) {
+  const { reader, accept } = params;
+  const nonce = accept.extra.nonce;
+  const required = BigInt(accept.amount);
+  const wantAssetId = parseAlgorandAssetId(accept.asset);
+  let txs;
+  try {
+    txs = await reader.transactionsForAccount(accept.payTo, 50);
+  } catch {
+    return rpcFailed(nonce);
+  }
+  const tx = txs.find((t) => typeof t.note === "string" && t.note === nonce);
+  if (!tx) return notFound(nonce);
+  if (typeof tx.roundTime === "number") {
+    const ageSeconds = Math.floor(Date.now() / 1e3) - tx.roundTime;
+    if (Number.isFinite(ageSeconds) && ageSeconds > accept.maxTimeoutSeconds) {
+      return {
+        ok: false,
+        error: "payment_expired",
+        detail: `Payment is ${ageSeconds}s old; max allowed is ${accept.maxTimeoutSeconds}s.`
+      };
+    }
+  }
+  const isNative = wantAssetId === null;
+  const typeOk = isNative ? tx.txType === "pay" : tx.txType === "axfer";
+  const assetOk = isNative ? tx.assetId == null : tx.assetId === wantAssetId;
+  if (!typeOk || tx.receiver !== accept.payTo || !assetOk) {
+    return {
+      ok: false,
+      error: "transfer_not_found",
+      detail: `Algorand tx ${tx.id} carries our nonce but has no matching ${isNative ? "ALGO" : `ASA ${wantAssetId}`} transfer to ${accept.payTo}.`
+    };
+  }
+  let paid = 0n;
+  try {
+    paid = tx.amount ? BigInt(tx.amount) : 0n;
+  } catch {
+    paid = 0n;
+  }
+  if (paid < required) {
+    return { ok: false, error: "amount_too_low", detail: `Paid ${paid}, required ${required}.` };
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "onchain-proof",
+      success: true,
+      network: accept.network,
+      transaction: tx.id,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer: tx.sender ?? "",
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function notFound(nonce) {
+  return {
+    ok: false,
+    error: "transfer_not_found",
+    detail: `No matching Algorand payment found for nonce ${nonce} (not yet settled, or wrong recipient/amount/asset/note).`
+  };
+}
+function rpcFailed(nonce) {
+  return {
+    ok: false,
+    error: "tx_not_found",
+    detail: `Could not read the Algorand indexer for nonce ${nonce} (transient RPC failure) \u2014 retry.`
+  };
+}
+
+// src/drivers/algorand/wallet.ts
+import algosdk2 from "algosdk";
+function assertAlgorandWallet(wallet, network) {
+  if (typeof wallet !== "object" || wallet === null) {
+    throw new WrongFamilyError(
+      `chain ${network} is Algorand; wallet must be { key } (25-word mnemonic) or { account }.`
+    );
+  }
+  assertNoLegacyWalletKey(wallet, "Algorand");
+  if (!("key" in wallet) && !("account" in wallet)) {
+    throw new WrongFamilyError(
+      `chain ${network} is Algorand; wallet must be { key } (25-word mnemonic) or { account }.`
+    );
+  }
+  return wallet;
+}
+function resolveAlgorandWallet(config) {
+  if (config.account) {
+    return { addr: String(config.account.addr), sk: config.account.sk };
+  }
+  if (config.key != null) {
+    try {
+      const { addr, sk } = algosdk2.mnemonicToSecretKey(config.key);
+      return { addr: addr.toString(), sk };
+    } catch (cause) {
+      throw new WrongFamilyError(
+        "Algorand wallet { key } is not a valid 25-word Algorand mnemonic.",
+        { cause }
+      );
+    }
+  }
+  throw new WrongFamilyError("Algorand wallet needs { key } (25-word mnemonic) or { account }.");
+}
+
+// src/drivers/algorand/index.ts
+var algorandDriver = {
+  family: "algorand",
+  resolve(opts) {
+    if (opts.chain !== "algorand") return null;
+    const algodUrl = opts.rpcUrl ?? ALGORAND_MAINNET.defaultAlgod;
+    return makeAlgorandNetwork(ALGORAND_MAINNET, algodUrl);
+  }
+};
+function makeAlgorandNetwork(preset, algodUrl) {
+  const algod = new algosdk3.Algodv2("", algodUrl, "");
+  const indexer = new algosdk3.Indexer("", preset.defaultIndexer, "");
+  const network = preset.caip2;
+  const reader = {
+    async transactionsForAccount(account, limit) {
+      const res = await indexer.lookupAccountTransactions(account).limit(limit).do();
+      return (res.transactions ?? []).map((t) => adaptTxn(t)).filter((r) => r !== null);
+    }
+  };
+  const payClient = {
+    async build(transfer) {
+      const suggestedParams = await algod.getTransactionParams().do();
+      const common = {
+        sender: transfer.sender,
+        receiver: transfer.receiver,
+        amount: transfer.amount,
+        note: transfer.note,
+        suggestedParams
+      };
+      const txn = transfer.assetId === void 0 ? algosdk3.makePaymentTxnWithSuggestedParamsFromObject(common) : algosdk3.makeAssetTransferTxnWithSuggestedParamsFromObject({
+        ...common,
+        assetIndex: transfer.assetId
+      });
+      return { txn, txId: txn.txID() };
+    },
+    async signSend({ txn, sk }) {
+      const signed = txn.signTxn(sk);
+      await algod.sendRawTransaction(signed).do();
+    }
+  };
+  const settleClient = {
+    async simulate(signedGroup) {
+      const resp = await algod.simulateRawTransactions(signedGroup).do();
+      const fm = resp?.txnGroups?.[0]?.failureMessage;
+      return { failureMessage: fm && fm.length > 0 ? fm : null };
+    },
+    async submit(signedGroup) {
+      const res = await algod.sendRawTransaction(signedGroup).do();
+      return res?.txid ?? "";
+    },
+    async waitForConfirmation(txid) {
+      const info = await algosdk3.waitForConfirmation(algod, txid, 10);
+      const r = info.confirmedRound;
+      return r != null && Number(r) > 0 ? Number(r) : null;
+    }
+  };
+  return {
+    family: "algorand",
+    network,
+    supports: (n) => n === network,
+    resolveToken(token) {
+      if (token === "native") {
+        return { asset: "native", decimals: ALGO_DECIMALS, symbol: ALGO_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 Algorand (known: ${known}). Pass { assetId, decimals } for a custom ASA, or use 'native'.`
+          );
+        }
+        return { asset: algorandAssetId(info.assetId), decimals: info.decimals, symbol: info.symbol };
+      }
+      rejectForeignToken(token, "algorand", network);
+      const t = token;
+      if (typeof t.assetId !== "number" || typeof t.decimals !== "number") {
+        throw new WrongFamilyError(
+          `chain ${network} is Algorand; a custom token must be { assetId, decimals }.`
+        );
+      }
+      return {
+        asset: algorandAssetId(t.assetId),
+        decimals: t.decimals,
+        ...t.symbol ? { symbol: t.symbol } : {}
+      };
+    },
+    describeAsset(asset) {
+      if (asset === "native") return { symbol: ALGO_SYMBOL, decimals: ALGO_DECIMALS };
+      for (const info of Object.values(preset.tokens)) {
+        if (algorandAssetId(info.assetId) === asset) {
+          return { symbol: info.symbol, decimals: info.decimals };
+        }
+      }
+      return null;
+    },
+    assertValidPayTo(payTo) {
+      if (payTo.startsWith("0x")) {
+        throw new WrongFamilyError(
+          `chain ${network} is Algorand, but payTo "${payTo}" looks like an EVM address.`
+        );
+      }
+      if (!algosdk3.isValidAddress(payTo)) {
+        throw new WrongFamilyError(
+          `chain ${network} is Algorand, but payTo "${payTo}" is not a valid Algorand address.`
+        );
+      }
+    },
+    bindWallet(wallet) {
+      return { _native: assertAlgorandWallet(wallet, network) };
+    },
+    async send(wallet, accept) {
+      const signer = resolveAlgorandWallet(wallet._native);
+      return payAlgorand({ client: payClient, sk: signer.sk, sender: signer.addr, accept });
+    },
+    async confirm(ref) {
+      try {
+        const info = await algosdk3.waitForConfirmation(algod, ref, 10);
+        return { height: String(info.confirmedRound ?? 0) };
+      } catch (err) {
+        throw new ConfirmationTimeoutError(`Algorand tx ${ref} did not confirm in time.`, {
+          cause: err
+        });
+      }
+    },
+    async estimateCost(accept) {
+      if (accept.scheme === "exact") {
+        return nativeCost({
+          symbol: ALGO_SYMBOL,
+          decimals: ALGO_DECIMALS,
+          fee: 0n,
+          basis: "estimated",
+          detail: "gasless \u2014 the fee payer (facilitator/relayer) pools the group fee; the buyer pays 0 ALGO"
+        });
+      }
+      return nativeCost({
+        symbol: ALGO_SYMBOL,
+        decimals: ALGO_DECIMALS,
+        fee: 1000n,
+        basis: "heuristic",
+        detail: "min fee 1000 \xB5Algos (1 transaction)"
+      });
+    },
+    async balanceOf(wallet, asset) {
+      let owner;
+      try {
+        owner = resolveAlgorandWallet(wallet._native).addr;
+      } catch {
+        return { token: null, native: null };
+      }
+      let info;
+      try {
+        info = await algod.accountInformation(owner).do();
+      } catch {
+        return { token: null, native: null };
+      }
+      const native = info.amount != null ? BigInt(info.amount) : null;
+      if (asset === "native") return { token: native, native };
+      const assetId = parseAlgorandAssetId(asset);
+      const holding = (info.assets ?? []).find((a) => Number(a.assetId) === assetId);
+      return { token: holding ? BigInt(holding.amount) : 0n, native };
+    },
+    async recipientReady(payTo, asset) {
+      if (asset === "native") return { ready: "n/a" };
+      const assetId = parseAlgorandAssetId(asset);
+      if (assetId == null) return { ready: "unknown" };
+      try {
+        const info = await algod.accountInformation(payTo).do();
+        const optedIn = (info.assets ?? []).some((a) => Number(a.assetId) === assetId);
+        return optedIn ? { ready: true } : { ready: false, reason: "NOT_OPTED_IN" };
+      } catch (e) {
+        if (/does not exist|no accounts found|404|account not found/i.test(String(e?.message ?? e))) {
+          return { ready: false, reason: "NOT_OPTED_IN" };
+        }
+        return { ready: "unknown" };
+      }
+    },
+    async verify(_ref, accept) {
+      return verifyAlgorand({ reader, accept });
+    },
+    // Standard x402 `exact` rail, BUYER side — build the canonical 2-txn group (buyer axfer at
+    // fee 0 + the fee payer's pooled-fee pay txn), sign ONLY the axfer (the buyer spends zero
+    // ALGO). Never submits. Throws UnsupportedSchemeError for native / a missing feePayer / a
+    // feePayer that equals the payer.
+    async payExact(wallet, accept) {
+      const signer = resolveAlgorandWallet(wallet._native);
+      const suggestedParams = await algod.getTransactionParams().do();
+      const { payload, payerFrom, nonce } = await payExactAlgorand({
+        suggestedParams,
+        sk: signer.sk,
+        sender: signer.addr,
+        accept
+      });
+      return { payload, accepted: accept, payerFrom, nonce };
+    },
+    // Standard x402 `exact` rail, SELLER side — verify the inbound group against the trusted
+    // accept, then co-sign the fee txn as the fee payer + submit the group (self-settle, no
+    // facilitator). The buyer stays gasless; the merchant's relayer pays the pooled group fee.
+    async settleExactSelf({ relayer, payload, accept }) {
+      if (!("paymentGroup" in payload)) {
+        return { ok: false, error: "signature_invalid", detail: "Algorand exact expects a { paymentGroup } payload." };
+      }
+      const signer = resolveAlgorandWallet(relayer._native);
+      return verifyAndSettleExactAlgorand({
+        client: settleClient,
+        feePayerSk: signer.sk,
+        feePayerAddr: signer.addr,
+        payload,
+        accept
+      });
+    },
+    // The gate's rail-advertisement SPI. The fee payer is EITHER a keyless facilitator's sponsor
+    // address (`feePayer` — facilitator mode, neither buyer nor merchant pays gas) OR the
+    // merchant's own bound `relayer` (self mode); native ALGO isn't exact-payable. `null` ⇒ no
+    // exact rail. The buyer fee-pools the group, so the merchant may even reuse `payTo` as the
+    // relayer (Algorand allows feePayer === payTo — the fee txn is separate, unlike Solana).
+    async resolveExactRail({ asset, relayer, feePayer }) {
+      if (asset === "native") return null;
+      let fp = feePayer;
+      if (!fp && relayer) {
+        try {
+          fp = resolveAlgorandWallet(relayer._native).addr;
+        } catch {
+          return null;
+        }
+      }
+      if (!fp || !algosdk3.isValidAddress(fp)) return null;
+      return { method: "algorand", extra: { feePayer: fp } };
+    }
+  };
+}
+function adaptTxn(raw) {
+  const t = raw;
+  if (!t || typeof t.id !== "string") return null;
+  const note = t.note && t.note.length ? decodeNote(t.note) : void 0;
+  const base = {
+    id: t.id,
+    txType: String(t.txType ?? ""),
+    ...note !== void 0 ? { note } : {},
+    ...t.sender != null ? { sender: String(t.sender) } : {},
+    ...typeof t.roundTime === "number" ? { roundTime: t.roundTime } : {}
+  };
+  if (t.paymentTransaction) {
+    const pt = t.paymentTransaction;
+    return {
+      ...base,
+      txType: "pay",
+      ...pt.receiver != null ? { receiver: String(pt.receiver) } : {},
+      ...pt.amount != null ? { amount: String(pt.amount) } : {}
+    };
+  }
+  if (t.assetTransferTransaction) {
+    const att = t.assetTransferTransaction;
+    return {
+      ...base,
+      txType: "axfer",
+      ...att.receiver != null ? { receiver: String(att.receiver) } : {},
+      ...att.amount != null ? { amount: String(att.amount) } : {},
+      ...att.assetId != null ? { assetId: Number(att.assetId) } : {}
+    };
+  }
+  return base;
+}
+function decodeNote(bytes) {
+  try {
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return void 0;
+  }
+}
+export {
+  algorandDriver
+};