Document @solana/transaction-confirmation with TypeDoc

Author: steveluscher

Diff for: packages/transaction-confirmation/README.md

@@ -135,7 +135,7 @@ try {
 
 ### `waitForRecentTransactionConfirmation()`
 
-Supply your own confirmation implementations to this function to create a custom nonce transaction confirmation strategy.
+Supply your own confirmation implementations to this function to create a custom confirmation strategy for recently-landed transactions.
 
 ```ts
 import { waitForRecentTransactionConfirmation } from '@solana/transaction-confirmation';

Diff for: packages/transaction-confirmation/src/confirmation-strategy-blockheight.ts

@@ -6,7 +6,16 @@ import type { Commitment } from '@solana/rpc-types';
 
 type GetBlockHeightExceedencePromiseFn = (config: {
     abortSignal: AbortSignal;
+    /**
+     * Fetch the block height as of the highest slot that has reached this level of commitment.
+     *
+     * @defaultValue Whichever default is applied by the underlying {@link RpcApi} in use. For
+     * example, when using an API created by a `createSolanaRpc*()` helper, the default commitment
+     * is `"confirmed"` unless configured otherwise. Unmitigated by an API layer on the client, the
+     * default commitment applied by the server is `"finalized"`.
+     */
     commitment?: Commitment;
+    /** The block height after which to reject the promise */
     lastValidBlockHeight: bigint;
 }) => Promise<void>;
 
@@ -15,6 +24,40 @@ type CreateBlockHeightExceedencePromiseFactoryyConfig<TCluster> = {
     rpcSubscriptions: RpcSubscriptions<SlotNotificationsApi> & { '~cluster'?: TCluster };
 };
 
+/**
+ * Creates a promise that throws when the network progresses past the block height after which the
+ * supplied blockhash is considered expired for use as a transaction lifetime specifier.
+ *
+ * When a transaction's lifetime is tied to a blockhash, that transaction can be landed on the
+ * network until that blockhash expires. All blockhashes have a block height after which they are
+ * considered to have expired.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import { isSolanaError, SolanaError } from '@solana/errors';
+ * import { createBlockHeightExceedencePromiseFactory } from '@solana/transaction-confirmation';
+ *
+ * const getBlockHeightExceedencePromise = createBlockHeightExceedencePromiseFactory({
+ *     rpc,
+ *     rpcSubscriptions,
+ * });
+ * try {
+ *     await getBlockHeightExceedencePromise({ lastValidBlockHeight });
+ * } catch (e) {
+ *     if (isSolanaError(e, SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED)) {
+ *         console.error(
+ *             `The block height of the network has exceeded ${e.context.lastValidBlockHeight}. ` +
+ *                 `It is now ${e.context.currentBlockHeight}`,
+ *         );
+ *         // Re-sign and retry the transaction.
+ *         return;
+ *     }
+ *     throw e;
+ * }
+ * ```
+ */
 export function createBlockHeightExceedencePromiseFactory({
     rpc,
     rpcSubscriptions,

Diff for: packages/transaction-confirmation/src/confirmation-strategy-nonce.ts

@@ -10,8 +10,17 @@ import { Nonce } from '@solana/transaction-messages';
 
 type GetNonceInvalidationPromiseFn = (config: {
     abortSignal: AbortSignal;
+    /**
+     * Fetch the nonce account details as of the highest slot that has reached this level of
+     * commitment.
+     */
     commitment: Commitment;
+    /**
+     * The value of the nonce that we would expect to see in the nonce account in order for any
+     * transaction with that nonce-based lifetime to be considered valid.
+     */
     currentNonceValue: Nonce;
+    /** The address of the account in which the currently-valid nonce value is stored */
     nonceAccountAddress: Address;
 }) => Promise<void>;
 
@@ -26,6 +35,40 @@ const NONCE_VALUE_OFFSET =
     32; // nonce authority(pubkey)
 // Then comes the nonce value.
 
+/**
+ * Creates a promise that throws when the value stored in a nonce account is not the expected one.
+ *
+ * When a transaction's lifetime is tied to the value stored in a nonce account, that transaction
+ * can be landed on the network until the nonce is advanced to a new value.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import { isSolanaError, SolanaError } from '@solana/errors';
+ * import { createNonceInvalidationPromiseFactory } from '@solana/transaction-confirmation';
+ *
+ * const getNonceInvalidationPromise = createNonceInvalidationPromiseFactory({
+ *     rpc,
+ *     rpcSubscriptions,
+ * });
+ * try {
+ *     await getNonceInvalidationPromise({
+ *         currentNonceValue,
+ *         nonceAccountAddress,
+ *     });
+ * } catch (e) {
+ *     if (isSolanaError(e, SOLANA_ERROR__NONCE_INVALID)) {
+ *         console.error(`The nonce has advanced to ${e.context.actualNonceValue}`);
+ *         // Re-sign and retry the transaction.
+ *         return;
+ *     } else if (isSolanaError(e, SOLANA_ERROR__NONCE_ACCOUNT_NOT_FOUND)) {
+ *         console.error(`No nonce account was found at ${nonceAccountAddress}`);
+ *     }
+ *     throw e;
+ * }
+ * ```
+ */
 export function createNonceInvalidationPromiseFactory({
     rpc,
     rpcSubscriptions,

Diff for: packages/transaction-confirmation/src/confirmation-strategy-recent-signature.ts

@@ -8,7 +8,15 @@ import { type Commitment, commitmentComparator } from '@solana/rpc-types';
 
 type GetRecentSignatureConfirmationPromiseFn = (config: {
     abortSignal: AbortSignal;
+    /**
+     * The level of commitment the transaction must have achieved in order for the promise to
+     * resolve.
+     */
     commitment: Commitment;
+    /**
+     * A 64 byte Ed25519 signature, encoded as a base-58 string, that uniquely identifies a
+     * transaction by virtue of being the first or only signature in its list of signatures.
+     */
     signature: Signature;
 }) => Promise<void>;
 
@@ -17,6 +25,38 @@ type CreateRecentSignatureConfirmationPromiseFactoryConfig<TCluster> = {
     rpcSubscriptions: RpcSubscriptions<SignatureNotificationsApi> & { '~cluster'?: TCluster };
 };
 
+/**
+ * Creates a promise that resolves when a recently-landed transaction achieves the target
+ * confirmation commitment, and throws when the transaction fails with an error.
+ *
+ * The status of recently-landed transactions is available in the network's status cache. This
+ * confirmation strategy will only yield a result if the signature is still in the status cache. To
+ * fetch the status of transactions older than those available in the status cache, use the
+ * {@link GetSignatureStatusesApi.getSignatureStatuses} method setting the
+ * `searchTransactionHistory` configuration param to `true`.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import { createRecentSignatureConfirmationPromiseFactory } from '@solana/transaction-confirmation';
+ *
+ * const getRecentSignatureConfirmationPromise = createRecentSignatureConfirmationPromiseFactory({
+ *     rpc,
+ *     rpcSubscriptions,
+ * });
+ * try {
+ *     await getRecentSignatureConfirmationPromise({
+ *         commitment,
+ *         signature,
+ *     });
+ *     console.log(`The transaction with signature \`${signature}\` has achieved a commitment level of \`${commitment}\``);
+ * } catch (e) {
+ *     console.error(`The transaction with signature \`${signature}\` failed`, e.cause);
+ *     throw e;
+ * }
+ * ```
+ */
 export function createRecentSignatureConfirmationPromiseFactory({
     rpc,
     rpcSubscriptions,

Diff for: packages/transaction-confirmation/src/confirmation-strategy-timeout.ts

@@ -2,9 +2,35 @@ import type { Commitment } from '@solana/rpc-types';
 
 type Config = Readonly<{
     abortSignal: AbortSignal;
+    /**
+     * The timeout promise will throw after 30 seconds when the commitment is `processed`, and 60
+     * seconds otherwise.
+     */
     commitment: Commitment;
 }>;
 
+/**
+ * When no other heuristic exists to infer that a transaction has expired, you can use this promise
+ * factory with a commitment level. It throws after 30 seconds when the commitment is `processed`,
+ * and 60 seconds otherwise. You would typically race this with another confirmation strategy.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import { safeRace } from '@solana/promises';
+ * import { getTimeoutPromise } from '@solana/transaction-confirmation';
+ *
+ * try {
+ *     await safeRace([getCustomTransactionConfirmationPromise(/* ... *\/), getTimeoutPromise({ commitment })]);
+ * } catch (e) {
+ *     if (e instanceof DOMException && e.name === 'TimeoutError') {
+ *         console.log('Could not confirm transaction after a timeout');
+ *     }
+ *     throw e;
+ * }
+ * ```
+ */
 export async function getTimeoutPromise({ abortSignal: callerAbortSignal, commitment }: Config) {
     return await new Promise((_, reject) => {
         const handleAbort = (e: AbortSignalEventMap['abort']) => {

Diff for: packages/transaction-confirmation/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * This package contains utilities for confirming transactions and for building your own transaction
+ * confirmation strategies.
+ *
+ * @packageDocumentation
+ */
 export * from './confirmation-strategy-blockheight';
 export * from './confirmation-strategy-nonce';
 export * from './confirmation-strategy-recent-signature';

Diff for: packages/transaction-confirmation/src/waiters.ts

@@ -25,9 +25,35 @@ interface WaitForRecentTransactionWithBlockhashLifetimeConfirmationConfig
 interface WaitForRecentTransactionWithTimeBasedLifetimeConfirmationConfig
     extends BaseTransactionConfirmationStrategyConfig {
     getTimeoutPromise: typeof getTimeoutPromise;
+    /**
+     * A 64 byte Ed25519 signature, encoded as a base-58 string, that uniquely identifies a
+     * transaction by virtue of being the first or only signature in its list of signatures.
+     */
     signature: Signature;
 }
 
+/**
+ * Supply your own confirmation implementations to this function to create a custom nonce
+ * transaction confirmation strategy.
+ *
+ * @example
+ * ```ts
+ * import { waitForDurableNonceTransactionConfirmation } from '@solana/transaction-confirmation';
+ *
+ * try {
+ *     await waitForDurableNonceTransactionConfirmation({
+ *         getNonceInvalidationPromise({ abortSignal, commitment, currentNonceValue, nonceAccountAddress }) {
+ *             // Return a promise that rejects when a nonce becomes invalid.
+ *         },
+ *         getRecentSignatureConfirmationPromise({ abortSignal, commitment, signature }) {
+ *             // Return a promise that resolves when a transaction achieves confirmation
+ *         },
+ *     });
+ * } catch (e) {
+ *     // Handle errors.
+ * }
+ * ```
+ */
 export async function waitForDurableNonceTransactionConfirmation(
     config: WaitForDurableNonceTransactionConfirmationConfig,
 ): Promise<void> {
@@ -47,6 +73,28 @@ export async function waitForDurableNonceTransactionConfirmation(
     );
 }
 
+/**
+ * Supply your own confirmation implementations to this function to create a custom confirmation
+ * strategy for recently-landed transactions.
+ *
+ * @example
+ * ```ts
+ * import { waitForRecentTransactionConfirmation } from '@solana/transaction-confirmation';
+ *
+ * try {
+ *     await waitForRecentTransactionConfirmation({
+ *         getBlockHeightExceedencePromise({ abortSignal, commitment, lastValidBlockHeight }) {
+ *             // Return a promise that rejects when the blockhash's block height has been exceeded
+ *         },
+ *         getRecentSignatureConfirmationPromise({ abortSignal, commitment, signature }) {
+ *             // Return a promise that resolves when a transaction achieves confirmation
+ *         },
+ *     });
+ * } catch (e) {
+ *     // Handle errors.
+ * }
+ * ```
+ */
 export async function waitForRecentTransactionConfirmation(
     config: WaitForRecentTransactionWithBlockhashLifetimeConfirmationConfig,
 ): Promise<void> {