blindseal-sdk 0.0.0-stage → 0.5.0

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,29 @@
+import { Connection, Keypair, PublicKey, type Signer } from '@solana/web3.js';
+import { type Attestation } 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>;
+export interface VerifyResult {
+    ok: boolean;
+    reason: string | null;
+}
+/** Off-chain Groth16 verify via the same wasm the verify pages use. */
+export declare function verifyOffchain(att: Attestation): Promise<VerifyResult>;

package/dist/index.js

@@ -0,0 +1,52 @@
+// 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;
+}
+/** Off-chain Groth16 verify via the same wasm the verify pages use. */
+export async function verifyOffchain(att) {
+    const wasm = await import('blindseal-verifier-wasm');
+    const { readFileSync } = await import('node:fs');
+    const req = createRequire(import.meta.url);
+    const bytes = readFileSync(req.resolve('blindseal-verifier-wasm/bg.wasm'));
+    wasm.initSync({ module: bytes });
+    return JSON.parse(wasm.verify_attestation_json(JSON.stringify(att)));
+}

package/dist/ix.d.ts

@@ -0,0 +1,102 @@
+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;
+/** Decode the 168-byte committed blob into its six fields. */
+export declare function decodePublicInputs(blob: Uint8Array): {
+    payloadHash: Buffer;
+    policyRoot: Buffer;
+    detectorVersion: Buffer;
+    actionHash: Buffer;
+    nullifier: Buffer;
+    expirySlot: bigint;
+};
+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,167 @@
+// 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();
+/** Decode the 168-byte committed blob into its six fields. */
+export function decodePublicInputs(blob) {
+    if (blob.length !== 168)
+        throw new Error(`publicInputs must be 168 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,
+    });
+}