@wzrd_sol/solana-agent-plugin 0.1.0

package/examples/hello-wzrd.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * WZRD "Hello World" — prove an agent can interact in 30 seconds.
+ *
+ * What this does:
+ *   1. Read the leaderboard (no auth, 2 seconds)
+ *   2. Authenticate with Ed25519 (no browser, 1 second)
+ *   3. Check portfolio (what do I hold?)
+ *   4. Check claimable CCM (any rewards ready?)
+ *
+ * Usage:
+ *   SOLANA_RPC_URL=https://... WZRD_KEYPAIR_PATH=~/.config/solana/id.json node hello-wzrd.mjs
+ *
+ * Or generate a fresh keypair:
+ *   solana-keygen new -o /tmp/agent.json --no-bip39-passphrase
+ *   SOLANA_RPC_URL=https://... WZRD_KEYPAIR_PATH=/tmp/agent.json node hello-wzrd.mjs
+ */
+
+import { readFileSync } from 'node:fs';
+import { Keypair } from '@solana/web3.js';
+import { WzrdClient } from '../dist/index.js';
+
+const KEYPAIR_PATH = process.env.WZRD_KEYPAIR_PATH;
+if (!KEYPAIR_PATH) {
+  console.log('Usage: WZRD_KEYPAIR_PATH=/path/to/keypair.json node hello-wzrd.mjs');
+  console.log('Generate one: solana-keygen new -o /tmp/agent.json --no-bip39-passphrase');
+  process.exit(1);
+}
+
+const raw = readFileSync(KEYPAIR_PATH, 'utf8');
+const wallet = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(raw)));
+const client = new WzrdClient(wallet);
+
+console.log(`\n=== WZRD Hello World ===`);
+console.log(`Agent: ${wallet.publicKey.toBase58()}\n`);
+
+// 1. Leaderboard (public, no auth)
+console.log('→ Fetching leaderboard...');
+const board = await client.getLeaderboard(5);
+console.log(`  ${board.markets.length} markets, root_seq=${board.root.root_seq}`);
+for (const m of board.markets) {
+  const vel = m.velocity_ema >= 1000 ? `${(m.velocity_ema/1000).toFixed(0)}K` : m.velocity_ema.toFixed(0);
+  console.log(`  #${m.market_id} ${m.metric} — ${vel} velocity (${m.platform})`);
+}
+
+// 2. Portfolio (auth required — triggers challenge/verify automatically)
+console.log('\n→ Authenticating + fetching portfolio...');
+try {
+  const portfolio = await client.getPortfolio();
+  const open = portfolio.positions.filter(p => !p.is_settled);
+  console.log(`  ${open.length} open positions, ${(portfolio.total_deposited_usdc / 1e6).toFixed(4)} USDC total`);
+  for (const p of open) {
+    console.log(`  • Market #${p.market_id}: ${(p.usdc_deposited / 1e6).toFixed(4)} USDC, ${(p.multiplier_bps / 10000).toFixed(1)}x`);
+  }
+} catch (e) {
+  console.log(`  No portfolio yet (${e instanceof Error ? e.message : e})`);
+  console.log('  → First-time agent? You got auto-funded 0.003 SOL + 1000 CCM signup bonus!');
+}
+
+// 3. Claims check
+console.log('\n→ Checking claimable CCM...');
+try {
+  const claims = await client.getClaims();
+  const claimable = claims.cumulative_total - claims.claimed_total;
+  console.log(`  Cumulative: ${claims.cumulative_total}, Claimed: ${claims.claimed_total}`);
+  console.log(`  Claimable now: ${claimable > 0 ? claimable : 'none'}`);
+  if (claimable > 0) {
+    console.log('  → Run with --claim to harvest via gasless relay');
+  }
+} catch (e) {
+  console.log(`  No claims data yet (${e instanceof Error ? e.message : e})`);
+}
+
+console.log('\n=== Done ===');
+console.log('Next steps:');
+console.log('  1. Fund your wallet with USDC (even 0.01 is enough)');
+console.log('  2. Use wzrd_deposit to enter a market');
+console.log('  3. Wait ~10 min for scoring cycle');
+console.log('  4. Use wzrd_claim to harvest CCM (gasless — no SOL needed)');

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@wzrd_sol/solana-agent-plugin",
+  "version": "0.1.0",
+  "description": "WZRD Liquid Attention Protocol plugin for Solana Agent Kit — deposit, claim, leaderboard, portfolio, velocity signal",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@solana/web3.js": "^1.95.0",
+    "@wzrd_sol/sdk": "^0.1.0",
+    "tweetnacl": "^1.0.3"
+  },
+  "peerDependencies": {
+    "solana-agent-kit": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "solana-agent-kit": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "solana",
+    "agent",
+    "wzrd",
+    "attention",
+    "defi",
+    "mcp",
+    "ai-agent",
+    "solana-agent-kit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/twzrd-sol/wzrd-final"
+  }
+}

package/src/actions/claim.ts

@@ -0,0 +1,98 @@
+/**
+ * Action: wzrd_claim
+ *
+ * Claim accrued CCM tokens via the gasless relay.
+ * Server pays tx fees — agent doesn't need SOL to claim.
+ *
+ * Flow: check claimable amount → relay claim → receive CCM.
+ */
+
+import type { WzrdClient } from '../client.js';
+
+export const CLAIM_ACTION = {
+  name: 'wzrd_claim',
+  similes: ['wzrd_harvest', 'claim_ccm', 'redeem_rewards', 'collect_yield'],
+  description:
+    'Claim accrued CCM tokens from your WZRD positions. Uses the gasless relay — ' +
+    'the server pays transaction fees, so you don\'t need SOL to claim. ' +
+    'CCM accrues based on your velocity multiplier and is distributed via ' +
+    'merkle proofs published on-chain every ~10 minutes. ' +
+    'Call this periodically to harvest your earned CCM.',
+
+  examples: [
+    [
+      {
+        user: 'user',
+        content: { text: 'Claim my CCM rewards' },
+      },
+      {
+        user: 'assistant',
+        content: {
+          text: 'Claimed 100,000 CCM via gasless relay. ' +
+            'Cumulative total: 250,000 CCM. Tx: 2VKz...J39c',
+        },
+      },
+    ],
+    [
+      {
+        user: 'user',
+        content: { text: 'How much CCM can I claim?' },
+      },
+      {
+        user: 'assistant',
+        content: {
+          text: 'You have 100,000 CCM claimable (250,000 cumulative, 150,000 already claimed). ' +
+            'Shall I claim it now?',
+        },
+      },
+    ],
+  ],
+
+  validate: async () => true,
+
+  handler: async (client: WzrdClient, params: { execute?: boolean }) => {
+    // 1. Check claimable amount
+    const claims = await client.getClaims();
+    const claimable = claims.cumulative_total - claims.claimed_total;
+
+    if (claimable <= 0) {
+      return {
+        success: true,
+        text:
+          `No CCM to claim. Cumulative: ${claims.cumulative_total}, ` +
+          `already claimed: ${claims.claimed_total}. ` +
+          `Deposit into markets and wait for the next scoring cycle.`,
+        data: claims,
+      };
+    }
+
+    // 2. If just checking (not executing), report the amount
+    if (params.execute === false) {
+      return {
+        success: true,
+        text:
+          `${claimable} CCM claimable ` +
+          `(${claims.cumulative_total} cumulative, ${claims.claimed_total} claimed). ` +
+          `Root seq: ${claims.root_seq}. Call with execute=true to claim.`,
+        data: claims,
+      };
+    }
+
+    // 3. Execute gasless relay claim
+    const result = await client.claimRelay();
+
+    return {
+      success: true,
+      text:
+        `Claimed CCM via gasless relay. ` +
+        `Cumulative total: ${result.cumulative_total}. ` +
+        `Root seq: ${result.root_seq}. ` +
+        `Tx: ${result.tx_sig.slice(0, 16)}...`,
+      data: {
+        ...result,
+        claimable_before: claimable,
+        explorer: `https://solscan.io/tx/${result.tx_sig}`,
+      },
+    };
+  },
+};

package/src/actions/deposit.ts

@@ -0,0 +1,197 @@
+/**
+ * Action: wzrd_deposit
+ *
+ * Deposit USDC into a WZRD attention market → mint vLOFI tokens.
+ * Requires: Keypair with USDC balance + SOL for tx fees.
+ *
+ * The agent picks a market_id (from leaderboard), specifies USDC amount,
+ * and the handler builds + signs + sends the deposit transaction.
+ */
+
+import {
+  Connection,
+  Keypair,
+  ComputeBudgetProgram,
+  TransactionMessage,
+  VersionedTransaction,
+} from '@solana/web3.js';
+import {
+  createDepositMarketIx,
+  fetchOnChainPosition,
+  fetchTokenBalance,
+  getAta,
+  TOKEN_PROGRAM_ID,
+} from '@wzrd_sol/sdk';
+
+import type { WzrdClient } from '../client.js';
+
+const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const CONFIRM_TIMEOUT_MS = 60_000;
+
+export interface DepositParams {
+  market_id: number;
+  amount_usdc: number;
+  priority_fee?: number; // microLamports per CU, default 50_000
+}
+
+export const DEPOSIT_ACTION = {
+  name: 'wzrd_deposit',
+  similes: ['wzrd_invest', 'deposit_usdc', 'buy_attention', 'enter_market'],
+  description:
+    'Deposit USDC into a WZRD attention market to mint vLOFI tokens. ' +
+    'vLOFI represents your position in the market. As the underlying AI model ' +
+    'gains attention (downloads, stars), your multiplier increases and you earn ' +
+    'more CCM on each merkle root publication. ' +
+    'Requires: market_id (from leaderboard) and amount_usdc (e.g., 0.01). ' +
+    'The deposit is atomic — USDC is transferred and vLOFI is minted in one transaction.',
+
+  examples: [
+    [
+      {
+        user: 'user',
+        content: { text: 'Deposit 0.01 USDC into market 10' },
+      },
+      {
+        user: 'assistant',
+        content: {
+          text: 'Deposited 0.01 USDC into Market #10 (Qwen 2.5 72B). ' +
+            'Received 10,000 vLOFI. Tx: X7FG...Cziv (772ms, 50687 CU)',
+        },
+      },
+    ],
+    [
+      {
+        user: 'user',
+        content: { text: 'Invest in the highest velocity market' },
+      },
+      {
+        user: 'assistant',
+        content: {
+          text: 'Looking up leaderboard... Top market is #16 (Qwen 3.5 35B) ' +
+            'with 804K velocity. Depositing 0.01 USDC...',
+        },
+      },
+    ],
+  ],
+
+  validate: async (_client: WzrdClient, params: DepositParams) => {
+    if (!params.market_id || params.market_id < 1) return false;
+    if (!params.amount_usdc || params.amount_usdc <= 0) return false;
+    if (params.amount_usdc > 100) return false; // safety cap
+    return true;
+  },
+
+  handler: async (
+    _client: WzrdClient,
+    params: DepositParams,
+    connection: Connection,
+    wallet: Keypair,
+  ) => {
+    const { market_id, amount_usdc, priority_fee = 50_000 } = params;
+    const amountNative = BigInt(Math.round(amount_usdc * 1_000_000));
+    const t0 = Date.now();
+
+    // 1. Idempotency — check existing position
+    const existing = await fetchOnChainPosition(
+      connection,
+      wallet.publicKey,
+      market_id,
+    );
+    if (existing && existing.depositedAmount > 0n && !existing.settled) {
+      return {
+        success: false,
+        text: `Position already exists in market ${market_id} ` +
+          `(${existing.depositedAmount} deposited). Cannot double-deposit.`,
+      };
+    }
+
+    // 2. Balance checks
+    const { PublicKey } = await import('@solana/web3.js');
+    const usdcMint = new PublicKey(USDC_MINT);
+    const usdcAta = getAta(wallet.publicKey, usdcMint, TOKEN_PROGRAM_ID);
+    const usdcBalance = await fetchTokenBalance(connection, usdcAta);
+    if (usdcBalance < amountNative) {
+      return {
+        success: false,
+        text: `Insufficient USDC: have ${Number(usdcBalance) / 1e6}, need ${amount_usdc}`,
+      };
+    }
+
+    const solBalance = await connection.getBalance(wallet.publicKey);
+    if (solBalance < 10_000) {
+      return {
+        success: false,
+        text: `Insufficient SOL for tx fees: ${solBalance} lamports`,
+      };
+    }
+
+    // 3. Build deposit instructions
+    const ixs = await createDepositMarketIx(
+      connection,
+      wallet.publicKey,
+      market_id,
+      amountNative,
+    );
+
+    ixs.unshift(
+      ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }),
+      ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priority_fee }),
+    );
+
+    // 4. Simulate
+    const { blockhash, lastValidBlockHeight } =
+      await connection.getLatestBlockhash('confirmed');
+    const message = new TransactionMessage({
+      payerKey: wallet.publicKey,
+      recentBlockhash: blockhash,
+      instructions: ixs,
+    }).compileToV0Message();
+
+    const tx = new VersionedTransaction(message);
+    tx.sign([wallet]);
+
+    const sim = await connection.simulateTransaction(tx);
+    if (sim.value.err) {
+      return {
+        success: false,
+        text: `Simulation failed: ${JSON.stringify(sim.value.err)}`,
+        data: { logs: sim.value.logs?.slice(-5) },
+      };
+    }
+
+    // 5. Send + confirm
+    const signature = await connection.sendTransaction(tx, {
+      skipPreflight: true,
+      maxRetries: 3,
+    });
+
+    const confirmed = connection.confirmTransaction(
+      { signature, blockhash, lastValidBlockHeight },
+      'confirmed',
+    );
+    const timeout = new Promise<never>((_, reject) =>
+      setTimeout(
+        () => reject(new Error(`Timeout after ${CONFIRM_TIMEOUT_MS}ms`)),
+        CONFIRM_TIMEOUT_MS,
+      ),
+    );
+
+    await Promise.race([confirmed, timeout]);
+    const elapsed = Date.now() - t0;
+
+    return {
+      success: true,
+      text:
+        `Deposited ${amount_usdc} USDC into Market #${market_id}. ` +
+        `Tx: ${signature.slice(0, 16)}... (${elapsed}ms, ${sim.value.unitsConsumed} CU)`,
+      data: {
+        signature,
+        market_id,
+        amount_usdc,
+        cu_used: sim.value.unitsConsumed,
+        elapsed_ms: elapsed,
+        explorer: `https://solscan.io/tx/${signature}`,
+      },
+    };
+  },
+};

package/src/actions/index.ts

@@ -0,0 +1,5 @@
+export { LEADERBOARD_ACTION } from './leaderboard.js';
+export { PORTFOLIO_ACTION } from './portfolio.js';
+export { DEPOSIT_ACTION } from './deposit.js';
+export { CLAIM_ACTION } from './claim.js';
+export { VELOCITY_ACTION } from './velocity.js';

package/src/actions/leaderboard.ts

@@ -0,0 +1,81 @@
+/**
+ * Action: wzrd_leaderboard
+ *
+ * Fetch the WZRD attention market leaderboard — ranked by velocity EMA.
+ * No auth required. Permissionless read.
+ */
+
+import type { WzrdClient, WzrdMarket } from '../client.js';
+
+export const LEADERBOARD_ACTION = {
+  name: 'wzrd_leaderboard',
+  similes: ['wzrd_markets', 'wzrd_trending', 'attention_markets', 'top_models'],
+  description:
+    'Fetch the WZRD attention market leaderboard. Shows AI models and open-source ' +
+    'projects ranked by real-time velocity (download/star momentum). Returns market IDs, ' +
+    'velocity EMA, multiplier, TVL, and platform (huggingface/github). ' +
+    'Use this to find the highest-attention markets before depositing.',
+
+  examples: [
+    [
+      {
+        user: 'user',
+        content: { text: 'Show me the top attention markets' },
+      },
+      {
+        user: 'assistant',
+        content: {
+          text: 'Here are the top WZRD markets by velocity:\n' +
+            '1. Qwen 3.5 35B — 804K velocity (HuggingFace)\n' +
+            '2. Qwen 3.5 9B — 769K velocity (HuggingFace)\n' +
+            '3. Ollama — 104K velocity (GitHub)',
+        },
+      },
+    ],
+    [
+      {
+        user: 'user',
+        content: { text: 'What HuggingFace models are trending?' },
+      },
+      {
+        user: 'assistant',
+        content: {
+          text: 'Top HuggingFace models by attention velocity: ...',
+        },
+      },
+    ],
+  ],
+
+  validate: async () => true,
+
+  handler: async (
+    client: WzrdClient,
+    params: { limit?: number; platform?: string },
+  ) => {
+    const data = await client.getLeaderboard(
+      params.limit ?? 10,
+      params.platform,
+    );
+
+    const lines = data.markets.map(
+      (m: WzrdMarket, i: number) =>
+        `${i + 1}. ${m.metric} — ${formatVelocity(m.velocity_ema)} velocity ` +
+        `(${m.platform}) | ${m.multiplier_bps / 10000}x multiplier | ` +
+        `${m.position_count} positions | market_id=${m.market_id}`,
+    );
+
+    return {
+      success: true,
+      text:
+        `WZRD Leaderboard (${data.markets.length} markets, ` +
+        `root_seq=${data.root.root_seq}):\n${lines.join('\n')}`,
+      data,
+    };
+  },
+};
+
+function formatVelocity(v: number): string {
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1_000) return `${(v / 1_000).toFixed(0)}K`;
+  return v.toFixed(0);
+}

package/src/actions/portfolio.ts

@@ -0,0 +1,62 @@
+/**
+ * Action: wzrd_portfolio
+ *
+ * Fetch the agent's WZRD portfolio — positions, USDC deposited, vLOFI held, CCM earned.
+ * Requires auth (Ed25519 agent session).
+ */
+
+import type { WzrdClient, WzrdPosition } from '../client.js';
+
+export const PORTFOLIO_ACTION = {
+  name: 'wzrd_portfolio',
+  similes: ['wzrd_positions', 'wzrd_balance', 'wzrd_holdings', 'my_positions'],
+  description:
+    'Fetch your WZRD portfolio — all open positions across attention markets. ' +
+    'Shows USDC deposited, vLOFI minted, multiplier, and settlement status per market. ' +
+    'Use this to check your exposure before depositing more or claiming CCM.',
+
+  examples: [
+    [
+      {
+        user: 'user',
+        content: { text: 'Show my WZRD positions' },
+      },
+      {
+        user: 'assistant',
+        content: {
+          text: 'Your WZRD portfolio:\n' +
+            '• Market #10 (Qwen 2.5 72B): 0.01 USDC, 5.0x multiplier\n' +
+            '• Market #8 (Ollama): 0.01 USDC, 5.0x multiplier\n' +
+            'Total: 0.02 USDC deposited, 0 CCM earned',
+        },
+      },
+    ],
+  ],
+
+  validate: async () => true,
+
+  handler: async (client: WzrdClient) => {
+    const portfolio = await client.getPortfolio();
+
+    const open = portfolio.positions.filter((p: WzrdPosition) => !p.is_settled);
+    const lines = open.map(
+      (p: WzrdPosition) =>
+        `• Market #${p.market_id} (${p.metric}): ` +
+        `${(p.usdc_deposited / 1_000_000).toFixed(4)} USDC, ` +
+        `${(p.multiplier_bps / 10_000).toFixed(1)}x multiplier` +
+        (p.is_settled ? ' [settled]' : ''),
+    );
+
+    const totalUsdc = portfolio.total_deposited_usdc / 1_000_000;
+    const totalCcm = portfolio.total_ccm_earned / 1_000_000;
+
+    return {
+      success: true,
+      text:
+        `Your WZRD portfolio (${open.length} open positions):\n` +
+        `${lines.length ? lines.join('\n') : '(no positions)'}\n` +
+        `Total: ${totalUsdc.toFixed(4)} USDC deposited, ${totalCcm.toFixed(4)} CCM earned`,
+      data: portfolio,
+    };
+  },
+};