@x1id/resolve 0.23.0 → 0.44.0

package/dist/shield.js

@@ -0,0 +1,695 @@
+/**
+ * Shield: confidential zXNT / zUSDC.X on X1 (docs/specs/shield-confidential-tokens.md).
+ *
+ * What this module gives an integrator, with no dependencies and no proofs:
+ *
+ * - the Shield addresses, derived exactly like `programs/x1-shield`:
+ *   z-mint `["z-mint", backing]`, `ShieldMint` `["shield-mint", z_mint]`, the
+ *   reserve (the ShieldMint PDA's associated token account of the backing
+ *   mint) and a holder's Shield account (their Token-2022 ATA of the z-mint);
+ * - the `shield` / `unshield` instruction builders (`buildShieldIx`,
+ *   `buildUnshieldIx`);
+ * - decoders for a `ShieldMint` record and a Token-2022 account's
+ *   `ConfidentialTransferAccount` extension, plus the "ready to receive
+ *   privately" rule (spec §7);
+ * - {@link resolveShieldRecipient}: `@name` → the address to pay under the
+ *   one payment rule (verified X1 record, else the current authority), its
+ *   Shield account and whether it is ready, honouring the `x1.shield = off`
+ *   opt-out text record and refusing reserved (treasury-held) names;
+ * - payment receipts (`x1receipt1…`): a strict bech32m codec, and
+ *   {@link verifyShieldReceipt}, which finds the payment's proof data on chain
+ *   and hands it to a commitment checker.
+ *
+ * Proof generation and the elliptic-curve check of a receipt stay in the
+ * separate `shield-proofs` WASM (spec §7: "so the SDK stays light"); this
+ * module takes that check as a function (`checkCommitments`), e.g.
+ * `(r, kind, data) => wasm.verifyReceiptAgainstProof(r, kind, data)`.
+ *
+ * PDAs come through an injected {@link PdaFinder}, like every other builder in
+ * this package: it never hand-rolls the ed25519 on-curve check.
+ */
+import { encodeBase58, decodeBase58, decodeBase58_32 } from "./base58.js";
+import { makeAccountReader, nftHolder, parseHandleAccount, } from "./accounts.js";
+import { fetchRecords, liveRecords } from "./records.js";
+import { fetchTextRecords, findTextRecord } from "./textRecords.js";
+import { fetchConfigTreasury } from "./register.js";
+import { paymentAddressFor } from "./payment.js";
+import { ResolveError } from "./types.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** `programs/x1-shield` as deployed on X1 TESTNET (S1). Mainnet is not
+ *  deployed yet (owner gate S5); a mainnet deploy may use its own id, so
+ *  integrators should take the id from their network config. */
+export const SHIELD_PROGRAM_ID_TESTNET = "7Kqs3Nu82F1NCoUgnKEBUyW2uiftRXQjc7vJ3D2Zdzxo";
+export const TOKEN_2022_PROGRAM_ID = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+/** Classic SPL Token (p-token on X1) — the wrapped-native mint's program. */
+export const SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+export const ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+export const ZK_ELGAMAL_PROOF_PROGRAM_ID = "ZkE1Gama1Proof11111111111111111111111111111";
+/** Wrapped-native mint: the backing of zXNT. */
+export const NATIVE_MINT = "So11111111111111111111111111111111111111112";
+/** USDC.X on X1 mainnet: the backing of zUSDC.X there (spec §3). */
+export const USDCX_MINT_MAINNET = "B69chRzqzDCmdB5WYB8NRu5Yv5ZA95ABiZcdzCgGm9Tq";
+export const Z_MINT_SEED = "z-mint";
+export const SHIELD_MINT_SEED = "shield-mint";
+/** `sha256("global:shield")[0..8]`. */
+export const SHIELD_DISCRIMINATOR = Uint8Array.from([220, 198, 253, 246, 231, 84, 147, 98]);
+/** `sha256("global:unshield")[0..8]`. */
+export const UNSHIELD_DISCRIMINATOR = Uint8Array.from([21, 228, 55, 24, 194, 10, 21, 22]);
+/** `sha256("account:ShieldMint")[0..8]`. */
+export const SHIELD_MINT_ACCOUNT_DISCRIMINATOR = Uint8Array.from([183, 22, 172, 202, 204, 78, 142, 136]);
+/** Token-2022 caps one confidential Deposit at 2^48 − 1 base units, so one
+ *  `shield` above that reverts (x1-shield FBL-0008): split it. */
+export const MAX_SHIELD_AMOUNT = (1n << 48n) - 1n;
+/** The X1ID text record a name sets to `off` to opt out of being offered for
+ *  private payments (spec §7). */
+export const SHIELD_OPT_OUT_TEXT_KEY = "x1.shield";
+const TE = new TextEncoder();
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+function u64le(n) {
+    if (n < 0n || n > 0xffffffffffffffffn)
+        throw new Error("amount must fit in a u64");
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, n, true);
+    return b;
+}
+function readU64LE(d, o) {
+    return new DataView(d.buffer, d.byteOffset, d.byteLength).getBigUint64(o, true);
+}
+function b64ToBytes(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+// ---------------------------------------------------------------------------
+// PDAs
+// ---------------------------------------------------------------------------
+/** The canonical z-mint of `backingMint`: `["z-mint", backing]`. */
+export async function deriveZMint(find, programId, backingMint) {
+    return find([TE.encode(Z_MINT_SEED), toBytes32(backingMint, "backingMint")], toBase58(programId, "programId"));
+}
+/** A z-mint's `ShieldMint` record (its mint authority and the reserve's
+ *  owner): `["shield-mint", z_mint]`. */
+export async function deriveShieldMint(find, programId, zMint) {
+    return find([TE.encode(SHIELD_MINT_SEED), toBytes32(zMint, "zMint")], toBase58(programId, "programId"));
+}
+/** Associated token account of `owner` for `mint` under `tokenProgram`. */
+export async function deriveAssociatedTokenAccount(find, owner, mint, tokenProgram) {
+    return find([toBytes32(owner, "owner"), toBytes32(tokenProgram, "tokenProgram"), toBytes32(mint, "mint")], ASSOCIATED_TOKEN_PROGRAM_ID);
+}
+/** A holder's Shield account for `zMint`: their Token-2022 ATA of it. */
+export function deriveShieldAccount(find, owner, zMint) {
+    return deriveAssociatedTokenAccount(find, owner, zMint, TOKEN_2022_PROGRAM_ID);
+}
+export async function deriveShieldAccounts(find, p) {
+    const zMint = await deriveZMint(find, p.programId, p.backingMint);
+    const shieldMint = await deriveShieldMint(find, p.programId, zMint);
+    const reserve = await deriveAssociatedTokenAccount(find, shieldMint, p.backingMint, p.backingTokenProgram);
+    if (p.owner === undefined)
+        return { zMint, shieldMint, reserve };
+    const [zAccount, backingAccount] = await Promise.all([
+        deriveShieldAccount(find, p.owner, zMint),
+        deriveAssociatedTokenAccount(find, p.owner, p.backingMint, p.backingTokenProgram),
+    ]);
+    return { zMint, shieldMint, reserve, zAccount, backingAccount };
+}
+const k = (pubkey, what, isSigner, isWritable) => ({
+    pubkey: toBase58(pubkey, what),
+    isSigner,
+    isWritable,
+});
+/**
+ * `shield(amount)`: move backing into the reserve, mint exactly what arrived
+ * to the owner's Shield account and deposit it into its confidential PENDING
+ * balance. The owner's Shield account must already be configured for
+ * confidential balances. For zXNT, `backingAccount` is the owner's
+ * wrapped-native ATA, funded in the same transaction (create idempotent →
+ * system transfer → SyncNative → shield → CloseAccount; see
+ * programs/x1-shield/src/lib.rs "Client sequences").
+ */
+export function buildShieldIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            k(p.owner, "owner", true, false),
+            k(p.shieldMint, "shieldMint", false, true),
+            k(p.zMint, "zMint", false, true),
+            k(p.backingMint, "backingMint", false, false),
+            k(p.backingAccount, "backingAccount", false, true),
+            k(p.reserve, "reserve", false, true),
+            k(p.zAccount, "zAccount", false, true),
+            k(p.backingTokenProgram, "backingTokenProgram", false, false),
+            k(TOKEN_2022_PROGRAM_ID, "zTokenProgram", false, false),
+        ],
+        data: concatBytes(SHIELD_DISCRIMINATOR, u64le(p.amount)),
+    };
+}
+/**
+ * `unshield(amount)`: burn `amount` from the owner's PUBLIC z-balance (put
+ * there by a Token-2022 confidential Withdraw earlier in the same
+ * transaction), verify the burn, release exactly that backing to
+ * `backingAccount`. Note the account order differs from `shield`.
+ */
+export function buildUnshieldIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            k(p.owner, "owner", true, false),
+            k(p.shieldMint, "shieldMint", false, true),
+            k(p.zMint, "zMint", false, true),
+            k(p.backingMint, "backingMint", false, false),
+            k(p.zAccount, "zAccount", false, true),
+            k(p.reserve, "reserve", false, true),
+            k(p.backingAccount, "backingAccount", false, true),
+            k(p.backingTokenProgram, "backingTokenProgram", false, false),
+            k(TOKEN_2022_PROGRAM_ID, "zTokenProgram", false, false),
+        ],
+        data: concatBytes(UNSHIELD_DISCRIMINATOR, u64le(p.amount)),
+    };
+}
+function concatBytes(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+/** `disc(8) z_mint(32) backing_mint(32) reserve(32) backing_token_program(32)
+ *  decimals(1) shielded_supply(8) bump(1) z_mint_bump(1)`. Null when the bytes
+ *  are not a ShieldMint. */
+export function parseShieldMint(data) {
+    if (data.length < 147)
+        return null;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== SHIELD_MINT_ACCOUNT_DISCRIMINATOR[i])
+            return null;
+    const pk = (o) => encodeBase58(data.slice(o, o + 32));
+    return {
+        zMint: pk(8),
+        backingMint: pk(40),
+        reserve: pk(72),
+        backingTokenProgram: pk(104),
+        decimals: data[136],
+        shieldedSupply: readU64LE(data, 137),
+    };
+}
+/** spl-token-2022 base `Account` length; extensions follow. */
+const BASE_ACCOUNT_LEN = 165;
+const ACCOUNT_TYPE_ACCOUNT = 2;
+/** `ExtensionType::ConfidentialTransferAccount`. */
+export const EXT_CONFIDENTIAL_TRANSFER_ACCOUNT = 5;
+const CT_ACCOUNT_LEN = 295;
+/** Decode a Token-2022 token account and its confidential extension. Null
+ *  when the bytes are not a token account. Pure. */
+export function decodeConfidentialTokenAccount(data) {
+    if (data.length < BASE_ACCOUNT_LEN)
+        return null;
+    const mint = encodeBase58(data.slice(0, 32));
+    const owner = encodeBase58(data.slice(32, 64));
+    const amount = readU64LE(data, 64);
+    let ct = null;
+    if (data.length > BASE_ACCOUNT_LEN) {
+        if (data[BASE_ACCOUNT_LEN] !== ACCOUNT_TYPE_ACCOUNT)
+            return null;
+        const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+        let o = BASE_ACCOUNT_LEN + 1;
+        while (o + 4 <= data.length) {
+            const type = dv.getUint16(o, true);
+            const len = dv.getUint16(o + 2, true);
+            const start = o + 4;
+            if (type === 0 || start + len > data.length)
+                break; // Uninitialized / padding
+            if (type === EXT_CONFIDENTIAL_TRANSFER_ACCOUNT && len >= CT_ACCOUNT_LEN) {
+                let p = start;
+                const take = (n) => {
+                    const v = data.slice(p, p + n);
+                    p += n;
+                    return v;
+                };
+                const approved = take(1)[0] === 1;
+                const elgamalPubkey = take(32);
+                const pendingLo = take(64);
+                const pendingHi = take(64);
+                const available = take(64);
+                const decryptable = take(36);
+                const allowConfidentialCredits = take(1)[0] === 1;
+                const allowNonConfidentialCredits = take(1)[0] === 1;
+                ct = {
+                    approved,
+                    elgamalPubkey,
+                    pendingLo,
+                    pendingHi,
+                    available,
+                    decryptable,
+                    allowConfidentialCredits,
+                    allowNonConfidentialCredits,
+                    pendingCreditCounter: readU64LE(data, p),
+                    maxPendingCreditCounter: readU64LE(data, p + 8),
+                };
+            }
+            o = start + len;
+        }
+    }
+    return { mint, owner, amount, ct };
+}
+/** True for the opt-out text record's value (`off`, any case/whitespace). */
+export function isShieldOptOut(value) {
+    return (value ?? "").trim().toLowerCase() === "off";
+}
+/**
+ * Judge readiness to receive privately (spec §7) from the account at the
+ * derived Shield address: `account` is `{ data, owner }` as read from chain
+ * (null = no account). Pure.
+ */
+export function shieldReadiness(account, expected, optedOut = false) {
+    if (optedOut)
+        return { kind: "opted-out" };
+    if (!account)
+        return { kind: "no-account" };
+    if (account.owner !== TOKEN_2022_PROGRAM_ID)
+        return { kind: "mismatch" };
+    const acct = decodeConfidentialTokenAccount(account.data);
+    if (!acct || acct.owner !== expected.owner || acct.mint !== expected.zMint)
+        return { kind: "mismatch" };
+    if (!acct.ct)
+        return { kind: "not-configured" };
+    if (!acct.ct.approved || !acct.ct.allowConfidentialCredits)
+        return { kind: "not-accepting" };
+    return { kind: "ready", elgamalPubkey: acct.ct.elgamalPubkey };
+}
+/**
+ * Resolve an @name for a private payment in `zMint` (spec §7):
+ *
+ * 1. the name's payment address under the one rule (`paymentAddressFor`): a
+ *    live VERIFIED X1 record, else the current authority (`Handle.owner`, or
+ *    the pNFT holder of a tokenized name);
+ * 2. a reserved name (its payment target is the registry treasury) is
+ *    REFUSED — `ResolveError("reserved")`;
+ * 3. the recipient's Shield account (their Token-2022 ATA of `zMint`) is read
+ *    from chain: `ataReady` iff it is configured for confidential balances;
+ * 4. a live `x1.shield = off` text record makes the name not ready
+ *    (`readiness.kind === "opted-out"`), however its account looks.
+ *
+ * No X1ID record is needed to receive privately; readiness is chain state.
+ */
+export async function resolveShieldRecipient(name, zMint, config) {
+    const reader = makeAccountReader(config.rpcUrl, config.fetchImpl);
+    const rpc = reader.rpc;
+    const zMintB58 = toBase58(zMint, "zMint");
+    const programBytes = toBytes32(config.handleProgramId, "handleProgramId");
+    const programB58 = encodeBase58(programBytes);
+    const canonical = config.wasm.normalizeHandle(name.trim().replace(/^@/, ""));
+    if (!canonical)
+        throw new ResolveError("invalid-handle", `"${name}" is not a valid handle`, name);
+    const derived = config.wasm.deriveHandleAccount(canonical, programBytes);
+    if (!derived)
+        throw new ResolveError("invalid-handle", `"${name}" is not a valid handle`, name);
+    const handleAccount = encodeBase58(derived);
+    const info = await reader.accountInfo(handleAccount);
+    if (!info || info.owner !== programB58)
+        throw new ResolveError("not-found", `@${canonical} is not registered`, name);
+    const handle = parseHandleAccount(info.data);
+    if (!handle)
+        throw new ResolveError("rpc-error", `@${canonical} returned a malformed account`, name);
+    const authority = handle.nftMint === null
+        ? encodeBase58(handle.owner)
+        : (await nftHolder(reader, config.wasm, canonical, handle.nftMint, name)).address;
+    const treasury = config.treasury ??
+        (await fetchConfigTreasury(rpc, await config.find([TE.encode("config")], programB58))) ??
+        null;
+    const reserved = () => new ResolveError("reserved", `@${canonical} is reserved by X1ID and can't receive payments`, name);
+    if (treasury !== null && authority === treasury)
+        throw reserved();
+    const records = liveRecords(await fetchRecords(rpc, programB58, handleAccount, handle.registeredAt, handle.recordsClearedAt, handle.holderEpoch));
+    const payment = paymentAddressFor(records, authority);
+    if (!payment)
+        throw new ResolveError("not-found", `@${canonical} has no payment address right now`, name);
+    if (treasury !== null && payment.address === treasury)
+        throw reserved();
+    // holderEpoch: a native tokenized sale must stale the seller's opt-out.
+    // findTextRecord: byte-exact key, live only, never a BOM look-alike.
+    const texts = await fetchTextRecords(rpc, programB58, handleAccount, handle.registeredAt, handle.recordsClearedAt, handle.holderEpoch);
+    const optedOut = isShieldOptOut(findTextRecord(texts, SHIELD_OPT_OUT_TEXT_KEY)?.text);
+    const zAccount = await deriveShieldAccount(config.find, payment.address, zMintB58);
+    const acct = await reader.accountInfo(zAccount);
+    const readiness = shieldReadiness(acct, { owner: payment.address, zMint: zMintB58 }, optedOut);
+    return {
+        name: canonical,
+        handleAccount,
+        address: payment.address,
+        basis: payment.basis,
+        zAccount,
+        ataReady: readiness.kind === "ready",
+        readiness,
+        elgamalPubkey: readiness.kind === "ready" ? readiness.elgamalPubkey : null,
+    };
+}
+// ---------------------------------------------------------------------------
+// bech32m (BIP-350) — the receipt / view-key string format
+// ---------------------------------------------------------------------------
+const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const BECH32M_CONST = 0x2bc830a3;
+function polymod(values) {
+    const G = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+    let chk = 1;
+    for (const v of values) {
+        const top = chk >>> 25;
+        chk = ((chk & 0x1ffffff) << 5) ^ v;
+        for (let i = 0; i < 5; i++)
+            if ((top >>> i) & 1)
+                chk ^= G[i];
+    }
+    return chk >>> 0;
+}
+function hrpExpand(hrp) {
+    const out = [];
+    for (let i = 0; i < hrp.length; i++)
+        out.push(hrp.charCodeAt(i) >> 5);
+    out.push(0);
+    for (let i = 0; i < hrp.length; i++)
+        out.push(hrp.charCodeAt(i) & 31);
+    return out;
+}
+function convertBits(data, from, to, pad) {
+    let acc = 0;
+    let bits = 0;
+    const out = [];
+    const maxv = (1 << to) - 1;
+    for (let i = 0; i < data.length; i++) {
+        const v = data[i];
+        if (v < 0 || v >> from !== 0)
+            return null;
+        acc = (acc << from) | v;
+        bits += from;
+        while (bits >= to) {
+            bits -= to;
+            out.push((acc >> bits) & maxv);
+        }
+    }
+    if (pad) {
+        if (bits > 0)
+            out.push((acc << (to - bits)) & maxv);
+    }
+    else if (bits >= from || ((acc << (to - bits)) & maxv) !== 0) {
+        return null;
+    }
+    return out;
+}
+/** bech32m-encode `bytes` under `hrp` (no 90-char limit: receipts are long). */
+export function bech32mEncode(hrp, bytes) {
+    const data = convertBits(bytes, 8, 5, true);
+    const values = [...hrpExpand(hrp), ...data, 0, 0, 0, 0, 0, 0];
+    const mod = polymod(values) ^ BECH32M_CONST;
+    const checksum = Array.from({ length: 6 }, (_, i) => (mod >>> (5 * (5 - i))) & 31);
+    return `${hrp}1${[...data, ...checksum].map((d) => CHARSET[d]).join("")}`;
+}
+/** Strict bech32m decode: right checksum constant (not BIP-173 bech32), no
+ *  mixed case, the expected `hrp`. Null on any failure. */
+export function bech32mDecode(s, hrp) {
+    if (s.length > 1023)
+        return null;
+    if (s !== s.toLowerCase() && s !== s.toUpperCase())
+        return null;
+    const lower = s.toLowerCase();
+    const sep = lower.lastIndexOf("1");
+    if (sep < 1 || sep + 7 > lower.length)
+        return null;
+    if (lower.slice(0, sep) !== hrp)
+        return null;
+    const data = [];
+    for (const c of lower.slice(sep + 1)) {
+        const v = CHARSET.indexOf(c);
+        if (v < 0)
+            return null;
+        data.push(v);
+    }
+    if (polymod([...hrpExpand(hrp), ...data]) !== BECH32M_CONST)
+        return null;
+    const bytes = convertBits(data.slice(0, -6), 5, 8, false);
+    return bytes ? Uint8Array.from(bytes) : null;
+}
+// ---------------------------------------------------------------------------
+// Payment receipts (spec §5)
+// ---------------------------------------------------------------------------
+export const SHIELD_RECEIPT_HRP = "x1receipt";
+const RECEIPT_VERSION = 1;
+const RECEIPT_LEN = 1 + 64 + 32 + 8 + 32 + 32;
+export function encodeShieldReceipt(r) {
+    const sig = decodeBase58(r.txSignature, 64);
+    if (!sig)
+        throw new Error("txSignature must be a 64-byte base58 signature");
+    if (r.openingLo.length !== 32 || r.openingHi.length !== 32)
+        throw new Error("openings must be 32 bytes each");
+    return bech32mEncode(SHIELD_RECEIPT_HRP, concatBytes(Uint8Array.of(RECEIPT_VERSION), sig, toBytes32(r.mint, "mint"), u64le(r.amount), r.openingLo, r.openingHi));
+}
+/** Decode a receipt string. Null when it isn't a valid v1 receipt. */
+export function decodeShieldReceipt(s) {
+    const raw = bech32mDecode(s.trim(), SHIELD_RECEIPT_HRP);
+    if (!raw || raw.length !== RECEIPT_LEN || raw[0] !== RECEIPT_VERSION)
+        return null;
+    return {
+        txSignature: encodeBase58(raw.slice(1, 65)),
+        mint: encodeBase58(raw.slice(65, 97)),
+        amount: readU64LE(raw, 97),
+        openingLo: raw.slice(105, 137),
+        openingHi: raw.slice(137, 169),
+    };
+}
+/**
+ * Pull a receipt out of what someone pasted or scanned: the bare string,
+ * with whitespace or line breaks, or a `…/receipt?r=…` link. Returns the
+ * normalized lowercase receipt only when it decodes; null otherwise.
+ */
+export function extractShieldReceipt(input) {
+    let s = input.trim();
+    if (!s)
+        return null;
+    if (/^https?:\/\//i.test(s)) {
+        try {
+            s = new URL(s).searchParams.get("r") ?? "";
+        }
+        catch {
+            return null;
+        }
+    }
+    s = s.replace(/\s+/g, "");
+    if (s !== s.toLowerCase() && s !== s.toUpperCase())
+        return null;
+    s = s.toLowerCase();
+    return decodeShieldReceipt(s) ? s : null;
+}
+// ---------------------------------------------------------------------------
+// Payment lookup + receipt verification (S-2: proofs live in the staging txs)
+// ---------------------------------------------------------------------------
+/** `ProofType` of the two proofs that carry a transfer's amount commitments. */
+export const PROOF_TYPE_BATCHED_GROUPED_3_HANDLES_VALIDITY = 12;
+export const PROOF_TYPE_BATCHED_RANGE_U128 = 7;
+async function getTx(rpc, sig) {
+    return (await rpc("getTransaction", [
+        sig,
+        { encoding: "json", commitment: "confirmed", maxSupportedTransactionVersion: 0 },
+    ]));
+}
+function ixsOf(tx) {
+    const keys = tx.transaction.message.accountKeys;
+    return tx.transaction.message.instructions.map((ix) => ({
+        program: keys[ix.programIdIndex],
+        accounts: ix.accounts.map((i) => keys[i]),
+        data: decodeBase58(ix.data) ?? new Uint8Array(0),
+    }));
+}
+/** Successful transactions that touched `account` at or before `slot`. */
+async function txsTouching(rpc, account, slot, exclude) {
+    const sigs = ((await rpc("getSignaturesForAddress", [account, { limit: 25, commitment: "confirmed" }])) ?? []);
+    const out = [];
+    for (const s of sigs) {
+        if (s.err || s.slot > slot || s.signature === exclude)
+            continue;
+        const t = await getTx(rpc, s.signature);
+        if (t && !t.meta?.err)
+            out.push(t);
+    }
+    return out;
+}
+/** Token-2022 `TransferInstructionData` (no fee): [27, 7] ‖ new decryptable
+ *  available 36 ‖ auditor ciphertext lo 64 ‖ hi 64 ‖ equality, validity,
+ *  range proof instruction offsets (i8 each). */
+const TRANSFER_DATA_LEN = 2 + 36 + 64 + 64 + 3;
+const TRANSFER_COMMITMENT_LO = 2 + 36;
+const TRANSFER_COMMITMENT_HI = 2 + 36 + 64;
+const TRANSFER_OFFSETS = 2 + 36 + 64 + 64;
+/** Offsets inside `BatchedGroupedCiphertext3HandlesValidityProofData`:
+ *  context = first(source) pubkey 32 ‖ second(destination) pubkey 32 ‖
+ *  third(auditor) pubkey 32 ‖ grouped ciphertext lo 128 ‖ hi 128 (each =
+ *  commitment 32 ‖ handle×3), then the proof. */
+const VALIDITY_CONTEXT_LEN = 96 + 128 + 128;
+const VALIDITY_COMMITMENT_LO = 96;
+const VALIDITY_COMMITMENT_HI = 96 + 128;
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a[i] ^ b[i];
+    return d === 0;
+}
+/** Does this validity proof carry exactly the Transfer's amount commitments?
+ *  The payer controls the context account and can verify any number of
+ *  other proofs into it, so a proof found by address alone proves nothing
+ *  about this payment (Sentinel FBL-0009). */
+function provesThisTransfer(proof, lo, hi) {
+    return (proof.length >= VALIDITY_CONTEXT_LEN &&
+        bytesEqual(proof.subarray(VALIDITY_COMMITMENT_LO, VALIDITY_COMMITMENT_LO + 32), lo) &&
+        bytesEqual(proof.subarray(VALIDITY_COMMITMENT_HI, VALIDITY_COMMITMENT_HI + 32), hi));
+}
+const isInlineValidity = (ix) => ix.program === ZK_ELGAMAL_PROOF_PROGRAM_ID &&
+    ix.data[0] === PROOF_TYPE_BATCHED_GROUPED_3_HANDLES_VALIDITY &&
+    ix.data.length > 1 + VALIDITY_CONTEXT_LEN;
+/**
+ * Find a confidential payment and the proof data its amount lives in. The
+ * Transfer's accounts are decoded from its proof-offset bytes (an inline
+ * proof in the same transaction, or a context-state account plus the
+ * Instructions sysvar). For a context account the proof bytes come from the
+ * staging transaction that verified the 3-handle validity proof into it
+ * (crates/shield-proofs README, "S-2"), which depends on the RPC node still
+ * holding that transaction. Either way a proof is used only when its
+ * commitments equal the ones in the Transfer instruction, which Token-2022
+ * checked against the proof it consumed. Null when `txSignature` isn't a
+ * successful Token-2022 confidential transfer.
+ */
+export async function findShieldPayment(rpc, txSignature) {
+    const tx = await getTx(rpc, txSignature);
+    if (!tx || tx.meta?.err)
+        return null;
+    const ixs = ixsOf(tx);
+    const at = ixs.findIndex((ix) => ix.program === TOKEN_2022_PROGRAM_ID && ix.data[0] === 27 && ix.data[1] === 7);
+    const transfer = ixs[at];
+    if (!transfer || transfer.data.length !== TRANSFER_DATA_LEN)
+        return null;
+    const off = (i) => (transfer.data[TRANSFER_OFFSETS + i] << 24) >> 24; // i8
+    const [eqOff, valOff, rangeOff] = [off(0), off(1), off(2)];
+    // source, mint, destination, [Instructions sysvar if any proof is inline],
+    // then a context account for each proof that isn't inline, then authority
+    let i = 3;
+    if (eqOff !== 0 || valOff !== 0 || rangeOff !== 0)
+        i++;
+    if (eqOff === 0)
+        i++;
+    const ctxVal = valOff === 0 ? transfer.accounts[i++] : undefined;
+    if (rangeOff === 0)
+        i++;
+    const sender = transfer.accounts[i];
+    const [src, mint, dst] = transfer.accounts;
+    if (!src || !mint || !dst || !sender || (valOff === 0 && !ctxVal))
+        return null;
+    const lo = transfer.data.slice(TRANSFER_COMMITMENT_LO, TRANSFER_COMMITMENT_LO + 32);
+    const hi = transfer.data.slice(TRANSFER_COMMITMENT_HI, TRANSFER_COMMITMENT_HI + 32);
+    let validityProof = null;
+    if (valOff !== 0) {
+        const v = ixs[at + valOff];
+        if (v && isInlineValidity(v) && provesThisTransfer(v.data.subarray(1), lo, hi))
+            validityProof = v.data.slice(1);
+    }
+    else {
+        for (const t of await txsTouching(rpc, ctxVal, tx.slot, txSignature)) {
+            const v = ixsOf(t).find((ix) => isInlineValidity(ix) && ix.accounts[0] === ctxVal && provesThisTransfer(ix.data.subarray(1), lo, hi));
+            if (v) {
+                validityProof = v.data.slice(1);
+                break;
+            }
+        }
+    }
+    return {
+        txSignature,
+        slot: tx.slot,
+        blockTime: tx.blockTime,
+        zMint: mint,
+        sender,
+        sourceAccount: src,
+        destinationAccount: dst,
+        amountCommitmentLo: lo,
+        amountCommitmentHi: hi,
+        validityProof,
+    };
+}
+/**
+ * The amount ciphertexts of a payment as seen by one party (`"source"` or
+ * `"destination"`): 64-byte ElGamal ciphertexts `commitment ‖ that party's
+ * handle` for the amount's lo (16-bit) and hi (32-bit) parts. Decrypt with
+ * the party's keys as `lo + hi·2^16` (shield-proofs `decryptPending(lo, hi)`
+ * does exactly that). Also returns the party's ElGamal key from the proof so
+ * a caller can check it is theirs. Null on malformed data.
+ */
+export function paymentAmountCiphertexts(validityProof, party) {
+    if (validityProof.length < VALIDITY_CONTEXT_LEN)
+        return null;
+    const h = party === "source" ? 0 : 1;
+    const grouped = (start) => concatBytes(validityProof.slice(start, start + 32), validityProof.slice(start + 32 + 32 * h, start + 64 + 32 * h));
+    return {
+        lo: grouped(96),
+        hi: grouped(96 + 128),
+        elgamalPubkey: validityProof.slice(32 * h, 32 * h + 32),
+    };
+}
+/**
+ * Verify a receipt against the chain: decode it, find the payment
+ * ({@link findShieldPayment}), check the z-mint, and ask `checkCommitments`
+ * (the shield-proofs WASM's `verifyReceiptAgainstProof`) whether the
+ * receipt's amount and openings reproduce the commitments in the payment's
+ * own validity proof: the one whose commitments equal the Transfer
+ * instruction's (Sentinel FBL-0009). Anyone can run it; it needs no keys.
+ */
+export async function verifyShieldReceipt(receipt, opts) {
+    const r = decodeShieldReceipt(receipt);
+    if (!r)
+        return { ok: false, reason: "malformed" };
+    const tx = await getTx(opts.rpc, r.txSignature);
+    if (!tx || tx.meta?.err)
+        return { ok: false, reason: "not-found" };
+    const p = await findShieldPayment(opts.rpc, r.txSignature);
+    if (!p)
+        return { ok: false, reason: "not-a-payment" };
+    if (p.zMint !== r.mint)
+        return { ok: false, reason: "wrong-token" };
+    if (!p.validityProof || !provesThisTransfer(p.validityProof, p.amountCommitmentLo, p.amountCommitmentHi)) {
+        return { ok: false, reason: "no-proof-history" };
+    }
+    let ok = false;
+    try {
+        ok = await opts.checkCommitments(receipt.trim().toLowerCase(), PROOF_TYPE_BATCHED_GROUPED_3_HANDLES_VALIDITY, p.validityProof);
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok)
+        return { ok: false, reason: "mismatch" };
+    return {
+        ok: true,
+        amount: r.amount,
+        zMint: p.zMint,
+        txSignature: p.txSignature,
+        blockTime: p.blockTime,
+        sender: p.sender,
+        recipientAccount: p.destinationAccount,
+    };
+}
+/** Re-exported for callers that want to read account bytes the same way. */
+export { b64ToBytes as shieldBase64ToBytes };