@wzrd_sol/solana-agent-plugin 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @wzrd_sol/solana-agent-plugin
+
+WZRD Liquid Attention Protocol plugin for autonomous Solana agents. Provides 5 actions for interacting with WZRD attention markets: browse the leaderboard, classify velocity signals, view portfolio positions, deposit USDC to mint vLOFI, and claim CCM yield via gasless relay.
+
+Works standalone, with [Solana Agent Kit](https://github.com/sendAI/solana-agent-kit), or as a base for ElizaOS action wrappers.
+
+## Install
+
+```bash
+npm install @wzrd_sol/solana-agent-plugin
+```
+
+## Quick Start
+
+```typescript
+import { Keypair } from '@solana/web3.js';
+import { WzrdClient } from '@wzrd_sol/solana-agent-plugin';
+
+// Any Ed25519 keypair — used for agent auth
+const keypair = Keypair.generate();
+const client = new WzrdClient(keypair);
+
+// Browse attention markets (no auth required)
+const leaderboard = await client.getLeaderboard();
+console.log(leaderboard.markets.map(m => `${m.channel_id}: ${m.velocity_ema}`));
+
+// Authenticated endpoints (auto-handles challenge/verify flow)
+const portfolio = await client.getPortfolio();
+const claims = await client.getClaims();
+const result = await client.claimRelay(); // gasless CCM claim
+```
+
+## Actions
+
+The plugin exports 5 actions that follow the Solana Agent Kit action interface:
+
+| Action | Auth | Description |
+|--------|------|-------------|
+| `LEADERBOARD_ACTION` | No | Fetch ranked attention markets |
+| `VELOCITY_ACTION` | No | Classify signal strength (BREAKOUT / MOMENTUM / EMERGING / STABLE / COOLING / WEAK) |
+| `PORTFOLIO_ACTION` | Yes | View positions and CCM earned |
+| `DEPOSIT_ACTION` | Yes | Deposit USDC into a market, receive vLOFI |
+| `CLAIM_ACTION` | Yes | Claim CCM via server-paid gasless relay |
+
+```typescript
+import { WZRD_ACTIONS, WZRD_PLUGIN } from '@wzrd_sol/solana-agent-plugin';
+
+// Register all actions with Solana Agent Kit
+// WZRD_PLUGIN.actions contains all 5 actions
+```
+
+## API
+
+### `new WzrdClient(keypair: Keypair, apiUrl?: string)`
+
+Creates a client instance. The keypair is used for Ed25519 agent authentication. Default API URL is `https://api.twzrd.xyz`.
+
+### Methods
+
+- `getLeaderboard(limit?: number, platform?: string)` -- no auth
+- `getPortfolio()` -- authenticated
+- `getClaims()` -- authenticated
+- `claimRelay()` -- authenticated, gasless
+- `getHealth()` -- no auth
+
+Auth is handled automatically: the client requests a challenge nonce, signs it with the keypair, and caches the bearer token (24h TTL, auto-refreshes).
+
+## License
+
+MIT

package/dist/actions/claim.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare const CLAIM_ACTION: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        user: string;
+        content: {
+            text: string;
+        };
+    }[][];
+    validate: () => Promise<boolean>;
+    handler: (client: WzrdClient, params: {
+        execute?: boolean;
+    }) => Promise<{
+        success: boolean;
+        text: string;
+        data: import("../client.js").WzrdClaim;
+    } | {
+        success: boolean;
+        text: string;
+        data: {
+            claimable_before: number;
+            explorer: string;
+            root_seq: number;
+            cumulative_total: number;
+            tx_sig: string;
+        };
+    }>;
+};

package/dist/actions/claim.js

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+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, params) => {
+        // 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/dist/actions/deposit.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 } from '@solana/web3.js';
+import type { WzrdClient } from '../client.js';
+export interface DepositParams {
+    market_id: number;
+    amount_usdc: number;
+    priority_fee?: number;
+}
+export declare const DEPOSIT_ACTION: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        user: string;
+        content: {
+            text: string;
+        };
+    }[][];
+    validate: (_client: WzrdClient, params: DepositParams) => Promise<boolean>;
+    handler: (_client: WzrdClient, params: DepositParams, connection: Connection, wallet: Keypair) => Promise<{
+        success: boolean;
+        text: string;
+        data?: undefined;
+    } | {
+        success: boolean;
+        text: string;
+        data: {
+            logs: string[] | undefined;
+            signature?: undefined;
+            market_id?: undefined;
+            amount_usdc?: undefined;
+            cu_used?: undefined;
+            elapsed_ms?: undefined;
+            explorer?: undefined;
+        };
+    } | {
+        success: boolean;
+        text: string;
+        data: {
+            signature: string;
+            market_id: number;
+            amount_usdc: number;
+            cu_used: number | undefined;
+            elapsed_ms: number;
+            explorer: string;
+            logs?: undefined;
+        };
+    }>;
+};

package/dist/actions/deposit.js

@@ -0,0 +1,134 @@
+/**
+ * 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 { ComputeBudgetProgram, TransactionMessage, VersionedTransaction, } from '@solana/web3.js';
+import { createDepositMarketIx, fetchOnChainPosition, fetchTokenBalance, getAta, TOKEN_PROGRAM_ID, } from '@wzrd_sol/sdk';
+const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const CONFIRM_TIMEOUT_MS = 60_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, params) => {
+        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, params, connection, wallet) => {
+        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((_, 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/dist/actions/index.d.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/dist/actions/index.js

@@ -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/dist/actions/leaderboard.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Action: wzrd_leaderboard
+ *
+ * Fetch the WZRD attention market leaderboard — ranked by velocity EMA.
+ * No auth required. Permissionless read.
+ */
+import type { WzrdClient } from '../client.js';
+export declare const LEADERBOARD_ACTION: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        user: string;
+        content: {
+            text: string;
+        };
+    }[][];
+    validate: () => Promise<boolean>;
+    handler: (client: WzrdClient, params: {
+        limit?: number;
+        platform?: string;
+    }) => Promise<{
+        success: boolean;
+        text: string;
+        data: import("../client.js").WzrdLeaderboard;
+    }>;
+};

package/dist/actions/leaderboard.js

@@ -0,0 +1,63 @@
+/**
+ * Action: wzrd_leaderboard
+ *
+ * Fetch the WZRD attention market leaderboard — ranked by velocity EMA.
+ * No auth required. Permissionless read.
+ */
+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, params) => {
+        const data = await client.getLeaderboard(params.limit ?? 10, params.platform);
+        const lines = data.markets.map((m, i) => `${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) {
+    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/dist/actions/portfolio.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Action: wzrd_portfolio
+ *
+ * Fetch the agent's WZRD portfolio — positions, USDC deposited, vLOFI held, CCM earned.
+ * Requires auth (Ed25519 agent session).
+ */
+import type { WzrdClient } from '../client.js';
+export declare const PORTFOLIO_ACTION: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        user: string;
+        content: {
+            text: string;
+        };
+    }[][];
+    validate: () => Promise<boolean>;
+    handler: (client: WzrdClient) => Promise<{
+        success: boolean;
+        text: string;
+        data: import("../client.js").WzrdPortfolio;
+    }>;
+};

package/dist/actions/portfolio.js

@@ -0,0 +1,48 @@
+/**
+ * Action: wzrd_portfolio
+ *
+ * Fetch the agent's WZRD portfolio — positions, USDC deposited, vLOFI held, CCM earned.
+ * Requires auth (Ed25519 agent session).
+ */
+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) => {
+        const portfolio = await client.getPortfolio();
+        const open = portfolio.positions.filter((p) => !p.is_settled);
+        const lines = open.map((p) => `• 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,
+        };
+    },
+};

package/dist/actions/velocity.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Action: wzrd_velocity
+ *
+ * Analyze attention velocity across markets — classify signal strength.
+ * No auth required. Pure analytics over leaderboard data.
+ *
+ * Signal tiers:
+ *   BREAKOUT  — top 10% velocity (p90+)
+ *   MOMENTUM  — p70-90
+ *   EMERGING  — new market (<300 snapshots) with above-median velocity
+ *   STABLE    — p40-70
+ *   COOLING   — p20-40
+ *   WEAK      — below p20
+ */
+import type { WzrdClient } from '../client.js';
+type SignalTier = 'BREAKOUT' | 'MOMENTUM' | 'EMERGING' | 'STABLE' | 'COOLING' | 'WEAK';
+export interface MarketSignal {
+    market_id: number;
+    metric: string;
+    platform: string;
+    velocity_ema: number;
+    signal: SignalTier;
+    percentile: number;
+}
+export declare const VELOCITY_ACTION: {
+    name: string;
+    similes: string[];
+    description: string;
+    examples: {
+        user: string;
+        content: {
+            text: string;
+        };
+    }[][];
+    validate: () => Promise<boolean>;
+    handler: (client: WzrdClient, params: {
+        platform?: string;
+        min_signal?: SignalTier;
+    }) => Promise<{
+        success: boolean;
+        text: string;
+        data: {
+            signals: never[];
+            median_velocity?: undefined;
+        };
+    } | {
+        success: boolean;
+        text: string;
+        data: {
+            signals: MarketSignal[];
+            median_velocity: number;
+        };
+    }>;
+};
+export {};