@piprail/sdk 1.20.1 → 1.21.1

package/dist/solana-IBVUZS54.js

@@ -0,0 +1,724 @@
+import {
+  ConfirmationTimeoutError,
+  SettlementError,
+  UnknownTokenError,
+  UnsupportedSchemeError,
+  WrongFamilyError,
+  nativeCost,
+  rejectForeignToken,
+  toInsufficientFundsError
+} from "./chunk-ILPABTI2.js";
+
+// src/drivers/solana/index.ts
+import { Connection, PublicKey as PublicKey3 } from "@solana/web3.js";
+import {
+  getAccount,
+  getAssociatedTokenAddressSync as getAssociatedTokenAddressSync3,
+  TOKEN_2022_PROGRAM_ID as TOKEN_2022_PROGRAM_ID2,
+  TokenAccountNotFoundError
+} from "@solana/spl-token";
+
+// src/drivers/solana/chains.ts
+var SOL_DECIMALS = 9;
+var SOLANA_MAINNET = {
+  caip2: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  defaultRpc: "https://api.mainnet-beta.solana.com",
+  tokens: {
+    USDC: {
+      mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      decimals: 6,
+      symbol: "USDC"
+    },
+    USDT: {
+      mint: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+      decimals: 6,
+      symbol: "USDT"
+    }
+  }
+};
+
+// src/drivers/solana/pay.ts
+import {
+  PublicKey,
+  SystemProgram,
+  Transaction
+} from "@solana/web3.js";
+import {
+  createAssociatedTokenAccountIdempotentInstruction,
+  createTransferCheckedInstruction,
+  getAssociatedTokenAddressSync
+} from "@solana/spl-token";
+async function paySolana(params) {
+  const { connection, keypair, accept } = params;
+  const payTo = new PublicKey(accept.payTo);
+  const amount = BigInt(accept.amount);
+  const tx = new Transaction();
+  if (accept.asset === "native") {
+    tx.add(
+      SystemProgram.transfer({
+        fromPubkey: keypair.publicKey,
+        toPubkey: payTo,
+        lamports: amount
+      })
+    );
+  } else {
+    const mint = new PublicKey(accept.asset);
+    const source = getAssociatedTokenAddressSync(mint, keypair.publicKey);
+    const dest = getAssociatedTokenAddressSync(mint, payTo);
+    tx.add(
+      createAssociatedTokenAccountIdempotentInstruction(
+        keypair.publicKey,
+        // payer for any rent
+        dest,
+        payTo,
+        mint
+      )
+    );
+    tx.add(
+      createTransferCheckedInstruction(
+        source,
+        mint,
+        dest,
+        keypair.publicKey,
+        amount,
+        accept.extra.decimals
+      )
+    );
+  }
+  const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash();
+  tx.recentBlockhash = blockhash;
+  tx.lastValidBlockHeight = lastValidBlockHeight;
+  tx.feePayer = keypair.publicKey;
+  tx.sign(keypair);
+  const signature = await connection.sendRawTransaction(tx.serialize(), {
+    maxRetries: 5
+  });
+  await connection.confirmTransaction(
+    { signature, blockhash, lastValidBlockHeight },
+    "confirmed"
+  );
+  return signature;
+}
+
+// src/drivers/solana/verify.ts
+async function verifySolana(params) {
+  const { connection, signature, accept } = params;
+  const required = BigInt(accept.amount);
+  let tx;
+  try {
+    tx = await connection.getParsedTransaction(signature, {
+      commitment: "confirmed",
+      maxSupportedTransactionVersion: 0
+    });
+  } catch {
+    return notFound(signature);
+  }
+  if (!tx) return notFound(signature);
+  const meta = tx.meta;
+  if (!meta) {
+    return { ok: false, error: "no_meta", detail: `No metadata for ${signature}.` };
+  }
+  if (meta.err !== null) {
+    return {
+      ok: false,
+      error: "tx_reverted",
+      detail: `Transaction ${signature} failed on-chain.`
+    };
+  }
+  if (typeof tx.blockTime !== "number") {
+    return {
+      ok: false,
+      error: "payment_expired",
+      detail: `Cannot determine the age of ${signature} (no blockTime).`
+    };
+  }
+  const ageSeconds = Math.floor(Date.now() / 1e3) - tx.blockTime;
+  if (ageSeconds > accept.maxTimeoutSeconds) {
+    return {
+      ok: false,
+      error: "payment_expired",
+      detail: `Payment is ${ageSeconds}s old; max allowed is ${accept.maxTimeoutSeconds}s.`
+    };
+  }
+  const accountKeys = tx.transaction.message.accountKeys.map(
+    (k) => k.pubkey.toBase58()
+  );
+  const payer = accountKeys[0] ?? "";
+  if (accept.asset === "native") {
+    const idx = accountKeys.indexOf(accept.payTo);
+    if (idx < 0) {
+      return {
+        ok: false,
+        error: "wrong_recipient",
+        detail: `Native payment in ${signature} did not credit ${accept.payTo}.`
+      };
+    }
+    const delta = BigInt(meta.postBalances[idx] ?? 0) - BigInt(meta.preBalances[idx] ?? 0);
+    if (delta < required) {
+      return {
+        ok: false,
+        error: "amount_too_low",
+        detail: `Credited ${delta} lamports, required ${required}.`
+      };
+    }
+  } else {
+    const mint = accept.asset;
+    const pre = meta.preTokenBalances ?? [];
+    const post = meta.postTokenBalances ?? [];
+    let delta = 0n;
+    for (const p of post) {
+      if (p.mint !== mint || p.owner !== accept.payTo) continue;
+      const before = pre.find((x) => x.accountIndex === p.accountIndex);
+      delta += BigInt(p.uiTokenAmount.amount) - BigInt(before?.uiTokenAmount.amount ?? "0");
+    }
+    if (delta < required) {
+      return {
+        ok: false,
+        error: "transfer_not_found",
+        detail: `No SPL transfer of >= ${required} (mint ${mint}) to ${accept.payTo} in ${signature}.`
+      };
+    }
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "onchain-proof",
+      success: true,
+      network: accept.network,
+      transaction: signature,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer,
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function notFound(signature) {
+  return {
+    ok: false,
+    error: "tx_not_found",
+    detail: `Signature ${signature} not found or not yet confirmed.`
+  };
+}
+
+// src/drivers/solana/exact.ts
+import {
+  ComputeBudgetProgram,
+  PublicKey as PublicKey2,
+  TransactionInstruction,
+  TransactionMessage,
+  VersionedTransaction
+} from "@solana/web3.js";
+import {
+  createTransferCheckedInstruction as createTransferCheckedInstruction2,
+  decodeTransferCheckedInstruction,
+  getAssociatedTokenAddressSync as getAssociatedTokenAddressSync2,
+  TOKEN_2022_PROGRAM_ID,
+  TOKEN_PROGRAM_ID
+} from "@solana/spl-token";
+import bs58 from "bs58";
+var COMPUTE_UNIT_LIMIT = 2e4;
+var COMPUTE_UNIT_PRICE_MICROLAMPORTS = 1;
+function tokenProgramFor(accept) {
+  return accept.extra.tokenProgram === "token-2022" ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
+}
+function isEmptySig(sig) {
+  return !sig || sig.every((b) => b === 0);
+}
+async function payExactSolana(input) {
+  const { connection, keypair, accept } = input;
+  if (accept.asset === "native") {
+    throw new UnsupportedSchemeError(
+      "SVM exact is SPL-token only (TransferChecked); native SOL is not exact-payable. Pay via onchain-proof."
+    );
+  }
+  if (!accept.extra.feePayer) {
+    throw new UnsupportedSchemeError("SVM exact rail must advertise extra.feePayer (the merchant sponsor key).");
+  }
+  if (accept.extra.decimals === void 0) {
+    throw new UnsupportedSchemeError("SVM exact rail must advertise extra.decimals for the TransferChecked.");
+  }
+  let feePayer;
+  let mint;
+  let payTo;
+  try {
+    feePayer = new PublicKey2(accept.extra.feePayer);
+    mint = new PublicKey2(accept.asset);
+    payTo = new PublicKey2(accept.payTo);
+  } catch (err) {
+    throw new UnsupportedSchemeError(
+      `SVM exact: bad feePayer/asset/payTo (${err instanceof Error ? err.message : String(err)}).`
+    );
+  }
+  if (feePayer.equals(payTo)) {
+    throw new UnsupportedSchemeError(
+      "SVM exact: the fee payer must differ from payTo \u2014 payTo appears in the transfer instruction, which the fee payer must not (a scheme MUST-rule). Use a separate relayer key for the gate."
+    );
+  }
+  const program = tokenProgramFor(accept);
+  const source = getAssociatedTokenAddressSync2(mint, keypair.publicKey, true, program);
+  const dest = getAssociatedTokenAddressSync2(mint, payTo, true, program);
+  let destInfo = "unknown";
+  try {
+    destInfo = await input.connection.getAccountInfo(dest);
+  } catch {
+    destInfo = "unknown";
+  }
+  if (destInfo === null) {
+    throw new UnsupportedSchemeError(
+      `SVM exact: the recipient's token account for ${mint.toBase58()} doesn't exist yet \u2014 the exact rail can't create it. Pay via onchain-proof (which creates it), or have ${payTo.toBase58()} create its associated token account first.`
+    );
+  }
+  const instructions = [
+    ComputeBudgetProgram.setComputeUnitLimit({ units: COMPUTE_UNIT_LIMIT }),
+    ComputeBudgetProgram.setComputeUnitPrice({ microLamports: COMPUTE_UNIT_PRICE_MICROLAMPORTS }),
+    createTransferCheckedInstruction2(
+      source,
+      mint,
+      dest,
+      keypair.publicKey,
+      BigInt(accept.amount),
+      accept.extra.decimals,
+      [],
+      program
+    )
+  ];
+  const { blockhash } = await connection.getLatestBlockhash();
+  const message = new TransactionMessage({
+    payerKey: feePayer,
+    recentBlockhash: blockhash,
+    instructions
+  }).compileToV0Message();
+  const tx = new VersionedTransaction(message);
+  tx.sign([keypair]);
+  const buyerIndex = message.staticAccountKeys.findIndex((k) => k.equals(keypair.publicKey));
+  if (buyerIndex < 1 || buyerIndex >= message.header.numRequiredSignatures) {
+    throw new UnsupportedSchemeError("SVM exact: could not locate the buyer signer slot.");
+  }
+  const buyerSig = tx.signatures[buyerIndex];
+  if (!buyerSig || isEmptySig(buyerSig)) {
+    throw new UnsupportedSchemeError("SVM exact: the wallet did not produce a buyer signature.");
+  }
+  const transaction = Buffer.from(tx.serialize()).toString("base64");
+  return {
+    payload: { transaction },
+    payerFrom: keypair.publicKey.toBase58(),
+    nonce: bs58.encode(buyerSig)
+  };
+}
+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 };
+}
+async function verifyAndSettleExactSolana(input) {
+  const { connection, feePayerKeypair, payload, accept } = input;
+  let payTo;
+  let mint;
+  let railFeePayer;
+  try {
+    payTo = new PublicKey2(accept.payTo);
+    mint = new PublicKey2(accept.asset);
+    if (!accept.extra.feePayer) throw new Error("rail is missing extra.feePayer");
+    railFeePayer = new PublicKey2(accept.extra.feePayer);
+  } catch (err) {
+    throw new SettlementError(`SVM exact: rail has a bad payTo/asset/feePayer (${err instanceof Error ? err.message : String(err)}).`);
+  }
+  if (!railFeePayer.equals(feePayerKeypair.publicKey)) {
+    throw new SettlementError(
+      "SVM exact: the gate relayer key does not match the rail extra.feePayer \u2014 misconfigured rail."
+    );
+  }
+  if (feePayerKeypair.publicKey.equals(payTo)) {
+    throw new SettlementError("SVM exact: the fee payer must differ from payTo \u2014 misconfigured rail.");
+  }
+  const program = tokenProgramFor(accept);
+  let tx;
+  try {
+    tx = VersionedTransaction.deserialize(Buffer.from(payload.transaction, "base64"));
+  } catch (err) {
+    return fail("signature_invalid", `Unparseable SVM transaction: ${shorten(err instanceof Error ? err.message : String(err))}.`);
+  }
+  const message = tx.message;
+  if (message.version !== 0) {
+    return fail("signature_invalid", "SVM exact requires a versioned (v0) transaction.");
+  }
+  const altAccounts = [];
+  for (const lookup of message.addressTableLookups) {
+    let value;
+    try {
+      ;
+      ({ value } = await connection.getAddressLookupTable(lookup.accountKey));
+    } catch {
+      return fail("tx_not_found", `Could not read lookup table ${lookup.accountKey.toBase58()} (transient RPC) \u2014 retry.`);
+    }
+    if (!value) {
+      return fail("signature_invalid", `Lookup table ${lookup.accountKey.toBase58()} is not resolvable \u2014 account visibility cannot be guaranteed.`);
+    }
+    altAccounts.push(value);
+  }
+  const keys = message.getAccountKeys({ addressLookupTableAccounts: altAccounts });
+  const feePayerKey = keys.get(0);
+  if (!feePayerKey || !feePayerKey.equals(feePayerKeypair.publicKey)) {
+    return fail("signature_invalid", "Transaction fee payer is not the merchant sponsor key.");
+  }
+  if (!isEmptySig(tx.signatures[0])) {
+    return fail("signature_invalid", "The fee-payer signature slot must be empty \u2014 the buyer must not sign it.");
+  }
+  for (const ix of message.compiledInstructions) {
+    const ixProgram = keys.get(ix.programIdIndex);
+    if (ixProgram && ixProgram.equals(feePayerKey)) {
+      return fail("signature_invalid", "The fee payer is invoked as a program.");
+    }
+    for (const i of ix.accountKeyIndexes) {
+      if (keys.get(i)?.equals(feePayerKey)) {
+        return fail("signature_invalid", "The fee payer appears in an instruction account list (would risk a fund drain).");
+      }
+    }
+  }
+  const isSignedSigner = (pubkey) => {
+    const idx = message.staticAccountKeys.findIndex((k) => k.equals(pubkey));
+    return idx >= 1 && idx < message.header.numRequiredSignatures && !isEmptySig(tx.signatures[idx]);
+  };
+  const expectedDest = getAssociatedTokenAddressSync2(mint, payTo, true, program);
+  const requiredAmount = BigInt(accept.amount);
+  let paidToPayTo = 0n;
+  let buyerOwner = null;
+  let sawTransferToPayTo = false;
+  for (const ix of message.compiledInstructions) {
+    const programId = keys.get(ix.programIdIndex);
+    if (!programId || !programId.equals(program)) continue;
+    let decoded;
+    try {
+      decoded = decodeTransferCheckedInstruction(
+        new TransactionInstruction({
+          programId,
+          keys: ix.accountKeyIndexes.map((i) => ({
+            pubkey: keys.get(i),
+            isSigner: message.isAccountSigner(i),
+            isWritable: message.isAccountWritable(i)
+          })),
+          data: Buffer.from(ix.data)
+        }),
+        program
+      );
+    } catch {
+      continue;
+    }
+    if (!decoded.keys.mint.pubkey.equals(mint)) continue;
+    if (!decoded.keys.destination.pubkey.equals(expectedDest)) {
+      return fail("wrong_recipient", `A transfer pays ${decoded.keys.destination.pubkey.toBase58()}, not payTo's ATA ${expectedDest.toBase58()}.`);
+    }
+    if (decoded.data.decimals !== accept.extra.decimals) {
+      return fail("transfer_not_found", `Transfer decimals ${decoded.data.decimals} \u2260 rail decimals ${accept.extra.decimals}.`);
+    }
+    sawTransferToPayTo = true;
+    if (!isSignedSigner(decoded.keys.owner.pubkey)) continue;
+    paidToPayTo += BigInt(decoded.data.amount);
+    buyerOwner = decoded.keys.owner.pubkey;
+  }
+  if (!buyerOwner) {
+    return fail(
+      sawTransferToPayTo ? "signature_invalid" : "transfer_not_found",
+      sawTransferToPayTo ? "A TransferChecked to payTo's ATA is not authorized by a transaction signer." : `No TransferChecked of mint ${mint.toBase58()} (program ${program.toBase58()}) found.`
+    );
+  }
+  if (paidToPayTo < requiredAmount) {
+    return fail("amount_too_low", `Signed transfers pay ${paidToPayTo} to payTo, required ${requiredAmount}.`);
+  }
+  const buyerIndex = message.staticAccountKeys.findIndex((k) => k.equals(buyerOwner));
+  if (buyerIndex < 1 || buyerIndex >= message.header.numRequiredSignatures) {
+    return fail("signature_invalid", "The transfer authority is not a transaction signer.");
+  }
+  if (isEmptySig(tx.signatures[buyerIndex])) {
+    return fail("signature_invalid", "The buyer signature slot is empty.");
+  }
+  tx.sign([feePayerKeypair]);
+  try {
+    const sim = await connection.simulateTransaction(tx, { sigVerify: true, replaceRecentBlockhash: false, commitment: "confirmed" });
+    if (sim.value.err) {
+      const errStr = typeof sim.value.err === "string" ? sim.value.err : JSON.stringify(sim.value.err);
+      if (/blockhash|block height|expired/i.test(errStr)) return fail("payment_expired", `Transaction blockhash is no longer valid: ${shorten(errStr)}.`);
+      if (/signature/i.test(errStr)) return fail("signature_invalid", `Signature verification failed: ${shorten(errStr)}.`);
+      return fail("tx_reverted", `Transaction would fail on-chain: ${shorten(errStr)}.`);
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/signature verification|invalid signature/i.test(msg)) return fail("signature_invalid", `Signature verification failed: ${shorten(msg)}.`);
+    if (/blockhash|block height|expired/i.test(msg)) return fail("payment_expired", `Transaction blockhash is no longer valid: ${shorten(msg)}.`);
+    return fail("tx_not_found", `Could not simulate the transaction (transient RPC) \u2014 retry: ${shorten(msg)}.`);
+  }
+  let txid;
+  try {
+    txid = await connection.sendRawTransaction(tx.serialize(), { maxRetries: 5 });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/blockhash|block height|expired/i.test(msg)) return fail("payment_expired", `Settle broadcast rejected \u2014 blockhash expired: ${shorten(msg)}.`);
+    throw new SettlementError(
+      `SVM exact settle: the merchant fee payer failed to broadcast (${shorten(msg)}). The buyer's signed transaction is still valid \u2014 fund/fix the fee payer and the buyer can re-present it.`,
+      { cause: err }
+    );
+  }
+  const confirmed = await pollConfirmed(connection, txid);
+  if (confirmed === "reverted") {
+    return fail("tx_reverted", `Settle tx ${txid} reverted on-chain (a post-simulate race).`);
+  }
+  if (confirmed === "timeout") {
+    throw new SettlementError(
+      `SVM exact settle: broadcast ${txid} but it did not confirm in time. It likely landed \u2014 re-verify by signature before re-presenting; do NOT re-pay.`
+    );
+  }
+  return {
+    ok: true,
+    receipt: {
+      scheme: "exact",
+      success: true,
+      network: accept.network,
+      transaction: txid,
+      asset: accept.asset,
+      amount: accept.amount,
+      payer: buyerOwner.toBase58(),
+      payTo: accept.payTo,
+      verifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+async function pollConfirmed(connection, signature) {
+  const deadline = Date.now() + 3e4;
+  for (; ; ) {
+    let info;
+    try {
+      const { value } = await connection.getSignatureStatuses([signature], { searchTransactionHistory: true });
+      info = value[0];
+    } catch {
+      info = null;
+    }
+    if (info) {
+      if (info.err) return "reverted";
+      if (info.confirmationStatus === "confirmed" || info.confirmationStatus === "finalized") return "ok";
+    }
+    if (Date.now() >= deadline) return "timeout";
+    await new Promise((r) => setTimeout(r, 1e3));
+  }
+}
+
+// src/drivers/solana/wallet.ts
+import { Keypair as Keypair3 } from "@solana/web3.js";
+import bs582 from "bs58";
+function toKeypair(wallet, network) {
+  if (typeof wallet !== "object" || wallet === null) {
+    throw new WrongFamilyError(
+      `chain ${network} is Solana; wallet must be { secretKey } or { signer }.`
+    );
+  }
+  if ("privateKey" in wallet || "walletClient" in wallet) {
+    throw new WrongFamilyError(
+      `chain ${network} is Solana; an EVM wallet can't be used \u2014 pass { secretKey } or { signer }.`
+    );
+  }
+  if ("signer" in wallet) {
+    return wallet.signer;
+  }
+  if ("secretKey" in wallet) {
+    const sk = wallet.secretKey;
+    const bytes = typeof sk === "string" ? bs582.decode(sk) : sk;
+    return Keypair3.fromSecretKey(bytes);
+  }
+  throw new WrongFamilyError(
+    `chain ${network} is Solana; wallet must be { secretKey } or { signer }.`
+  );
+}
+
+// src/drivers/solana/index.ts
+var solanaDriver = {
+  family: "solana",
+  resolve(opts) {
+    if (opts.chain !== "solana") return null;
+    const rpcUrl = opts.rpcUrl ?? SOLANA_MAINNET.defaultRpc;
+    return makeSolanaNetwork(SOLANA_MAINNET, rpcUrl);
+  }
+};
+function makeSolanaNetwork(preset, rpcUrl) {
+  const connection = new Connection(rpcUrl, "confirmed");
+  const network = preset.caip2;
+  return {
+    family: "solana",
+    network,
+    supports: (n) => n === network,
+    resolveToken(token) {
+      if (token === "native") {
+        return { asset: "native", decimals: SOL_DECIMALS, symbol: "SOL" };
+      }
+      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 Solana (known: ${known}). Pass { mint, decimals } instead, or use 'native'.`
+          );
+        }
+        return { asset: info.mint, decimals: info.decimals, symbol: info.symbol };
+      }
+      rejectForeignToken(token, "solana", network);
+      if (!("mint" in token)) {
+        throw new WrongFamilyError(
+          `chain ${network} is Solana; a custom token must be { mint, decimals }.`
+        );
+      }
+      return {
+        asset: token.mint,
+        decimals: token.decimals,
+        ...token.symbol ? { symbol: token.symbol } : {}
+      };
+    },
+    describeAsset(asset) {
+      if (asset === "native") return { symbol: "SOL", decimals: SOL_DECIMALS };
+      for (const info of Object.values(preset.tokens)) {
+        if (info.mint === asset) return { symbol: info.symbol, decimals: info.decimals };
+      }
+      return null;
+    },
+    assertValidPayTo(payTo) {
+      if (payTo.startsWith("0x")) {
+        throw new WrongFamilyError(
+          `chain ${network} is Solana, but payTo "${payTo}" looks like an EVM address.`
+        );
+      }
+      try {
+        new PublicKey3(payTo);
+      } catch {
+        throw new WrongFamilyError(
+          `chain ${network} is Solana, but payTo "${payTo}" is not a base58 address.`
+        );
+      }
+    },
+    bindWallet(wallet) {
+      return { _native: toKeypair(wallet, network) };
+    },
+    async send(wallet, accept) {
+      try {
+        return await paySolana({ connection, keypair: wallet._native, accept });
+      } catch (err) {
+        throw toInsufficientFundsError(err) ?? err;
+      }
+    },
+    async confirm(ref) {
+      let info;
+      try {
+        const { value } = await connection.getSignatureStatuses([ref], {
+          searchTransactionHistory: true
+        });
+        info = value[0];
+      } catch (err) {
+        throw new ConfirmationTimeoutError(
+          `Solana payment ${ref} could not be confirmed (RPC read failed).`,
+          { cause: err }
+        );
+      }
+      if (!info || info.err || info.confirmationStatus !== "confirmed" && info.confirmationStatus !== "finalized") {
+        throw new ConfirmationTimeoutError(`Solana payment ${ref} did not confirm in time.`);
+      }
+      return { height: String(info.slot) };
+    },
+    async estimateCost(accept) {
+      if (accept.scheme === "exact") {
+        return nativeCost({
+          symbol: "SOL",
+          decimals: SOL_DECIMALS,
+          fee: 0n,
+          basis: "estimated",
+          detail: "gasless \u2014 the fee payer (facilitator/relayer) broadcasts and pays the SOL fee"
+        });
+      }
+      const base = 5000n;
+      if (accept.asset === "native") {
+        return nativeCost({
+          symbol: "SOL",
+          decimals: SOL_DECIMALS,
+          fee: base,
+          basis: "heuristic",
+          detail: "1 signature (5000 lamports)"
+        });
+      }
+      const ataRent = 2039280n;
+      return nativeCost({
+        symbol: "SOL",
+        decimals: SOL_DECIMALS,
+        fee: base + ataRent,
+        basis: "heuristic",
+        detail: "1 signature + recipient token-account rent (~0.00204 SOL, if not already created)"
+      });
+    },
+    async balanceOf(wallet, asset) {
+      const owner = wallet._native.publicKey;
+      const native = await connection.getBalance(owner).then((n) => BigInt(n)).catch(() => null);
+      if (asset === "native") return { token: native, native };
+      let token;
+      try {
+        const ata = getAssociatedTokenAddressSync3(new PublicKey3(asset), owner);
+        token = (await getAccount(connection, ata, "confirmed")).amount;
+      } catch (e) {
+        token = e instanceof TokenAccountNotFoundError ? 0n : null;
+      }
+      return { token, native };
+    },
+    // No receive prerequisite — the payer's tx idempotently creates the recipient's ATA (pay.ts).
+    async recipientReady() {
+      return { ready: "n/a" };
+    },
+    async verify(ref, accept) {
+      return verifySolana({ connection, signature: ref, accept });
+    },
+    // Standard x402 `exact` rail, BUYER side — partial-sign an SPL TransferChecked with the
+    // merchant as fee payer (the buyer spends zero SOL). Never broadcasts. Throws
+    // UnsupportedSchemeError for native / a missing feePayer / feePayer === payTo.
+    async payExact(wallet, accept) {
+      const { payload, payerFrom, nonce } = await payExactSolana({
+        connection,
+        keypair: wallet._native,
+        accept
+      });
+      return { payload, accepted: accept, payerFrom, nonce };
+    },
+    // Standard x402 `exact` rail, SELLER side — verify the partial-signed tx against the
+    // trusted accept, then co-sign as the fee payer + broadcast (self-settle, no facilitator).
+    async settleExactSelf({ relayer, payload, accept }) {
+      if (!("transaction" in payload)) {
+        return { ok: false, error: "signature_invalid", detail: "SVM exact expects a { transaction } payload." };
+      }
+      return verifyAndSettleExactSolana({
+        connection,
+        feePayerKeypair: relayer._native,
+        payload,
+        accept
+      });
+    },
+    // The gate's rail-advertisement SPI. The SVM fee payer is EITHER a facilitator's sponsor
+    // pubkey (`feePayer` — facilitator mode, neither buyer nor merchant pays gas) OR the
+    // merchant's own bound `relayer` (self mode); native isn't exact-payable. Reads the mint's
+    // owner once to flag token-2022 (so both ends derive the same ATA). `null` ⇒ no exact rail.
+    async resolveExactRail({ asset, relayer, feePayer }) {
+      if (asset === "native") return null;
+      const fp = feePayer ?? (relayer ? relayer._native.publicKey.toBase58() : void 0);
+      if (!fp) return null;
+      try {
+        new PublicKey3(fp);
+      } catch {
+        return null;
+      }
+      let tokenProgram = "spl-token";
+      try {
+        const info = await connection.getAccountInfo(new PublicKey3(asset));
+        if (info?.owner.equals(TOKEN_2022_PROGRAM_ID2)) tokenProgram = "token-2022";
+      } catch {
+      }
+      return { method: "svm", extra: { feePayer: fp, tokenProgram } };
+    }
+  };
+}
+export {
+  solanaDriver
+};