veralayer 0.0.0-stage → 0.1.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,84 @@
-# Temporary Holding Version
+# veralayer
 
-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.
+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)

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,82 @@
+#!/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);
+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'));
+const [cmd, a1, a2] = pos;
+const policy = {
+    ...(flag('min-tier') ? { minTier: flag('min-tier') } : {}),
+    ...(flag('daily') ? { dailyLimitSol: Number(flag('daily')) } : {}),
+    ...(flag('max-tx') ? { maxSolPerTx: Number(flag('max-tx')) } : {}),
+};
+const vera = new Vera({ apiUrl: flag('api') ?? process.env.VERA_API_URL, apiKey: process.env.VERA_API_KEY });
+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 === '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) {
+        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
+
+  --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,60 @@
+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);
+}
+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?;
+    constructor(opts?: {
+        apiUrl?: string;
+        apiKey?: string;
+        issuer?: string;
+    });
+    private req;
+    /** Score a counterparty. Returns score, tier, reasons and a signed attestation. */
+    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. */
+    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. */
+    require(address: string, minTier?: Exclude<Tier, 'unknown'>): Promise<CheckResult>;
+}

package/dist/client.js

@@ -0,0 +1,78 @@
+// 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 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;
+    }
+}
+// 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);
+}
+/** 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();
+    if (trustedIssuer && attestation.issuer !== trustedIssuer)
+        return { valid: false, expired, reason: 'issuer is not the trusted Vera key' };
+    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;
+    constructor(opts = {}) {
+        this.apiUrl = (opts.apiUrl ?? 'https://vera-agent-psi.vercel.app').replace(/\/$/, '');
+        this.apiKey = opts.apiKey;
+        this.issuer = opts.issuer;
+    }
+    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 } });
+        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 }) });
+    }
+    /** The Vera issuer public key, fetched once from /.well-known/vera.json unless pinned in the constructor. */
+    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 counterparty meets the minimum tier and the attestation verifies. */
+    async require(address, minTier = 'medium') {
+        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 (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,67 @@
+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;
+    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 ledger;
+    private onReview?;
+    private onDecision?;
+    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. Records the SOL spent in the ledger. */
+    sendTransaction(tx: Transaction | VersionedTransaction, signers?: Signer[], options?: SendOptions): Promise<{
+        signature: string;
+        decision: Decision;
+    }>;
+}

package/dist/guard.js

@@ -0,0 +1,103 @@
+import { Vera } from './client.js';
+import { inspectTransaction } from './inspect.js';
+import { evaluatePolicy } from './policy.js';
+export class MemoryLedger {
+    day = '';
+    spent = 0;
+    roll() { const d = new Date().toISOString().slice(0, 10); if (d !== this.day) {
+        this.day = d;
+        this.spent = 0;
+    } }
+    spentToday() { this.roll(); return this.spent; }
+    add(sol) { this.roll(); this.spent += sol; }
+}
+export class VeraBlockedError extends Error {
+    decision;
+    constructor(decision) {
+        super(`Vera blocked this transaction: ${decision.findings.filter((f) => f.action === 'block').map((f) => f.message).join('; ')}`);
+        this.decision = decision;
+    }
+}
+export class VeraReviewRequiredError extends Error {
+    decision;
+    constructor(decision) {
+        super(`Vera needs a human review: ${decision.findings.filter((f) => f.action === 'review').map((f) => f.message).join('; ')}`);
+        this.decision = decision;
+    }
+}
+export class VeraGuard {
+    vera;
+    policy;
+    connection;
+    ledger;
+    onReview;
+    onDecision;
+    constructor(opts = {}) {
+        this.vera = opts.vera instanceof Vera ? opts.vera : new Vera(opts.vera);
+        this.policy = opts.policy ?? {};
+        this.connection = opts.connection;
+        this.ledger = opts.ledger ?? new MemoryLedger();
+        this.onReview = opts.onReview;
+        this.onDecision = opts.onDecision;
+    }
+    /** Score recipients (deduplicated, in parallel) and verify each signed result against Vera's published key. */
+    async checkRecipients(addresses) {
+        const skip = new Set([...(this.policy.allow ?? []), ...(this.policy.deny ?? [])]);
+        const uniq = [...new Set(addresses)].filter((a) => !skip.has(a));
+        return Promise.all(uniq.map(async (address) => {
+            try {
+                const r = await this.vera.check(address);
+                const v = await this.vera.verify(r);
+                const a = r.attestation;
+                return { address, ok: true, score: a.score, tier: a.tier, reasons: a.reasons, attestationId: r.id, verified: v.valid, expired: v.expired };
+            }
+            catch (e) {
+                return { address, ok: false, error: e.message };
+            }
+        }));
+    }
+    /** Decide on a planned payment without building a transaction (e.g. before quoting a price to another agent). */
+    async evaluatePayment(payment) {
+        const outflows = payment.token
+            ? [{ kind: 'token', to: payment.to, toAccount: payment.to, amount: payment.token.amount, mint: payment.token.mint, instruction: 'planned' }]
+            : [{ kind: 'sol', to: payment.to, toAccount: payment.to, amount: payment.amountSol ?? 0, instruction: 'planned' }];
+        return this.decide(outflows, []);
+    }
+    /** Decode a transaction and decide on it. Does not send anything. */
+    async evaluate(tx) {
+        const ins = await inspectTransaction(tx, this.connection);
+        return this.decide(ins.outflows, ins.unknownPrograms);
+    }
+    async decide(outflows, unknownPrograms) {
+        const recipients = await this.checkRecipients(outflows.map((o) => o.to));
+        const decision = evaluatePolicy({ outflows, recipients, unknownPrograms, spentTodaySol: await this.ledger.spentToday(), policy: this.policy });
+        this.onDecision?.(decision);
+        return decision;
+    }
+    /** Throws VeraBlockedError / VeraReviewRequiredError unless the transaction may be sent. */
+    async assert(tx) {
+        const d = await this.evaluate(tx);
+        if (d.action === 'block')
+            throw new VeraBlockedError(d);
+        if (d.action === 'review' && !(this.onReview && (await this.onReview(d))))
+            throw new VeraReviewRequiredError(d);
+        return d;
+    }
+    /** Evaluate, then sign and send only if allowed. Records the SOL spent in the ledger. */
+    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);
+        }
+        else {
+            signature = await this.connection.sendTransaction(tx, signers, options);
+        }
+        await this.ledger.add(decision.totalSol);
+        return { signature, decision };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Vera, VeraError, 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 { KNOWN_PROGRAMS } from './programs.js';

package/dist/index.js

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

package/dist/inspect.d.ts

@@ -0,0 +1,23 @@
+import type { Connection, Transaction, VersionedTransaction } from '@solana/web3.js';
+import type { Outflow } from './policy.js';
+export type Inspection = {
+    payer: string;
+    outflows: Outflow[];
+    programs: string[];
+    unknownPrograms: string[];
+    /** instructions we decoded vs. ones we could not attribute value to */
+    notes: string[];
+};
+type Ix = {
+    programId: string;
+    accounts: string[];
+    data: Uint8Array;
+};
+/** Flatten a legacy or versioned transaction into plain instructions, resolving address lookup tables. */
+export declare function instructionsOf(tx: Transaction | VersionedTransaction, connection?: Connection): Promise<{
+    payer: string;
+    ixs: Ix[];
+}>;
+/** Decode 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>;
+export {};

package/dist/inspect.js

@@ -0,0 +1,96 @@
+import { KNOWN_PROGRAMS } from './programs.js';
+const SYSTEM = '11111111111111111111111111111111';
+const TOKEN = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+const TOKEN22 = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
+const ATA = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+const SKIP_PROGRAMS = new Set([SYSTEM, TOKEN, TOKEN22, ATA, 'ComputeBudget111111111111111111111111111111']);
+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);
+function isVersioned(tx) {
+    return 'version' in tx;
+}
+/** Flatten a legacy or versioned transaction into plain instructions, resolving address lookup tables. */
+export async function instructionsOf(tx, connection) {
+    if (!isVersioned(tx)) {
+        const payer = (tx.feePayer ?? tx.instructions[0]?.keys.find((k) => k.isSigner)?.pubkey)?.toBase58() ?? '';
+        return { payer, ixs: tx.instructions.map((ix) => ({ programId: ix.programId.toBase58(), accounts: ix.keys.map((k) => k.pubkey.toBase58()), data: Uint8Array.from(ix.data) })) };
+    }
+    const msg = tx.message;
+    const luts = [];
+    for (const l of msg.addressTableLookups ?? []) {
+        if (!connection)
+            throw new Error('a Connection is needed to resolve address lookup tables');
+        const res = await connection.getAddressLookupTable(l.accountKey);
+        if (!res.value)
+            throw new Error(`lookup table ${l.accountKey.toBase58()} not found`);
+        luts.push(res.value);
+    }
+    const keys = msg.getAccountKeys({ addressLookupTableAccounts: luts });
+    const k = (i) => keys.get(i).toBase58();
+    return {
+        payer: k(0),
+        ixs: msg.compiledInstructions.map((ix) => ({ programId: k(ix.programIdIndex), accounts: ix.accountKeyIndexes.map(k), data: ix.data })),
+    };
+}
+/** Decode outflows from the paying wallet. Token destinations are resolved to their owner via RPC when needed. */
+export async function inspectTransaction(tx, connection) {
+    const { payer, ixs } = await instructionsOf(tx, connection);
+    const outflows = [];
+    const notes = [];
+    const programs = new Set();
+    // token accounts created in this transaction: ata -> { wallet, mint }
+    const created = new Map();
+    for (const ix of ixs)
+        if (ix.programId === ATA && ix.accounts.length >= 4)
+            created.set(ix.accounts[1], { owner: ix.accounts[2], mint: ix.accounts[3] });
+    const pendingTokens = [];
+    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' });
+        }
+        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' });
+        }
+    }
+    // resolve token destinations to owners (and mint/decimals for plain `transfer`)
+    for (const t of pendingTokens) {
+        let owner, mint = t.mint, decimals = t.decimals;
+        const c = created.get(t.account);
+        if (c) {
+            owner = c.owner;
+            mint ??= c.mint;
+        }
+        if ((!owner || decimals === undefined) && connection) {
+            const info = await connection.getParsedAccountInfo(new (await import('@solana/web3.js')).PublicKey(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));
+                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 });
+    }
+    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
+    for (const p of all)
+        if (!SKIP_PROGRAMS.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 };
+}

package/dist/policy.d.ts

@@ -0,0 +1,76 @@
+import type { Tier } from './client.js';
+export type Action = 'allow' | 'review' | 'block';
+export type Policy = {
+    /** Recipients below this tier are blocked. Default 'medium'. */
+    minTier?: Exclude<Tier, 'unknown'>;
+    /** Max SOL one recipient may receive in one transaction, per tier. Default high: no cap, medium: 5, low: 0, unknown: 0. */
+    tierLimitsSol?: Partial<Record<Tier, number>>;
+    /** Max total SOL leaving the wallet in one transaction. */
+    maxSolPerTx?: number;
+    /** Max total SOL per UTC day, tracked by the guard's ledger. */
+    dailyLimitSol?: number;
+    /** Per-mint caps for SPL tokens, in UI units (e.g. { EPjF…Dt1v: 500 } for 500 USDC per transaction). */
+    tokenLimits?: Record<string, number>;
+    /** Addresses that skip scoring (your own treasury, known vendors). */
+    allow?: string[];
+    /** Addresses that are always blocked. */
+    deny?: string[];
+    /** 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'. */
+    onCheckError?: Exclude<Action, 'allow'>;
+    /** Transactions that call programs outside the well-known list. Default 'review'. */
+    unknownPrograms?: 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 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. */
+    amount: number;
+    mint?: string;
+    instruction: string;
+};
+/** What the guard learned about one recipient. */
+export type RecipientCheck = {
+    address: string;
+    ok: true;
+    score: number | null;
+    tier: Tier;
+    reasons: {
+        kind: string;
+        text: string;
+    }[];
+    attestationId: string;
+    verified: boolean;
+    expired: boolean;
+} | {
+    address: string;
+    ok: false;
+    error: string;
+};
+export type Finding = {
+    action: Action;
+    code: string;
+    message: string;
+    address?: string;
+};
+export type Decision = {
+    action: Action;
+    findings: Finding[];
+    outflows: Outflow[];
+    recipients: RecipientCheck[];
+    totalSol: number;
+    unknownPrograms: string[];
+};
+export declare function evaluatePolicy(input: {
+    outflows: Outflow[];
+    recipients: RecipientCheck[];
+    unknownPrograms?: string[];
+    spentTodaySol?: number;
+    policy?: Policy;
+}): Decision;

package/dist/policy.js

@@ -0,0 +1,70 @@
+export const DEFAULT_POLICY = {
+    minTier: 'medium',
+    tierLimitsSol: { high: Infinity, medium: 5, low: 0, unknown: 0 },
+    allow: [],
+    deny: [],
+    onUnknown: 'review',
+    onCheckError: 'block',
+    unknownPrograms: 'review',
+};
+const RANK = { unknown: 0, low: 1, medium: 2, high: 3 };
+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+$/, ''));
+export function evaluatePolicy(input) {
+    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();
+    for (const o of input.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)}`;
+        if (deny.has(to)) {
+            add('block', 'denylisted', `${short} 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);
+            continue;
+        }
+        if (!r.verified) {
+            add(p.onCheckError, 'bad_signature', `Vera's signature for ${short} did not verify`, to);
+            continue;
+        }
+        if (r.expired) {
+            add('review', 'stale_check', `Vera's result for ${short} has expired`, to);
+        }
+        if (r.tier === 'unknown') {
+            add(p.onUnknown, 'unknown_recipient', `${short} 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);
+        }
+        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);
+        }
+    }
+    for (const o of input.outflows) {
+        if (o.kind !== 'token' || !o.mint || !p.tokenLimits || !(o.mint in p.tokenLimits))
+            continue;
+        if (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`);
+    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(', ')}`);
+    const action = findings.reduce((a, f) => worst(a, f.action), 'allow');
+    return { action, findings, outflows: input.outflows, recipients: input.recipients, totalSol, unknownPrograms: input.unknownPrograms ?? [] };
+}

package/dist/programs.d.ts

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

package/dist/programs.js

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

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "veralayer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./policy": {
+      "types": "./dist/policy.d.ts",
+      "import": "./dist/policy.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "bin": {
+    "veralayer": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "test": "node --env-file-if-exists=../../../../checker/.env test/run.mjs",
+    "prepublishOnly": "tsc && node test/smoke.mjs"
+  },
+  "keywords": [
+    "solana",
+    "ai-agent",
+    "agent-payments",
+    "trust-score",
+    "risk",
+    "guard",
+    "mcp",
+    "solana-agent-kit"
+  ],
+  "homepage": "https://vera-agent-psi.vercel.app",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@solana/web3.js": "^1.95.0"
+  },
+  "peerDependenciesMeta": {
+    "@solana/web3.js": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@noble/curves": "^2.4.0",
+    "bs58": "^6.0.0"
+  },
+  "devDependencies": {
+    "@solana/web3.js": "^1.99.0",
+    "@types/node": "^26.6.6",
+    "typescript": "^5.9.3"
+  }
+}