@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/adapters/solana/pricing.js

@@ -0,0 +1,239 @@
+"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.hasSharePrice = hasSharePrice;
+exports.sharesForDeposit = sharesForDeposit;
+exports.assetsForRedeem = assetsForRedeem;
+exports.withdrawalFee = withdrawalFee;
+exports.validateSlippageBps = validateSlippageBps;
+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 UpshiftSDKError 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.UpshiftSDKError('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 UpshiftSDKError 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'));
+}
+/**
+ * Whether the vault has a share price. Mirrors `SharePriceUndefined`:
+ * outstanding shares against no assets has no price in either direction.
+ */
+function hasSharePrice(supply, totalAssets) {
+    return totalAssets !== 0n || supply === 0n;
+}
+function requireSharePrice(supply, totalAssets) {
+    // The program would refuse the instruction.
+    if (!hasSharePrice(supply, totalAssets)) {
+        throw new core_1.UpshiftValidationError('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 UpshiftValidationError 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 UpshiftValidationError 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;
+}
+/**
+ * Refuse a `slippageBps` that is not an integer in `0 .. 10_000`.
+ *
+ * @throws UpshiftValidationError when it is out of range or not an integer.
+ */
+function validateSlippageBps(slippageBps) {
+    if (!Number.isInteger(slippageBps) ||
+        slippageBps < 0 ||
+        slippageBps > Number(BPS_DENOMINATOR)) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `slippageBps must be an integer between 0 and 10000, got ${slippageBps}.`);
+    }
+}
+/**
+ * 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 UpshiftValidationError when `slippageBps` is out of range or not an integer.
+ */
+function applySlippage(expected, slippageBps) {
+    validateSlippageBps(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/queue-hints.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Remediation hints for withdrawal-queue errors.
+ *
+ * Leaf module (depends on nothing in the adapter) so both `queue.actions.ts`
+ * and `vault.actions.ts` can use it: `queue.actions.ts` already imports from
+ * `vault.actions.ts`, so defining the hints in either file and importing them
+ * from the other would create a circular dependency.
+ */
+/**
+ * The sentence to append for a queue error the caller can act on.
+ *
+ * @param e - The error thrown by an Anchor `.rpc()` call (any value).
+ * @returns A sentence starting with a space, or `''` when the error is not a
+ *   queue error with a known remedy.
+ */
+export declare function queueHint(e: unknown): string;
+/**
+ * The hint for a direct vault redeem refused because the vault routes exits
+ * through its withdrawal queue (`WithdrawalQueueRequired`, vault error 6021).
+ *
+ * Only this one queue hint applies to a direct redeem: the others (cooldown,
+ * claim liquidity, ...) describe the claim of a queued request, and e.g. the
+ * `NotEnoughLiquidity` claim hint ("the request stays pending") would be wrong
+ * for a direct redeem, which leaves no request behind.
+ *
+ * @param e - The error thrown by the redeem `.rpc()` call (any value).
+ * @returns The queue-redeem instruction sentence (leading space), or `''`.
+ */
+export declare function redeemQueueHint(e: unknown): string;

package/lib/adapters/solana/queue-hints.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Remediation hints for withdrawal-queue errors.
+ *
+ * Leaf module (depends on nothing in the adapter) so both `queue.actions.ts`
+ * and `vault.actions.ts` can use it: `queue.actions.ts` already imports from
+ * `vault.actions.ts`, so defining the hints in either file and importing them
+ * from the other would create a circular dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queueHint = queueHint;
+exports.redeemQueueHint = redeemQueueHint;
+/**
+ * What to do next, for the queue errors a caller can act on. Matched by the
+ * error's name, not its number: both programs number their errors from 6000,
+ * so a bare code is ambiguous between them.
+ */
+const QUEUE_HINTS = {
+    WithdrawalQueueRequired: ' This vault redeems through its withdrawal queue: request with `vaultRequestRedeem`, then claim with `vaultRedeem` and `options.request`.',
+    CooldownNotElapsed: ' The request is still in its cooldown; claim it once its eligibility time has passed.',
+    RequestExpired: ' The request is past its fulfillment window and can no longer be claimed; cancel it to get the shares back.',
+    FinalizerNotAllowed: ' Only the holder or the finalizer the request names may claim it.',
+    StaleRequestSequence: ' The request changed since it was read (it was claimed or cancelled, and possibly recreated); read it again.',
+    QueueNotActiveOnVault: ' The vault is no longer attached to this queue, so it takes no new requests; redeem directly instead.',
+    NotRequestOwner: ' Only the holder who made the request may cancel it.',
+    PayoutBelowFloor: ' The shares are worth less than the floor set when the request was made; claim once the price recovers, or cancel and request again with a lower `minAssetsOut` or higher `slippageBps`.',
+    // Raised by the vault inside the claim's CPI; only claims reach this map.
+    NotEnoughLiquidity: " The vault's liquid reserve cannot cover this payout yet; the request stays pending, so claim it again later.",
+};
+/**
+ * The sentence to append for a queue error the caller can act on.
+ *
+ * @param e - The error thrown by an Anchor `.rpc()` call (any value).
+ * @returns A sentence starting with a space, or `''` when the error is not a
+ *   queue error with a known remedy.
+ */
+function queueHint(e) {
+    const name = e
+        ?.error?.errorCode?.code;
+    return (name && QUEUE_HINTS[name]) || '';
+}
+/**
+ * The hint for a direct vault redeem refused because the vault routes exits
+ * through its withdrawal queue (`WithdrawalQueueRequired`, vault error 6021).
+ *
+ * Only this one queue hint applies to a direct redeem: the others (cooldown,
+ * claim liquidity, ...) describe the claim of a queued request, and e.g. the
+ * `NotEnoughLiquidity` claim hint ("the request stays pending") would be wrong
+ * for a direct redeem, which leaves no request behind.
+ *
+ * @param e - The error thrown by the redeem `.rpc()` call (any value).
+ * @returns The queue-redeem instruction sentence (leading space), or `''`.
+ */
+function redeemQueueHint(e) {
+    const name = e
+        ?.error?.errorCode?.code;
+    return name === 'WithdrawalQueueRequired' ? queueHint(e) : '';
+}
+//# sourceMappingURL=queue-hints.js.map

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

@@ -0,0 +1,97 @@
+/**
+ * Write paths for the august_withdrawal_queue program: request a withdrawal,
+ * claim (finalize) a ready one, cancel a pending one.
+ *
+ * Built like the vault's deposit and redeem handlers (`vault.actions.ts`):
+ * every check the SDK can make runs before the wallet is asked to sign, every
+ * account the transaction needs is created inside it with an idempotent
+ * instruction, and failures surface as `UpshiftValidationError` (bad input or
+ * state the caller can fix) or `UpshiftSDKError` (the transaction failed, with
+ * the program's reason and the numeric code).
+ */
+import { type AnchorProvider } from '@coral-xyz/anchor';
+import { type Connection, PublicKey } from '@solana/web3.js';
+import type { ISolanaCancelRedeemRequestParams, ISolanaRequestRedeemParams, ISolanaRequestRedeemResult } from './types';
+export { queueHint } from './queue-hints';
+/** The request PDA: `["withdrawal_request", queue, owner, request_id as u64 LE]`. */
+export declare function deriveWithdrawalRequestPda(queue: PublicKey, owner: PublicKey, requestId: bigint, queueProgramId: PublicKey): PublicKey;
+/**
+ * Escrow shares in a withdrawal request on a vault with a queue attached.
+ *
+ * Reads the vault state and queue in one call, checks the gate points at the
+ * queue, and submits `request_withdrawal` from the holder's share account. The
+ * recipient's deposit-token account is created in the same transaction when it
+ * has none. Unless `minAssetsOut` is given, the request's floor is the current
+ * net quote lowered by `slippageBps`, the floor `vaultRedeem` would use.
+ *
+ * RPC: one `getMultipleAccountsInfo` (vault state and queue), one
+ * `getAccountInfo` for the share mint (decimals for a UI `amount`, supply for
+ * the default floor) unless `amount` is raw and `minAssetsOut` is given, one
+ * `getParsedTokenAccountsByOwner` for the share account, and one more read for
+ * the payout account (the holder's, or another recipient's ATA, which may be
+ * off-curve), then the send.
+ *
+ * @returns The signature, the new request's address and its id.
+ * @throws UpshiftValidationError for bad input, a vault without an attached
+ *   queue, a frozen account or too few shares, all before signing.
+ * @throws UpshiftSDKError when the transaction fails.
+ */
+export declare function handleSolanaRequestRedeem({ provider, connection, queueProgramId, params, }: {
+    provider: AnchorProvider;
+    connection: Connection;
+    queueProgramId: PublicKey;
+    params: ISolanaRequestRedeemParams;
+}): Promise<ISolanaRequestRedeemResult>;
+/**
+ * Claim a request whose cooldown has run: `finalize_withdrawal`, which redeems
+ * the escrowed shares through the vault and pays the request's recipient.
+ *
+ * Anyone the request permits may claim it: the holder always, and anyone else
+ * unless it names a finalizer, in which case only that key. It is refused here,
+ * before signing, when the caller is not permitted, the cooldown has not run,
+ * or the window has closed; the wall clock stands in for the chain's, so at the
+ * boundary the program may still disagree by a slot. The vault's fee-recipient
+ * account is created in the same transaction when it has none, and so is the
+ * request's payout account when it is the holder's own ATA and has been closed
+ * since; any other closed or a frozen payout account is refused before
+ * signing, since the claim could only fail.
+ *
+ * RPC: three reads in turn, each address coming from the account before it
+ * (the request, its queue, then the queue's vault together with the payout
+ * account), then the send.
+ *
+ * @throws UpshiftValidationError for a missing request or one the caller cannot
+ *   claim yet, before signing.
+ * @throws UpshiftSDKError when the transaction fails, e.g. `NotEnoughLiquidity`
+ *   while the vault's reserve is deployed; the request stays pending.
+ */
+export declare function handleSolanaClaimRedeem({ provider, connection, vaultProgramId, queueProgramId, wallet, request: requestAddress, nowSeconds, }: {
+    provider: AnchorProvider;
+    connection: Connection;
+    vaultProgramId: PublicKey;
+    queueProgramId: PublicKey;
+    wallet: PublicKey | string;
+    request: PublicKey | string;
+    /** Unix seconds to check eligibility against; defaults to now. */
+    nowSeconds?: number;
+}): Promise<string>;
+/**
+ * Cancel a pending request: `cancel_withdrawal` returns its shares to the
+ * holder's share account (created in the same transaction when they closed
+ * theirs) and closes the request, refunding its rent. Allowed at any time
+ * while the request exists, cooldown or not, expired or not, paused or not.
+ *
+ * RPC: two reads in turn (the request, then its queue), one
+ * `getParsedTokenAccountsByOwner`, then the send.
+ *
+ * @returns The confirmed transaction's signature.
+ * @throws UpshiftValidationError for a missing request or one `wallet` did not
+ *   make, before signing.
+ * @throws UpshiftSDKError when the transaction fails.
+ */
+export declare function handleSolanaCancelRedeemRequest({ provider, connection, queueProgramId, params, }: {
+    provider: AnchorProvider;
+    connection: Connection;
+    queueProgramId: PublicKey;
+    params: ISolanaCancelRedeemRequestParams;
+}): Promise<string>;