@upshiftfinance/sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,140 @@
+import { type web3 } from '@coral-xyz/anchor';
+import { type Connection, PublicKey, type Transaction } from '@solana/web3.js';
+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
+ * error.
+ *
+ * Anchor's {@link https://github.com/coral-xyz/anchor `ProgramError`} calls
+ * `super()` with no argument, so its `.message` is the empty string by
+ * construction — the real reason lives on `.msg`/`.code` (and `.toString()`).
+ * `AnchorError` puts it on `.error.errorMessage` / `.error.errorCode.number`.
+ * Reading `.message` directly (as this file used to) therefore rendered
+ * `"Solana deposit failed: "` for every recognized on-chain revert — dropping
+ * the numeric code the team needs to tell "Vault is paused" from
+ * "Insufficient amount" from an account-constraint violation.
+ *
+ * When no reason can be extracted, returns an actionable, user-facing fallback
+ * rather than an "unknown error" admission — the raw throwable is still
+ * 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;
+/**
+ * Validate a caller-supplied slippage floor before it reaches Anchor's `u64`
+ * encoder.
+ *
+ * Anchor serializes a `BN` to `u64` via `toArrayLike`, which writes the
+ * magnitude and drops the sign — a `-1n` floor would reach the program as a
+ * floor of `1`, inverting the caller's intent instead of failing. Values above
+ * `u64` fare no better: they surface as an untyped "byte array longer than
+ * desired length" from inside the encoder, naming nothing the caller passed.
+ * Both are caught here, at the public-API boundary.
+ *
+ * @param value - The caller's `minSharesOut` / `minAssetsOut`, in raw base units.
+ * @param label - Option name, quoted in the error.
+ * @returns `value`, once known to fit an unsigned 64-bit integer.
+ * @throws {@link UpshiftValidationError} when it is not a `bigint` in `0 .. 2^64-1`.
+ */
+export declare function validateExplicitFloor(value: bigint, label: string): bigint;
+/**
+ * Deposit funds into a Solana Upshift vault and mint share tokens.
+ *
+ * @param depositAmount  `bigint` is treated as raw on-chain units (preferred
+ *   — no JS-float round-trip). `number` is treated as a UI amount and
+ *   scaled by the deposit mint's decimals via {@link uiAmountToRawBn}.
+ * @throws UpshiftValidationError on missing wallet/programId or invalid amount,
+ *   or when the wallet's deposit-mint balance is below `depositAmount`.
+ * @throws UpshiftSDKError when a candidate token account's balance cannot be
+ *   read, or wrapping any downstream failure (`cause` preserved).
+ * @throws UpshiftTransactionError (`TRANSACTION_UNCONFIRMED`) when the
+ *   transaction was sent but its outcome could not be established; check
+ *   `signature` before resubmitting.
+ * @remarks **Side effects.** Submits exactly one transaction, signed by the
+ *   provider's wallet. When the wallet has no share account, that transaction
+ *   also creates one, and `publicKey` pays its rent — roughly 0.00204 SOL,
+ *   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 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. An `idl`
+ *   that predates `deposit_checked` gets the plain `deposit` with no floor,
+ *   unless `options` asks for one — then it throws {@link UpshiftValidationError}.
+ */
+export declare function handleSolanaDeposit({ provider, connection, 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
+     * send. Kept so existing callers keep compiling; will be removed in the next
+     * major.
+     */
+    sendTransaction?: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>;
+} & ISolanaConnectionOptions): Promise<any>;
+/**
+ * Redeem vault shares back into the underlying mint on a Solana Upshift vault.
+ *
+ * @param redeemShares  `bigint` is treated as raw share-token units;
+ *   `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.
+ *   An `idl` that predates `redeem_checked` gets the plain `redeem` with no
+ *   floor, unless `options` asks for one — then it throws
+ *   {@link UpshiftValidationError}.
+ * @throws UpshiftValidationError on missing wallet/programId or invalid amount,
+ *   or when the wallet holds fewer shares than `redeemShares`.
+ * @throws UpshiftSDKError when a candidate token account's balance cannot be
+ *   read, or wrapping any downstream failure (`cause` preserved).
+ * @throws UpshiftTransactionError (`TRANSACTION_UNCONFIRMED`) when the
+ *   transaction was sent but its outcome could not be established; check
+ *   `signature` before resubmitting.
+ * @remarks **Side effects.** Submits exactly one transaction, signed by the
+ *   provider's wallet. That transaction also creates the payout account when
+ *   the wallet has none, and the vault's fee-recipient account when *it* has
+ *   none — `publicKey` pays rent for both, roughly 0.00204 SOL each and
+ *   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, 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
+     * a second transaction to send. Kept so existing callers keep compiling;
+     * will be removed in the next major.
+     */
+    sendTransaction?: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>;
+} & ISolanaConnectionOptions): Promise<any>;