@ember-finance/sdk 2.38.0 → 2.39.0

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

@@ -0,0 +1,111 @@
+/**
+ * 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 const BASE = 1000000000n;
+const U64_MAX = 18446744073709551615n;
+/** `math::safely_cast_to_u64`. */
+function castToU64(value, op) {
+    if (value > U64_MAX) {
+        throw new Error(`${op} overflowed a u64: ${value}`);
+    }
+    return value;
+}
+/** `math::mul`: `a * b / BASE`, flooring. */
+export function mul(a, b) {
+    return castToU64((a * b) / BASE, "mul");
+}
+/** `math::mul_ceil`. */
+export function mulCeil(a, b) {
+    return castToU64((a * b + BASE - 1n) / BASE, "mul_ceil");
+}
+/** `math::div`: `a * BASE / b`, flooring. */
+export function div(a, b) {
+    if (b <= 0n)
+        throw new Error("division by zero");
+    return castToU64((a * BASE) / b, "div");
+}
+/** `math::div_ceil`. */
+export function divCeil(a, b) {
+    if (b <= 0n)
+        throw new Error("division by zero");
+    return castToU64((a * BASE + b - 1n) / b, "div_ceil");
+}
+// --- the vault's derived quantities, from state.rs ---------------------------------
+/** `Vault::get_vault_tvl`. */
+export const vaultTvl = (totalShares, rate) => div(totalShares, rate);
+/** `Vault::calculate_shares_from_amount`. */
+export const sharesFromAmount = (amount, rate) => mul(amount, rate);
+/** `Vault::calculate_shares_from_amount_ceil`. */
+export const sharesFromAmountCeil = (amount, rate) => mulCeil(amount, rate);
+/** `Vault::calculate_amount_from_shares_floor`: what settlement actually pays. */
+export const amountFromSharesFloor = (shares, rate) => div(shares, rate);
+/** `Vault::calculate_amount_from_shares`: ceil, what minting costs. */
+export const amountFromShares = (shares, rate) => divCeil(shares, rate);
+/**
+ * `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 function maxMintShares(totalShares, rate, maxTvl) {
+    const maxSupply = (maxTvl * rate) / BASE;
+    const capped = maxSupply > U64_MAX ? U64_MAX : maxSupply;
+    return capped > totalShares ? capped - totalShares : 0n;
+}
+/**
+ * `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 function maxDepositAmount(totalShares, rate, maxTvl) {
+    if (rate <= 0n)
+        throw new Error("division by zero");
+    const headroom = maxMintShares(totalShares, rate, maxTvl);
+    if (headroom === 0n)
+        return 0n;
+    const maxAmount = ((headroom + 1n) * BASE - 1n) / rate;
+    return maxAmount > U64_MAX ? U64_MAX : maxAmount;
+}
+/**
+ * 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 function withdrawalFee(gross, fee, options) {
+    if (options.exempt) {
+        return { permanent: 0n, timeBased: 0n, net: gross };
+    }
+    const permanent = fee.permanentFeePercentage > 0n ? mul(gross, fee.permanentFeePercentage) : 0n;
+    let timeBased = 0n;
+    if (fee.timeBasedFeePercentage > 0n && fee.timeBasedFeeThreshold > 0n) {
+        // Written as the program writes it, to avoid overflowing
+        // lastDepositTs + threshold.
+        const inWindow = options.lastDepositTs === 0n ||
+            options.nowMs < options.lastDepositTs ||
+            fee.timeBasedFeeThreshold > options.nowMs - options.lastDepositTs;
+        if (inWindow)
+            timeBased = mul(gross, fee.timeBasedFeePercentage);
+    }
+    return { permanent, timeBased, net: gross - permanent - timeBased };
+}

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

@@ -0,0 +1,54 @@
+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;
+/** The protocol-wide config. One per program id, and it can never be closed. */
+export declare const deriveProtocolConfig: (programId: PublicKey) => PublicKey;
+/**
+ * The vault PDA and the three accounts hanging off it.
+ *
+ * `["vault", share_mint]` is the only seed pair, which is what makes the share
+ * mint the vault's identity: one mint is one vault, enforced on chain because
+ * a second `create_vault` on the same mint hits an already-initialised
+ * account.
+ */
+export declare function deriveVaultPdas(programId: PublicKey, shareMint: PublicKey): ISolanaVaultPdas;
+/** An owner's per-vault account: their deposit clock and pending requests. */
+export declare const deriveVaultAccount: (programId: PublicKey, vault: PublicKey, owner: PublicKey) => PublicKey;
+/**
+ * A withdrawal request's account.
+ *
+ * Seeded by the owner's `next_request_nonce` *at the time of the request*, so
+ * a caller must read the owner's `VaultAccount` first. A fresh owner starts at
+ * nonce 0.
+ */
+export declare const deriveWithdrawalRequest: (programId: PublicKey, vault: PublicKey, owner: PublicKey, nonce: 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.
+ */
+export declare const deriveEventAuthority: (programId: PublicKey) => PublicKey;
+/** Those last two accounts, ready to append to an instruction's keys. */
+export declare const eventCpiAccounts: (programId: PublicKey) => {
+    pubkey: PublicKey;
+    isSigner: boolean;
+    isWritable: boolean;
+}[];
+/** `sha256("global:<name>")[..8]`, the first eight bytes of an instruction. */
+export declare const instructionDiscriminator: (name: string) => Buffer;
+/** `sha256("account:<Name>")[..8]`, the first eight bytes of an account. */
+export declare const accountDiscriminator: (name: string) => Buffer;
+export declare const TOKEN_PROGRAM_ID: PublicKey;
+export declare const TOKEN_2022_PROGRAM_ID: PublicKey;
+export declare const ASSOCIATED_TOKEN_PROGRAM_ID: PublicKey;
+export declare const TOKEN_METADATA_PROGRAM_ID: PublicKey;
+/**
+ * An associated token account.
+ *
+ * `tokenProgram` matters: the same owner and mint give different addresses
+ * under SPL Token and Token-2022, and a vault's collateral and share mints may
+ * live under different programs.
+ */
+export declare const associatedTokenAddress: (owner: PublicKey, mint: PublicKey, tokenProgram?: PublicKey) => PublicKey;
+/** The Metaplex metadata account carrying a mint's name and symbol. */
+export declare const metadataAddress: (mint: PublicKey) => PublicKey;

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

@@ -0,0 +1,93 @@
+import { PublicKey } from "@solana/web3.js";
+// Not node:crypto. This module is reachable from the SDK root through
+// EmberVaults, so a Node-only import would break browser builds for every
+// consumer, Sui and EVM included - not just Solana ones.
+import { sha256 } from "@noble/hashes/sha2";
+import { SOLANA_SEEDS } from "../interfaces/index.js";
+/**
+ * PDA derivation for `ember_vaults`.
+ *
+ * Every address below is a pure function of the program id and, where it
+ * applies, the share mint. Nothing here touches the network, and the results
+ * are stable across redeploys: upgrading a program leaves its id unchanged,
+ * so its PDAs and the accounts at them survive. Only a new program id moves
+ * them.
+ */
+const seed = (s) => Buffer.from(s, "utf8");
+/** Little-endian u64, for the nonce and sequence-number seeds. */
+export function u64le(v) {
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(BigInt(v));
+    return b;
+}
+/** 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];
+/**
+ * The vault PDA and the three accounts hanging off it.
+ *
+ * `["vault", share_mint]` is the only seed pair, which is what makes the share
+ * mint the vault's identity: one mint is one vault, enforced on chain because
+ * a second `create_vault` on the same mint hits an already-initialised
+ * account.
+ */
+export function deriveVaultPdas(programId, shareMint) {
+    const pda = (...seeds) => PublicKey.findProgramAddressSync(seeds, programId)[0];
+    const vault = pda(seed(SOLANA_SEEDS.vault), shareMint.toBuffer());
+    return {
+        vault,
+        vaultCollateral: pda(seed(SOLANA_SEEDS.vaultCollateral), vault.toBuffer()),
+        vaultPendingShares: pda(seed(SOLANA_SEEDS.vaultPendingShares), vault.toBuffer()),
+        withdrawalQueue: pda(seed(SOLANA_SEEDS.withdrawalQueue), vault.toBuffer())
+    };
+}
+/** An owner's per-vault account: their deposit clock and pending requests. */
+export const deriveVaultAccount = (programId, vault, owner) => PublicKey.findProgramAddressSync([seed(SOLANA_SEEDS.account), vault.toBuffer(), owner.toBuffer()], programId)[0];
+/**
+ * A withdrawal request's account.
+ *
+ * Seeded by the owner's `next_request_nonce` *at the time of the request*, so
+ * a caller must read the owner's `VaultAccount` first. A fresh owner starts at
+ * nonce 0.
+ */
+export const deriveWithdrawalRequest = (programId, vault, owner, nonce) => PublicKey.findProgramAddressSync([
+    seed(SOLANA_SEEDS.withdrawalRequest),
+    vault.toBuffer(),
+    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.
+/**
+ * The event authority `emit_cpi!` signs with. Anchor requires it and the
+ * program id as the last two accounts of every instruction that emits.
+ */
+export const deriveEventAuthority = (programId) => PublicKey.findProgramAddressSync([seed("__event_authority")], programId)[0];
+/** Those last two accounts, ready to append to an instruction's keys. */
+export const eventCpiAccounts = (programId) => [
+    { pubkey: deriveEventAuthority(programId), isSigner: false, isWritable: false },
+    { pubkey: programId, isSigner: false, isWritable: false }
+];
+// --- Anchor discriminators --------------------------------------------------------
+const digest8 = (preimage) => Buffer.from(sha256(new TextEncoder().encode(preimage))).subarray(0, 8);
+/** `sha256("global:<name>")[..8]`, the first eight bytes of an instruction. */
+export const instructionDiscriminator = (name) => digest8(`global:${name}`);
+/** `sha256("account:<Name>")[..8]`, the first eight bytes of an account. */
+export const accountDiscriminator = (name) => digest8(`account:${name}`);
+// --- SPL addresses ----------------------------------------------------------------
+export const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+export const TOKEN_2022_PROGRAM_ID = new PublicKey("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb");
+export const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+export const TOKEN_METADATA_PROGRAM_ID = new PublicKey("metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s");
+/**
+ * An associated token account.
+ *
+ * `tokenProgram` matters: the same owner and mint give different addresses
+ * under SPL Token and Token-2022, and a vault's collateral and share mints may
+ * live under different programs.
+ */
+export const associatedTokenAddress = (owner, mint, tokenProgram = TOKEN_PROGRAM_ID) => PublicKey.findProgramAddressSync([owner.toBuffer(), tokenProgram.toBuffer(), mint.toBuffer()], ASSOCIATED_TOKEN_PROGRAM_ID)[0];
+/** The Metaplex metadata account carrying a mint's name and symbol. */
+export const metadataAddress = (mint) => PublicKey.findProgramAddressSync([Buffer.from("metadata"), TOKEN_METADATA_PROGRAM_ID.toBuffer(), mint.toBuffer()], TOKEN_METADATA_PROGRAM_ID)[0];

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@ember-finance/sdk",
     "description": "Ember Protocol SDK",
-    "version": "2.38.0",
+    "version": "2.39.0",
     "type": "module",
     "module": "./dist/index.js",
     "main": "./dist/index.js",
@@ -85,6 +85,7 @@
     "dependencies": {
         "@aws-sdk/client-kms": "^3.1044.0",
         "@noble/curves": "^2.2.0",
+        "@noble/hashes": "^1.8.0",
         "asn1.js": "^5.4.1",
         "axios": "1.13.6",
         "yarn": "^1.22.19"
@@ -93,6 +94,7 @@
         "@firefly-exchange/library-sui": "^3.0.0",
         "@mysten/sui": "^2.0.0",
         "@openapitools/openapi-generator-cli": "^2.41.0",
+        "@solana/web3.js": "^1.95.0",
         "@types/chai": "^4.3.3",
         "@types/chai-as-promised": "^7.1.5",
         "@types/dotenv-parse-variables": "^2.0.1",
@@ -118,6 +120,7 @@
     "peerDependencies": {
         "@firefly-exchange/library-sui": "^3.0.0",
         "@mysten/sui": "^2.0.0",
+        "@solana/web3.js": "^1.95.0",
         "ethers": "^6.13.4"
     },
     "repository": {
@@ -143,5 +146,10 @@
         "shell-quote": "^1.10.0",
         "tar": "^7.5.19"
     },
-    "packageManager": "yarn@4.14.1"
+    "packageManager": "yarn@4.14.1",
+    "peerDependenciesMeta": {
+        "@solana/web3.js": {
+            "optional": true
+        }
+    }
 }