veralayer 0.0.0-stage → 0.2.0

package/dist/guard.js

@@ -0,0 +1,115 @@
+import { Vera } from './client.js';
+import { inspectTransaction } from './inspect.js';
+import { evaluatePolicy, validatePolicy } from './policy.js';
+export class MemoryLedger {
+    day = '';
+    spent = 0;
+    roll() { const d = new Date().toISOString().slice(0, 10); if (d !== this.day) {
+        this.day = d;
+        this.spent = 0;
+    } }
+    spentToday() { this.roll(); return this.spent; }
+    add(sol) { this.roll(); this.spent += sol; }
+}
+export class VeraBlockedError extends Error {
+    decision;
+    constructor(decision) {
+        super(`Vera blocked this transaction: ${decision.findings.filter((f) => f.action === 'block').map((f) => f.message).join('; ')}`);
+        this.decision = decision;
+    }
+}
+export class VeraReviewRequiredError extends Error {
+    decision;
+    constructor(decision) {
+        super(`Vera needs a human review: ${decision.findings.filter((f) => f.action === 'review').map((f) => f.message).join('; ')}`);
+        this.decision = decision;
+    }
+}
+export class VeraGuard {
+    vera;
+    policy;
+    connection;
+    wallet;
+    ledger;
+    onReview;
+    onDecision;
+    // evaluate + reserve run one at a time, so two concurrent sends can't both pass a daily limit
+    lock = Promise.resolve();
+    constructor(opts = {}) {
+        this.vera = opts.vera instanceof Vera ? opts.vera : new Vera(opts.vera);
+        this.policy = opts.policy ?? {};
+        validatePolicy(this.policy); // fail at startup on typos, not silently at payment time
+        this.connection = opts.connection;
+        this.wallet = opts.wallet;
+        this.ledger = opts.ledger ?? new MemoryLedger();
+        this.onReview = opts.onReview;
+        this.onDecision = opts.onDecision;
+    }
+    /** Score recipients (deduplicated, in parallel) and verify each signed result against Vera's published key. */
+    async checkRecipients(addresses) {
+        const skip = new Set([...(this.policy.allow ?? []), ...(this.policy.deny ?? [])]);
+        const uniq = [...new Set(addresses)].filter((a) => !skip.has(a));
+        return Promise.all(uniq.map(async (address) => {
+            try {
+                const r = await this.vera.check(address); // throws if the result is for another address
+                const v = await this.vera.verify(r);
+                const a = r.attestation;
+                return { address, ok: true, score: a.score, tier: a.tier, reasons: a.reasons, attestationId: r.id, verified: v.valid, expired: v.expired };
+            }
+            catch (e) {
+                return { address, ok: false, error: e.message };
+            }
+        }));
+    }
+    /** Decide on a planned payment without building a transaction (e.g. before quoting a price to another agent). */
+    async evaluatePayment(payment) {
+        const outflows = payment.token
+            ? [{ kind: 'token', to: payment.to, toAccount: payment.to, amount: payment.token.amount, mint: payment.token.mint, instruction: 'planned' }]
+            : [{ kind: 'sol', to: payment.to, toAccount: payment.to, amount: payment.amountSol ?? 0, instruction: 'planned' }];
+        return this.decide(outflows, {});
+    }
+    /** Decode a transaction and decide on it. Does not send anything. */
+    async evaluate(tx) {
+        const ins = await inspectTransaction(tx, this.connection, { wallet: this.wallet });
+        return this.decide(ins.outflows, { unknownPrograms: ins.unknownPrograms, valuePrograms: ins.valuePrograms, risky: ins.risky });
+    }
+    async decide(outflows, extra) {
+        const recipients = await this.checkRecipients(outflows.map((o) => o.to));
+        const decision = evaluatePolicy({ outflows, recipients, ...extra, spentTodaySol: await this.ledger.spentToday(), policy: this.policy });
+        this.onDecision?.(decision);
+        return decision;
+    }
+    /** Throws VeraBlockedError / VeraReviewRequiredError unless the transaction may be sent. */
+    async assert(tx) {
+        const d = await this.evaluate(tx);
+        if (d.action === 'block')
+            throw new VeraBlockedError(d);
+        if (d.action === 'review' && !(this.onReview && (await this.onReview(d))))
+            throw new VeraReviewRequiredError(d);
+        return d;
+    }
+    /** Evaluate, then sign and send only if allowed. The SOL is reserved in the ledger before sending and released if sending fails. */
+    async sendTransaction(tx, signers = [], options) {
+        if (!this.connection)
+            throw new Error('VeraGuard needs a Connection to send transactions');
+        const run = this.lock.then(async () => { const d = await this.assert(tx); await this.ledger.add(d.totalSol); return d; });
+        this.lock = run.catch(() => { });
+        const decision = await run;
+        try {
+            let signature;
+            if ('version' in tx) {
+                if (signers.length)
+                    tx.sign(signers);
+                signature = await this.connection.sendTransaction(tx, options);
+            }
+            else {
+                signature = await this.connection.sendTransaction(tx, signers, options);
+            }
+            return { signature, decision };
+        }
+        catch (e) {
+            await this.ledger.add(-decision.totalSol);
+            throw e;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Vera, VeraError, VERA_ISSUER, DEFAULT_API_URL, verifyAttestation, canonical, type Attestation, type CheckResult, type Tier, type VerifyResult } from './client.js';
+export { VeraGuard, MemoryLedger, VeraBlockedError, VeraReviewRequiredError, type GuardOptions, type SpendLedger } from './guard.js';
+export { inspectTransaction, instructionsOf, type Inspection } from './inspect.js';
+export { evaluatePolicy, validatePolicy, DEFAULT_POLICY, type Policy, type RiskyInstruction, type Decision, type Finding, type Outflow, type RecipientCheck, type Action } from './policy.js';
+export { KNOWN_PROGRAMS } from './programs.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+// veralayer: payment guard for AI agents on Solana.
+export { Vera, VeraError, VERA_ISSUER, DEFAULT_API_URL, verifyAttestation, canonical } from './client.js';
+export { VeraGuard, MemoryLedger, VeraBlockedError, VeraReviewRequiredError } from './guard.js';
+export { inspectTransaction, instructionsOf } from './inspect.js';
+export { evaluatePolicy, validatePolicy, DEFAULT_POLICY } from './policy.js';
+export { KNOWN_PROGRAMS } from './programs.js';

package/dist/inspect.d.ts

@@ -0,0 +1,29 @@
+import type { Connection, Transaction, VersionedTransaction } from '@solana/web3.js';
+import type { Outflow, RiskyInstruction } from './policy.js';
+export type Inspection = {
+    payer: string;
+    /** the wallet being guarded (option `wallet`, default the fee payer) */
+    wallet: string;
+    outflows: Outflow[];
+    programs: string[];
+    unknownPrograms: string[];
+    /** names of well-known programs called that can move value the guard does not decode */
+    valuePrograms: string[];
+    risky: RiskyInstruction[];
+    notes: string[];
+};
+type Ix = {
+    programId: string;
+    accounts: string[];
+    data: Uint8Array;
+};
+/** Flatten a legacy or versioned transaction into plain instructions, resolving address lookup tables. */
+export declare function instructionsOf(tx: Transaction | VersionedTransaction, connection?: Connection): Promise<{
+    payer: string;
+    ixs: Ix[];
+}>;
+/** Decode what leaves `wallet` (default: the fee payer). Token destinations are resolved to their owner via RPC when needed. */
+export declare function inspectTransaction(tx: Transaction | VersionedTransaction, connection?: Connection, opts?: {
+    wallet?: string;
+}): Promise<Inspection>;
+export {};

package/dist/inspect.js

@@ -0,0 +1,125 @@
+import { KNOWN_PROGRAMS } from './programs.js';
+const SYSTEM = '11111111111111111111111111111111';
+const TOKEN = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+const TOKEN22 = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
+const ATA = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+// programs that never move value on their own
+const INERT = new Set([SYSTEM, TOKEN, TOKEN22, ATA, 'ComputeBudget111111111111111111111111111111', 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr',
+    'Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo', 'noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV', 'AddressLookupTab1e1111111111111111111111111']);
+const u64 = (d, o) => Number(new DataView(d.buffer, d.byteOffset + o, 8).getBigUint64(0, true));
+const u32 = (d, o) => new DataView(d.buffer, d.byteOffset + o, 4).getUint32(0, true);
+const short = (a) => `${a.slice(0, 4)}…${a.slice(-4)}`;
+function isVersioned(tx) {
+    return 'version' in tx;
+}
+/** Flatten a legacy or versioned transaction into plain instructions, resolving address lookup tables. */
+export async function instructionsOf(tx, connection) {
+    if (!isVersioned(tx)) {
+        const payer = (tx.feePayer ?? tx.instructions[0]?.keys.find((k) => k.isSigner)?.pubkey)?.toBase58() ?? '';
+        return { payer, ixs: tx.instructions.map((ix) => ({ programId: ix.programId.toBase58(), accounts: ix.keys.map((k) => k.pubkey.toBase58()), data: Uint8Array.from(ix.data) })) };
+    }
+    const msg = tx.message;
+    const luts = [];
+    for (const l of msg.addressTableLookups ?? []) {
+        if (!connection)
+            throw new Error('a Connection is needed to resolve address lookup tables');
+        const res = await connection.getAddressLookupTable(l.accountKey);
+        if (!res.value)
+            throw new Error(`lookup table ${l.accountKey.toBase58()} not found`);
+        luts.push(res.value);
+    }
+    const keys = msg.getAccountKeys({ addressLookupTableAccounts: luts });
+    const k = (i) => keys.get(i).toBase58();
+    return {
+        payer: k(0),
+        ixs: msg.compiledInstructions.map((ix) => ({ programId: k(ix.programIdIndex), accounts: ix.accountKeyIndexes.map(k), data: ix.data })),
+    };
+}
+/** Decode what leaves `wallet` (default: the fee payer). Token destinations are resolved to their owner via RPC when needed. */
+export async function inspectTransaction(tx, connection, opts = {}) {
+    const { payer, ixs } = await instructionsOf(tx, connection);
+    const wallet = opts.wallet ?? payer;
+    const outflows = [];
+    const risky = [];
+    const notes = [];
+    const programs = new Set();
+    // token accounts created in this transaction: ata -> { owner, mint }  (Create = 0 / empty data, CreateIdempotent = 1)
+    const created = new Map();
+    for (const ix of ixs)
+        if (ix.programId === ATA && (ix.data.length === 0 || ix.data[0] <= 1) && ix.accounts.length >= 4)
+            created.set(ix.accounts[1], { owner: ix.accounts[2], mint: ix.accounts[3] });
+    const pendingTokens = [];
+    const sol = (from, to, lamports, instruction) => outflows.push({ kind: 'sol', from, to, toAccount: to, amount: lamports / 1e9, instruction });
+    for (const ix of ixs) {
+        programs.add(ix.programId);
+        const a = ix.accounts, d = ix.data;
+        if (ix.programId === SYSTEM && d.length >= 4) {
+            const op = u32(d, 0);
+            if (op === 0 && d.length >= 12)
+                sol(a[0], a[1], u64(d, 4), 'system.createAccount');
+            else if (op === 2 && d.length >= 12)
+                sol(a[0], a[1], u64(d, 4), 'system.transfer');
+            else if (op === 11 && d.length >= 12)
+                sol(a[1], a[2], u64(d, 4), 'system.transferWithSeed');
+            else if (op === 3 && d.length >= 44) {
+                const seedLen = u64(d, 36);
+                if (d.length >= 44 + seedLen + 8)
+                    sol(a[0], a[1], u64(d, 44 + seedLen), 'system.createAccountWithSeed');
+            }
+            else if (op === 5 && d.length >= 12)
+                sol(a[4], a[1], u64(d, 4), 'system.withdrawNonceAccount');
+            else if ((op === 1 || op === 10) && a[0] === wallet)
+                risky.push({ instruction: 'system.assign', message: `Reassigns the wallet ${short(wallet)} to another program` });
+        }
+        else if ((ix.programId === TOKEN || ix.programId === TOKEN22) && d.length >= 1) {
+            const op = d[0];
+            if (op === 3 && d.length >= 9)
+                pendingTokens.push({ account: a[1], raw: u64(d, 1), authority: a[2], instruction: 'token.transfer' });
+            else if (op === 12 && d.length >= 10)
+                pendingTokens.push({ account: a[2], raw: u64(d, 1), decimals: d[9], mint: a[1], authority: a[3], instruction: 'token.transferChecked' });
+            else if (op === 26 && d[1] === 1 && d.length >= 11)
+                pendingTokens.push({ account: a[2], raw: u64(d, 2), decimals: d[10], mint: a[1], authority: a[3], instruction: 'token.transferCheckedWithFee' });
+            else if ((op === 4 && a[2] === wallet) || (op === 13 && a[3] === wallet))
+                risky.push({ instruction: 'token.approve', message: `Lets ${short(op === 4 ? a[1] : a[2])} spend tokens from ${short(a[0])}` });
+            else if (op === 6 && a[1] === wallet)
+                risky.push({ instruction: 'token.setAuthority', message: `Changes an authority on ${short(a[0])}, which the wallet controls` });
+            else if (op === 9 && a[2] === wallet && a[1] !== wallet)
+                risky.push({ instruction: 'token.closeAccount', message: `Closes ${short(a[0])} and sends its lamports (all wrapped SOL) to ${short(a[1])}` });
+        }
+    }
+    // resolve token destinations to owners (and mint/decimals for plain `transfer`)
+    const { PublicKey: PK } = connection ? await import('@solana/web3.js') : { PublicKey: undefined };
+    for (const t of pendingTokens) {
+        let owner, mint = t.mint, decimals = t.decimals;
+        const c = created.get(t.account);
+        if (c) {
+            owner = c.owner;
+            mint ??= c.mint;
+        }
+        if ((!owner || decimals === undefined) && connection && PK) {
+            const info = await connection.getParsedAccountInfo(new PK(t.account));
+            const parsed = info.value?.data?.parsed?.info;
+            owner ??= parsed?.owner;
+            mint ??= parsed?.mint;
+            decimals ??= parsed?.tokenAmount?.decimals;
+            if (decimals === undefined && mint) {
+                const m = await connection.getParsedAccountInfo(new PK(mint));
+                decimals = m.value?.data?.parsed?.info?.decimals;
+            }
+        }
+        if (!owner)
+            notes.push(`could not resolve the owner of token account ${t.account}; scored as-is`);
+        outflows.push({ kind: 'token', from: t.authority, to: owner ?? t.account, toAccount: t.account, amount: decimals === undefined ? t.raw : t.raw / 10 ** decimals, mint, decimalsKnown: decimals !== undefined, instruction: t.instruction });
+    }
+    const all = [...programs];
+    const unknownPrograms = all.filter((p) => !INERT.has(p) && !KNOWN_PROGRAMS[p]);
+    const valuePrograms = all.filter((p) => !INERT.has(p) && KNOWN_PROGRAMS[p]).map((p) => KNOWN_PROGRAMS[p]);
+    for (const p of all)
+        if (!INERT.has(p))
+            notes.push(`calls ${KNOWN_PROGRAMS[p] ?? p}: value moved inside this program is not decoded`);
+    // only value that leaves the guarded wallet counts; transfers between other parties in the same transaction do not
+    const mine = outflows.filter((o) => o.from === wallet && o.to !== wallet && o.amount > 0);
+    if (mine.length < outflows.filter((o) => o.amount > 0).length)
+        notes.push('some transfers in this transaction are not from the guarded wallet and were not counted');
+    return { payer, wallet, outflows: mine, programs: all, unknownPrograms, valuePrograms, risky, notes };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,4 @@
+export declare function runMcp(opts?: {
+    apiUrl?: string;
+    apiKey?: string;
+}): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,103 @@
+// MCP server over stdio (newline-delimited JSON-RPC 2.0), no extra dependencies.
+// Start with `npx -y veralayer mcp`; add to Claude Desktop / Cursor as a stdio server.
+// Tools: vera_check (score an address) and vera_guard_payment (full guard decision for a planned SOL payment).
+import { createInterface } from 'node:readline';
+import { Vera } from './client.js';
+import { VeraGuard } from './guard.js';
+const VERSION = '0.2.0';
+const PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const TOOLS = [
+    {
+        name: 'vera_check',
+        title: 'Vera trust check',
+        description: 'Score a Solana address before paying it. Returns a 0-100 trust score, a tier (high/medium/low/unknown), the reasons, and whether Vera\'s signed result verified. A score is a risk signal, not a guarantee.',
+        inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Solana address (base58)' } }, required: ['address'] },
+    },
+    {
+        name: 'vera_guard_payment',
+        title: 'Vera payment guard',
+        description: 'Decide whether a planned SOL payment should go ahead under a spending policy. Returns allow, review or block with the rule that fired. Call this before sending funds.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                to: { type: 'string', description: 'Recipient Solana address' },
+                amount_sol: { type: 'number', description: 'Amount in SOL' },
+                min_tier: { type: 'string', enum: ['high', 'medium', 'low'], description: 'Minimum recipient tier (default medium)' },
+                max_sol_per_tx: { type: 'number', description: 'Optional cap for this payment' },
+            },
+            required: ['to', 'amount_sol'],
+        },
+    },
+];
+export async function runMcp(opts = {}) {
+    const vera = new Vera({ ...opts, issuer: process.env.VERA_ISSUER });
+    const send = (msg) => process.stdout.write(JSON.stringify(msg) + '\n');
+    const text = (t, structured, isError = false) => ({ content: [{ type: 'text', text: t }], ...(structured ? { structuredContent: structured } : {}), ...(isError ? { isError } : {}) });
+    async function call(name, args) {
+        try {
+            if (name === 'vera_check') {
+                const address = String(args.address ?? '').trim();
+                const r = await vera.check(address);
+                const v = await vera.verify(r);
+                const a = r.attestation;
+                const lines = [
+                    `${a.score ?? 'n/a'}/100 · ${a.tier.toUpperCase()} · ${address}`,
+                    ...(r.summary ? [r.summary] : []),
+                    ...a.reasons.map((x) => `- [${x.kind}] ${x.text}`),
+                    `Signature ${v.valid ? 'verified' : 'INVALID'} · attestation ${r.id}`,
+                ];
+                return text(lines.join('\n'), { score: a.score, tier: a.tier, reasons: a.reasons, verified: v.valid, attestation_id: r.id });
+            }
+            if (name === 'vera_guard_payment') {
+                const policy = {
+                    ...(args.min_tier ? { minTier: args.min_tier } : {}),
+                    ...(typeof args.max_sol_per_tx === 'number' ? { maxSolPerTx: args.max_sol_per_tx } : {}),
+                };
+                const amount = Number(args.amount_sol);
+                if (!Number.isFinite(amount) || amount < 0)
+                    return text(`Invalid amount_sol: ${String(args.amount_sol)}`, undefined, true);
+                const d = await new VeraGuard({ vera, policy }).evaluatePayment({ to: String(args.to), amountSol: amount });
+                const lines = [`${d.action.toUpperCase()}: ${args.amount_sol} SOL to ${args.to}`, ...d.findings.map((f) => `- ${f.action}: ${f.message}`)];
+                if (!d.findings.length)
+                    lines.push('- no policy rule fired');
+                return text(lines.join('\n'), { action: d.action, findings: d.findings });
+            }
+            return null;
+        }
+        catch (e) {
+            return text(`Vera failed: ${e.message}`, undefined, true);
+        }
+    }
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', async (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+        }
+        const { id, method, params } = msg;
+        if (id === undefined)
+            return; // notifications (e.g. notifications/initialized) need no reply
+        if (typeof method !== 'string')
+            return send({ jsonrpc: '2.0', id, error: { code: -32600, message: 'Invalid request' } });
+        const reply = (result) => send({ jsonrpc: '2.0', id, result });
+        switch (method) {
+            case 'initialize':
+                return reply({ protocolVersion: PROTOCOLS.includes(params?.protocolVersion) ? params?.protocolVersion : PROTOCOLS[0], capabilities: { tools: {} }, serverInfo: { name: 'veralayer', version: VERSION } });
+            case 'ping':
+                return reply({});
+            case 'tools/list':
+                return reply({ tools: TOOLS });
+            case 'tools/call': {
+                const res = await call(String(params?.name), params?.arguments ?? {});
+                return res ? reply(res) : send({ jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${String(params?.name)}` } });
+            }
+            default:
+                return send({ jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } });
+        }
+    });
+}

package/dist/policy.d.ts

@@ -0,0 +1,104 @@
+import type { Tier } from './client.js';
+export type Action = 'allow' | 'review' | 'block';
+export type Policy = {
+    /** Recipients below this tier are blocked. Default 'medium'. */
+    minTier?: Exclude<Tier, 'unknown'>;
+    /** Max SOL one recipient may receive in one transaction, per tier. Default high: no cap, medium: 5, low: 0. Unknown recipients are governed by onUnknown unless you set a cap here. */
+    tierLimitsSol?: Partial<Record<Tier, number>>;
+    /** Max total SOL leaving the wallet in one transaction. */
+    maxSolPerTx?: number;
+    /** Max total SOL per UTC day, tracked by the guard's ledger. */
+    dailyLimitSol?: number;
+    /** Per-mint caps for SPL tokens, in UI units (e.g. { EPjF…Dt1v: 500 } for 500 USDC per transaction). */
+    tokenLimits?: Record<string, number>;
+    /** Addresses that skip scoring (your own treasury, known vendors). */
+    allow?: string[];
+    /** Addresses that are always blocked. */
+    deny?: string[];
+    /** Recipients Vera cannot score (no history). Default 'review'. */
+    onUnknown?: Action;
+    /** The check failed, its signature did not verify, or it was for another address. Default 'block'. */
+    onCheckError?: Exclude<Action, 'allow'>;
+    /** Transactions that call programs outside the well-known list. Default 'review'. */
+    unknownPrograms?: Action;
+    /** Well-known programs that can move value the guard does not decode (swaps, lending). Default 'review'. */
+    knownPrograms?: Action;
+    /** Instructions that hand over control of the wallet or its tokens (approve, setAuthority, closeAccount to someone else, assign). Default 'block'. */
+    riskyInstructions?: Action;
+};
+export declare const DEFAULT_POLICY: {
+    minTier: "medium";
+    tierLimitsSol: Partial<Record<Tier, number>>;
+    allow: string[];
+    deny: string[];
+    onUnknown: Action;
+    onCheckError: Exclude<Action, "allow">;
+    unknownPrograms: Action;
+    knownPrograms: Action;
+    riskyInstructions: Action;
+};
+/** One movement of value out of the guarded wallet. */
+export type Outflow = {
+    kind: 'sol' | 'token';
+    /** The wallet that ends up owning the funds (token accounts are resolved to their owner). */
+    to: string;
+    /** The account that is credited: same as `to` for SOL, the token account for SPL. */
+    toAccount: string;
+    /** SOL for kind 'sol'; UI units for tokens (raw units when decimals are unknown). */
+    amount: number;
+    mint?: string;
+    /** false when token decimals could not be resolved, so `amount` is in raw units. */
+    decimalsKnown?: boolean;
+    /** The wallet the value leaves (the signer of the transfer). */
+    from?: string;
+    instruction: string;
+};
+/** An instruction that changes who controls the wallet or its tokens. */
+export type RiskyInstruction = {
+    instruction: string;
+    message: string;
+};
+/** What the guard learned about one recipient. */
+export type RecipientCheck = {
+    address: string;
+    ok: true;
+    score: number | null;
+    tier: Tier;
+    reasons: {
+        kind: string;
+        text: string;
+    }[];
+    attestationId: string;
+    verified: boolean;
+    expired: boolean;
+} | {
+    address: string;
+    ok: false;
+    error: string;
+};
+export type Finding = {
+    action: Action;
+    code: string;
+    message: string;
+    address?: string;
+};
+export type Decision = {
+    action: Action;
+    findings: Finding[];
+    outflows: Outflow[];
+    recipients: RecipientCheck[];
+    totalSol: number;
+    unknownPrograms: string[];
+};
+/** Throws on a policy that would silently weaken checks (typos in tiers or actions, non-numeric limits). */
+export declare function validatePolicy(p?: Policy): void;
+export declare function evaluatePolicy(input: {
+    outflows: Outflow[];
+    recipients: RecipientCheck[];
+    unknownPrograms?: string[];
+    /** names of well-known programs that may move value the guard does not decode */
+    valuePrograms?: string[];
+    risky?: RiskyInstruction[];
+    spentTodaySol?: number;
+    policy?: Policy;
+}): Decision;

package/dist/policy.js

@@ -0,0 +1,112 @@
+export const DEFAULT_POLICY = {
+    minTier: 'medium',
+    tierLimitsSol: { high: Infinity, medium: 5, low: 0 },
+    allow: [],
+    deny: [],
+    onUnknown: 'review',
+    onCheckError: 'block',
+    unknownPrograms: 'review',
+    knownPrograms: 'review',
+    riskyInstructions: 'block',
+};
+const RANK = { unknown: 0, low: 1, medium: 2, high: 3 };
+const ACTIONS = ['allow', 'review', 'block'];
+const worst = (a, b) => (a === 'block' || b === 'block' ? 'block' : a === 'review' || b === 'review' ? 'review' : 'allow');
+const fmt = (n) => (Number.isInteger(n) ? String(n) : n.toFixed(4).replace(/0+$/, ''));
+const short = (a) => `${a.slice(0, 4)}…${a.slice(-4)}`;
+/** Throws on a policy that would silently weaken checks (typos in tiers or actions, non-numeric limits). */
+export function validatePolicy(p = {}) {
+    if (p.minTier !== undefined && !['high', 'medium', 'low'].includes(p.minTier))
+        throw new Error(`invalid minTier: ${String(p.minTier)}`);
+    for (const k of ['onUnknown', 'onCheckError', 'unknownPrograms', 'knownPrograms', 'riskyInstructions']) {
+        if (p[k] !== undefined && !ACTIONS.includes(p[k]))
+            throw new Error(`invalid ${k}: ${String(p[k])}`);
+    }
+    if (p.onCheckError === 'allow')
+        throw new Error('onCheckError cannot be allow');
+    const nums = [['maxSolPerTx', p.maxSolPerTx], ['dailyLimitSol', p.dailyLimitSol],
+        ...Object.entries(p.tierLimitsSol ?? {}).map(([k, v]) => [`tierLimitsSol.${k}`, v]),
+        ...Object.entries(p.tokenLimits ?? {}).map(([k, v]) => [`tokenLimits.${k}`, v])];
+    for (const [k, v] of nums)
+        if (v !== undefined && (typeof v !== 'number' || Number.isNaN(v) || v < 0))
+            throw new Error(`invalid ${k}: ${String(v)}`);
+    for (const k of Object.keys(p.tierLimitsSol ?? {}))
+        if (!(k in RANK))
+            throw new Error(`invalid tier in tierLimitsSol: ${k}`);
+}
+export function evaluatePolicy(input) {
+    validatePolicy(input.policy);
+    const p = { ...DEFAULT_POLICY, ...input.policy, tierLimitsSol: { ...DEFAULT_POLICY.tierLimitsSol, ...input.policy?.tierLimitsSol } };
+    const allow = new Set(p.allow), deny = new Set(p.deny);
+    const findings = [];
+    const add = (action, code, message, address) => findings.push({ action, code, message, ...(address ? { address } : {}) });
+    // malformed amounts never pass and never count toward limits
+    const good = (o) => typeof o.amount === 'number' && Number.isFinite(o.amount) && o.amount >= 0;
+    for (const o of input.outflows)
+        if (!good(o))
+            add('block', 'bad_amount', `Invalid amount ${String(o.amount)} to ${short(String(o.to))}`, o.to);
+    const outflows = input.outflows.filter(good);
+    const totalSol = outflows.filter((o) => o.kind === 'sol').reduce((s, o) => s + o.amount, 0);
+    const solTo = new Map();
+    for (const o of outflows)
+        if (o.kind === 'sol')
+            solTo.set(o.to, (solTo.get(o.to) || 0) + o.amount);
+    const byAddr = new Map(input.recipients.map((r) => [r.address, r]));
+    for (const to of new Set(outflows.map((o) => o.to))) {
+        const s = short(to);
+        if (deny.has(to)) {
+            add('block', 'denylisted', `${s} is on your deny list`, to);
+            continue;
+        }
+        if (allow.has(to))
+            continue;
+        const r = byAddr.get(to);
+        if (!r || !r.ok) {
+            add(p.onCheckError, 'check_failed', `Could not check ${s}${r && !r.ok ? `: ${r.error}` : ''}`, to);
+            continue;
+        }
+        if (!(r.tier in RANK)) {
+            add(p.onCheckError, 'bad_tier', `Vera returned an unexpected tier for ${s}`, to);
+            continue;
+        }
+        if (!r.verified) {
+            add(p.onCheckError, 'bad_signature', `Vera's signature for ${s} did not verify`, to);
+            continue;
+        }
+        if (r.expired)
+            add('review', 'stale_check', `Vera's result for ${s} has expired`, to);
+        if (r.tier === 'unknown') {
+            add(p.onUnknown, 'unknown_recipient', `${s} has no history Vera can score`, to);
+        }
+        else if (RANK[r.tier] < RANK[p.minTier]) {
+            add('block', 'tier_below_minimum', `${s} is ${r.tier} trust (${r.score}/100), below your minimum of ${p.minTier}: ${r.reasons[0]?.text ?? ''}`.trim(), to);
+        }
+        const cap = p.tierLimitsSol[r.tier] ?? Infinity;
+        const sent = solTo.get(to) || 0;
+        if (sent > cap)
+            add(cap === 0 ? 'block' : 'review', 'tier_limit', `${fmt(sent)} SOL to ${s} exceeds the ${fmt(cap)} SOL limit for ${r.tier} trust`, to);
+    }
+    for (const o of outflows) {
+        if (o.kind !== 'token')
+            continue;
+        if (o.decimalsKnown === false) {
+            add('review', 'unknown_decimals', `Could not read token decimals for ${short(o.toAccount)}; amount not compared to limits`, o.to);
+            continue;
+        }
+        if (o.mint && p.tokenLimits && o.mint in p.tokenLimits && o.amount > p.tokenLimits[o.mint])
+            add('review', 'token_limit', `${fmt(o.amount)} of ${o.mint.slice(0, 4)}… exceeds your ${fmt(p.tokenLimits[o.mint])} per-transaction cap`, o.to);
+    }
+    if (p.maxSolPerTx !== undefined && totalSol > p.maxSolPerTx)
+        add('block', 'tx_limit', `${fmt(totalSol)} SOL in one transaction exceeds your ${fmt(p.maxSolPerTx)} SOL cap`);
+    if (p.dailyLimitSol !== undefined && (input.spentTodaySol ?? 0) + totalSol > p.dailyLimitSol)
+        add('block', 'daily_limit', `This would bring today's spend to ${fmt((input.spentTodaySol ?? 0) + totalSol)} SOL, over your ${fmt(p.dailyLimitSol)} SOL daily limit`);
+    for (const r of input.risky ?? [])
+        if (p.riskyInstructions !== 'allow')
+            add(p.riskyInstructions, 'risky_instruction', r.message);
+    if (input.unknownPrograms?.length && p.unknownPrograms !== 'allow')
+        add(p.unknownPrograms, 'unknown_program', `Calls ${input.unknownPrograms.length} program${input.unknownPrograms.length > 1 ? 's' : ''} outside the well-known list: ${input.unknownPrograms.map((x) => x.slice(0, 4) + '…').join(', ')}`);
+    if (input.valuePrograms?.length && p.knownPrograms !== 'allow')
+        add(p.knownPrograms, 'opaque_value', `Value may move inside ${input.valuePrograms.join(', ')}, which the guard does not decode`);
+    const action = findings.reduce((a, f) => worst(a, f.action), 'allow');
+    return { action, findings, outflows, recipients: input.recipients, totalSol, unknownPrograms: input.unknownPrograms ?? [] };
+}

package/dist/programs.d.ts

@@ -0,0 +1 @@
+export declare const KNOWN_PROGRAMS: Record<string, string>;

package/dist/programs.js

@@ -0,0 +1,37 @@
+// Well-known, widely used Solana programs. Calls to anything else count as "unverified" in the score.
+// This is an allowlist of popularity, not an audit: a known program can still be used in a harmful way.
+export const KNOWN_PROGRAMS = {
+    '11111111111111111111111111111111': 'System',
+    TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA: 'SPL Token',
+    TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb: 'Token-2022',
+    ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL: 'Associated Token Account',
+    ComputeBudget111111111111111111111111111111: 'Compute Budget',
+    MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr: 'Memo',
+    Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo: 'Memo v1',
+    Stake11111111111111111111111111111111111111: 'Stake',
+    Vote111111111111111111111111111111111111111: 'Vote',
+    AddressLookupTab1e1111111111111111111111111: 'Address Lookup Table',
+    metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s: 'Metaplex Token Metadata',
+    BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY: 'Metaplex Bubblegum',
+    cmtDvXumGCrqC1Age74AVPhSRVXJMd8PJS91L8KbNCK: 'Account Compression',
+    noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV: 'Noop',
+    JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4: 'Jupiter',
+    '6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P': 'pump.fun',
+    pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA: 'PumpSwap',
+    '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8': 'Raydium AMM',
+    CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK: 'Raydium CLMM',
+    CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C: 'Raydium CPMM',
+    whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc: 'Orca Whirlpools',
+    LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo: 'Meteora DLMM',
+    Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB: 'Meteora Pools',
+    dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN: 'Meteora DBC',
+    MarBmsSgKXdrN1egZf5sqe1TMai9K1rChYNDJgjq7aD: 'Marinade',
+    SPoo1Ku8WFXoNDMHPsrGSTSG1Y47rzgn41SLUNakuHy: 'Stake Pool',
+    PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY: 'Phoenix',
+    dRiftyHA39MWEi3m9aunc5MzRF1JYuBsbn6VPcn33UH: 'Drift',
+    KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD: 'Kamino Lend',
+    So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo: 'Solend',
+    TSWAPaqyCSx2KABk68Shruf4rp7CxcNi8hAsbdwmHbN: 'Tensor',
+    M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K: 'Magic Eden',
+    SQDS4ep65T869zMMBKyuUq6aD6EgTu8psMjkvj52pCf: 'Squads',
+};