@solana/web3.js 1.66.5 → 1.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/web3.js",
-  "version": "1.66.5",
+  "version": "1.67.0",
   "description": "Solana Javascript API",
   "keywords": [
     "api",

package/src/connection.ts

@@ -28,7 +28,7 @@ import {AgentManager} from './agent-manager';
 import {EpochSchedule} from './epoch-schedule';
 import {SendTransactionError, SolanaJSONRPCError} from './errors';
 import fetchImpl, {Response} from './fetch-impl';
-import {NonceAccount} from './nonce-account';
+import {DurableNonce, NonceAccount} from './nonce-account';
 import {PublicKey} from './publickey';
 import {Signer} from './keypair';
 import {MS_PER_SLOT} from './timing';
@@ -45,6 +45,7 @@ import {sleep} from './utils/sleep';
 import {toBuffer} from './utils/to-buffer';
 import {
   TransactionExpiredBlockheightExceededError,
+  TransactionExpiredNonceInvalidError,
   TransactionExpiredTimeoutError,
 } from './transaction/expiry-custom-errors';
 import {makeWebsocketUrl} from './utils/makeWebsocketUrl';
@@ -338,6 +339,28 @@ function extractCommitmentFromConfig<TConfig>(
   return {commitment, config};
 }
 
+/**
+ * A strategy for confirming durable nonce transactions.
+ */
+export type DurableNonceTransactionConfirmationStrategy = {
+  /**
+   * The lowest slot at which to fetch the nonce value from the
+   * nonce account. This should be no lower than the slot at
+   * which the last-known value of the nonce was fetched.
+   */
+  minContextSlot: number;
+  /**
+   * The account where the current value of the nonce is stored.
+   */
+  nonceAccountPubkey: PublicKey;
+  /**
+   * The nonce value that was used to sign the transaction
+   * for which confirmation is being sought.
+   */
+  nonceValue: DurableNonce;
+  signature: TransactionSignature;
+};
+
 /**
  * @internal
  */
@@ -2438,6 +2461,26 @@ export type GetTransactionCountConfig = {
   minContextSlot?: number;
 };
 
+/**
+ * Configuration object for `getNonce`
+ */
+export type GetNonceConfig = {
+  /** Optional commitment level */
+  commitment?: Commitment;
+  /** The minimum slot that the request can be evaluated at */
+  minContextSlot?: number;
+};
+
+/**
+ * Configuration object for `getNonceAndContext`
+ */
+export type GetNonceAndContextConfig = {
+  /** Optional commitment level */
+  commitment?: Commitment;
+  /** The minimum slot that the request can be evaluated at */
+  minContextSlot?: number;
+};
+
 /**
  * Information describing an account
  */
@@ -3348,7 +3391,9 @@ export class Connection {
   }
 
   confirmTransaction(
-    strategy: BlockheightBasedTransactionConfirmationStrategy,
+    strategy:
+      | BlockheightBasedTransactionConfirmationStrategy
+      | DurableNonceTransactionConfirmationStrategy,
     commitment?: Commitment,
   ): Promise<RpcResponseAndContext<SignatureResult>>;
 
@@ -3363,6 +3408,7 @@ export class Connection {
   async confirmTransaction(
     strategy:
       | BlockheightBasedTransactionConfirmationStrategy
+      | DurableNonceTransactionConfirmationStrategy
       | TransactionSignature,
     commitment?: Commitment,
   ): Promise<RpcResponseAndContext<SignatureResult>> {
@@ -3371,8 +3417,9 @@ export class Connection {
     if (typeof strategy == 'string') {
       rawSignature = strategy;
     } else {
-      const config =
-        strategy as BlockheightBasedTransactionConfirmationStrategy;
+      const config = strategy as
+        | BlockheightBasedTransactionConfirmationStrategy
+        | DurableNonceTransactionConfirmationStrategy;
       rawSignature = config.signature;
     }
 
@@ -3386,31 +3433,58 @@ export class Connection {
 
     assert(decodedSignature.length === 64, 'signature has invalid length');
 
-    const confirmationCommitment = commitment || this.commitment;
-    let timeoutId;
+    if (typeof strategy === 'string') {
+      return await this.confirmTransactionUsingLegacyTimeoutStrategy({
+        commitment: commitment || this.commitment,
+        signature: rawSignature,
+      });
+    } else if ('lastValidBlockHeight' in strategy) {
+      return await this.confirmTransactionUsingBlockHeightExceedanceStrategy({
+        commitment: commitment || this.commitment,
+        strategy,
+      });
+    } else {
+      return await this.confirmTransactionUsingDurableNonceStrategy({
+        commitment: commitment || this.commitment,
+        strategy,
+      });
+    }
+  }
+
+  private getTransactionConfirmationPromise({
+    commitment,
+    signature,
+  }: {
+    commitment?: Commitment;
+    signature: string;
+  }): {
+    abortConfirmation(): void;
+    confirmationPromise: Promise<{
+      __type: TransactionStatus.PROCESSED;
+      response: RpcResponseAndContext<SignatureResult>;
+    }>;
+  } {
     let signatureSubscriptionId: number | undefined;
     let disposeSignatureSubscriptionStateChangeObserver:
       | SubscriptionStateChangeDisposeFn
       | undefined;
     let done = false;
-
     const confirmationPromise = new Promise<{
       __type: TransactionStatus.PROCESSED;
       response: RpcResponseAndContext<SignatureResult>;
     }>((resolve, reject) => {
       try {
         signatureSubscriptionId = this.onSignature(
-          rawSignature,
+          signature,
           (result: SignatureResult, context: Context) => {
             signatureSubscriptionId = undefined;
             const response = {
               context,
               value: result,
             };
-            done = true;
             resolve({__type: TransactionStatus.PROCESSED, response});
           },
-          confirmationCommitment,
+          commitment,
         );
         const subscriptionSetupPromise = new Promise<void>(
           resolveSubscriptionSetup => {
@@ -3432,7 +3506,7 @@ export class Connection {
         (async () => {
           await subscriptionSetupPromise;
           if (done) return;
-          const response = await this.getSignatureStatus(rawSignature);
+          const response = await this.getSignatureStatus(signature);
           if (done) return;
           if (response == null) {
             return;
@@ -3444,7 +3518,7 @@ export class Connection {
           if (value?.err) {
             reject(value.err);
           } else {
-            switch (confirmationCommitment) {
+            switch (commitment) {
               case 'confirmed':
               case 'single':
               case 'singleGossip': {
@@ -3482,80 +3556,250 @@ export class Connection {
         reject(err);
       }
     });
+    const abortConfirmation = () => {
+      if (disposeSignatureSubscriptionStateChangeObserver) {
+        disposeSignatureSubscriptionStateChangeObserver();
+        disposeSignatureSubscriptionStateChangeObserver = undefined;
+      }
+      if (signatureSubscriptionId) {
+        this.removeSignatureListener(signatureSubscriptionId);
+        signatureSubscriptionId = undefined;
+      }
+    };
+    return {abortConfirmation, confirmationPromise};
+  }
 
-    const expiryPromise = new Promise<
-      | {__type: TransactionStatus.BLOCKHEIGHT_EXCEEDED}
-      | {__type: TransactionStatus.TIMED_OUT; timeoutMs: number}
-    >(resolve => {
-      if (typeof strategy === 'string') {
-        let timeoutMs = this._confirmTransactionInitialTimeout || 60 * 1000;
-        switch (confirmationCommitment) {
-          case 'processed':
-          case 'recent':
-          case 'single':
-          case 'confirmed':
-          case 'singleGossip': {
-            timeoutMs = this._confirmTransactionInitialTimeout || 30 * 1000;
-            break;
-          }
-          // exhaust enums to ensure full coverage
-          case 'finalized':
-          case 'max':
-          case 'root':
+  private async confirmTransactionUsingBlockHeightExceedanceStrategy({
+    commitment,
+    strategy: {lastValidBlockHeight, signature},
+  }: {
+    commitment?: Commitment;
+    strategy: BlockheightBasedTransactionConfirmationStrategy;
+  }) {
+    let done: boolean = false;
+    const expiryPromise = new Promise<{
+      __type: TransactionStatus.BLOCKHEIGHT_EXCEEDED;
+    }>(resolve => {
+      const checkBlockHeight = async () => {
+        try {
+          const blockHeight = await this.getBlockHeight(commitment);
+          return blockHeight;
+        } catch (_e) {
+          return -1;
         }
-
-        timeoutId = setTimeout(
-          () => resolve({__type: TransactionStatus.TIMED_OUT, timeoutMs}),
-          timeoutMs,
-        );
+      };
+      (async () => {
+        let currentBlockHeight = await checkBlockHeight();
+        if (done) return;
+        while (currentBlockHeight <= lastValidBlockHeight) {
+          await sleep(1000);
+          if (done) return;
+          currentBlockHeight = await checkBlockHeight();
+          if (done) return;
+        }
+        resolve({__type: TransactionStatus.BLOCKHEIGHT_EXCEEDED});
+      })();
+    });
+    const {abortConfirmation, confirmationPromise} =
+      this.getTransactionConfirmationPromise({commitment, signature});
+    let result: RpcResponseAndContext<SignatureResult>;
+    try {
+      const outcome = await Promise.race([confirmationPromise, expiryPromise]);
+      if (outcome.__type === TransactionStatus.PROCESSED) {
+        result = outcome.response;
       } else {
-        let config =
-          strategy as BlockheightBasedTransactionConfirmationStrategy;
-        const checkBlockHeight = async () => {
-          try {
-            const blockHeight = await this.getBlockHeight(commitment);
-            return blockHeight;
-          } catch (_e) {
-            return -1;
+        throw new TransactionExpiredBlockheightExceededError(signature);
+      }
+    } finally {
+      done = true;
+      abortConfirmation();
+    }
+    return result;
+  }
+
+  private async confirmTransactionUsingDurableNonceStrategy({
+    commitment,
+    strategy: {minContextSlot, nonceAccountPubkey, nonceValue, signature},
+  }: {
+    commitment?: Commitment;
+    strategy: DurableNonceTransactionConfirmationStrategy;
+  }) {
+    let done: boolean = false;
+    const expiryPromise = new Promise<{
+      __type: TransactionStatus.NONCE_INVALID;
+      slotInWhichNonceDidAdvance: number | null;
+    }>(resolve => {
+      let currentNonceValue: string | undefined = nonceValue;
+      let lastCheckedSlot: number | null = null;
+      const getCurrentNonceValue = async () => {
+        try {
+          const {context, value: nonceAccount} = await this.getNonceAndContext(
+            nonceAccountPubkey,
+            {
+              commitment,
+              minContextSlot,
+            },
+          );
+          lastCheckedSlot = context.slot;
+          return nonceAccount?.nonce;
+        } catch (e) {
+          // If for whatever reason we can't reach/read the nonce
+          // account, just keep using the last-known value.
+          return currentNonceValue;
+        }
+      };
+      (async () => {
+        currentNonceValue = await getCurrentNonceValue();
+        if (done) return;
+        while (
+          true // eslint-disable-line no-constant-condition
+        ) {
+          if (nonceValue !== currentNonceValue) {
+            resolve({
+              __type: TransactionStatus.NONCE_INVALID,
+              slotInWhichNonceDidAdvance: lastCheckedSlot,
+            });
+            return;
           }
-        };
-        (async () => {
-          let currentBlockHeight = await checkBlockHeight();
+          await sleep(2000);
           if (done) return;
-          while (currentBlockHeight <= config.lastValidBlockHeight) {
-            await sleep(1000);
-            if (done) return;
-            currentBlockHeight = await checkBlockHeight();
-            if (done) return;
-          }
-          resolve({__type: TransactionStatus.BLOCKHEIGHT_EXCEEDED});
-        })();
-      }
+          currentNonceValue = await getCurrentNonceValue();
+          if (done) return;
+        }
+      })();
     });
-
+    const {abortConfirmation, confirmationPromise} =
+      this.getTransactionConfirmationPromise({commitment, signature});
     let result: RpcResponseAndContext<SignatureResult>;
     try {
       const outcome = await Promise.race([confirmationPromise, expiryPromise]);
-      switch (outcome.__type) {
-        case TransactionStatus.BLOCKHEIGHT_EXCEEDED:
-          throw new TransactionExpiredBlockheightExceededError(rawSignature);
-        case TransactionStatus.PROCESSED:
-          result = outcome.response;
+      if (outcome.__type === TransactionStatus.PROCESSED) {
+        result = outcome.response;
+      } else {
+        // Double check that the transaction is indeed unconfirmed.
+        let signatureStatus:
+          | RpcResponseAndContext<SignatureStatus | null>
+          | null
+          | undefined;
+        while (
+          true // eslint-disable-line no-constant-condition
+        ) {
+          const status = await this.getSignatureStatus(signature);
+          if (status == null) {
+            break;
+          }
+          if (
+            status.context.slot <
+            (outcome.slotInWhichNonceDidAdvance ?? minContextSlot)
+          ) {
+            await sleep(400);
+            continue;
+          }
+          signatureStatus = status;
           break;
-        case TransactionStatus.TIMED_OUT:
-          throw new TransactionExpiredTimeoutError(
-            rawSignature,
-            outcome.timeoutMs / 1000,
-          );
+        }
+        if (signatureStatus?.value) {
+          const commitmentForStatus = commitment || 'finalized';
+          const {confirmationStatus} = signatureStatus.value;
+          switch (commitmentForStatus) {
+            case 'processed':
+            case 'recent':
+              if (
+                confirmationStatus !== 'processed' &&
+                confirmationStatus !== 'confirmed' &&
+                confirmationStatus !== 'finalized'
+              ) {
+                throw new TransactionExpiredNonceInvalidError(signature);
+              }
+              break;
+            case 'confirmed':
+            case 'single':
+            case 'singleGossip':
+              if (
+                confirmationStatus !== 'confirmed' &&
+                confirmationStatus !== 'finalized'
+              ) {
+                throw new TransactionExpiredNonceInvalidError(signature);
+              }
+              break;
+            case 'finalized':
+            case 'max':
+            case 'root':
+              if (confirmationStatus !== 'finalized') {
+                throw new TransactionExpiredNonceInvalidError(signature);
+              }
+              break;
+            default:
+              // Exhaustive switch.
+              // eslint-disable-next-line @typescript-eslint/no-unused-vars
+              ((_: never) => {})(commitmentForStatus);
+          }
+          result = {
+            context: signatureStatus.context,
+            value: {err: signatureStatus.value.err},
+          };
+        } else {
+          throw new TransactionExpiredNonceInvalidError(signature);
+        }
       }
     } finally {
-      clearTimeout(timeoutId);
-      if (disposeSignatureSubscriptionStateChangeObserver) {
-        disposeSignatureSubscriptionStateChangeObserver();
+      done = true;
+      abortConfirmation();
+    }
+    return result;
+  }
+
+  private async confirmTransactionUsingLegacyTimeoutStrategy({
+    commitment,
+    signature,
+  }: {
+    commitment?: Commitment;
+    signature: string;
+  }) {
+    let timeoutId;
+    const expiryPromise = new Promise<{
+      __type: TransactionStatus.TIMED_OUT;
+      timeoutMs: number;
+    }>(resolve => {
+      let timeoutMs = this._confirmTransactionInitialTimeout || 60 * 1000;
+      switch (commitment) {
+        case 'processed':
+        case 'recent':
+        case 'single':
+        case 'confirmed':
+        case 'singleGossip': {
+          timeoutMs = this._confirmTransactionInitialTimeout || 30 * 1000;
+          break;
+        }
+        // exhaust enums to ensure full coverage
+        case 'finalized':
+        case 'max':
+        case 'root':
       }
-      if (signatureSubscriptionId) {
-        this.removeSignatureListener(signatureSubscriptionId);
+      timeoutId = setTimeout(
+        () => resolve({__type: TransactionStatus.TIMED_OUT, timeoutMs}),
+        timeoutMs,
+      );
+    });
+    const {abortConfirmation, confirmationPromise} =
+      this.getTransactionConfirmationPromise({
+        commitment,
+        signature,
+      });
+    let result: RpcResponseAndContext<SignatureResult>;
+    try {
+      const outcome = await Promise.race([confirmationPromise, expiryPromise]);
+      if (outcome.__type === TransactionStatus.PROCESSED) {
+        result = outcome.response;
+      } else {
+        throw new TransactionExpiredTimeoutError(
+          signature,
+          outcome.timeoutMs / 1000,
+        );
       }
+    } finally {
+      clearTimeout(timeoutId);
+      abortConfirmation();
     }
     return result;
   }
@@ -4708,11 +4952,11 @@ export class Connection {
    */
   async getNonceAndContext(
     nonceAccount: PublicKey,
-    commitment?: Commitment,
+    commitmentOrConfig?: Commitment | GetNonceAndContextConfig,
   ): Promise<RpcResponseAndContext<NonceAccount | null>> {
     const {context, value: accountInfo} = await this.getAccountInfoAndContext(
       nonceAccount,
-      commitment,
+      commitmentOrConfig,
     );
 
     let value = null;
@@ -4731,9 +4975,9 @@ export class Connection {
    */
   async getNonce(
     nonceAccount: PublicKey,
-    commitment?: Commitment,
+    commitmentOrConfig?: Commitment | GetNonceConfig,
   ): Promise<NonceAccount | null> {
-    return await this.getNonceAndContext(nonceAccount, commitment)
+    return await this.getNonceAndContext(nonceAccount, commitmentOrConfig)
       .then(x => x.value)
       .catch(e => {
         throw new Error(

package/src/nonce-account.ts

@@ -1,7 +1,6 @@
 import * as BufferLayout from '@solana/buffer-layout';
 import {Buffer} from 'buffer';
 
-import type {Blockhash} from './blockhash';
 import * as Layout from './layout';
 import {PublicKey} from './publickey';
 import type {FeeCalculator} from './fee-calculator';
@@ -36,9 +35,14 @@ const NonceAccountLayout = BufferLayout.struct<
 
 export const NONCE_ACCOUNT_LENGTH = NonceAccountLayout.span;
 
+/**
+ * A durable nonce is a 32 byte value encoded as a base58 string.
+ */
+export type DurableNonce = string;
+
 type NonceAccountArgs = {
   authorizedPubkey: PublicKey;
-  nonce: Blockhash;
+  nonce: DurableNonce;
   feeCalculator: FeeCalculator;
 };
 
@@ -47,7 +51,7 @@ type NonceAccountArgs = {
  */
 export class NonceAccount {
   authorizedPubkey: PublicKey;
-  nonce: Blockhash;
+  nonce: DurableNonce;
   feeCalculator: FeeCalculator;
 
   /**

package/src/transaction/expiry-custom-errors.ts

@@ -33,3 +33,16 @@ export class TransactionExpiredTimeoutError extends Error {
 Object.defineProperty(TransactionExpiredTimeoutError.prototype, 'name', {
   value: 'TransactionExpiredTimeoutError',
 });
+
+export class TransactionExpiredNonceInvalidError extends Error {
+  signature: string;
+
+  constructor(signature: string) {
+    super(`Signature ${signature} has expired: the nonce is no longer valid.`);
+    this.signature = signature;
+  }
+}
+
+Object.defineProperty(TransactionExpiredNonceInvalidError.prototype, 'name', {
+  value: 'TransactionExpiredNonceInvalidError',
+});

package/src/transaction/legacy.ts

@@ -22,6 +22,7 @@ export const enum TransactionStatus {
   BLOCKHEIGHT_EXCEEDED,
   PROCESSED,
   TIMED_OUT,
+  NONCE_INVALID,
 }
 
 /**
@@ -145,7 +146,9 @@ export type TransactionCtorFields_DEPRECATED = {
 export type TransactionCtorFields = TransactionCtorFields_DEPRECATED;
 
 /**
- * List of Transaction object fields that may be initialized at construction
+ * Blockhash-based transactions have a lifetime that are defined by
+ * the blockhash they include. Any transaction whose blockhash is
+ * too old will be rejected.
  */
 export type TransactionBlockhashCtor = {
   /** The transaction fee payer */
@@ -158,6 +161,18 @@ export type TransactionBlockhashCtor = {
   lastValidBlockHeight: number;
 };
 
+/**
+ * Use these options to construct a durable nonce transaction.
+ */
+export type TransactionNonceCtor = {
+  /** The transaction fee payer */
+  feePayer?: PublicKey | null;
+  minContextSlot: number;
+  nonceInfo: NonceInformation;
+  /** One or more signatures */
+  signatures?: Array<SignaturePubkeyPair>;
+};
+
 /**
  * Nonce information to be used to build an offline Transaction.
  */
@@ -228,6 +243,15 @@ export class Transaction {
    */
   nonceInfo?: NonceInformation;
 
+  /**
+   * If this is a nonce transaction this represents the minimum slot from which
+   * to evaluate if the nonce has advanced when attempting to confirm the
+   * transaction. This protects against a case where the transaction confirmation
+   * logic loads the nonce account from an old slot and assumes the mismatch in
+   * nonce value implies that the nonce has been advanced.
+   */
+  minNonceContextSlot?: number;
+
   /**
    * @internal
    */
@@ -241,6 +265,9 @@ export class Transaction {
   // Construct a transaction with a blockhash and lastValidBlockHeight
   constructor(opts?: TransactionBlockhashCtor);
 
+  // Construct a transaction using a durable nonce
+  constructor(opts?: TransactionNonceCtor);
+
   /**
    * @deprecated `TransactionCtorFields` has been deprecated and will be removed in a future version.
    * Please supply a `TransactionBlockhashCtor` instead.
@@ -251,7 +278,10 @@ export class Transaction {
    * Construct an empty Transaction
    */
   constructor(
-    opts?: TransactionBlockhashCtor | TransactionCtorFields_DEPRECATED,
+    opts?:
+      | TransactionBlockhashCtor
+      | TransactionNonceCtor
+      | TransactionCtorFields_DEPRECATED,
   ) {
     if (!opts) {
       return;
@@ -262,7 +292,13 @@ export class Transaction {
     if (opts.signatures) {
       this.signatures = opts.signatures;
     }
-    if (Object.prototype.hasOwnProperty.call(opts, 'lastValidBlockHeight')) {
+    if (Object.prototype.hasOwnProperty.call(opts, 'nonceInfo')) {
+      const {minContextSlot, nonceInfo} = opts as TransactionNonceCtor;
+      this.minNonceContextSlot = minContextSlot;
+      this.nonceInfo = nonceInfo;
+    } else if (
+      Object.prototype.hasOwnProperty.call(opts, 'lastValidBlockHeight')
+    ) {
       const {blockhash, lastValidBlockHeight} =
         opts as TransactionBlockhashCtor;
       this.recentBlockhash = blockhash;