@wzrd_sol/sdk 0.1.1 → 0.2.0

package/README.md

@@ -107,6 +107,8 @@ const ixs = await createSettleMarketIx(connection, wallet.publicKey, 6);
 // Build, sign, send as above
 ```
 
+`settle_market` returns USDC from reserve and burns vLOFI. It does not mint CCM; CCM is claimed via merkle proof (`claim_global` / `claim_global_v2`).
+
 ### Read On-Chain State
 
 ```typescript

package/dist/accounts.d.ts

@@ -15,6 +15,8 @@ export interface MarketVaultFull extends MarketVaultData {
     marketId: number;
     totalDeposited: bigint;
     totalShares: bigint;
+    navPerShareBps: bigint;
+    lastNavUpdateSlot: bigint;
 }
 export interface ProtocolStateData {
     isInitialized: boolean;
@@ -40,6 +42,16 @@ export interface OnChainPosition {
     settled: boolean;
     entrySlot: bigint;
 }
+export type LifecyclePhase = 'deposited' | 'accruing' | 'claimable' | 'claimed' | 'settled';
+export interface LifecyclePhaseInput {
+    settled: boolean;
+    positionCreatedAt?: Date | string | null;
+    latestRootCreatedAt?: Date | string | null;
+    latestProofCreatedAt?: Date | string | null;
+    proofCumulativeTotalBase?: bigint | number | null;
+    claimedTotalBase?: bigint | number | null;
+    claimableCcmBase?: bigint | number | null;
+}
 /** Parse a MarketVault account's core fields (skip Anchor discriminator). */
 export declare function parseMarketVault(data: Buffer): MarketVaultData;
 /**
@@ -52,6 +64,7 @@ export declare function parseMarketVault(data: Buffer): MarketVaultData;
 export declare function parseProtocolState(data: Buffer): ProtocolStateData;
 /** Parse a UserMarketPosition account. Returns null if data is too short. */
 export declare function parseUserMarketPosition(data: Buffer): OnChainPosition | null;
+export declare function deriveLifecyclePhase(input: LifecyclePhaseInput): LifecyclePhase;
 /** Fetch a user's position for a specific market directly from chain. */
 export declare function fetchOnChainPosition(connection: Connection, user: PublicKey, marketId: number, programId?: PublicKey): Promise<OnChainPosition | null>;
 /** Fetch the full MarketVault data from chain. */

package/dist/accounts.js

@@ -42,7 +42,7 @@ export function parseProtocolState(data) {
 }
 /** Parse a UserMarketPosition account. Returns null if data is too short. */
 export function parseUserMarketPosition(data) {
-    if (data.length < 106)
+    if (data.length < 114)
         return null;
     const d = data.subarray(8); // skip Anchor discriminator
     return {
@@ -55,6 +55,45 @@ export function parseUserMarketPosition(data) {
         entrySlot: d.readBigUInt64LE(90),
     };
 }
+function toMillis(value) {
+    if (!value)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    const time = date.getTime();
+    return Number.isFinite(time) ? time : null;
+}
+function toBigIntOrZero(value) {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return BigInt(Math.trunc(value));
+    return 0n;
+}
+export function deriveLifecyclePhase(input) {
+    if (input.settled)
+        return 'settled';
+    const positionCreatedAtMs = toMillis(input.positionCreatedAt);
+    const latestRootCreatedAtMs = toMillis(input.latestRootCreatedAt);
+    if (positionCreatedAtMs !== null &&
+        (latestRootCreatedAtMs === null || latestRootCreatedAtMs < positionCreatedAtMs)) {
+        return 'deposited';
+    }
+    const latestProofCreatedAtMs = toMillis(input.latestProofCreatedAt);
+    const proofAppliesToPosition = positionCreatedAtMs === null ||
+        (latestProofCreatedAtMs !== null && latestProofCreatedAtMs >= positionCreatedAtMs);
+    const claimableCcmBase = toBigIntOrZero(input.claimableCcmBase);
+    if (proofAppliesToPosition && claimableCcmBase > 0n) {
+        return 'claimable';
+    }
+    const proofCumulativeTotalBase = toBigIntOrZero(input.proofCumulativeTotalBase);
+    const claimedTotalBase = toBigIntOrZero(input.claimedTotalBase);
+    if (proofAppliesToPosition &&
+        proofCumulativeTotalBase > 0n &&
+        claimedTotalBase >= proofCumulativeTotalBase) {
+        return 'claimed';
+    }
+    return 'accruing';
+}
 // ── Fetch Helpers ──────────────────────────────────────
 /** Fetch a user's position for a specific market directly from chain. */
 export async function fetchOnChainPosition(connection, user, marketId, programId) {
@@ -82,6 +121,8 @@ export async function fetchMarketVault(connection, marketId, programId) {
         marketId,
         totalDeposited: d.readBigUInt64LE(105),
         totalShares: d.readBigUInt64LE(113),
+        navPerShareBps: d.length >= 137 ? d.readBigUInt64LE(129) : 0n,
+        lastNavUpdateSlot: d.length >= 145 ? d.readBigUInt64LE(137) : 0n,
     };
 }
 /** Read a token account balance from chain. */

package/dist/accounts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/accounts.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { deriveLifecyclePhase } from './accounts.js';
+describe('deriveLifecyclePhase', () => {
+    it('returns settled when the position is settled', () => {
+        expect(deriveLifecyclePhase({ settled: true })).toBe('settled');
+    });
+    it('returns deposited before any newer root has landed', () => {
+        expect(deriveLifecyclePhase({
+            settled: false,
+            positionCreatedAt: '2026-03-17T10:00:00Z',
+            latestRootCreatedAt: '2026-03-17T09:59:59Z',
+        })).toBe('deposited');
+    });
+    it('returns claimable when an unclaimed proof exists after the position', () => {
+        expect(deriveLifecyclePhase({
+            settled: false,
+            positionCreatedAt: '2026-03-17T10:00:00Z',
+            latestRootCreatedAt: '2026-03-17T10:05:00Z',
+            latestProofCreatedAt: '2026-03-17T10:06:00Z',
+            proofCumulativeTotalBase: 50n,
+            claimedTotalBase: 25n,
+            claimableCcmBase: 25n,
+        })).toBe('claimable');
+    });
+    it('returns claimed when the latest proof is fully claimed', () => {
+        expect(deriveLifecyclePhase({
+            settled: false,
+            positionCreatedAt: '2026-03-17T10:00:00Z',
+            latestRootCreatedAt: '2026-03-17T10:05:00Z',
+            latestProofCreatedAt: '2026-03-17T10:06:00Z',
+            proofCumulativeTotalBase: 50n,
+            claimedTotalBase: 50n,
+            claimableCcmBase: 0n,
+        })).toBe('claimed');
+    });
+    it('returns accruing when no proof applies to the position yet', () => {
+        expect(deriveLifecyclePhase({
+            settled: false,
+            positionCreatedAt: '2026-03-17T10:00:00Z',
+            latestRootCreatedAt: '2026-03-17T10:05:00Z',
+            latestProofCreatedAt: '2026-03-17T09:55:00Z',
+            proofCumulativeTotalBase: 50n,
+            claimedTotalBase: 50n,
+            claimableCcmBase: 0n,
+        })).toBe('accruing');
+    });
+});

package/dist/agent-auth.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent Auth — Ed25519 challenge/verify handshake + inference/report/earned helpers.
+ *
+ * Stateless functions for the WZRD agent API. Used by AgentLoop and
+ * directly by any TypeScript agent that needs to authenticate and earn CCM.
+ *
+ * Runtime dependency: tweetnacl (direct dep — required for Ed25519 signing).
+ *
+ * @module agent-auth
+ */
+import type { Keypair } from '@solana/web3.js';
+/** Response from the challenge endpoint. */
+export interface ChallengeResponse {
+    nonce: string;
+    message_format: string;
+}
+/** Response from the verify endpoint. */
+export interface VerifyResponse {
+    token: string;
+    pubkey: string;
+    expires_at: string;
+}
+/** Response from the infer endpoint. */
+export interface InferResponse {
+    execution_id: string | null;
+    quality_score: number | null;
+    latency_ms: number | null;
+    cost_usd: number | null;
+    provider: string | null;
+    executed_model: string | null;
+    response_preview: string | null;
+}
+/** Response from the report endpoint. */
+export interface ReportResponse {
+    pending_ccm: number;
+    status: string;
+}
+/** Response from the earned endpoint. */
+export interface EarnedResponse {
+    total_earned_ccm: number;
+    pending_ccm: number;
+    rank: number | null;
+    contribution_streak_days: number;
+    pipeline: {
+        state: string | null;
+        next_root_eta_secs: number | null;
+        hint: string | null;
+    } | null;
+}
+/**
+ * Request a challenge nonce from the WZRD server.
+ */
+export declare function agentChallenge(apiBase?: string): Promise<ChallengeResponse>;
+/**
+ * Submit a signed challenge for verification. Returns a session token.
+ */
+export declare function agentVerify(pubkey: string, nonce: string, signature: string, apiBase?: string): Promise<VerifyResponse>;
+/**
+ * Full auth flow: challenge -> sign -> verify -> token.
+ *
+ * Uses tweetnacl (transitive dep of @solana/web3.js) for Ed25519 signing.
+ * Message format: `wzrd-agent-auth v1 | wallet:{pubkey} | nonce:{nonce}`
+ */
+export declare function agentAuth(keypair: Keypair, apiBase?: string): Promise<string>;
+/**
+ * Run server-witnessed inference. Returns execution_id for verified reports.
+ *
+ * The server calls the LLM, grades the response, and stores an execution
+ * receipt. Pass the returned `execution_id` to `agentReport()` so the
+ * contribution is marked verified (highest reward tier).
+ */
+export declare function agentInfer(token: string, model: string, taskType: string, apiBase?: string): Promise<InferResponse>;
+/**
+ * Report a model pick for reward eligibility.
+ */
+export declare function agentReport(token: string, modelId: string, opts?: {
+    taskType?: string;
+    executionId?: string | null;
+    qualityScore?: number | null;
+    latencyMs?: number | null;
+    costUsd?: number | null;
+    outcome?: string;
+    /** Full WZRD signal metadata — mirrors Python report_pick().metadata.wzrd */
+    metadata?: Record<string, unknown>;
+}, apiBase?: string): Promise<ReportResponse>;
+/**
+ * Check earned CCM status.
+ */
+export declare function agentEarned(token: string, apiBase?: string): Promise<EarnedResponse>;

package/dist/agent-auth.js

@@ -0,0 +1,147 @@
+/**
+ * Agent Auth — Ed25519 challenge/verify handshake + inference/report/earned helpers.
+ *
+ * Stateless functions for the WZRD agent API. Used by AgentLoop and
+ * directly by any TypeScript agent that needs to authenticate and earn CCM.
+ *
+ * Runtime dependency: tweetnacl (direct dep — required for Ed25519 signing).
+ *
+ * @module agent-auth
+ */
+// ── Constants ────────────────────────────────────────────────────
+const DEFAULT_API_BASE = 'https://api.twzrd.xyz';
+// ── Base58 Encoder (inline — avoids adding bs58 as a direct dep) ─
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+function base58Encode(bytes) {
+    let zeroes = 0;
+    for (let i = 0; i < bytes.length && bytes[i] === 0; i++)
+        zeroes++;
+    const size = Math.ceil(bytes.length * 138 / 100) + 1;
+    const b58 = new Uint8Array(size);
+    let length = 0;
+    for (let i = zeroes; i < bytes.length; i++) {
+        let carry = bytes[i];
+        let j = 0;
+        for (let k = size - 1; k >= 0 && (carry !== 0 || j < length); k--, j++) {
+            carry += 256 * b58[k];
+            b58[k] = carry % 58;
+            carry = Math.floor(carry / 58);
+        }
+        length = j;
+    }
+    let result = '1'.repeat(zeroes);
+    let started = false;
+    for (let i = size - length; i < size; i++) {
+        if (!started && b58[i] === 0)
+            continue;
+        started = true;
+        result += BASE58_ALPHABET[b58[i]];
+    }
+    return result || '1';
+}
+// ── Auth Functions ───────────────────────────────────────────────
+/**
+ * Request a challenge nonce from the WZRD server.
+ */
+export async function agentChallenge(apiBase = DEFAULT_API_BASE) {
+    const resp = await fetch(`${apiBase}/v1/agent/challenge`);
+    if (!resp.ok)
+        throw new Error(`[wzrd] challenge failed: ${resp.status}`);
+    return resp.json();
+}
+/**
+ * Submit a signed challenge for verification. Returns a session token.
+ */
+export async function agentVerify(pubkey, nonce, signature, apiBase = DEFAULT_API_BASE) {
+    const resp = await fetch(`${apiBase}/v1/agent/verify`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ pubkey, nonce, signature }),
+    });
+    if (!resp.ok)
+        throw new Error(`[wzrd] verify failed: ${resp.status}`);
+    return resp.json();
+}
+/**
+ * Full auth flow: challenge -> sign -> verify -> token.
+ *
+ * Uses tweetnacl (transitive dep of @solana/web3.js) for Ed25519 signing.
+ * Message format: `wzrd-agent-auth v1 | wallet:{pubkey} | nonce:{nonce}`
+ */
+export async function agentAuth(keypair, apiBase = DEFAULT_API_BASE) {
+    // tweetnacl is a direct dependency (declared in package.json)
+    const naclMod = await import('tweetnacl');
+    const nacl = naclMod.default ?? naclMod;
+    const pubkey = keypair.publicKey.toBase58();
+    const { nonce } = await agentChallenge(apiBase);
+    const message = `wzrd-agent-auth v1 | wallet:${pubkey} | nonce:${nonce}`;
+    const messageBytes = new TextEncoder().encode(message);
+    const sig = nacl.sign.detached(messageBytes, keypair.secretKey);
+    const signatureB58 = base58Encode(sig);
+    const session = await agentVerify(pubkey, nonce, signatureB58, apiBase);
+    return session.token;
+}
+// ── API Functions ────────────────────────────────────────────────
+/**
+ * Run server-witnessed inference. Returns execution_id for verified reports.
+ *
+ * The server calls the LLM, grades the response, and stores an execution
+ * receipt. Pass the returned `execution_id` to `agentReport()` so the
+ * contribution is marked verified (highest reward tier).
+ */
+export async function agentInfer(token, model, taskType, apiBase = DEFAULT_API_BASE) {
+    const resp = await fetch(`${apiBase}/v1/agent/infer`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ model, task_type: taskType }),
+    });
+    if (!resp.ok)
+        throw new Error(`[wzrd] infer failed: ${resp.status}`);
+    return resp.json();
+}
+/**
+ * Report a model pick for reward eligibility.
+ */
+export async function agentReport(token, modelId, opts = {}, apiBase = DEFAULT_API_BASE) {
+    const payload = {
+        model_id: modelId,
+        outcome: opts.outcome ?? 'success',
+    };
+    if (opts.taskType != null)
+        payload.task_type = opts.taskType;
+    if (opts.executionId != null)
+        payload.execution_id = opts.executionId;
+    if (opts.qualityScore != null)
+        payload.quality_score = opts.qualityScore;
+    if (opts.latencyMs != null)
+        payload.latency_ms = opts.latencyMs;
+    if (opts.costUsd != null)
+        payload.cost_usd = opts.costUsd;
+    if (opts.metadata != null)
+        payload.metadata = opts.metadata;
+    const resp = await fetch(`${apiBase}/v1/agent/report`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(payload),
+    });
+    if (!resp.ok)
+        throw new Error(`[wzrd] report failed: ${resp.status}`);
+    return resp.json();
+}
+/**
+ * Check earned CCM status.
+ */
+export async function agentEarned(token, apiBase = DEFAULT_API_BASE) {
+    const resp = await fetch(`${apiBase}/v1/agent/earned`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!resp.ok)
+        throw new Error(`[wzrd] earned check failed: ${resp.status}`);
+    return resp.json();
+}

package/dist/agent-loop.d.ts

@@ -0,0 +1,87 @@
+/**
+ * AgentLoop — turn any TypeScript agent into a WZRD earning agent.
+ *
+ * Ports the core earn loop from Python `wzrd.run_loop()` to TypeScript:
+ *   1. Auth via Ed25519 challenge/verify
+ *   2. Per task: fetchPick() (momentum API) -> agentInfer() -> agentReport()
+ *   3. Check earned -> relay claim if available
+ *   4. Sleep -> repeat
+ *
+ * Scoring parity with Python: confidence × action × trend × task-platform × quality.
+ *
+ * @example
+ * ```ts
+ * import { AgentLoop } from '@wzrd_sol/sdk';
+ * import { Keypair } from '@solana/web3.js';
+ *
+ * const loop = new AgentLoop({
+ *   keypair: Keypair.fromSecretKey(secretKey),
+ *   tasks: ['code', 'chat', 'reasoning'],
+ *   cycleSeconds: 300,
+ * });
+ *
+ * loop.start(); // runs forever, handles auth + infer + report + claim
+ * ```
+ *
+ * @module agent-loop
+ */
+import type { Keypair } from '@solana/web3.js';
+import type { EarnedResponse } from './agent-auth.js';
+/** Result of a single cycle, delivered via onCycle callback. */
+export interface CycleResult {
+    cycle: number;
+    tasks: Array<{
+        task: string;
+        model: string | null;
+        qualityScore: number | null;
+        executionId: string | null;
+        pendingCcm: number;
+    }>;
+    earned: EarnedResponse | null;
+    error: string | null;
+}
+/** Configuration for the AgentLoop. */
+export interface AgentLoopOptions {
+    /** Solana keypair for Ed25519 signing. */
+    keypair: Keypair;
+    /** Task types to report on each cycle. Default: ['code', 'chat', 'reasoning']. */
+    tasks?: string[];
+    /** Seconds between cycles (minimum 30). Default: 300. */
+    cycleSeconds?: number;
+    /** Stop after N cycles. Omit or 0 for infinite. */
+    maxCycles?: number;
+    /** Attempt gasless relay claim when CCM is claimable. Default: true. */
+    claim?: boolean;
+    /** API base URL. Default: 'https://api.twzrd.xyz'. */
+    apiBase?: string;
+    /** Optional callback invoked after each cycle completes. */
+    onCycle?: (result: CycleResult) => void;
+}
+/**
+ * Runs the WZRD earn loop: authenticate, pick models, infer, report, claim.
+ *
+ * Create one instance and call `start()`. The loop runs until `maxCycles`
+ * is reached or `stop()` is called. Handles SIGINT/SIGTERM for graceful
+ * shutdown.
+ */
+export declare class AgentLoop {
+    private readonly keypair;
+    private readonly tasks;
+    private readonly cycleSeconds;
+    private readonly maxCycles;
+    private readonly claim;
+    private readonly apiBase;
+    private readonly onCycle?;
+    private running;
+    private token;
+    private sleepResolve;
+    constructor(options: AgentLoopOptions);
+    /**
+     * Start the earn loop. Blocks until maxCycles is reached or stop() is called.
+     */
+    start(): Promise<void>;
+    /**
+     * Signal the loop to stop after the current cycle completes.
+     */
+    stop(): void;
+}