@ember-finance/sdk 2.38.0 → 2.40.0

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

@@ -0,0 +1,237 @@
+import { PublicKey } from "@solana/web3.js";
+import { accountDiscriminator } from "./pdas.js";
+/**
+ * Borsh decoding for `ember_vaults` accounts.
+ *
+ * Decoded by hand rather than through Anchor's client. The program's IDL is
+ * not published on chain — `anchor idl init` cannot get an IDL this size past
+ * the public RPCs — so a client cannot fetch it, and pulling in the whole
+ * Anchor runtime to read a few dozen fields is not worth the dependency.
+ *
+ * Field order here must track `state.rs`. The discriminator check catches a
+ * wrong account type; it cannot catch a field reordered within the right one,
+ * so `SolanaAccountDecoding.test.ts` pins the offsets against fixtures taken
+ * from a real deployment.
+ */
+/** A forward-only reader over account data. */
+export class Cursor {
+    constructor(data, offset = 0) {
+        this.data = data;
+        this.offset = offset;
+    }
+    skip(n) {
+        this.offset += n;
+        return this;
+    }
+    u8() {
+        return this.data.readUInt8(this.offset++);
+    }
+    bool() {
+        // Borsh admits only 0 or 1. Anything else means the cursor has drifted
+        // out of alignment, and reading it as false would hide that.
+        const b = this.u8();
+        if (b > 1)
+            throw new Error(`invalid bool byte ${b}: the layout is misaligned`);
+        return b === 1;
+    }
+    u64() {
+        const v = this.data.readBigUInt64LE(this.offset);
+        this.offset += 8;
+        return v;
+    }
+    u128() {
+        const lo = this.data.readBigUInt64LE(this.offset);
+        const hi = this.data.readBigUInt64LE(this.offset + 8);
+        this.offset += 16;
+        return (hi << 64n) | lo;
+    }
+    pubkey() {
+        const k = new PublicKey(this.data.subarray(this.offset, this.offset + 32));
+        this.offset += 32;
+        return k;
+    }
+    string() {
+        const len = this.data.readUInt32LE(this.offset);
+        const s = this.data
+            .subarray(this.offset + 4, this.offset + 4 + len)
+            .toString("utf8");
+        this.offset += 4 + len;
+        return s;
+    }
+    vec(item) {
+        const len = this.data.readUInt32LE(this.offset);
+        this.offset += 4;
+        return Array.from({ length: len }, () => item(this));
+    }
+    /** How far in the cursor has read. For the layout tests. */
+    position() {
+        return this.offset;
+    }
+}
+/** Fails unless `data` carries the discriminator for `name`. */
+function expect(data, name) {
+    if (!data.subarray(0, 8).equals(accountDiscriminator(name))) {
+        throw new Error(`account is not a ${name}`);
+    }
+    return new Cursor(data, 8);
+}
+const withdrawalRequest = (c) => ({
+    owner: c.pubkey(),
+    receiver: c.pubkey(),
+    shares: c.u64(),
+    estimatedWithdrawAmount: c.u64(),
+    timestamp: c.u64(),
+    sequenceNumber: c.u128()
+});
+/**
+ * `state::Vault`, in declaration order.
+ *
+ * Returns the cursor's final position alongside the value, so a caller can
+ * check it against the account's own length. Stopping early still decodes
+ * without error — the withdrawal-fee tail was missed exactly that way — so
+ * "it parsed" is not evidence the layout is right.
+ */
+export function decodeVaultWithPosition(data) {
+    const vault = decodeVaultInner(data);
+    return vault;
+}
+/** `state::Vault`, in declaration order. */
+export function decodeVault(data) {
+    return decodeVaultInner(data).vault;
+}
+function decodeVaultInner(data) {
+    const c = expect(data, "Vault");
+    c.u8(); // bump
+    const name = c.string();
+    const admin = c.pubkey();
+    const operator = c.pubkey();
+    const rateManager = c.pubkey();
+    const collateralMint = c.pubkey();
+    const shareMint = c.pubkey();
+    const blacklisted = c.vec(x => x.pubkey());
+    const paused = c.bool();
+    const pausedDeposits = c.bool();
+    const pausedWithdrawals = c.bool();
+    const pausedPrivileged = c.bool();
+    const subAccounts = c.vec(x => x.pubkey());
+    const rate = {
+        value: c.u64(),
+        maxRateChangePerUpdate: c.u64(),
+        rateUpdateInterval: c.u64(),
+        lastUpdatedAt: c.u64()
+    };
+    const feePercentage = c.u64();
+    const balance = c.u64();
+    const pendingSharesToBurn = c.u64();
+    const fee = { accrued: c.u64(), lastChargedAt: c.u64() };
+    const minWithdrawalShares = c.u64();
+    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());
+    // 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.
+    const withdrawalFee = {
+        permanentFeePercentage: c.u64(),
+        timeBasedFeePercentage: c.u64(),
+        timeBasedFeeThreshold: c.u64(),
+        feeExempt: c.vec(x => x.pubkey())
+    };
+    const vault = {
+        name,
+        admin,
+        operator,
+        rateManager,
+        collateralMint,
+        shareMint,
+        blacklisted,
+        paused,
+        pausedDeposits,
+        pausedWithdrawals,
+        pausedPrivileged,
+        subAccounts,
+        rate,
+        feePercentage,
+        balance,
+        pendingSharesToBurn,
+        fee,
+        minWithdrawalShares,
+        maxTvl,
+        sequenceNumber,
+        parkingLot,
+        depositUserList,
+        withdrawalUserList,
+        withdrawalFee
+    };
+    return { vault, position: c.position() };
+}
+/** `state::VaultAccount`. */
+export function decodeVaultAccount(data) {
+    const c = expect(data, "VaultAccount");
+    c.u8(); // bump
+    c.pubkey(); // vault
+    c.pubkey(); // owner
+    return {
+        lastDepositTs: c.u64(),
+        totalPendingWithdrawalShares: c.u64(),
+        pendingWithdrawalRequests: c.vec(withdrawalRequest),
+        cancelWithdrawRequest: c.vec(x => x.u128()),
+        nextRequestNonce: c.u64()
+    };
+}
+/** `state::WithdrawalRequestAccount`. */
+export function decodeWithdrawalRequestAccount(address, data) {
+    const c = expect(data, "WithdrawalRequestAccount");
+    c.u8(); // bump
+    return {
+        address,
+        vault: c.pubkey(),
+        nonce: c.u64(),
+        queueIndex: c.u64(),
+        request: withdrawalRequest(c)
+    };
+}
+/** `state::WithdrawalQueue`: head and tail, the entries live in their own accounts. */
+export function decodeWithdrawalQueue(data) {
+    const c = expect(data, "WithdrawalQueue");
+    c.u8(); // bump
+    return { vault: c.pubkey(), head: c.u64(), tail: c.u64() };
+}
+/** `state::ProtocolConfig`. */
+export function decodeProtocolConfig(data) {
+    const c = expect(data, "ProtocolConfig");
+    c.u8(); // bump
+    // Order is load-bearing: platform_fee_recipient sits *after* version and
+    // the pause flag, and max_rate precedes default_rate. Getting either wrong
+    // decodes silently into plausible-looking nonsense.
+    return {
+        admin: c.pubkey(),
+        pendingAdmin: c.pubkey(),
+        guardian: c.pubkey(),
+        version: c.u64(),
+        pauseNonAdminOperations: c.bool(),
+        platformFeeRecipient: c.pubkey(),
+        minRate: c.u64(),
+        maxRate: c.u64(),
+        defaultRate: c.u64(),
+        minRateInterval: c.u64(),
+        maxRateInterval: c.u64(),
+        maxFeePercentage: c.u64()
+    };
+}
+/**
+ * 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.
+ */
+export function decodeMint(data) {
+    const option = (o) => data.readUInt32LE(o) === 1 ? new PublicKey(data.subarray(o + 4, o + 36)) : null;
+    return {
+        mintAuthority: option(0),
+        supply: data.readBigUInt64LE(36),
+        decimals: data.readUInt8(44),
+        isInitialized: data.readUInt8(45) === 1,
+        freezeAuthority: option(46)
+    };
+}

package/dist/src/solana-vaults/utils/deployment-parser.d.ts

@@ -0,0 +1,94 @@
+import { PublicKey } from "@solana/web3.js";
+import { type ISolanaDeployment, type ISolanaTokenInfo, type ISolanaVaultInfo, type ISolanaVaultPdas } from "../interfaces/index.js";
+/**
+ * Reads a Solana deployment manifest.
+ *
+ * The manifest is `deployments/<cluster>.json` from ember-contracts, served
+ * unchanged through the vaults API. Every lookup is local: the parser never
+ * touches the network, and anything it cannot answer from the manifest it
+ * derives, since every vault address is a pure function of its share mint.
+ */
+export declare class SolanaDeploymentParser {
+    private readonly deployment;
+    readonly programId: PublicKey;
+    constructor(deployment: ISolanaDeployment);
+    /** The raw manifest, as supplied. */
+    getDeployment(): ISolanaDeployment;
+    /**
+     * The cluster, when the manifest carries it. The API serves it as the
+     * enclosing chain identifier rather than inside the deployment, so a
+     * parser built from an API response will not have it.
+     */
+    getCluster(): string | undefined;
+    /** The RPC endpoint the deploy ran through. Manifest only. */
+    getRpcUrl(): string | undefined;
+    /**
+     * The protocol config PDA.
+     *
+     * Derived rather than read from the manifest: it is a pure function of the
+     * program id, so deriving it cannot disagree with the chain even if the
+     * manifest is stale.
+     */
+    getProtocolConfigAddress(): PublicKey;
+    /**
+     * The upgrade authority.
+     *
+     * Three outcomes, and they are not the same thing: a key, `null` for a
+     * program explicitly recorded as immutable, and `undefined` when the
+     * deployment simply does not say. The API serves only `programId` as
+     * guaranteed, so an omitted field must not be read as proof of
+     * immutability.
+     */
+    getUpgradeAuthority(): PublicKey | null | undefined;
+    /**
+     * The slot the program was first deployed at — where an indexer should
+     * start its backfill. Never moved by an upgrade; only a new program id
+     * resets it.
+     */
+    getDeploySlot(): number | undefined;
+    getTokens(): Record<string, ISolanaTokenInfo>;
+    getTokenBySymbol(symbol: string): ISolanaTokenInfo | undefined;
+    getTokenByMint(mint: PublicKey | string): ISolanaTokenInfo | undefined;
+    /** The token program that owns a mint, so ATAs derive correctly. */
+    getTokenProgram(mint: PublicKey | string): PublicKey | undefined;
+    /** Every vault, keyed by share mint. */
+    getVaults(): Record<string, ISolanaVaultInfo>;
+    getVaultCount(): number;
+    /** A vault by its share mint, which is its identity. */
+    getVault(shareMint: PublicKey | string): ISolanaVaultInfo | undefined;
+    /**
+     * A vault by name. Names are not unique on chain and the vault admin can
+     * change them, so this throws rather than guessing when two match.
+     */
+    getVaultByName(name: string): ISolanaVaultInfo | undefined;
+    /** A vault by its vault PDA, for resolving an address seen on chain. */
+    getVaultByAddress(vault: PublicKey | string): ISolanaVaultInfo | undefined;
+    /**
+     * The vault's PDAs, derived from the share mint.
+     *
+     * The manifest records these too, and they are checked against the
+     * derivation: a mismatch means the manifest was written by a different
+     * program id, which would otherwise surface as a confusing on-chain
+     * failure much later.
+     */
+    getVaultPdas(shareMint: PublicKey | string): ISolanaVaultPdas;
+    /** The collateral mint a vault takes. */
+    getCollateralMint(shareMint: PublicKey | string): PublicKey;
+    /** A vault's roles, as addresses. `rateManager` is null until it is set. */
+    getVaultRoles(shareMint: PublicKey | string): {
+        admin: PublicKey;
+        operator: PublicKey;
+        rateManager: PublicKey | null;
+        subAccounts: PublicKey[];
+    };
+    /**
+     * The share token's name and symbol, or null when the vault was created
+     * without metadata. A classic SPL mint carries neither itself; both live
+     * in a Metaplex account alongside it.
+     */
+    getShareTokenMetadata(shareMint: PublicKey | string): {
+        name: string;
+        symbol: string;
+        address: PublicKey;
+    } | null;
+}

package/dist/src/solana-vaults/utils/deployment-parser.js

@@ -0,0 +1,174 @@
+import { PublicKey } from "@solana/web3.js";
+import { deriveProtocolConfig, deriveVaultPdas, metadataAddress } from "./pdas.js";
+/**
+ * Reads a Solana deployment manifest.
+ *
+ * The manifest is `deployments/<cluster>.json` from ember-contracts, served
+ * unchanged through the vaults API. Every lookup is local: the parser never
+ * touches the network, and anything it cannot answer from the manifest it
+ * derives, since every vault address is a pure function of its share mint.
+ */
+export class SolanaDeploymentParser {
+    constructor(deployment) {
+        if (!deployment?.program?.programId) {
+            throw new Error("solana deployment is missing program.programId");
+        }
+        this.deployment = deployment;
+        this.programId = new PublicKey(deployment.program.programId);
+    }
+    /** The raw manifest, as supplied. */
+    getDeployment() {
+        return this.deployment;
+    }
+    /**
+     * The cluster, when the manifest carries it. The API serves it as the
+     * enclosing chain identifier rather than inside the deployment, so a
+     * parser built from an API response will not have it.
+     */
+    getCluster() {
+        return this.deployment.cluster;
+    }
+    /** The RPC endpoint the deploy ran through. Manifest only. */
+    getRpcUrl() {
+        return this.deployment.rpcUrl;
+    }
+    /**
+     * The protocol config PDA.
+     *
+     * Derived rather than read from the manifest: it is a pure function of the
+     * program id, so deriving it cannot disagree with the chain even if the
+     * manifest is stale.
+     */
+    getProtocolConfigAddress() {
+        return deriveProtocolConfig(this.programId);
+    }
+    /**
+     * The upgrade authority.
+     *
+     * Three outcomes, and they are not the same thing: a key, `null` for a
+     * program explicitly recorded as immutable, and `undefined` when the
+     * deployment simply does not say. The API serves only `programId` as
+     * guaranteed, so an omitted field must not be read as proof of
+     * immutability.
+     */
+    getUpgradeAuthority() {
+        const a = this.deployment.program.upgradeAuthority;
+        if (a === undefined)
+            return undefined;
+        return a === null ? null : new PublicKey(a);
+    }
+    /**
+     * The slot the program was first deployed at — where an indexer should
+     * start its backfill. Never moved by an upgrade; only a new program id
+     * resets it.
+     */
+    getDeploySlot() {
+        return this.deployment.program.deploySlot;
+    }
+    // --- tokens ---
+    getTokens() {
+        return this.deployment.tokens ?? {};
+    }
+    getTokenBySymbol(symbol) {
+        return this.getTokens()[symbol];
+    }
+    getTokenByMint(mint) {
+        const key = typeof mint === "string" ? mint : mint.toBase58();
+        return Object.values(this.getTokens()).find(t => t.mint === key);
+    }
+    /** The token program that owns a mint, so ATAs derive correctly. */
+    getTokenProgram(mint) {
+        const token = this.getTokenByMint(mint);
+        return token ? new PublicKey(token.tokenProgram) : undefined;
+    }
+    // --- vaults ---
+    /** Every vault, keyed by share mint. */
+    getVaults() {
+        return this.deployment.vaults ?? {};
+    }
+    getVaultCount() {
+        return Object.keys(this.getVaults()).length;
+    }
+    /** A vault by its share mint, which is its identity. */
+    getVault(shareMint) {
+        const key = typeof shareMint === "string" ? shareMint : shareMint.toBase58();
+        return this.getVaults()[key];
+    }
+    /**
+     * A vault by name. Names are not unique on chain and the vault admin can
+     * change them, so this throws rather than guessing when two match.
+     */
+    getVaultByName(name) {
+        const hits = Object.values(this.getVaults()).filter(v => v.name === name);
+        if (hits.length > 1) {
+            throw new Error(`${hits.length} vaults are named ${JSON.stringify(name)}; address one by share mint`);
+        }
+        return hits[0];
+    }
+    /** A vault by its vault PDA, for resolving an address seen on chain. */
+    getVaultByAddress(vault) {
+        const key = typeof vault === "string" ? vault : vault.toBase58();
+        return Object.values(this.getVaults()).find(v => v.vault === key);
+    }
+    /**
+     * The vault's PDAs, derived from the share mint.
+     *
+     * The manifest records these too, and they are checked against the
+     * derivation: a mismatch means the manifest was written by a different
+     * program id, which would otherwise surface as a confusing on-chain
+     * failure much later.
+     */
+    getVaultPdas(shareMint) {
+        const mint = typeof shareMint === "string" ? new PublicKey(shareMint) : shareMint;
+        const pdas = deriveVaultPdas(this.programId, mint);
+        const recorded = this.getVault(mint);
+        if (recorded && recorded.vault !== pdas.vault.toBase58()) {
+            throw new Error(`manifest records vault ${recorded.vault} for share mint ${mint.toBase58()}, ` +
+                `but program ${this.programId.toBase58()} derives ${pdas.vault.toBase58()}. ` +
+                `The manifest belongs to a different deployment.`);
+        }
+        return pdas;
+    }
+    /** The collateral mint a vault takes. */
+    getCollateralMint(shareMint) {
+        const vault = this.getVault(shareMint);
+        if (!vault) {
+            const key = typeof shareMint === "string" ? shareMint : shareMint.toBase58();
+            throw new Error(`no vault recorded for share mint ${key}`);
+        }
+        return new PublicKey(vault.collateralMint);
+    }
+    /** A vault's roles, as addresses. `rateManager` is null until it is set. */
+    getVaultRoles(shareMint) {
+        const vault = this.getVault(shareMint);
+        if (!vault) {
+            const key = typeof shareMint === "string" ? shareMint : shareMint.toBase58();
+            throw new Error(`no vault recorded for share mint ${key}`);
+        }
+        return {
+            admin: new PublicKey(vault.admin),
+            operator: new PublicKey(vault.operator),
+            rateManager: vault.rateManager ? new PublicKey(vault.rateManager) : null,
+            subAccounts: vault.subAccounts.map(a => new PublicKey(a))
+        };
+    }
+    /**
+     * The share token's name and symbol, or null when the vault was created
+     * without metadata. A classic SPL mint carries neither itself; both live
+     * in a Metaplex account alongside it.
+     */
+    getShareTokenMetadata(shareMint) {
+        const vault = this.getVault(shareMint);
+        if (!vault?.shareName || !vault.shareSymbol)
+            return null;
+        const mint = typeof shareMint === "string" ? new PublicKey(shareMint) : shareMint;
+        return {
+            name: vault.shareName,
+            symbol: vault.shareSymbol,
+            // Derived rather than read: the metadata account is a PDA of the
+            // share mint, so the manifest's copy is a convenience the API does
+            // not serve.
+            address: metadataAddress(mint)
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+export * from "./pdas.js";
+export * from "./borsh.js";
+export * from "./deployment-parser.js";

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

@@ -0,0 +1,3 @@
+export * from "./pdas.js";
+export * from "./borsh.js";
+export * from "./deployment-parser.js";

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

@@ -0,0 +1,77 @@
+/**
+ * The program's fixed-point arithmetic, mirrored exactly.
+ *
+ * Every quote the reader answers locally has an on-chain counterpart in
+ * `quote.rs`, and the two must agree to the unit: a preview that rounds the
+ * other way sends a user into a transaction the program then rejects. So
+ * these are transcribed from `math.rs` rather than reimplemented, including
+ * which operations floor and which ceil.
+ *
+ * `bigint` throughout. The program works in u128 internally and casts back to
+ * u64, so doing this in `number` would lose precision above 2^53 — a vault
+ * holding more than ~9 million tokens at 9 decimals.
+ */
+/** `math::BASE`: 1.0 in the program's fixed point. */
+export declare const BASE = 1000000000n;
+/** `math::mul`: `a * b / BASE`, flooring. */
+export declare function mul(a: bigint, b: bigint): bigint;
+/** `math::mul_ceil`. */
+export declare function mulCeil(a: bigint, b: bigint): bigint;
+/** `math::div`: `a * BASE / b`, flooring. */
+export declare function div(a: bigint, b: bigint): bigint;
+/** `math::div_ceil`. */
+export declare function divCeil(a: bigint, b: bigint): bigint;
+/** `Vault::get_vault_tvl`. */
+export declare const vaultTvl: (totalShares: bigint, rate: bigint) => bigint;
+/** `Vault::calculate_shares_from_amount`. */
+export declare const sharesFromAmount: (amount: bigint, rate: bigint) => bigint;
+/** `Vault::calculate_shares_from_amount_ceil`. */
+export declare const sharesFromAmountCeil: (amount: bigint, rate: bigint) => bigint;
+/** `Vault::calculate_amount_from_shares_floor`: what settlement actually pays. */
+export declare const amountFromSharesFloor: (shares: bigint, rate: bigint) => bigint;
+/** `Vault::calculate_amount_from_shares`: ceil, what minting costs. */
+export declare const amountFromShares: (shares: bigint, rate: bigint) => bigint;
+/**
+ * `Vault::max_mint_shares`: shares still issuable under `maxTvl`.
+ *
+ * Saturating, not checked: a vault already over its cap (because the cap was
+ * lowered, or the rate moved) reports 0 rather than erroring.
+ */
+export declare function maxMintShares(totalShares: bigint, rate: bigint, maxTvl: bigint): bigint;
+/**
+ * `Vault::max_deposit_amount`: collateral still depositable under `maxTvl`.
+ *
+ * The `+1 ... -1` is the program's, not a transcription slip: it is the
+ * largest amount whose floored share conversion still fits the headroom, so
+ * depositing exactly this much lands on the cap rather than one unit over.
+ */
+export declare function maxDepositAmount(totalShares: bigint, rate: bigint, maxTvl: bigint): bigint;
+/** What settlement withholds from a gross payout. */
+export interface IWithdrawalFeeBreakdown {
+    permanent: bigint;
+    timeBased: bigint;
+    /** What the receiver actually gets. */
+    net: bigint;
+}
+/**
+ * The fee settlement deducts, for one holder redeeming `gross`.
+ *
+ * Both fees are taken off the gross amount and stay in the vault, so they
+ * accrue to the remaining holders rather than leaving. A fee-exempt owner
+ * pays neither.
+ *
+ * The time-based fee is charged while the holder is still *inside*
+ * `threshold` of their last deposit — it penalises leaving early, so it
+ * applies to recent depositors, not long-standing ones. A holder with no
+ * recorded deposit at all (`lastDepositTs === 0`, which is how shares received
+ * by transfer look) is treated as inside the window and pays it.
+ */
+export declare function withdrawalFee(gross: bigint, fee: {
+    permanentFeePercentage: bigint;
+    timeBasedFeePercentage: bigint;
+    timeBasedFeeThreshold: bigint;
+}, options: {
+    exempt: boolean;
+    lastDepositTs: bigint;
+    nowMs: bigint;
+}): IWithdrawalFeeBreakdown;