@agenticstechnologies/verify 0.0.0-stage → 1.0.0

package/src/record.mjs

@@ -0,0 +1,440 @@
+// Offline check for a signed agent record (GET /api/record/:handle/export).
+//
+// The 0–100 formula adapts lib/bureau/scoring.ts and matches lib/record/score.ts.
+// Good = paid on time, an approval, or a recorded outcome.
+// Adverse = claim paid, or a denial. A filed claim that was not paid is in
+// the total only. Windows are 7-day buckets of the events themselves, newest
+// first, weighted 1, 1/2, 1/4, … Stability is 1/(1+variance) of the per-window
+// good rate, and it applies only when two or more windows exist.
+//
+//   base = reliability * (1 - incident rate)
+//   score = round(100 * base)                         when one window
+//   score = round(100 * base * (0.5 + 0.5 * stability)) when two or more
+//
+// score_version 2. A self-reported event weighs SELF_REPORTED_WEIGHT. An agent
+// with only self-reported scoring events cannot score above SELF_REPORTED_CAP.
+// Missing provenance weighs 1, so a version 1 set of settlements and claims
+// still produces the same number. Exports that omit score_version are read
+// with agentRecordV1. Written form: docs/record/score.md.
+//
+// No scoring event → score is null, label "New, no record yet".
+// The signature is EdDSA with the Bond key published at /.well-known/jwks.json.
+// This file does not fetch that URL and does not trust a key embedded in the file.
+
+import { canonicalize } from "./evidence.mjs";
+
+export const NEW_RECORD_LABEL = "New, no record yet";
+export const SCORE_VERSION = 2;
+export const SELF_REPORTED_WEIGHT = 0.25;
+export const SELF_REPORTED_CAP = 40;
+export const RECORD_TYP = "agentics.record.v1";
+export const RECORD_ISS = "https://agentics.you";
+export const RECORD_JWT_TYP = "agentics-record+jwt";
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HEX64 = /^[0-9a-f]{64}$/;
+const HANDLE = /^[a-z0-9][a-z0-9-]{0,29}$/;
+const V1_KINDS = new Set(["paid_on_time", "claim_filed", "claim_paid"]);
+const KINDS = new Set([
+  "paid_on_time",
+  "claim_filed",
+  "claim_paid",
+  "denial",
+  "approval",
+  "outcome",
+  "outcome_adverse",
+]);
+const PROVENANCE = new Set(["verified_by_agentics", "self_reported", "imported"]);
+
+function clamp01(x) {
+  if (!Number.isFinite(x)) return 0;
+  if (x < 0) return 0;
+  if (x > 1) return 1;
+  return x;
+}
+
+function recencyWeight(windowIndex) {
+  return Math.pow(0.5, Math.max(0, windowIndex));
+}
+
+function iso(v) {
+  if (v instanceof Date) return Number.isFinite(v.getTime()) ? v.toISOString() : null;
+  if (typeof v === "string" && v.trim()) {
+    const t = Date.parse(v);
+    return Number.isFinite(t) ? new Date(t).toISOString() : null;
+  }
+  return null;
+}
+
+export function publicSeller(value) {
+  if (value == null) return null;
+  const s = String(value).trim().toLowerCase();
+  if (!s || s.includes("@") || /\s/.test(s) || s.length > 253) return null;
+  return s;
+}
+
+export function normalizeEvents(events) {
+  const seen = new Set();
+  const out = [];
+  for (const raw of events ?? []) {
+    if (!raw || typeof raw !== "object") continue;
+    const kind = String(raw.kind ?? "");
+    if (!KINDS.has(kind)) continue;
+    const at = iso(raw.at);
+    if (!at) continue;
+    const hash = raw.receipt_hash == null ? "" : String(raw.receipt_hash).trim().toLowerCase();
+    if (hash && !HEX64.test(hash)) continue;
+    if (hash) {
+      const key = `${kind}:${hash}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+    }
+    const seller = publicSeller(raw.seller);
+    const event = { kind, at };
+    if (seller) event.seller = seller;
+    if (hash) event.receipt_hash = hash;
+    const provenance = provenanceOf(raw.provenance);
+    if (provenance) event.provenance = provenance;
+    out.push(event);
+  }
+  return out;
+}
+
+function provenanceOf(value) {
+  return typeof value === "string" && PROVENANCE.has(value) ? value : undefined;
+}
+
+function eventWeight(event) {
+  return event.provenance === "self_reported" ? SELF_REPORTED_WEIGHT : 1;
+}
+
+export function recordWindows(events) {
+  const buckets = new Map();
+  for (const event of events) {
+    const t = Date.parse(event.at);
+    if (!Number.isFinite(t)) continue;
+    const key = Math.floor(t / WEEK_MS);
+    const bucket = buckets.get(key) ?? { total: 0, good: 0, adverse: 0 };
+    const weight = eventWeight(event);
+    bucket.total += weight;
+    if (event.kind === "paid_on_time" || event.kind === "approval" || event.kind === "outcome") bucket.good += weight;
+    if (event.kind === "claim_paid" || event.kind === "denial" || event.kind === "outcome_adverse") bucket.adverse += weight;
+    buckets.set(key, bucket);
+  }
+  return [...buckets.keys()]
+    .sort((a, b) => b - a)
+    .map((key, index) => {
+      const bucket = buckets.get(key);
+      return { window_index: index, total: bucket.total, good: bucket.good, adverse: bucket.adverse };
+    });
+}
+
+function recordReliability(windows) {
+  let num = 0;
+  let den = 0;
+  for (const w of windows) {
+    const weight = recencyWeight(w.window_index);
+    const total = Math.max(0, Number(w.total) || 0);
+    num += weight * Math.max(0, Number(w.good) || 0);
+    den += weight * total;
+  }
+  if (den <= 0) return null;
+  return clamp01(num / den);
+}
+
+function recordIncidentRate(windows) {
+  let num = 0;
+  let den = 0;
+  for (const w of windows) {
+    const weight = recencyWeight(w.window_index);
+    const total = Math.max(0, Number(w.total) || 0);
+    num += weight * Math.max(0, Number(w.adverse) || 0);
+    den += weight * total;
+  }
+  if (den <= 0) return null;
+  return clamp01(num / den);
+}
+
+function recordStability(windows) {
+  const rates = [];
+  for (const w of windows) {
+    const total = Math.max(0, Number(w.total) || 0);
+    if (total <= 0) continue;
+    rates.push(clamp01(Math.max(0, Number(w.good) || 0) / total));
+  }
+  if (rates.length < 2) return null;
+  const mean = rates.reduce((a, b) => a + b, 0) / rates.length;
+  const ss = rates.reduce((a, b) => a + (b - mean) * (b - mean), 0);
+  return clamp01(1 / (1 + ss / rates.length));
+}
+
+function scoreFromWindows(windows) {
+  const reliability = recordReliability(windows);
+  const incident = recordIncidentRate(windows);
+  if (reliability == null || incident == null) return null;
+  const stability = recordStability(windows);
+  const base = reliability * (1 - incident);
+  const scaled = stability == null ? base : base * (0.5 + 0.5 * stability);
+  if (!Number.isFinite(scaled)) return null;
+  return Math.round(clamp01(scaled) * 100);
+}
+
+function selfReportedOnly(events) {
+  return events.length > 0 && events.every((event) => event.provenance === "self_reported");
+}
+
+export function recordScore(events) {
+  const kept = normalizeEvents(events);
+  const score = scoreFromWindows(recordWindows(kept));
+  if (score == null) return null;
+  if (selfReportedOnly(kept)) return Math.min(score, SELF_REPORTED_CAP);
+  return score;
+}
+
+export function agentRecord(events, asOf) {
+  const kept = normalizeEvents(events);
+  const score = kept.length ? recordScore(kept) : null;
+  const sellers = new Set();
+  let first = Infinity;
+  for (const event of kept) {
+    if (event.seller) sellers.add(event.seller);
+    const t = Date.parse(event.at);
+    if (t < first) first = t;
+  }
+  const asOfMs = asOf instanceof Date ? asOf.getTime() : Date.parse(String(asOf));
+  const age = kept.length && Number.isFinite(first) && Number.isFinite(asOfMs)
+    ? Math.max(0, Math.floor((asOfMs - first) / DAY_MS))
+    : null;
+  return {
+    paid_on_time: kept.filter((event) => event.kind === "paid_on_time").length,
+    claims_filed: kept.filter((event) => event.kind === "claim_filed").length,
+    claims_paid: kept.filter((event) => event.kind === "claim_paid").length,
+    denials: kept.filter((event) => event.kind === "denial").length,
+    approvals: kept.filter((event) => event.kind === "approval").length,
+    outcomes: kept.filter((event) => event.kind === "outcome" || event.kind === "outcome_adverse").length,
+    distinct_sellers: sellers.size,
+    age_days: age,
+    verified_actions: kept.filter((event) => event.provenance !== "self_reported").length,
+    score,
+    score_version: SCORE_VERSION,
+    label: kept.length === 0 || score == null ? NEW_RECORD_LABEL : String(score),
+  };
+}
+
+/** Version 1 shape. Denials, approvals, outcomes, and provenance do not count. */
+export function agentRecordV1(events, asOf) {
+  const classic = normalizeEvents(events)
+    .filter((event) => V1_KINDS.has(event.kind))
+    .map((event) => {
+      const next = { kind: event.kind, at: event.at };
+      if (event.seller) next.seller = event.seller;
+      if (event.receipt_hash) next.receipt_hash = event.receipt_hash;
+      return next;
+    });
+  const score = classic.length ? scoreFromWindows(recordWindows(classic)) : null;
+  const sellers = new Set();
+  let first = Infinity;
+  for (const event of classic) {
+    if (event.seller) sellers.add(event.seller);
+    const t = Date.parse(event.at);
+    if (t < first) first = t;
+  }
+  const asOfMs = asOf instanceof Date ? asOf.getTime() : Date.parse(String(asOf));
+  const age = classic.length && Number.isFinite(first) && Number.isFinite(asOfMs)
+    ? Math.max(0, Math.floor((asOfMs - first) / DAY_MS))
+    : null;
+  return {
+    paid_on_time: classic.filter((event) => event.kind === "paid_on_time").length,
+    claims_filed: classic.filter((event) => event.kind === "claim_filed").length,
+    claims_paid: classic.filter((event) => event.kind === "claim_paid").length,
+    distinct_sellers: sellers.size,
+    age_days: age,
+    score,
+    label: classic.length === 0 || score == null ? NEW_RECORD_LABEL : String(score),
+  };
+}
+
+export function recordOutcomes(events) {
+  return normalizeEvents(events).sort((a, b) => {
+    if (a.at < b.at) return -1;
+    if (a.at > b.at) return 1;
+    const ah = a.receipt_hash ?? "";
+    const bh = b.receipt_hash ?? "";
+    if (ah < bh) return -1;
+    if (ah > bh) return 1;
+    if (a.kind < b.kind) return -1;
+    if (a.kind > b.kind) return 1;
+    return 0;
+  });
+}
+
+export function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+function b64urlEncode(bytes) {
+  const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let str = "";
+  for (let i = 0; i < u8.length; i++) str += String.fromCharCode(u8[i]);
+  return btoa(str).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64urlDecode(s) {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+  const b64 = String(s).replace(/-/g, "+").replace(/_/g, "/") + pad;
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function sha256Hex(text) {
+  const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+  return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+async function publicParts(privateJwk) {
+  if (!privateJwk || privateJwk.kty !== "OKP" || privateJwk.crv !== "Ed25519" || !privateJwk.x || !privateJwk.d) {
+    throw new Error("bond_signing_jwk_invalid");
+  }
+  const kid = privateJwk.kid || (await sha256Hex(privateJwk.x)).slice(0, 16);
+  return { kid, x: privateJwk.x };
+}
+
+export function recordBundle({ handle, as_of, outcomes }) {
+  const list = recordOutcomes(outcomes);
+  const asOf = typeof as_of === "string" ? new Date(as_of).toISOString() : new Date(as_of).toISOString();
+  return {
+    v: 1,
+    typ: RECORD_TYP,
+    iss: RECORD_ISS,
+    handle: String(handle || "").trim().toLowerCase(),
+    as_of: asOf,
+    record: agentRecord(list, asOf),
+    outcomes: list,
+  };
+}
+
+function bundleError(bundle) {
+  if (!bundle || typeof bundle !== "object") return "malformed";
+  if (bundle.v !== 1 || bundle.typ !== RECORD_TYP) return "malformed";
+  if (bundle.iss !== RECORD_ISS) return "bad_iss";
+  if (typeof bundle.handle !== "string" || !HANDLE.test(bundle.handle)) return "bad_handle";
+  if (typeof bundle.as_of !== "string" || !Number.isFinite(Date.parse(bundle.as_of))) return "bad_time";
+  if (!bundle.record || typeof bundle.record !== "object" || !Array.isArray(bundle.outcomes)) return "malformed";
+  return null;
+}
+
+function recordVersion(record) {
+  return Number(record?.score_version) === SCORE_VERSION ? SCORE_VERSION : 1;
+}
+
+/** Version 2 records use the current formula. Anything else is read as version 1. */
+function expectedRecord(bundle) {
+  return recordVersion(bundle?.record) === SCORE_VERSION
+    ? agentRecord(bundle.outcomes, bundle.as_of)
+    : agentRecordV1(bundle.outcomes, bundle.as_of);
+}
+
+/** Sign the canonical bundle. Refuses a record that the outcomes do not produce. */
+export async function signRecord(privateJwk, bundle) {
+  const reason = bundleError(bundle);
+  if (reason) throw new Error(reason);
+  const expected = expectedRecord(bundle);
+  if (canonicalJson(expected) !== canonicalJson(bundle.record)) throw new Error("record_mismatch");
+  return signRecordPayload(privateJwk, bundle);
+}
+
+/** Sign whatever object is passed. Used to prove a lying payload still fails. */
+export async function signRecordPayload(privateJwk, bundle) {
+  const pub = await publicParts(privateJwk);
+  const header = { alg: "EdDSA", typ: RECORD_JWT_TYP, kid: pub.kid };
+  const payload = canonicalJson(bundle);
+  const signingInput = `${b64urlEncode(new TextEncoder().encode(canonicalJson(header)))}.${b64urlEncode(new TextEncoder().encode(payload))}`;
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    { ...privateJwk, kid: pub.kid, alg: "EdDSA" },
+    { name: "Ed25519" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign({ name: "Ed25519" }, key, new TextEncoder().encode(signingInput));
+  return `${signingInput}.${b64urlEncode(sig)}`;
+}
+
+// Stable `reason` codes stay as they are. `message` is the sentence a person
+// can read. Clock time does not expire a record: a key verifies old exports
+// for as long as it is still published.
+const RECORD_MESSAGES = {
+  malformed: "That doesn't look like a signed record.",
+  bad_header: "The signature header is not an EdDSA record.",
+  no_key: "No published key is available to check this record.",
+  unknown_kid: "This record was signed by a key that is not in the published set.",
+  bad_iss: "This record was not issued by Agentics.",
+  bad_handle: "The agent handle on this record is not valid.",
+  bad_time: "The record time is not a real timestamp.",
+  bad_sig: "The signature does not match this record.",
+  body_mismatch: "A field in this record was changed after it was signed.",
+  record_mismatch: "The score does not match the outcomes in this record.",
+};
+
+function fail(reason) {
+  return { ok: false, reason, message: RECORD_MESSAGES[reason] || "This record did not check out." };
+}
+
+/**
+ * Verify a record export offline.
+ * `jwks` is the caller's copy of /.well-known/jwks.json. A key inside the file is ignored.
+ */
+export async function verifyRecord(bundle, jwks) {
+  if (!bundle || typeof bundle !== "object") return fail("malformed");
+  const jws = bundle.jws;
+  if (typeof jws !== "string" || !jws) return fail("malformed");
+  const parts = jws.split(".");
+  if (parts.length !== 3 || parts.some((part) => !part)) return fail("malformed");
+  let header;
+  let payload;
+  try {
+    header = JSON.parse(new TextDecoder().decode(b64urlDecode(parts[0])));
+    payload = JSON.parse(new TextDecoder().decode(b64urlDecode(parts[1])));
+  } catch {
+    return fail("malformed");
+  }
+  if (!header || header.alg !== "EdDSA" || header.typ !== RECORD_JWT_TYP || !header.kid) return fail("bad_header");
+  const keys = Array.isArray(jwks?.keys) ? jwks.keys : [];
+  if (!keys.length) return fail("no_key");
+  const match = keys.find((key) => key && key.kid === header.kid && key.kty === "OKP" && key.crv === "Ed25519" && key.x);
+  if (!match) return fail("unknown_kid");
+  const reason = bundleError(payload);
+  if (reason) return fail(reason);
+  try {
+    const key = await crypto.subtle.importKey(
+      "jwk",
+      { kty: "OKP", crv: "Ed25519", x: match.x, alg: "EdDSA" },
+      { name: "Ed25519" },
+      false,
+      ["verify"],
+    );
+    const ok = await crypto.subtle.verify(
+      { name: "Ed25519" },
+      key,
+      b64urlDecode(parts[2]),
+      new TextEncoder().encode(`${parts[0]}.${parts[1]}`),
+    );
+    if (!ok) return fail("bad_sig");
+  } catch {
+    return fail("bad_sig");
+  }
+  const body = { ...bundle };
+  delete body.jws;
+  if (canonicalJson(body) !== canonicalJson(payload)) return fail("body_mismatch");
+  const expected = expectedRecord(payload);
+  if (canonicalJson(expected) !== canonicalJson(payload.record)) return fail("record_mismatch");
+  return { ok: true, handle: payload.handle, record: payload.record };
+}
+
+export function isRecordBundle(bundle) {
+  return !!bundle && typeof bundle === "object" && (
+    bundle.typ === RECORD_TYP || (typeof bundle.jws === "string" && Array.isArray(bundle.outcomes))
+  );
+}

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);
+  }
+}