@elmntl/jlpd-sdk 0.2.0 → 0.13.5

package/dist/jlpd-strategy/types.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AUM_HARD_BREAKER_BPS = exports.DEFAULT_SOFT_BREAKER_TOL_BPS = exports.MAX_BREAKER_BPS = void 0;
+exports.softBreakerTolBpsResolved = softBreakerTolBpsResolved;
+exports.aumHardBreakerBpsResolved = aumHardBreakerBpsResolved;
+/** Upper bound for either divergence-breaker band (100%). Only bounds an admin typo. */
+exports.MAX_BREAKER_BPS = 10000;
+/** Default soft-breaker band (1%), applied when the stored field reads `0` or `> MAX_BREAKER_BPS`. */
+exports.DEFAULT_SOFT_BREAKER_TOL_BPS = 100;
+/** Default hard-breaker band (3%), applied when the stored field reads `0` or `> MAX_BREAKER_BPS`. */
+exports.DEFAULT_AUM_HARD_BREAKER_BPS = 300;
+/**
+ * Resolved soft-breaker band: the stored value, or `DEFAULT_SOFT_BREAKER_TOL_BPS`
+ * when the stored value is `0` or exceeds `MAX_BREAKER_BPS` — mirrors
+ * `JlpdConfig::soft_breaker_tol_bps_resolved` exactly.
+ */
+function softBreakerTolBpsResolved(config) {
+    const v = config.softBreakerTolBps;
+    return v === 0 || v > exports.MAX_BREAKER_BPS ? exports.DEFAULT_SOFT_BREAKER_TOL_BPS : v;
+}
+/**
+ * Resolved hard-breaker band: the stored value, or `DEFAULT_AUM_HARD_BREAKER_BPS`
+ * when the stored value is `0` or exceeds `MAX_BREAKER_BPS` — mirrors
+ * `JlpdConfig::aum_hard_breaker_bps_resolved` exactly.
+ */
+function aumHardBreakerBpsResolved(config) {
+    const v = config.aumHardBreakerBps;
+    return v === 0 || v > exports.MAX_BREAKER_BPS ? exports.DEFAULT_AUM_HARD_BREAKER_BPS : v;
+}

package/dist/p-stv-core/accounts.d.ts

@@ -0,0 +1,152 @@
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import type { SolanaConnection } from "../common/connection";
+import { GlobalConfig, Stv, WithdrawRequest, DelayedDepositRequest, ManagerRole } from "./types";
+/**
+ * GlobalConfig — singleton protocol registry. Total 56 bytes.
+ *
+ * Layout (offsets include the 8-byte discriminator):
+ *   [  0..  8]  discriminator         (sha256("account:GlobalConfig")[..8])
+ *   [  8.. 40]  admin                  Pubkey
+ *   [ 40.. 48]  nextVaultId            u64
+ *   [ 48.. 50]  flags                  u16  (CFG_FLAG_*)
+ *   [ 50.. 51]  version                u8
+ *   [ 51.. 52]  bump                   u8
+ *   [ 52.. 56]  _padding               [u8; 4]
+ */
+export declare function deserializeGlobalConfig(data: Buffer): GlobalConfig;
+/**
+ * STV — per-vault state. Total 664 bytes (v2 layout).
+ *
+ * v2 layout (offsets include the 8-byte Anchor-compatible discriminator).
+ * All compile-time asserts in p-stv-core/programs/p-stv-core/src/state/stv.rs
+ * are the canonical source of truth; offsets here are copied from those asserts.
+ *
+ *   [  0..  8]  discriminator                (sha256("account:Stv")[..8])
+ *   [  8.. 40]  baseMint                      Pubkey   (_OFFSET_BASE_MINT == 8)
+ *   [ 40.. 72]  evMint                        Pubkey   (_OFFSET_EV_MINT == 40)
+ *   [ 72..104]  strategy                      Pubkey   (_OFFSET_STRATEGY == 72; immutable)
+ *   [104..136]  feeReceiver                   Pubkey   (_OFFSET_FEE_RECEIVER == 104)
+ *   [136..168]  lendProgram                   Pubkey   (_OFFSET_LEND_PROGRAM == 136; zero = inactive)
+ *   [168..200]  vaultAta                      Pubkey   (_OFFSET_VAULT_ATA == 168; canonical ATA)
+ *   [200..232]  coldAdmin                     Pubkey   (_OFFSET_COLD_ADMIN == 200; per-vault cold admin, never zero on v2)
+ *   [232..264]  pendingAdmin                  Pubkey   (_OFFSET_PENDING_ADMIN == 232; zero = no rotation in progress)
+ *   [264..296]  childVaults[4]                [u64; 4] (_OFFSET_CHILD_VAULTS == 264; MAX_CHILD_VAULTS = 4)
+ *   [296..304]  vaultId                       u64      (_OFFSET_VAULT_ID == 296)
+ *   [304..312]  reservedBase                  u64
+ *   [312..320]  requestedShares               u64      (shares pending in escrow)
+ *   [320..328]  vaultCapacity                 u64      (0 = uncapped)
+ *   [328..336]  minDeposit                    u64
+ *   [336..344]  hwm                           u64      (high-water mark for perf fees)
+ *   [344..352]  lastFeeTs                     u64
+ *   [352..360]  epochPps                      u64      (locked PPS for current epoch claims)
+ *   [360..368]  lastNav                       u64      (snapshot for rate-limit window)
+ *   [368..376]  dailyWithdrawnBase            u64      (rate-limit accumulator)
+ *   [376..380]  nextEpochTs                   u32
+ *   [380..384]  epochSec                      u32
+ *   [384..388]  currentEpochId                u32
+ *   [388..392]  pendingWithdrawals            u32
+ *   [392..396]  withdrawWindowStart           u32
+ *   [396..398]  mgmtFeeBps                    u16
+ *   [398..400]  perfFeeBps                    u16
+ *   [400..402]  flags                         u16
+ *   [402..404]  dailyWithdrawLimitBps         u16
+ *   [404..405]  childVaultCount               u8
+ *   [405..406]  version                       u8       (== 2 for v2 accounts)
+ *   [406..407]  bump                          u8
+ *   [407..408]  _padding                      [u8; 1]
+ *   [408..410]  depositFeeBps                 u16      (_OFFSET_DEPOSIT_FEE_BPS == 408)
+ *   [410..412]  withdrawalFeeBps              u16      (_OFFSET_WITHDRAWAL_FEE_BPS == 410)
+ *   [412..416]  pendingDepositCount           u32      (_OFFSET_PENDING_DEPOSIT_COUNT == 412)
+ *   [416..424]  pendingDepositBase            u64      (_OFFSET_PENDING_DEPOSIT_BASE == 416)
+ *   [424..456]  feeReceiverEvAta              Pubkey   (_OFFSET_FEE_RECEIVER_EV_ATA == 424)
+ *   [456..464]  lockedSeedShares              u64      (_OFFSET_LOCKED_SEED_SHARES == 456)
+ *   [464..465]  withdrawalMode                u8       (_OFFSET_WITHDRAWAL_MODE == 464; 0=instant, 1=X, 2=X+1)
+ *   [465..468]  _reservedPad                  [u8; 3]  (_OFFSET_RESERVED_PAD == 465; alignment before last_nav_ts)
+ *   [468..472]  lastNavTs                     u32      (_OFFSET_LAST_NAV_TS == 468; unix seconds; 0 = no epoch yet)
+ *   [472..476]  strategyStalenessThreshold    u32      (_OFFSET_STRATEGY_STALENESS_THRESHOLD == 472; 0 = use default 24 h)
+ *   [476..508]  warmAdmin                     Pubkey   (_OFFSET_WARM_ADMIN == 476; [0u8;32] = "follow cold" sentinel — resolve via warmAdminEffective())
+ *   [508..664]  _reserved                     [u8; 156] (_OFFSET_RESERVED == 508)
+ */
+export declare function deserializeStv(data: Buffer): Stv;
+/**
+ * Resolve the effective warm admin for an STV: the stored `warmAdmin`
+ * "follow cold" sentinel (`PublicKey.default`, i.e. `[0u8;32]`) resolves to
+ * `stv.coldAdmin` (cold). Mirrors the on-chain `Stv::warm_admin_effective()`
+ * helper (state/stv.rs) — every warm-gated on-chain auth check
+ * (`add_manager`, `remove_manager`, `override_claim_withdraw`,
+ * `trip_circuit_breaker`) routes through that same resolution, so this is
+ * the correct way to read `warmAdmin` off-chain too; never compare
+ * `stv.warmAdmin` directly against a candidate signer.
+ *
+ * PRE-DEPLOY CAVEAT: every STV on the currently-deployed mainnet program
+ * reads the sentinel (the field lives in a zeroed pre-upgrade reserved
+ * tail), so this always resolves to `stv.coldAdmin` until the program
+ * upgrade ships — which is the correct, safe answer either way (cold's
+ * power set is a superset of warm's).
+ */
+export declare function warmAdminEffective(stv: Stv): PublicKey;
+/**
+ * WithdrawRequest — per-(STV, user, epoch) withdraw escrow. Total 168 bytes.
+ *
+ * Layout (offsets include the 8-byte discriminator):
+ *   [  0..  8]  discriminator           (sha256("account:WithdrawRequest")[..8])
+ *   [  8.. 40]  stv                      Pubkey
+ *   [ 40.. 72]  user                     Pubkey
+ *   [ 72.. 80]  shares                   u64
+ *   [ 80.. 88]  pps                      u64   (locked at process_epoch time)
+ *   [ 88.. 92]  epochId                  u32
+ *   [ 92.. 96]  claimAvailableAfter      u32   (unix seconds)
+ *   [ 96.. 97]  bump                     u8
+ *   [ 97.. 98]  version                  u8
+ *   [ 98.. 99]  requestFlags             u8   (bit0 WR_FLAG_MIGRATE: 0=withdraw, 1=migrate)
+ *   [ 99..104]  _padding                 [u8; 5]
+ *   [104..112]  destVaultId              u64  (migrate: dest STV vault_id; withdraw: 0)
+ *   [112..120]  minDestShares            u64  (migrate: slippage floor; withdraw: 0)
+ *   [120..168]  _reserved0               [u8; 48]
+ */
+export declare function deserializeWithdrawRequest(data: Buffer): WithdrawRequest;
+/**
+ * WithdrawRequest kind from `requestFlags` bit 0.
+ * Returns `"migrate"` when WR_FLAG_MIGRATE (0x01) is set, else `"withdraw"`.
+ */
+export declare function withdrawRequestKind(wr: WithdrawRequest): "withdraw" | "migrate";
+/**
+ * DelayedDepositRequest — per-(STV, user, epoch) pending deposit. Total 152 bytes.
+ *
+ * Layout (offsets include the 8-byte discriminator):
+ *   [  0..  8]  discriminator           (sha256("account:DelayedDepositRequest")[..8])
+ *   [  8.. 40]  stv                      Pubkey
+ *   [ 40.. 72]  user                     Pubkey
+ *   [ 72.. 80]  amount                   u64
+ *   [ 80.. 84]  epochId                  u32   (offset_of == 80, asserted on-chain)
+ *   [ 84.. 85]  bump                     u8
+ *   [ 85.. 86]  version                  u8
+ *   [ 86.. 88]  _padding                 [u8; 2]
+ *   [ 88..152]  _reserved                [u8; 64]
+ */
+export declare function deserializeDelayedDepositRequest(data: Buffer): DelayedDepositRequest;
+/**
+ * ManagerRole — per-(STV, manager) authorization record. Total 80 bytes.
+ *
+ * Layout (offsets include the 8-byte discriminator):
+ *   [  0..  8]  discriminator       (sha256("account:ManagerRole")[..8] —
+ *                                     shared with elemental-lend + jlpd-strategy)
+ *   [  8.. 40]  stv                  Pubkey
+ *   [ 40.. 72]  manager              Pubkey
+ *   [ 72.. 73]  bump                 u8
+ *   [ 73.. 80]  _padding             [u8; 7]
+ */
+export declare function deserializeManagerRole(data: Buffer): ManagerRole;
+export declare function fetchGlobalConfig(connection: SolanaConnection, programId?: PublicKey): Promise<GlobalConfig>;
+export declare function fetchStv(connection: SolanaConnection, vaultId: number | BN, programId?: PublicKey): Promise<Stv>;
+export declare function fetchStvByAddress(connection: SolanaConnection, address: PublicKey): Promise<Stv>;
+export declare function fetchWithdrawRequest(connection: SolanaConnection, stv: PublicKey, user: PublicKey, epochId: number, programId?: PublicKey): Promise<WithdrawRequest>;
+export declare function fetchWithdrawRequestByAddress(connection: SolanaConnection, address: PublicKey): Promise<WithdrawRequest>;
+export declare function fetchDelayedDepositRequest(connection: SolanaConnection, stv: PublicKey, user: PublicKey, epochId: number, programId?: PublicKey): Promise<DelayedDepositRequest>;
+export declare function fetchDelayedDepositRequestByAddress(connection: SolanaConnection, address: PublicKey): Promise<DelayedDepositRequest>;
+export declare function fetchAllStvs(connection: SolanaConnection, programId?: PublicKey): Promise<[PublicKey, Stv][]>;
+export declare function fetchPendingWithdrawRequests(connection: SolanaConnection, stv: PublicKey, epochId: number, programId?: PublicKey): Promise<[PublicKey, WithdrawRequest][]>;
+export declare function fetchPendingDelayedDepositRequests(connection: SolanaConnection, stv: PublicKey, epochId: number, programId?: PublicKey): Promise<[PublicKey, DelayedDepositRequest][]>;
+export declare function fetchManagerRole(connection: SolanaConnection, stv: PublicKey, manager: PublicKey, programId?: PublicKey): Promise<ManagerRole | null>;
+export declare function fetchManagersForStv(connection: SolanaConnection, stv: PublicKey, programId?: PublicKey): Promise<[PublicKey, ManagerRole][]>;

package/dist/p-stv-core/accounts.js

@@ -0,0 +1,407 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deserializeGlobalConfig = deserializeGlobalConfig;
+exports.deserializeStv = deserializeStv;
+exports.warmAdminEffective = warmAdminEffective;
+exports.deserializeWithdrawRequest = deserializeWithdrawRequest;
+exports.withdrawRequestKind = withdrawRequestKind;
+exports.deserializeDelayedDepositRequest = deserializeDelayedDepositRequest;
+exports.deserializeManagerRole = deserializeManagerRole;
+exports.fetchGlobalConfig = fetchGlobalConfig;
+exports.fetchStv = fetchStv;
+exports.fetchStvByAddress = fetchStvByAddress;
+exports.fetchWithdrawRequest = fetchWithdrawRequest;
+exports.fetchWithdrawRequestByAddress = fetchWithdrawRequestByAddress;
+exports.fetchDelayedDepositRequest = fetchDelayedDepositRequest;
+exports.fetchDelayedDepositRequestByAddress = fetchDelayedDepositRequestByAddress;
+exports.fetchAllStvs = fetchAllStvs;
+exports.fetchPendingWithdrawRequests = fetchPendingWithdrawRequests;
+exports.fetchPendingDelayedDepositRequests = fetchPendingDelayedDepositRequests;
+exports.fetchManagerRole = fetchManagerRole;
+exports.fetchManagersForStv = fetchManagersForStv;
+const web3_js_1 = require("@solana/web3.js");
+const buffer_1 = require("../common/buffer");
+const constants_1 = require("./constants");
+const pda_1 = require("./pda");
+// ---------------------------------------------------------------------------
+// Deserialization
+//
+// All offsets below INCLUDE the 8-byte Anchor account discriminator. Layout
+// blocks above each parser show the field map; the helpers in
+// `common/buffer.ts` validate that `offset + width <= data.length` so a
+// drift between this file and the on-chain layout fails loudly with a
+// `RangeError` rather than returning garbage.
+// ---------------------------------------------------------------------------
+/**
+ * GlobalConfig — singleton protocol registry. Total 56 bytes.
+ *
+ * Layout (offsets include the 8-byte discriminator):
+ *   [  0..  8]  discriminator         (sha256("account:GlobalConfig")[..8])
+ *   [  8.. 40]  admin                  Pubkey
+ *   [ 40.. 48]  nextVaultId            u64
+ *   [ 48.. 50]  flags                  u16  (CFG_FLAG_*)
+ *   [ 50.. 51]  version                u8
+ *   [ 51.. 52]  bump                   u8
+ *   [ 52.. 56]  _padding               [u8; 4]
+ */
+function deserializeGlobalConfig(data) {
+    if (data.length < constants_1.GLOBAL_CONFIG_SIZE) {
+        throw new Error(`GlobalConfig data too short: ${data.length} < ${constants_1.GLOBAL_CONFIG_SIZE}`);
+    }
+    const disc = data.subarray(0, 8);
+    if (!disc.equals(constants_1.DISC_GLOBAL_CONFIG)) {
+        throw new Error(`Invalid GlobalConfig discriminator`);
+    }
+    return {
+        admin: (0, buffer_1.readPubkey)(data, 8),
+        nextVaultId: (0, buffer_1.readU64)(data, 40),
+        flags: (0, buffer_1.readU16)(data, 48),
+        version: (0, buffer_1.readU8)(data, 50),
+        bump: (0, buffer_1.readU8)(data, 51),
+    };
+}
+/**
+ * STV — per-vault state. Total 664 bytes (v2 layout).
+ *
+ * v2 layout (offsets include the 8-byte Anchor-compatible discriminator).
+ * All compile-time asserts in p-stv-core/programs/p-stv-core/src/state/stv.rs
+ * are the canonical source of truth; offsets here are copied from those asserts.
+ *
+ *   [  0..  8]  discriminator                (sha256("account:Stv")[..8])
+ *   [  8.. 40]  baseMint                      Pubkey   (_OFFSET_BASE_MINT == 8)
+ *   [ 40.. 72]  evMint                        Pubkey   (_OFFSET_EV_MINT == 40)
+ *   [ 72..104]  strategy                      Pubkey   (_OFFSET_STRATEGY == 72; immutable)
+ *   [104..136]  feeReceiver                   Pubkey   (_OFFSET_FEE_RECEIVER == 104)
+ *   [136..168]  lendProgram                   Pubkey   (_OFFSET_LEND_PROGRAM == 136; zero = inactive)
+ *   [168..200]  vaultAta                      Pubkey   (_OFFSET_VAULT_ATA == 168; canonical ATA)
+ *   [200..232]  coldAdmin                     Pubkey   (_OFFSET_COLD_ADMIN == 200; per-vault cold admin, never zero on v2)
+ *   [232..264]  pendingAdmin                  Pubkey   (_OFFSET_PENDING_ADMIN == 232; zero = no rotation in progress)
+ *   [264..296]  childVaults[4]                [u64; 4] (_OFFSET_CHILD_VAULTS == 264; MAX_CHILD_VAULTS = 4)
+ *   [296..304]  vaultId                       u64      (_OFFSET_VAULT_ID == 296)
+ *   [304..312]  reservedBase                  u64
+ *   [312..320]  requestedShares               u64      (shares pending in escrow)
+ *   [320..328]  vaultCapacity                 u64      (0 = uncapped)
+ *   [328..336]  minDeposit                    u64
+ *   [336..344]  hwm                           u64      (high-water mark for perf fees)
+ *   [344..352]  lastFeeTs                     u64
+ *   [352..360]  epochPps                      u64      (locked PPS for current epoch claims)
+ *   [360..368]  lastNav                       u64      (snapshot for rate-limit window)
+ *   [368..376]  dailyWithdrawnBase            u64      (rate-limit accumulator)
+ *   [376..380]  nextEpochTs                   u32
+ *   [380..384]  epochSec                      u32
+ *   [384..388]  currentEpochId                u32
+ *   [388..392]  pendingWithdrawals            u32
+ *   [392..396]  withdrawWindowStart           u32
+ *   [396..398]  mgmtFeeBps                    u16
+ *   [398..400]  perfFeeBps                    u16
+ *   [400..402]  flags                         u16
+ *   [402..404]  dailyWithdrawLimitBps         u16
+ *   [404..405]  childVaultCount               u8
+ *   [405..406]  version                       u8       (== 2 for v2 accounts)
+ *   [406..407]  bump                          u8
+ *   [407..408]  _padding                      [u8; 1]
+ *   [408..410]  depositFeeBps                 u16      (_OFFSET_DEPOSIT_FEE_BPS == 408)
+ *   [410..412]  withdrawalFeeBps              u16      (_OFFSET_WITHDRAWAL_FEE_BPS == 410)
+ *   [412..416]  pendingDepositCount           u32      (_OFFSET_PENDING_DEPOSIT_COUNT == 412)
+ *   [416..424]  pendingDepositBase            u64      (_OFFSET_PENDING_DEPOSIT_BASE == 416)
+ *   [424..456]  feeReceiverEvAta              Pubkey   (_OFFSET_FEE_RECEIVER_EV_ATA == 424)
+ *   [456..464]  lockedSeedShares              u64      (_OFFSET_LOCKED_SEED_SHARES == 456)
+ *   [464..465]  withdrawalMode                u8       (_OFFSET_WITHDRAWAL_MODE == 464; 0=instant, 1=X, 2=X+1)
+ *   [465..468]  _reservedPad                  [u8; 3]  (_OFFSET_RESERVED_PAD == 465; alignment before last_nav_ts)
+ *   [468..472]  lastNavTs                     u32      (_OFFSET_LAST_NAV_TS == 468; unix seconds; 0 = no epoch yet)
+ *   [472..476]  strategyStalenessThreshold    u32      (_OFFSET_STRATEGY_STALENESS_THRESHOLD == 472; 0 = use default 24 h)
+ *   [476..508]  warmAdmin                     Pubkey   (_OFFSET_WARM_ADMIN == 476; [0u8;32] = "follow cold" sentinel — resolve via warmAdminEffective())
+ *   [508..664]  _reserved                     [u8; 156] (_OFFSET_RESERVED == 508)
+ */
+function deserializeStv(data) {
+    if (data.length < constants_1.STV_SIZE) {
+        throw new Error(`Stv data too short: ${data.length} < ${constants_1.STV_SIZE}`);
+    }
+    const disc = data.subarray(0, 8);
+    if (!disc.equals(constants_1.DISC_STV)) {
+        throw new Error(`Invalid Stv discriminator`);
+    }
+    // v2 gate: version must be 2 (stv.rs Stv::from_account — discriminator +
+    // version==2 is the complete loader gate; cold_admin!=0 is enforced at write
+    // time by init_or_update_stv and is NOT re-checked by the on-chain loader).
+    const version = (0, buffer_1.readU8)(data, 405);
+    if (version !== 2) {
+        throw new Error(`Stv account is not v2: version=${version}`);
+    }
+    // childVaults: [u64; 4] at offset 264, MAX_CHILD_VAULTS = 4
+    const childVaults = [];
+    for (let i = 0; i < constants_1.MAX_STRATEGIES; i++) {
+        childVaults.push((0, buffer_1.readU64)(data, 264 + i * 8));
+    }
+    return {
+        baseMint: (0, buffer_1.readPubkey)(data, 8),
+        evMint: (0, buffer_1.readPubkey)(data, 40),
+        strategy: (0, buffer_1.readPubkey)(data, 72),
+        feeReceiver: (0, buffer_1.readPubkey)(data, 104),
+        lendProgram: (0, buffer_1.readPubkey)(data, 136),
+        vaultAta: (0, buffer_1.readPubkey)(data, 168),
+        coldAdmin: (0, buffer_1.readPubkey)(data, 200),
+        pendingAdmin: (0, buffer_1.readPubkey)(data, 232),
+        childVaults,
+        vaultId: (0, buffer_1.readU64)(data, 296),
+        reservedBase: (0, buffer_1.readU64)(data, 304),
+        requestedShares: (0, buffer_1.readU64)(data, 312),
+        vaultCapacity: (0, buffer_1.readU64)(data, 320),
+        minDeposit: (0, buffer_1.readU64)(data, 328),
+        hwm: (0, buffer_1.readU64)(data, 336),
+        lastFeeTs: (0, buffer_1.readU64)(data, 344),
+        epochPps: (0, buffer_1.readU64)(data, 352),
+        lastNav: (0, buffer_1.readU64)(data, 360),
+        dailyWithdrawnBase: (0, buffer_1.readU64)(data, 368),
+        nextEpochTs: (0, buffer_1.readU32)(data, 376),
+        epochSec: (0, buffer_1.readU32)(data, 380),
+        currentEpochId: (0, buffer_1.readU32)(data, 384),
+        pendingWithdrawals: (0, buffer_1.readU32)(data, 388),
+        withdrawWindowStart: (0, buffer_1.readU32)(data, 392),
+        mgmtFeeBps: (0, buffer_1.readU16)(data, 396),
+        perfFeeBps: (0, buffer_1.readU16)(data, 398),
+        flags: (0, buffer_1.readU16)(data, 400),
+        dailyWithdrawLimitBps: (0, buffer_1.readU16)(data, 402),
+        childVaultCount: (0, buffer_1.readU8)(data, 404),
+        version,
+        bump: (0, buffer_1.readU8)(data, 406),
+        depositFeeBps: (0, buffer_1.readU16)(data, 408),
+        withdrawalFeeBps: (0, buffer_1.readU16)(data, 410),
+        pendingDepositCount: (0, buffer_1.readU32)(data, 412),
+        pendingDepositBase: (0, buffer_1.readU64)(data, 416),
+        feeReceiverEvAta: (0, buffer_1.readPubkey)(data, 424),
+        lockedSeedShares: (0, buffer_1.readU64)(data, 456),
+        withdrawalMode: (0, buffer_1.readU8)(data, 464),
+        lastNavTs: (0, buffer_1.readU32)(data, 468),
+        strategyStalenessThreshold: (0, buffer_1.readU32)(data, 472),
+        warmAdmin: (0, buffer_1.readPubkey)(data, 476),
+    };
+}
+/**
+ * Resolve the effective warm admin for an STV: the stored `warmAdmin`
+ * "follow cold" sentinel (`PublicKey.default`, i.e. `[0u8;32]`) resolves to
+ * `stv.coldAdmin` (cold). Mirrors the on-chain `Stv::warm_admin_effective()`
+ * helper (state/stv.rs) — every warm-gated on-chain auth check
+ * (`add_manager`, `remove_manager`, `override_claim_withdraw`,
+ * `trip_circuit_breaker`) routes through that same resolution, so this is
+ * the correct way to read `warmAdmin` off-chain too; never compare
+ * `stv.warmAdmin` directly against a candidate signer.
+ *
+ * PRE-DEPLOY CAVEAT: every STV on the currently-deployed mainnet program
+ * reads the sentinel (the field lives in a zeroed pre-upgrade reserved
+ * tail), so this always resolves to `stv.coldAdmin` until the program
+ * upgrade ships — which is the correct, safe answer either way (cold's
+ * power set is a superset of warm's).
+ */
+function warmAdminEffective(stv) {
+    return stv.warmAdmin.equals(web3_js_1.PublicKey.default) ? stv.coldAdmin : stv.warmAdmin;
+}
+/**
+ * WithdrawRequest — per-(STV, user, epoch) withdraw escrow. Total 168 bytes.
+ *
+ * Layout (offsets include the 8-byte discriminator):
+ *   [  0..  8]  discriminator           (sha256("account:WithdrawRequest")[..8])
+ *   [  8.. 40]  stv                      Pubkey
+ *   [ 40.. 72]  user                     Pubkey
+ *   [ 72.. 80]  shares                   u64
+ *   [ 80.. 88]  pps                      u64   (locked at process_epoch time)
+ *   [ 88.. 92]  epochId                  u32
+ *   [ 92.. 96]  claimAvailableAfter      u32   (unix seconds)
+ *   [ 96.. 97]  bump                     u8
+ *   [ 97.. 98]  version                  u8
+ *   [ 98.. 99]  requestFlags             u8   (bit0 WR_FLAG_MIGRATE: 0=withdraw, 1=migrate)
+ *   [ 99..104]  _padding                 [u8; 5]
+ *   [104..112]  destVaultId              u64  (migrate: dest STV vault_id; withdraw: 0)
+ *   [112..120]  minDestShares            u64  (migrate: slippage floor; withdraw: 0)
+ *   [120..168]  _reserved0               [u8; 48]
+ */
+function deserializeWithdrawRequest(data) {
+    if (data.length < constants_1.WITHDRAW_REQUEST_SIZE) {
+        throw new Error(`WithdrawRequest data too short: ${data.length} < ${constants_1.WITHDRAW_REQUEST_SIZE}`);
+    }
+    const disc = data.subarray(0, 8);
+    if (!disc.equals(constants_1.DISC_WITHDRAW_REQUEST)) {
+        throw new Error(`Invalid WithdrawRequest discriminator`);
+    }
+    return {
+        stv: (0, buffer_1.readPubkey)(data, 8),
+        user: (0, buffer_1.readPubkey)(data, 40),
+        shares: (0, buffer_1.readU64)(data, 72),
+        pps: (0, buffer_1.readU64)(data, 80),
+        epochId: (0, buffer_1.readU32)(data, 88),
+        claimAvailableAfter: (0, buffer_1.readU32)(data, 92),
+        bump: (0, buffer_1.readU8)(data, 96),
+        // version is at offset 97 (_OFFSET_VERSION in withdraw_request.rs:68)
+        version: (0, buffer_1.readU8)(data, 97),
+        requestFlags: (0, buffer_1.readU8)(data, 98),
+        destVaultId: (0, buffer_1.readU64)(data, 104),
+        minDestShares: (0, buffer_1.readU64)(data, 112),
+    };
+}
+/**
+ * WithdrawRequest kind from `requestFlags` bit 0.
+ * Returns `"migrate"` when WR_FLAG_MIGRATE (0x01) is set, else `"withdraw"`.
+ */
+function withdrawRequestKind(wr) {
+    return (wr.requestFlags & 0x01) !== 0 ? "migrate" : "withdraw";
+}
+/**
+ * DelayedDepositRequest — per-(STV, user, epoch) pending deposit. Total 152 bytes.
+ *
+ * Layout (offsets include the 8-byte discriminator):
+ *   [  0..  8]  discriminator           (sha256("account:DelayedDepositRequest")[..8])
+ *   [  8.. 40]  stv                      Pubkey
+ *   [ 40.. 72]  user                     Pubkey
+ *   [ 72.. 80]  amount                   u64
+ *   [ 80.. 84]  epochId                  u32   (offset_of == 80, asserted on-chain)
+ *   [ 84.. 85]  bump                     u8
+ *   [ 85.. 86]  version                  u8
+ *   [ 86.. 88]  _padding                 [u8; 2]
+ *   [ 88..152]  _reserved                [u8; 64]
+ */
+function deserializeDelayedDepositRequest(data) {
+    if (data.length < constants_1.DELAYED_DEPOSIT_REQUEST_SIZE) {
+        throw new Error(`DelayedDepositRequest data too short: ${data.length} < ${constants_1.DELAYED_DEPOSIT_REQUEST_SIZE}`);
+    }
+    const disc = data.subarray(0, 8);
+    if (!disc.equals(constants_1.DISC_DELAYED_DEPOSIT_REQUEST)) {
+        throw new Error(`Invalid DelayedDepositRequest discriminator`);
+    }
+    return {
+        stv: (0, buffer_1.readPubkey)(data, 8),
+        user: (0, buffer_1.readPubkey)(data, 40),
+        amount: (0, buffer_1.readU64)(data, 72),
+        epochId: (0, buffer_1.readU32)(data, 80),
+        bump: (0, buffer_1.readU8)(data, 84),
+        version: (0, buffer_1.readU8)(data, 85),
+    };
+}
+/**
+ * ManagerRole — per-(STV, manager) authorization record. Total 80 bytes.
+ *
+ * Layout (offsets include the 8-byte discriminator):
+ *   [  0..  8]  discriminator       (sha256("account:ManagerRole")[..8] —
+ *                                     shared with elemental-lend + jlpd-strategy)
+ *   [  8.. 40]  stv                  Pubkey
+ *   [ 40.. 72]  manager              Pubkey
+ *   [ 72.. 73]  bump                 u8
+ *   [ 73.. 80]  _padding             [u8; 7]
+ */
+function deserializeManagerRole(data) {
+    if (data.length < constants_1.MANAGER_ROLE_SIZE) {
+        throw new Error(`ManagerRole data too short: ${data.length} < ${constants_1.MANAGER_ROLE_SIZE}`);
+    }
+    const disc = data.subarray(0, 8);
+    if (!disc.equals(constants_1.DISC_MANAGER_ROLE)) {
+        throw new Error(`Invalid ManagerRole discriminator`);
+    }
+    return {
+        stv: (0, buffer_1.readPubkey)(data, 8),
+        manager: (0, buffer_1.readPubkey)(data, 40),
+        bump: (0, buffer_1.readU8)(data, 72),
+    };
+}
+// ---------------------------------------------------------------------------
+// Fetch Helpers
+// ---------------------------------------------------------------------------
+async function fetchGlobalConfig(connection, programId = constants_1.PROGRAM_ID) {
+    const [configPda] = (0, pda_1.findConfigPda)(programId);
+    const info = await connection.getAccountInfo(configPda);
+    if (!info)
+        throw new Error("GlobalConfig account not found");
+    return deserializeGlobalConfig(info.data);
+}
+async function fetchStv(connection, vaultId, programId = constants_1.PROGRAM_ID) {
+    const [stvPda] = (0, pda_1.findStvPda)(vaultId, programId);
+    const info = await connection.getAccountInfo(stvPda);
+    if (!info)
+        throw new Error(`Stv account not found for vault_id ${vaultId}`);
+    return deserializeStv(info.data);
+}
+async function fetchStvByAddress(connection, address) {
+    const info = await connection.getAccountInfo(address);
+    if (!info)
+        throw new Error(`Stv account not found at ${address.toBase58()}`);
+    return deserializeStv(info.data);
+}
+async function fetchWithdrawRequest(connection, stv, user, epochId, programId = constants_1.PROGRAM_ID) {
+    const [wrPda] = (0, pda_1.findWithdrawRequestPda)(stv, user, epochId, programId);
+    const info = await connection.getAccountInfo(wrPda);
+    if (!info)
+        throw new Error("WithdrawRequest account not found");
+    return deserializeWithdrawRequest(info.data);
+}
+async function fetchWithdrawRequestByAddress(connection, address) {
+    const info = await connection.getAccountInfo(address);
+    if (!info)
+        throw new Error(`WithdrawRequest not found at ${address.toBase58()}`);
+    return deserializeWithdrawRequest(info.data);
+}
+async function fetchDelayedDepositRequest(connection, stv, user, epochId, programId = constants_1.PROGRAM_ID) {
+    const [pda] = (0, pda_1.findDelayedDepositRequestPda)(stv, user, epochId, programId);
+    const info = await connection.getAccountInfo(pda);
+    if (!info)
+        throw new Error("DelayedDepositRequest account not found");
+    return deserializeDelayedDepositRequest(info.data);
+}
+async function fetchDelayedDepositRequestByAddress(connection, address) {
+    const info = await connection.getAccountInfo(address);
+    if (!info)
+        throw new Error(`DelayedDepositRequest not found at ${address.toBase58()}`);
+    return deserializeDelayedDepositRequest(info.data);
+}
+// ---------------------------------------------------------------------------
+// GPA Helpers
+// ---------------------------------------------------------------------------
+async function fetchAllStvs(connection, programId = constants_1.PROGRAM_ID) {
+    const accounts = await connection.getProgramAccounts(programId, {
+        filters: [
+            { dataSize: constants_1.STV_SIZE },
+            { memcmp: { offset: 0, bytes: constants_1.DISC_STV.toString("base64"), encoding: "base64" } },
+        ],
+    });
+    return accounts.map((a) => [a.pubkey, deserializeStv(a.account.data)]);
+}
+async function fetchPendingWithdrawRequests(connection, stv, epochId, programId = constants_1.PROGRAM_ID) {
+    const epochBuf = Buffer.alloc(4);
+    epochBuf.writeUInt32LE(epochId, 0);
+    const accounts = await connection.getProgramAccounts(programId, {
+        filters: [
+            { dataSize: constants_1.WITHDRAW_REQUEST_SIZE },
+            { memcmp: { offset: 0, bytes: constants_1.DISC_WITHDRAW_REQUEST.toString("base64"), encoding: "base64" } },
+            { memcmp: { offset: 8, bytes: stv.toBuffer().toString("base64"), encoding: "base64" } },
+            { memcmp: { offset: 88, bytes: epochBuf.toString("base64"), encoding: "base64" } },
+        ],
+    });
+    return accounts.map((a) => [a.pubkey, deserializeWithdrawRequest(a.account.data)]);
+}
+async function fetchPendingDelayedDepositRequests(connection, stv, epochId, programId = constants_1.PROGRAM_ID) {
+    const epochBuf = Buffer.alloc(4);
+    epochBuf.writeUInt32LE(epochId, 0);
+    const accounts = await connection.getProgramAccounts(programId, {
+        filters: [
+            { dataSize: constants_1.DELAYED_DEPOSIT_REQUEST_SIZE },
+            { memcmp: { offset: 0, bytes: constants_1.DISC_DELAYED_DEPOSIT_REQUEST.toString("base64"), encoding: "base64" } },
+            { memcmp: { offset: 8, bytes: stv.toBuffer().toString("base64"), encoding: "base64" } },
+            { memcmp: { offset: 80, bytes: epochBuf.toString("base64"), encoding: "base64" } },
+        ],
+    });
+    return accounts.map((a) => [a.pubkey, deserializeDelayedDepositRequest(a.account.data)]);
+}
+async function fetchManagerRole(connection, stv, manager, programId = constants_1.PROGRAM_ID) {
+    const [pda] = (0, pda_1.findStvManagerRolePda)(stv, manager, programId);
+    const info = await connection.getAccountInfo(pda);
+    if (!info)
+        return null;
+    return deserializeManagerRole(info.data);
+}
+async function fetchManagersForStv(connection, stv, programId = constants_1.PROGRAM_ID) {
+    const accounts = await connection.getProgramAccounts(programId, {
+        filters: [
+            { dataSize: constants_1.MANAGER_ROLE_SIZE },
+            { memcmp: { offset: 0, bytes: constants_1.DISC_MANAGER_ROLE.toString("base64"), encoding: "base64" } },
+            { memcmp: { offset: 8, bytes: stv.toBuffer().toString("base64"), encoding: "base64" } },
+        ],
+    });
+    return accounts.map((a) => [a.pubkey, deserializeManagerRole(a.account.data)]);
+}