blindseal-sdk 0.0.0-stage → 0.5.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 VaultMCP contributors
+Copyright (c) 2026 Blindseal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { Connection, Keypair, PublicKey, type Signer } from '@solana/web3.js';
+import { type Attestation, type DecodedPublicInputs } from './ix.js';
+export * from './ix.js';
+export declare class WrongClusterError extends Error {
+    readonly got: string;
+    constructor(got: string);
+}
+export interface SubmitOptions {
+    wallet: Signer | Keypair;
+    rpcUrl?: string;
+    connection?: Connection;
+    policyRoot?: PublicKey | null;
+    computeUnits?: number;
+    /** Test hook only: skip the genesis guard (localnet). Never set in production. */
+    allowNonMainnet?: boolean;
+}
+/**
+ * Submit an attestation directly (no gated program): verifies on-chain and consumes the nullifier.
+ * Refuses any cluster whose genesis hash is not mainnet-beta's — chainId 1 is the only chain.
+ */
+export declare function submit(att: Attestation, opts: SubmitOptions): Promise<string>;
+/** Has this attestation's nullifier been consumed on chain? */
+export declare function isConsumed(att: Attestation, conn: Connection, programId?: PublicKey): Promise<boolean>;
+/** Labeled top-level fields that must equal the committed public inputs. */
+export declare const LABELED_FIELDS: readonly ["payloadHash", "policyRoot", "detectorVersion", "actionHash", "nullifier", "expirySlot"];
+export type LabeledField = (typeof LABELED_FIELDS)[number];
+/**
+ * Result of `verifyOffchain`.
+ * - `ok`: true only if the Groth16 proof verifies AND every labeled field equals its decoded value.
+ * - `reason`: present when `ok` is false — the wasm verifier's reason if the proof failed, otherwise
+ *   `label mismatch: <field>[, <field>…]` (or the decode error if the blob is not 168 bytes).
+ * - `decoded`: the six fields decoded from `publicInputs[0]`; present whenever the blob parses,
+ *   even when the proof or the labels fail. Hex fields are 0x-prefixed lower-case; `expirySlot`
+ *   is a decimal u64 string.
+ * - `mismatches`: the labeled fields that differ from `decoded` (empty when none, or when the blob
+ *   did not parse).
+ */
+export interface VerifyOffchainResult {
+    ok: boolean;
+    reason?: string;
+    decoded?: DecodedPublicInputs;
+    mismatches: string[];
+}
+/** @deprecated Use `VerifyOffchainResult`. */
+export type VerifyResult = VerifyOffchainResult;
+/**
+ * Compare the six labeled top-level fields of an attestation to the decoded committed blob.
+ * Hex is compared case-insensitively with or without `0x`; `expirySlot` may be a number, bigint or
+ * decimal string. A missing or malformed label counts as a mismatch. Returns the differing field
+ * names in canonical order.
+ */
+export declare function labelMismatches(att: Partial<Record<LabeledField, unknown>>, decoded: DecodedPublicInputs): string[];
+/**
+ * Off-chain verify via the same wasm the verify pages use, then cross-check the labels.
+ * 1. Decode `publicInputs[0]` into its six fields (see `decodePublicInputs`).
+ * 2. Groth16 verify of `proof.bytes` against `publicInputs[0]`, using the DECODED `detectorVersion`
+ *    as the vkey hash (the committed one — same as the on-chain program, which checks the vkey it
+ *    verified with equals the blob's). The proof therefore stands or falls on the blob alone.
+ * 3. Compare each labeled top-level field to the decoded value; any difference fails the result,
+ *    because the proof binds only the blob — a tampered label would otherwise pass unnoticed.
+ * Does NOT check expiry against the current slot, nullifier consumption or the on-chain allowlists.
+ */
+export declare function verifyOffchain(att: Attestation): Promise<VerifyOffchainResult>;

package/dist/index.js

@@ -0,0 +1,109 @@
+// Blindseal SDK (BLINDSEAL.md §3.8). Mainnet is the only deploy target: chainId 1 = Solana
+// mainnet, 2 is reserved. `submit()` refuses any RPC whose genesis hash is not mainnet-beta's.
+// Everything encoding-related lives in ix.ts; this file adds the Node-dependent pieces.
+import { createRequire } from 'node:module';
+import { ComputeBudgetProgram, Connection, Transaction } from '@solana/web3.js';
+import { CHAIN_ID_SOLANA_MAINNET, DEFAULT_RPC_URL, MAINNET_GENESIS_HASH, PROGRAM_ID, VERIFY_CU_LIMIT, actionArgsFrom, buildVerifyIx, decodePublicInputs, hex, nullifierPda, } from './ix.js';
+export * from './ix.js';
+export class WrongClusterError extends Error {
+    got;
+    constructor(got) {
+        super(`RPC genesis hash ${got} is not Solana mainnet-beta (${MAINNET_GENESIS_HASH}); refusing to send`);
+        this.got = got;
+    }
+}
+/**
+ * Submit an attestation directly (no gated program): verifies on-chain and consumes the nullifier.
+ * Refuses any cluster whose genesis hash is not mainnet-beta's — chainId 1 is the only chain.
+ */
+export async function submit(att, opts) {
+    if (att.chainId !== CHAIN_ID_SOLANA_MAINNET)
+        throw new Error(`attestation chainId ${att.chainId} is not Solana mainnet (1)`);
+    const conn = opts.connection ?? new Connection(opts.rpcUrl ?? process.env.BLINDSEAL_RPC_URL ?? DEFAULT_RPC_URL, 'confirmed');
+    if (!opts.allowNonMainnet) {
+        const genesis = await conn.getGenesisHash();
+        if (genesis !== MAINNET_GENESIS_HASH)
+            throw new WrongClusterError(genesis);
+    }
+    const action = actionArgsFrom(att);
+    const ix = buildVerifyIx(att, action, { payer: opts.wallet.publicKey, policyRoot: opts.policyRoot });
+    const tx = new Transaction().add(ComputeBudgetProgram.setComputeUnitLimit({ units: opts.computeUnits ?? VERIFY_CU_LIMIT }), ix);
+    tx.feePayer = opts.wallet.publicKey;
+    tx.recentBlockhash = (await conn.getLatestBlockhash('confirmed')).blockhash;
+    tx.sign(opts.wallet);
+    const sig = await conn.sendRawTransaction(tx.serialize(), { skipPreflight: false });
+    await conn.confirmTransaction(sig, 'confirmed');
+    return sig;
+}
+/** Has this attestation's nullifier been consumed on chain? */
+export async function isConsumed(att, conn, programId = PROGRAM_ID) {
+    const { nullifier } = decodePublicInputs(hex(att.publicInputs[0]));
+    const info = await conn.getAccountInfo(nullifierPda(nullifier, programId), 'confirmed');
+    return info !== null;
+}
+/** Labeled top-level fields that must equal the committed public inputs. */
+export const LABELED_FIELDS = ['payloadHash', 'policyRoot', 'detectorVersion', 'actionHash', 'nullifier', 'expirySlot'];
+const normHex = (v) => '0x' + String(v ?? '').trim().replace(/^0x/i, '').toLowerCase();
+const normSlot = (v) => {
+    if (typeof v === 'bigint')
+        return v.toString();
+    if (typeof v === 'number')
+        return Number.isInteger(v) && v >= 0 ? String(v) : null;
+    if (typeof v === 'string' && /^\d+$/.test(v.trim()))
+        return BigInt(v.trim()).toString();
+    return null;
+};
+/**
+ * Compare the six labeled top-level fields of an attestation to the decoded committed blob.
+ * Hex is compared case-insensitively with or without `0x`; `expirySlot` may be a number, bigint or
+ * decimal string. A missing or malformed label counts as a mismatch. Returns the differing field
+ * names in canonical order.
+ */
+export function labelMismatches(att, decoded) {
+    const out = [];
+    for (const k of LABELED_FIELDS) {
+        const same = k === 'expirySlot' ? normSlot(att.expirySlot) === decoded.expirySlot : normHex(att[k]) === decoded[k];
+        if (!same)
+            out.push(k);
+    }
+    return out;
+}
+let wasmReady = null;
+const loadWasm = () => (wasmReady ??= (async () => {
+    const wasm = await import('blindseal-verifier-wasm');
+    const { readFileSync } = await import('node:fs');
+    const req = createRequire(import.meta.url);
+    wasm.initSync({ module: readFileSync(req.resolve('blindseal-verifier-wasm/bg.wasm')) });
+    return wasm;
+})().catch((e) => { wasmReady = null; throw e; }));
+/**
+ * Off-chain verify via the same wasm the verify pages use, then cross-check the labels.
+ * 1. Decode `publicInputs[0]` into its six fields (see `decodePublicInputs`).
+ * 2. Groth16 verify of `proof.bytes` against `publicInputs[0]`, using the DECODED `detectorVersion`
+ *    as the vkey hash (the committed one — same as the on-chain program, which checks the vkey it
+ *    verified with equals the blob's). The proof therefore stands or falls on the blob alone.
+ * 3. Compare each labeled top-level field to the decoded value; any difference fails the result,
+ *    because the proof binds only the blob — a tampered label would otherwise pass unnoticed.
+ * Does NOT check expiry against the current slot, nullifier consumption or the on-chain allowlists.
+ */
+export async function verifyOffchain(att) {
+    const wasm = await loadWasm();
+    let decoded;
+    let decodeError;
+    try {
+        decoded = decodePublicInputs(String(att.publicInputs?.[0] ?? ''));
+    }
+    catch (e) {
+        decodeError = e instanceof Error ? e.message : String(e);
+    }
+    const forWasm = decoded ? { ...att, detectorVersion: decoded.detectorVersion } : att;
+    const proof = JSON.parse(wasm.verify_attestation_json(JSON.stringify(forWasm)));
+    const mismatches = decoded ? labelMismatches(att, decoded) : [];
+    if (!proof.ok)
+        return { ok: false, reason: proof.reason ?? 'proof did not verify', decoded, mismatches };
+    if (!decoded)
+        return { ok: false, reason: decodeError ?? 'publicInputs did not decode', mismatches };
+    if (mismatches.length)
+        return { ok: false, reason: `label mismatch: ${mismatches.join(', ')}`, decoded, mismatches };
+    return { ok: true, decoded, mismatches };
+}

package/dist/ix.d.ts

@@ -0,0 +1,121 @@
+import { PublicKey, TransactionInstruction } from '@solana/web3.js';
+export declare const PROGRAM_ID: PublicKey;
+export declare const TRANSFER_GATE_ID: PublicKey;
+export declare const CHAIN_ID_SOLANA_MAINNET = 1;
+/** Genesis hash of Solana mainnet-beta — the only cluster submit() will talk to. */
+export declare const MAINNET_GENESIS_HASH = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d";
+export declare const DEFAULT_RPC_URL = "https://api.mainnet-beta.solana.com";
+/** Groth16 verify + nullifier creation; measured on localnet (docs/performance.md). */
+export declare const VERIFY_CU_LIMIT = 400000;
+export declare const ACTION_DOMAIN = "blindseal.action.v1";
+export declare const NULLIFIER_DOMAIN = "blindseal.nullifier.v1";
+export interface AttestationAction {
+    targetProgram: string;
+    sourceAuthority: string;
+    instruction: string;
+    recipient: string;
+    mint: string;
+    amount: string;
+}
+/** attestation.json as written by crates/prover / `blindseal attest`. */
+export interface Attestation {
+    version: number;
+    decisionId?: string | null;
+    chainId: number;
+    payloadHash: string;
+    policyRoot: string;
+    detectorVersion: string;
+    actionHash: string;
+    nullifier: string;
+    expirySlot: number;
+    nonce: string;
+    action: AttestationAction;
+    publicInputs: [string];
+    proof: {
+        protocol: 'groth16';
+        curve: 'bn254';
+        bytes: string;
+    };
+}
+export interface ActionArgs {
+    chainId: number;
+    targetProgram: PublicKey;
+    sourceAuthority: PublicKey;
+    instruction: Uint8Array;
+    recipient: PublicKey;
+    mint: PublicKey;
+    amount: bigint;
+    nonce: Uint8Array;
+}
+export declare const hex: (s: string) => Buffer;
+export declare function actionArgsFrom(att: Attestation): ActionArgs;
+export declare const configPda: (programId?: PublicKey) => PublicKey;
+export declare const policyRootPda: (root: Uint8Array, programId?: PublicKey) => PublicKey;
+export declare const nullifierPda: (nullifier: Uint8Array, programId?: PublicKey) => PublicKey;
+export declare function computeActionHash(a: ActionArgs, payloadHash: Uint8Array, policyRoot: Uint8Array, detectorVersion: Uint8Array, expirySlot: bigint): Buffer;
+export declare const computeNullifier: (actionHash: Uint8Array) => Buffer;
+export declare const PUBLIC_INPUTS_LEN = 168;
+/** The six committed fields as 0x-prefixed lower-case hex; `expirySlot` is a decimal u64 string. */
+export interface DecodedPublicInputs {
+    payloadHash: string;
+    policyRoot: string;
+    detectorVersion: string;
+    actionHash: string;
+    nullifier: string;
+    expirySlot: string;
+}
+/** Byte-level view of the same six fields (used by the instruction builders). */
+export interface DecodedPublicInputsBytes {
+    payloadHash: Buffer;
+    policyRoot: Buffer;
+    detectorVersion: Buffer;
+    actionHash: Buffer;
+    nullifier: Buffer;
+    expirySlot: bigint;
+}
+/**
+ * Decode the 168-byte committed blob into its six fields.
+ * - Given a hex string (`publicInputs[0]`, with or without `0x`), returns 0x-prefixed lower-case
+ *   hex fields and `expirySlot` as a decimal string — the shape `verifyOffchain` reports as `decoded`.
+ * - Given raw bytes, returns Buffers and a bigint expiry (the form the instruction builders use).
+ * Throws if the input is not exactly 168 bytes (or not valid hex).
+ */
+export declare function decodePublicInputs(blobHex: string): DecodedPublicInputs;
+export declare function decodePublicInputs(blob: Uint8Array): DecodedPublicInputsBytes;
+export declare const discriminator: (name: string) => Buffer;
+export declare function encodeActionArgs(a: ActionArgs): Buffer;
+export interface VerifyAccounts {
+    payer: PublicKey;
+    /** Pass when the program runs in allowlist mode; omit otherwise. */
+    policyRoot?: PublicKey | null;
+    programId?: PublicKey;
+}
+/** `verify_and_consume(proof, public_inputs, action)` for composing into a gated transaction. */
+export declare function buildVerifyIx(att: Attestation, action: ActionArgs, accounts: VerifyAccounts): TransactionInstruction;
+/** `initialize(allowed_vkeys, allowlist_policies)` — creates the Config PDA; `authority` pays and becomes the authority. */
+export declare function buildInitializeIx(authority: PublicKey, allowedVkeys: Uint8Array[], allowlistPolicies: boolean, programId?: PublicKey): TransactionInstruction;
+/** `set_config(allowed_vkeys?, allowlist_policies?, paused?)` — each `undefined` leaves the field unchanged. */
+export declare function buildSetConfigIx(authority: PublicKey, o: {
+    allowedVkeys?: Uint8Array[];
+    allowlistPolicies?: boolean;
+    paused?: boolean;
+}, programId?: PublicKey): TransactionInstruction;
+/** `register_policy_root(root)` — authority only; creates PDA(["policy", root]). */
+export declare function buildRegisterPolicyRootIx(authority: PublicKey, root: Uint8Array, programId?: PublicKey): TransactionInstruction;
+/** Decode the Config account (8 disc ‖ 32 authority ‖ vec<[u8;32]> ‖ bool allowlist ‖ bool paused ‖ u8 bump). */
+export declare function decodeConfig(data: Uint8Array): {
+    authority: string;
+    allowedVkeys: string[];
+    allowlistPolicies: boolean;
+    paused: boolean;
+    bump: number;
+};
+/** `gated_transfer(proof, public_inputs, nonce, amount)`: the gate CPIs verify_and_consume with the
+ *  action IT executes, then transfers `amount` lamports source → recipient in the same tx. */
+export declare function buildGatedTransferIx(att: Attestation, accounts: {
+    source: PublicKey;
+    recipient: PublicKey;
+    policyRoot?: PublicKey | null;
+    gateId?: PublicKey;
+    verifyId?: PublicKey;
+}): TransactionInstruction;

package/dist/ix.js

@@ -0,0 +1,187 @@
+// Pure, environment-agnostic part of the SDK: constants, types, PDAs, hashing (byte-for-byte
+// detector-core / on-chain), Anchor wire encoding and every instruction builder. Imported by the
+// localnet suite (CommonJS) and by index.ts (adds submit / verifyOffchain, which need Node APIs).
+import { createHash } from 'node:crypto';
+import { PublicKey, SystemProgram, TransactionInstruction } from '@solana/web3.js';
+export const PROGRAM_ID = new PublicKey('merZNYKpKwwX4CGgzvma3jPvLfrMTkZcb1cSXUKANcb');
+export const TRANSFER_GATE_ID = new PublicKey('ErAS5x2oUky3aCJPasSKNaf8USVE9of5vzHHCPWwSEVG');
+export const CHAIN_ID_SOLANA_MAINNET = 1;
+/** Genesis hash of Solana mainnet-beta — the only cluster submit() will talk to. */
+export const MAINNET_GENESIS_HASH = '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d';
+export const DEFAULT_RPC_URL = 'https://api.mainnet-beta.solana.com';
+/** Groth16 verify + nullifier creation; measured on localnet (docs/performance.md). */
+export const VERIFY_CU_LIMIT = 400_000;
+export const ACTION_DOMAIN = 'blindseal.action.v1';
+export const NULLIFIER_DOMAIN = 'blindseal.nullifier.v1';
+export const hex = (s) => Buffer.from(s.replace(/^0x/, ''), 'hex');
+const pk = (s) => (s ? new PublicKey(s) : PublicKey.default);
+export function actionArgsFrom(att) {
+    return {
+        chainId: att.chainId,
+        targetProgram: pk(att.action.targetProgram),
+        sourceAuthority: pk(att.action.sourceAuthority),
+        instruction: hex(att.action.instruction),
+        recipient: pk(att.action.recipient),
+        mint: pk(att.action.mint),
+        amount: BigInt(att.action.amount),
+        nonce: hex(att.nonce),
+    };
+}
+// ---- PDAs ----
+export const configPda = (programId = PROGRAM_ID) => PublicKey.findProgramAddressSync([Buffer.from('config')], programId)[0];
+export const policyRootPda = (root, programId = PROGRAM_ID) => PublicKey.findProgramAddressSync([Buffer.from('policy'), Buffer.from(root)], programId)[0];
+export const nullifierPda = (nullifier, programId = PROGRAM_ID) => PublicKey.findProgramAddressSync([Buffer.from('nullifier'), Buffer.from(nullifier)], programId)[0];
+// ---- hashing (byte-for-byte detector-core / on-chain) ----
+const u16le = (n) => { const b = Buffer.alloc(2); b.writeUInt16LE(n); return b; };
+const u64le = (n) => { const b = Buffer.alloc(8); b.writeBigUInt64LE(n); return b; };
+export function computeActionHash(a, payloadHash, policyRoot, detectorVersion, expirySlot) {
+    return createHash('sha256')
+        .update(ACTION_DOMAIN).update(u16le(a.chainId))
+        .update(a.targetProgram.toBytes()).update(a.sourceAuthority.toBytes()).update(a.instruction)
+        .update(a.recipient.toBytes()).update(a.mint.toBytes()).update(u64le(a.amount))
+        .update(payloadHash).update(policyRoot).update(detectorVersion).update(u64le(expirySlot)).update(a.nonce)
+        .digest();
+}
+export const computeNullifier = (actionHash) => createHash('sha256').update(NULLIFIER_DOMAIN).update(actionHash).digest();
+// ---- the committed public-input blob ----
+// `publicInputs[0]` is the guest's public values in commit order (crates/guest/src/main.rs):
+//   [0..32)    payloadHash      [32..64)   policyRoot      [64..96)   detectorVersion
+//   [96..128)  actionHash       [128..160) nullifier       [160..168) expirySlot (u64 LE)
+// 168 bytes = 336 hex chars. This is the ONLY data the proof binds; the six labeled top-level
+// fields of attestation.json are convenience copies and must be checked against it.
+export const PUBLIC_INPUTS_LEN = 168;
+export function decodePublicInputs(blob) {
+    if (typeof blob === 'string') {
+        const h = blob.trim().replace(/^0x/i, '').toLowerCase();
+        if (!/^[0-9a-f]*$/.test(h) || h.length % 2 !== 0)
+            throw new Error('publicInputs is not a hex string');
+        const b = decodeBytes(Buffer.from(h, 'hex'));
+        const hx = (x) => '0x' + x.toString('hex');
+        return {
+            payloadHash: hx(b.payloadHash), policyRoot: hx(b.policyRoot), detectorVersion: hx(b.detectorVersion),
+            actionHash: hx(b.actionHash), nullifier: hx(b.nullifier), expirySlot: b.expirySlot.toString(),
+        };
+    }
+    return decodeBytes(blob);
+}
+function decodeBytes(blob) {
+    if (blob.length !== PUBLIC_INPUTS_LEN)
+        throw new Error(`publicInputs must be ${PUBLIC_INPUTS_LEN} bytes, got ${blob.length}`);
+    const b = Buffer.from(blob);
+    return {
+        payloadHash: b.subarray(0, 32), policyRoot: b.subarray(32, 64), detectorVersion: b.subarray(64, 96),
+        actionHash: b.subarray(96, 128), nullifier: b.subarray(128, 160), expirySlot: b.readBigUInt64LE(160),
+    };
+}
+// ---- Anchor wire encoding ----
+export const discriminator = (name) => createHash('sha256').update(`global:${name}`).digest().subarray(0, 8);
+const vecU8 = (b) => { const len = Buffer.alloc(4); len.writeUInt32LE(b.length); return Buffer.concat([len, Buffer.from(b)]); };
+export function encodeActionArgs(a) {
+    return Buffer.concat([
+        u16le(a.chainId), a.targetProgram.toBuffer(), a.sourceAuthority.toBuffer(), Buffer.from(a.instruction),
+        a.recipient.toBuffer(), a.mint.toBuffer(), u64le(a.amount), Buffer.from(a.nonce),
+    ]);
+}
+/** `verify_and_consume(proof, public_inputs, action)` for composing into a gated transaction. */
+export function buildVerifyIx(att, action, accounts) {
+    const programId = accounts.programId ?? PROGRAM_ID;
+    const proof = hex(att.proof.bytes);
+    const blob = hex(att.publicInputs[0]);
+    const { nullifier } = decodePublicInputs(blob);
+    const data = Buffer.concat([discriminator('verify_and_consume'), vecU8(proof), vecU8(blob), encodeActionArgs(action)]);
+    const policy = accounts.policyRoot === undefined ? policyRootPda(decodePublicInputs(blob).policyRoot, programId) : accounts.policyRoot;
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: configPda(programId), isSigner: false, isWritable: false },
+            // Anchor optional account: pass the program id itself for None.
+            { pubkey: policy ?? programId, isSigner: false, isWritable: false },
+            { pubkey: nullifierPda(nullifier, programId), isSigner: false, isWritable: true },
+            { pubkey: accounts.payer, isSigner: true, isWritable: true },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data,
+    });
+}
+// ---- admin instructions (authority only) ----
+const boolB = (b) => Buffer.from([b ? 1 : 0]);
+const vecVkeys = (v) => { const len = Buffer.alloc(4); len.writeUInt32LE(v.length); return Buffer.concat([len, ...v.map((k) => Buffer.from(k))]); };
+const option = (present, body) => (present ? Buffer.concat([Buffer.from([1]), body]) : Buffer.from([0]));
+/** `initialize(allowed_vkeys, allowlist_policies)` — creates the Config PDA; `authority` pays and becomes the authority. */
+export function buildInitializeIx(authority, allowedVkeys, allowlistPolicies, programId = PROGRAM_ID) {
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: configPda(programId), isSigner: false, isWritable: true },
+            { pubkey: authority, isSigner: true, isWritable: true },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data: Buffer.concat([discriminator('initialize'), vecVkeys(allowedVkeys), boolB(allowlistPolicies)]),
+    });
+}
+/** `set_config(allowed_vkeys?, allowlist_policies?, paused?)` — each `undefined` leaves the field unchanged. */
+export function buildSetConfigIx(authority, o, programId = PROGRAM_ID) {
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: configPda(programId), isSigner: false, isWritable: true },
+            { pubkey: authority, isSigner: true, isWritable: false },
+        ],
+        data: Buffer.concat([
+            discriminator('set_config'),
+            option(o.allowedVkeys !== undefined, o.allowedVkeys ? vecVkeys(o.allowedVkeys) : Buffer.alloc(0)),
+            option(o.allowlistPolicies !== undefined, boolB(o.allowlistPolicies ?? false)),
+            option(o.paused !== undefined, boolB(o.paused ?? false)),
+        ]),
+    });
+}
+/** `register_policy_root(root)` — authority only; creates PDA(["policy", root]). */
+export function buildRegisterPolicyRootIx(authority, root, programId = PROGRAM_ID) {
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: configPda(programId), isSigner: false, isWritable: false },
+            { pubkey: policyRootPda(root, programId), isSigner: false, isWritable: true },
+            { pubkey: authority, isSigner: true, isWritable: true },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data: Buffer.concat([discriminator('register_policy_root'), Buffer.from(root)]),
+    });
+}
+/** Decode the Config account (8 disc ‖ 32 authority ‖ vec<[u8;32]> ‖ bool allowlist ‖ bool paused ‖ u8 bump). */
+export function decodeConfig(data) {
+    const b = Buffer.from(data);
+    const n = b.readUInt32LE(40);
+    const vkeys = [];
+    for (let i = 0; i < n; i++)
+        vkeys.push('0x' + b.subarray(44 + i * 32, 76 + i * 32).toString('hex'));
+    const off = 44 + n * 32;
+    return { authority: new PublicKey(b.subarray(8, 40)).toBase58(), allowedVkeys: vkeys, allowlistPolicies: b[off] === 1, paused: b[off + 1] === 1, bump: b[off + 2] };
+}
+// ---- transfer-gate (example gated program) ----
+/** `gated_transfer(proof, public_inputs, nonce, amount)`: the gate CPIs verify_and_consume with the
+ *  action IT executes, then transfers `amount` lamports source → recipient in the same tx. */
+export function buildGatedTransferIx(att, accounts) {
+    const gateId = accounts.gateId ?? TRANSFER_GATE_ID;
+    const verifyId = accounts.verifyId ?? PROGRAM_ID;
+    const proof = hex(att.proof.bytes);
+    const blob = hex(att.publicInputs[0]);
+    const { nullifier, policyRoot } = decodePublicInputs(blob);
+    const amount = Buffer.alloc(8);
+    amount.writeBigUInt64LE(BigInt(att.action.amount));
+    const data = Buffer.concat([discriminator('gated_transfer'), vecU8(proof), vecU8(blob), hex(att.nonce), amount]);
+    const policy = accounts.policyRoot === undefined ? policyRootPda(policyRoot, verifyId) : accounts.policyRoot;
+    return new TransactionInstruction({
+        programId: gateId,
+        keys: [
+            { pubkey: accounts.source, isSigner: true, isWritable: true },
+            { pubkey: accounts.recipient, isSigner: false, isWritable: true },
+            { pubkey: configPda(verifyId), isSigner: false, isWritable: false },
+            { pubkey: policy ?? gateId, isSigner: false, isWritable: false }, // Anchor optional None = program id
+            { pubkey: nullifierPda(nullifier, verifyId), isSigner: false, isWritable: true },
+            { pubkey: verifyId, isSigner: false, isWritable: false },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data,
+    });
+}