@temporalabs/treasury 0.1.1 → 0.1.3

package/dist/solana/layout.js

@@ -0,0 +1,209 @@
+/**
+ * Decoders for the two accounts this client reads on Solana: the kVault `VaultState` and the lending
+ * program's `Reserve`.
+ *
+ * 🔴 HAND-DECLARED OFFSETS, PINNED TO KAMINO'S OWN SDK. `tests/solana-kvault.unit.test.ts` decodes a real
+ * mainnet snapshot (`tests/fixtures/solana/vault-snapshot.json`) and compares every field with what
+ * Kamino's SDK decoded from the same bytes (`vendor/kamino/decode-fixtures.json`, version in
+ * `vendor/kamino/PINNED`). The discriminator and the exact account length are checked on every decode, so a
+ * different account type, or a resized one, is refused rather than read as garbage. Kamino's SDK is not a
+ * dependency at runtime.
+ *
+ * Amounts are bigint base units. `*Sf` fields are the lending program's scaled fractions: value × 2^60.
+ */
+import { getAddressDecoder } from "@solana/kit";
+import { DEFAULT_PUBKEY, MAX_RESERVES, RESERVE_SIZE, VAULT_STATE_SIZE } from "./constants.js";
+/** klend's fixed-point scale: a `*_sf` field is value × 2^60. */
+export const SF_ONE = 1n << 60n;
+/** `sha256("account:VaultState")[0..8]` — Anchor's account discriminator. */
+export const VAULT_STATE_DISCRIMINATOR = Uint8Array.from([228, 196, 82, 165, 98, 210, 235, 152]);
+/** `sha256("account:Reserve")[0..8]`. */
+export const RESERVE_DISCRIMINATOR = Uint8Array.from([43, 242, 204, 202, 26, 247, 59, 127]);
+/** Byte offsets INTO THE ACCOUNT DATA (the 8-byte discriminator included). */
+export const VAULT_STATE_OFFSETS = {
+    vaultAdminAuthority: 8,
+    baseVaultAuthority: 40,
+    tokenMint: 80,
+    tokenMintDecimals: 112,
+    tokenVault: 120,
+    tokenProgram: 152,
+    sharesMint: 184,
+    sharesMintDecimals: 216,
+    tokenAvailable: 224,
+    sharesIssued: 232,
+    unallocatedWeight: 248,
+    performanceFeeBps: 256,
+    managementFeeBps: 264,
+    pendingFeesSf: 296,
+    allocations: 312,
+    minInvestAmount: 58_424,
+    minInvestDelaySlots: 58_432,
+    pendingAdmin: 58_448,
+    name: 58_528,
+    unallocatedTokensCap: 58_640,
+    allocationAdmin: 58_648,
+    allowAllocationsInWhitelistedReservesOnly: 58_728,
+    allowInvestInWhitelistedReservesOnly: 58_729,
+    depositCap: 58_736,
+    permissioningAuthority: 58_840,
+};
+/** One `VaultAllocation` slot: its size, and each field's offset WITHIN the slot. */
+export const ALLOCATION_SLOT = {
+    size: 2_160,
+    reserve: 0,
+    ctokenVault: 32,
+    targetAllocationWeight: 64,
+    tokenAllocationCap: 72,
+    ctokenAllocationCap: 88,
+    ctokenAllocation: 1_104,
+    lastInvestSlot: 1_112,
+};
+export const RESERVE_OFFSETS = {
+    lastUpdateSlot: 16,
+    lendingMarket: 32,
+    liquidityMint: 128,
+    liquiditySupplyVault: 160,
+    totalAvailableAmount: 224,
+    borrowedAmountSf: 232,
+    liquidityMintDecimals: 272,
+    accumulatedProtocolFeesSf: 344,
+    accumulatedReferrerFeesSf: 360,
+    pendingReferrerFeesSf: 376,
+    collateralMint: 2_560,
+    collateralMintTotalSupply: 2_592,
+    depositLimit: 5_016,
+};
+const addressDecoder = getAddressDecoder();
+function view(data) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength);
+}
+const u64 = (d, o) => view(d).getBigUint64(o, true);
+const u128 = (d, o) => u64(d, o) | (u64(d, o + 8) << 64n);
+const pubkey = (d, o) => addressDecoder.decode(d.subarray(o, o + 32));
+/** Refuse anything that is not exactly the account this decoder was written for. */
+function assertAccount(data, size, disc, what) {
+    if (data.length !== size) {
+        throw new Error(`kamino: ${what} is ${data.length} bytes, expected ${size} (a different program version or account type)`);
+    }
+    for (let i = 0; i < 8; i++) {
+        if (data[i] !== disc[i])
+            throw new Error(`kamino: ${what} discriminator mismatch — not a ${what} account`);
+    }
+}
+export function decodeVaultState(data) {
+    assertAccount(data, VAULT_STATE_SIZE, VAULT_STATE_DISCRIMINATOR, "VaultState");
+    const o = VAULT_STATE_OFFSETS;
+    const allocations = [];
+    for (let i = 0; i < MAX_RESERVES; i++) {
+        const base = o.allocations + i * ALLOCATION_SLOT.size;
+        const reserve = pubkey(data, base + ALLOCATION_SLOT.reserve);
+        if (reserve === DEFAULT_PUBKEY)
+            continue;
+        allocations.push({
+            reserve,
+            ctokenVault: pubkey(data, base + ALLOCATION_SLOT.ctokenVault),
+            targetAllocationWeight: u64(data, base + ALLOCATION_SLOT.targetAllocationWeight),
+            tokenAllocationCap: u64(data, base + ALLOCATION_SLOT.tokenAllocationCap),
+            ctokenAllocationCap: u64(data, base + ALLOCATION_SLOT.ctokenAllocationCap),
+            ctokenAllocation: u64(data, base + ALLOCATION_SLOT.ctokenAllocation),
+            lastInvestSlot: u64(data, base + ALLOCATION_SLOT.lastInvestSlot),
+        });
+    }
+    const nameBytes = data.subarray(o.name, o.name + 40);
+    const nul = nameBytes.indexOf(0);
+    return {
+        vaultAdminAuthority: pubkey(data, o.vaultAdminAuthority),
+        baseVaultAuthority: pubkey(data, o.baseVaultAuthority),
+        tokenMint: pubkey(data, o.tokenMint),
+        tokenMintDecimals: u64(data, o.tokenMintDecimals),
+        tokenVault: pubkey(data, o.tokenVault),
+        tokenProgram: pubkey(data, o.tokenProgram),
+        sharesMint: pubkey(data, o.sharesMint),
+        sharesMintDecimals: u64(data, o.sharesMintDecimals),
+        tokenAvailable: u64(data, o.tokenAvailable),
+        sharesIssued: u64(data, o.sharesIssued),
+        unallocatedWeight: u64(data, o.unallocatedWeight),
+        performanceFeeBps: u64(data, o.performanceFeeBps),
+        managementFeeBps: u64(data, o.managementFeeBps),
+        pendingFeesSf: u128(data, o.pendingFeesSf),
+        allocations,
+        minInvestAmount: u64(data, o.minInvestAmount),
+        minInvestDelaySlots: u64(data, o.minInvestDelaySlots),
+        pendingAdmin: pubkey(data, o.pendingAdmin),
+        name: new TextDecoder().decode(nul === -1 ? nameBytes : nameBytes.subarray(0, nul)),
+        unallocatedTokensCap: u64(data, o.unallocatedTokensCap),
+        allocationAdmin: pubkey(data, o.allocationAdmin),
+        allowAllocationsInWhitelistedReservesOnly: data[o.allowAllocationsInWhitelistedReservesOnly],
+        allowInvestInWhitelistedReservesOnly: data[o.allowInvestInWhitelistedReservesOnly],
+        depositCap: u64(data, o.depositCap),
+        permissioningAuthority: pubkey(data, o.permissioningAuthority),
+    };
+}
+export function decodeReserve(data) {
+    assertAccount(data, RESERVE_SIZE, RESERVE_DISCRIMINATOR, "Reserve");
+    const o = RESERVE_OFFSETS;
+    return {
+        lastUpdateSlot: u64(data, o.lastUpdateSlot),
+        lendingMarket: pubkey(data, o.lendingMarket),
+        liquidityMint: pubkey(data, o.liquidityMint),
+        liquiditySupplyVault: pubkey(data, o.liquiditySupplyVault),
+        totalAvailableAmount: u64(data, o.totalAvailableAmount),
+        borrowedAmountSf: u128(data, o.borrowedAmountSf),
+        liquidityMintDecimals: u64(data, o.liquidityMintDecimals),
+        accumulatedProtocolFeesSf: u128(data, o.accumulatedProtocolFeesSf),
+        accumulatedReferrerFeesSf: u128(data, o.accumulatedReferrerFeesSf),
+        pendingReferrerFeesSf: u128(data, o.pendingReferrerFeesSf),
+        collateralMint: pubkey(data, o.collateralMint),
+        collateralMintTotalSupply: u64(data, o.collateralMintTotalSupply),
+        depositLimit: u64(data, o.depositLimit),
+    };
+}
+/**
+ * A reserve's total supply in liquidity units, scaled by 2^60: available + borrowed − every fee bucket.
+ * klend-sdk's `Reserve.getTotalSupplySf()`, the numerator of the collateral exchange rate.
+ */
+export function totalSupplySf(r) {
+    return (r.totalAvailableAmount * SF_ONE +
+        r.borrowedAmountSf -
+        r.accumulatedProtocolFeesSf -
+        r.accumulatedReferrerFeesSf -
+        r.pendingReferrerFeesSf);
+}
+/**
+ * What `ctokens` of this reserve are worth in liquidity base units, at the reserve's STORED state
+ * (floored): ctokens × totalSupply / ctokenSupply. A reserve accrues interest only when refreshed, so this
+ * lags the true value by the interest since `lastUpdateSlot` — conservative, and what klend-sdk's
+ * `getCollateralExchangeRate()` (the "stale" rate) also reports.
+ */
+export function ctokensToLiquidity(ctokens, r) {
+    if (r.collateralMintTotalSupply === 0n)
+        return 0n;
+    return (ctokens * totalSupplySf(r)) / (r.collateralMintTotalSupply * SF_ONE);
+}
+/**
+ * A reserve's share price — liquidity per ctoken — as an 18-decimal fixed-point bigint. `0n` for a reserve
+ * with no ctokens.
+ */
+export function reserveSharePrice1e18(r) {
+    if (r.collateralMintTotalSupply === 0n)
+        return 0n;
+    return (totalSupplySf(r) * 10n ** 18n) / (r.collateralMintTotalSupply * SF_ONE);
+}
+export function vaultHoldings(vault, reserves) {
+    const byReserve = new Map();
+    let invested = 0n;
+    for (const a of vault.allocations) {
+        const r = reserves.get(a.reserve);
+        if (r === undefined) {
+            // A missing reserve would silently drop its share of the AUM: refuse instead.
+            throw new Error(`kamino: the vault allocates to reserve ${a.reserve}, which was not read`);
+        }
+        const v = ctokensToLiquidity(a.ctokenAllocation, r);
+        byReserve.set(a.reserve, v);
+        invested += v;
+    }
+    const aumIncludingFees = vault.tokenAvailable + invested;
+    const pendingFees = vault.pendingFeesSf / SF_ONE;
+    return { idle: vault.tokenAvailable, byReserve, aumIncludingFees, pendingFees, netAum: aumIncludingFees - pendingFees };
+}
+//# sourceMappingURL=layout.js.map

package/dist/solana/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/solana/layout.ts"],"names":[],"mappings":"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"}

package/dist/solana/rpc.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The Solana RPC: one client per command run, on the endpoint `solanaRpcUrlFromEnv` resolves, and the cluster
+ * check that is the counterpart of an EVM endpoint's chain id.
+ */
+import { type Rpc, type RpcTransport, type SolanaRpcApi } from "@solana/kit";
+export type SolanaRpc = Rpc<SolanaRpcApi>;
+/**
+ * A transport that waits out HTTP 429 instead of failing the command. Solana's public endpoint rate-limits
+ * after a handful of requests (measured 2026-10-11: a burst of about twenty reads answered 429), and one
+ * command makes several. Up to five retries, backing off from half a second, never past the limit above.
+ */
+/**
+ * The wait between retries. The timer keeps the process alive: while a command waits out a 429 nothing else
+ * may be pending, and an unref'd timer let Node end mid-retry — exit 0 with no output at all.
+ */
+export declare const retrySleep: (ms: number) => Promise<void>;
+export declare function withRateLimitRetry(base: RpcTransport, sleep?: (ms: number) => Promise<void>): RpcTransport;
+export declare function makeSolanaRpc(url: string): SolanaRpc;
+/**
+ * Which cluster an endpoint serves, by its genesis hash: `"mainnet"`, `"other"` (devnet, testnet, a local
+ * validator — any of them answers every read, and none of them holds the registry's vault), or `undefined`
+ * when it did not say within `ms`.
+ */
+export declare function solanaCluster(rpc: SolanaRpc, ms?: number): Promise<"mainnet" | "other" | undefined>;

package/dist/solana/rpc.js

@@ -0,0 +1,66 @@
+/**
+ * The Solana RPC: one client per command run, on the endpoint `solanaRpcUrlFromEnv` resolves, and the cluster
+ * check that is the counterpart of an EVM endpoint's chain id.
+ */
+import { createDefaultRpcTransport, createSolanaRpcFromTransport, isSolanaError, SOLANA_ERROR__RPC__TRANSPORT_HTTP_ERROR } from "@solana/kit";
+import { MAINNET_GENESIS_HASH } from "./constants.js";
+/** The longest a single request waits out HTTP 429 before the 429 is reported (the EVM client's limit too). */
+const RATE_LIMIT_WAIT_MS = 15_000;
+/**
+ * A transport that waits out HTTP 429 instead of failing the command. Solana's public endpoint rate-limits
+ * after a handful of requests (measured 2026-10-11: a burst of about twenty reads answered 429), and one
+ * command makes several. Up to five retries, backing off from half a second, never past the limit above.
+ */
+/**
+ * The wait between retries. The timer keeps the process alive: while a command waits out a 429 nothing else
+ * may be pending, and an unref'd timer let Node end mid-retry — exit 0 with no output at all.
+ */
+export const retrySleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function withRateLimitRetry(base, sleep = retrySleep) {
+    return (async (req) => {
+        let waited = 0;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await base(req);
+            }
+            catch (e) {
+                const is429 = isSolanaError(e, SOLANA_ERROR__RPC__TRANSPORT_HTTP_ERROR) && e.context.statusCode === 429;
+                if (!is429 || attempt >= 5 || waited >= RATE_LIMIT_WAIT_MS)
+                    throw e;
+                const ms = Math.min(500 * 2 ** attempt, RATE_LIMIT_WAIT_MS - waited);
+                waited += ms;
+                await sleep(ms);
+            }
+        }
+    });
+}
+export function makeSolanaRpc(url) {
+    return createSolanaRpcFromTransport(withRateLimitRetry(createDefaultRpcTransport({ url: url })));
+}
+/**
+ * Which cluster an endpoint serves, by its genesis hash: `"mainnet"`, `"other"` (devnet, testnet, a local
+ * validator — any of them answers every read, and none of them holds the registry's vault), or `undefined`
+ * when it did not say within `ms`.
+ */
+export async function solanaCluster(rpc, ms = 3000) {
+    let timer;
+    try {
+        const hash = await Promise.race([
+            rpc.getGenesisHash().send(),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(undefined), ms);
+            }),
+        ]);
+        if (hash === undefined)
+            return undefined;
+        return hash === MAINNET_GENESIS_HASH ? "mainnet" : "other";
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=rpc.js.map

package/dist/solana/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/solana/rpc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,aAAa,EAAE,uCAAuC,EAAkD,MAAM,aAAa,CAAC;AAC9L,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAItD,+GAA+G;AAC/G,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC;;;;GAIG;AACH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAE/F,MAAM,UAAU,kBAAkB,CAAC,IAAkB,EAAE,QAAuC,UAAU;IACtG,OAAO,CAAC,KAAK,EAAE,GAAgC,EAAE,EAAE;QACjD,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,EAAE,uCAAuC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,KAAK,GAAG,CAAC;gBACxG,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,IAAI,MAAM,IAAI,kBAAkB;oBAAE,MAAM,CAAC,CAAC;gBACpE,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC,CAAC;gBACrE,MAAM,IAAI,EAAE,CAAC;gBACb,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC,CAAiB,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,4BAA4B,CAAC,kBAAkB,CAAC,yBAAyB,CAAC,EAAE,GAAG,EAAE,GAAY,EAAE,CAAC,CAAC,CAAc,CAAC;AACzH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAc,EAAE,EAAE,GAAG,IAAI;IAC3D,IAAI,KAAiC,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAC9B,GAAG,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE;YAC3B,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,EAAE;gBACjC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;YACnD,CAAC,CAAC;SACH,CAAC,CAAC;QACH,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,OAAO,IAAI,KAAK,oBAAoB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/solana/vault.d.ts

@@ -0,0 +1,153 @@
+/**
+ * A Kamino vault on Solana, read and simulated: what the earn commands report for `chain: "solana"`.
+ *
+ * Every verdict here comes from the chain. Amounts out of a quote, a pre-flight or a position's exit are
+ * read from a SIMULATED transaction's post-state — the token balance the user's account would hold after
+ * it — never computed from a rule this client restates. That matters on this program in particular:
+ * measured on mainnet on 2026-10-11, each `withdraw` INSTRUCTION keeps up to 0.001 USDC in the vault (one
+ * instruction: 10,000 base units paid 9,000, 2,000,000 kept 1,000; the same 2,000,000 as two instructions
+ * kept 1,929; a two-leg full exit kept 1,000), and one worth 0.001 USDC or less is refused (error 7049). The
+ * cause is the vault program's GLOBAL withdrawal penalty — its global config account
+ * (BKyTcUe6daNG8HbgBix2ugdRHbykG2dK9hPBBqhUyoEX) holds `withdrawalPenaltyLamports` = 1000 and
+ * `withdrawalPenaltyBps` = 0 — while this vault's own penalty settings read 0. Kamino can change the global
+ * value, and how it combines across legs is not a rule this client restates: a simulated quote is exact.
+ */
+import { type Instruction } from "@solana/kit";
+import type { SolanaVaultEntry } from "../registry-schema.js";
+import { type ReserveView, type VaultHoldings, type VaultStateView } from "./layout.js";
+import { compileUnsigned, type Lifetime, type VaultAccounts } from "./kvault.js";
+import type { SolanaRpc } from "./rpc.js";
+/** The vault and every reserve it allocates to, read at (about) one slot. */
+export interface VaultRead {
+    readonly entry: SolanaVaultEntry;
+    readonly state: VaultStateView;
+    readonly reserves: ReadonlyMap<string, ReserveView>;
+    readonly holdings: VaultHoldings;
+    readonly accounts: VaultAccounts;
+    readonly slot: bigint;
+}
+/**
+ * Reads the vault state and its reserves, and refuses a row the chain disagrees with: the registry's asset,
+ * share mint and decimals are claims, and the vault state is the authority over them.
+ */
+export declare function readVault(rpc: SolanaRpc, entry: SolanaVaultEntry): Promise<VaultRead>;
+/** What one share is worth in the asset, as a decimal string at the asset's precision (stored reserve state). */
+export declare function sharePrice(v: VaultRead): string;
+/** An SPL token account's balance, or 0 when the account does not exist. */
+export declare function tokenBalance(rpc: SolanaRpc, account: string): Promise<{
+    exists: boolean;
+    amount: bigint;
+}>;
+/**
+ * Compute-unit limits. Measured by simulation on mainnet, 2026-10-11, with two funded reserves: a deposit
+ * used about 115,000 units; a withdrawal about 144,000 paid from idle, 186,000 when it disinvests from one
+ * reserve, and 346,000 for a two-leg exit. The limits (400,000 per leg) leave room and cost nothing unless a
+ * priority fee is set.
+ */
+export declare const DEPOSIT_COMPUTE_UNITS = 400000;
+export declare const WITHDRAW_COMPUTE_UNITS_PER_RESERVE = 400000;
+/**
+ * Refuses while the vault requires a co-signer. Kamino's program lets a "permissioning authority" be set on a
+ * vault, after which it must co-sign every deposit AND every withdrawal; this client builds single-signer
+ * transactions only, so it cannot move money in or out while one is set. Unset today; checked on every build.
+ */
+export declare function assertNoCoSigner(v: VaultRead): void;
+/** The deposit: create the user's share account if it is missing, then deposit `amount` base units. */
+export declare function depositInstructions(v: VaultRead, user: string, amount: bigint): Promise<Instruction[]>;
+/**
+ * The withdrawal of `shares`: the account's USDC account if it is missing, then one `withdraw` per reserve
+ * it needs. Each pays from the vault's idle balance
+ * first and then from its named reserve, so the shares are split across reserves in order of what each can
+ * release now (the vault's position in it, capped by the reserve's own available liquidity). A vault with no
+ * reserves cannot be withdrawn from by this program's instruction, and is refused.
+ *
+ * ⚠️ The program CAPS a leg that asks for more than it can pay rather than reverting it (measured: a leg
+ * oversized by 500,000 shares succeeded, paid the leg's maximum and left the excess shares with the user).
+ * So every build path simulates the withdrawal and refuses it unless every share burns, less rounding
+ * (`simulateWithdrawal`, `partialWithdrawal`). A reserve's state can still move between that simulation and the send, and then the
+ * transaction lands paying less, with no error; `verifySolanaLanded` reports that as a partial withdrawal.
+ */
+export declare function withdrawInstructions(v: VaultRead, user: string, shares: bigint): Promise<Instruction[]>;
+export interface Simulated {
+    readonly ok: boolean;
+    /** The program's error, as the RPC reports it; `null` on success. */
+    readonly err: unknown;
+    readonly logs: readonly string[];
+    readonly unitsConsumed: bigint | null;
+    readonly slot: bigint;
+    /** Each watched token account's balance AFTER the transaction, or `null` if it would not exist. */
+    readonly after: ReadonlyMap<string, bigint | null>;
+}
+/**
+ * Simulates an unsigned transaction against the RPC's current state. `sigVerify: false` lets the signer slot
+ * be any address (nothing is signed); `replaceRecentBlockhash` makes the blockhash irrelevant. READ-ONLY:
+ * nothing lands, nothing is paid.
+ */
+export declare function simulate(rpc: SolanaRpc, ixs: readonly Instruction[], feePayer: string, watch: readonly string[]): Promise<Simulated>;
+/**
+ * Simulates a withdrawal and reads, from the account's own token accounts, what it would pay and how many shares
+ * it would burn. The program caps a leg it cannot pay in full rather than failing it (see `withdrawInstructions`),
+ * so `burned` short of the shares asked for means the transaction would land as a partial withdrawal. Both are
+ * `undefined` when the simulation fails or the account's USDC account would not exist. `legs` is the number of
+ * withdraw instructions.
+ */
+export declare function simulateWithdrawal(rpc: SolanaRpc, v: VaultRead, user: string, ixs: readonly Instruction[]): Promise<{
+    sim: Simulated;
+    received?: bigint;
+    burned?: bigint;
+    legs: number;
+}>;
+/** A kVault withdraw instruction: the program's address and the instruction's discriminator. */
+export declare function isWithdrawInstruction(programAddress: string, data: ArrayLike<number> | undefined): boolean;
+/**
+ * Why a simulated withdrawal that burns fewer shares than asked for is refused, or `undefined` when it burns them
+ * all. Up to one share unit per withdraw instruction is rounding, not a capped leg: the program floors what a
+ * leg pays and then ceils the shares that payment burns, which comes out one unit short when a share is worth
+ * less than one base unit of the asset. A capped leg falls short by the part its reserve could not pay.
+ */
+export declare function partialWithdrawal(asked: bigint, burned: bigint, legs: number, shareDecimals: number, slot: bigint): string | undefined;
+/** One line for a failed simulation: the program's error and the last log lines that say why. */
+export declare function describeSimulation(s: Simulated): string;
+export type SolanaPreflightStatus = "OPEN_READY" | "NEEDS_FUNDS" | "REVERTED_OTHER" | "UNRESOLVED";
+/** What `earn status --account` and `earn quote --direction deposit` report on Solana. */
+export declare function preflightDepositSolana(rpc: SolanaRpc, entry: SolanaVaultEntry, account: string, amountHuman: string | undefined): Promise<{
+    vault: string;
+    depositor: string;
+    status: SolanaPreflightStatus;
+    canDeposit: boolean;
+    findings: string[];
+} | {
+    status: SolanaPreflightStatus;
+    canDeposit: boolean;
+    expectedSharesRaw: bigint;
+    findings: string[];
+    vault: string;
+    depositor: string;
+    balances: {
+        asset: string;
+        shares: string;
+    };
+    quotes: {
+        sharePriceInAssets: string;
+    };
+    measuredAtSlot: number;
+} | {
+    status: SolanaPreflightStatus;
+    canDeposit: boolean;
+    findings: string[];
+    vault: string;
+    depositor: string;
+    balances: {
+        asset: string;
+        shares: string;
+    };
+    quotes: {
+        sharePriceInAssets: string;
+    };
+    measuredAtSlot: number;
+}>;
+/** A fresh blockhash: what an unsigned transaction is bound to, and the block height it expires after. */
+export declare function freshLifetime(rpc: SolanaRpc): Promise<Lifetime & {
+    currentBlockHeight: bigint;
+}>;
+export { compileUnsigned };