@augustdigital/sdk 9.9.0 → 9.10.1

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

@@ -0,0 +1,88 @@
+import { AnchorProvider } from '@coral-xyz/anchor';
+import { type Commitment, type ConfirmOptions, type Connection, type Signer, type Transaction, type TransactionSignature, type VersionedTransaction } from '@solana/web3.js';
+/** Delay between signature-status polls. */
+export declare const CONFIRM_POLL_INTERVAL_MS = 2000;
+/**
+ * Wall-clock backstop, also bounding every in-flight RPC read (web3.js sets no
+ * request timeout). Expiry is normally seen first: a blockhash lasts ~150
+ * blocks (~60s, longer when slots are skipped), and the finalized height it is checked against lags ~13s.
+ */
+export declare const CONFIRM_TIMEOUT_MS = 120000;
+/** Cap on a single RPC read, so a hung request counts as a failed read rather than eating the backstop. */
+export declare const CONFIRM_READ_TIMEOUT_MS = 10000;
+/** Ceiling for the doubling wait after polls whose reads failed. */
+export declare const CONFIRM_MAX_BACKOFF_MS = 16000;
+/**
+ * Wait for a sent transaction to reach `commitment`, over HTTP only.
+ *
+ * Anchor's `.rpc()` confirms by signature alone: a WebSocket
+ * `signatureSubscribe` raced against a fixed 30s (`confirmed`) or 60s
+ * (`finalized`) timer, so a transaction that landed is reported as failed
+ * whenever the notification is missed. This polls `getSignatureStatuses`, and
+ * ends on the blockhash's real expiry rather than a timer.
+ *
+ * It never reports that resubmitting is safe. An expired transaction that no
+ * lookup can find very likely never landed, but an RPC node with incomplete
+ * history cannot prove it, and a wrong "safe" duplicates a deposit or redeem.
+ *
+ * @param connection - Connection the transaction was sent through.
+ * @param signature - Signature returned by `sendRawTransaction`.
+ * @param lastValidBlockHeight - Expiry of the blockhash the signed
+ *   transaction carries, checked against the finalized block height. Omit
+ *   when unknown (or for a durable-nonce transaction): the wait then ends only
+ *   on confirmation, failure or `timeoutMs`.
+ * @param commitment - Level the transaction must reach.
+ * @param pollIntervalMs - Delay between polls; must be positive. Defaults to {@link CONFIRM_POLL_INTERVAL_MS}.
+ * @param timeoutMs - Wall-clock backstop; must be positive. Defaults to {@link CONFIRM_TIMEOUT_MS}.
+ * @param readTimeoutMs - Cap on each RPC read; must be positive. Defaults to {@link CONFIRM_READ_TIMEOUT_MS}.
+ * @returns `signature`, once its status reaches `commitment` with no error.
+ * @throws {@link SendTransactionError} when the transaction failed at
+ *   `commitment`, with logs attached for Anchor's `translateError`.
+ * @throws {@link AugustTransactionError} `TRANSACTION_UNCONFIRMED` when no
+ *   outcome was established: the blockhash expired with the transaction
+ *   nowhere to be found, or `timeoutMs` passed. `context.reason` is
+ *   `expired_not_found` (very likely never landed — still check before
+ *   resubmitting), `below_commitment` (seen landing without error),
+ *   `failed_below_commitment` (seen failing, not yet final), `rpc_failing`
+ *   (reads failed) or `not_visible`; `context` also carries the last status
+ *   seen and read counts, and `cause` the last failed read.
+ * @throws {@link AugustValidationError} for a non-positive or non-finite interval or timeout.
+ * @remarks **RPC cost.** The first poll runs right after sending. Per poll: one `getSignatureStatuses`, plus one
+ *   finalized `getBlockHeight` while the transaction is not visible (and, past
+ *   expiry, one history lookup). Typically 1–3 calls at `confirmed`, ~7–10 at
+ *   `finalized`, ~60 for an expiring transaction; the `timeoutMs` backstop
+ *   allows ~60 polls of 1–3 calls, fewer while reads fail: the wait doubles
+ *   after each poll with a failed read, up to {@link CONFIRM_MAX_BACKOFF_MS}. Failed reads are tolerated, so a transient RPC
+ *   error never misreports a landed transaction.
+ */
+export declare function confirmByBlockhash({ connection, signature, lastValidBlockHeight, commitment, pollIntervalMs, timeoutMs, readTimeoutMs, }: {
+    connection: Connection;
+    signature: TransactionSignature;
+    lastValidBlockHeight?: number;
+    commitment: Commitment;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    readTimeoutMs?: number;
+}): Promise<TransactionSignature>;
+/**
+ * `AnchorProvider` whose `sendAndConfirm` — what `program.methods…rpc()` calls —
+ * confirms with {@link confirmByBlockhash} instead of Anchor's signature-only
+ * WebSocket wait. Signing and Anchor's error translation are unchanged.
+ */
+export declare class BlockhashConfirmingProvider extends AnchorProvider {
+    /**
+     * Sign, send and confirm a transaction.
+     *
+     * @param tx - Transaction to send. Its blockhash (and fee payer, if unset)
+     *   are set here. A `VersionedTransaction` already carries a blockhash this
+     *   cannot learn the expiry of, so it takes Anchor's default path.
+     * @param signers - Extra signers besides the wallet.
+     * @param opts - Defaults to the provider's options.
+     * @returns The transaction signature.
+     * @throws See {@link confirmByBlockhash}; also whatever the wallet or
+     *   `sendRawTransaction` throws (user rejection, preflight failure).
+     * @remarks **RPC cost.** `getLatestBlockhash` + `sendRawTransaction`, then
+     *   the confirmation polls described on {@link confirmByBlockhash}.
+     */
+    sendAndConfirm(tx: Transaction | VersionedTransaction, signers?: Signer[], opts?: ConfirmOptions): Promise<TransactionSignature>;
+}

package/lib/adapters/solana/confirm.js

@@ -0,0 +1,291 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockhashConfirmingProvider = exports.CONFIRM_MAX_BACKOFF_MS = exports.CONFIRM_READ_TIMEOUT_MS = exports.CONFIRM_TIMEOUT_MS = exports.CONFIRM_POLL_INTERVAL_MS = void 0;
+exports.confirmByBlockhash = confirmByBlockhash;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const core_1 = require("../../core");
+const concurrency_1 = require("../../core/helpers/concurrency");
+/** Delay between signature-status polls. */
+exports.CONFIRM_POLL_INTERVAL_MS = 2_000;
+/**
+ * Wall-clock backstop, also bounding every in-flight RPC read (web3.js sets no
+ * request timeout). Expiry is normally seen first: a blockhash lasts ~150
+ * blocks (~60s, longer when slots are skipped), and the finalized height it is checked against lags ~13s.
+ */
+exports.CONFIRM_TIMEOUT_MS = 120_000;
+/** Cap on a single RPC read, so a hung request counts as a failed read rather than eating the backstop. */
+exports.CONFIRM_READ_TIMEOUT_MS = 10_000;
+/** Ceiling for the doubling wait after polls whose reads failed. */
+exports.CONFIRM_MAX_BACKOFF_MS = 16_000;
+const COMMITMENT_RANK = {
+    processed: 0,
+    recent: 0,
+    confirmed: 1,
+    single: 1,
+    singleGossip: 1,
+    finalized: 2,
+    max: 2,
+    root: 2,
+};
+/**
+ * The level a status has reached. Older RPCs omit `confirmationStatus`; the
+ * level is then inferred from `confirmations` as Agave's
+ * `TransactionStatus::satisfies_commitment` does: `null` is rooted, more than
+ * one confirmation is `confirmed`, anything else `processed`.
+ */
+function levelOf(status) {
+    if (status.confirmationStatus)
+        return status.confirmationStatus;
+    if (status.confirmations === null)
+        return 'finalized';
+    return status.confirmations > 1 ? 'confirmed' : 'processed';
+}
+function reaches(status, commitment) {
+    return COMMITMENT_RANK[levelOf(status)] >= COMMITMENT_RANK[commitment];
+}
+/**
+ * Wait for a sent transaction to reach `commitment`, over HTTP only.
+ *
+ * Anchor's `.rpc()` confirms by signature alone: a WebSocket
+ * `signatureSubscribe` raced against a fixed 30s (`confirmed`) or 60s
+ * (`finalized`) timer, so a transaction that landed is reported as failed
+ * whenever the notification is missed. This polls `getSignatureStatuses`, and
+ * ends on the blockhash's real expiry rather than a timer.
+ *
+ * It never reports that resubmitting is safe. An expired transaction that no
+ * lookup can find very likely never landed, but an RPC node with incomplete
+ * history cannot prove it, and a wrong "safe" duplicates a deposit or redeem.
+ *
+ * @param connection - Connection the transaction was sent through.
+ * @param signature - Signature returned by `sendRawTransaction`.
+ * @param lastValidBlockHeight - Expiry of the blockhash the signed
+ *   transaction carries, checked against the finalized block height. Omit
+ *   when unknown (or for a durable-nonce transaction): the wait then ends only
+ *   on confirmation, failure or `timeoutMs`.
+ * @param commitment - Level the transaction must reach.
+ * @param pollIntervalMs - Delay between polls; must be positive. Defaults to {@link CONFIRM_POLL_INTERVAL_MS}.
+ * @param timeoutMs - Wall-clock backstop; must be positive. Defaults to {@link CONFIRM_TIMEOUT_MS}.
+ * @param readTimeoutMs - Cap on each RPC read; must be positive. Defaults to {@link CONFIRM_READ_TIMEOUT_MS}.
+ * @returns `signature`, once its status reaches `commitment` with no error.
+ * @throws {@link SendTransactionError} when the transaction failed at
+ *   `commitment`, with logs attached for Anchor's `translateError`.
+ * @throws {@link AugustTransactionError} `TRANSACTION_UNCONFIRMED` when no
+ *   outcome was established: the blockhash expired with the transaction
+ *   nowhere to be found, or `timeoutMs` passed. `context.reason` is
+ *   `expired_not_found` (very likely never landed — still check before
+ *   resubmitting), `below_commitment` (seen landing without error),
+ *   `failed_below_commitment` (seen failing, not yet final), `rpc_failing`
+ *   (reads failed) or `not_visible`; `context` also carries the last status
+ *   seen and read counts, and `cause` the last failed read.
+ * @throws {@link AugustValidationError} for a non-positive or non-finite interval or timeout.
+ * @remarks **RPC cost.** The first poll runs right after sending. Per poll: one `getSignatureStatuses`, plus one
+ *   finalized `getBlockHeight` while the transaction is not visible (and, past
+ *   expiry, one history lookup). Typically 1–3 calls at `confirmed`, ~7–10 at
+ *   `finalized`, ~60 for an expiring transaction; the `timeoutMs` backstop
+ *   allows ~60 polls of 1–3 calls, fewer while reads fail: the wait doubles
+ *   after each poll with a failed read, up to {@link CONFIRM_MAX_BACKOFF_MS}. Failed reads are tolerated, so a transient RPC
+ *   error never misreports a landed transaction.
+ */
+async function confirmByBlockhash({ connection, signature, lastValidBlockHeight, commitment, pollIntervalMs = exports.CONFIRM_POLL_INTERVAL_MS, timeoutMs = exports.CONFIRM_TIMEOUT_MS, readTimeoutMs = exports.CONFIRM_READ_TIMEOUT_MS, }) {
+    for (const [name, value] of [
+        ['pollIntervalMs', pollIntervalMs],
+        ['timeoutMs', timeoutMs],
+        ['readTimeoutMs', readTimeoutMs],
+    ]) {
+        if (!Number.isFinite(value) || value <= 0)
+            throw new core_1.AugustValidationError('INVALID_INPUT', `confirmByBlockhash: ${name} must be a positive finite number, got ${value}.`);
+    }
+    const deadline = Date.now() + timeoutMs;
+    let reads = 0;
+    let failedReads = 0;
+    let lastReadError;
+    let lastSeen;
+    /** Finalized block height at which the transaction was found expired and absent. */
+    let expiredAt;
+    /** One RPC read; `undefined` when it failed or hung (outcome unknown). */
+    const read = async (call) => {
+        reads += 1;
+        const remaining = deadline - Date.now();
+        // Records whether the RPC itself rejected, so a timeout is told apart from
+        // a failure by which promise lost, not by reading the clock.
+        let rpcFailure;
+        const pending = call().catch((error) => {
+            rpcFailure = { error };
+            throw error;
+        });
+        try {
+            return await (0, concurrency_1.withTimeout)(pending, Math.min(readTimeoutMs, remaining), 'Solana RPC read');
+        }
+        catch (timeout) {
+            // The timer was the backstop's, not the per-read cap: not an RPC failure.
+            if (!rpcFailure && remaining < readTimeoutMs)
+                return undefined;
+            failedReads += 1;
+            lastReadError = rpcFailure ? rpcFailure.error : timeout;
+            return undefined;
+        }
+    };
+    const statusOf = (searchTransactionHistory = false) => read(() => connection
+        .getSignatureStatuses([signature], { searchTransactionHistory })
+        .then((r) => r.value[0]));
+    /**
+     * `true` once `status` is final at `commitment`; throws if it failed there.
+     * A failure seen below `commitment` is not final yet, as in Anchor.
+     */
+    const settled = async (status) => {
+        lastSeen = status;
+        if (!reaches(status, commitment))
+            return false;
+        if (!status.err)
+            return true;
+        const tx = await read(() => connection.getTransaction(signature, {
+            commitment: 'confirmed',
+            maxSupportedTransactionVersion: 0,
+        }));
+        // Keep `JSON.stringify(status.err)` in the message: without logs, Anchor's
+        // `ProgramError.parse` recovers the program error code from its
+        // `"Custom":N}`.
+        throw new web3_js_1.SendTransactionError({
+            action: 'send',
+            signature,
+            transactionMessage: `Transaction failed: ${JSON.stringify(status.err)}`,
+            logs: tx?.meta?.logMessages ?? undefined,
+        });
+    };
+    /** One poll: `true` once confirmed; throws on a definitive failure. */
+    const pollOnce = async () => {
+        // `undefined` = read failed (unknown); `null` = not visible to the RPC.
+        const status = await statusOf();
+        if (status)
+            return settled(status);
+        // Seen before but gone now (dropped fork): no longer evidence it landed.
+        if (status === null)
+            lastSeen = undefined;
+        if (status === undefined || lastValidBlockHeight === undefined)
+            return false;
+        // Finalized, whatever `commitment` is: a `processed`/`confirmed` height can
+        // belong to a fork that is later dropped while the transaction still lands
+        // on the surviving one. Past the finalized height, every fork is expired.
+        const height = await read(() => connection.getBlockHeight('finalized'));
+        if (height === undefined || height <= lastValidBlockHeight)
+            return false;
+        // Past expiry. Last look, including history, in case it landed between polls.
+        const final = await statusOf(true);
+        if (final)
+            return settled(final);
+        if (final === null)
+            expiredAt = height;
+        return false;
+    };
+    // Poll first: a transaction often lands within a second of sending. After a
+    // poll with a failed read, the wait doubles (up to the ceiling) so a failing
+    // RPC is not hit at full cadence; a clean poll restores the normal interval.
+    let backoff = 0;
+    for (;;) {
+        const failedBefore = failedReads;
+        if (await pollOnce())
+            return signature;
+        if (expiredAt !== undefined)
+            break;
+        backoff = failedReads > failedBefore ? backoff + 1 : 0;
+        const interval = Math.min(pollIntervalMs * 2 ** backoff, Math.max(pollIntervalMs, exports.CONFIRM_MAX_BACKOFF_MS));
+        const wait = Math.min(interval, deadline - Date.now());
+        if (wait <= 0)
+            break;
+        await new Promise((r) => setTimeout(r, wait));
+    }
+    const seconds = timeoutMs / 1000;
+    const seenAt = lastSeen ? levelOf(lastSeen) : null;
+    const reason = expiredAt !== undefined
+        ? 'expired_not_found'
+        : !lastSeen
+            ? failedReads > 0
+                ? 'rpc_failing'
+                : 'not_visible'
+            : lastSeen.err
+                ? 'failed_below_commitment'
+                : 'below_commitment';
+    const message = {
+        expired_not_found: `Transaction ${signature} was not found and its blockhash has expired (block height exceeded), ` +
+            'so it very likely never landed. This cannot be proven from the RPC; check the signature before resubmitting.',
+        below_commitment: `Transaction ${signature} landed without error (${seenAt}) but was not confirmed in ${seconds} seconds ` +
+            `at '${commitment}'. Do not resubmit; it is most likely to finalize.`,
+        failed_below_commitment: `Transaction ${signature} was seen failing (${seenAt}) but was not confirmed in ${seconds} seconds ` +
+            `at '${commitment}', so the failure is not final yet. Check the signature before resubmitting.`,
+        rpc_failing: undefined,
+        not_visible: undefined,
+    }[reason];
+    throw new core_1.AugustTransactionError(message ??
+        `Transaction ${signature} was not confirmed in ${seconds} seconds. ` +
+            'It is unknown if it succeeded or failed; check the signature before resubmitting.', signature, {
+        cause: expiredAt !== undefined
+            ? new web3_js_1.TransactionExpiredBlockheightExceededError(signature)
+            : lastReadError,
+        context: {
+            signature,
+            commitment,
+            reason,
+            ...(expiredAt !== undefined && {
+                lastValidBlockHeight,
+                blockHeight: expiredAt,
+            }),
+            lastSeenStatus: seenAt,
+            lastSeenErr: lastSeen?.err ?? null,
+            reads,
+            failedReads,
+        },
+    });
+}
+/**
+ * `AnchorProvider` whose `sendAndConfirm` — what `program.methods…rpc()` calls —
+ * confirms with {@link confirmByBlockhash} instead of Anchor's signature-only
+ * WebSocket wait. Signing and Anchor's error translation are unchanged.
+ */
+class BlockhashConfirmingProvider extends anchor_1.AnchorProvider {
+    /**
+     * Sign, send and confirm a transaction.
+     *
+     * @param tx - Transaction to send. Its blockhash (and fee payer, if unset)
+     *   are set here. A `VersionedTransaction` already carries a blockhash this
+     *   cannot learn the expiry of, so it takes Anchor's default path.
+     * @param signers - Extra signers besides the wallet.
+     * @param opts - Defaults to the provider's options.
+     * @returns The transaction signature.
+     * @throws See {@link confirmByBlockhash}; also whatever the wallet or
+     *   `sendRawTransaction` throws (user rejection, preflight failure).
+     * @remarks **RPC cost.** `getLatestBlockhash` + `sendRawTransaction`, then
+     *   the confirmation polls described on {@link confirmByBlockhash}.
+     */
+    async sendAndConfirm(tx, signers, opts = this.opts) {
+        if ('version' in tx)
+            return super.sendAndConfirm(tx, signers, opts);
+        const commitment = opts.commitment ?? this.connection.commitment ?? 'finalized';
+        const preflightCommitment = opts.preflightCommitment ?? commitment;
+        const { blockhash, lastValidBlockHeight } = await this.connection.getLatestBlockhash(preflightCommitment);
+        tx.feePayer = tx.feePayer ?? this.wallet.publicKey;
+        tx.recentBlockhash = blockhash;
+        for (const signer of signers ?? [])
+            tx.partialSign(signer);
+        const signed = await this.wallet.signTransaction(tx);
+        const signature = await this.connection.sendRawTransaction(signed.serialize(), {
+            skipPreflight: opts.skipPreflight,
+            preflightCommitment,
+            maxRetries: opts.maxRetries,
+            minContextSlot: opts.minContextSlot,
+        });
+        return confirmByBlockhash({
+            connection: this.connection,
+            signature,
+            // The expiry fetched here only bounds a tx that carries this blockhash.
+            // A wallet may re-stamp it when signing, and a durable-nonce tx
+            // serializes its nonce instead; either way it could still land.
+            lastValidBlockHeight: !signed.nonceInfo && signed.recentBlockhash === blockhash
+                ? lastValidBlockHeight
+                : undefined,
+            commitment,
+        });
+    }
+}
+exports.BlockhashConfirmingProvider = BlockhashConfirmingProvider;
+//# sourceMappingURL=confirm.js.map

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

@@ -25,7 +25,7 @@ export declare const Solana: {
         getProvider: ({ connection, publicKey, signTransaction, }: {
             publicKey: PublicKey;
             signTransaction: (<T extends Transaction | web3.VersionedTransaction>(transaction: T) => Promise<T>) | undefined;
-        } & import("./types").ISolanaConnectionOptions) => AnchorProvider;
+        } & import("./types").ISolanaConnectionOptions) => import("./confirm").BlockhashConfirmingProvider;
         getReadOnlyProvider: ({ connection }: import("./types").ISolanaConnectionOptions) => AnchorProvider;
         deriveShareMintPda: (vaultProgramId: PublicKey | string) => web3.PublicKey;
         deriveVaultStatePda: (vaultProgramId: PublicKey | string) => web3.PublicKey;

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

@@ -1,6 +1,7 @@
 import { AnchorProvider, BN, Program, type web3 } from '@coral-xyz/anchor';
 import { PublicKey, type ParsedAccountData, type Transaction } from '@solana/web3.js';
 import type { ISolanaConnectionOptions, ISolanaVaultState } from './types';
+import { BlockhashConfirmingProvider } from './confirm';
 declare function getExplorerLink({ signature, type, network, }: {
     signature: string;
     type: 'tx' | 'address' | 'token';
@@ -16,7 +17,7 @@ declare function getBestRpcEndpoint({ endpoint, network, connection, }: ISolanaC
 declare function getProvider({ connection, publicKey, signTransaction, }: {
     publicKey: PublicKey;
     signTransaction: (<T extends Transaction | web3.VersionedTransaction>(transaction: T) => Promise<T>) | undefined;
-} & ISolanaConnectionOptions): AnchorProvider;
+} & ISolanaConnectionOptions): BlockhashConfirmingProvider;
 declare function getReadOnlyProvider({ connection }: ISolanaConnectionOptions): AnchorProvider;
 declare function deriveVaultStatePda(vaultProgramId: PublicKey | string): web3.PublicKey;
 declare function deriveShareMintPda(vaultProgramId: PublicKey | string): web3.PublicKey;

package/lib/adapters/solana/utils.js

@@ -7,6 +7,7 @@ const anchor_1 = require("@coral-xyz/anchor");
 const web3_js_1 = require("@solana/web3.js");
 const ethers_1 = require("ethers");
 const constants_1 = require("./constants");
+const confirm_1 = require("./confirm");
 const core_1 = require("../../core");
 // ============================================================================
 // SOLANA UTILITIES
@@ -96,7 +97,8 @@ function getProvider({ connection, publicKey, signTransaction, }) {
     if (!publicKey || !signTransaction) {
         throw new core_1.AugustValidationError('INVALID_INPUT', 'Wallet not connected: publicKey and signTransaction are required for write operations');
     }
-    return new anchor_1.AnchorProvider(connection, {
+    // Anchor's own confirmation misreports landed txs as timed out; see confirm.ts.
+    return new confirm_1.BlockhashConfirmingProvider(connection, {
         publicKey,
         signTransaction,
         signAllTransactions: async (txs) => {

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

@@ -45,6 +45,9 @@ export declare function slippageHint(e: unknown): string;
  *   or when the wallet's deposit-mint balance is below `depositAmount`.
  * @throws AugustSDKError when a candidate token account's balance cannot be
  *   read, or wrapping any downstream failure (`cause` preserved).
+ * @throws AugustTransactionError (`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,
@@ -92,6 +95,9 @@ export declare function handleSolanaDeposit({ provider, connection, network, vau
  *   or when the wallet holds fewer shares than `redeemShares`.
  * @throws AugustSDKError when a candidate token account's balance cannot be
  *   read, or wrapping any downstream failure (`cause` preserved).
+ * @throws AugustTransactionError (`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

package/lib/adapters/solana/vault.actions.js

@@ -301,6 +301,9 @@ async function resolveUserTokenAccountPair({ connection, owner, mints, }) {
  *   or when the wallet's deposit-mint balance is below `depositAmount`.
  * @throws AugustSDKError when a candidate token account's balance cannot be
  *   read, or wrapping any downstream failure (`cause` preserved).
+ * @throws AugustTransactionError (`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,
@@ -547,6 +550,9 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
  *   or when the wallet holds fewer shares than `redeemShares`.
  * @throws AugustSDKError when a candidate token account's balance cannot be
  *   read, or wrapping any downstream failure (`cause` preserved).
+ * @throws AugustTransactionError (`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

package/lib/adapters/stellar/soroban.js

@@ -19,6 +19,7 @@ exports.queryContract = queryContract;
 exports.buildSorobanTx = buildSorobanTx;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const core_1 = require("../../core");
+const concurrency_1 = require("../../core/helpers/concurrency");
 const constants_1 = require("./constants");
 function createServer(rpcUrl) {
     return new stellar_sdk_1.rpc.Server(rpcUrl, {
@@ -149,17 +150,6 @@ function scrubErrorUrls(value, scrub, depth = 0, seen = new WeakSet()) {
     }
     return out;
 }
-/**
- * Race a promise against a timeout so a hung call can't block indefinitely. The
- * timer is always cleared, so a fast-resolving promise leaves nothing pending.
- */
-function withTimeout(promise, ms, label) {
-    let timer;
-    const timeout = new Promise((_resolve, reject) => {
-        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-    });
-    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
 /**
  * Return a Soroban RPC server backed by a healthy endpoint for `config`. Thin
  * wrapper over {@link resolveHealthyServer} for callers (e.g. submission) that
@@ -241,7 +231,7 @@ async function probeHealthyServer(rpcUrls, cacheKey) {
             firstConstructableUrl = url;
         }
         try {
-            const health = await withTimeout(server.getHealth(), HEALTH_PROBE_TIMEOUT_MS, 'getHealth');
+            const health = await (0, concurrency_1.withTimeout)(server.getHealth(), HEALTH_PROBE_TIMEOUT_MS, 'getHealth');
             if (health.status === 'healthy') {
                 healthyServerCache.set(cacheKey, {
                     server,
@@ -355,7 +345,7 @@ async function withEndpointFailover(config, method, operation, options = {}) {
     const rpcUrls = config.rpcUrls && config.rpcUrls.length > 0
         ? config.rpcUrls
         : [config.rpcUrl];
-    const runOn = (server) => withTimeout(operation(server), timeoutMs, `Soroban ${method}`);
+    const runOn = (server) => (0, concurrency_1.withTimeout)(operation(server), timeoutMs, `Soroban ${method}`);
     const cacheKey = rpcUrls.join('|');
     // Reduce every configured endpoint URL to protocol+host in anything surfaced
     // from here (logs, the thrown message, the chained cause). SDK errors embed the

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "9.9.0";
+export declare const SDK_VERSION = "9.10.1";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '9.9.0';
+exports.SDK_VERSION = '9.10.1';
 //# sourceMappingURL=version.js.map

package/lib/core/constants/core.d.ts

@@ -117,6 +117,7 @@ export declare const WEBSERVER_ENDPOINTS: {
             summary: (vaultAddress: IAddress) => string;
             withdrawals: (chain: string, vaultAddress: IAddress) => string;
             debank: (vaultAddress: IAddress) => string;
+            octav: (vaultAddress: IAddress) => string;
             userHistory: (vaultAddress: IAddress, wallet: IAddress) => string;
             archivedVaults: string;
         };

package/lib/core/constants/core.js

@@ -184,6 +184,7 @@ exports.WEBSERVER_ENDPOINTS = {
             summary: (vaultAddress) => `/tokenized_vault/vault_summary/${(0, ethers_1.getAddress)(vaultAddress)}`,
             withdrawals: (chain, vaultAddress) => `/withdrawals/${chain}/${(0, ethers_1.getAddress)(vaultAddress)}`,
             debank: (vaultAddress) => `/tokenized_vault/${(0, ethers_1.getAddress)(vaultAddress)}/debank`,
+            octav: (vaultAddress) => `/tokenized_vault/${subaccountSegment(vaultAddress)}/octav`,
             // Mongo-backed deposit/withdraw history for archived vaults whose
             // subgraph has been (or will be) retired. See fetchArchivedVaults.
             userHistory: (vaultAddress, wallet) => `/upshift/vault_history/${(0, ethers_1.getAddress)(vaultAddress)}?wallet=${(0, ethers_1.getAddress)(wallet)}`,

package/lib/core/errors/index.d.ts

@@ -15,7 +15,7 @@
  * ```
  */
 /** Stable error codes attached to SDK errors. */
-export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'HISTORY_UNAVAILABLE' | 'PRICE_UNAVAILABLE' | 'UNKNOWN';
+export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'TRANSACTION_UNCONFIRMED' | 'HISTORY_UNAVAILABLE' | 'PRICE_UNAVAILABLE' | 'UNKNOWN';
 /** Options accepted by every SDK error constructor. */
 export interface AugustErrorOptions {
     /** Original error preserved for stack-trace chaining. */
@@ -145,5 +145,33 @@ export declare class AugustPriceUnavailableError extends AugustSDKError {
      */
     constructor(message: string, options?: AugustErrorOptions);
 }
+/**
+ * A transaction was sent but its outcome could not be established
+ * (`TRANSACTION_UNCONFIRMED`). It may have landed: check {@link signature}
+ * before resubmitting, or a deposit or redeem can execute twice.
+ * `context.reason` says what was seen (e.g. `expired_not_found`: the blockhash
+ * expired and no lookup found it, so it very likely never landed).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.solana.vaultDeposit(programId, idl, wallet, amount, undefined, vault);
+ * } catch (err) {
+ *   if (err instanceof AugustTransactionError) showPending(err.signature);
+ *   else throw err;
+ * }
+ * ```
+ */
+export declare class AugustTransactionError extends AugustSDKError {
+    /** Signature of the transaction that was sent. */
+    readonly signature: string;
+    /**
+     * @param message - Human-readable description, naming the signature.
+     * @param signature - Signature of the transaction that was sent.
+     * @param options - Standard SDK error options.
+     */
+    constructor(message: string, signature: string, options?: AugustErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 export declare function isAugustSDKError(err: unknown): err is AugustSDKError;

package/lib/core/errors/index.js

@@ -16,7 +16,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AugustPriceUnavailableError = exports.AugustHistoryUnavailableError = exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
+exports.AugustTransactionError = exports.AugustPriceUnavailableError = exports.AugustHistoryUnavailableError = exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
 exports.isAugustSDKError = isAugustSDKError;
 /** Base class for all SDK errors. */
 class AugustSDKError extends Error {
@@ -212,6 +212,41 @@ class AugustPriceUnavailableError extends AugustSDKError {
     }
 }
 exports.AugustPriceUnavailableError = AugustPriceUnavailableError;
+/**
+ * A transaction was sent but its outcome could not be established
+ * (`TRANSACTION_UNCONFIRMED`). It may have landed: check {@link signature}
+ * before resubmitting, or a deposit or redeem can execute twice.
+ * `context.reason` says what was seen (e.g. `expired_not_found`: the blockhash
+ * expired and no lookup found it, so it very likely never landed).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.solana.vaultDeposit(programId, idl, wallet, amount, undefined, vault);
+ * } catch (err) {
+ *   if (err instanceof AugustTransactionError) showPending(err.signature);
+ *   else throw err;
+ * }
+ * ```
+ */
+class AugustTransactionError extends AugustSDKError {
+    /** Signature of the transaction that was sent. */
+    signature;
+    /**
+     * @param message - Human-readable description, naming the signature.
+     * @param signature - Signature of the transaction that was sent.
+     * @param options - Standard SDK error options.
+     */
+    constructor(message, signature, options) {
+        super('TRANSACTION_UNCONFIRMED', message, options);
+        this.name = 'AugustTransactionError';
+        this.signature = signature;
+    }
+    toJSON() {
+        return { ...super.toJSON(), signature: this.signature };
+    }
+}
+exports.AugustTransactionError = AugustTransactionError;
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 function isAugustSDKError(err) {
     return (err instanceof AugustSDKError ||