@augustdigital/sdk 9.3.0 → 9.4.0

package/lib/adapters/solana/pricing.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Off-chain mirror of the `august_vault` pricing math.
+ *
+ * Used to quote what a deposit or redeem is expected to return so a slippage
+ * floor can be handed to `deposit_checked` / `redeem_checked`. Mirrors
+ * `VaultState::shares_for_deposit_with_offset` and
+ * `assets_for_redeem_with_offset` (`programs/august-vault/src/state/vault.rs`):
+ * `u128` intermediates, a per-vault virtual-share offset defaulting to
+ * `EXTRA_SHARES = 1_000_000`, a pro-rata floor (deposit) or cap (redeem),
+ * every division rounded down; plus the withdrawal fee `redeem_checked` takes,
+ * `ceil(assets * fee / 1e6)` at `FEE_RATE_DENOMINATOR_VALUE = 1_000_000`.
+ *
+ * A quote is only a quote. The program prices at execution, against state
+ * that may have moved since the read; the floor derived here is what protects
+ * the caller when the two differ.
+ *
+ * This mirror cannot validate itself — agreeing with its own tests proves
+ * nothing about the program — so every claim below about program behaviour is
+ * cited to its handler in `fractal-protocol/solana-upshift-vault-programs`, by
+ * file and function rather than line. Verified against that repo at 3b91c86.
+ * Do not "fix" the math here against intuition; re-read the handler.
+ *
+ * Adapter-internal. These functions are exported for `vault.actions.ts` and
+ * the unit tests only — deliberately absent from the `adapters/solana` barrel,
+ * so they are not public SDK surface and carry no benchmark or telemetry
+ * taxonomy obligation. Promoting one to the barrel means taking both on.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SLIPPAGE_BPS = exports.DEFAULT_SHARE_OFFSET = void 0;
+exports.toBigInt = toBigInt;
+exports.resolveShareOffset = resolveShareOffset;
+exports.totalAssetsOf = totalAssetsOf;
+exports.sharesForDeposit = sharesForDeposit;
+exports.assetsForRedeem = assetsForRedeem;
+exports.withdrawalFee = withdrawalFee;
+exports.applySlippage = applySlippage;
+exports.quoteDepositFloor = quoteDepositFloor;
+exports.quoteRedeemFloor = quoteRedeemFloor;
+const core_1 = require("../../core");
+/** What the program uses when a vault stores `share_offset == 0` (vaults created before the field existed). */
+exports.DEFAULT_SHARE_OFFSET = 1000000n;
+/** Denominator of `VaultState.withdrawal_fee`: the fee is in parts per million. */
+const FEE_RATE_DENOMINATOR = 1000000n;
+/** Slippage tolerance applied when a caller gives neither `slippageBps` nor an explicit floor. */
+exports.DEFAULT_SLIPPAGE_BPS = 50;
+const BPS_DENOMINATOR = 10000n;
+/**
+ * Coerce an on-chain integer as Anchor decodes it (`BN`, `number`, decimal
+ * string, or `bigint`) to `bigint`.
+ *
+ * @param value - The decoded field.
+ * @param label - Named in the error when the value is not a non-negative integer.
+ * @throws AugustSDKError when the value cannot be read as a non-negative integer.
+ */
+function toBigInt(value, label) {
+    if (typeof value === 'bigint' && value >= 0n)
+        return value;
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+        return BigInt(value);
+    const text = typeof value === 'string'
+        ? value
+        : value !== null && typeof value === 'object'
+            ? String(value)
+            : '';
+    if (/^\d+$/.test(text))
+        return BigInt(text);
+    throw new core_1.AugustSDKError('UNKNOWN', `Solana vault pricing: ${label} is not a non-negative integer (got ${String(value)}).`);
+}
+/**
+ * The vault's effective share offset. A stored zero (or a state decoded from
+ * an IDL that predates the field) resolves to the program default, exactly as
+ * `VaultState::share_offset()` does on-chain.
+ *
+ * @param raw - `VaultState.shareOffset` as decoded, or `undefined`.
+ */
+function resolveShareOffset(raw) {
+    if (raw === undefined || raw === null)
+        return exports.DEFAULT_SHARE_OFFSET;
+    const offset = toBigInt(raw, 'shareOffset');
+    return offset === 0n ? exports.DEFAULT_SHARE_OFFSET : offset;
+}
+/**
+ * `localAum + deployedAum`, the `total_assets()` the program prices against.
+ *
+ * @param state - Decoded `VaultState`.
+ * @throws AugustSDKError when either field is missing, which means the state
+ *   was decoded with an IDL this SDK cannot price against.
+ */
+function totalAssetsOf(state) {
+    return (toBigInt(state.localAum, 'localAum') +
+        toBigInt(state.deployedAum, 'deployedAum'));
+}
+function requireSharePrice(supply, totalAssets) {
+    // Mirrors `SharePriceUndefined`: outstanding shares against no assets has no
+    // price in either direction, and the program would refuse the instruction.
+    if (totalAssets === 0n && supply > 0n) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', 'This vault holds no assets while shares are outstanding, so it has no share price; deposits and redemptions are refused until the operator recapitalises it.');
+    }
+}
+/**
+ * Shares minted for depositing `amount` base units.
+ *
+ * `floor(max(amount * (supply + offset) / (totalAssets + offset), amount * supply / totalAssets))`.
+ * Above par the offset term is the larger and binds; below par the pro-rata
+ * floor binds so a depositor never hands value to incumbents on arrival.
+ *
+ * @param input - Share supply, total assets and the vault's resolved offset,
+ *   all in raw base units.
+ * @throws AugustValidationError when the vault has no share price.
+ */
+function sharesForDeposit(input) {
+    const { supply, totalAssets, amount, offset } = input;
+    requireSharePrice(supply, totalAssets);
+    const withOffsets = (amount * (supply + offset)) / (totalAssets + offset);
+    if (totalAssets === 0n)
+        return withOffsets;
+    const proRata = (amount * supply) / totalAssets;
+    return withOffsets > proRata ? withOffsets : proRata;
+}
+/**
+ * Assets paid, before the withdrawal fee, for burning `shares`.
+ *
+ * `floor(min(shares * (totalAssets + offset) / (supply + offset), shares * totalAssets / supply))`.
+ * The mirror of {@link sharesForDeposit}: above par the offset term binds,
+ * below par the pro-rata cap does, so no redeemer takes more than its share.
+ *
+ * @param input - Share supply, total assets and the vault's resolved offset,
+ *   all in raw base units.
+ * @throws AugustValidationError when the vault has no share price.
+ */
+function assetsForRedeem(input) {
+    const { supply, totalAssets, shares, offset } = input;
+    requireSharePrice(supply, totalAssets);
+    const withOffsets = (shares * (totalAssets + offset)) / (supply + offset);
+    if (supply === 0n)
+        return withOffsets;
+    const proRata = (shares * totalAssets) / supply;
+    return withOffsets < proRata ? withOffsets : proRata;
+}
+/**
+ * The withdrawal fee the program takes from a gross redemption:
+ * `ceil(assets * feePpm / 1e6)`, rounded **up** as on-chain.
+ *
+ * @param assets - Gross assets from {@link assetsForRedeem}.
+ * @param feePpm - `VaultState.withdrawalFee`, parts per million.
+ */
+function withdrawalFee(assets, feePpm) {
+    return (assets * feePpm + FEE_RATE_DENOMINATOR - 1n) / FEE_RATE_DENOMINATOR;
+}
+/**
+ * Lower `expected` by `slippageBps` basis points, rounding down.
+ *
+ * @param expected - The quoted output in raw base units.
+ * @param slippageBps - Integer basis points, `0` to `10_000`.
+ * @throws AugustValidationError when `slippageBps` is out of range or not an integer.
+ */
+function applySlippage(expected, slippageBps) {
+    if (!Number.isInteger(slippageBps) ||
+        slippageBps < 0 ||
+        slippageBps > Number(BPS_DENOMINATOR)) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', `slippageBps must be an integer between 0 and 10000, got ${slippageBps}.`);
+    }
+    return (expected * (BPS_DENOMINATOR - BigInt(slippageBps))) / BPS_DENOMINATOR;
+}
+/**
+ * The `min_shares_out` to pass to `deposit_checked`: the quoted shares for
+ * `amount`, lowered by `slippageBps`.
+ *
+ * Nothing is netted out, because there is no deposit-side fee. In
+ * `instructions/deposit.rs::handler_checked` the comparison is
+ * `require!(shares >= min_shares_out, SlippageExceeded)` directly on the
+ * `shares_for_deposit` result, with no fee term anywhere in the handler.
+ * Structurally too: `VaultState` carries exactly one fee field,
+ * `withdrawal_fee`, and `deposit_checked` takes no `fee_recipient_account`
+ * among its accounts (`redeem_checked` does), so it has no account to pay one
+ * to. Gross and net are the same quantity here.
+ *
+ * Quoting from state read *before* the transaction is correct despite the
+ * handler transferring the deposit in first: `transfer_in_ctx` moves SPL
+ * tokens into the vault ATA, but `total_assets()` sums the stored `local_aum`
+ * and `deployed_aum` fields, and `local_aum` is incremented only *after*
+ * `shares_for_deposit` has been computed. Supply is likewise read before the
+ * mint. The handler prices against the same pre-deposit figures this quote
+ * does.
+ *
+ * @param input - Vault state, deposit amount and tolerance.
+ */
+function quoteDepositFloor(input) {
+    return applySlippage(sharesForDeposit(input), input.slippageBps);
+}
+/**
+ * The `min_assets_out` to pass to `redeem_checked`: the quoted payout for
+ * `shares` **net of the withdrawal fee** — which is what `redeem_checked`
+ * compares against — lowered by `slippageBps`.
+ *
+ * Net rather than gross is the hinge of the whole guarantee, so it is pinned
+ * here rather than left to be re-derived. In
+ * `instructions/redeem.rs::handler_checked` the program computes the gross
+ * `assets`, subtracts `fees` — the `ceil_div` of `assets * withdrawal_fee`
+ * over `FEE_RATE_DENOMINATOR_VALUE` — and compares `min_assets_out` against
+ * that difference, which is the figure the caller actually receives.
+ * `Redeem::ceil_div` is `(n + d - 1) / d`, which is what
+ * {@link withdrawalFee} reproduces.
+ *
+ * Getting this wrong fails quietly in the dangerous direction. Quote against
+ * the gross payout and the floor sits a whole fee above what the program
+ * measures, so it binds early and reverts healthy redemptions. Net it twice —
+ * or drop the fee from a vault that charges one — and the floor sits below the
+ * real payout by the fee, leaving protection weaker than the advertised
+ * `slippageBps` instead of visibly broken. `withdrawal_fee` is capped just
+ * under 10% (`set_withdrawal_fee`), which bounds that silent gap.
+ *
+ * @param input - Vault state, shares to burn, fee and tolerance.
+ */
+function quoteRedeemFloor(input) {
+    const gross = assetsForRedeem(input);
+    const net = gross - withdrawalFee(gross, input.feePpm);
+    return applySlippage(net, input.slippageBps);
+}
+//# sourceMappingURL=pricing.js.map

package/lib/adapters/solana/types.d.ts

@@ -65,3 +65,48 @@ export interface ISolanaVaultStats {
     feeRecipient: string;
     lastUpdated: Date;
 }
+/**
+ * Slippage protection for {@link SolanaAdapter.vaultDeposit}.
+ *
+ * The SDK quotes the shares a deposit should mint from the vault's current
+ * state and passes a floor to the program's `deposit_checked` instruction,
+ * which reverts with `SlippageExceeded` if the share price moves past it
+ * before execution.
+ */
+export interface ISolanaDepositOptions {
+    /**
+     * Tolerance below the quoted shares, in basis points (`0` to `10000`).
+     * `0` demands the quote exactly. Ignored when `minSharesOut` is given.
+     * @defaultValue 50 (0.5%)
+     */
+    slippageBps?: number;
+    /**
+     * Explicit floor in raw share units, passed to `deposit_checked` as is.
+     * Skips the quote and the single snapshot read it needs. `0n` restores the
+     * unguarded behaviour of the plain `deposit` instruction.
+     *
+     * Must be a `bigint` in `0 .. 2^64-1`; anything else throws
+     * {@link AugustValidationError} before the transaction is built.
+     */
+    minSharesOut?: bigint;
+}
+/**
+ * Slippage protection for {@link SolanaAdapter.vaultRedeem}.
+ *
+ * The floor is measured **net of the withdrawal fee**, i.e. on what the wallet
+ * actually receives, matching the program's `redeem_checked`.
+ */
+export interface ISolanaRedeemOptions {
+    /**
+     * Tolerance below the quoted net payout, in basis points (`0` to `10000`).
+     * `0` demands the quote exactly. Ignored when `minAssetsOut` is given.
+     * @defaultValue 50 (0.5%)
+     */
+    slippageBps?: number;
+    /**
+     * Explicit floor in raw deposit-mint units, net of the withdrawal fee,
+     * passed to `redeem_checked` as is. Skips the quote. `0n` restores the
+     * unguarded behaviour of the plain `redeem` instruction.
+     */
+    minAssetsOut?: bigint;
+}

package/lib/adapters/solana/vault.actions.d.ts

@@ -1,6 +1,6 @@
 import { type web3 } from '@coral-xyz/anchor';
 import { type Connection, PublicKey, type Transaction } from '@solana/web3.js';
-import type { ISolanaConnectionOptions } from './types';
+import type { ISolanaConnectionOptions, ISolanaDepositOptions, ISolanaRedeemOptions } from './types';
 import type { SendTransactionOptions } from '@solana/wallet-adapter-base';
 /**
  * Extract a human- and machine-readable reason from a thrown Solana/Anchor
@@ -20,6 +20,21 @@ import type { SendTransactionOptions } from '@solana/wallet-adapter-base';
  * preserved on the wrapped error's `cause` and in telemetry for diagnosis.
  */
 export declare function describeSolanaError(e: unknown): string;
+/**
+ * A sentence to append when the program rejected the instruction for
+ * slippage, so the caller learns what to do rather than just what happened.
+ * Empty for every other error.
+ *
+ * Not merely a restatement of the program's reason string. Both checked
+ * instructions share error 6018, whose on-chain message is share-worded —
+ * "Received fewer shares than the caller's minimum" — so on a *redeem*, where
+ * the floor is denominated in assets, the program describes the wrong
+ * quantity. This sentence is what makes that case readable. The numeric code
+ * `describeSolanaError` renders alongside it is kept deliberately: it is the
+ * handle support and telemetry group on, and it survives a reword of the
+ * program's message.
+ */
+export declare function slippageHint(e: unknown): string;
 /**
  * Deposit funds into a Solana August vault and mint share tokens.
  *
@@ -36,16 +51,20 @@ export declare function describeSolanaError(e: unknown): string;
  *   non-refundable while the account stays open — on top of the network fee.
  *   Callers should ensure the wallet holds enough SOL for both before
  *   prompting the user to sign.
- * @remarks The on-chain `deposit` instruction has no `min_shares_out`
- *   parameter; slippage cannot be enforced on-chain until the program ships
- *   that argument.
+ * @remarks Sends `deposit_checked`, not `deposit`. Unless `options.minSharesOut`
+ *   is given, the vault state and share mint are read to quote the shares this
+ *   deposit should mint, and that quote lowered by `options.slippageBps`
+ *   (default {@link DEFAULT_SLIPPAGE_BPS}) is passed as the floor; the program
+ *   reverts with `SlippageExceeded` if execution would mint fewer.
  */
-export declare function handleSolanaDeposit({ provider, connection, network, vaultProgramId, vaultAddress, depositAmount, publicKey, idl, }: {
+export declare function handleSolanaDeposit({ provider, connection, network, vaultProgramId, vaultAddress, depositAmount, publicKey, idl, options, }: {
     vaultProgramId: PublicKey | string;
     vaultAddress?: PublicKey | string;
     idl: any;
     publicKey: PublicKey | string;
     depositAmount: number | bigint;
+    /** Slippage protection; see {@link ISolanaDepositOptions}. */
+    options?: ISolanaDepositOptions;
     /**
      * @deprecated Accepted and ignored. Share-account creation is now prepended
      * to the deposit instruction, so there is no longer a second transaction to
@@ -58,8 +77,12 @@ export declare function handleSolanaDeposit({ provider, connection, network, vau
  * Redeem vault shares back into the underlying mint on a Solana August vault.
  *
  * @param redeemShares  `bigint` is treated as raw share-token units;
- *   `number` is treated as a UI amount. See {@link handleSolanaDeposit} for
- *   the same caveat about the missing on-chain slippage guard.
+ *   `number` is treated as a UI amount.
+ * @remarks Sends `redeem_checked`, not `redeem`. Unless `options.minAssetsOut`
+ *   is given, the payout is quoted from the vault state and share supply the
+ *   handler already reads, **net of the withdrawal fee**, and that quote
+ *   lowered by `options.slippageBps` (default {@link DEFAULT_SLIPPAGE_BPS}) is
+ *   passed as the floor; the program reverts with `SlippageExceeded` below it.
  * @throws AugustValidationError on missing wallet/programId or invalid amount,
  *   or when the wallet holds fewer shares than `redeemShares`.
  * @throws AugustSDKError when a candidate token account's balance cannot be
@@ -71,12 +94,14 @@ export declare function handleSolanaDeposit({ provider, connection, network, vau
  *   non-refundable, on top of the network fee. Callers should ensure the
  *   wallet holds enough SOL for all of it before prompting the user to sign.
  */
-export declare function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultAddress, publicKey, redeemShares, idl, }: {
+export declare function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultAddress, publicKey, redeemShares, idl, options, }: {
     idl: any;
     vaultProgramId: PublicKey | string;
     vaultAddress?: PublicKey | string;
     publicKey: PublicKey | string;
     redeemShares: number | bigint;
+    /** Slippage protection; see {@link ISolanaRedeemOptions}. */
+    options?: ISolanaRedeemOptions;
     /**
      * @deprecated Accepted and ignored. Payout- and fee-recipient-account
      * creation is now prepended to the redeem instruction, so there is no longer