@wzrd_sol/sdk 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# @wzrd/sdk
+
+TypeScript SDK for the Liquid Attention Protocol on Solana.
+
+Builds `deposit_market`, `settle_market`, and `claim_global` transaction instructions that wallets sign directly — no server signing needed.
+
+## Install
+
+```bash
+npm install @wzrd/sdk @solana/web3.js
+```
+
+## Example Scripts
+
+From the repo root:
+
+```bash
+npm run build --workspace=sdk
+npm run typecheck:examples --workspace=sdk
+```
+
+Runnable examples:
+
+- `npm run example:deposit --workspace=sdk`
+- `npm run example:claim --workspace=sdk`
+
+Both examples expect:
+
+- `SOLANA_RPC_URL`
+- `WZRD_KEYPAIR_PATH`
+
+The deposit example also expects:
+
+- `WZRD_MARKET_ID`
+- `WZRD_DEPOSIT_USDC`
+
+## Quick Reference
+
+### PDA Derivation
+
+```typescript
+import {
+  getProtocolStatePDA,
+  getMarketVaultPDA,
+  getUserPositionPDA,
+  getGlobalRootConfigPDA,
+  getClaimStatePDA,
+  PROGRAM_ID,
+} from '@wzrd/sdk';
+
+const protocolState = getProtocolStatePDA();
+const marketVault = getMarketVaultPDA(protocolState, 6); // market ID 6
+const position = getUserPositionPDA(marketVault, walletPubkey);
+```
+
+### Deposit USDC → Receive vLOFI
+
+```typescript
+import { Connection, Keypair, VersionedTransaction, TransactionMessage } from '@solana/web3.js';
+import { createDepositMarketIx } from '@wzrd/sdk';
+
+const connection = new Connection('https://api.mainnet-beta.solana.com');
+const wallet = Keypair.fromSecretKey(/* your key */);
+
+// Build instructions for a 1 USDC deposit into market 6
+const ixs = await createDepositMarketIx(connection, wallet.publicKey, 6, 1_000_000n);
+
+const { blockhash } = await connection.getLatestBlockhash();
+const message = new TransactionMessage({
+  payerKey: wallet.publicKey,
+  recentBlockhash: blockhash,
+  instructions: ixs,
+}).compileToV0Message();
+
+const tx = new VersionedTransaction(message);
+tx.sign([wallet]);
+const sig = await connection.sendTransaction(tx);
+console.log('Deposit tx:', sig);
+```
+
+### Claim CCM via Merkle Proof
+
+```typescript
+import { createClaimGlobalIx } from '@wzrd/sdk';
+
+// Fetch proof from the server API
+const res = await fetch(`https://api.twzrd.xyz/v1/claims/${wallet.publicKey.toBase58()}`);
+const { root_seq, cumulative_total, proof } = await res.json();
+
+const ixs = await createClaimGlobalIx(
+  connection,
+  wallet.publicKey,
+  root_seq,
+  BigInt(cumulative_total),
+  proof, // hex-encoded [u8; 32] nodes
+);
+
+// Build, sign, send as above
+```
+
+### Settle a Matured Position
+
+```typescript
+import { createSettleMarketIx } from '@wzrd/sdk';
+
+const ixs = await createSettleMarketIx(connection, wallet.publicKey, 6);
+// Build, sign, send as above
+```
+
+### Read On-Chain State
+
+```typescript
+import { fetchMarketVault, fetchOnChainPosition, fetchTokenBalance } from '@wzrd/sdk';
+
+const vault = await fetchMarketVault(connection, 6);
+console.log('Total deposited:', vault?.totalDeposited);
+
+const pos = await fetchOnChainPosition(connection, wallet.publicKey, 6);
+console.log('My deposit:', pos?.depositedAmount, 'Multiplier:', pos?.attentionMultiplierBps);
+```
+
+## Exports
+
+### Constants
+
+| Export | Description |
+|--------|-------------|
+| `PROGRAM_ID` | Mainnet program ID (`GnGz...`) |
+| `DEVNET_PROGRAM_ID` | Devnet program ID (`GmGX...`) |
+| `TOKEN_PROGRAM_ID` | SPL Token program |
+| `TOKEN_2022_PROGRAM_ID` | Token-2022 program (CCM uses this) |
+
+### PDA Derivation
+
+| Function | Seeds |
+|----------|-------|
+| `getProtocolStatePDA()` | `["protocol_state"]` |
+| `getMarketVaultPDA(protocolState, marketId)` | `["market_vault", protocolState, marketId]` |
+| `getUserPositionPDA(marketVault, user)` | `["market_position", marketVault, user]` |
+| `getGlobalRootConfigPDA(ccmMint)` | `["global_root", ccmMint]` |
+| `getClaimStatePDA(ccmMint, claimer)` | `["claim_global", ccmMint, claimer]` |
+
+### Instruction Builders
+
+| Function | On-chain instruction |
+|----------|---------------------|
+| `createDepositMarketIx(conn, user, marketId, amount)` | `deposit_market` |
+| `createSettleMarketIx(conn, user, marketId)` | `settle_market` |
+| `createClaimGlobalIx(conn, claimer, rootSeq, total, proof)` | `claim_global` |
+| `createInitializeMarketVaultIx(admin, marketId, ...)` | `initialize_market_vault` |
+
+### Account Parsers
+
+| Function | Account type |
+|----------|-------------|
+| `parseMarketVault(data)` | `MarketVault` |
+| `parseProtocolState(data)` | `ProtocolState` |
+| `parseUserMarketPosition(data)` | `UserMarketPosition` |
+| `fetchMarketVault(conn, marketId)` | Fetch + parse |
+| `fetchOnChainPosition(conn, user, marketId)` | Fetch + parse |
+| `fetchTokenBalance(conn, ata)` | Raw token balance |
+
+## Key Addresses
+
+| Asset | Mint | Token Program |
+|-------|------|---------------|
+| USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | SPL Token |
+| vLOFI | `E9Kt33axpCy3ve2PCY9BSrbPhcR9wdDsWQECAahzw2dS` | SPL Token |
+| CCM | `Dxk8mAb3C7AM8JN6tAJfVuSja5yidhZM5sEKW3SRX2BM` | Token-2022 |

package/dist/accounts.d.ts

@@ -0,0 +1,60 @@
+/**
+ * On-chain account deserialization for the Liquid Attention Protocol.
+ *
+ * Layouts must match the Anchor account structs defined in
+ * programs/attention-oracle/src/state/*.rs.
+ */
+import { Connection, PublicKey } from '@solana/web3.js';
+export interface MarketVaultData {
+    bump: number;
+    depositMint: PublicKey;
+    vlofiMint: PublicKey;
+    vaultAta: PublicKey;
+}
+export interface MarketVaultFull extends MarketVaultData {
+    marketId: number;
+    totalDeposited: bigint;
+    totalShares: bigint;
+}
+export interface ProtocolStateData {
+    isInitialized: boolean;
+    version: number;
+    admin: PublicKey;
+    publisher: PublicKey;
+    treasury: PublicKey;
+    oracleAuthority: PublicKey;
+    /** CCM (reward) mint address */
+    mint: PublicKey;
+    /** USDC (or deposit token) mint address — added for market vault init discovery */
+    depositMint?: PublicKey;
+    paused: boolean;
+    requireReceipt: boolean;
+    bump: number;
+}
+export interface OnChainPosition {
+    user: PublicKey;
+    marketVault: PublicKey;
+    depositedAmount: bigint;
+    sharesMinted: bigint;
+    attentionMultiplierBps: bigint;
+    settled: boolean;
+    entrySlot: bigint;
+}
+/** Parse a MarketVault account's core fields (skip Anchor discriminator). */
+export declare function parseMarketVault(data: Buffer): MarketVaultData;
+/**
+ * Parse a ProtocolState account (matches `ProtocolState` struct in state/protocol.rs).
+ *
+ * Layout after 8-byte Anchor discriminator:
+ *   is_initialized(1) + version(1) + admin(32) + publisher(32)
+ *   + treasury(32) + oracle_authority(32) + mint(32) + paused(1) + require_receipt(1) + bump(1)
+ */
+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;
+/** 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. */
+export declare function fetchMarketVault(connection: Connection, marketId: number, programId?: PublicKey): Promise<MarketVaultFull | null>;
+/** Read a token account balance from chain. */
+export declare function fetchTokenBalance(connection: Connection, tokenAccount: PublicKey): Promise<bigint>;

package/dist/accounts.js

@@ -0,0 +1,93 @@
+/**
+ * On-chain account deserialization for the Liquid Attention Protocol.
+ *
+ * Layouts must match the Anchor account structs defined in
+ * programs/attention-oracle/src/state/*.rs.
+ */
+import { PublicKey } from '@solana/web3.js';
+import { getProtocolStatePDA, getMarketVaultPDA, getUserPositionPDA } from './pda';
+// ── Parsers ────────────────────────────────────────────
+/** Parse a MarketVault account's core fields (skip Anchor discriminator). */
+export function parseMarketVault(data) {
+    const d = data.subarray(8);
+    return {
+        bump: d[0],
+        // market_id at offset 1 (8 bytes) — skip
+        depositMint: new PublicKey(d.subarray(9, 41)),
+        vlofiMint: new PublicKey(d.subarray(41, 73)),
+        vaultAta: new PublicKey(d.subarray(73, 105)),
+    };
+}
+/**
+ * Parse a ProtocolState account (matches `ProtocolState` struct in state/protocol.rs).
+ *
+ * Layout after 8-byte Anchor discriminator:
+ *   is_initialized(1) + version(1) + admin(32) + publisher(32)
+ *   + treasury(32) + oracle_authority(32) + mint(32) + paused(1) + require_receipt(1) + bump(1)
+ */
+export function parseProtocolState(data) {
+    const d = data.subarray(8);
+    return {
+        isInitialized: d[0] !== 0,
+        version: d[1],
+        admin: new PublicKey(d.subarray(2, 34)),
+        publisher: new PublicKey(d.subarray(34, 66)),
+        treasury: new PublicKey(d.subarray(66, 98)),
+        oracleAuthority: new PublicKey(d.subarray(98, 130)),
+        mint: new PublicKey(d.subarray(130, 162)),
+        paused: d[162] !== 0,
+        requireReceipt: d[163] !== 0,
+        bump: d[164],
+    };
+}
+/** Parse a UserMarketPosition account. Returns null if data is too short. */
+export function parseUserMarketPosition(data) {
+    if (data.length < 106)
+        return null;
+    const d = data.subarray(8); // skip Anchor discriminator
+    return {
+        user: new PublicKey(d.subarray(1, 33)),
+        marketVault: new PublicKey(d.subarray(33, 65)),
+        depositedAmount: d.readBigUInt64LE(65),
+        sharesMinted: d.readBigUInt64LE(73),
+        attentionMultiplierBps: d.readBigUInt64LE(81),
+        settled: d[89] !== 0,
+        entrySlot: d.readBigUInt64LE(90),
+    };
+}
+// ── Fetch Helpers ──────────────────────────────────────
+/** Fetch a user's position for a specific market directly from chain. */
+export async function fetchOnChainPosition(connection, user, marketId, programId) {
+    const protocolState = getProtocolStatePDA(programId);
+    const marketVault = getMarketVaultPDA(protocolState, marketId, programId);
+    const positionPda = getUserPositionPDA(marketVault, user, programId);
+    const info = await connection.getAccountInfo(positionPda);
+    if (!info)
+        return null;
+    return parseUserMarketPosition(Buffer.from(info.data));
+}
+/** Fetch the full MarketVault data from chain. */
+export async function fetchMarketVault(connection, marketId, programId) {
+    const protocolState = getProtocolStatePDA(programId);
+    const marketVault = getMarketVaultPDA(protocolState, marketId, programId);
+    const info = await connection.getAccountInfo(marketVault);
+    if (!info)
+        return null;
+    const d = Buffer.from(info.data).subarray(8);
+    return {
+        bump: d[0],
+        depositMint: new PublicKey(d.subarray(9, 41)),
+        vlofiMint: new PublicKey(d.subarray(41, 73)),
+        vaultAta: new PublicKey(d.subarray(73, 105)),
+        marketId,
+        totalDeposited: d.readBigUInt64LE(105),
+        totalShares: d.readBigUInt64LE(113),
+    };
+}
+/** Read a token account balance from chain. */
+export async function fetchTokenBalance(connection, tokenAccount) {
+    const info = await connection.getAccountInfo(tokenAccount);
+    if (!info || info.data.length < 72)
+        return 0n;
+    return Buffer.from(info.data.subarray(64, 72)).readBigUInt64LE(0);
+}

package/dist/constants.d.ts

@@ -0,0 +1,16 @@
+import { PublicKey } from '@solana/web3.js';
+/** Devnet program ID (matches declare_id! in lib.rs) */
+export declare const DEVNET_PROGRAM_ID: PublicKey;
+/** Mainnet program ID */
+export declare const MAINNET_PROGRAM_ID: PublicKey;
+/** Default program ID — mainnet */
+export declare const PROGRAM_ID: PublicKey;
+export declare const TOKEN_PROGRAM_ID: PublicKey;
+export declare const TOKEN_2022_PROGRAM_ID: PublicKey;
+export declare const ASSOCIATED_TOKEN_PROGRAM_ID: PublicKey;
+export declare const PROTOCOL_STATE_SEED = "protocol_state";
+export declare const MARKET_VAULT_SEED = "market_vault";
+export declare const MARKET_POSITION_SEED = "market_position";
+export declare const GLOBAL_ROOT_SEED = "global_root";
+export declare const CLAIM_STATE_GLOBAL_SEED = "claim_global";
+export declare const CHANNEL_CONFIG_V2_SEED = "channel_cfg_v2";

package/dist/constants.js

@@ -0,0 +1,19 @@
+import { PublicKey } from '@solana/web3.js';
+// ── Program IDs ────────────────────────────────────────
+/** Devnet program ID (matches declare_id! in lib.rs) */
+export const DEVNET_PROGRAM_ID = new PublicKey('GmGXXNjLhxKdEfCqnYgW2tev4DewPvgUXzhsVfm677VW');
+/** Mainnet program ID */
+export const MAINNET_PROGRAM_ID = new PublicKey('GnGzNdsQMxMpJfMeqnkGPsvHm8kwaDidiKjNU2dCVZop');
+/** Default program ID — mainnet */
+export const PROGRAM_ID = MAINNET_PROGRAM_ID;
+// ── Token Program IDs ──────────────────────────────────
+export const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+export const TOKEN_2022_PROGRAM_ID = new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb');
+export const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+// ── PDA Seeds (must match programs/attention-oracle/src/constants.rs) ──
+export const PROTOCOL_STATE_SEED = 'protocol_state';
+export const MARKET_VAULT_SEED = 'market_vault';
+export const MARKET_POSITION_SEED = 'market_position';
+export const GLOBAL_ROOT_SEED = 'global_root';
+export const CLAIM_STATE_GLOBAL_SEED = 'claim_global';
+export const CHANNEL_CONFIG_V2_SEED = 'channel_cfg_v2';

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @wzrd/sdk — TypeScript SDK for the Liquid Attention Protocol.
+ *
+ * PDA derivation, instruction builders, and account parsers for
+ * deposit_market, settle_market, and claim_global.
+ */
+export declare const VERSION = "0.1.0";
+export { PROGRAM_ID, DEVNET_PROGRAM_ID, MAINNET_PROGRAM_ID, TOKEN_PROGRAM_ID, TOKEN_2022_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';
+export { getProtocolStatePDA, getMarketVaultPDA, getUserPositionPDA, getGlobalRootConfigPDA, getClaimStatePDA, getChannelConfigV2PDA, getAta, } from './pda';
+export type { MarketVaultData, MarketVaultFull, ProtocolStateData, OnChainPosition, } from './accounts';
+export { parseMarketVault, parseProtocolState, parseUserMarketPosition, fetchOnChainPosition, fetchMarketVault, fetchTokenBalance, } from './accounts';
+export { anchorDisc, createAtaIdempotentIx, createDepositMarketIx, createSettleMarketIx, createInitializeMarketVaultIx, createClaimGlobalIx, createChannelConfigV2Ix, } from './instructions';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @wzrd/sdk — TypeScript SDK for the Liquid Attention Protocol.
+ *
+ * PDA derivation, instruction builders, and account parsers for
+ * deposit_market, settle_market, and claim_global.
+ */
+export const VERSION = '0.1.0';
+// ── Constants ──────────────────────────────────────────
+export { PROGRAM_ID, DEVNET_PROGRAM_ID, MAINNET_PROGRAM_ID, TOKEN_PROGRAM_ID, TOKEN_2022_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';
+// ── PDA Derivation ─────────────────────────────────────
+export { getProtocolStatePDA, getMarketVaultPDA, getUserPositionPDA, getGlobalRootConfigPDA, getClaimStatePDA, getChannelConfigV2PDA, getAta, } from './pda';
+export { parseMarketVault, parseProtocolState, parseUserMarketPosition, fetchOnChainPosition, fetchMarketVault, fetchTokenBalance, } from './accounts';
+// ── Instruction Builders ───────────────────────────────
+export { anchorDisc, createAtaIdempotentIx, createDepositMarketIx, createSettleMarketIx, createInitializeMarketVaultIx, createClaimGlobalIx, createChannelConfigV2Ix, } from './instructions';

package/dist/instructions.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Instruction builders for the Liquid Attention Protocol.
+ *
+ * Builds deposit_market, settle_market, and claim_global TransactionInstructions
+ * that the wallet adapter signs directly — no server signing needed.
+ */
+import { Connection, PublicKey, TransactionInstruction } from '@solana/web3.js';
+/**
+ * Anchor instruction discriminator: first 8 bytes of SHA-256("global:<name>").
+ * Works in both browser (WebCrypto) and Node.js (crypto module) environments.
+ */
+export declare function anchorDisc(name: string): Promise<Buffer>;
+/** Build a CreateIdempotent ATA instruction (instruction index 1). Never fails if ATA exists. */
+export declare function createAtaIdempotentIx(payer: PublicKey, ata: PublicKey, owner: PublicKey, mint: PublicKey, tokenProgramId?: PublicKey): TransactionInstruction;
+/**
+ * Build a `deposit_market` TransactionInstruction.
+ *
+ * Accounts (order must match DepositMarket struct in vault.rs):
+ *   0. user              (signer, writable)
+ *   1. protocol_state    (readonly)
+ *   2. market_vault      (writable)
+ *   3. user_market_position (writable)
+ *   4. user_usdc_ata     (writable)
+ *   5. vault_usdc_ata    (writable)
+ *   6. vlofi_mint        (writable)
+ *   7. user_vlofi_ata    (writable)
+ *   8. token_program     (readonly)
+ *   9. token_2022_program (readonly)
+ *  10. system_program    (readonly)
+ *
+ * @returns Array of instructions: idempotent ATA creates + the deposit IX.
+ */
+export declare function createDepositMarketIx(connection: Connection, user: PublicKey, marketId: number, 
+/** USDC amount in native units (6 decimals, e.g., 1_000_000 = 1 USDC) */
+amount: bigint | number, programId?: PublicKey): Promise<TransactionInstruction[]>;
+/**
+ * Build a `settle_market` TransactionInstruction.
+ *
+ * Accounts (order must match SettleMarket struct in vault.rs):
+ *   0. user              (signer, writable)
+ *   1. protocol_state    (readonly)
+ *   2. market_vault      (writable)
+ *   3. user_market_position (writable)
+ *   4. vlofi_mint        (writable)
+ *   5. user_vlofi_ata    (writable)
+ *   6. vault_usdc_ata    (writable)
+ *   7. user_usdc_ata     (writable)
+ *   8. ccm_mint          (writable)
+ *   9. user_ccm_ata      (writable)
+ *  10. token_program     (readonly) — legacy SPL (USDC)
+ *  11. token_2022_program (readonly) — vLOFI burn
+ *  12. ccm_token_program (readonly) — CCM mint (Token-2022 on mainnet)
+ *
+ * @returns Array of instructions: idempotent ATA create for CCM + the settle IX.
+ */
+export declare function createSettleMarketIx(connection: Connection, user: PublicKey, marketId: number, programId?: PublicKey): Promise<TransactionInstruction[]>;
+/**
+ * Build an `initialize_market_vault` TransactionInstruction.
+ *
+ * Accounts (order must match InitializeMarketVault struct in vault.rs):
+ *   0. admin            (signer, writable)
+ *   1. protocol_state   (readonly)
+ *   2. market_vault     (writable, init)
+ *   3. deposit_mint     (readonly) — USDC
+ *   4. vlofi_mint       (readonly) — Token-2022
+ *   5. vault_ata        (readonly) — Pre-created ATA owned by vault PDA
+ *   6. system_program   (readonly)
+ */
+export declare function createInitializeMarketVaultIx(admin: PublicKey, marketId: number, depositMint: PublicKey, vlofiMint: PublicKey, programId?: PublicKey): Promise<TransactionInstruction>;
+/**
+ * Build a `claim_global` TransactionInstruction.
+ *
+ * Accounts (must match ClaimGlobal struct in global.rs):
+ *   0. claimer             (signer, writable)
+ *   1. protocol_state      (writable)
+ *   2. global_root_config  (readonly)
+ *   3. claim_state         (writable, init_if_needed)
+ *   4. mint                (readonly) — CCM Token-2022 mint
+ *   5. treasury_ata        (writable)
+ *   6. claimer_ata         (writable, init_if_needed)
+ *   7. token_program       (readonly) — Token-2022
+ *   8. associated_token_program (readonly)
+ *   9. system_program      (readonly)
+ *
+ * @returns Array of instructions: idempotent ATA create for claimer CCM + the claim IX.
+ */
+export declare function createClaimGlobalIx(connection: Connection, claimer: PublicKey, rootSeq: number, cumulativeTotal: bigint | number, 
+/** Hex-encoded 32-byte sibling hashes from the claims API */
+proofHex: string[], programId?: PublicKey): Promise<TransactionInstruction[]>;
+/**
+ * Build a `create_channel_config_v2` TransactionInstruction.
+ *
+ * Accounts (order must match CreateChannelConfigV2 struct in admin.rs):
+ *   0. admin            (signer, writable)
+ *   1. protocol_state   (readonly)
+ *   2. channel_config   (writable, init)
+ *   3. system_program   (readonly)
+ *
+ * Args (Borsh-serialized):
+ *   subject:         Pubkey (32 bytes)
+ *   authority:       Pubkey (32 bytes)
+ *   creator_wallet:  Pubkey (32 bytes)
+ *   creator_fee_bps: u16   (2 bytes LE)
+ */
+export declare function createChannelConfigV2Ix(admin: PublicKey, 
+/** CCM mint pubkey (from ProtocolState.mint) */
+mint: PublicKey, subject: PublicKey, authority: PublicKey, creatorWallet: PublicKey, creatorFeeBps: number, programId?: PublicKey): Promise<TransactionInstruction>;

package/dist/instructions.js

@@ -0,0 +1,332 @@
+/**
+ * Instruction builders for the Liquid Attention Protocol.
+ *
+ * Builds deposit_market, settle_market, and claim_global TransactionInstructions
+ * that the wallet adapter signs directly — no server signing needed.
+ */
+import { SystemProgram, TransactionInstruction, } from '@solana/web3.js';
+import { PROGRAM_ID, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, } from './constants';
+import { getProtocolStatePDA, getMarketVaultPDA, getUserPositionPDA, getGlobalRootConfigPDA, getClaimStatePDA, getChannelConfigV2PDA, getAta, } from './pda';
+import { parseMarketVault, parseProtocolState } from './accounts';
+// ── Helpers ────────────────────────────────────────────
+/**
+ * Anchor instruction discriminator: first 8 bytes of SHA-256("global:<name>").
+ * Works in both browser (WebCrypto) and Node.js (crypto module) environments.
+ */
+export async function anchorDisc(name) {
+    const preimage = `global:${name}`;
+    // Node.js path — use built-in crypto module
+    if (typeof globalThis.process !== 'undefined') {
+        const { createHash } = await import('crypto');
+        const hash = createHash('sha256').update(preimage).digest();
+        return Buffer.from(hash.subarray(0, 8));
+    }
+    // Browser path — WebCrypto
+    const encoded = new TextEncoder().encode(preimage);
+    const hash = await crypto.subtle.digest('SHA-256', encoded.buffer);
+    return Buffer.from(new Uint8Array(hash).slice(0, 8));
+}
+/** Build a CreateIdempotent ATA instruction (instruction index 1). Never fails if ATA exists. */
+export function createAtaIdempotentIx(payer, ata, owner, mint, tokenProgramId = TOKEN_PROGRAM_ID) {
+    return new TransactionInstruction({
+        programId: ASSOCIATED_TOKEN_PROGRAM_ID,
+        keys: [
+            { pubkey: payer, isSigner: true, isWritable: true },
+            { pubkey: ata, isSigner: false, isWritable: true },
+            { pubkey: owner, isSigner: false, isWritable: false },
+            { pubkey: mint, isSigner: false, isWritable: false },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+            { pubkey: tokenProgramId, isSigner: false, isWritable: false },
+        ],
+        data: Buffer.from([1]), // CreateIdempotent
+    });
+}
+// ── Instruction Builders ───────────────────────────────
+/**
+ * Build a `deposit_market` TransactionInstruction.
+ *
+ * Accounts (order must match DepositMarket struct in vault.rs):
+ *   0. user              (signer, writable)
+ *   1. protocol_state    (readonly)
+ *   2. market_vault      (writable)
+ *   3. user_market_position (writable)
+ *   4. user_usdc_ata     (writable)
+ *   5. vault_usdc_ata    (writable)
+ *   6. vlofi_mint        (writable)
+ *   7. user_vlofi_ata    (writable)
+ *   8. token_program     (readonly)
+ *   9. token_2022_program (readonly)
+ *  10. system_program    (readonly)
+ *
+ * @returns Array of instructions: idempotent ATA creates + the deposit IX.
+ */
+export async function createDepositMarketIx(connection, user, marketId, 
+/** USDC amount in native units (6 decimals, e.g., 1_000_000 = 1 USDC) */
+amount, programId = PROGRAM_ID) {
+    const protocolState = getProtocolStatePDA(programId);
+    const marketVault = getMarketVaultPDA(protocolState, marketId, programId);
+    const userPosition = getUserPositionPDA(marketVault, user, programId);
+    // Fetch vault to discover mints
+    const vaultInfo = await connection.getAccountInfo(marketVault);
+    if (!vaultInfo)
+        throw new Error(`MarketVault not found for market ${marketId}`);
+    const vault = parseMarketVault(Buffer.from(vaultInfo.data));
+    const userUsdcAta = getAta(user, vault.depositMint, TOKEN_PROGRAM_ID);
+    const userVlofiAta = getAta(user, vault.vlofiMint, TOKEN_PROGRAM_ID);
+    // Prepend idempotent ATA creation for USDC and vLOFI (no-ops if they exist)
+    const ixs = [
+        createAtaIdempotentIx(user, userUsdcAta, user, vault.depositMint, TOKEN_PROGRAM_ID),
+        createAtaIdempotentIx(user, userVlofiAta, user, vault.vlofiMint, TOKEN_PROGRAM_ID),
+    ];
+    // Instruction data: [8 disc][8 market_id LE][8 amount LE]
+    const disc = await anchorDisc('deposit_market');
+    const data = Buffer.alloc(24);
+    disc.copy(data, 0);
+    data.writeBigUInt64LE(BigInt(marketId), 8);
+    data.writeBigUInt64LE(BigInt(amount), 16);
+    ixs.push(new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: user, isSigner: true, isWritable: true },
+            { pubkey: protocolState, isSigner: false, isWritable: false },
+            { pubkey: marketVault, isSigner: false, isWritable: true },
+            { pubkey: userPosition, isSigner: false, isWritable: true },
+            { pubkey: userUsdcAta, isSigner: false, isWritable: true },
+            { pubkey: vault.vaultAta, isSigner: false, isWritable: true },
+            { pubkey: vault.vlofiMint, isSigner: false, isWritable: true },
+            { pubkey: userVlofiAta, isSigner: false, isWritable: true },
+            { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: TOKEN_2022_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data,
+    }));
+    return ixs;
+}
+/**
+ * Build a `settle_market` TransactionInstruction.
+ *
+ * Accounts (order must match SettleMarket struct in vault.rs):
+ *   0. user              (signer, writable)
+ *   1. protocol_state    (readonly)
+ *   2. market_vault      (writable)
+ *   3. user_market_position (writable)
+ *   4. vlofi_mint        (writable)
+ *   5. user_vlofi_ata    (writable)
+ *   6. vault_usdc_ata    (writable)
+ *   7. user_usdc_ata     (writable)
+ *   8. ccm_mint          (writable)
+ *   9. user_ccm_ata      (writable)
+ *  10. token_program     (readonly) — legacy SPL (USDC)
+ *  11. token_2022_program (readonly) — vLOFI burn
+ *  12. ccm_token_program (readonly) — CCM mint (Token-2022 on mainnet)
+ *
+ * @returns Array of instructions: idempotent ATA create for CCM + the settle IX.
+ */
+export async function createSettleMarketIx(connection, user, marketId, programId = PROGRAM_ID) {
+    const protocolState = getProtocolStatePDA(programId);
+    const marketVault = getMarketVaultPDA(protocolState, marketId, programId);
+    const userPosition = getUserPositionPDA(marketVault, user, programId);
+    // Fetch vault to discover mints
+    const vaultInfo = await connection.getAccountInfo(marketVault);
+    if (!vaultInfo)
+        throw new Error(`MarketVault not found for market ${marketId}`);
+    const vault = parseMarketVault(Buffer.from(vaultInfo.data));
+    // Fetch protocol state to discover CCM mint
+    const protocolInfo = await connection.getAccountInfo(protocolState);
+    if (!protocolInfo)
+        throw new Error('ProtocolState not found');
+    const protocol = parseProtocolState(Buffer.from(protocolInfo.data));
+    // Detect CCM mint's token program (Token-2022 on mainnet, legacy SPL on devnet)
+    const ccmMintInfo = await connection.getAccountInfo(protocol.mint);
+    if (!ccmMintInfo)
+        throw new Error('CCM mint account not found');
+    const ccmTokenProgram = ccmMintInfo.owner;
+    const userVlofiAta = getAta(user, vault.vlofiMint, TOKEN_PROGRAM_ID);
+    const userUsdcAta = getAta(user, vault.depositMint, TOKEN_PROGRAM_ID);
+    const userCcmAta = getAta(user, protocol.mint, ccmTokenProgram);
+    // Prepend idempotent ATA creation for CCM (no-op if exists)
+    const ixs = [
+        createAtaIdempotentIx(user, userCcmAta, user, protocol.mint, ccmTokenProgram),
+    ];
+    // Instruction data: [8 disc][8 market_id LE]
+    const disc = await anchorDisc('settle_market');
+    const data = Buffer.alloc(16);
+    disc.copy(data, 0);
+    data.writeBigUInt64LE(BigInt(marketId), 8);
+    ixs.push(new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: user, isSigner: true, isWritable: true },
+            { pubkey: protocolState, isSigner: false, isWritable: false },
+            { pubkey: marketVault, isSigner: false, isWritable: true },
+            { pubkey: userPosition, isSigner: false, isWritable: true },
+            { pubkey: vault.vlofiMint, isSigner: false, isWritable: true },
+            { pubkey: userVlofiAta, isSigner: false, isWritable: true },
+            { pubkey: vault.vaultAta, isSigner: false, isWritable: true },
+            { pubkey: userUsdcAta, isSigner: false, isWritable: true },
+            { pubkey: protocol.mint, isSigner: false, isWritable: true },
+            { pubkey: userCcmAta, isSigner: false, isWritable: true },
+            { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: TOKEN_2022_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: ccmTokenProgram, isSigner: false, isWritable: false },
+        ],
+        data,
+    }));
+    return ixs;
+}
+/**
+ * Build an `initialize_market_vault` TransactionInstruction.
+ *
+ * Accounts (order must match InitializeMarketVault struct in vault.rs):
+ *   0. admin            (signer, writable)
+ *   1. protocol_state   (readonly)
+ *   2. market_vault     (writable, init)
+ *   3. deposit_mint     (readonly) — USDC
+ *   4. vlofi_mint       (readonly) — Token-2022
+ *   5. vault_ata        (readonly) — Pre-created ATA owned by vault PDA
+ *   6. system_program   (readonly)
+ */
+export async function createInitializeMarketVaultIx(admin, marketId, depositMint, vlofiMint, programId = PROGRAM_ID) {
+    const protocolState = getProtocolStatePDA(programId);
+    const marketVault = getMarketVaultPDA(protocolState, marketId, programId);
+    // The vault's USDC ATA must be pre-created and owned by the vault PDA
+    const vaultAta = getAta(marketVault, depositMint, TOKEN_PROGRAM_ID);
+    // Instruction data: [8 disc][8 market_id LE]
+    const disc = await anchorDisc('initialize_market_vault');
+    const data = Buffer.alloc(16);
+    disc.copy(data, 0);
+    data.writeBigUInt64LE(BigInt(marketId), 8);
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: admin, isSigner: true, isWritable: true },
+            { pubkey: protocolState, isSigner: false, isWritable: false },
+            { pubkey: marketVault, isSigner: false, isWritable: true },
+            { pubkey: depositMint, isSigner: false, isWritable: false },
+            { pubkey: vlofiMint, isSigner: false, isWritable: false },
+            { pubkey: vaultAta, isSigner: false, isWritable: false },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data,
+    });
+}
+/**
+ * Build a `claim_global` TransactionInstruction.
+ *
+ * Accounts (must match ClaimGlobal struct in global.rs):
+ *   0. claimer             (signer, writable)
+ *   1. protocol_state      (writable)
+ *   2. global_root_config  (readonly)
+ *   3. claim_state         (writable, init_if_needed)
+ *   4. mint                (readonly) — CCM Token-2022 mint
+ *   5. treasury_ata        (writable)
+ *   6. claimer_ata         (writable, init_if_needed)
+ *   7. token_program       (readonly) — Token-2022
+ *   8. associated_token_program (readonly)
+ *   9. system_program      (readonly)
+ *
+ * @returns Array of instructions: idempotent ATA create for claimer CCM + the claim IX.
+ */
+export async function createClaimGlobalIx(connection, claimer, rootSeq, cumulativeTotal, 
+/** Hex-encoded 32-byte sibling hashes from the claims API */
+proofHex, programId = PROGRAM_ID) {
+    const protocolState = getProtocolStatePDA(programId);
+    // Fetch protocol state to discover CCM mint
+    const protocolInfo = await connection.getAccountInfo(protocolState);
+    if (!protocolInfo)
+        throw new Error('ProtocolState not found');
+    const protocol = parseProtocolState(Buffer.from(protocolInfo.data));
+    const ccmMint = protocol.mint;
+    // Derive PDAs
+    const globalRootConfig = getGlobalRootConfigPDA(ccmMint, programId);
+    const claimState = getClaimStatePDA(ccmMint, claimer, programId);
+    // ATAs — Token-2022 for CCM
+    const treasuryAta = getAta(protocolState, ccmMint, TOKEN_2022_PROGRAM_ID);
+    const claimerAta = getAta(claimer, ccmMint, TOKEN_2022_PROGRAM_ID);
+    // Prepend idempotent ATA creation for claimer's CCM account
+    const ixs = [
+        createAtaIdempotentIx(claimer, claimerAta, claimer, ccmMint, TOKEN_2022_PROGRAM_ID),
+    ];
+    // Decode hex proof to bytes
+    const proofBytes = proofHex.map((h) => Buffer.from(h, 'hex'));
+    // Instruction data: [8 disc][8 root_seq LE][8 cumulative_total LE][4 proof_len LE][N * 32 proof]
+    const disc = await anchorDisc('claim_global');
+    const dataLen = 8 + 8 + 8 + 4 + proofBytes.length * 32;
+    const data = Buffer.alloc(dataLen);
+    let offset = 0;
+    disc.copy(data, offset);
+    offset += 8;
+    data.writeBigUInt64LE(BigInt(rootSeq), offset);
+    offset += 8;
+    data.writeBigUInt64LE(BigInt(cumulativeTotal), offset);
+    offset += 8;
+    data.writeUInt32LE(proofBytes.length, offset);
+    offset += 4;
+    for (const node of proofBytes) {
+        node.copy(data, offset);
+        offset += 32;
+    }
+    ixs.push(new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: claimer, isSigner: true, isWritable: true },
+            { pubkey: protocolState, isSigner: false, isWritable: true },
+            { pubkey: globalRootConfig, isSigner: false, isWritable: false },
+            { pubkey: claimState, isSigner: false, isWritable: true },
+            { pubkey: ccmMint, isSigner: false, isWritable: false },
+            { pubkey: treasuryAta, isSigner: false, isWritable: true },
+            { pubkey: claimerAta, isSigner: false, isWritable: true },
+            { pubkey: TOKEN_2022_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: ASSOCIATED_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data,
+    }));
+    return ixs;
+}
+// ── Admin Instruction Builders ────────────────────────
+/**
+ * Build a `create_channel_config_v2` TransactionInstruction.
+ *
+ * Accounts (order must match CreateChannelConfigV2 struct in admin.rs):
+ *   0. admin            (signer, writable)
+ *   1. protocol_state   (readonly)
+ *   2. channel_config   (writable, init)
+ *   3. system_program   (readonly)
+ *
+ * Args (Borsh-serialized):
+ *   subject:         Pubkey (32 bytes)
+ *   authority:       Pubkey (32 bytes)
+ *   creator_wallet:  Pubkey (32 bytes)
+ *   creator_fee_bps: u16   (2 bytes LE)
+ */
+export async function createChannelConfigV2Ix(admin, 
+/** CCM mint pubkey (from ProtocolState.mint) */
+mint, subject, authority, creatorWallet, creatorFeeBps, programId = PROGRAM_ID) {
+    const protocolState = getProtocolStatePDA(programId);
+    const channelConfig = getChannelConfigV2PDA(mint, subject, programId);
+    // Instruction data: [8 disc][32 subject][32 authority][32 creator_wallet][2 fee_bps LE]
+    const disc = await anchorDisc('create_channel_config_v2');
+    const data = Buffer.alloc(8 + 32 + 32 + 32 + 2);
+    let offset = 0;
+    disc.copy(data, offset);
+    offset += 8;
+    subject.toBuffer().copy(data, offset);
+    offset += 32;
+    authority.toBuffer().copy(data, offset);
+    offset += 32;
+    creatorWallet.toBuffer().copy(data, offset);
+    offset += 32;
+    data.writeUInt16LE(creatorFeeBps, offset);
+    return new TransactionInstruction({
+        programId,
+        keys: [
+            { pubkey: admin, isSigner: true, isWritable: true },
+            { pubkey: protocolState, isSigner: false, isWritable: false },
+            { pubkey: channelConfig, isSigner: false, isWritable: true },
+            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        ],
+        data,
+    });
+}

package/dist/pda.d.ts

@@ -0,0 +1,20 @@
+/**
+ * PDA derivation helpers for the Liquid Attention Protocol.
+ *
+ * Seeds must match programs/attention-oracle/src/constants.rs.
+ */
+import { PublicKey } from '@solana/web3.js';
+/** Derive the singleton ProtocolState PDA. */
+export declare function getProtocolStatePDA(programId?: PublicKey): PublicKey;
+/** Derive a MarketVault PDA for a given market ID. */
+export declare function getMarketVaultPDA(protocolState: PublicKey, marketId: number, programId?: PublicKey): PublicKey;
+/** Derive a UserMarketPosition PDA. */
+export declare function getUserPositionPDA(marketVault: PublicKey, user: PublicKey, programId?: PublicKey): PublicKey;
+/** Derive the GlobalRootConfig PDA for a given CCM mint. */
+export declare function getGlobalRootConfigPDA(ccmMint: PublicKey, programId?: PublicKey): PublicKey;
+/** Derive the per-user ClaimStateGlobal PDA. */
+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 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

@@ -0,0 +1,37 @@
+/**
+ * PDA derivation helpers for the Liquid Attention Protocol.
+ *
+ * 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';
+/** Derive the singleton ProtocolState PDA. */
+export function getProtocolStatePDA(programId = PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(PROTOCOL_STATE_SEED)], programId)[0];
+}
+/** Derive a MarketVault PDA for a given market ID. */
+export function getMarketVaultPDA(protocolState, marketId, programId = PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(marketId));
+    return PublicKey.findProgramAddressSync([Buffer.from(MARKET_VAULT_SEED), protocolState.toBuffer(), idBuf], programId)[0];
+}
+/** Derive a UserMarketPosition PDA. */
+export function getUserPositionPDA(marketVault, user, programId = PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(MARKET_POSITION_SEED), marketVault.toBuffer(), user.toBuffer()], programId)[0];
+}
+/** Derive the GlobalRootConfig PDA for a given CCM mint. */
+export function getGlobalRootConfigPDA(ccmMint, programId = PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(GLOBAL_ROOT_SEED), ccmMint.toBuffer()], programId)[0];
+}
+/** Derive the per-user ClaimStateGlobal PDA. */
+export function getClaimStatePDA(ccmMint, claimer, programId = PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(CLAIM_STATE_GLOBAL_SEED), ccmMint.toBuffer(), claimer.toBuffer()], programId)[0];
+}
+/** Derive a ChannelConfigV2 PDA for a given mint and subject. */
+export function getChannelConfigV2PDA(mint, subject, programId = PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(CHANNEL_CONFIG_V2_SEED), mint.toBuffer(), subject.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/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@wzrd_sol/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the WZRD Liquid Attention Protocol — deposit, settle, claim on Solana",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "dev": "tsc --watch",
+    "example:deposit": "tsx examples/deposit.ts",
+    "example:claim": "tsx examples/claim.ts",
+    "typecheck:examples": "tsc -p tsconfig.examples.json"
+  },
+  "keywords": [
+    "solana",
+    "attention",
+    "defi",
+    "sdk",
+    "wzrd",
+    "vlofi",
+    "ccm",
+    "anchor"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/twzrd-sol/wzrd-final",
+    "directory": "sdk"
+  },
+  "homepage": "https://twzrd.xyz",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@solana/web3.js": "^1.90.0"
+  },
+  "devDependencies": {
+    "@solana/web3.js": "^1.95.0",
+    "typescript": "^5.5.0"
+  }
+}