@wzrd_sol/solana-agent-plugin 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -12,7 +12,7 @@
  *
  * Works with:
  *   - Solana Agent Kit (SendAI) — register as plugin
- *   - ElizaOS — wrap actions as ElizaOS Actions
+ *   - ElizaOS — wrap actions as ELIZA-style actions
  *   - Standalone — use WzrdClient directly
  *
  * Quick start:
@@ -23,275 +23,20 @@
 export { WzrdClient } from './client.js';
 export type { WzrdMarket, WzrdLeaderboard, WzrdPosition, WzrdPortfolio, WzrdClaim, WzrdRelayResult, } from './client.js';
 export { LEADERBOARD_ACTION, PORTFOLIO_ACTION, DEPOSIT_ACTION, CLAIM_ACTION, VELOCITY_ACTION, } from './actions/index.js';
-export declare const WZRD_ACTIONS: readonly [{
-    name: string;
-    similes: string[];
-    description: string;
-    examples: {
-        user: string;
-        content: {
-            text: string;
-        };
-    }[][];
-    validate: () => Promise<boolean>;
-    handler: (client: import("./client.js").WzrdClient, params: {
-        limit?: number;
-        platform?: string;
-    }) => Promise<{
-        success: boolean;
-        text: string;
-        data: import("./client.js").WzrdLeaderboard;
-    }>;
-}, {
-    name: string;
-    similes: string[];
-    description: string;
-    examples: {
-        user: string;
-        content: {
-            text: string;
-        };
-    }[][];
-    validate: () => Promise<boolean>;
-    handler: (client: import("./client.js").WzrdClient) => Promise<{
-        success: boolean;
-        text: string;
-        data: import("./client.js").WzrdPortfolio;
-    }>;
-}, {
-    name: string;
-    similes: string[];
-    description: string;
-    examples: {
-        user: string;
-        content: {
-            text: string;
-        };
-    }[][];
-    validate: (_client: import("./client.js").WzrdClient, params: import("./actions/deposit.js").DepositParams) => Promise<boolean>;
-    handler: (_client: import("./client.js").WzrdClient, params: import("./actions/deposit.js").DepositParams, connection: import("@solana/web3.js").Connection, wallet: import("@solana/web3.js").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;
-        };
-    }>;
-}, {
-    name: string;
-    similes: string[];
-    description: string;
-    examples: {
-        user: string;
-        content: {
-            text: string;
-        };
-    }[][];
-    validate: () => Promise<boolean>;
-    handler: (client: import("./client.js").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;
-        };
-    }>;
-}, {
-    name: string;
-    similes: string[];
-    description: string;
-    examples: {
-        user: string;
-        content: {
-            text: string;
-        };
-    }[][];
-    validate: () => Promise<boolean>;
-    handler: (client: import("./client.js").WzrdClient, params: {
-        platform?: string;
-        min_signal?: "BREAKOUT" | "MOMENTUM" | "EMERGING" | "STABLE" | "COOLING" | "WEAK";
-    }) => Promise<{
-        success: boolean;
-        text: string;
-        data: {
-            signals: never[];
-            median_velocity?: undefined;
-        };
-    } | {
-        success: boolean;
-        text: string;
-        data: {
-            signals: import("./actions/velocity.js").MarketSignal[];
-            median_velocity: number;
-        };
-    }>;
-}];
-/** Plugin metadata for framework registration. */
-export declare const WZRD_PLUGIN: {
-    name: string;
-    description: string;
-    actions: readonly [{
-        name: string;
-        similes: string[];
-        description: string;
-        examples: {
-            user: string;
-            content: {
-                text: string;
-            };
-        }[][];
-        validate: () => Promise<boolean>;
-        handler: (client: import("./client.js").WzrdClient, params: {
-            limit?: number;
-            platform?: string;
-        }) => Promise<{
-            success: boolean;
-            text: string;
-            data: import("./client.js").WzrdLeaderboard;
-        }>;
-    }, {
-        name: string;
-        similes: string[];
-        description: string;
-        examples: {
-            user: string;
-            content: {
-                text: string;
-            };
-        }[][];
-        validate: () => Promise<boolean>;
-        handler: (client: import("./client.js").WzrdClient) => Promise<{
-            success: boolean;
-            text: string;
-            data: import("./client.js").WzrdPortfolio;
-        }>;
-    }, {
-        name: string;
-        similes: string[];
-        description: string;
-        examples: {
-            user: string;
-            content: {
-                text: string;
-            };
-        }[][];
-        validate: (_client: import("./client.js").WzrdClient, params: import("./actions/deposit.js").DepositParams) => Promise<boolean>;
-        handler: (_client: import("./client.js").WzrdClient, params: import("./actions/deposit.js").DepositParams, connection: import("@solana/web3.js").Connection, wallet: import("@solana/web3.js").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;
-            };
-        }>;
-    }, {
-        name: string;
-        similes: string[];
-        description: string;
-        examples: {
-            user: string;
-            content: {
-                text: string;
-            };
-        }[][];
-        validate: () => Promise<boolean>;
-        handler: (client: import("./client.js").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;
-            };
-        }>;
-    }, {
-        name: string;
-        similes: string[];
-        description: string;
-        examples: {
-            user: string;
-            content: {
-                text: string;
-            };
-        }[][];
-        validate: () => Promise<boolean>;
-        handler: (client: import("./client.js").WzrdClient, params: {
-            platform?: string;
-            min_signal?: "BREAKOUT" | "MOMENTUM" | "EMERGING" | "STABLE" | "COOLING" | "WEAK";
-        }) => Promise<{
-            success: boolean;
-            text: string;
-            data: {
-                signals: never[];
-                median_velocity?: undefined;
-            };
-        } | {
-            success: boolean;
-            text: string;
-            data: {
-                signals: import("./actions/velocity.js").MarketSignal[];
-                median_velocity: number;
-            };
-        }>;
-    }];
-    version: string;
-};
+export type { MarketSignal } from './actions/index.js';
+import type { Plugin } from 'solana-agent-kit';
+import { getClaimsData, getClientForAgent, getLeaderboardData } from './runtime.js';
+import { type MarketSignal } from './actions/velocity.js';
+export declare const WZRD_ACTIONS: Plugin["actions"];
+export interface WzrdPluginMethods {
+    wzrdLeaderboard(limit?: number, platform?: string): Promise<ReturnType<typeof getLeaderboardData>>;
+    wzrdPortfolio(): Promise<ReturnType<typeof getClientForAgent>['getPortfolio']>;
+    wzrdClaims(): Promise<ReturnType<typeof getClaimsData>>;
+    wzrdDeposit(marketId: number, amountUsdc: number, priorityFee?: number): Promise<Record<string, unknown>>;
+    wzrdClaim(execute?: boolean): Promise<Record<string, unknown>>;
+    wzrdVelocity(platform?: string, minSignal?: MarketSignal['signal']): Promise<Record<string, unknown>>;
+    wzrdClient(): ReturnType<typeof getClientForAgent>;
+}
+export declare function createWzrdPlugin(): Plugin;
+/** Default plugin instance for direct registration via `agent.use(...)`. */
+export declare const WZRD_PLUGIN: Plugin;

package/dist/index.js

@@ -12,7 +12,7 @@
  *
  * Works with:
  *   - Solana Agent Kit (SendAI) — register as plugin
- *   - ElizaOS — wrap actions as ElizaOS Actions
+ *   - ElizaOS — wrap actions as ELIZA-style actions
  *   - Standalone — use WzrdClient directly
  *
  * Quick start:
@@ -22,12 +22,12 @@
  */
 export { WzrdClient } from './client.js';
 export { LEADERBOARD_ACTION, PORTFOLIO_ACTION, DEPOSIT_ACTION, CLAIM_ACTION, VELOCITY_ACTION, } from './actions/index.js';
-// ── Convenience: all actions as array ────────────────────
+import { getClaimsData, getClientForAgent, getLeaderboardData } from './runtime.js';
 import { LEADERBOARD_ACTION } from './actions/leaderboard.js';
 import { PORTFOLIO_ACTION } from './actions/portfolio.js';
-import { DEPOSIT_ACTION } from './actions/deposit.js';
-import { CLAIM_ACTION } from './actions/claim.js';
-import { VELOCITY_ACTION } from './actions/velocity.js';
+import { DEPOSIT_ACTION, depositHandler } from './actions/deposit.js';
+import { CLAIM_ACTION, claimHandler } from './actions/claim.js';
+import { VELOCITY_ACTION, velocityHandler } from './actions/velocity.js';
 export const WZRD_ACTIONS = [
     LEADERBOARD_ACTION,
     PORTFOLIO_ACTION,
@@ -35,10 +35,51 @@ export const WZRD_ACTIONS = [
     CLAIM_ACTION,
     VELOCITY_ACTION,
 ];
-/** Plugin metadata for framework registration. */
-export const WZRD_PLUGIN = {
-    name: 'wzrd',
-    description: 'WZRD Liquid Attention Protocol — deposit USDC into AI attention markets, earn CCM yield',
-    actions: WZRD_ACTIONS,
-    version: '0.1.0',
-};
+export function createWzrdPlugin() {
+    let agentRef = null;
+    const requireAgent = () => {
+        if (!agentRef) {
+            throw new Error('WZRD plugin has not been initialized with a SolanaAgentKit instance');
+        }
+        return agentRef;
+    };
+    return {
+        name: 'wzrd',
+        initialize(agent) {
+            agentRef = agent;
+        },
+        methods: {
+            wzrdClient() {
+                return getClientForAgent(requireAgent());
+            },
+            async wzrdLeaderboard(limit = 20, platform) {
+                return getLeaderboardData(requireAgent(), { limit, platform });
+            },
+            async wzrdPortfolio() {
+                return getClientForAgent(requireAgent()).getPortfolio();
+            },
+            async wzrdClaims() {
+                return getClaimsData(requireAgent());
+            },
+            async wzrdDeposit(marketId, amountUsdc, priorityFee) {
+                return depositHandler(requireAgent(), {
+                    market_id: marketId,
+                    amount_usdc: amountUsdc,
+                    priority_fee: priorityFee,
+                });
+            },
+            async wzrdClaim(execute = true) {
+                return claimHandler(requireAgent(), { execute });
+            },
+            async wzrdVelocity(platform, minSignal) {
+                return velocityHandler(requireAgent(), {
+                    platform,
+                    min_signal: minSignal,
+                });
+            },
+        },
+        actions: WZRD_ACTIONS,
+    };
+}
+/** Default plugin instance for direct registration via `agent.use(...)`. */
+export const WZRD_PLUGIN = createWzrdPlugin();

package/dist/runtime.d.ts

@@ -0,0 +1,16 @@
+import { PublicKey } from '@solana/web3.js';
+import type { SolanaAgentKit } from 'solana-agent-kit';
+import { WzrdClient, type WzrdClaim, type WzrdLeaderboard, type WzrdPortfolio } from './client.js';
+export type SignalTier = 'BREAKOUT' | 'MOMENTUM' | 'EMERGING' | 'STABLE' | 'COOLING' | 'WEAK';
+export declare function resolveApiUrl(explicit?: string): string;
+export declare function getClientForAgent(agent: SolanaAgentKit, apiUrl?: string): WzrdClient;
+export declare function getWalletPublicKey(agent: SolanaAgentKit): PublicKey;
+export declare function formatVelocity(v: number): string;
+export declare function formatUsdc(nativeAmount: number | bigint): string;
+export declare function formatCcm(nativeAmount: number | bigint): string;
+export declare function getLeaderboardData(agent: SolanaAgentKit, input: {
+    limit?: number;
+    platform?: string;
+}): Promise<WzrdLeaderboard>;
+export declare function getPortfolioData(agent: SolanaAgentKit): Promise<WzrdPortfolio>;
+export declare function getClaimsData(agent: SolanaAgentKit): Promise<WzrdClaim>;

package/dist/runtime.js

@@ -0,0 +1,33 @@
+import { DEFAULT_API_URL, WzrdClient, } from './client.js';
+export function resolveApiUrl(explicit) {
+    const envUrl = process.env.WZRD_API_URL?.trim();
+    return explicit?.trim() || envUrl || DEFAULT_API_URL;
+}
+export function getClientForAgent(agent, apiUrl) {
+    return new WzrdClient(agent.wallet, resolveApiUrl(apiUrl));
+}
+export function getWalletPublicKey(agent) {
+    return agent.wallet.publicKey;
+}
+export 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);
+}
+export function formatUsdc(nativeAmount) {
+    return (Number(nativeAmount) / 1_000_000).toFixed(4);
+}
+export function formatCcm(nativeAmount) {
+    return (Number(nativeAmount) / 1_000_000).toFixed(4);
+}
+export async function getLeaderboardData(agent, input) {
+    return getClientForAgent(agent).getLeaderboard(input.limit ?? 10, input.platform);
+}
+export async function getPortfolioData(agent) {
+    return getClientForAgent(agent).getPortfolio();
+}
+export async function getClaimsData(agent) {
+    return getClientForAgent(agent).getClaims();
+}

package/examples/hello-wzrd.mjs

@@ -18,7 +18,7 @@
 
 import { readFileSync } from 'node:fs';
 import { Keypair } from '@solana/web3.js';
-import { WzrdClient } from '../dist/index.js';
+import { WzrdClient } from '@wzrd_sol/solana-agent-plugin';
 
 const KEYPAIR_PATH = process.env.WZRD_KEYPAIR_PATH;
 if (!KEYPAIR_PATH) {

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@wzrd_sol/solana-agent-plugin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
@@ -17,8 +18,9 @@
   },
   "dependencies": {
     "@solana/web3.js": "^1.95.0",
-    "@wzrd_sol/sdk": "^0.1.0",
-    "tweetnacl": "^1.0.3"
+    "@wzrd_sol/sdk": "^0.1.1",
+    "tweetnacl": "^1.0.3",
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "solana-agent-kit": "^2.0.0"
@@ -28,6 +30,10 @@
       "optional": true
     }
   },
+  "devDependencies": {
+    "solana-agent-kit": "^2.0.10",
+    "typescript": "^5.6.3"
+  },
   "keywords": [
     "solana",
     "agent",

package/src/actions/claim.ts

@@ -7,9 +7,73 @@
  * Flow: check claimable amount → relay claim → receive CCM.
  */
 
-import type { WzrdClient } from '../client.js';
+import { z } from 'zod';
+import type { Action, SolanaAgentKit } from 'solana-agent-kit';
 
-export const CLAIM_ACTION = {
+import { formatCcm, getClaimsData, getClientForAgent } from '../runtime.js';
+
+export const claimSchema = z.object({
+  execute: z.boolean().optional(),
+});
+
+export async function claimHandler(
+  agent: SolanaAgentKit,
+  input: z.infer<typeof claimSchema>,
+): Promise<Record<string, unknown>> {
+  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: Action = {
   name: 'wzrd_claim',
   similes: ['wzrd_harvest', 'claim_ccm', 'redeem_rewards', 'collect_yield'],
   description:
@@ -22,77 +86,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: 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}`,
-      },
-    };
-  },
+  schema: claimSchema,
+  handler: async (agent, input) => claimHandler(agent, claimSchema.parse(input)),
 };