Add getSignatureStatuses to RpcInterface

.changeset/stale-bugs-remain.md

@@ -0,0 +1,6 @@
+---
+'@metaplex-foundation/umi-rpc-web3js': patch
+'@metaplex-foundation/umi': patch
+---
+
+Add getSignatureStatuses to RpcInterface

packages/umi-rpc-web3js/src/createWeb3JsRpc.ts

@@ -1,18 +1,14 @@
 import {
   ACCOUNT_HEADER_SIZE,
-  base58,
   BlockhashWithExpiryBlockHeight,
   Cluster,
   Commitment,
   CompiledInstruction,
   Context,
   ErrorWithLogs,
-  isZeroAmount,
-  lamports,
   MaybeRpcAccount,
   ProgramError,
   PublicKey,
-  resolveClusterFromEndpoint,
   RpcAccount,
   RpcAccountExistsOptions,
   RpcAirdropOptions,
@@ -26,17 +22,23 @@ import {
   RpcGetLatestBlockhashOptions,
   RpcGetProgramAccountsOptions,
   RpcGetRentOptions,
+  RpcGetSignatureStatusesOptions,
+  RpcGetSlotOptions,
   RpcGetTransactionOptions,
   RpcInterface,
   RpcSendTransactionOptions,
   SolAmount,
-  createAmount,
   Transaction,
   TransactionMetaInnerInstruction,
   TransactionMetaTokenBalance,
   TransactionSignature,
+  TransactionStatus,
   TransactionWithMeta,
-  RpcGetSlotOptions,
+  base58,
+  createAmount,
+  isZeroAmount,
+  lamports,
+  resolveClusterFromEndpoint,
 } from '@metaplex-foundation/umi';
 import {
   fromWeb3JsMessage,
@@ -223,6 +225,25 @@ export function createWeb3JsRpc(
     };
   };
 
+  const getSignatureStatuses = async (
+    signatures: TransactionSignature[],
+    options: RpcGetSignatureStatusesOptions = {}
+  ): Promise<Array<TransactionStatus | null>> => {
+    const response = await getConnection().getSignatureStatuses(
+      signatures.map((signature) => base58.deserialize(signature)[0]),
+      { searchTransactionHistory: options?.searchTransactionHistory ?? false }
+    );
+    return response.value.map((status) => {
+      if (!status) return null;
+      return {
+        slot: status.slot,
+        confirmations: status.confirmations,
+        error: status.err,
+        commitment: status.confirmationStatus ?? null,
+      };
+    });
+  };
+
   const accountExists = async (
     publicKey: PublicKey,
     options: RpcAccountExistsOptions = {}
@@ -316,6 +337,7 @@ export function createWeb3JsRpc(
       getConnection().getSlot(options),
     getLatestBlockhash,
     getTransaction,
+    getSignatureStatuses,
     accountExists,
     airdrop,
     call,

packages/umi/src/RpcInterface.ts

@@ -10,6 +10,7 @@ import type {
   Transaction,
   TransactionError,
   TransactionSignature,
+  TransactionStatus,
   TransactionWithMeta,
 } from './Transaction';
 
@@ -113,6 +114,19 @@ export interface RpcInterface {
     options?: RpcGetTransactionOptions
   ): Promise<TransactionWithMeta | null>;
 
+  /**
+   * Fetch transaction commitments from an array of signatures.
+   *
+   * @param signatures The signatures of all transactions we want to fetch commitments for.
+   * @param options The options to use when fetching transaction commitments.
+   * @returns An array of transaction statuses in the same order as the signatures.
+   * If a transaction was not found, `null` will be returned instead.
+   */
+  getSignatureStatuses(
+    signatures: TransactionSignature[],
+    options?: RpcGetSignatureStatusesOptions
+  ): Promise<Array<TransactionStatus | null>>;
+
   /**
    * Whether or not an account at a given address exists.
    *
@@ -299,6 +313,18 @@ export type RpcGetLatestBlockhashOptions = RpcBaseOptions;
  */
 export type RpcGetTransactionOptions = RpcBaseOptions;
 
+/**
+ * The options to use when fetching transaction statuses.
+ * @category Rpc
+ */
+export type RpcGetSignatureStatusesOptions = RpcBaseOptions & {
+  /**
+   * Enable searching status history, not needed for recent transactions.
+   * @defaultValue `false`
+   */
+  searchTransactionHistory?: boolean;
+};
+
 /**
  * The options to use when checking if an account exists.
  * @category Rpc
@@ -391,6 +417,7 @@ export function createNullRpc(): RpcInterface {
     getSlot: errorHandler,
     getLatestBlockhash: errorHandler,
     getTransaction: errorHandler,
+    getSignatureStatuses: errorHandler,
     accountExists: errorHandler,
     airdrop: errorHandler,
     call: errorHandler,

packages/umi/src/Transaction.ts

@@ -1,6 +1,7 @@
 import { Amount, SolAmount } from './Amount';
 import type { Instruction } from './Instruction';
-import { samePublicKey, PublicKey } from './PublicKey';
+import { PublicKey, samePublicKey } from './PublicKey';
+import type { Commitment } from './RpcInterface';
 
 /**
  * The maximum amount of bytes that can be used for a transaction.
@@ -207,6 +208,21 @@ export type AddressLookupTableInput = {
   addresses: PublicKey[];
 };
 
+/**
+ * The status of a sent transaction.
+ * @category Transactions
+ */
+export type TransactionStatus = {
+  /** When the transaction was processed. */
+  slot: number;
+  /** The number of blocks that have been confirmed and voted on in the fork containing `slot`. */
+  confirmations: number | null;
+  /** The transaction error, if any. */
+  error: TransactionError | null;
+  /** The cluster confirmation status, if any. */
+  commitment: Commitment | null;
+};
+
 /**
  * Adds a given signature to the transaction's signature array
  * and returns the updated transaction as a new object.