veralayer 0.1.0 → 0.2.0

package/README.md

@@ -1,84 +1,113 @@
-# 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://vera-agent-psi.vercel.app). 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
-```
-
-## 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, unknown: 0 }` | Max SOL to one recipient in one transaction. Over the limit means `review`; a limit of 0 means `block`. |
-| `maxSolPerTx` | none | Caps the total SOL out per transaction. |
-| `dailyLimitSol` | none | Caps the total SOL out per UTC day, tracked by `ledger`: `MemoryLedger` by default, or your own store. |
-| `tokenLimits` | none | Per-mint cap in UI units. Over the cap means `review`. |
-| `allow` / `deny` | `[]` | `allow` skips scoring; `deny` always blocks. |
-| `onUnknown` | `'review'` | Recipients with no history to score. |
-| `onCheckError` | `'block'` | When the check fails or the signature does not verify. |
-| `unknownPrograms` | `'review'` | Transactions that call programs outside the well-known list. |
-
-## 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)
+# 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.js

@@ -6,16 +6,51 @@
 import { Vera } from './client.js';
 import { VeraGuard } from './guard.js';
 const args = process.argv.slice(2);
-const flag = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; };
-const json = args.includes('--json');
-const pos = args.filter((a, i) => !a.startsWith('--') && !(i > 0 && args[i - 1].startsWith('--') && args[i - 1] !== '--json'));
+// 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 = {
-    ...(flag('min-tier') ? { minTier: flag('min-tier') } : {}),
-    ...(flag('daily') ? { dailyLimitSol: Number(flag('daily')) } : {}),
-    ...(flag('max-tx') ? { maxSolPerTx: Number(flag('max-tx')) } : {}),
+    ...(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 });
+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}`);
@@ -37,6 +72,10 @@ function printDecision(d) {
         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);
@@ -52,6 +91,8 @@ async function main() {
         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);
     }
@@ -69,13 +110,14 @@ async function main() {
         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
-
-  --min-tier high|medium|low   --daily <sol>   --max-tx <sol>   --json
+    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;
 }

package/dist/client.d.ts

@@ -34,6 +34,9 @@ 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;
@@ -41,20 +44,26 @@ 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. */
+    /** 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 Vera issuer public key, fetched once from /.well-known/vera.json unless pinned in the constructor. */
+    /** 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 counterparty meets the minimum tier and the attestation verifies. */
+    /** 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

@@ -1,7 +1,7 @@
 // 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() // defaults to the hosted API; pass { apiKey } only if you were issued one;
+//   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);
@@ -14,19 +14,28 @@ export class VeraError extends Error {
         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);
+    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 expired = Date.parse(attestation.expires_at) < Date.now();
+    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' };
@@ -39,23 +48,38 @@ 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 ?? 'https://vera-agent-psi.vercel.app').replace(/\/$/, '');
+        this.apiUrl = (opts.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, '');
         this.apiKey = opts.apiKey;
-        this.issuer = opts.issuer;
+        this.issuer = opts.issuer === 'fetch' ? undefined : (opts.issuer ?? VERA_ISSUER);
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
     }
     async req(path, init) {
-        const r = await fetch(this.apiUrl + path, { ...init, headers: { 'content-type': 'application/json', ...(this.apiKey ? { 'x-api-key': this.apiKey } : {}), ...init?.headers } });
+        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. */
-    check(address, opts = {}) {
-        return this.req('/v1/check', { method: 'POST', body: JSON.stringify({ address, fresh: opts.fresh }) });
+    /** 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 Vera issuer public key, fetched once from /.well-known/vera.json unless pinned in the constructor. */
+    /** 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;
@@ -64,13 +88,17 @@ export class Vera {
     async verify(result) {
         return verifyAttestation(result.attestation, result.signature, await this.getIssuer());
     }
-    /** Convenience gate: throws unless the counterparty meets the minimum tier and the attestation verifies. */
+    /** 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}`);
-        const rank = { unknown: 0, low: 1, medium: 2, high: 3 };
+        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

@@ -23,6 +23,8 @@ export declare class VeraReviewRequiredError extends Error {
 }
 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;
@@ -39,9 +41,11 @@ 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[]>;
@@ -59,7 +63,7 @@ export declare class VeraGuard {
     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. Records the SOL spent in the ledger. */
+    /** 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;

package/dist/guard.js

@@ -1,6 +1,6 @@
 import { Vera } from './client.js';
 import { inspectTransaction } from './inspect.js';
-import { evaluatePolicy } from './policy.js';
+import { evaluatePolicy, validatePolicy } from './policy.js';
 export class MemoryLedger {
     day = '';
     spent = 0;
@@ -29,13 +29,18 @@ 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;
@@ -46,7 +51,7 @@ export class VeraGuard {
         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);
+                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 };
@@ -61,16 +66,16 @@ export class VeraGuard {
         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, []);
+        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);
-        return this.decide(ins.outflows, ins.unknownPrograms);
+        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, unknownPrograms) {
+    async decide(outflows, extra) {
         const recipients = await this.checkRecipients(outflows.map((o) => o.to));
-        const decision = evaluatePolicy({ outflows, recipients, unknownPrograms, spentTodaySol: await this.ledger.spentToday(), policy: this.policy });
+        const decision = evaluatePolicy({ outflows, recipients, ...extra, spentTodaySol: await this.ledger.spentToday(), policy: this.policy });
         this.onDecision?.(decision);
         return decision;
     }
@@ -83,21 +88,28 @@ export class VeraGuard {
             throw new VeraReviewRequiredError(d);
         return d;
     }
-    /** Evaluate, then sign and send only if allowed. Records the SOL spent in the ledger. */
+    /** 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 decision = await this.assert(tx);
-        let signature;
-        if ('version' in tx) {
-            if (signers.length)
-                tx.sign(signers);
-            signature = await this.connection.sendTransaction(tx, options);
+        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 };
         }
-        else {
-            signature = await this.connection.sendTransaction(tx, signers, options);
+        catch (e) {
+            await this.ledger.add(-decision.totalSol);
+            throw e;
         }
-        await this.ledger.add(decision.totalSol);
-        return { signature, decision };
     }
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { Vera, VeraError, verifyAttestation, canonical, type Attestation, type CheckResult, type Tier, type VerifyResult } from './client.js';
+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, DEFAULT_POLICY, type Policy, type Decision, type Finding, type Outflow, type RecipientCheck, type Action } from './policy.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

@@ -1,6 +1,6 @@
 // veralayer: payment guard for AI agents on Solana.
-export { Vera, VeraError, verifyAttestation, canonical } from './client.js';
+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, DEFAULT_POLICY } from './policy.js';
+export { evaluatePolicy, validatePolicy, DEFAULT_POLICY } from './policy.js';
 export { KNOWN_PROGRAMS } from './programs.js';

package/dist/inspect.d.ts

@@ -1,11 +1,15 @@
 import type { Connection, Transaction, VersionedTransaction } from '@solana/web3.js';
-import type { Outflow } from './policy.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[];
-    /** instructions we decoded vs. ones we could not attribute value to */
+    /** names of well-known programs called that can move value the guard does not decode */
+    valuePrograms: string[];
+    risky: RiskyInstruction[];
     notes: string[];
 };
 type Ix = {
@@ -18,6 +22,8 @@ export declare function instructionsOf(tx: Transaction | VersionedTransaction, c
     payer: string;
     ixs: Ix[];
 }>;
-/** Decode outflows from the paying wallet. Token destinations are resolved to their owner via RPC when needed. */
-export declare function inspectTransaction(tx: Transaction | VersionedTransaction, connection?: Connection): Promise<Inspection>;
+/** 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

@@ -3,9 +3,12 @@ const SYSTEM = '11111111111111111111111111111111';
 const TOKEN = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
 const TOKEN22 = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
 const ATA = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
-const SKIP_PROGRAMS = new Set([SYSTEM, TOKEN, TOKEN22, ATA, 'ComputeBudget111111111111111111111111111111']);
+// 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;
 }
@@ -32,38 +35,60 @@ export async function instructionsOf(tx, connection) {
         ixs: msg.compiledInstructions.map((ix) => ({ programId: k(ix.programIdIndex), accounts: ix.accountKeyIndexes.map(k), data: ix.data })),
     };
 }
-/** Decode outflows from the paying wallet. Token destinations are resolved to their owner via RPC when needed. */
-export async function inspectTransaction(tx, connection) {
+/** 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 -> { wallet, mint }
+    // 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.accounts.length >= 4)
+        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);
-        if (ix.programId === SYSTEM && ix.data.length >= 12) {
-            const op = u32(ix.data, 0);
-            if (op === 2)
-                outflows.push({ kind: 'sol', to: ix.accounts[1], toAccount: ix.accounts[1], amount: u64(ix.data, 4) / 1e9, instruction: 'system.transfer' });
-            else if (op === 11)
-                outflows.push({ kind: 'sol', to: ix.accounts[2], toAccount: ix.accounts[2], amount: u64(ix.data, 4) / 1e9, instruction: 'system.transferWithSeed' });
-            else if (op === 0 && ix.accounts[1])
-                outflows.push({ kind: 'sol', to: ix.accounts[1], toAccount: ix.accounts[1], amount: u64(ix.data, 4) / 1e9, instruction: 'system.createAccount' });
+        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) && ix.data.length >= 9) {
-            const op = ix.data[0];
-            if (op === 3)
-                pendingTokens.push({ account: ix.accounts[1], raw: u64(ix.data, 1), instruction: 'token.transfer' });
-            else if (op === 12 && ix.data.length >= 10)
-                pendingTokens.push({ account: ix.accounts[2], raw: u64(ix.data, 1), decimals: ix.data[9], mint: ix.accounts[1], instruction: 'token.transferChecked' });
+        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);
@@ -71,26 +96,30 @@ export async function inspectTransaction(tx, connection) {
             owner = c.owner;
             mint ??= c.mint;
         }
-        if ((!owner || decimals === undefined) && connection) {
-            const info = await connection.getParsedAccountInfo(new (await import('@solana/web3.js')).PublicKey(t.account));
+        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 (await import('@solana/web3.js')).PublicKey(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', to: owner ?? t.account, toAccount: t.account, amount: decimals === undefined ? t.raw : t.raw / 10 ** decimals, mint, instruction: t.instruction });
+        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) => !SKIP_PROGRAMS.has(p) && !KNOWN_PROGRAMS[p]);
-    // value moved inside other programs (swaps, CPIs) is not decoded here; say so instead of pretending
+    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 (!SKIP_PROGRAMS.has(p))
+        if (!INERT.has(p))
             notes.push(`calls ${KNOWN_PROGRAMS[p] ?? p}: value moved inside this program is not decoded`);
-    return { payer, outflows: outflows.filter((o) => o.to !== payer && o.amount > 0), programs: all, unknownPrograms, notes };
+    // 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

@@ -3,7 +3,7 @@ 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: 0. */
+    /** 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;
@@ -15,25 +15,48 @@ export type Policy = {
     allow?: string[];
     /** Addresses that are always blocked. */
     deny?: string[];
-    /** What to do with recipients Vera cannot score (no history). Default 'review'. */
-    onUnknown?: Exclude<Action, 'allow'> | 'allow';
-    /** What to do when the Vera check itself fails or its signature does not verify. Default 'block'. */
+    /** 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: Required<Omit<Policy, 'maxSolPerTx' | 'dailyLimitSol' | 'tokenLimits'>> & Pick<Policy, 'maxSolPerTx' | 'dailyLimitSol' | 'tokenLimits'>;
-/** One movement of value out of the paying wallet. */
+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. */
+    /** 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 = {
@@ -67,10 +90,15 @@ export type Decision = {
     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

@@ -1,70 +1,112 @@
 export const DEFAULT_POLICY = {
     minTier: 'medium',
-    tierLimitsSol: { high: Infinity, medium: 5, low: 0, unknown: 0 },
+    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 } : {}) });
-    const totalSol = input.outflows.filter((o) => o.kind === 'sol').reduce((s, o) => s + o.amount, 0);
-    const solTo = new Map();
+    // 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(input.outflows.map((o) => o.to))) {
-        const short = `${to.slice(0, 4)}…${to.slice(-4)}`;
+    for (const to of new Set(outflows.map((o) => o.to))) {
+        const s = short(to);
         if (deny.has(to)) {
-            add('block', 'denylisted', `${short} is on your deny list`, 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 ${short}${r && !r.ok ? `: ${r.error}` : ''}`, to);
+            add(p.onCheckError, 'check_failed', `Could not check ${s}${r && !r.ok ? `: ${r.error}` : ''}`, to);
             continue;
         }
-        if (!r.verified) {
-            add(p.onCheckError, 'bad_signature', `Vera's signature for ${short} did not verify`, to);
+        if (!(r.tier in RANK)) {
+            add(p.onCheckError, 'bad_tier', `Vera returned an unexpected tier for ${s}`, to);
             continue;
         }
-        if (r.expired) {
-            add('review', 'stale_check', `Vera's result for ${short} has expired`, to);
+        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', `${short} has no history Vera can score`, to);
+            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', `${short} is ${r.tier} trust (${r.score}/100), below your minimum of ${p.minTier}: ${r.reasons[0]?.text ?? ''}`.trim(), to);
+            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 && !(r.tier === 'unknown' && p.onUnknown === 'allow')) {
-            add(cap === 0 ? 'block' : 'review', 'tier_limit', `${fmt(sent)} SOL to ${short} exceeds the ${fmt(cap)} SOL limit for ${r.tier} trust`, to);
-        }
+        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 input.outflows) {
-        if (o.kind !== 'token' || !o.mint || !p.tokenLimits || !(o.mint in p.tokenLimits))
+    for (const o of outflows) {
+        if (o.kind !== 'token')
             continue;
-        if (o.amount > p.tokenLimits[o.mint])
+        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: input.outflows, recipients: input.recipients, totalSol, unknownPrograms: input.unknownPrograms ?? [] };
+    return { action, findings, outflows, recipients: input.recipients, totalSol, unknownPrograms: input.unknownPrograms ?? [] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veralayer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Payment guard for AI agents on Solana: inspects every outgoing transaction, scores each recipient with Vera, and enforces your spending policy before anything is signed.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,12 @@
     "./client": {
       "types": "./dist/client.d.ts",
       "import": "./dist/client.js"
-    }
+    },
+    "./agent-kit": {
+      "types": "./dist/agent-kit.d.ts",
+      "import": "./dist/agent-kit.js"
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "veralayer": "dist/cli.js"
@@ -27,10 +32,13 @@
     "README.md",
     "LICENSE"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/cli.js",
+    "./dist/mcp.js"
+  ],
   "scripts": {
     "build": "tsc",
-    "test": "node --env-file-if-exists=../../../../checker/.env test/run.mjs",
+    "test": "node --env-file-if-exists=../../../../checker/.env test/run.mjs && node --env-file-if-exists=../../../../checker/.env test/security.mjs",
     "prepublishOnly": "tsc && node test/smoke.mjs"
   },
   "keywords": [
@@ -41,19 +49,26 @@
     "risk",
     "guard",
     "mcp",
-    "solana-agent-kit"
+    "solana-agent-kit",
+    "model-context-protocol",
+    "claude",
+    "cursor"
   ],
-  "homepage": "https://vera-agent-psi.vercel.app",
+  "homepage": "https://veraagent.io",
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19"
   },
   "peerDependencies": {
-    "@solana/web3.js": "^1.95.0"
+    "@solana/web3.js": "^1.95.0",
+    "zod": ">=3.22"
   },
   "peerDependenciesMeta": {
     "@solana/web3.js": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -63,6 +78,7 @@
   "devDependencies": {
     "@solana/web3.js": "^1.99.0",
     "@types/node": "^26.6.6",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod": "^4.6.7"
   }
 }