@ember-finance/sdk 2.39.0 → 2.42.0

package/dist/src/solana-vaults/on-chain-calls/vault-reader.js

@@ -1,6 +1,6 @@
 import { PublicKey } from "@solana/web3.js";
-import { decodeMint, decodeProtocolConfig, decodeVault, decodeVaultAccount, decodeWithdrawalQueue, decodeWithdrawalRequestAccount } from "../utils/borsh.js";
-import { accountDiscriminator, associatedTokenAddress, deriveVaultAccount } from "../utils/pdas.js";
+import { decodeDepositParkingLot, decodeDepositRequest, decodeMint, decodeProtocolConfig, decodeVault, decodeVaultAccount, decodeWithdrawalQueue, decodeWithdrawalRequestAccount } from "../utils/borsh.js";
+import { DEPOSIT_REQUEST_OFFSETS, DEPOSIT_REQUEST_SIZE, MAX_MULTIPLE_ACCOUNTS, MAX_QUEUE_SCAN, accountDiscriminator, associatedTokenAddress, deriveDepositRequest, deriveDepositUser, deriveParkingLot, deriveParkingLotEscrow, deriveVaultAccount, deriveWithdrawalUser } from "../utils/pdas.js";
 import { amountFromShares, amountFromSharesFloor, maxDepositAmount, maxMintShares, sharesFromAmount, sharesFromAmountCeil, vaultTvl, withdrawalFee } from "../utils/math.js";
 /**
  * Reads vault state from the chain.
@@ -29,6 +29,22 @@ export class SolanaVaultReader {
     key(value) {
         return typeof value === "string" ? new PublicKey(value) : value;
     }
+    /**
+     * Whether an account is on one of the unbounded allow lists.
+     *
+     * The program's own test is `UserListEntry::exists`: owned by the program
+     * AND non-empty. A bare "the account exists" is weaker and wrong here -
+     * these addresses are public and derivable, so anyone can make
+     * `getAccountInfo` return non-null for one by sending it lamports. That
+     * system-owned, dataless account would read as listed and then be rejected
+     * on chain, which is a confusing false positive on a path users hit
+     * directly.
+     */
+    async isListed(derive, shareMint, account) {
+        const entry = derive(this.programId, this.getVaultPdas(shareMint).vault, this.key(account));
+        const info = await this.connection.getAccountInfo(entry);
+        return info !== null && info.owner.equals(this.programId) && info.data.length > 0;
+    }
     // --- raw state ---
     /** The protocol config, or null when the protocol is not initialised. */
     async getProtocolConfig() {
@@ -238,32 +254,35 @@ export class SolanaVaultReader {
         return sharesFromAmountCeil(assets, (await this.getVaultState(shareMint)).rate.value);
     }
     async maxDeposit(shareMint, owner) {
-        const [vault, config, supply] = await Promise.all([
+        const [vault, config, supply, listed] = await Promise.all([
             this.getVaultState(shareMint),
             this.getProtocolConfig(),
-            this.getTotalSupply(shareMint)
+            this.getTotalSupply(shareMint),
+            this.isListed(deriveDepositUser, shareMint, owner)
         ]);
-        if (!this.canDeposit(vault, config, this.key(owner)))
+        if (!this.canDeposit(vault, config, this.key(owner), listed))
             return 0n;
         return maxDepositAmount(supply, vault.rate.value, vault.maxTvl);
     }
     async maxMint(shareMint, owner) {
-        const [vault, config, supply] = await Promise.all([
+        const [vault, config, supply, listed] = await Promise.all([
             this.getVaultState(shareMint),
             this.getProtocolConfig(),
-            this.getTotalSupply(shareMint)
+            this.getTotalSupply(shareMint),
+            this.isListed(deriveDepositUser, shareMint, owner)
         ]);
-        if (!this.canDeposit(vault, config, this.key(owner)))
+        if (!this.canDeposit(vault, config, this.key(owner), listed))
             return 0n;
         return maxMintShares(supply, vault.rate.value, vault.maxTvl);
     }
     async maxRedeem(shareMint, owner) {
-        const [vault, config, balance] = await Promise.all([
+        const [vault, config, balance, listed] = await Promise.all([
             this.getVaultState(shareMint),
             this.getProtocolConfig(),
-            this.balanceOf(shareMint, owner)
+            this.balanceOf(shareMint, owner),
+            this.isListed(deriveWithdrawalUser, shareMint, owner)
         ]);
-        if (!this.canWithdraw(vault, config, this.key(owner)))
+        if (!this.canWithdraw(vault, config, this.key(owner), listed))
             return 0n;
         // Below the minimum the whole balance is unredeemable, not merely capped.
         return balance < vault.minWithdrawalShares ? 0n : balance;
@@ -282,7 +301,7 @@ export class SolanaVaultReader {
             : amountFromSharesFloor(redeemable, vault.rate.value);
     }
     /** `quote.rs::can_deposit`. */
-    canDeposit(vault, config, owner) {
+    canDeposit(vault, config, owner, listed) {
         if (config?.pauseNonAdminOperations)
             return false;
         if (vault.paused || vault.pausedDeposits)
@@ -293,22 +312,164 @@ export class SolanaVaultReader {
             return false;
         // A bound parking lot closes the direct path to everyone not listed;
         // with no lot, an empty list is open to all.
-        if (!vault.parkingLot.equals(PublicKey.default)) {
-            return vault.depositUserList.some(a => a.equals(owner));
-        }
-        return (vault.depositUserList.length === 0 ||
-            vault.depositUserList.some(a => a.equals(owner)));
+        if (!vault.parkingLot.equals(PublicKey.default))
+            return listed;
+        return vault.depositUserCount === 0n || listed;
     }
     /** `quote.rs::can_withdraw`. */
-    canWithdraw(vault, config, owner) {
+    canWithdraw(vault, config, owner, listed) {
         if (config?.pauseNonAdminOperations)
             return false;
         if (vault.paused || vault.pausedWithdrawals)
             return false;
         if (vault.blacklisted.some(a => a.equals(owner)))
             return false;
-        return (vault.withdrawalUserList.length === 0 ||
-            vault.withdrawalUserList.some(a => a.equals(owner)));
+        return vault.withdrawalUserCount === 0n || listed;
+    }
+    // --- parking lot ---
+    /** The lot's address for a vault, whether or not one exists. */
+    parkingLotAddress(shareMint) {
+        return deriveParkingLot(this.programId, this.getVaultPdas(shareMint).vault);
+    }
+    /**
+     * A vault's parking lot, or null when it has none.
+     *
+     * Null is the ordinary case: a lot is opt-in per vault, so most vaults have
+     * no account at this address at all.
+     */
+    async getParkingLot(shareMint) {
+        const address = this.parkingLotAddress(shareMint);
+        const account = await this.connection.getAccountInfo(address);
+        return account === null ? null : decodeDepositParkingLot(account.data, address);
+    }
+    /** The lot's escrow token account. */
+    parkingLotEscrowAddress(shareMint) {
+        return deriveParkingLotEscrow(this.programId, this.parkingLotAddress(shareMint));
+    }
+    /** One parked deposit by its sequence number, or null if it is gone. */
+    async getDepositRequest(shareMint, sequenceNumber) {
+        const address = deriveDepositRequest(this.programId, this.parkingLotAddress(shareMint), sequenceNumber);
+        const account = await this.connection.getAccountInfo(address);
+        return account === null ? null : decodeDepositRequest(account.data, address);
+    }
+    /**
+     * A page of the lot's queue, oldest first, with an explicit cursor.
+     *
+     * `limit` counts SLOTS SCANNED, not requests returned, because a slot may
+     * be empty: a cancelled request's account is closed while its number stays
+     * in the range. `scannedTo` is therefore returned separately and is always
+     * advanced — a page of zero requests still tells the caller where to
+     * resume, which an empty array alone could not.
+     *
+     * Reads are batched at `MAX_MULTIPLE_ACCOUNTS`: `getMultipleAccounts`
+     * refuses more than 100 pubkeys per call, so a larger window is split
+     * rather than failing.
+     *
+     * This window is `(queueStartIndex, sequenceNumber]` — the UNSETTLED part
+     * of the queue. Requests whose refund is waiting to be claimed sit BELOW
+     * the head and are not here; use `getRequestsByDepositor` for those.
+     */
+    async getPendingDeposits(shareMint, options) {
+        const lot = await this.getParkingLot(shareMint);
+        if (lot === null) {
+            return { requests: [], scannedTo: 0n, hasMore: false };
+        }
+        // NaN survives trunc/max/min, and `slots.length < NaN` is false, so the
+        // scan loop would never run and `slots[-1].seq` would throw below.
+        const rawLimit = options?.limit;
+        const limit = Number.isFinite(rawLimit)
+            ? Math.min(Math.max(Math.trunc(rawLimit), 1), MAX_QUEUE_SCAN)
+            : MAX_MULTIPLE_ACCOUNTS;
+        // Clamp up to the head. Below it only CLAIMABLE requests survive (the
+        // program settles the rest and the head only moves forward), so an
+        // `after` behind the head would walk settled slots and report their
+        // requests as pending. Clamping also keeps the cursor monotonic: an
+        // `after` past the tail resumes at itself rather than being dragged
+        // back to `sequenceNumber`.
+        const after = options?.after ?? lot.queueStartIndex;
+        const resume = after > lot.queueStartIndex ? after : lot.queueStartIndex;
+        const from = resume + 1n;
+        if (from > lot.sequenceNumber) {
+            return { requests: [], scannedTo: resume, hasMore: false };
+        }
+        const slots = [];
+        for (let seq = from; seq <= lot.sequenceNumber && slots.length < limit; seq++) {
+            slots.push({
+                seq,
+                address: deriveDepositRequest(this.programId, lot.address, seq)
+            });
+        }
+        const requests = [];
+        for (let i = 0; i < slots.length; i += MAX_MULTIPLE_ACCOUNTS) {
+            const batch = slots.slice(i, i + MAX_MULTIPLE_ACCOUNTS);
+            const accounts = await this.connection.getMultipleAccountsInfo(batch.map(b => b.address));
+            accounts.forEach((account, j) => {
+                if (account === null)
+                    return; // cancelled or settled: slot closed
+                requests.push(decodeDepositRequest(account.data, batch[j].address));
+            });
+        }
+        const scannedTo = slots[slots.length - 1].seq;
+        return { requests, scannedTo, hasMore: scannedTo < lot.sequenceNumber };
+    }
+    /**
+     * Every surviving request belonging to one depositor, wherever it sits in
+     * the queue.
+     *
+     * Position-independent on purpose. A CLAIMABLE request — one that settled
+     * but whose refund could not be delivered — lives BELOW `queueStartIndex`
+     * (see parking_lot.rs: "below the head only claimable requests remain"),
+     * so no scan of the pending window can ever find one. Walking downwards
+     * instead is unbounded and mostly hits closed accounts.
+     *
+     * So this filters on chain by the account's own bytes: the request's size,
+     * its parking lot at offset 9 and its depositor at offset 57. Those
+     * offsets track `DepositRequest` in state.rs and are pinned by test.
+     *
+     * `getProgramAccounts` is an indexed scan and some public RPCs restrict
+     * it; a provider endpoint is the right place to run this.
+     */
+    async getRequestsByDepositor(shareMint, depositor) {
+        const lot = await this.getParkingLot(shareMint);
+        if (lot === null)
+            return [];
+        const accounts = await this.connection.getProgramAccounts(this.programId, {
+            filters: [
+                { dataSize: DEPOSIT_REQUEST_SIZE },
+                {
+                    memcmp: {
+                        offset: DEPOSIT_REQUEST_OFFSETS.parkingLot,
+                        bytes: lot.address.toBase58()
+                    }
+                },
+                {
+                    memcmp: {
+                        offset: DEPOSIT_REQUEST_OFFSETS.depositor,
+                        bytes: this.key(depositor).toBase58()
+                    }
+                }
+            ]
+        });
+        return accounts
+            .map(({ pubkey, account }) => decodeDepositRequest(account.data, pubkey))
+            .sort((a, b) => a.sequenceNumber < b.sequenceNumber
+            ? -1
+            : a.sequenceNumber > b.sequenceNumber
+                ? 1
+                : 0);
+    }
+    /**
+     * A depositor's requests, split by what they can do with them.
+     *
+     * `pending` is still queued and can be cancelled; `claimable` has settled
+     * with an undeliverable refund and is collected with `claim_refund`.
+     */
+    async getDepositsFor(shareMint, depositor) {
+        const mine = await this.getRequestsByDepositor(shareMint, depositor);
+        return {
+            pending: mine.filter(r => !r.claimable),
+            claimable: mine.filter(r => r.claimable)
+        };
     }
     // --- withdrawals ---
     /** An owner's vault account, or null before their first deposit or redeem. */

package/dist/src/solana-vaults/signers/index.d.ts

@@ -0,0 +1 @@
+export * from "./solana-signer.js";

package/dist/src/solana-vaults/signers/index.js

@@ -0,0 +1 @@
+export * from "./solana-signer.js";

package/dist/src/solana-vaults/signers/solana-signer.d.ts

@@ -0,0 +1,44 @@
+import { Keypair, PublicKey, type Transaction } from "@solana/web3.js";
+/**
+ * The browser-wallet shape: Phantom, Solflare, Backpack and the
+ * `@solana/wallet-adapter` wallets all satisfy this.
+ *
+ * Deliberately structural rather than an import of the wallet-adapter types:
+ * taking that dependency would pull a React-oriented package into a library
+ * that otherwise needs only web3.js, and every adapter already matches this.
+ */
+export interface ISolanaWalletAdapter {
+    /** Null while the wallet is disconnected. */
+    publicKey: PublicKey | null;
+    signTransaction(tx: Transaction): Promise<Transaction>;
+    /** Present on most adapters; unused here, declared so they still match. */
+    signAllTransactions?(txs: Transaction[]): Promise<Transaction[]>;
+}
+/**
+ * Either shape works wherever the SDK signs: a raw `Keypair` for scripts, ops
+ * tooling and tests, or a connected wallet for a browser app.
+ */
+export type SolanaSigner = Keypair | ISolanaWalletAdapter;
+/** What the call layer actually uses, once the two shapes are collapsed. */
+export interface INormalisedSolanaSigner {
+    publicKey: PublicKey;
+    signTransaction(tx: Transaction): Promise<Transaction>;
+}
+/**
+ * Duck-typed, NOT `instanceof Keypair`.
+ *
+ * A dApp frequently ends up with two copies of @solana/web3.js in its tree —
+ * its own and the SDK's, or two versions hoisted side by side — and a `Keypair`
+ * built against one copy fails `instanceof` against the other. That failure
+ * mode is silent and maddening to debug, so the check is on shape instead:
+ * only an adapter has `signTransaction`.
+ */
+export declare function isWalletAdapter(signer: SolanaSigner): signer is ISolanaWalletAdapter;
+/**
+ * Collapses either shape into one signer.
+ *
+ * A disconnected wallet is rejected here rather than later: its `publicKey` is
+ * null, which would otherwise surface as a confusing failure deep inside
+ * instruction building, after the caller has already paid for account reads.
+ */
+export declare function normaliseSigner(signer: SolanaSigner): INormalisedSolanaSigner;

package/dist/src/solana-vaults/signers/solana-signer.js

@@ -0,0 +1,61 @@
+/**
+ * Duck-typed, NOT `instanceof Keypair`.
+ *
+ * A dApp frequently ends up with two copies of @solana/web3.js in its tree —
+ * its own and the SDK's, or two versions hoisted side by side — and a `Keypair`
+ * built against one copy fails `instanceof` against the other. That failure
+ * mode is silent and maddening to debug, so the check is on shape instead:
+ * only an adapter has `signTransaction`.
+ */
+export function isWalletAdapter(signer) {
+    return typeof signer.signTransaction === "function";
+}
+/**
+ * The inverse check, structural throughout.
+ *
+ * `publicKey instanceof PublicKey` would defeat the whole point of the check
+ * above: a Keypair from another copy of web3.js carries THAT copy's PublicKey,
+ * so the duplicate-package hazard would simply move here and reject a perfectly
+ * good signer. It is checked by the methods this SDK actually calls on it.
+ */
+function isKeypairLike(signer) {
+    const candidate = signer;
+    const key = candidate.publicKey;
+    return (candidate.secretKey instanceof Uint8Array &&
+        key !== null &&
+        key !== undefined &&
+        typeof key.toBase58 === "function" &&
+        typeof key.toBuffer === "function");
+}
+/**
+ * Collapses either shape into one signer.
+ *
+ * A disconnected wallet is rejected here rather than later: its `publicKey` is
+ * null, which would otherwise surface as a confusing failure deep inside
+ * instruction building, after the caller has already paid for account reads.
+ */
+export function normaliseSigner(signer) {
+    if (isWalletAdapter(signer)) {
+        const { publicKey } = signer;
+        if (publicKey === null || publicKey === undefined) {
+            throw new Error("wallet is not connected: its publicKey is null. Connect it before signing.");
+        }
+        return {
+            publicKey,
+            signTransaction: (tx) => signer.signTransaction(tx)
+        };
+    }
+    if (isKeypairLike(signer)) {
+        return {
+            publicKey: signer.publicKey,
+            // partialSign rather than sign: a transaction may legitimately need
+            // other signatures too (a fresh mint keypair, a fee payer), and
+            // `sign` would discard any already collected.
+            signTransaction: async (tx) => {
+                tx.partialSign(signer);
+                return tx;
+            }
+        };
+    }
+    throw new Error("unsupported signer: pass a Keypair, or a wallet exposing publicKey and signTransaction");
+}

package/dist/src/solana-vaults/utils/borsh.d.ts

@@ -1,5 +1,5 @@
 import { PublicKey } from "@solana/web3.js";
-import type { ISolanaProtocolConfigState, ISolanaVaultAccount, ISolanaVaultState, ISolanaWithdrawalQueue, ISolanaWithdrawalRequestAccount } from "../interfaces/index.js";
+import type { ISolanaDepositRequest, ISolanaParkingLotState, ISolanaProtocolConfigState, ISolanaVaultAccount, ISolanaVaultState, ISolanaWithdrawalQueue, ISolanaWithdrawalRequestAccount } from "../interfaces/index.js";
 /**
  * Borsh decoding for `ember_vaults` accounts.
  *
@@ -62,4 +62,15 @@ export interface ISplMint {
  * The classic 82-byte SPL mint layout. The first 82 bytes of a Token-2022
  * mint are identical, so this reads both; it just ignores any extensions.
  */
+/**
+ * `state::DepositParkingLot`.
+ *
+ * Field order tracks the Rust struct and is load-bearing: a transposition
+ * decodes into plausible numbers rather than failing. `sequence_number` and
+ * `queue_start_index` are u128 - sixteen bytes each, not eight - so reading
+ * either as a u64 would silently shift every field after it.
+ */
+export declare function decodeDepositParkingLot(data: Buffer, address: PublicKey): ISolanaParkingLotState;
+/** `state::DepositRequest`, one parked deposit. */
+export declare function decodeDepositRequest(data: Buffer, address: PublicKey): ISolanaDepositRequest;
 export declare function decodeMint(data: Buffer): ISplMint;

package/dist/src/solana-vaults/utils/borsh.js

@@ -128,8 +128,11 @@ function decodeVaultInner(data) {
     const maxTvl = c.u64();
     const sequenceNumber = c.u128();
     const parkingLot = c.pubkey();
-    const depositUserList = c.vec(x => x.pubkey());
-    const withdrawalUserList = c.vec(x => x.pubkey());
+    // Counts, not members: both lists became one PDA per account, so the vault
+    // carries only their size. 0 means open to all; use deriveDepositUser /
+    // deriveWithdrawalUser to test one account.
+    const depositUserCount = c.u64();
+    const withdrawalUserCount = c.u64();
     // The tail the parking-lot change appended. Decoded rather than skipped:
     // a vault with fees configured would otherwise be indistinguishable from a
     // fee-free one.
@@ -161,8 +164,8 @@ function decodeVaultInner(data) {
         maxTvl,
         sequenceNumber,
         parkingLot,
-        depositUserList,
-        withdrawalUserList,
+        depositUserCount,
+        withdrawalUserCount,
         withdrawalFee
     };
     return { vault, position: c.position() };
@@ -225,6 +228,45 @@ export function decodeProtocolConfig(data) {
  * The classic 82-byte SPL mint layout. The first 82 bytes of a Token-2022
  * mint are identical, so this reads both; it just ignores any extensions.
  */
+/**
+ * `state::DepositParkingLot`.
+ *
+ * Field order tracks the Rust struct and is load-bearing: a transposition
+ * decodes into plausible numbers rather than failing. `sequence_number` and
+ * `queue_start_index` are u128 - sixteen bytes each, not eight - so reading
+ * either as a u64 would silently shift every field after it.
+ */
+export function decodeDepositParkingLot(data, address) {
+    const c = expect(data, "DepositParkingLot");
+    return {
+        address,
+        bump: c.u8(),
+        vault: c.pubkey(),
+        operator: c.pubkey(),
+        depositsPaused: c.bool(),
+        cancellationsPaused: c.bool(),
+        sequenceNumber: c.u128(),
+        queueStartIndex: c.u128(),
+        totalPendingAssets: c.u64(),
+        totalClaimableAssets: c.u64(),
+        depositAllowListCount: c.u64()
+    };
+}
+/** `state::DepositRequest`, one parked deposit. */
+export function decodeDepositRequest(data, address) {
+    const c = expect(data, "DepositRequest");
+    return {
+        address,
+        bump: c.u8(),
+        parkingLot: c.pubkey(),
+        sequenceNumber: c.u128(),
+        depositor: c.pubkey(),
+        receiver: c.pubkey(),
+        assets: c.u64(),
+        timestamp: c.u64(),
+        claimable: c.bool()
+    };
+}
 export function decodeMint(data) {
     const option = (o) => data.readUInt32LE(o) === 1 ? new PublicKey(data.subarray(o + 4, o + 36)) : null;
     return {

package/dist/src/solana-vaults/utils/pdas.d.ts

@@ -2,6 +2,15 @@ import { PublicKey } from "@solana/web3.js";
 import { type ISolanaVaultPdas } from "../interfaces/index.js";
 /** Little-endian u64, for the nonce and sequence-number seeds. */
 export declare function u64le(v: bigint | number): Buffer;
+/**
+ * A u128 as 16 little-endian bytes: the program's sequence numbers.
+ *
+ * Range-checked, because the masking loop truncates silently otherwise:
+ * `(1n << 128n) + 6n` and `6n` encode to identical bytes, so an out-of-range
+ * sequence number would cancel request 6 rather than fail. `u64le` gets this
+ * for free from `writeBigUInt64LE`, which throws.
+ */
+export declare function u128le(v: bigint | number): Buffer;
 /** The protocol-wide config. One per program id, and it can never be closed. */
 export declare const deriveProtocolConfig: (programId: PublicKey) => PublicKey;
 /**
@@ -23,6 +32,67 @@ export declare const deriveVaultAccount: (programId: PublicKey, vault: PublicKey
  * nonce 0.
  */
 export declare const deriveWithdrawalRequest: (programId: PublicKey, vault: PublicKey, owner: PublicKey, nonce: bigint) => PublicKey;
+/**
+ * `getMultipleAccounts` refuses more than 100 pubkeys per call, so any wider
+ * window has to be split rather than sent whole.
+ */
+export declare const MAX_MULTIPLE_ACCOUNTS = 100;
+/** An upper bound on one queue scan, so a caller cannot ask for an unbounded walk. */
+export declare const MAX_QUEUE_SCAN = 1000;
+/** `DepositRequest` is fixed width, which lets getProgramAccounts filter on it. */
+export declare const DEPOSIT_REQUEST_SIZE = 138;
+/**
+ * Byte offsets into a `DepositRequest` account, discriminator included.
+ *
+ * Used as memcmp filters, so they track state.rs exactly: an offset that
+ * drifts returns nothing rather than failing, which looks like "no requests".
+ */
+export declare const DEPOSIT_REQUEST_OFFSETS: {
+    /** after discriminator(8) + bump(1) */
+    readonly parkingLot: 9;
+    /** after parking_lot(32) + sequence_number(16) */
+    readonly depositor: 57;
+    /** after receiver(32) + assets(8) + timestamp(8) */
+    readonly claimable: 137;
+};
+/** Membership of a vault's deposit allow list. Scoped to the vault. */
+export declare const deriveDepositUser: (programId: PublicKey, vault: PublicKey, account: PublicKey) => PublicKey;
+/** Membership of a vault's withdrawal allow list. Scoped to the vault. */
+export declare const deriveWithdrawalUser: (programId: PublicKey, vault: PublicKey, account: PublicKey) => PublicKey;
+/**
+ * Membership of a parking lot's own deposit allow list.
+ *
+ * Scoped to the VAULT, not the lot, matching the program's
+ * `[PARKING_LOT_USER_SEED, vault, account]`.
+ */
+export declare const deriveParkingLotUser: (programId: PublicKey, vault: PublicKey, account: PublicKey) => PublicKey;
+/**
+ * A vault's deposit parking lot: where async deposits wait to be forwarded.
+ *
+ * One lot per vault, so this is derivable from the vault alone. A vault with
+ * no lot simply has no account at this address.
+ */
+export declare const deriveParkingLot: (programId: PublicKey, vault: PublicKey) => PublicKey;
+/**
+ * The lot's escrow token account, holding collateral for pending requests.
+ *
+ * It holds `total_pending_assets + total_claimable_assets`: the second is
+ * Solana-only, owed to depositors whose refund could not be delivered.
+ */
+export declare const deriveParkingLotEscrow: (programId: PublicKey, parkingLot: PublicKey) => PublicKey;
+/**
+ * One parked deposit, keyed by its queue sequence number.
+ *
+ * The seed is a u128 (16 bytes LE), not the u64 the withdrawal request uses.
+ *
+ * WHEN PARKING, the sequence number is the lot's `sequence_number` PLUS ONE -
+ * the slot the next park will take, since the program increments before it
+ * writes. That makes a park racy by construction: if another lands first this
+ * address is already in use and the transaction fails its address check, and
+ * must be rebuilt against a fresh read. Cancelling or claiming an EXISTING
+ * request uses that request's own recorded sequence number instead.
+ */
+export declare const deriveDepositRequest: (programId: PublicKey, parkingLot: PublicKey, sequenceNumber: bigint) => PublicKey;
 /**
  * The event authority `emit_cpi!` signs with. Anchor requires it and the
  * program id as the last two accounts of every instruction that emits.

package/dist/src/solana-vaults/utils/pdas.js

@@ -20,6 +20,27 @@ export function u64le(v) {
     b.writeBigUInt64LE(BigInt(v));
     return b;
 }
+const U128_MAX = (1n << 128n) - 1n;
+/**
+ * A u128 as 16 little-endian bytes: the program's sequence numbers.
+ *
+ * Range-checked, because the masking loop truncates silently otherwise:
+ * `(1n << 128n) + 6n` and `6n` encode to identical bytes, so an out-of-range
+ * sequence number would cancel request 6 rather than fail. `u64le` gets this
+ * for free from `writeBigUInt64LE`, which throws.
+ */
+export function u128le(v) {
+    let value = BigInt(v);
+    if (value < 0n || value > U128_MAX) {
+        throw new RangeError(`value ${value} is out of range for a u128`);
+    }
+    const buf = Buffer.alloc(16);
+    for (let i = 0; i < 16; i++) {
+        buf[i] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+    return buf;
+}
 /** The protocol-wide config. One per program id, and it can never be closed. */
 export const deriveProtocolConfig = (programId) => PublicKey.findProgramAddressSync([seed(SOLANA_SEEDS.protocolConfig)], programId)[0];
 /**
@@ -55,11 +76,86 @@ export const deriveWithdrawalRequest = (programId, vault, owner, nonce) => Publi
     owner.toBuffer(),
     u64le(nonce)
 ], programId)[0];
-// The parking lot's PDAs - the lot, its escrow and a deposit request - are
-// derived in the phase that adds decoders for DepositParkingLot and
-// DepositRequest. Deriving an address nothing can read is a surface that
-// looks usable and is not. Note for then: a request's seed is the lot's
-// sequence_number + 1, the slot the next park will take.
+/**
+ * `getMultipleAccounts` refuses more than 100 pubkeys per call, so any wider
+ * window has to be split rather than sent whole.
+ */
+export const MAX_MULTIPLE_ACCOUNTS = 100;
+/** An upper bound on one queue scan, so a caller cannot ask for an unbounded walk. */
+export const MAX_QUEUE_SCAN = 1000;
+/** `DepositRequest` is fixed width, which lets getProgramAccounts filter on it. */
+export const DEPOSIT_REQUEST_SIZE = 138;
+/**
+ * Byte offsets into a `DepositRequest` account, discriminator included.
+ *
+ * Used as memcmp filters, so they track state.rs exactly: an offset that
+ * drifts returns nothing rather than failing, which looks like "no requests".
+ */
+export const DEPOSIT_REQUEST_OFFSETS = {
+    /** after discriminator(8) + bump(1) */
+    parkingLot: 9,
+    /** after parking_lot(32) + sequence_number(16) */
+    depositor: 57,
+    /** after receiver(32) + assets(8) + timestamp(8) */
+    claimable: 137
+};
+/**
+ * An allow-list entry: one account per listed member.
+ *
+ * The three lists are unbounded, so membership is not a `Vec` on the vault or
+ * the lot but the EXISTENCE of this PDA. The program's test is
+ * `UserListEntry::exists` - owned by the program and non-empty - which is
+ * stricter than "the account exists": these addresses are public and
+ * derivable, so anyone can make a bare `getAccountInfo` return non-null by
+ * sending lamports to one. A system-owned account with no data reads as
+ * listed to a naive check and is rejected on chain.
+ *
+ * Every gated instruction takes the caller's entry whether or not it exists,
+ * so these are always derivable without a network read.
+ */
+const deriveUserEntry = (programId, seedName, scope, account) => PublicKey.findProgramAddressSync([seed(seedName), scope.toBuffer(), account.toBuffer()], programId)[0];
+/** Membership of a vault's deposit allow list. Scoped to the vault. */
+export const deriveDepositUser = (programId, vault, account) => deriveUserEntry(programId, SOLANA_SEEDS.depositUser, vault, account);
+/** Membership of a vault's withdrawal allow list. Scoped to the vault. */
+export const deriveWithdrawalUser = (programId, vault, account) => deriveUserEntry(programId, SOLANA_SEEDS.withdrawalUser, vault, account);
+/**
+ * Membership of a parking lot's own deposit allow list.
+ *
+ * Scoped to the VAULT, not the lot, matching the program's
+ * `[PARKING_LOT_USER_SEED, vault, account]`.
+ */
+export const deriveParkingLotUser = (programId, vault, account) => deriveUserEntry(programId, SOLANA_SEEDS.parkingLotUser, vault, account);
+/**
+ * A vault's deposit parking lot: where async deposits wait to be forwarded.
+ *
+ * One lot per vault, so this is derivable from the vault alone. A vault with
+ * no lot simply has no account at this address.
+ */
+export const deriveParkingLot = (programId, vault) => PublicKey.findProgramAddressSync([seed(SOLANA_SEEDS.parkingLot), vault.toBuffer()], programId)[0];
+/**
+ * The lot's escrow token account, holding collateral for pending requests.
+ *
+ * It holds `total_pending_assets + total_claimable_assets`: the second is
+ * Solana-only, owed to depositors whose refund could not be delivered.
+ */
+export const deriveParkingLotEscrow = (programId, parkingLot) => PublicKey.findProgramAddressSync([seed(SOLANA_SEEDS.parkingLotEscrow), parkingLot.toBuffer()], programId)[0];
+/**
+ * One parked deposit, keyed by its queue sequence number.
+ *
+ * The seed is a u128 (16 bytes LE), not the u64 the withdrawal request uses.
+ *
+ * WHEN PARKING, the sequence number is the lot's `sequence_number` PLUS ONE -
+ * the slot the next park will take, since the program increments before it
+ * writes. That makes a park racy by construction: if another lands first this
+ * address is already in use and the transaction fails its address check, and
+ * must be rebuilt against a fresh read. Cancelling or claiming an EXISTING
+ * request uses that request's own recorded sequence number instead.
+ */
+export const deriveDepositRequest = (programId, parkingLot, sequenceNumber) => PublicKey.findProgramAddressSync([
+    seed(SOLANA_SEEDS.depositRequest),
+    parkingLot.toBuffer(),
+    u128le(sequenceNumber)
+], programId)[0];
 /**
  * The event authority `emit_cpi!` signs with. Anchor requires it and the
  * program id as the last two accounts of every instruction that emits.