@wzrd_sol/solana-agent-plugin 0.1.0 → 0.1.2

package/src/actions/portfolio.ts

@@ -5,9 +5,39 @@
  * Requires auth (Ed25519 agent session).
  */
 
-import type { WzrdClient, WzrdPosition } from '../client.js';
+import { z } from 'zod';
+import type { Action, SolanaAgentKit } from 'solana-agent-kit';
 
-export const PORTFOLIO_ACTION = {
+import { formatCcm, formatUsdc, getPortfolioData } from '../runtime.js';
+
+export const portfolioSchema = z.object({});
+
+export async function portfolioHandler(
+  agent: SolanaAgentKit,
+  _input: z.infer<typeof portfolioSchema>,
+): Promise<Record<string, unknown>> {
+  const portfolio = await getPortfolioData(agent);
+  const open = portfolio.positions.filter((p) => !p.is_settled);
+  const lines = open.map(
+    (p) =>
+      `• Market #${p.market_id} (${p.metric}): ` +
+      `${formatUsdc(p.usdc_deposited)} USDC, ` +
+      `${(p.multiplier_bps / 10_000).toFixed(1)}x multiplier` +
+      (p.is_settled ? ' [settled]' : ''),
+  );
+
+  return {
+    success: true,
+    text:
+      `Your WZRD portfolio (${open.length} open positions):\n` +
+      `${lines.length ? lines.join('\n') : '(no positions)'}\n` +
+      `Total: ${formatUsdc(portfolio.total_deposited_usdc)} USDC deposited, ` +
+      `${formatCcm(portfolio.total_ccm_earned)} CCM earned`,
+    data: portfolio,
+  };
+}
+
+export const PORTFOLIO_ACTION: Action = {
   name: 'wzrd_portfolio',
   similes: ['wzrd_positions', 'wzrd_balance', 'wzrd_holdings', 'my_positions'],
   description:
@@ -18,45 +48,17 @@ export const PORTFOLIO_ACTION = {
   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',
+        input: {},
+        output: {
+          success: true,
+          open_positions: 2,
+          total_deposited_usdc: 20000,
+          total_ccm_earned: 0,
         },
+        explanation: 'Fetch the authenticated agent portfolio and summarize open exposure.',
       },
     ],
   ],
-
-  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,
-    };
-  },
+  schema: portfolioSchema,
+  handler: async (agent, input) => portfolioHandler(agent, portfolioSchema.parse(input)),
 };

package/src/actions/velocity.ts

@@ -13,9 +13,11 @@
  *   WEAK      — below p20
  */
 
-import type { WzrdClient, WzrdMarket } from '../client.js';
+import { z } from 'zod';
+import type { Action, SolanaAgentKit } from 'solana-agent-kit';
+import type { WzrdMarket } from '../client.js';
 
-type SignalTier = 'BREAKOUT' | 'MOMENTUM' | 'EMERGING' | 'STABLE' | 'COOLING' | 'WEAK';
+import { formatVelocity, getLeaderboardData, type SignalTier } from '../runtime.js';
 
 export interface MarketSignal {
   market_id: number;
@@ -26,7 +28,79 @@ export interface MarketSignal {
   percentile: number;
 }
 
-export const VELOCITY_ACTION = {
+export const velocitySchema = z.object({
+  platform: z.string().min(1).optional(),
+  min_signal: z
+    .enum(['BREAKOUT', 'MOMENTUM', 'EMERGING', 'STABLE', 'COOLING', 'WEAK'])
+    .optional(),
+});
+
+export async function velocityHandler(
+  agent: SolanaAgentKit,
+  input: z.infer<typeof velocitySchema>,
+): Promise<Record<string, unknown>> {
+  const data = await getLeaderboardData(agent, { limit: 50, platform: input.platform });
+  const markets = data.markets;
+
+  if (markets.length === 0) {
+    return { success: true, text: 'No markets found.', data: { signals: [] } };
+  }
+
+  const sorted = [...markets].sort((a, b) => a.velocity_ema - b.velocity_ema);
+  const signals: MarketSignal[] = markets.map((m: WzrdMarket) => {
+    const rank = sorted.findIndex((s) => s.market_id === m.market_id);
+    const percentile = ((rank + 1) / sorted.length) * 100;
+    const signal = classify(m, percentile);
+    return {
+      market_id: m.market_id,
+      metric: m.metric,
+      platform: m.platform,
+      velocity_ema: m.velocity_ema,
+      signal,
+      percentile: Math.round(percentile),
+    };
+  });
+
+  const tierOrder: SignalTier[] = ['BREAKOUT', 'MOMENTUM', 'EMERGING', 'STABLE', 'COOLING', 'WEAK'];
+  const minIdx = input.min_signal
+    ? tierOrder.indexOf(input.min_signal)
+    : tierOrder.length;
+  const filtered = minIdx < tierOrder.length
+    ? signals.filter((s) => tierOrder.indexOf(s.signal) <= minIdx)
+    : signals;
+
+  const grouped = new Map<SignalTier, MarketSignal[]>();
+  for (const s of filtered) {
+    const arr = grouped.get(s.signal) ?? [];
+    arr.push(s);
+    grouped.set(s.signal, arr);
+  }
+
+  const lines: string[] = [];
+  for (const tier of tierOrder) {
+    const group = grouped.get(tier);
+    if (!group?.length) continue;
+    lines.push(`${tier}:`);
+    for (const s of group) {
+      lines.push(
+        `  • ${s.metric} (${formatVelocity(s.velocity_ema)} velocity, p${s.percentile}) [${s.platform}]`,
+      );
+    }
+  }
+
+  const medianIdx = Math.floor(sorted.length / 2);
+  const medianVelocity = sorted[medianIdx]?.velocity_ema ?? 0;
+
+  return {
+    success: true,
+    text:
+      `Velocity analysis (${markets.length} markets, ` +
+      `median ${formatVelocity(medianVelocity)}):\n${lines.join('\n')}`,
+    data: { signals: filtered, median_velocity: medianVelocity },
+  };
+}
+
+export const VELOCITY_ACTION: Action = {
   name: 'wzrd_velocity',
   similes: ['wzrd_signal', 'attention_signal', 'market_analysis', 'velocity_check'],
   description:
@@ -39,92 +113,17 @@ export const VELOCITY_ACTION = {
   examples: [
     [
       {
-        user: 'user',
-        content: { text: 'What markets have breakout velocity?' },
-      },
-      {
-        user: 'assistant',
-        content: {
-          text: 'BREAKOUT signals:\n' +
-            '• Qwen 3.5 35B (804K velocity, p95)\n' +
-            'MOMENTUM signals:\n' +
-            '• Qwen 3.5 9B (769K velocity, p85)\n' +
-            '• Qwen 2.5 72B (378K velocity, p72)',
+        input: { min_signal: 'MOMENTUM' },
+        output: {
+          success: true,
+          signals: ['BREAKOUT: Qwen 3.5 35B', 'MOMENTUM: Qwen 2.5 72B'],
         },
+        explanation: 'Classify the current leaderboard into signal tiers for deposit decisions.',
       },
     ],
   ],
-
-  validate: async () => true,
-
-  handler: async (
-    client: WzrdClient,
-    params: { platform?: string; min_signal?: SignalTier },
-  ) => {
-    const data = await client.getLeaderboard(50, params.platform);
-    const markets = data.markets;
-
-    if (markets.length === 0) {
-      return { success: true, text: 'No markets found.', data: { signals: [] } };
-    }
-
-    // Sort by velocity for percentile calculation
-    const sorted = [...markets].sort((a, b) => a.velocity_ema - b.velocity_ema);
-    const signals: MarketSignal[] = markets.map((m: WzrdMarket) => {
-      const rank = sorted.findIndex((s) => s.market_id === m.market_id);
-      const percentile = ((rank + 1) / sorted.length) * 100;
-      const signal = classify(m, percentile);
-      return {
-        market_id: m.market_id,
-        metric: m.metric,
-        platform: m.platform,
-        velocity_ema: m.velocity_ema,
-        signal,
-        percentile: Math.round(percentile),
-      };
-    });
-
-    // Filter by minimum signal if requested
-    const tierOrder: SignalTier[] = ['BREAKOUT', 'MOMENTUM', 'EMERGING', 'STABLE', 'COOLING', 'WEAK'];
-    const minIdx = params.min_signal
-      ? tierOrder.indexOf(params.min_signal)
-      : tierOrder.length;
-    const filtered = minIdx < tierOrder.length
-      ? signals.filter((s) => tierOrder.indexOf(s.signal) <= minIdx)
-      : signals;
-
-    // Group by signal tier
-    const grouped = new Map<SignalTier, MarketSignal[]>();
-    for (const s of filtered) {
-      const arr = grouped.get(s.signal) ?? [];
-      arr.push(s);
-      grouped.set(s.signal, arr);
-    }
-
-    const lines: string[] = [];
-    for (const tier of tierOrder) {
-      const group = grouped.get(tier);
-      if (!group?.length) continue;
-      lines.push(`${tier}:`);
-      for (const s of group) {
-        lines.push(
-          `  • ${s.metric} (${formatVelocity(s.velocity_ema)} velocity, p${s.percentile}) [${s.platform}]`,
-        );
-      }
-    }
-
-    // Median velocity
-    const medianIdx = Math.floor(sorted.length / 2);
-    const medianVelocity = sorted[medianIdx]?.velocity_ema ?? 0;
-
-    return {
-      success: true,
-      text:
-        `Velocity analysis (${markets.length} markets, ` +
-        `median ${formatVelocity(medianVelocity)}):\n${lines.join('\n')}`,
-      data: { signals: filtered, median_velocity: medianVelocity },
-    };
-  },
+  schema: velocitySchema,
+  handler: async (agent, input) => velocityHandler(agent, velocitySchema.parse(input)),
 };
 
 function classify(m: WzrdMarket, percentile: number): SignalTier {
@@ -135,9 +134,3 @@ function classify(m: WzrdMarket, percentile: number): SignalTier {
   if (percentile >= 20) return 'COOLING';
   return 'WEAK';
 }
-
-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/client.ts

@@ -2,14 +2,21 @@
  * WZRD API client — handles agent auth (Ed25519 challenge/verify),
  * token caching, and all REST calls.
  *
- * Standalone: no framework dependency. Works with any Keypair holder.
+ * Standalone: no framework dependency. Works with a Keypair or any wallet
+ * implementation that supports `publicKey` + `signMessage()`.
  */
 
-import { Keypair } from '@solana/web3.js';
+import { Keypair, type PublicKey } from '@solana/web3.js';
 
-const DEFAULT_API_URL = 'https://api.twzrd.xyz';
+export const DEFAULT_API_URL = 'https://api.twzrd.xyz';
 const TOKEN_REFRESH_MARGIN_MS = 5 * 60 * 1000;
 
+export interface WzrdSigner {
+  publicKey: PublicKey;
+  signMessage?: (message: Uint8Array) => Promise<Uint8Array>;
+  secretKey?: Uint8Array;
+}
+
 // ── Base58 encoder (zero-dependency) ────────────────────
 
 const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
@@ -51,6 +58,7 @@ export interface WzrdMarket {
   status: string;
   snapshot_count: number;
   last_scored_at: string;
+  depositable: boolean;
 }
 
 export interface WzrdLeaderboard {
@@ -91,7 +99,9 @@ export interface WzrdClaim {
 export interface WzrdRelayResult {
   root_seq: number;
   cumulative_total: number;
-  tx_sig: string;
+  claimed_total?: number;
+  tx_sig?: string;
+  status?: 'already_claimed';
 }
 
 // ── Client ──────────────────────────────────────────────
@@ -101,12 +111,37 @@ export class WzrdClient {
   private tokenExpiresAt = 0;
 
   constructor(
-    private readonly keypair: Keypair,
+    private readonly signer: WzrdSigner | Keypair,
     private readonly apiUrl: string = DEFAULT_API_URL,
   ) {}
 
   get pubkey(): string {
-    return this.keypair.publicKey.toBase58();
+    return this.signer.publicKey.toBase58();
+  }
+
+  private isWalletSigner(
+    signer: WzrdSigner | Keypair,
+  ): signer is WzrdSigner & { signMessage: NonNullable<WzrdSigner['signMessage']> } {
+    return typeof (signer as WzrdSigner).signMessage === 'function';
+  }
+
+  private hasSecretKey(signer: WzrdSigner | Keypair): signer is WzrdSigner & { secretKey: Uint8Array } {
+    return signer instanceof Keypair || signer.secretKey instanceof Uint8Array;
+  }
+
+  private async signAuthMessage(message: Uint8Array): Promise<Uint8Array> {
+    if (this.isWalletSigner(this.signer)) {
+      return this.signer.signMessage(message);
+    }
+
+    if (this.hasSecretKey(this.signer)) {
+      const { default: nacl } = await import('tweetnacl');
+      return nacl.sign.detached(message, this.signer.secretKey);
+    }
+
+    throw new Error(
+      'WzrdClient requires a signer with signMessage() or an Ed25519 secretKey',
+    );
   }
 
   // ── Auth ────────────────────────────────────────────
@@ -119,11 +154,7 @@ export class WzrdClient {
 
     // 2. Sign with Ed25519
     const message = `wzrd-agent-auth v1 | wallet:${this.pubkey} | nonce:${nonce}`;
-    const { default: nacl } = await import('tweetnacl');
-    const sig = nacl.sign.detached(
-      new TextEncoder().encode(message),
-      this.keypair.secretKey,
-    );
+    const sig = await this.signAuthMessage(new TextEncoder().encode(message));
 
     // 3. Verify
     const vr = await fetch(`${this.apiUrl}/v1/agent/verify`, {

package/src/index.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:
@@ -38,14 +38,18 @@ export {
   CLAIM_ACTION,
   VELOCITY_ACTION,
 } from './actions/index.js';
+export type { MarketSignal } from './actions/index.js';
 
 // ── Convenience: all actions as array ────────────────────
 
+import type { Plugin, SolanaAgentKit } from 'solana-agent-kit';
+
+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, type MarketSignal } from './actions/velocity.js';
 
 export const WZRD_ACTIONS = [
   LEADERBOARD_ACTION,
@@ -53,12 +57,66 @@ export const WZRD_ACTIONS = [
   DEPOSIT_ACTION,
   CLAIM_ACTION,
   VELOCITY_ACTION,
-] as const;
+] as 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 function createWzrdPlugin(): Plugin {
+  let agentRef: SolanaAgentKit | null = null;
+
+  const requireAgent = (): SolanaAgentKit => {
+    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?: string) {
+        return getLeaderboardData(requireAgent(), { limit, platform });
+      },
+      async wzrdPortfolio() {
+        return getClientForAgent(requireAgent()).getPortfolio();
+      },
+      async wzrdClaims() {
+        return getClaimsData(requireAgent());
+      },
+      async wzrdDeposit(marketId: number, amountUsdc: number, priorityFee?: number) {
+        return depositHandler(requireAgent(), {
+          market_id: marketId,
+          amount_usdc: amountUsdc,
+          priority_fee: priorityFee,
+        });
+      },
+      async wzrdClaim(execute = true) {
+        return claimHandler(requireAgent(), { execute });
+      },
+      async wzrdVelocity(platform?: string, minSignal?: MarketSignal['signal']) {
+        return velocityHandler(requireAgent(), {
+          platform,
+          min_signal: minSignal,
+        });
+      },
+    },
+    actions: WZRD_ACTIONS,
+  };
+}
 
-/** 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',
-};
+/** Default plugin instance for direct registration via `agent.use(...)`. */
+export const WZRD_PLUGIN: Plugin = createWzrdPlugin();

package/src/runtime.ts

@@ -0,0 +1,60 @@
+import { PublicKey } from '@solana/web3.js';
+import type { SolanaAgentKit } from 'solana-agent-kit';
+
+import {
+  DEFAULT_API_URL,
+  WzrdClient,
+  type WzrdClaim,
+  type WzrdLeaderboard,
+  type WzrdPortfolio,
+} from './client.js';
+
+export type SignalTier =
+  | 'BREAKOUT'
+  | 'MOMENTUM'
+  | 'EMERGING'
+  | 'STABLE'
+  | 'COOLING'
+  | 'WEAK';
+
+export function resolveApiUrl(explicit?: string): string {
+  const envUrl = process.env.WZRD_API_URL?.trim();
+  return explicit?.trim() || envUrl || DEFAULT_API_URL;
+}
+
+export function getClientForAgent(agent: SolanaAgentKit, apiUrl?: string): WzrdClient {
+  return new WzrdClient(agent.wallet, resolveApiUrl(apiUrl));
+}
+
+export function getWalletPublicKey(agent: SolanaAgentKit): PublicKey {
+  return agent.wallet.publicKey;
+}
+
+export 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);
+}
+
+export function formatUsdc(nativeAmount: number | bigint): string {
+  return (Number(nativeAmount) / 1_000_000).toFixed(4);
+}
+
+export function formatCcm(nativeAmount: number | bigint): string {
+  return (Number(nativeAmount) / 1_000_000).toFixed(4);
+}
+
+export async function getLeaderboardData(
+  agent: SolanaAgentKit,
+  input: { limit?: number; platform?: string },
+): Promise<WzrdLeaderboard> {
+  return getClientForAgent(agent).getLeaderboard(input.limit ?? 10, input.platform);
+}
+
+export async function getPortfolioData(agent: SolanaAgentKit): Promise<WzrdPortfolio> {
+  return getClientForAgent(agent).getPortfolio();
+}
+
+export async function getClaimsData(agent: SolanaAgentKit): Promise<WzrdClaim> {
+  return getClientForAgent(agent).getClaims();
+}

package/type-smoke-Cvxu.ts

@@ -0,0 +1,8 @@
+import type { Action, Plugin } from 'solana-agent-kit';
+import { WZRD_PLUGIN, LEADERBOARD_ACTION } from './dist/index.js';
+
+const plugin: Plugin = WZRD_PLUGIN;
+const action: Action = LEADERBOARD_ACTION;
+
+void plugin;
+void action;