@wzrd_sol/eliza-plugin 0.3.1 → 0.3.2

package/README.md

@@ -1,8 +1,15 @@
 # @wzrd_sol/eliza-plugin
 
-ElizaOS plugin for WZRD Agent Intel and the legacy earn loop on Solana.
+ElizaOS plugin for WZRD Agent Intel — x402 firewall, free preflight checks before spends,
+paid trust receipts (V6 + ERC-8004), and the earn loop on Solana.
 
-**Before any x402 spend:** run `WZRD_INTEL_PREFLIGHT` (free ReadinessCard). Escalate to `WZRD_INTEL_TRUST` only when you need a signed V5 receipt. Verify offline with `WZRD_VERIFY_RECEIPT`.
+## 3-line quickstart
+
+```typescript
+import wzrdPlugin from '@wzrd_sol/eliza-plugin';
+const agent = new AgentRuntime({ plugins: [wzrdPlugin] });
+// "Preflight seller JUP6Lkb... at 0.25 USDC" → allow/warn/block, free, no wallet
+```
 
 ## Install
 
@@ -15,93 +22,185 @@ npm install @wzrd_sol/eliza-plugin
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `WZRD_INTEL_URL` | No | `https://intel.twzrd.xyz` | Agent Intel API (preflight, trust, verify) |
-| `WZRD_API_URL` | No | `https://api.twzrd.xyz` | Legacy earn API (infer/report/claim) |
+| `WZRD_API_URL` | No | `https://api.twzrd.xyz` | Earn API (infer/report/claim) |
 | `SOLANA_PRIVATE_KEY` | Earn lane only | — | JSON array of secret key bytes for agent Ed25519 auth |
 
-### Wiring a paying fetch (intel paid actions)
+## Intel actions (primary)
 
-The plugin does **not** embed a wallet. Paid `WZRD_INTEL_TRUST` needs an x402-capable `fetch` from the host:
+| Action | Auth/Pay | Description |
+|--------|----------|-------------|
+| `WZRD_INTEL_PREFLIGHT` | Free | ReadinessCard: `decision`, `trust_score`, `can_spend`, `caveats`, `preflight_id` |
+| `WZRD_INTEL_TRUST` | x402 (~0.05 USDC) | Paid trust payload + V6 signed receipt + ERC-8004 `reputation_credential` |
+| `WZRD_VERIFY_RECEIPT` | Free (offline) | Recompute leaf + Ed25519 verify; no network when pubkey is known |
 
-```typescript
-import { AgentRuntime } from '@elizaos/core';
-import wzrdPlugin, { setPayingFetch } from '@wzrd_sol/eliza-plugin';
-import { agentcashFetch } from 'your-x402-wrapper'; // agentcash, twzrd-x402-gate, etc.
+### Preflight (free, no wallet)
 
-setPayingFetch(agentcashFetch);
+```typescript
+import { intelPreflightAction } from '@wzrd_sol/eliza-plugin';
 
-const agent = new AgentRuntime({
-  plugins: [wzrdPlugin],
-  settings: {
-    WZRD_INTEL_URL: 'https://intel.twzrd.xyz',
-    SOLANA_PRIVATE_KEY: process.env.SOLANA_PRIVATE_KEY,
+// Reads seller_wallet / price_usdc / agent_intent from message content.
+await intelPreflightAction.handler(runtime, {
+  content: {
+    seller_wallet: 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4',
+    price_usdc: 0.25,
+    agent_intent: 'quote preview',
   },
-});
+}, state, opts, callback);
 ```
 
-Without a paying fetch, `WZRD_INTEL_TRUST` returns the HTTP 402 requirements and an `npx agentcash@latest fetch ...` one-liner.
+Response (formatted text returned to agent):
 
-## Usage
+```
+ReadinessCard v1
+Decision: allow
+Trust score: 72
+Can spend: yes
+Preflight ID: pf_abc123
+Paid deep dive available (0.05 USDC) — use WZRD_INTEL_TRUST
+```
 
-```typescript
-import { wzrdPlugin } from '@wzrd_sol/eliza-plugin';
+### Guard pattern: fire-before-pay with `withTwzrdGuard`
+
+For agents that call x402-gated URLs directly (not via pre-known seller wallet), pair this
+plugin with `twzrd-x402-gate` to intercept 402s before any spend:
 
-const agent = new AgentRuntime({
-  plugins: [wzrdPlugin],
+```typescript
+import wzrdPlugin from '@wzrd_sol/eliza-plugin';
+import { withTwzrdGuard } from 'twzrd-x402-gate';
+import { createAgentcashFetch } from 'agentcash';
+
+// Wrap the paying fetch — guard runs preflight on every 402 before USDC moves.
+const x402Fetch = createAgentcashFetch({ apiKey: process.env.AGENTCASH_API_KEY });
+const safeFetch = withTwzrdGuard(x402Fetch, {
+  autoReceipt: true,   // auto-buy $0.05 TWZRD receipt on warn/allow
+  x402Fetch,
 });
+
+// Wire safeFetch into any tool or skill that calls paid resources:
+const response = await safeFetch('https://api.exa.ai/search');
+// → decision=block throws before payment
+// → decision=warn/allow: payment proceeds, TWZRD receipt captured
 ```
 
-Programmatic SDK calls (same types as the plugin) are re-exported:
+Guard flow:
+1. `safeFetch` hits the resource, gets HTTP 402.
+2. `withTwzrdGuard` reads `accepts[0].payTo` (seller wallet).
+3. Calls `POST /v1/intel/preflight` — free, no auth.
+4. `block` - throws, no payment made.
+5. `warn/allow` - returns the 402 for the x402 client to pay.
+
+### Pre-spend gate (programmatic)
 
 ```typescript
-import { intelPreflight, fetchIntelTrust, verifyReceipt, IntelPaymentRequiredError } from '@wzrd_sol/eliza-plugin';
+import { preSpendGate, fetchIntelTrust } from '@wzrd_sol/eliza-plugin';
+
+// Gate before paying:
+const gate = await preSpendGate({ seller_wallet: sellerPubkey });
+if (!gate.allow) return `Blocked (${gate.decision}): ${gate.reason}`;
+
+// Then pay and get the receipt:
+const trust = await fetchIntelTrust(sellerPubkey, { fetchImpl: myX402Fetch });
 ```
 
-## Intel actions (primary)
+### Paid trust receipt (agentcash)
 
-| Action | Auth/Pay | Description |
-|--------|----------|-------------|
-| `WZRD_INTEL_PREFLIGHT` | Free | ReadinessCard: decision, trust_score, can_spend, caveats, paid upsell |
-| `WZRD_INTEL_TRUST` | x402 (~0.05 USDC) | Paid trust payload + V5 `twzrd_receipt` (needs `setPayingFetch`) |
-| `WZRD_VERIFY_RECEIPT` | Free (offline) | Recompute leaf + Ed25519 verify; no network when pubkey is known |
+```typescript
+import wzrdPlugin, { setPayingFetch } from '@wzrd_sol/eliza-plugin';
+import { createAgentcashFetch } from 'agentcash';
 
-### Example prompts
+setPayingFetch(createAgentcashFetch({ apiKey: process.env.AGENTCASH_API_KEY }));
 
-- "Preflight Jupiter Quote Preview before I pay 0.25 USDC to 6EF8rrect..."
-- "Get the trust receipt for seller JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"
-- "Verify this receipt: {leaf, preimage, signature...}"
-- "Is it safe to call the paid intel endpoint on this seller?"
+const agent = new AgentRuntime({ plugins: [wzrdPlugin] });
+// "Get the trust receipt for seller JUP6LkbZ..."
+// → WZRD_INTEL_TRUST: runs free preflight, pays $0.05 USDC, returns VC
+```
 
-### Free preflight (no wallet)
+### Paid trust receipt (PayAI)
 
 ```typescript
-import { intelPreflightAction } from '@wzrd_sol/eliza-plugin';
+import wzrdPlugin, { setPayingFetch } from '@wzrd_sol/eliza-plugin';
+import { PayAIClient } from '@payai/client';
 
-// Handler reads seller_wallet / price_usdc / agent_intent from message content
-await intelPreflightAction.handler(runtime, {
-  content: {
-    seller_wallet: 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4',
-    price_usdc: 0.25,
-    agent_intent: 'quote preview',
-  },
-}, ...);
+const payai = new PayAIClient({ keypairPath: '~/.config/solana/id.json' });
+setPayingFetch((url, init) => payai.fetch(url, init));
+
+const agent = new AgentRuntime({ plugins: [wzrdPlugin] });
 ```
 
+Without a paying fetch, `WZRD_INTEL_TRUST` returns the HTTP 402 requirements and an
+`npx agentcash@latest fetch ...` one-liner to pay manually.
+
+**`WZRD_INTEL_TRUST` response fields:**
+
+```
+Trust payload for JUP6Lkb...
+Score: 61.8  Paid: yes
+Settlement tx: 4xK3n...
+Reputation credential (ERC-8004 AgentReputationCredential):
+  effectiveTrustScore: 62       <- route on this (wash-adjusted)
+  trustScore: 72  washFactor: 0.86
+  distinctCounterparties: 14    <- cross-facilitator breadth
+  corpusScope: cross-facilitator
+  version: intel_renorm_v1
+Routing gate: effectiveTrustScore < 30 -> block, 30-60 -> warn, > 60 -> allow
+Receipt v6, leaf: 0x3a4f...
+Use WZRD_VERIFY_RECEIPT to verify offline.
+```
+
+**Routing logic:**
+
+```typescript
+const vc = trust.reputation_credential.credentialSubject;
+if (vc.effectiveTrustScore < 30) return 'block';
+if (vc.distinctCounterparties < 3) return 'warn'; // thin history
+if (vc.washFactor < 0.5) return 'warn';           // suspicious ring
+```
+
+`effectiveTrustScore` is the cross-facilitator wash-adjusted score — computed across all known
+x402 facilitators, not just one settlement path.
+
+### Example agent prompts (trust)
+
+- `"Preflight Jupiter Quote Preview before I pay 0.25 USDC to 6EF8rrect..."`
+- `"Get the trust receipt for seller JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"`
+- `"Is it safe to call the paid intel endpoint on this seller?"`
+- `"Verify this receipt: {leaf, preimage, signature...}"`
+
 ## Legacy earn actions
 
 | Action | Auth | Description |
 |--------|------|-------------|
 | `WZRD_INFER` | Agent Ed25519 | Server-witnessed inference; returns `execution_id` |
 | `WZRD_REPORT` | Agent Ed25519 | Report outcome with `execution_id` for verified rewards |
-| `WZRD_EARN` | Agent Ed25519 | Full infer → report → rewards check in one action |
+| `WZRD_EARN` | Agent Ed25519 | Full infer -> report -> rewards check in one action |
 | `WZRD_CLAIM` | Agent Ed25519 | Gasless CCM claim via relay |
 | `WZRD_REWARDS` | Agent Ed25519 | Pending and lifetime CCM balance |
 
 ### Example prompts (earn)
 
-- "Run inference through WZRD: explain quicksort in Python"
-- "Earn some CCM on WZRD"
-- "Check my WZRD rewards"
-- "Claim my CCM"
+- `"Run inference through WZRD: explain quicksort in Python"`
+- `"Earn some CCM on WZRD"`
+- `"Check my WZRD rewards"`
+- `"Claim my CCM"`
+
+## Programmatic SDK usage
+
+```typescript
+import {
+  intelPreflight,
+  fetchIntelTrust,
+  verifyReceipt,
+  preSpendGate,
+  IntelPaymentRequiredError,
+} from '@wzrd_sol/eliza-plugin';
+
+import type {
+  ReadinessCard,
+  PreflightResponse,
+  IntelTrustResponse,
+  TwzrdReceipt,
+} from '@wzrd_sol/eliza-plugin';
+```
 
 ## Test
 
@@ -112,7 +211,8 @@ npm run build
 npm test
 ```
 
-`npm test` loads the plugin into a real `@elizaos/core` `AgentRuntime`, runs live free preflight against `intel.twzrd.xyz`, offline receipt verify, and a mocked paid trust path.
+`npm test` runs live free preflight against `intel.twzrd.xyz`, offline receipt verify, and a
+mocked paid trust path.
 
 Manual earn smoke (requires `SOLANA_PRIVATE_KEY`):
 
@@ -123,11 +223,11 @@ npx tsx test/earn-e2e.ts
 ## Links
 
 - [Agent Intel API](https://intel.twzrd.xyz)
-- [Legacy API](https://api.twzrd.xyz)
-- [SDK](https://www.npmjs.com/package/@wzrd_sol/sdk)
-- [twzrd-agent-intel (Python/MCP)](https://github.com/twzrd-sol/wzrd-final/tree/main/packages/twzrd-agent-intel)
-- [Agent discovery](https://twzrd.xyz/llms.txt)
+- [API docs / llms.txt](https://intel.twzrd.xyz/llms.txt)
+- [x402 gate (standalone firewall)](https://www.npmjs.com/package/twzrd-x402-gate)
+- [GOAT plugin](https://www.npmjs.com/package/@wzrd_sol/goat-plugin)
+- [TWZRD trust quickstart](https://intel.twzrd.xyz/docs/QUICKSTART.md)
 
 ## License
 
-MIT
+MIT

package/dist/actions/intel-preflight.js

@@ -62,9 +62,9 @@ export const intelPreflightAction = {
     handler: async (runtime, message, _state, _opt, callback) => {
         const content = (message.content ?? {});
         const input = parsePreflightInput(content);
-        if (!input.seller_wallet && !input.resource_name && !input.resource_url && !input.agent_intent) {
+        if (!input.seller_wallet && !input.resource_name && !input.resource_url) {
             await callback?.({
-                text: 'Provide seller_wallet, resource_name, resource_url, or agent_intent for preflight. ' +
+                text: 'Provide seller_wallet, resource_name, or resource_url for preflight. ' +
                     'Example: "Preflight seller JUP6Lkb... at 0.25 USDC"',
             });
             return { success: false, error: 'Missing preflight input' };

package/dist/actions/intel-trust.js

@@ -57,14 +57,21 @@ export const intelTrustAction = {
                 return fetchIntelTrust(pubkey, { apiBase, fetchImpl: abortingFetch });
             });
             const receipt = res.twzrd_receipt;
-            const text = `Trust payload for ${pubkey}\n` +
-                `Score: ${res.trust?.score ?? 'n/a'}\n` +
-                `Paid: ${res.paid ? 'yes' : 'no'}\n` +
-                (res.tx ? `Settlement tx: ${res.tx}\n` : '') +
-                (receipt
-                    ? `Receipt v${receipt.version}, leaf: ${receipt.leaf}\n` +
-                        `Use WZRD_VERIFY_RECEIPT to verify offline.`
-                    : 'No twzrd_receipt in response.');
+            const vc = res.reputation_credential?.credentialSubject;
+            const lines = [
+                `Trust payload for ${pubkey}`,
+                `Score: ${res.trust?.score ?? 'n/a'}  Paid: ${res.paid ? 'yes' : 'no'}`,
+            ];
+            const settleTx = res.tx ?? res.tx_pending;
+            if (settleTx)
+                lines.push(`Settlement tx${res.tx ? '' : ' (pending)'}: ${settleTx}`);
+            if (vc) {
+                lines.push(`Reputation credential (ERC-8004 AgentReputationCredential):`, `  effectiveTrustScore: ${vc.effectiveTrustScore ?? 'n/a'}`, `  trustScore: ${vc.trustScore ?? 'n/a'}  washFactor: ${vc.washFactor ?? 'n/a'}`, `  distinctCounterparties: ${vc.distinctCounterparties ?? 'n/a'}`, `  corpusScope: ${vc.corpusScope ?? 'n/a'}`, `  version: ${vc.trustScoreVersion ?? 'n/a'}`, `Routing gate: effectiveTrustScore < 30 → block, 30-60 → warn, > 60 → allow`);
+            }
+            lines.push(receipt
+                ? `Receipt v${receipt.version}, leaf: ${receipt.leaf}\nUse WZRD_VERIFY_RECEIPT to verify offline.`
+                : 'No twzrd_receipt in response.');
+            const text = lines.join('\n');
             await callback?.({ text });
             return { success: true, data: res };
         }

package/dist/client.d.ts

@@ -75,7 +75,7 @@ export declare class WzrdClient {
         quality_score?: number;
         latency_ms?: number;
     }): Promise<ReportResult>;
-    /** Check pending + total rewards (flattens nested /v1/agent/earned response) */
+    /** Check pending + total rewards (reads flat /v1/agent/earned response) */
     getRewards(): Promise<RewardsBalance>;
     /** Gasless CCM claim via server relay */
     claimRelay(): Promise<ClaimResult>;

package/dist/client.js

@@ -87,19 +87,17 @@ export class WzrdClient {
         }
         return res.json();
     }
-    /** Check pending + total rewards (flattens nested /v1/agent/earned response) */
+    /** Check pending + total rewards (reads flat /v1/agent/earned response) */
     async getRewards() {
         const res = await this.authedFetch('/v1/agent/earned');
         if (!res.ok)
             throw new Error(`Rewards check failed: ${res.status}`);
         const data = await res.json();
-        const economy = data.economy;
-        const routing = data.routing;
         return {
-            pending_ccm: Number(economy?.pending_ccm ?? 0),
-            total_rewarded_ccm: Number(economy?.earned_ccm ?? 0),
-            rank: null, // rank not in this endpoint
-            contribution_count: Number(routing?.lifetime_contributions ?? 0),
+            pending_ccm: Number(data.pending_ccm ?? 0),
+            total_rewarded_ccm: Number(data.total_earned_ccm ?? 0),
+            rank: data.rank == null ? null : Number(data.rank),
+            contribution_count: Number(data.lifetime_contributions ?? 0),
         };
     }
     /** Gasless CCM claim via server relay */

package/dist/intel-helpers.js

@@ -41,9 +41,10 @@ export function parseReceipt(content) {
     }
     return null;
 }
+const SOLANA_PUBKEY_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 export function extractPubkey(content) {
     const direct = str(content.pubkey ?? content.seller_wallet ?? content.wallet);
-    if (direct)
+    if (direct && SOLANA_PUBKEY_RE.test(direct))
         return direct;
     const text = str(content.text);
     if (!text)
@@ -51,7 +52,7 @@ export function extractPubkey(content) {
     const fromJson = tryParseJson(text);
     if (fromJson) {
         const w = str(fromJson.pubkey ?? fromJson.seller_wallet ?? fromJson.wallet);
-        if (w)
+        if (w && SOLANA_PUBKEY_RE.test(w))
             return w;
     }
     return extractWallet(text);
@@ -71,7 +72,10 @@ export function formatPaymentRequired(err, apiBase, pubkey) {
         `No paying fetch configured. Wire one before runtime creation:\n` +
         `  import { setPayingFetch } from '@wzrd_sol/eliza-plugin';\n` +
         `  setPayingFetch(myAgentcashFetch);\n\n` +
-        `Or pay out of band:\n` +
+        `Pay out of band only with an x402 client that preserves the sponsored fee-payer slot.\n` +
+        `Caveat: npx agentcash@latest fetch is not currently a green TWZRD repro; ` +
+        `it failed closed with payment_invalid / fee_payer_slot_already_signed on 2026-06-23.\n` +
+        `Known-bad compatibility command:\n` +
         `  npx agentcash@latest fetch ${url}`);
 }
 function str(v) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wzrd_sol/eliza-plugin",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "WZRD Agent Intel for ElizaOS — preflight ReadinessCards, x402-paid signed trust receipts (V6 reputation leaf), offline verification on intel.twzrd.xyz. Also ships the legacy earn loop.",
   "type": "module",
   "main": "dist/index.js",
@@ -59,8 +59,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/twzrd-sol/twzrd-trust.git",
-    "directory": "eliza-plugin"
+    "url": "git+https://github.com/twzrd-sol/wzrd-final.git",
+    "directory": "agents/eliza-plugin"
   },
   "bugs": {
     "url": "https://github.com/twzrd-sol/twzrd-trust/issues"