veralayer 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VeraLayer
+
+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/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# veralayer
+
+A payment guard for AI agents on Solana. It sits between your agent's wallet and the network and checks every outgoing transaction:
+
+- **Decodes the transaction.** It finds where value goes: SOL transfers, SPL and Token-2022 transfers (each token account is resolved to the wallet that owns it), v0 lookup tables, and every program called.
+- **Scores each recipient.** Every recipient is checked with [Vera](https://veraagent.io). The score is built from on-chain history, and every reason cites the fact behind it.
+- **Verifies the signature.** Each result is signed by Vera. The guard verifies that signature locally against Vera's published ed25519 key, so a tampered score is rejected.
+- **Applies your policy.** It returns `allow`, `review` or `block`, with a finding for each rule that fired. Only allowed transactions are signed and sent.
+
+```bash
+npm install veralayer @solana/web3.js
+```
+
+## Guard a wallet
+
+```ts
+import { Connection } from '@solana/web3.js';
+import { VeraGuard, VeraBlockedError } from 'veralayer';
+
+const guard = new VeraGuard({
+  connection: new Connection(process.env.RPC_URL!),
+  policy: {
+    minTier: 'medium',                              // block low-trust recipients
+    tierLimitsSol: { high: 50, medium: 5 },         // max SOL per recipient per tx, by tier
+    dailyLimitSol: 20,                              // across all transactions today
+    tokenLimits: { EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: 500 }, // 500 USDC per tx
+    deny: ['<known bad address>'],
+    allow: ['<your treasury>'],
+  },
+  onReview: async (decision) => askHumanInTelegram(decision), // optional; without it, review = block
+});
+
+try {
+  const { signature, decision } = await guard.sendTransaction(tx, [agentKeypair]);
+} catch (e) {
+  if (e instanceof VeraBlockedError) console.log(e.decision.findings); // why it was stopped
+}
+```
+
+## Decide before you build a transaction
+
+```ts
+const d = await guard.evaluatePayment({ to: seller, amountSol: 1.5 });
+if (d.action !== 'allow') return refuse(d.findings[0].message);
+```
+
+## Just score an address
+
+```ts
+import { Vera } from 'veralayer';
+const vera = new Vera();
+const r = await vera.check(address);   // { attestation: { score, tier, reasons, ... }, signature, summary }
+await vera.verify(r);                  // { valid: true, expired: false }, checked offline
+```
+
+## Use it from Claude, Cursor or any MCP client
+
+```json
+{ "mcpServers": { "vera": { "command": "npx", "args": ["-y", "veralayer", "mcp"] } } }
+```
+
+Tools: `vera_check(address)` and `vera_guard_payment(to, amount_sol)`.
+
+## Solana Agent Kit
+
+```ts
+import { createVeraPlugin } from 'veralayer/agent-kit';
+agent.use(createVeraPlugin({ policy: { minTier: 'medium' } }));
+```
+
+Full docs: https://veraagent.io/docs
+
+## CLI
+
+```bash
+npx veralayer check <address>
+npx veralayer pay <address> 2.5 --min-tier medium --daily 20
+npx veralayer inspect <base64 transaction> --rpc <url>
+```
+
+## Policy reference
+
+| Field | Default | Effect |
+|---|---|---|
+| `minTier` | `'medium'` | Recipients below this tier are blocked. |
+| `tierLimitsSol` | `{ high: ∞, medium: 5, low: 0 }` | Max SOL to one recipient per transaction. Over the limit → `review`; a limit of 0 → `block`. |
+| `maxSolPerTx` | none | Total SOL per transaction → `block`. |
+| `dailyLimitSol` | none | Total SOL per UTC day (ledger) → `block`. |
+| `tokenLimits` | none | Per-mint cap in UI units → `review`. |
+| `allow` / `deny` | `[]` | Skip scoring / always block. |
+| `onUnknown` | `'review'` | Recipients with no history. |
+| `onCheckError` | `'block'` | API failure, bad signature, or a result for another address. |
+| `unknownPrograms` | `'review'` | Programs outside the well-known list. |
+| `knownPrograms` | `'review'` | Well-known programs that move value the guard doesn't decode (swaps). Set `'allow'` if your agent swaps. |
+| `riskyInstructions` | `'block'` | `approve`, `setAuthority`, `closeAccount` to someone else, or `assign`, signed by the wallet. |
+
+A policy with a typo throws when the guard is created, rather than silently weakening a check.
+
+## Trust
+
+- **Pinned key.** Results must be signed by Vera's production key, which ships as `VERA_ISSUER`. For a self-hosted Vera, pass `vera: { apiUrl, issuer }`.
+- **Address check.** A result for a different address than the one requested is rejected.
+- **Bad amounts.** NaN, negative and infinite amounts block.
+- **Daily limits.** Spend is reserved before sending and released if the send fails. Concurrent sends are serialised.
+- **Relayers.** If a relayer pays fees, pass `wallet` so that only the agent's own transfers count.
+
+## What it does not do (yet)
+
+- **Value inside other programs.** Value moved inside swaps and other CPIs is not decoded. Those programs are listed, and unknown ones trigger `review`.
+- **On-chain anchoring.** Vera's results are signed but not yet anchored on-chain.
+- **Guarantees.** A score reads history, not intent. It is a risk signal, not a guarantee.
+
+MIT · by [VeraLayer](https://veralayer.io)

package/dist/agent-kit.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { Policy } from './policy.js';
+type Action = {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        input: Record<string, unknown>;
+        output: Record<string, unknown>;
+        explanation: string;
+    }[][];
+    schema: z.ZodTypeAny;
+    handler: (agent: unknown, input: Record<string, any>) => Promise<Record<string, any>>;
+};
+type Plugin = {
+    name: string;
+    methods: Record<string, any>;
+    actions: Action[];
+    initialize(agent: unknown): void;
+};
+export declare function createVeraPlugin(opts?: {
+    apiUrl?: string;
+    apiKey?: string;
+    issuer?: string;
+    policy?: Policy;
+}): Plugin;
+export default createVeraPlugin;

package/dist/agent-kit.js

@@ -0,0 +1,65 @@
+// Solana Agent Kit v2 plugin.
+//
+//   import { SolanaAgentKit } from 'solana-agent-kit';
+//   import { createVeraPlugin } from 'veralayer/agent-kit';
+//   const agent = new SolanaAgentKit(wallet, rpcUrl, {}).use(createVeraPlugin({ policy: { minTier: 'medium' } }));
+//   await agent.methods.veraGuardPayment(to, 1.5);
+//
+// Types are structural, so this file needs zod but not solana-agent-kit itself.
+import { z } from 'zod';
+import { Vera } from './client.js';
+import { VeraGuard } from './guard.js';
+export function createVeraPlugin(opts = {}) {
+    const vera = new Vera(opts);
+    const guard = new VeraGuard({ vera, policy: opts.policy });
+    const check = async (address) => {
+        const r = await vera.check(address);
+        const v = await vera.verify(r);
+        const a = r.attestation;
+        return { address, score: a.score, tier: a.tier, reasons: a.reasons, summary: r.summary, attestation_id: r.id, signature_valid: v.valid };
+    };
+    const actions = [
+        {
+            name: 'VERA_TRUST_CHECK',
+            similes: ['check counterparty', 'is this address safe to pay', 'trust score', 'vet wallet before payment'],
+            description: 'Score a Solana address with Vera before sending it funds: 0-100 score, tier, reasons, and whether the signed result verified.',
+            examples: [[{ input: { address: '<counterparty address>' }, output: { status: 'success', score: 55, tier: 'medium' }, explanation: 'Illustrative: score a recipient before paying it' }]],
+            schema: z.object({ address: z.string().min(32).max(44) }),
+            handler: async (_agent, input) => {
+                try {
+                    return { status: 'success', ...(await check(String(input.address))) };
+                }
+                catch (e) {
+                    return { status: 'error', message: e.message };
+                }
+            },
+        },
+        {
+            name: 'VERA_GUARD_PAYMENT',
+            similes: ['should I pay', 'guard payment', 'check payment against policy'],
+            description: 'Decide whether a planned SOL payment may go ahead under the configured spending policy: allow, review or block, with the rule that fired.',
+            examples: [[{ input: { to: '<recipient>', amountSol: 1 }, output: { status: 'success', action: 'allow', findings: [] }, explanation: 'Illustrative: gate a 1 SOL payment' }]],
+            schema: z.object({ to: z.string().min(32).max(44), amountSol: z.number().positive() }),
+            handler: async (_agent, input) => {
+                try {
+                    const d = await guard.evaluatePayment({ to: String(input.to), amountSol: Number(input.amountSol) });
+                    return { status: 'success', action: d.action, findings: d.findings };
+                }
+                catch (e) {
+                    return { status: 'error', message: e.message };
+                }
+            },
+        },
+    ];
+    return {
+        name: 'vera',
+        methods: {
+            veraCheck: check,
+            veraRequire: (address, minTier = 'medium') => vera.require(address, minTier),
+            veraGuardPayment: (to, amountSol) => guard.evaluatePayment({ to, amountSol }),
+        },
+        actions,
+        initialize() { },
+    };
+}
+export default createVeraPlugin;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// npx veralayer check <address>            score one address
+// npx veralayer pay <address> <sol>        what the guard would decide for a SOL payment
+// npx veralayer inspect <base64 tx>        decode a transaction and decide on it
+// options: --min-tier high|medium|low  --daily <sol>  --max-tx <sol>  --json  --api <url>  --rpc <url>
+import { Vera } from './client.js';
+import { VeraGuard } from './guard.js';
+const args = process.argv.slice(2);
+// supports --name value and --name=value
+const flags = new Map();
+const pos = [];
+for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') {
+        flags.set('json', '1');
+        continue;
+    }
+    if (a.startsWith('--')) {
+        const [k, v] = a.slice(2).split(/=(.*)/s);
+        if (v !== undefined)
+            flags.set(k, v);
+        else
+            flags.set(k, args[++i] ?? '');
+        continue;
+    }
+    pos.push(a);
+}
+const flag = (name) => flags.get(name);
+const json = flags.has('json');
+const [cmd, a1, a2] = pos;
+const num = (name) => {
+    const v = flag(name);
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n < 0) {
+        console.error(`--${name} must be a non-negative number`);
+        process.exit(1);
+    }
+    return n;
+};
+const minTier = flag('min-tier');
+if (minTier !== undefined && !['high', 'medium', 'low'].includes(minTier)) {
+    console.error('--min-tier must be high, medium or low');
+    process.exit(1);
+}
+const daily = num('daily'), maxTx = num('max-tx');
+const policy = {
+    ...(minTier ? { minTier: minTier } : {}),
+    ...(daily !== undefined ? { dailyLimitSol: daily } : {}),
+    ...(maxTx !== undefined ? { maxSolPerTx: maxTx } : {}),
+};
+const vera = new Vera({ apiUrl: flag('api') ?? process.env.VERA_API_URL, apiKey: process.env.VERA_API_KEY, issuer: process.env.VERA_ISSUER });
+const c = process.stdout.isTTY ? { r: '\x1b[31m', g: '\x1b[32m', y: '\x1b[33m', d: '\x1b[2m', b: '\x1b[1m', x: '\x1b[0m' } : { r: '', g: '', y: '', d: '', b: '', x: '' };
+const tierColor = (t) => (t === 'high' ? c.g : t === 'medium' ? c.y : t === 'low' ? c.r : c.d);
+const glyph = (k) => (k === 'ok' ? `${c.g}✓${c.x}` : k === 'warn' ? `${c.y}!${c.x}` : k === 'bad' ? `${c.r}×${c.x}` : `${c.d}i${c.x}`);
+function printDecision(d) {
+    const col = d.action === 'allow' ? c.g : d.action === 'review' ? c.y : c.r;
+    console.log(`\n${c.b}${col}${d.action.toUpperCase()}${c.x}  ${d.totalSol ? `${d.totalSol} SOL out` : ''}`);
+    for (const o of d.outflows)
+        console.log(`  ${c.d}→${c.x} ${o.amount} ${o.kind === 'sol' ? 'SOL' : (o.mint ?? 'token').slice(0, 6) + '…'} to ${o.to}`);
+    for (const r of d.recipients) {
+        if (!r.ok) {
+            console.log(`  ${c.r}×${c.x} ${r.address}: ${r.error}`);
+            continue;
+        }
+        console.log(`  ${tierColor(r.tier)}${r.tier.toUpperCase()} ${r.score ?? '—'}${c.x} ${r.address} ${r.verified ? `${c.d}signature ✓${c.x}` : `${c.r}signature ✗${c.x}`}`);
+    }
+    for (const f of d.findings)
+        console.log(`  ${f.action === 'block' ? c.r : c.y}${f.action}${c.x}  ${f.message}`);
+    if (!d.findings.length)
+        console.log(`  ${c.d}no policy findings${c.x}`);
+}
+async function main() {
+    if (cmd === 'mcp') {
+        const { runMcp } = await import('./mcp.js');
+        return runMcp({ apiUrl: flag('api') ?? process.env.VERA_API_URL, apiKey: process.env.VERA_API_KEY });
+    }
+    if (cmd === 'check' && a1) {
+        const r = await vera.check(a1);
+        const v = await vera.verify(r);
+        if (json)
+            return console.log(JSON.stringify({ ...r, verified: v }, null, 2));
+        const a = r.attestation;
+        console.log(`\n${c.b}${tierColor(a.tier)}${a.score ?? '—'}/100 ${a.tier.toUpperCase()}${c.x}  ${a.subject}`);
+        if (r.summary)
+            console.log(`${c.d}${r.summary}${c.x}`);
+        for (const x of a.reasons)
+            console.log(`  ${glyph(x.kind)} ${x.text}`);
+        console.log(`\n${c.d}attestation ${r.id}\nsignature ${v.valid ? 'verified' : 'INVALID'} · ${a.method} · expires ${a.expires_at}${c.x}`);
+        return;
+    }
+    if (cmd === 'pay' && a1 && a2) {
+        if (!Number.isFinite(Number(a2)) || Number(a2) < 0)
+            throw new Error(`invalid amount: ${a2}`);
+        const d = await new VeraGuard({ vera, policy }).evaluatePayment({ to: a1, amountSol: Number(a2) });
+        return json ? console.log(JSON.stringify(d, null, 2)) : printDecision(d);
+    }
+    if (cmd === 'inspect' && a1) {
+        const web3 = await import('@solana/web3.js').catch(() => { throw new Error('inspect needs @solana/web3.js: npm i @solana/web3.js'); });
+        const raw = Buffer.from(a1, 'base64');
+        let tx;
+        try {
+            tx = web3.VersionedTransaction.deserialize(raw);
+        }
+        catch {
+            tx = web3.Transaction.from(raw);
+        }
+        const connection = new web3.Connection(flag('rpc') ?? process.env.SOLANA_RPC_URL ?? 'https://api.mainnet-beta.solana.com', 'confirmed');
+        const d = await new VeraGuard({ vera, policy, connection }).evaluate(tx);
+        return json ? console.log(JSON.stringify(d, null, 2)) : printDecision(d);
+    }
+    console.log(`veralayer: payment guard for AI agents on Solana
+
+  veralayer check <address>          score an address (signed, verified locally)
+  veralayer pay <address> <sol>      decide on a planned SOL payment
+  veralayer inspect <base64 tx>      decode a transaction and decide on it
+  veralayer mcp                      run as an MCP server over stdio
+
+  --min-tier high|medium|low   --daily <sol>   --max-tx <sol>   --json
+  --api <url> (or VERA_API_URL)   --rpc <url> (or SOLANA_RPC_URL)`);
+    process.exitCode = cmd ? 1 : 0;
+}
+main().then(() => { }, (e) => { console.error(`${c.r}error${c.x} ${e.message}`); process.exitCode = 1; });

package/dist/client.d.ts

@@ -0,0 +1,69 @@
+export type Tier = 'high' | 'medium' | 'low' | 'unknown';
+export type Attestation = {
+    v: 1;
+    issuer: string;
+    subject: string;
+    score: number | null;
+    tier: Tier;
+    reasons: {
+        kind: 'ok' | 'warn' | 'bad' | 'info';
+        text: string;
+    }[];
+    features_sha256: string;
+    method: string;
+    issued_at: string;
+    expires_at: string;
+};
+export type CheckResult = {
+    id: string;
+    attestation: Attestation;
+    signature: string;
+    summary: string | null;
+    anchor?: {
+        cluster: string;
+        tx: string;
+    } | null;
+    features?: Record<string, unknown>;
+};
+export type VerifyResult = {
+    valid: boolean;
+    expired: boolean;
+    reason?: string;
+};
+export declare class VeraError extends Error {
+    status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** Vera's production signing key. Results signed by anything else are rejected unless you pass your own `issuer`. */
+export declare const VERA_ISSUER = "4VyCQLEb8eVmPYXDUwYkEpCMhXFBRshUiKHHuKTfPDFQ";
+export declare const DEFAULT_API_URL = "https://veraagent.io";
+export declare function canonical(v: unknown): string;
+/** Verify an attestation offline. Pass the trusted Vera issuer key (from /.well-known/vera.json) to pin it. */
+export declare function verifyAttestation(attestation: Attestation, signature: string, trustedIssuer?: string): VerifyResult;
+export declare class Vera {
+    private apiUrl;
+    private apiKey?;
+    private issuer?;
+    private timeoutMs;
+    /**
+     * @param opts.issuer  the key results must be signed with. Defaults to Vera's production key (VERA_ISSUER).
+     *                     Pass your own for a self-hosted Vera, or 'fetch' to trust /.well-known/vera.json on apiUrl.
+     */
+    constructor(opts?: {
+        apiUrl?: string;
+        apiKey?: string;
+        issuer?: string;
+        timeoutMs?: number;
+    });
+    private req;
+    /** Score a counterparty. Returns score, tier, reasons and a signed attestation. Throws if the result is for a different address. */
+    check(address: string, opts?: {
+        fresh?: boolean;
+    }): Promise<CheckResult>;
+    /** The key results must be signed with: pinned (default) or fetched once from /.well-known/vera.json. */
+    getIssuer(): Promise<string>;
+    /** Verify a check result locally against the trusted issuer key. */
+    verify(result: Pick<CheckResult, 'attestation' | 'signature'>): Promise<VerifyResult>;
+    /** Convenience gate: throws unless the result verifies, has not expired and meets the minimum tier. */
+    require(address: string, minTier?: Exclude<Tier, 'unknown'>): Promise<CheckResult>;
+}

package/dist/client.js

@@ -0,0 +1,106 @@
+// Vera API client: score an address and verify the signed result locally against Vera's published key.
+//
+//   import { Vera } from 'veralayer';
+//   const vera = new Vera();   // hosted API, results must be signed with VERA_ISSUER
+//   const check = await vera.check(counterparty);
+//   if (!(await vera.verify(check)).valid) throw new Error('bad attestation');
+//   if (check.attestation.tier === 'low') throw new Error(check.attestation.reasons[0].text);
+import { ed25519 } from '@noble/curves/ed25519.js';
+import bs58 from 'bs58';
+export class VeraError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Vera's production signing key. Results signed by anything else are rejected unless you pass your own `issuer`. */
+export const VERA_ISSUER = '4VyCQLEb8eVmPYXDUwYkEpCMhXFBRshUiKHHuKTfPDFQ';
+export const DEFAULT_API_URL = 'https://veraagent.io';
+const TIERS = ['high', 'medium', 'low', 'unknown'];
+// key-sorted JSON: must match the engine byte for byte
+export function canonical(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonical).join(',')}]`;
+    if (v && typeof v === 'object')
+        return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(',')}}`;
+    return JSON.stringify(v) ?? 'null';
+}
+/** Verify an attestation offline. Pass the trusted Vera issuer key (from /.well-known/vera.json) to pin it. */
+export function verifyAttestation(attestation, signature, trustedIssuer) {
+    const exp = Date.parse(attestation?.expires_at);
+    const expired = !(exp > Date.now()); // an unparseable date counts as expired
+    if (!attestation || typeof attestation.issuer !== 'string')
+        return { valid: false, expired, reason: 'malformed attestation' };
+    if (trustedIssuer && attestation.issuer !== trustedIssuer)
+        return { valid: false, expired, reason: 'issuer is not the trusted Vera key' };
+    if (!TIERS.includes(attestation.tier))
+        return { valid: false, expired, reason: `unexpected tier ${String(attestation.tier)}` };
+    try {
+        const ok = ed25519.verify(bs58.decode(signature), new TextEncoder().encode(canonical(attestation)), bs58.decode(attestation.issuer));
+        return ok ? { valid: true, expired } : { valid: false, expired, reason: 'signature does not match' };
+    }
+    catch {
+        return { valid: false, expired, reason: 'malformed signature or issuer' };
+    }
+}
+export class Vera {
+    apiUrl;
+    apiKey;
+    issuer;
+    timeoutMs;
+    /**
+     * @param opts.issuer  the key results must be signed with. Defaults to Vera's production key (VERA_ISSUER).
+     *                     Pass your own for a self-hosted Vera, or 'fetch' to trust /.well-known/vera.json on apiUrl.
+     */
+    constructor(opts = {}) {
+        this.apiUrl = (opts.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, '');
+        this.apiKey = opts.apiKey;
+        this.issuer = opts.issuer === 'fetch' ? undefined : (opts.issuer ?? VERA_ISSUER);
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+    }
+    async req(path, init) {
+        let r;
+        try {
+            r = await fetch(this.apiUrl + path, { ...init, signal: AbortSignal.timeout(this.timeoutMs), headers: { 'content-type': 'application/json', ...(this.apiKey ? { 'x-api-key': this.apiKey } : {}), ...init?.headers } });
+        }
+        catch (e) {
+            throw new VeraError(`Vera API unreachable: ${e.message}`);
+        }
+        const j = (await r.json().catch(() => ({})));
+        if (!r.ok)
+            throw new VeraError(j.error || `Vera API error ${r.status}`, r.status);
+        return j;
+    }
+    /** Score a counterparty. Returns score, tier, reasons and a signed attestation. Throws if the result is for a different address. */
+    async check(address, opts = {}) {
+        const r = await this.req('/v1/check', { method: 'POST', body: JSON.stringify({ address, fresh: opts.fresh }) });
+        if (r?.attestation?.subject !== address)
+            throw new VeraError('Vera returned a result for a different address');
+        return r;
+    }
+    /** The key results must be signed with: pinned (default) or fetched once from /.well-known/vera.json. */
+    async getIssuer() {
+        this.issuer ??= (await this.req('/.well-known/vera.json')).issuer;
+        return this.issuer;
+    }
+    /** Verify a check result locally against the trusted issuer key. */
+    async verify(result) {
+        return verifyAttestation(result.attestation, result.signature, await this.getIssuer());
+    }
+    /** Convenience gate: throws unless the result verifies, has not expired and meets the minimum tier. */
+    async require(address, minTier = 'medium') {
+        const rank = { unknown: 0, low: 1, medium: 2, high: 3 };
+        if (!(minTier in rank))
+            throw new VeraError(`invalid minTier: ${minTier}`);
+        const r = await this.check(address);
+        const v = await this.verify(r);
+        if (!v.valid)
+            throw new VeraError(`attestation invalid: ${v.reason}`);
+        if (v.expired)
+            throw new VeraError('attestation expired');
+        if (rank[r.attestation.tier] < rank[minTier])
+            throw new VeraError(`counterparty tier ${r.attestation.tier} is below ${minTier}: ${r.attestation.reasons[0]?.text ?? ''}`);
+        return r;
+    }
+}

package/dist/guard.d.ts

@@ -0,0 +1,71 @@
+import type { Connection, Signer, Transaction, VersionedTransaction, SendOptions } from '@solana/web3.js';
+import { Vera } from './client.js';
+import { type Decision, type Policy, type RecipientCheck } from './policy.js';
+/** Where the guard keeps today's spend. Swap in Redis/DB for multi-process agents. */
+export interface SpendLedger {
+    spentToday(): Promise<number> | number;
+    add(sol: number): Promise<void> | void;
+}
+export declare class MemoryLedger implements SpendLedger {
+    private day;
+    private spent;
+    private roll;
+    spentToday(): number;
+    add(sol: number): void;
+}
+export declare class VeraBlockedError extends Error {
+    decision: Decision;
+    constructor(decision: Decision);
+}
+export declare class VeraReviewRequiredError extends Error {
+    decision: Decision;
+    constructor(decision: Decision);
+}
+export type GuardOptions = {
+    connection?: Connection;
+    /** The wallet being guarded. Default: each transaction's fee payer. Set it when a relayer pays fees for your agent. */
+    wallet?: string;
+    policy?: Policy;
+    vera?: Vera | {
+        apiUrl?: string;
+        apiKey?: string;
+        issuer?: string;
+    };
+    ledger?: SpendLedger;
+    /** Called for 'review' decisions. Return true to send anyway (e.g. after a human approves in Slack/Telegram). Without it, review = block. */
+    onReview?: (decision: Decision) => Promise<boolean> | boolean;
+    /** Called after every decision, for logs and audit trails. */
+    onDecision?: (decision: Decision) => void;
+};
+export declare class VeraGuard {
+    readonly vera: Vera;
+    readonly policy: Policy;
+    private connection?;
+    private wallet?;
+    private ledger;
+    private onReview?;
+    private onDecision?;
+    private lock;
+    constructor(opts?: GuardOptions);
+    /** Score recipients (deduplicated, in parallel) and verify each signed result against Vera's published key. */
+    checkRecipients(addresses: string[]): Promise<RecipientCheck[]>;
+    /** Decide on a planned payment without building a transaction (e.g. before quoting a price to another agent). */
+    evaluatePayment(payment: {
+        to: string;
+        amountSol?: number;
+        token?: {
+            mint: string;
+            amount: number;
+        };
+    }): Promise<Decision>;
+    /** Decode a transaction and decide on it. Does not send anything. */
+    evaluate(tx: Transaction | VersionedTransaction): Promise<Decision>;
+    private decide;
+    /** Throws VeraBlockedError / VeraReviewRequiredError unless the transaction may be sent. */
+    assert(tx: Transaction | VersionedTransaction): Promise<Decision>;
+    /** Evaluate, then sign and send only if allowed. The SOL is reserved in the ledger before sending and released if sending fails. */
+    sendTransaction(tx: Transaction | VersionedTransaction, signers?: Signer[], options?: SendOptions): Promise<{
+        signature: string;
+        decision: Decision;
+    }>;
+}