@wzrd_sol/sdk 0.1.1 → 0.2.0

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/nav.d.ts

@@ -0,0 +1,40 @@
+/**
+ * NAV (Net Asset Value) helpers for vLOFI share computation.
+ *
+ * These pure functions mirror the on-chain deposit/settle math so that
+ * clients can preview shares received or principal returned without
+ * submitting a transaction.
+ *
+ * NAV BPS domain:
+ *   - 10_000 = 1.00x (1 USDC per share, initial NAV)
+ *   - 50_000 = 5.00x (max NAV, protocol ceiling)
+ *   - 0 = uninitialized (pre-realloc vaults, treated as 10_000)
+ */
+/** Structured NAV data extracted from a MarketVault. */
+export interface NavInfo {
+    /** NAV per share in basis points (10_000 = 1.0x). Zero means uninitialized. */
+    navPerShareBps: bigint;
+    /** Slot at which NAV was last updated on-chain. */
+    lastNavUpdateSlot: bigint;
+    /** Human-readable share price in USDC terms (navPerShareBps / 10_000). */
+    sharePrice: number;
+}
+/**
+ * Compute the number of vLOFI shares a deposit of `amount` base units will mint.
+ *
+ * Formula (matches vault.rs deposit_market):
+ *   shares = amount * 10_000 / nav_per_share_bps
+ *
+ * If navPerShareBps is 0 (uninitialized / pre-realloc vault), falls back to
+ * the default 10_000 BPS (1:1 ratio).
+ */
+export declare function computeSharesForDeposit(amount: bigint, navPerShareBps: bigint): bigint;
+/**
+ * Compute the USDC principal returned when settling `shares` of vLOFI.
+ *
+ * Formula (matches vault.rs settle_market):
+ *   principal = shares * nav_per_share_bps / 10_000
+ *
+ * If navPerShareBps is 0 (uninitialized), falls back to 10_000 BPS.
+ */
+export declare function computePrincipalForSettle(shares: bigint, navPerShareBps: bigint): bigint;

package/dist/nav.js

@@ -0,0 +1,39 @@
+/**
+ * NAV (Net Asset Value) helpers for vLOFI share computation.
+ *
+ * These pure functions mirror the on-chain deposit/settle math so that
+ * clients can preview shares received or principal returned without
+ * submitting a transaction.
+ *
+ * NAV BPS domain:
+ *   - 10_000 = 1.00x (1 USDC per share, initial NAV)
+ *   - 50_000 = 5.00x (max NAV, protocol ceiling)
+ *   - 0 = uninitialized (pre-realloc vaults, treated as 10_000)
+ */
+const DEFAULT_NAV_BPS = 10000n;
+const BPS_SCALE = 10000n;
+/**
+ * Compute the number of vLOFI shares a deposit of `amount` base units will mint.
+ *
+ * Formula (matches vault.rs deposit_market):
+ *   shares = amount * 10_000 / nav_per_share_bps
+ *
+ * If navPerShareBps is 0 (uninitialized / pre-realloc vault), falls back to
+ * the default 10_000 BPS (1:1 ratio).
+ */
+export function computeSharesForDeposit(amount, navPerShareBps) {
+    const effectiveNav = navPerShareBps === 0n ? DEFAULT_NAV_BPS : navPerShareBps;
+    return (amount * BPS_SCALE) / effectiveNav;
+}
+/**
+ * Compute the USDC principal returned when settling `shares` of vLOFI.
+ *
+ * Formula (matches vault.rs settle_market):
+ *   principal = shares * nav_per_share_bps / 10_000
+ *
+ * If navPerShareBps is 0 (uninitialized), falls back to 10_000 BPS.
+ */
+export function computePrincipalForSettle(shares, navPerShareBps) {
+    const effectiveNav = navPerShareBps === 0n ? DEFAULT_NAV_BPS : navPerShareBps;
+    return (shares * effectiveNav) / BPS_SCALE;
+}

package/dist/nav.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Unit tests for NAV computation helpers (computeSharesForDeposit, computePrincipalForSettle).
+ */
+export {};

package/dist/nav.test.js

@@ -0,0 +1,98 @@
+/**
+ * Unit tests for NAV computation helpers (computeSharesForDeposit, computePrincipalForSettle).
+ */
+import { describe, it, expect } from 'vitest';
+import { computeSharesForDeposit, computePrincipalForSettle } from './nav.js';
+// ── computeSharesForDeposit ──────────────────────────────
+describe('computeSharesForDeposit', () => {
+    it('returns 1:1 shares at default NAV (10_000 BPS)', () => {
+        const shares = computeSharesForDeposit(1000000n, 10000n);
+        expect(shares).toBe(1000000n);
+    });
+    it('returns half shares at 2x NAV (20_000 BPS)', () => {
+        const shares = computeSharesForDeposit(1000000n, 20000n);
+        expect(shares).toBe(500000n);
+    });
+    it('handles zero NAV fallback — treats as 10_000 BPS', () => {
+        // zero nav fallback: uninitialized vault should behave like 1:1
+        const shares = computeSharesForDeposit(1000000n, 0n);
+        expect(shares).toBe(1000000n);
+    });
+    it('handles max NAV of 50_000 BPS (5.0x)', () => {
+        // max nav: 50_000 BPS ceiling
+        const shares = computeSharesForDeposit(5000000n, 50000n);
+        expect(shares).toBe(1000000n);
+    });
+    it('returns 0 shares for 0 deposit amount', () => {
+        const shares = computeSharesForDeposit(0n, 10000n);
+        expect(shares).toBe(0n);
+    });
+    it('handles large deposit without overflow', () => {
+        // overflow test: large amount should not throw
+        const amount = 1000000000000n; // 1M USDC in base units
+        const shares = computeSharesForDeposit(amount, 10000n);
+        expect(shares).toBe(amount);
+    });
+    it('truncates fractional shares (integer division)', () => {
+        // 3 base units at 2x NAV = 1.5 → truncates to 1
+        const shares = computeSharesForDeposit(3n, 20000n);
+        expect(shares).toBe(1n);
+    });
+});
+// ── computePrincipalForSettle ─────────────────────────────
+describe('computePrincipalForSettle', () => {
+    it('returns 1:1 principal at default NAV (10_000 BPS)', () => {
+        const principal = computePrincipalForSettle(1000000n, 10000n);
+        expect(principal).toBe(1000000n);
+    });
+    it('returns double principal at 2x NAV (20_000 BPS)', () => {
+        const principal = computePrincipalForSettle(1000000n, 20000n);
+        expect(principal).toBe(2000000n);
+    });
+    it('handles zero NAV fallback — treats as 10_000 BPS', () => {
+        // zero nav fallback
+        const principal = computePrincipalForSettle(1000000n, 0n);
+        expect(principal).toBe(1000000n);
+    });
+    it('handles max NAV of 50_000 BPS (5.0x)', () => {
+        // max nav: 50_000 BPS ceiling
+        const principal = computePrincipalForSettle(1000000n, 50000n);
+        expect(principal).toBe(5000000n);
+    });
+    it('returns 0 principal for 0 shares', () => {
+        const principal = computePrincipalForSettle(0n, 10000n);
+        expect(principal).toBe(0n);
+    });
+    it('handles large shares without overflow', () => {
+        // overflow test: large shares
+        const shares = 1000000000000n;
+        const principal = computePrincipalForSettle(shares, 10000n);
+        expect(principal).toBe(shares);
+    });
+});
+// ── NavInfo type ─────────────────────────────────────────
+describe('NavInfo type', () => {
+    it('can be constructed with valid fields', () => {
+        const info = {
+            navPerShareBps: 15000n,
+            lastNavUpdateSlot: 405000000n,
+            sharePrice: 1.5,
+        };
+        expect(info.navPerShareBps).toBe(15000n);
+        expect(info.lastNavUpdateSlot).toBe(405000000n);
+        expect(info.sharePrice).toBe(1.5);
+    });
+});
+// ── Round-trip deposit→settle ────────────────────────────
+describe('deposit-settle round trip', () => {
+    it('deposit then settle at same NAV returns original amount', () => {
+        const amount = 1000000n;
+        const nav = 12500n;
+        const shares = computeSharesForDeposit(amount, nav);
+        const principal = computePrincipalForSettle(shares, nav);
+        // Due to integer division, principal <= amount
+        expect(principal).toBeLessThanOrEqual(amount);
+        // But should be close (within 1 base unit rounding)
+        expect(amount - principal).toBeLessThan(nav);
+    });
+});

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];

package/dist/stream.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Instruction builders for the wzrd-stream vLOFI claim system.
+ *
+ * Builds publish_stream_root, claim_stream, and claim_stream_sponsored
+ * TransactionInstructions for the vLOFI streaming distribution pipeline.
+ *
+ * Unlike CCM global claims (Token-2022), stream claims use standard SPL
+ * token program for vLOFI minting.
+ */
+import { PublicKey, TransactionInstruction } from '@solana/web3.js';
+/**
+ * Build a `publish_stream_root` TransactionInstruction.
+ *
+ * Publishes a new merkle root for vLOFI stream distribution.
+ *
+ * Accounts (order must match PublishStreamRoot struct):
+ *   0. payer              (signer, writable) - admin or publisher
+ *   1. protocol_state     (readonly)
+ *   2. stream_root_config (writable) - PDA: seeds=[b"stream_root", vlofiMint]
+ *   3. vlofi_mint         (readonly)
+ *   4. system_program     (readonly)
+ *
+ * Data layout: [8 disc][8 root_seq LE][32 root][32 dataset_hash] = 80 bytes
+ *
+ * @param payer       - Admin or authorized publisher (signer)
+ * @param vlofiMint   - vLOFI mint address
+ * @param rootSeq     - Monotonically increasing root sequence number
+ * @param root        - 32-byte merkle root hash
+ * @param datasetHash - 32-byte dataset hash for auditability
+ * @param programId   - Program ID (defaults to mainnet)
+ */
+export declare function createPublishStreamRootIx(payer: PublicKey, vlofiMint: PublicKey, rootSeq: number | bigint, root: Uint8Array | Buffer, datasetHash: Uint8Array | Buffer, programId?: PublicKey): TransactionInstruction;
+/**
+ * Build a `claim_stream` TransactionInstruction (self-signed).
+ *
+ * Claims vLOFI tokens from the stream distribution merkle tree.
+ * The claimer signs the transaction themselves.
+ *
+ * Accounts (order must match ClaimStream struct):
+ *   0. claimer            (signer, writable)
+ *   1. protocol_state     (readonly)
+ *   2. stream_root_config (readonly)
+ *   3. claim_state_stream (writable) - PDA: seeds=[b"claim_stream", vlofiMint, claimer]
+ *   4. vlofi_mint         (writable) - for mint_to
+ *   5. claimer_vlofi_ata  (writable) - ATA(claimer, vlofiMint, TOKEN_PROGRAM)
+ *   6. token_program      (readonly) - standard SPL Token
+ *   7. system_program     (readonly)
+ *
+ * Data layout: [8 disc][8 root_seq LE][8 cumulative_total LE][4 proof_len LE][proof_len * 32 proof_nodes]
+ *
+ * @param claimer         - Wallet claiming vLOFI (signer)
+ * @param vlofiMint       - vLOFI mint address
+ * @param rootSeq         - Root sequence number to claim against
+ * @param cumulativeTotal - Cumulative vLOFI amount entitled (native units)
+ * @param proofHex        - Hex-encoded 32-byte merkle proof sibling hashes
+ * @param programId       - Program ID (defaults to mainnet)
+ * @returns Array of instructions: idempotent ATA create + claim IX
+ */
+export declare function createClaimStreamIx(claimer: PublicKey, vlofiMint: PublicKey, rootSeq: number | bigint, cumulativeTotal: bigint | number, proofHex: string[], programId?: PublicKey): TransactionInstruction[];
+/**
+ * Build a `claim_stream_sponsored` TransactionInstruction (gasless relay).
+ *
+ * A relayer pays for the transaction while vLOFI goes to the claimer.
+ * The claimer does NOT need to sign.
+ *
+ * Accounts (order must match ClaimStreamSponsored struct):
+ *   0. payer              (signer, writable) - relayer
+ *   1. claimer            (readonly, NOT signer)
+ *   2. protocol_state     (readonly)
+ *   3. stream_root_config (readonly)
+ *   4. claim_state_stream (writable)
+ *   5. vlofi_mint         (writable)
+ *   6. claimer_vlofi_ata  (writable)
+ *   7. token_program      (readonly)
+ *   8. system_program     (readonly)
+ *
+ * Data layout: same as claim_stream
+ *
+ * @param payer           - Relayer wallet (signer, pays fees)
+ * @param claimer         - Wallet receiving vLOFI (NOT a signer)
+ * @param vlofiMint       - vLOFI mint address
+ * @param rootSeq         - Root sequence number to claim against
+ * @param cumulativeTotal - Cumulative vLOFI amount entitled (native units)
+ * @param proofHex        - Hex-encoded 32-byte merkle proof sibling hashes
+ * @param programId       - Program ID (defaults to mainnet)
+ * @returns Array of instructions: idempotent ATA create + sponsored claim IX
+ */
+export declare function createClaimStreamSponsoredIx(payer: PublicKey, claimer: PublicKey, vlofiMint: PublicKey, rootSeq: number | bigint, cumulativeTotal: bigint | number, proofHex: string[], programId?: PublicKey): TransactionInstruction[];