@solana/web3.js 1.41.9 → 1.43.0

package/package.json

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

package/src/compute-budget.ts

@@ -1,4 +1,5 @@
 import * as BufferLayout from '@solana/buffer-layout';
+import {u64} from '@solana/buffer-layout-utils';
 
 import {
   encodeData,
@@ -76,6 +77,34 @@ export class ComputeBudgetInstruction {
     return {bytes};
   }
 
+  /**
+   * Decode set compute unit limit compute budget instruction and retrieve the instruction params.
+   */
+  static decodeSetComputeUnitLimit(
+    instruction: TransactionInstruction,
+  ): SetComputeUnitLimitParams {
+    this.checkProgramId(instruction.programId);
+    const {units} = decodeData(
+      COMPUTE_BUDGET_INSTRUCTION_LAYOUTS.SetComputeUnitLimit,
+      instruction.data,
+    );
+    return {units};
+  }
+
+  /**
+   * Decode set compute unit price compute budget instruction and retrieve the instruction params.
+   */
+  static decodeSetComputeUnitPrice(
+    instruction: TransactionInstruction,
+  ): SetComputeUnitPriceParams {
+    this.checkProgramId(instruction.programId);
+    const {microLamports} = decodeData(
+      COMPUTE_BUDGET_INSTRUCTION_LAYOUTS.SetComputeUnitPrice,
+      instruction.data,
+    );
+    return {microLamports};
+  }
+
   /**
    * @internal
    */
@@ -96,11 +125,18 @@ export type ComputeBudgetInstructionType =
   // It would be preferable for this type to be `keyof ComputeBudgetInstructionInputData`
   // but Typedoc does not transpile `keyof` expressions.
   // See https://github.com/TypeStrong/typedoc/issues/1894
-  'RequestUnits' | 'RequestHeapFrame';
+  | 'RequestUnits'
+  | 'RequestHeapFrame'
+  | 'SetComputeUnitLimit'
+  | 'SetComputeUnitPrice';
 
 type ComputeBudgetInstructionInputData = {
   RequestUnits: IInstructionInputData & Readonly<RequestUnitsParams>;
   RequestHeapFrame: IInstructionInputData & Readonly<RequestHeapFrameParams>;
+  SetComputeUnitLimit: IInstructionInputData &
+    Readonly<SetComputeUnitLimitParams>;
+  SetComputeUnitPrice: IInstructionInputData &
+    Readonly<SetComputeUnitPriceParams>;
 };
 
 /**
@@ -109,8 +145,7 @@ type ComputeBudgetInstructionInputData = {
 export interface RequestUnitsParams {
   /** Units to request for transaction-wide compute */
   units: number;
-
-  /** Additional fee to pay */
+  /** Prioritization fee lamports */
   additionalFee: number;
 }
 
@@ -122,6 +157,22 @@ export type RequestHeapFrameParams = {
   bytes: number;
 };
 
+/**
+ * Set compute unit limit instruction params
+ */
+export interface SetComputeUnitLimitParams {
+  /** Transaction-wide compute unit limit */
+  units: number;
+}
+
+/**
+ * Set compute unit price instruction params
+ */
+export interface SetComputeUnitPriceParams {
+  /** Transaction compute unit price used for prioritization fees */
+  microLamports: number | bigint;
+}
+
 /**
  * An enumeration of valid ComputeBudget InstructionType's
  * @internal
@@ -147,6 +198,18 @@ export const COMPUTE_BUDGET_INSTRUCTION_LAYOUTS = Object.freeze<{
       ComputeBudgetInstructionInputData['RequestHeapFrame']
     >([BufferLayout.u8('instruction'), BufferLayout.u32('bytes')]),
   },
+  SetComputeUnitLimit: {
+    index: 2,
+    layout: BufferLayout.struct<
+      ComputeBudgetInstructionInputData['SetComputeUnitLimit']
+    >([BufferLayout.u8('instruction'), BufferLayout.u32('units')]),
+  },
+  SetComputeUnitPrice: {
+    index: 3,
+    layout: BufferLayout.struct<
+      ComputeBudgetInstructionInputData['SetComputeUnitPrice']
+    >([BufferLayout.u8('instruction'), u64('microLamports')]),
+  },
 });
 
 /**
@@ -186,4 +249,30 @@ export class ComputeBudgetProgram {
       data,
     });
   }
+
+  static setComputeUnitLimit(
+    params: SetComputeUnitLimitParams,
+  ): TransactionInstruction {
+    const type = COMPUTE_BUDGET_INSTRUCTION_LAYOUTS.SetComputeUnitLimit;
+    const data = encodeData(type, params);
+    return new TransactionInstruction({
+      keys: [],
+      programId: this.programId,
+      data,
+    });
+  }
+
+  static setComputeUnitPrice(
+    params: SetComputeUnitPriceParams,
+  ): TransactionInstruction {
+    const type = COMPUTE_BUDGET_INSTRUCTION_LAYOUTS.SetComputeUnitPrice;
+    const data = encodeData(type, {
+      microLamports: BigInt(params.microLamports),
+    });
+    return new TransactionInstruction({
+      keys: [],
+      programId: this.programId,
+      data,
+    });
+  }
 }

package/src/connection.ts

@@ -32,12 +32,15 @@ import {NonceAccount} from './nonce-account';
 import {PublicKey} from './publickey';
 import {Signer} from './keypair';
 import {MS_PER_SLOT} from './timing';
-import {Transaction} from './transaction';
+import {Transaction, TransactionStatus} from './transaction';
 import {Message} from './message';
 import assert from './util/assert';
 import {sleep} from './util/sleep';
-import {promiseTimeout} from './util/promise-timeout';
 import {toBuffer} from './util/to-buffer';
+import {
+  TransactionExpiredBlockheightExceededError,
+  TransactionExpiredTimeoutError,
+} from './util/tx-expiry-custom-errors';
 import {makeWebsocketUrl} from './util/url';
 import type {Blockhash} from './blockhash';
 import type {FeeCalculator} from './fee-calculator';
@@ -281,6 +284,19 @@ export type RpcResponseAndContext<T> = {
   value: T;
 };
 
+export type BlockhashWithExpiryBlockHeight = Readonly<{
+  blockhash: Blockhash;
+  lastValidBlockHeight: number;
+}>;
+
+/**
+ * A strategy for confirming transactions that uses the last valid
+ * block height for a given blockhash to check for transaction expiration.
+ */
+export type BlockheightBasedTransactionConfirmationStrategy = {
+  signature: TransactionSignature;
+} & BlockhashWithExpiryBlockHeight;
+
 /**
  * @internal
  */
@@ -2205,12 +2221,12 @@ export class Connection {
   /** @internal */ _disableBlockhashCaching: boolean = false;
   /** @internal */ _pollingBlockhash: boolean = false;
   /** @internal */ _blockhashInfo: {
-    recentBlockhash: Blockhash | null;
+    latestBlockhash: BlockhashWithExpiryBlockHeight | null;
     lastFetch: number;
     simulatedSignatures: Array<string>;
     transactionSignatures: Array<string>;
   } = {
-    recentBlockhash: null,
+    latestBlockhash: null,
     lastFetch: 0,
     transactionSignatures: [],
     simulatedSignatures: [],
@@ -2825,38 +2841,65 @@ export class Connection {
     return res.result;
   }
 
-  /**
-   * Confirm the transaction identified by the specified signature.
-   */
+  confirmTransaction(
+    strategy: BlockheightBasedTransactionConfirmationStrategy,
+    commitment?: Commitment,
+  ): Promise<RpcResponseAndContext<SignatureResult>>;
+
+  /** @deprecated Instead, call `confirmTransaction` using a `TransactionConfirmationConfig` */
+  // eslint-disable-next-line no-dupe-class-members
+  confirmTransaction(
+    strategy: TransactionSignature,
+    commitment?: Commitment,
+  ): Promise<RpcResponseAndContext<SignatureResult>>;
+
+  // eslint-disable-next-line no-dupe-class-members
   async confirmTransaction(
-    signature: TransactionSignature,
+    strategy:
+      | BlockheightBasedTransactionConfirmationStrategy
+      | TransactionSignature,
     commitment?: Commitment,
   ): Promise<RpcResponseAndContext<SignatureResult>> {
+    let rawSignature: string;
+
+    if (typeof strategy == 'string') {
+      rawSignature = strategy;
+    } else {
+      const config =
+        strategy as BlockheightBasedTransactionConfirmationStrategy;
+      rawSignature = config.signature;
+    }
+
     let decodedSignature;
+
     try {
-      decodedSignature = bs58.decode(signature);
+      decodedSignature = bs58.decode(rawSignature);
     } catch (err) {
-      throw new Error('signature must be base58 encoded: ' + signature);
+      throw new Error('signature must be base58 encoded: ' + rawSignature);
     }
 
     assert(decodedSignature.length === 64, 'signature has invalid length');
 
-    const start = Date.now();
     const subscriptionCommitment = commitment || this.commitment;
-
+    let timeoutId;
     let subscriptionId;
-    let response: RpcResponseAndContext<SignatureResult> | null = null;
-    const confirmPromise = new Promise((resolve, reject) => {
+    let done = false;
+
+    const confirmationPromise = new Promise<{
+      __type: TransactionStatus.PROCESSED;
+      response: RpcResponseAndContext<SignatureResult>;
+    }>((resolve, reject) => {
       try {
         subscriptionId = this.onSignature(
-          signature,
+          rawSignature,
           (result: SignatureResult, context: Context) => {
             subscriptionId = undefined;
-            response = {
+            const response = {
               context,
               value: result,
             };
-            resolve(null);
+            done = true;
+            resolve({__type: TransactionStatus.PROCESSED, response});
           },
           subscriptionCommitment,
         );
@@ -2865,40 +2908,79 @@ export class Connection {
       }
     });
 
-    let timeoutMs = this._confirmTransactionInitialTimeout || 60 * 1000;
-    switch (subscriptionCommitment) {
-      case 'processed':
-      case 'recent':
-      case 'single':
-      case 'confirmed':
-      case 'singleGossip': {
-        timeoutMs = this._confirmTransactionInitialTimeout || 30 * 1000;
-        break;
+    const checkBlockHeight = async () => {
+      try {
+        const blockHeight = await this.getBlockHeight(commitment);
+        return blockHeight;
+      } catch (_e) {
+        return -1;
       }
-      // exhaust enums to ensure full coverage
-      case 'finalized':
-      case 'max':
-      case 'root':
-    }
+    };
+
+    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 (subscriptionCommitment) {
+          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':
+        }
+
+        timeoutId = setTimeout(
+          () => resolve({__type: TransactionStatus.TIMED_OUT, timeoutMs}),
+          timeoutMs,
+        );
+      } else {
+        let config =
+          strategy as BlockheightBasedTransactionConfirmationStrategy;
+        (async () => {
+          let currentBlockHeight = await checkBlockHeight();
+          if (done) return;
+          while (currentBlockHeight <= config.lastValidBlockHeight) {
+            await sleep(1000);
+            if (done) return;
+            currentBlockHeight = await checkBlockHeight();
+            if (done) return;
+          }
+          resolve({__type: TransactionStatus.BLOCKHEIGHT_EXCEEDED});
+        })();
+      }
+    });
 
+    let result: RpcResponseAndContext<SignatureResult>;
     try {
-      await promiseTimeout(confirmPromise, timeoutMs);
+      const outcome = await Promise.race([confirmationPromise, expiryPromise]);
+      switch (outcome.__type) {
+        case TransactionStatus.BLOCKHEIGHT_EXCEEDED:
+          throw new TransactionExpiredBlockheightExceededError(rawSignature);
+        case TransactionStatus.PROCESSED:
+          result = outcome.response;
+          break;
+        case TransactionStatus.TIMED_OUT:
+          throw new TransactionExpiredTimeoutError(
+            rawSignature,
+            outcome.timeoutMs / 1000,
+          );
+      }
     } finally {
+      clearTimeout(timeoutId);
       if (subscriptionId) {
         this.removeSignatureListener(subscriptionId);
       }
     }
-
-    if (response === null) {
-      const duration = (Date.now() - start) / 1000;
-      throw new Error(
-        `Transaction was not confirmed in ${duration.toFixed(
-          2,
-        )} seconds. It is unknown if it succeeded or failed. Check signature ${signature} using the Solana Explorer or CLI tools.`,
-      );
-    }
-
-    return response;
+    return result;
   }
 
   /**
@@ -3245,11 +3327,11 @@ export class Connection {
 
   /**
    * Fetch the latest blockhash from the cluster
-   * @return {Promise<{blockhash: Blockhash, lastValidBlockHeight: number}>}
+   * @return {Promise<BlockhashWithExpiryBlockHeight>}
    */
   async getLatestBlockhash(
     commitment?: Commitment,
-  ): Promise<{blockhash: Blockhash; lastValidBlockHeight: number}> {
+  ): Promise<BlockhashWithExpiryBlockHeight> {
     try {
       const res = await this.getLatestBlockhashAndContext(commitment);
       return res.value;
@@ -3260,13 +3342,11 @@ export class Connection {
 
   /**
    * Fetch the latest blockhash from the cluster
-   * @return {Promise<{blockhash: Blockhash, lastValidBlockHeight: number}>}
+   * @return {Promise<BlockhashWithExpiryBlockHeight>}
    */
   async getLatestBlockhashAndContext(
     commitment?: Commitment,
-  ): Promise<
-    RpcResponseAndContext<{blockhash: Blockhash; lastValidBlockHeight: number}>
-  > {
+  ): Promise<RpcResponseAndContext<BlockhashWithExpiryBlockHeight>> {
     const args = this._buildArgs([], commitment);
     const unsafeRes = await this._rpcRequest('getLatestBlockhash', args);
     const res = create(unsafeRes, GetLatestBlockhashRpcResult);
@@ -3912,7 +3992,9 @@ export class Connection {
   /**
    * @internal
    */
-  async _recentBlockhash(disableCache: boolean): Promise<Blockhash> {
+  async _blockhashWithExpiryBlockHeight(
+    disableCache: boolean,
+  ): Promise<BlockhashWithExpiryBlockHeight> {
     if (!disableCache) {
       // Wait for polling to finish
       while (this._pollingBlockhash) {
@@ -3920,8 +4002,8 @@ export class Connection {
       }
       const timeSinceFetch = Date.now() - this._blockhashInfo.lastFetch;
       const expired = timeSinceFetch >= BLOCKHASH_CACHE_TIMEOUT_MS;
-      if (this._blockhashInfo.recentBlockhash !== null && !expired) {
-        return this._blockhashInfo.recentBlockhash;
+      if (this._blockhashInfo.latestBlockhash !== null && !expired) {
+        return this._blockhashInfo.latestBlockhash;
       }
     }
 
@@ -3931,21 +4013,25 @@ export class Connection {
   /**
    * @internal
    */
-  async _pollNewBlockhash(): Promise<Blockhash> {
+  async _pollNewBlockhash(): Promise<BlockhashWithExpiryBlockHeight> {
     this._pollingBlockhash = true;
     try {
       const startTime = Date.now();
+      const cachedLatestBlockhash = this._blockhashInfo.latestBlockhash;
+      const cachedBlockhash = cachedLatestBlockhash
+        ? cachedLatestBlockhash.blockhash
+        : null;
       for (let i = 0; i < 50; i++) {
-        const {blockhash} = await this.getRecentBlockhash('finalized');
+        const latestBlockhash = await this.getLatestBlockhash('finalized');
 
-        if (this._blockhashInfo.recentBlockhash != blockhash) {
+        if (cachedBlockhash !== latestBlockhash.blockhash) {
           this._blockhashInfo = {
-            recentBlockhash: blockhash,
+            latestBlockhash,
             lastFetch: Date.now(),
             transactionSignatures: [],
             simulatedSignatures: [],
           };
-          return blockhash;
+          return latestBlockhash;
         }
 
         // Sleep for approximately half a slot
@@ -3971,13 +4057,11 @@ export class Connection {
     let transaction;
     if (transactionOrMessage instanceof Transaction) {
       let originalTx: Transaction = transactionOrMessage;
-      transaction = new Transaction({
-        recentBlockhash: originalTx.recentBlockhash,
-        nonceInfo: originalTx.nonceInfo,
-        feePayer: originalTx.feePayer,
-        signatures: [...originalTx.signatures],
-      });
+      transaction = new Transaction();
+      transaction.feePayer = originalTx.feePayer;
       transaction.instructions = transactionOrMessage.instructions;
+      transaction.nonceInfo = originalTx.nonceInfo;
+      transaction.signatures = originalTx.signatures;
     } else {
       transaction = Transaction.populate(transactionOrMessage);
       // HACK: this function relies on mutating the populated transaction
@@ -3989,7 +4073,11 @@ export class Connection {
     } else {
       let disableCache = this._disableBlockhashCaching;
       for (;;) {
-        transaction.recentBlockhash = await this._recentBlockhash(disableCache);
+        const latestBlockhash = await this._blockhashWithExpiryBlockHeight(
+          disableCache,
+        );
+        transaction.lastValidBlockHeight = latestBlockhash.lastValidBlockHeight;
+        transaction.recentBlockhash = latestBlockhash.blockhash;
 
         if (!signers) break;
 
@@ -4077,7 +4165,11 @@ export class Connection {
     } else {
       let disableCache = this._disableBlockhashCaching;
       for (;;) {
-        transaction.recentBlockhash = await this._recentBlockhash(disableCache);
+        const latestBlockhash = await this._blockhashWithExpiryBlockHeight(
+          disableCache,
+        );
+        transaction.lastValidBlockHeight = latestBlockhash.lastValidBlockHeight;
+        transaction.recentBlockhash = latestBlockhash.blockhash;
         transaction.sign(...signers);
         if (!transaction.signature) {
           throw new Error('!signature'); // should never happen

package/src/transaction.ts

@@ -21,6 +21,12 @@ import type {CompiledInstruction} from './message';
  */
 export type TransactionSignature = string;
 
+export const enum TransactionStatus {
+  BLOCKHEIGHT_EXCEEDED,
+  PROCESSED,
+  TIMED_OUT,
+}
+
 /**
  * Default (empty) signature
  */
@@ -124,17 +130,30 @@ export type SignaturePubkeyPair = {
 
 /**
  * List of Transaction object fields that may be initialized at construction
- *
  */
-export type TransactionCtorFields = {
-  /** A recent blockhash */
-  recentBlockhash?: Blockhash | null;
+export type TransactionCtorFields_DEPRECATED = {
   /** Optional nonce information used for offline nonce'd transactions */
   nonceInfo?: NonceInformation | null;
   /** The transaction fee payer */
   feePayer?: PublicKey | null;
   /** One or more signatures */
   signatures?: Array<SignaturePubkeyPair>;
+  /** A recent blockhash */
+  recentBlockhash?: Blockhash;
+};
+
+/**
+ * List of Transaction object fields that may be initialized at construction
+ */
+export type TransactionBlockhashCtor = {
+  /** The transaction fee payer */
+  feePayer?: PublicKey | null;
+  /** One or more signatures */
+  signatures?: Array<SignaturePubkeyPair>;
+  /** A recent blockhash */
+  blockhash: Blockhash;
+  /** the last block chain can advance to before tx is declared expired */
+  lastValidBlockHeight: number;
 };
 
 /**
@@ -196,6 +215,11 @@ export class Transaction {
    */
   recentBlockhash?: Blockhash;
 
+  /**
+   * the last block chain can advance to before tx is declared expired
+   * */
+  lastValidBlockHeight?: number;
+
   /**
    * Optional Nonce information. If populated, transaction will use a durable
    * Nonce hash instead of a recentBlockhash. Must be populated by the caller
@@ -212,11 +236,35 @@ export class Transaction {
    */
   _json?: TransactionJSON;
 
+  // Construct a transaction with a blockhash and lastValidBlockHeight
+  constructor(opts?: TransactionBlockhashCtor);
+
+  /**
+   * @deprecated `TransactionCtorFields` has been deprecated and will be removed in a future version.
+   * Please supply a `TransactionBlockhashCtor` instead.
+   */
+  constructor(opts?: TransactionCtorFields_DEPRECATED);
+
   /**
    * Construct an empty Transaction
    */
-  constructor(opts?: TransactionCtorFields) {
-    opts && Object.assign(this, opts);
+  constructor(
+    opts?: TransactionBlockhashCtor | TransactionCtorFields_DEPRECATED,
+  ) {
+    if (!opts) {
+      return;
+    } else if (
+      Object.prototype.hasOwnProperty.call(opts, 'lastValidBlockHeight')
+    ) {
+      const newOpts = opts as TransactionBlockhashCtor;
+      Object.assign(this, newOpts);
+      this.recentBlockhash = newOpts.blockhash;
+      this.lastValidBlockHeight = newOpts.lastValidBlockHeight;
+    } else {
+      const oldOpts = opts as TransactionCtorFields_DEPRECATED;
+      Object.assign(this, oldOpts);
+      this.recentBlockhash = oldOpts.recentBlockhash;
+    }
   }
 
   /**
@@ -551,7 +599,6 @@ export class Transaction {
 
     const message = this._compile();
     this._partialSign(message, ...uniqueSigners);
-    this._verifySignatures(message.serialize(), true);
   }
 
   /**