@wzrd_sol/solana-agent-plugin 0.1.0 → 0.1.2

package/README.md

@@ -4,12 +4,37 @@ WZRD Liquid Attention Protocol plugin for autonomous Solana agents. Provides 5 a
 
 Works standalone, with [Solana Agent Kit](https://github.com/sendAI/solana-agent-kit), or as a base for ElizaOS action wrappers.
 
+## 30-Second Test
+
+No Solana Agent Kit dependency is required for the first smoke test. The package is ESM-first, so use `type: "module"` and `import`.
+
+```bash
+mkdir wzrd-agent && cd wzrd-agent
+printf '{\"name\":\"wzrd-agent\",\"type\":\"module\",\"private\":true}\n' > package.json
+npm install @wzrd_sol/solana-agent-plugin @solana/web3.js
+curl -O https://raw.githubusercontent.com/twzrd-sol/wzrd-final/main/agents/solana-agent-kit-plugin/examples/hello-wzrd.mjs
+solana-keygen new -o /tmp/agent.json --no-bip39-passphrase
+WZRD_KEYPAIR_PATH=/tmp/agent.json node hello-wzrd.mjs
+```
+
+What you should see:
+- top markets
+- successful Ed25519 agent auth
+- portfolio or signup-bonus path
+- claimable CCM state
+
 ## Install
 
 ```bash
 npm install @wzrd_sol/solana-agent-plugin
 ```
 
+Install with Solana Agent Kit only when you are ready to execute through its action system:
+
+```bash
+npm install @wzrd_sol/solana-agent-plugin solana-agent-kit
+```
+
 ## Quick Start
 
 ```typescript
@@ -30,6 +55,18 @@ const claims = await client.getClaims();
 const result = await client.claimRelay(); // gasless CCM claim
 ```
 
+## Solana Agent Kit
+
+The package works standalone or as a Solana Agent Kit plugin.
+
+```typescript
+import { SolanaAgentKit } from 'solana-agent-kit';
+import { WZRD_PLUGIN } from '@wzrd_sol/solana-agent-plugin';
+
+const agent = new SolanaAgentKit(/* wallet + rpc + model config */);
+agent.use(WZRD_PLUGIN);
+```
+
 ## Actions
 
 The plugin exports 5 actions that follow the Solana Agent Kit action interface:
@@ -38,7 +75,7 @@ The plugin exports 5 actions that follow the Solana Agent Kit action interface:
 |--------|------|-------------|
 | `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 |
+| `PORTFOLIO_ACTION` | Yes | View portfolio positions |
 | `DEPOSIT_ACTION` | Yes | Deposit USDC into a market, receive vLOFI |
 | `CLAIM_ACTION` | Yes | Claim CCM via server-paid gasless relay |
 
@@ -65,6 +102,11 @@ Creates a client instance. The keypair is used for Ed25519 agent authentication.
 
 Auth is handled automatically: the client requests a challenge nonce, signs it with the keypair, and caches the bearer token (24h TTL, auto-refreshes).
 
+For an end-to-end smoke test, use [`examples/hello-wzrd.mjs`](./examples/hello-wzrd.mjs). It works with just:
+- `@wzrd_sol/solana-agent-plugin`
+- `@solana/web3.js`
+- `WZRD_KEYPAIR_PATH=/path/to/keypair.json`
+
 ## License
 
 MIT

package/dist/actions/claim.d.ts

@@ -6,33 +6,14 @@
  *
  * 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;
-        };
-    }>;
-};
+import { z } from 'zod';
+import type { Action, SolanaAgentKit } from 'solana-agent-kit';
+export declare const claimSchema: z.ZodObject<{
+    execute: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    execute?: boolean | undefined;
+}, {
+    execute?: boolean | undefined;
+}>;
+export declare function claimHandler(agent: SolanaAgentKit, input: z.infer<typeof claimSchema>): Promise<Record<string, unknown>>;
+export declare const CLAIM_ACTION: Action;

package/dist/actions/claim.js

@@ -6,6 +6,55 @@
  *
  * Flow: check claimable amount → relay claim → receive CCM.
  */
+import { z } from 'zod';
+import { formatCcm, getClaimsData, getClientForAgent } from '../runtime.js';
+export const claimSchema = z.object({
+    execute: z.boolean().optional(),
+});
+export async function claimHandler(agent, input) {
+    const claims = await getClaimsData(agent);
+    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,
+        };
+    }
+    if (input.execute === false) {
+        return {
+            success: true,
+            text: `${formatCcm(claimable)} CCM claimable ` +
+                `(${formatCcm(claims.cumulative_total)} cumulative, ` +
+                `${formatCcm(claims.claimed_total)} claimed). ` +
+                `Root seq: ${claims.root_seq}. Call with execute=true to claim.`,
+            data: claims,
+        };
+    }
+    const result = await getClientForAgent(agent).claimRelay();
+    if (result.status === 'already_claimed') {
+        return {
+            success: true,
+            text: `Already claimed through root ${result.root_seq}. ` +
+                `Claimed total: ${formatCcm(result.claimed_total ?? claims.claimed_total)} CCM.`,
+            data: result,
+        };
+    }
+    return {
+        success: true,
+        text: `Claimed CCM via gasless relay. ` +
+            `Cumulative total: ${formatCcm(result.cumulative_total)}. ` +
+            `Root seq: ${result.root_seq}. ` +
+            `Tx: ${result.tx_sig?.slice(0, 16)}...`,
+        data: {
+            ...result,
+            claimable_before: claimable,
+            explorer: result.tx_sig ? `https://solscan.io/tx/${result.tx_sig}` : null,
+        },
+    };
+}
 export const CLAIM_ACTION = {
     name: 'wzrd_claim',
     similes: ['wzrd_harvest', 'claim_ccm', 'redeem_rewards', 'collect_yield'],
@@ -17,68 +66,16 @@ export const CLAIM_ACTION = {
     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?',
+                input: { execute: false },
+                output: {
+                    success: true,
+                    claimable: 100000,
+                    cumulative_total: 250000,
                 },
+                explanation: 'Check how much CCM is available before triggering a relay claim.',
             },
         ],
     ],
-    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}`,
-            },
-        };
-    },
+    schema: claimSchema,
+    handler: async (agent, input) => claimHandler(agent, claimSchema.parse(input)),
 };

package/dist/actions/deposit.d.ts

@@ -7,51 +7,20 @@
  * 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 {
+import { z } from 'zod';
+import type { Action, SolanaAgentKit } from 'solana-agent-kit';
+export declare const depositSchema: z.ZodObject<{
+    market_id: z.ZodNumber;
+    amount_usdc: z.ZodNumber;
+    priority_fee: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
     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;
-        };
-    }>;
-};
+    priority_fee?: number | undefined;
+}, {
+    market_id: number;
+    amount_usdc: number;
+    priority_fee?: number | undefined;
+}>;
+export declare function depositHandler(agent: SolanaAgentKit, input: z.infer<typeof depositSchema>): Promise<Record<string, unknown>>;
+export declare const DEPOSIT_ACTION: Action;

package/dist/actions/deposit.js

@@ -8,9 +8,147 @@
  * 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';
+import { z } from 'zod';
+import { formatUsdc, getWalletPublicKey } from '../runtime.js';
 const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
 const CONFIRM_TIMEOUT_MS = 60_000;
+export const depositSchema = z.object({
+    market_id: z.number().int().min(1),
+    amount_usdc: z.number().positive().max(100),
+    priority_fee: z.number().int().positive().optional(),
+});
+export async function depositHandler(agent, input) {
+    const { market_id, amount_usdc, priority_fee = 50_000 } = input;
+    const connection = agent.connection;
+    const payer = getWalletPublicKey(agent);
+    const amountNative = BigInt(Math.round(amount_usdc * 1_000_000));
+    const t0 = Date.now();
+    const sdk = await loadSdk();
+    const { createDepositMarketIx, fetchMarketVault, fetchOnChainPosition, fetchTokenBalance, getAta, TOKEN_PROGRAM_ID, } = sdk;
+    const vault = await fetchMarketVault(connection, market_id);
+    if (!vault) {
+        return {
+            success: false,
+            text: `Market ${market_id} is listed but does not have an on-chain vault yet. ` +
+                'Pick a market with an initialized vault before depositing.',
+            data: { market_id, reason: 'missing_vault' },
+        };
+    }
+    const existing = await fetchOnChainPosition(connection, payer, market_id);
+    if (existing && existing.depositedAmount > 0n && !existing.settled) {
+        return {
+            success: false,
+            text: `Position already exists in market ${market_id} ` +
+                `(${formatUsdc(existing.depositedAmount)} USDC deposited). Cannot double-deposit.`,
+            data: { market_id, deposited_amount: existing.depositedAmount.toString() },
+        };
+    }
+    const usdcAta = getAta(payer, vault.depositMint, TOKEN_PROGRAM_ID);
+    const usdcBalance = await fetchTokenBalance(connection, usdcAta);
+    if (usdcBalance < amountNative) {
+        return {
+            success: false,
+            text: `Insufficient USDC: have ${formatUsdc(usdcBalance)}, need ${amount_usdc.toFixed(4)}`,
+            data: {
+                market_id,
+                required_native: amountNative.toString(),
+                balance_native: usdcBalance.toString(),
+            },
+        };
+    }
+    const solBalance = await connection.getBalance(payer);
+    if (solBalance < 10_000) {
+        return {
+            success: false,
+            text: `Insufficient SOL for tx fees: ${solBalance} lamports`,
+            data: { market_id, sol_balance_lamports: solBalance },
+        };
+    }
+    let ixs;
+    try {
+        ixs = await createDepositMarketIx(connection, payer, market_id, amountNative);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('MarketVault not found')) {
+            return {
+                success: false,
+                text: `Market ${market_id} does not have a live vault yet. ` +
+                    'Choose a depositable market and retry.',
+                data: { market_id, reason: 'missing_vault' },
+            };
+        }
+        throw error;
+    }
+    ixs.unshift(ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }), ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priority_fee }));
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
+    const message = new TransactionMessage({
+        payerKey: payer,
+        recentBlockhash: blockhash,
+        instructions: ixs,
+    }).compileToV0Message();
+    const tx = new VersionedTransaction(message);
+    const signedTx = await agent.wallet.signTransaction(tx);
+    const sim = await connection.simulateTransaction(signedTx);
+    if (sim.value.err) {
+        return {
+            success: false,
+            text: `Simulation failed: ${JSON.stringify(sim.value.err)}`,
+            data: { market_id, logs: sim.value.logs?.slice(-5) ?? [] },
+        };
+    }
+    const { signature } = await agent.wallet.signAndSendTransaction(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));
+    try {
+        await Promise.race([confirmed, timeout]);
+    }
+    catch (error) {
+        return {
+            success: true,
+            text: `Deposit transaction sent for Market #${market_id}, but confirmation timed out. ` +
+                `Tx: ${signature}`,
+            data: {
+                signature,
+                market_id,
+                amount_usdc,
+                timed_out: true,
+                explorer: `https://solscan.io/tx/${signature}`,
+            },
+        };
+    }
+    const elapsed = Date.now() - t0;
+    return {
+        success: true,
+        text: `Deposited ${amount_usdc.toFixed(4)} 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}`,
+        },
+    };
+}
+async function loadSdk() {
+    try {
+        return await import('@wzrd_sol/sdk');
+    }
+    catch (error) {
+        const fallbackUrl = new URL('../../../../sdk/dist/index.js', import.meta.url);
+        try {
+            return (await import(fallbackUrl.href));
+        }
+        catch {
+            throw error;
+        }
+    }
+}
 export const DEPOSIT_ACTION = {
     name: 'wzrd_deposit',
     similes: ['wzrd_invest', 'deposit_usdc', 'buy_attention', 'enter_market'],
@@ -23,112 +161,17 @@ export const DEPOSIT_ACTION = {
     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...',
+                input: { market_id: 10, amount_usdc: 0.01 },
+                output: {
+                    success: true,
+                    market_id: 10,
+                    amount_usdc: 0.01,
+                    signature: 'X7FG...',
                 },
+                explanation: 'Deposit 0.01 USDC into a known vaulted market and mint vLOFI.',
             },
         ],
     ],
-    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}`,
-            },
-        };
-    },
+    schema: depositSchema,
+    handler: async (agent, input) => depositHandler(agent, depositSchema.parse(input)),
 };

package/dist/actions/index.d.ts

@@ -1,3 +1,4 @@
+export type { MarketSignal } from './velocity.js';
 export { LEADERBOARD_ACTION } from './leaderboard.js';
 export { PORTFOLIO_ACTION } from './portfolio.js';
 export { DEPOSIT_ACTION } from './deposit.js';

package/dist/actions/leaderboard.d.ts

@@ -4,24 +4,17 @@
  * 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;
-    }>;
-};
+import { z } from 'zod';
+import type { Action, SolanaAgentKit } from 'solana-agent-kit';
+export declare const leaderboardSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+    platform: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+    platform?: string | undefined;
+}, {
+    limit?: number | undefined;
+    platform?: string | undefined;
+}>;
+export declare function leaderboardHandler(agent: SolanaAgentKit, input: z.infer<typeof leaderboardSchema>): Promise<Record<string, unknown>>;
+export declare const LEADERBOARD_ACTION: Action;