@agenticstechnologies/verify 0.0.0-stage → 1.0.1

package/src/solana.mjs

@@ -0,0 +1,235 @@
+// Public Solana memo read. Devnet and testnet only. No key, no signature,
+// no mainnet RPC. A timeout or an unreachable RPC is a warning, not a hang
+// and not a failed bundle.
+
+export const MEMO_PROGRAM = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+
+export const PUBLIC_RPC = {
+  devnet: "https://api.devnet.solana.com",
+  testnet: "https://api.testnet.solana.com",
+};
+
+/** Free public Base Sepolia RPC. Testnet only. Never a mainnet endpoint. */
+export const PUBLIC_EVM_RPC = {
+  baseSepolia: "https://sepolia.base.org",
+};
+
+export const DEFAULT_RPC_TIMEOUT_MS = 8000;
+
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+/** @param {string} input */
+export function base58Decode(input) {
+  if (typeof input !== "string" || input.length === 0) return null;
+  const bytes = [];
+  for (const char of input) {
+    let carry = B58.indexOf(char);
+    if (carry < 0) return null;
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j] * 58;
+      bytes[j] = carry & 0xff;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+  for (const char of input) {
+    if (char !== "1") break;
+    bytes.push(0);
+  }
+  return Uint8Array.from(bytes.reverse());
+}
+
+/**
+ * @param {string | null | undefined} hint  anchor.chain or anchor.cluster
+ * @param {string | null | undefined} explorer
+ * @returns {"devnet" | "testnet" | "mainnet" | null}
+ */
+export function classifyCluster(hint, explorer) {
+  const blob = `${hint || ""} ${explorer || ""}`.toLowerCase();
+  if (!blob.trim()) return null;
+  if (blob.includes("devnet")) return "devnet";
+  if (blob.includes("testnet")) return "testnet";
+  if (blob.includes("mainnet") || /(^|[^a-z])solana([^a-z]|$)/.test(blob)) return "mainnet";
+  return null;
+}
+
+function memoBytes(data) {
+  if (typeof data === "string") return base58Decode(data);
+  if (data instanceof Uint8Array) return data;
+  if (Array.isArray(data) && data.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)) {
+    return Uint8Array.from(data);
+  }
+  return null;
+}
+
+/** Signers on the transaction message. jsonParsed keys carry `signer`. */
+export function signersFromTransaction(tx) {
+  const msg = tx && tx.transaction && tx.transaction.message;
+  if (!msg) return [];
+  const keys = msg.accountKeys || msg.staticAccountKeys || [];
+  const flagged = [];
+  for (const key of keys) {
+    if (key && typeof key === "object" && key.signer === true && key.pubkey) {
+      flagged.push(String(key.pubkey));
+    }
+  }
+  if (flagged.length) return flagged;
+  const count = msg.header && Number(msg.header.numRequiredSignatures);
+  if (!Number.isInteger(count) || count <= 0) return [];
+  const signers = [];
+  for (let i = 0; i < count && i < keys.length; i++) {
+    const key = keys[i];
+    const pubkey = typeof key === "string" ? key : key && key.pubkey;
+    if (pubkey) signers.push(String(pubkey));
+  }
+  return signers;
+}
+
+/**
+ * A memo counts only when the transaction succeeded and its one signer is
+ * `authority`. A non-null meta.err is `anchor_tx_failed`. Any other signer
+ * is `anchor_wrong_signer`.
+ * @param {unknown} tx
+ * @param {string} authority
+ * @returns {{ ok: true, memos: string[] } | { ok: false, reason: "anchor_tx_failed" | "anchor_wrong_signer" }}
+ */
+export function anchorMemoVerdict(tx, authority) {
+  const err = tx && tx.meta ? tx.meta.err : undefined;
+  if (err != null) return { ok: false, reason: "anchor_tx_failed" };
+  const expected = String(authority || "").trim();
+  const signers = signersFromTransaction(tx);
+  if (!expected || signers.length !== 1 || signers[0] !== expected) {
+    return { ok: false, reason: "anchor_wrong_signer" };
+  }
+  return { ok: true, memos: memosFromTransaction(tx) };
+}
+
+/** Memo strings on the transaction message. Inner instructions are ignored. */
+export function memosFromTransaction(tx) {
+  const msg = tx && tx.transaction && tx.transaction.message;
+  if (!msg) return [];
+  const instructions = msg.instructions || msg.compiledInstructions || [];
+  const keys = msg.accountKeys || msg.staticAccountKeys || [];
+  const memos = [];
+  for (const ix of instructions) {
+    if (!ix || typeof ix !== "object") continue;
+    const parsedMemo = typeof ix.parsed === "string"
+      ? ix.parsed
+      : (ix.parsed && typeof ix.parsed.memo === "string" ? ix.parsed.memo : null);
+    if (ix.programId === MEMO_PROGRAM || ix.program === "spl-memo") {
+      if (parsedMemo != null) memos.push(parsedMemo);
+      continue;
+    }
+    if (ix.programIdIndex == null) continue;
+    const key = keys[ix.programIdIndex];
+    const pubkey = typeof key === "string" ? key : key && key.pubkey;
+    if (pubkey !== MEMO_PROGRAM) continue;
+    if (parsedMemo != null) {
+      memos.push(parsedMemo);
+      continue;
+    }
+    const bytes = memoBytes(ix.data);
+    if (!bytes) continue;
+    memos.push(new TextDecoder().decode(bytes));
+  }
+  return memos;
+}
+
+function unreachableKind(err) {
+  if (!err) return "unreachable";
+  if (err.code === "timeout" || err.name === "AbortError" || err.name === "TimeoutError") return "timeout";
+  const msg = String(err.message || err);
+  if (/abort|timeout|timed out/i.test(msg)) return "timeout";
+  return "unreachable";
+}
+
+/**
+ * @param {{ txid: string, cluster: "devnet" | "testnet", expected: string, timeoutMs?: number, fetchImpl?: typeof fetch }} opts
+ * @returns {Promise<{ ok: boolean, warn: boolean, reason: string | null }>}
+ */
+export async function checkSolanaMemo(opts) {
+  const rpc = PUBLIC_RPC[opts.cluster];
+  if (!rpc) {
+    return { ok: false, warn: true, reason: `cluster ${opts.cluster} is not queried` };
+  }
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const ctrl = new AbortController();
+  let timer;
+  const timedOut = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      ctrl.abort();
+      const err = new Error("solana rpc timed out");
+      err.code = "timeout";
+      reject(err);
+    }, timeoutMs);
+  });
+  let pending;
+  try {
+    pending = Promise.resolve().then(() => fetchImpl(rpc, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "getTransaction",
+        params: [opts.txid, {
+          encoding: "jsonParsed",
+          maxSupportedTransactionVersion: 0,
+          commitment: "confirmed",
+        }],
+      }),
+      signal: ctrl.signal,
+    })).then((res) => res, (err) => {
+      if (err && (err.name === "AbortError" || err.name === "TimeoutError")) {
+        const wrapped = new Error("solana rpc timed out");
+        wrapped.code = "timeout";
+        throw wrapped;
+      }
+      throw err;
+    });
+    pending.catch(() => {});
+    const res = await Promise.race([pending, timedOut]);
+    if (!res || !res.ok) {
+      const status = res && res.status ? res.status : "no response";
+      return { ok: false, warn: true, reason: `solana rpc unreachable (http ${status})` };
+    }
+    const body = await res.json();
+    if (body && body.error) {
+      const msg = body.error.message || "rpc error";
+      return { ok: false, warn: true, reason: `solana rpc unreachable (${msg})` };
+    }
+    if (!body || body.result == null) {
+      return { ok: false, warn: false, reason: `transaction not found on ${opts.cluster}` };
+    }
+    if (opts.authority) {
+      const verdict = anchorMemoVerdict(body.result, opts.authority);
+      if (!verdict.ok) return { ok: false, warn: false, reason: verdict.reason };
+      if (verdict.memos.includes(opts.expected)) return { ok: true, warn: false, reason: null };
+      return {
+        ok: false,
+        warn: false,
+        reason: `solana memo does not equal ${opts.expected}`,
+      };
+    }
+    if (body.result && body.result.meta && body.result.meta.err != null) {
+      return { ok: false, warn: false, reason: "anchor_tx_failed" };
+    }
+    const memos = memosFromTransaction(body.result);
+    if (memos.includes(opts.expected)) return { ok: true, warn: false, reason: null };
+    return {
+      ok: false,
+      warn: false,
+      reason: `solana memo does not equal ${opts.expected}`,
+    };
+  } catch (err) {
+    const kind = unreachableKind(err);
+    const why = kind === "timeout" ? "solana rpc timed out" : "solana rpc unreachable";
+    return { ok: false, warn: true, reason: why };
+  } finally {
+    clearTimeout(timer);
+  }
+}