@wzrd_sol/sdk 0.1.2 → 0.2.0

package/dist/instructions.js

@@ -221,8 +221,10 @@ export async function createSettleMarketIx(connection, user, marketId, programId
     const protocolState = getProtocolStatePDA(programId);
     const marketVault = getMarketVaultPDA(protocolState, marketId, programId);
     const userPosition = getUserPositionPDA(marketVault, user, programId);
-    const accountsMode = options.accountsMode
-        ?? 'current';
+    // 'auto' resolves based on program ID: mainnet uses legacy_ccm layout
+    const accountsMode = options.accountsMode === 'auto' || !options.accountsMode
+        ? (programId.equals(PROGRAM_ID) ? 'legacy_ccm' : 'current')
+        : options.accountsMode;
     // Fetch vault + protocol state to discover mints/accounts.
     const vaultInfo = await connection.getAccountInfo(marketVault);
     if (!vaultInfo)
@@ -523,6 +525,31 @@ function getMarketStatePDA(ccmMint, marketId, programId = PROGRAM_ID) {
     idBuf.writeBigUInt64LE(BigInt(marketId));
     return PublicKey.findProgramAddressSync([MARKET_STATE_SEED, ccmMint.toBuffer(), idBuf], programId)[0];
 }
+// ── Prediction market PDA helpers ────────────────────────────────────
+const PM_VAULT_SEED = Buffer.from('market_vault');
+const MARKET_YES_MINT_SEED = Buffer.from('market_yes');
+const MARKET_NO_MINT_SEED = Buffer.from('market_no');
+const MARKET_MINT_AUTH_SEED = Buffer.from('market_auth');
+function getPredictionVaultPDA(ccmMint, marketId, programId = PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(marketId));
+    return PublicKey.findProgramAddressSync([PM_VAULT_SEED, ccmMint.toBuffer(), idBuf], programId)[0];
+}
+function getPredictionYesMintPDA(ccmMint, marketId, programId = PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(marketId));
+    return PublicKey.findProgramAddressSync([MARKET_YES_MINT_SEED, ccmMint.toBuffer(), idBuf], programId)[0];
+}
+function getPredictionNoMintPDA(ccmMint, marketId, programId = PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(marketId));
+    return PublicKey.findProgramAddressSync([MARKET_NO_MINT_SEED, ccmMint.toBuffer(), idBuf], programId)[0];
+}
+function getPredictionMintAuthorityPDA(ccmMint, marketId, programId = PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(marketId));
+    return PublicKey.findProgramAddressSync([MARKET_MINT_AUTH_SEED, ccmMint.toBuffer(), idBuf], programId)[0];
+}
 function getLegacyProtocolStatePDA(ccmMint, programId = PROGRAM_ID) {
     return PublicKey.findProgramAddressSync([PROTOCOL_SEED, ccmMint.toBuffer()], programId)[0];
 }
@@ -1574,3 +1601,174 @@ label, newUpdater, programId = PROGRAM_ID) {
         data,
     });
 }
+// ══════════════════════════════════════════════════════════════════════
+// PREDICTION MARKET TRADING INSTRUCTIONS
+// ══════════════════════════════════════════════════════════════════════
+/** Standard SPL Token program (used for YES/NO outcome tokens). */
+const SPL_TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+/**
+ * Build a `mint_shares` TransactionInstruction (prediction markets).
+ *
+ * Deposits CCM into the prediction market vault and receives 1:1 YES + NO tokens.
+ *
+ * Accounts (13 fixed, order matches markets.rs mint_shares):
+ *   0.  depositor          (signer, writable)
+ *   1.  protocol_state     (readonly)
+ *   2.  market_state       (writable)
+ *   3.  ccm_mint           (readonly)
+ *   4.  depositor_ccm_ata  (writable)
+ *   5.  vault              (writable)
+ *   6.  yes_mint           (writable)
+ *   7.  no_mint            (writable)
+ *   8.  depositor_yes_ata  (writable)
+ *   9.  depositor_no_ata   (writable)
+ *   10. mint_authority     (readonly)
+ *   11. token_program      (Token-2022, for CCM)
+ *   12. outcome_token_prog (SPL Token, for YES/NO)
+ *
+ * Args: amount (u64) — CCM native units to deposit
+ */
+export async function createMintSharesIx(depositor, ccmMint, marketId, amount, programId = PROGRAM_ID) {
+    const protocolState = getProtocolStatePDA(programId);
+    const marketState = getMarketStatePDA(ccmMint, marketId, programId);
+    const vault = getPredictionVaultPDA(ccmMint, marketId, programId);
+    const yesMint = getPredictionYesMintPDA(ccmMint, marketId, programId);
+    const noMint = getPredictionNoMintPDA(ccmMint, marketId, programId);
+    const mintAuthority = getPredictionMintAuthorityPDA(ccmMint, marketId, programId);
+    const depositorCcm = getAta(depositor, ccmMint, TOKEN_2022_PROGRAM_ID);
+    const depositorYes = getAta(depositor, yesMint, SPL_TOKEN_PROGRAM_ID);
+    const depositorNo = getAta(depositor, noMint, SPL_TOKEN_PROGRAM_ID);
+    const disc = await anchorDisc('mint_shares');
+    const data = Buffer.alloc(16);
+    disc.copy(data, 0);
+    data.writeBigUInt64LE(BigInt(amount), 8);
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: depositor, isSigner: true, isWritable: true },
+            { pubkey: protocolState, isSigner: false, isWritable: false },
+            { pubkey: marketState, isSigner: false, isWritable: true },
+            { pubkey: ccmMint, isSigner: false, isWritable: false },
+            { pubkey: depositorCcm, isSigner: false, isWritable: true },
+            { pubkey: vault, isSigner: false, isWritable: true },
+            { pubkey: yesMint, isSigner: false, isWritable: true },
+            { pubkey: noMint, isSigner: false, isWritable: true },
+            { pubkey: depositorYes, isSigner: false, isWritable: true },
+            { pubkey: depositorNo, isSigner: false, isWritable: true },
+            { pubkey: mintAuthority, isSigner: false, isWritable: false },
+            { pubkey: TOKEN_2022_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: SPL_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        ],
+        data,
+    });
+}
+/**
+ * Build a `redeem_shares` TransactionInstruction (prediction markets).
+ *
+ * Burns equal YES + NO shares and returns CCM. Pre-resolution only.
+ *
+ * Accounts (13 fixed, order matches markets.rs redeem_shares):
+ *   0.  redeemer           (signer, writable)
+ *   1.  protocol_state     (readonly)
+ *   2.  market_state       (writable)
+ *   3.  ccm_mint           (readonly)
+ *   4.  vault              (writable)
+ *   5.  yes_mint           (writable)
+ *   6.  no_mint            (writable)
+ *   7.  redeemer_yes_ata   (writable)
+ *   8.  redeemer_no_ata    (writable)
+ *   9.  redeemer_ccm_ata   (writable)
+ *   10. mint_authority     (readonly)
+ *   11. token_program      (Token-2022, for CCM)
+ *   12. outcome_token_prog (SPL Token, for YES/NO)
+ *
+ * Args: shares (u64) — number of YES+NO pairs to redeem
+ */
+export async function createRedeemSharesIx(redeemer, ccmMint, marketId, shares, programId = PROGRAM_ID) {
+    const protocolState = getProtocolStatePDA(programId);
+    const marketState = getMarketStatePDA(ccmMint, marketId, programId);
+    const vault = getPredictionVaultPDA(ccmMint, marketId, programId);
+    const yesMint = getPredictionYesMintPDA(ccmMint, marketId, programId);
+    const noMint = getPredictionNoMintPDA(ccmMint, marketId, programId);
+    const mintAuthority = getPredictionMintAuthorityPDA(ccmMint, marketId, programId);
+    const redeemerYes = getAta(redeemer, yesMint, SPL_TOKEN_PROGRAM_ID);
+    const redeemerNo = getAta(redeemer, noMint, SPL_TOKEN_PROGRAM_ID);
+    const redeemerCcm = getAta(redeemer, ccmMint, TOKEN_2022_PROGRAM_ID);
+    const disc = await anchorDisc('redeem_shares');
+    const data = Buffer.alloc(16);
+    disc.copy(data, 0);
+    data.writeBigUInt64LE(BigInt(shares), 8);
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: redeemer, isSigner: true, isWritable: true },
+            { pubkey: protocolState, isSigner: false, isWritable: false },
+            { pubkey: marketState, isSigner: false, isWritable: true },
+            { pubkey: ccmMint, isSigner: false, isWritable: false },
+            { pubkey: vault, isSigner: false, isWritable: true },
+            { pubkey: yesMint, isSigner: false, isWritable: true },
+            { pubkey: noMint, isSigner: false, isWritable: true },
+            { pubkey: redeemerYes, isSigner: false, isWritable: true },
+            { pubkey: redeemerNo, isSigner: false, isWritable: true },
+            { pubkey: redeemerCcm, isSigner: false, isWritable: true },
+            { pubkey: mintAuthority, isSigner: false, isWritable: false },
+            { pubkey: TOKEN_2022_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: SPL_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        ],
+        data,
+    });
+}
+/**
+ * Build a `settle` TransactionInstruction (prediction markets).
+ *
+ * Burns winning-side tokens and returns CCM 1:1. Post-resolution only.
+ *
+ * Accounts (11 fixed, order matches markets.rs settle):
+ *   0.  settler            (signer, writable)
+ *   1.  protocol_state     (readonly)
+ *   2.  market_state       (readonly)
+ *   3.  ccm_mint           (readonly)
+ *   4.  vault              (writable)
+ *   5.  winning_mint       (writable) — yes_mint if YES won, no_mint if NO
+ *   6.  settler_winning    (writable) — settler's ATA for the winning mint
+ *   7.  settler_ccm        (writable) — settler's CCM ATA
+ *   8.  mint_authority     (readonly)
+ *   9.  token_program      (Token-2022, for CCM)
+ *   10. outcome_token_prog (SPL Token, for YES/NO)
+ *
+ * Args: shares (u64) — winning tokens to settle
+ */
+export async function createSettlePredictionIx(settler, ccmMint, marketId, shares, 
+/** true = YES won, false = NO won */
+yesOutcome, programId = PROGRAM_ID) {
+    const protocolState = getProtocolStatePDA(programId);
+    const marketState = getMarketStatePDA(ccmMint, marketId, programId);
+    const vault = getPredictionVaultPDA(ccmMint, marketId, programId);
+    const yesMint = getPredictionYesMintPDA(ccmMint, marketId, programId);
+    const noMint = getPredictionNoMintPDA(ccmMint, marketId, programId);
+    const mintAuthority = getPredictionMintAuthorityPDA(ccmMint, marketId, programId);
+    const winningMint = yesOutcome ? yesMint : noMint;
+    const settlerWinning = getAta(settler, winningMint, SPL_TOKEN_PROGRAM_ID);
+    const settlerCcm = getAta(settler, ccmMint, TOKEN_2022_PROGRAM_ID);
+    const disc = await anchorDisc('settle');
+    const data = Buffer.alloc(16);
+    disc.copy(data, 0);
+    data.writeBigUInt64LE(BigInt(shares), 8);
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: settler, isSigner: true, isWritable: true },
+            { pubkey: protocolState, isSigner: false, isWritable: false },
+            { pubkey: marketState, isSigner: false, isWritable: false },
+            { pubkey: ccmMint, isSigner: false, isWritable: false },
+            { pubkey: vault, isSigner: false, isWritable: true },
+            { pubkey: winningMint, isSigner: false, isWritable: true },
+            { pubkey: settlerWinning, isSigner: false, isWritable: true },
+            { pubkey: settlerCcm, isSigner: false, isWritable: true },
+            { pubkey: mintAuthority, isSigner: false, isWritable: false },
+            { pubkey: TOKEN_2022_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: SPL_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        ],
+        data,
+    });
+}

package/dist/instructions.test.js

@@ -302,14 +302,14 @@ describe('parseUserMarketPosition', () => {
         expect(parseUserMarketPosition(buf)).toBeNull();
     });
     it('reads settled flag correctly', () => {
-        const buf = Buffer.alloc(8 + 100);
+        const buf = Buffer.alloc(114);
         buf[8 + 89] = 1; // settled
         const pos = parseUserMarketPosition(buf);
         expect(pos).not.toBeNull();
         expect(pos.settled).toBe(true);
     });
     it('reads depositedAmount as u64 LE', () => {
-        const buf = Buffer.alloc(8 + 100);
+        const buf = Buffer.alloc(114);
         buf.writeBigUInt64LE(1000000n, 8 + 1 + 32 + 32); // depositedAmount at offset 73 from disc
         const pos = parseUserMarketPosition(buf);
         expect(pos).not.toBeNull();

package/dist/model-selector.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Model Selector — pick the best open-source model using live WZRD velocity data.
+ *
+ * Combines on-chain attention signals from the WZRD protocol with
+ * OpenRouter pricing to compute a value score for every tracked model,
+ * then returns a ranked list filtered by budget, task, and trend.
+ *
+ * Usage:
+ *   import { bestModel } from '@wzrd_sol/sdk';
+ *   const picks = await bestModel({ task: 'code', budget: 'micro' });
+ *   console.log(picks[0].model_id);
+ *
+ * @module model-selector
+ */
+/** Budget tiers controlling the maximum blended price per million tokens. */
+export type BudgetTier = 'micro' | 'budget' | 'mid' | 'premium';
+/** Supported task types. The selector applies a task-specific boost. */
+export type TaskType = 'chat' | 'code' | 'reasoning';
+/** Velocity trend labels returned by the WZRD momentum API. */
+export type VelocityTrend = 'surging' | 'accelerating' | 'stable' | 'insufficient_history' | 'decelerating' | 'cooling';
+/** Confidence level from the WZRD momentum API. */
+export type Confidence = 'high' | 'medium' | 'low' | 'insufficient';
+/** A single model recommendation returned by the selector. */
+export interface ModelRecommendation {
+    /** Full model identifier (e.g. "google/gemma-3-27b-it"). */
+    model_id: string;
+    /** Routing provider — currently always "openrouter". */
+    provider: string;
+    /** Blended price per million tokens in USD (3:1 prompt:completion weighting). */
+    price_per_m_tokens: number;
+    /** Exponential moving average of the model's velocity from WZRD. */
+    velocity_ema: number;
+    /** Composite value score: velocity_ema / (blended_price + epsilon). Higher is better. */
+    value_score: number;
+    /** Current velocity trend from the WZRD momentum signal. */
+    trend: VelocityTrend;
+    /** Confidence level of the momentum signal. */
+    confidence: Confidence;
+}
+/** Options for filtering and ranking models. */
+export interface ModelSelectorOptions {
+    /** Maximum price tier. Default: "mid". */
+    budget?: BudgetTier;
+    /** Task type — applies a relevance boost to known-good models. Default: "chat". */
+    task?: TaskType;
+    /** Minimum confidence level from the momentum signal. Default: "low". */
+    min_confidence?: Confidence;
+    /** Maximum number of results to return. Default: 5. */
+    limit?: number;
+    /** Model ID substrings to exclude (case-insensitive). */
+    exclude?: string[];
+}
+/** Configuration for the ModelSelector class. */
+export interface ModelSelectorConfig {
+    /** WZRD API base URL. Default: "https://api.twzrd.xyz". */
+    wzrd_base_url?: string;
+    /** OpenRouter catalog URL. Default: "https://openrouter.ai/api/v1/models". */
+    openrouter_url?: string;
+    /** Cache TTL in milliseconds. Default: 300_000 (5 minutes). */
+    cache_ttl_ms?: number;
+}
+/**
+ * Fetches WZRD velocity data and OpenRouter pricing, caches results,
+ * and scores models by value (velocity / cost).
+ *
+ * Create one instance and reuse it — the internal cache avoids redundant
+ * HTTP requests within the TTL window.
+ *
+ * @example
+ * ```ts
+ * const selector = new ModelSelector({ wzrd_base_url: 'https://api.twzrd.xyz' });
+ * const picks = await selector.select({ task: 'code', budget: 'budget', limit: 3 });
+ * console.log(picks[0].model_id);
+ * ```
+ */
+export declare class ModelSelector {
+    private readonly wzrdBaseUrl;
+    private readonly openrouterUrl;
+    private readonly cacheTtlMs;
+    private cache;
+    constructor(config?: ModelSelectorConfig);
+    /**
+     * Select the best models for a given task and budget.
+     *
+     * Fetches live data from the WZRD leaderboard, momentum signal, and
+     * OpenRouter catalog (all cached for 5 minutes by default), then ranks
+     * every OpenRouter model tracked by WZRD using:
+     *
+     *   value_score = velocity_ema / (blended_price_per_m_tokens + epsilon)
+     *
+     * Results are filtered by budget tier, task relevance, minimum confidence,
+     * and exclusion list, then sorted by value_score descending.
+     *
+     * @param options - Filtering and ranking options.
+     * @returns Ranked array of model recommendations (may be empty).
+     */
+    select(options?: ModelSelectorOptions): Promise<ModelRecommendation[]>;
+    /**
+     * Invalidate the in-memory cache.
+     *
+     * Useful when you know upstream data has changed and want
+     * fresh results on the next `select()` call.
+     */
+    clearCache(): void;
+    private fetchLeaderboard;
+    private fetchMomentum;
+    private fetchOpenRouterCatalog;
+    /**
+     * Fetch JSON from a URL with in-memory TTL caching.
+     * Returns null on any error (network, HTTP status, parse failure).
+     */
+    private cachedFetch;
+}
+/**
+ * Pick the best open-source model for a task using live WZRD velocity data.
+ *
+ * This is a convenience wrapper around {@link ModelSelector.select} that
+ * uses a module-level singleton with default configuration. For custom
+ * base URLs or cache settings, instantiate {@link ModelSelector} directly.
+ *
+ * @param options - Filtering and ranking options.
+ * @returns Ranked array of model recommendations (may be empty if the API is unreachable).
+ *
+ * @example
+ * ```ts
+ * import { bestModel } from '@wzrd_sol/sdk';
+ *
+ * // Cheapest model good for code
+ * const picks = await bestModel({ task: 'code', budget: 'micro' });
+ * console.log(picks[0].model_id);
+ *
+ * // Premium reasoning model, exclude specific providers
+ * const reasoning = await bestModel({
+ *   task: 'reasoning',
+ *   budget: 'premium',
+ *   exclude: ['gpt'],
+ *   limit: 3,
+ * });
+ * ```
+ */
+export declare function bestModel(options?: ModelSelectorOptions): Promise<ModelRecommendation[]>;

package/dist/model-selector.js

@@ -0,0 +1,247 @@
+/**
+ * Model Selector — pick the best open-source model using live WZRD velocity data.
+ *
+ * Combines on-chain attention signals from the WZRD protocol with
+ * OpenRouter pricing to compute a value score for every tracked model,
+ * then returns a ranked list filtered by budget, task, and trend.
+ *
+ * Usage:
+ *   import { bestModel } from '@wzrd_sol/sdk';
+ *   const picks = await bestModel({ task: 'code', budget: 'micro' });
+ *   console.log(picks[0].model_id);
+ *
+ * @module model-selector
+ */
+// ── Constants ─────────────────────────────────────────────────────
+const DEFAULT_WZRD_URL = 'https://api.twzrd.xyz';
+const DEFAULT_OPENROUTER_URL = 'https://openrouter.ai/api/v1/models';
+const DEFAULT_CACHE_TTL_MS = 300000; // 5 minutes
+const EPSILON = 0.001;
+/** Maximum blended price per million tokens for each budget tier. */
+const BUDGET_LIMITS = {
+    micro: 0.20,
+    budget: 1.00,
+    mid: 5.00,
+    premium: Infinity,
+};
+/** Confidence levels ranked from lowest to highest. */
+const CONFIDENCE_RANK = {
+    insufficient: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+};
+/** Task-specific model name patterns and their score boost multiplier. */
+const TASK_BOOSTS = {
+    code: {
+        patterns: ['deepseek', 'qwen', 'codestral', 'starcoder', 'coder'],
+        boost: 1.3,
+    },
+    reasoning: {
+        patterns: ['deepseek-r', 'o1', 'o3', 'reasoning'],
+        boost: 1.5,
+    },
+    chat: {
+        patterns: ['claude', 'gpt', 'gemini', 'chat', 'llama'],
+        boost: 1.1,
+    },
+};
+// ── ModelSelector Class ───────────────────────────────────────────
+/**
+ * Fetches WZRD velocity data and OpenRouter pricing, caches results,
+ * and scores models by value (velocity / cost).
+ *
+ * Create one instance and reuse it — the internal cache avoids redundant
+ * HTTP requests within the TTL window.
+ *
+ * @example
+ * ```ts
+ * const selector = new ModelSelector({ wzrd_base_url: 'https://api.twzrd.xyz' });
+ * const picks = await selector.select({ task: 'code', budget: 'budget', limit: 3 });
+ * console.log(picks[0].model_id);
+ * ```
+ */
+export class ModelSelector {
+    constructor(config = {}) {
+        this.cache = new Map();
+        this.wzrdBaseUrl = (config.wzrd_base_url ?? DEFAULT_WZRD_URL).replace(/\/+$/, '');
+        this.openrouterUrl = config.openrouter_url ?? DEFAULT_OPENROUTER_URL;
+        this.cacheTtlMs = config.cache_ttl_ms ?? DEFAULT_CACHE_TTL_MS;
+    }
+    /**
+     * Select the best models for a given task and budget.
+     *
+     * Fetches live data from the WZRD leaderboard, momentum signal, and
+     * OpenRouter catalog (all cached for 5 minutes by default), then ranks
+     * every OpenRouter model tracked by WZRD using:
+     *
+     *   value_score = velocity_ema / (blended_price_per_m_tokens + epsilon)
+     *
+     * Results are filtered by budget tier, task relevance, minimum confidence,
+     * and exclusion list, then sorted by value_score descending.
+     *
+     * @param options - Filtering and ranking options.
+     * @returns Ranked array of model recommendations (may be empty).
+     */
+    async select(options = {}) {
+        const { budget = 'mid', task = 'chat', min_confidence = 'low', limit = 5, exclude = [], } = options;
+        // Fetch all three data sources in parallel (cached).
+        const [leaderboard, momentum, catalog] = await Promise.all([
+            this.fetchLeaderboard(),
+            this.fetchMomentum(),
+            this.fetchOpenRouterCatalog(),
+        ]);
+        // If any critical source failed, return empty (graceful degradation).
+        if (leaderboard === null || catalog === null) {
+            return [];
+        }
+        // Build lookup indices.
+        const orIndex = new Map();
+        for (const m of catalog.data) {
+            orIndex.set(m.id, m);
+        }
+        const momentumIndex = new Map();
+        if (momentum !== null) {
+            for (const m of momentum.models) {
+                momentumIndex.set(m.market_id, m);
+            }
+        }
+        // Filtering thresholds.
+        const maxPrice = BUDGET_LIMITS[budget];
+        const minConfidenceRank = CONFIDENCE_RANK[min_confidence];
+        const taskBoost = TASK_BOOSTS[task];
+        const excludeLower = exclude.map((e) => e.toLowerCase());
+        const candidates = [];
+        for (const market of leaderboard.markets) {
+            if (market.platform !== 'openrouter')
+                continue;
+            if (market.status !== 'open')
+                continue;
+            const orModel = orIndex.get(market.channel_id);
+            if (!orModel)
+                continue;
+            // Exclusion filter.
+            if (excludeLower.some((e) => market.channel_id.toLowerCase().includes(e)))
+                continue;
+            // Compute blended price per million tokens (3:1 prompt:completion weighting).
+            const promptPrice = parseFloat(orModel.pricing?.prompt ?? '0');
+            const completionPrice = parseFloat(orModel.pricing?.completion ?? '0');
+            const blendedPerM = ((promptPrice * 3 + completionPrice) / 4) * 1000000;
+            // Budget filter.
+            if (blendedPerM > maxPrice)
+                continue;
+            // Momentum data.
+            const mom = momentumIndex.get(market.market_id);
+            const trend = mom?.velocity_trend ?? 'insufficient_history';
+            const confidence = mom?.history_confidence ?? 'insufficient';
+            // Confidence filter.
+            const confidenceRank = CONFIDENCE_RANK[confidence];
+            if (confidenceRank < minConfidenceRank)
+                continue;
+            // Compute value score: velocity / (price + epsilon).
+            const velocityEma = market.velocity_ema;
+            const rawValueScore = velocityEma / (blendedPerM + EPSILON);
+            // Apply task-specific boost.
+            let taskMultiplier = 1.0;
+            if (taskBoost) {
+                for (const pattern of taskBoost.patterns) {
+                    if (market.channel_id.toLowerCase().includes(pattern)) {
+                        taskMultiplier = taskBoost.boost;
+                        break;
+                    }
+                }
+            }
+            const valueScore = rawValueScore * taskMultiplier;
+            candidates.push({
+                model_id: market.channel_id,
+                provider: 'openrouter',
+                price_per_m_tokens: Math.round(blendedPerM * 1000) / 1000,
+                velocity_ema: velocityEma,
+                value_score: Math.round(valueScore * 1000) / 1000,
+                trend,
+                confidence,
+            });
+        }
+        // Sort by value_score descending.
+        candidates.sort((a, b) => b.value_score - a.value_score);
+        return candidates.slice(0, limit);
+    }
+    /**
+     * Invalidate the in-memory cache.
+     *
+     * Useful when you know upstream data has changed and want
+     * fresh results on the next `select()` call.
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    // ── Private Helpers ───────────────────────────────────────────
+    async fetchLeaderboard() {
+        return this.cachedFetch('wzrd:leaderboard', `${this.wzrdBaseUrl}/v1/leaderboard?limit=100`);
+    }
+    async fetchMomentum() {
+        return this.cachedFetch('wzrd:momentum', `${this.wzrdBaseUrl}/v1/signals/momentum`);
+    }
+    async fetchOpenRouterCatalog() {
+        return this.cachedFetch('openrouter:catalog', this.openrouterUrl);
+    }
+    /**
+     * Fetch JSON from a URL with in-memory TTL caching.
+     * Returns null on any error (network, HTTP status, parse failure).
+     */
+    async cachedFetch(key, url) {
+        const now = Date.now();
+        const cached = this.cache.get(key);
+        if (cached && cached.expires_at > now) {
+            return cached.data;
+        }
+        try {
+            const resp = await fetch(url);
+            if (!resp.ok) {
+                return null;
+            }
+            const data = (await resp.json());
+            this.cache.set(key, { data, expires_at: now + this.cacheTtlMs });
+            return data;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ── Convenience Function ──────────────────────────────────────────
+/** Shared singleton used by the convenience `bestModel()` function. */
+let defaultSelector = null;
+/**
+ * Pick the best open-source model for a task using live WZRD velocity data.
+ *
+ * This is a convenience wrapper around {@link ModelSelector.select} that
+ * uses a module-level singleton with default configuration. For custom
+ * base URLs or cache settings, instantiate {@link ModelSelector} directly.
+ *
+ * @param options - Filtering and ranking options.
+ * @returns Ranked array of model recommendations (may be empty if the API is unreachable).
+ *
+ * @example
+ * ```ts
+ * import { bestModel } from '@wzrd_sol/sdk';
+ *
+ * // Cheapest model good for code
+ * const picks = await bestModel({ task: 'code', budget: 'micro' });
+ * console.log(picks[0].model_id);
+ *
+ * // Premium reasoning model, exclude specific providers
+ * const reasoning = await bestModel({
+ *   task: 'reasoning',
+ *   budget: 'premium',
+ *   exclude: ['gpt'],
+ *   limit: 3,
+ * });
+ * ```
+ */
+export async function bestModel(options = {}) {
+    if (!defaultSelector) {
+        defaultSelector = new ModelSelector();
+    }
+    return defaultSelector.select(options);
+}

package/dist/pda.d.ts

@@ -16,5 +16,9 @@ export declare function getGlobalRootConfigPDA(ccmMint: PublicKey, programId?: P
 export declare function getClaimStatePDA(ccmMint: PublicKey, claimer: PublicKey, programId?: PublicKey): PublicKey;
 /** Derive a ChannelConfigV2 PDA for a given mint and subject. */
 export declare function getChannelConfigV2PDA(mint: PublicKey, subject: PublicKey, programId?: PublicKey): PublicKey;
+/** Derive the StreamRootConfig PDA for a given vLOFI mint. */
+export declare function getStreamRootConfigPDA(vlofiMint: PublicKey, programId?: PublicKey): PublicKey;
+/** Derive the per-user ClaimStateStream PDA. */
+export declare function getClaimStateStreamPDA(vlofiMint: PublicKey, claimer: PublicKey, programId?: PublicKey): PublicKey;
 /** Derive an Associated Token Account address (works for both SPL and Token-2022). */
 export declare function getAta(owner: PublicKey, mint: PublicKey, tokenProgramId: PublicKey): PublicKey;

package/dist/pda.js

@@ -4,7 +4,7 @@
  * Seeds must match programs/attention-oracle/src/constants.rs.
  */
 import { PublicKey } from '@solana/web3.js';
-import { PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, PROTOCOL_STATE_SEED, MARKET_VAULT_SEED, MARKET_POSITION_SEED, GLOBAL_ROOT_SEED, CLAIM_STATE_GLOBAL_SEED, CHANNEL_CONFIG_V2_SEED, } from './constants.js';
+import { PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, PROTOCOL_STATE_SEED, MARKET_VAULT_SEED, MARKET_POSITION_SEED, GLOBAL_ROOT_SEED, CLAIM_STATE_GLOBAL_SEED, CHANNEL_CONFIG_V2_SEED, STREAM_ROOT_SEED, CLAIM_STATE_STREAM_SEED, } from './constants.js';
 /** Derive the singleton ProtocolState PDA. */
 export function getProtocolStatePDA(programId = PROGRAM_ID) {
     return PublicKey.findProgramAddressSync([Buffer.from(PROTOCOL_STATE_SEED)], programId)[0];
@@ -31,6 +31,15 @@ export function getClaimStatePDA(ccmMint, claimer, programId = PROGRAM_ID) {
 export function getChannelConfigV2PDA(mint, subject, programId = PROGRAM_ID) {
     return PublicKey.findProgramAddressSync([Buffer.from(CHANNEL_CONFIG_V2_SEED), mint.toBuffer(), subject.toBuffer()], programId)[0];
 }
+// ── Stream (vLOFI distribution) PDA Derivation ──────────
+/** Derive the StreamRootConfig PDA for a given vLOFI mint. */
+export function getStreamRootConfigPDA(vlofiMint, programId = PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(STREAM_ROOT_SEED), vlofiMint.toBuffer()], programId)[0];
+}
+/** Derive the per-user ClaimStateStream PDA. */
+export function getClaimStateStreamPDA(vlofiMint, claimer, programId = PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(CLAIM_STATE_STREAM_SEED), vlofiMint.toBuffer(), claimer.toBuffer()], programId)[0];
+}
 /** Derive an Associated Token Account address (works for both SPL and Token-2022). */
 export function getAta(owner, mint, tokenProgramId) {
     return PublicKey.findProgramAddressSync([owner.toBuffer(), tokenProgramId.toBuffer(), mint.toBuffer()], ASSOCIATED_TOKEN_PROGRAM_ID)[0];