@solana/web3.js 1.68.1 → 1.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/web3.js",
-  "version": "1.68.1",
+  "version": "1.70.0",
   "description": "Solana Javascript API",
   "keywords": [
     "api",
@@ -51,7 +51,7 @@
     "pretty": "prettier --check '{,{src,test}/**/}*.{j,t}s'",
     "pretty:fix": "prettier --write '{,{src,test}/**/}*.{j,t}s'",
     "re": "semantic-release --repository-url git@github.com:solana-labs/solana-web3.js.git",
-    "test": "cross-env TS_NODE_COMPILER_OPTIONS='{ \"module\": \"commonjs\", \"target\": \"es2019\" }' ts-mocha --require esm './test/**/*.test.ts'",
+    "test": "cross-env NODE_ENV=test TS_NODE_COMPILER_OPTIONS='{ \"module\": \"commonjs\", \"target\": \"es2019\" }' ts-mocha --require esm './test/**/*.test.ts'",
     "test:cover": "nyc --reporter=lcov npm run test",
     "test:live": "TEST_LIVE=1 npm run test",
     "test:live-with-test-validator": "start-server-and-test 'solana-test-validator --reset --quiet' http://localhost:8899/health test:live"
@@ -95,7 +95,7 @@
     "@types/express-serve-static-core": "^4.17.21",
     "@types/mocha": "^10.0.0",
     "@types/mz": "^2.7.3",
-    "@types/node": "^17.0.24",
+    "@types/node": "^18.11.10",
     "@types/node-fetch": "2",
     "@types/sinon": "^10.0.0",
     "@types/sinon-chai": "^3.2.8",
@@ -114,6 +114,7 @@
     "mocha": "^10.1.0",
     "mockttp": "^2.0.1",
     "mz": "^2.7.0",
+    "node-abort-controller": "^3.0.1",
     "npm-run-all": "^4.1.5",
     "nyc": "^15.1.0",
     "prettier": "^2.3.0",
@@ -129,8 +130,8 @@
     "ts-mocha": "^10.0.0",
     "ts-node": "^10.0.0",
     "tslib": "^2.1.0",
-    "typedoc": "^0.22.2",
-    "typescript": "^4.3.2"
+    "typedoc": "^0.23",
+    "typescript": "^4.9"
   },
   "engines": {
     "node": ">=12.20.0"

package/src/connection.ts

@@ -2,6 +2,8 @@ import bs58 from 'bs58';
 import {Buffer} from 'buffer';
 // @ts-ignore
 import fastStableStringify from 'fast-stable-stringify';
+import type {Agent as HttpAgent} from 'http';
+import {Agent as HttpsAgent} from 'https';
 import {
   type as pick,
   number,
@@ -311,9 +313,39 @@ export type BlockhashWithExpiryBlockHeight = Readonly<{
  * A strategy for confirming transactions that uses the last valid
  * block height for a given blockhash to check for transaction expiration.
  */
-export type BlockheightBasedTransactionConfirmationStrategy = {
+export type BlockheightBasedTransactionConfirmationStrategy =
+  BaseTransactionConfirmationStrategy & BlockhashWithExpiryBlockHeight;
+
+/**
+ * A strategy for confirming durable nonce transactions.
+ */
+export type DurableNonceTransactionConfirmationStrategy =
+  BaseTransactionConfirmationStrategy & {
+    /**
+     * 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;
+  };
+
+/**
+ * Properties shared by all transaction confirmation strategies
+ */
+export type BaseTransactionConfirmationStrategy = Readonly<{
+  /** A signal that, when aborted, cancels any outstanding transaction confirmation operations */
+  abortSignal?: AbortSignal;
   signature: TransactionSignature;
-} & BlockhashWithExpiryBlockHeight;
+}>;
 
 /* @internal */
 function assertEndpointUrl(putativeUrl: string) {
@@ -340,28 +372,6 @@ 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
  */
@@ -1442,11 +1452,47 @@ function createRpcClient(
   customFetch?: FetchFn,
   fetchMiddleware?: FetchMiddleware,
   disableRetryOnRateLimit?: boolean,
+  httpAgent?: HttpAgent | HttpsAgent | false,
 ): RpcClient {
   const fetch = customFetch ? customFetch : fetchImpl;
-  let agentManager: AgentManager | undefined;
-  if (!process.env.BROWSER) {
-    agentManager = new AgentManager(url.startsWith('https:') /* useHttps */);
+  let agentManager:
+    | {requestEnd(): void; requestStart(): HttpAgent | HttpsAgent}
+    | undefined;
+  if (process.env.BROWSER) {
+    if (httpAgent != null) {
+      console.warn(
+        'You have supplied an `httpAgent` when creating a `Connection` in a browser environment.' +
+          'It has been ignored; `httpAgent` is only used in Node environments.',
+      );
+    }
+  } else {
+    if (httpAgent == null) {
+      if (process.env.NODE_ENV !== 'test') {
+        agentManager = new AgentManager(
+          url.startsWith('https:') /* useHttps */,
+        );
+      }
+    } else {
+      if (httpAgent !== false) {
+        const isHttps = url.startsWith('https:');
+        if (isHttps && !(httpAgent instanceof HttpsAgent)) {
+          throw new Error(
+            'The endpoint `' +
+              url +
+              '` can only be paired with an `https.Agent`. You have, instead, supplied an ' +
+              '`http.Agent` through `httpAgent`.',
+          );
+        } else if (!isHttps && httpAgent instanceof HttpsAgent) {
+          throw new Error(
+            'The endpoint `' +
+              url +
+              '` can only be paired with an `http.Agent`. You have, instead, supplied an ' +
+              '`https.Agent` through `httpAgent`.',
+          );
+        }
+        agentManager = {requestEnd() {}, requestStart: () => httpAgent};
+      }
+    }
   }
 
   let fetchWithMiddleware: FetchFn | undefined;
@@ -2847,6 +2893,12 @@ export type FetchMiddleware = (
  * Configuration for instantiating a Connection
  */
 export type ConnectionConfig = {
+  /**
+   * An `http.Agent` that will be used to manage socket connections (eg. to implement connection
+   * persistence). Set this to `false` to create a connection that uses no agent. This applies to
+   * Node environments only.
+   */
+  httpAgent?: HttpAgent | HttpsAgent | false;
   /** Optional commitment level */
   commitment?: Commitment;
   /** Optional endpoint URL to the fullnode JSON RPC PubSub WebSocket Endpoint */
@@ -2964,6 +3016,7 @@ export class Connection {
     let fetch;
     let fetchMiddleware;
     let disableRetryOnRateLimit;
+    let httpAgent;
     if (commitmentOrConfig && typeof commitmentOrConfig === 'string') {
       this._commitment = commitmentOrConfig;
     } else if (commitmentOrConfig) {
@@ -2975,6 +3028,7 @@ export class Connection {
       fetch = commitmentOrConfig.fetch;
       fetchMiddleware = commitmentOrConfig.fetchMiddleware;
       disableRetryOnRateLimit = commitmentOrConfig.disableRetryOnRateLimit;
+      httpAgent = commitmentOrConfig.httpAgent;
     }
 
     this._rpcEndpoint = assertEndpointUrl(endpoint);
@@ -2986,6 +3040,7 @@ export class Connection {
       fetch,
       fetchMiddleware,
       disableRetryOnRateLimit,
+      httpAgent,
     );
     this._rpcRequest = createRpcRequest(this._rpcClient);
     this._rpcBatchRequest = createRpcBatchRequest(this._rpcClient);
@@ -3571,6 +3626,9 @@ export class Connection {
       const config = strategy as
         | BlockheightBasedTransactionConfirmationStrategy
         | DurableNonceTransactionConfirmationStrategy;
+      if (config.abortSignal?.aborted) {
+        return Promise.reject(config.abortSignal.reason);
+      }
       rawSignature = config.signature;
     }
 
@@ -3602,6 +3660,21 @@ export class Connection {
     }
   }
 
+  private getCancellationPromise(signal?: AbortSignal): Promise<never> {
+    return new Promise<never>((_, reject) => {
+      if (signal == null) {
+        return;
+      }
+      if (signal.aborted) {
+        reject(signal.reason);
+      } else {
+        signal.addEventListener('abort', () => {
+          reject(signal.reason);
+        });
+      }
+    });
+  }
+
   private getTransactionConfirmationPromise({
     commitment,
     signature,
@@ -3722,7 +3795,7 @@ export class Connection {
 
   private async confirmTransactionUsingBlockHeightExceedanceStrategy({
     commitment,
-    strategy: {lastValidBlockHeight, signature},
+    strategy: {abortSignal, lastValidBlockHeight, signature},
   }: {
     commitment?: Commitment;
     strategy: BlockheightBasedTransactionConfirmationStrategy;
@@ -3753,9 +3826,14 @@ export class Connection {
     });
     const {abortConfirmation, confirmationPromise} =
       this.getTransactionConfirmationPromise({commitment, signature});
+    const cancellationPromise = this.getCancellationPromise(abortSignal);
     let result: RpcResponseAndContext<SignatureResult>;
     try {
-      const outcome = await Promise.race([confirmationPromise, expiryPromise]);
+      const outcome = await Promise.race([
+        cancellationPromise,
+        confirmationPromise,
+        expiryPromise,
+      ]);
       if (outcome.__type === TransactionStatus.PROCESSED) {
         result = outcome.response;
       } else {
@@ -3770,7 +3848,13 @@ export class Connection {
 
   private async confirmTransactionUsingDurableNonceStrategy({
     commitment,
-    strategy: {minContextSlot, nonceAccountPubkey, nonceValue, signature},
+    strategy: {
+      abortSignal,
+      minContextSlot,
+      nonceAccountPubkey,
+      nonceValue,
+      signature,
+    },
   }: {
     commitment?: Commitment;
     strategy: DurableNonceTransactionConfirmationStrategy;
@@ -3821,9 +3905,14 @@ export class Connection {
     });
     const {abortConfirmation, confirmationPromise} =
       this.getTransactionConfirmationPromise({commitment, signature});
+    const cancellationPromise = this.getCancellationPromise(abortSignal);
     let result: RpcResponseAndContext<SignatureResult>;
     try {
-      const outcome = await Promise.race([confirmationPromise, expiryPromise]);
+      const outcome = await Promise.race([
+        cancellationPromise,
+        confirmationPromise,
+        expiryPromise,
+      ]);
       if (outcome.__type === TransactionStatus.PROCESSED) {
         result = outcome.response;
       } else {

package/src/epoch-schedule.ts

@@ -26,7 +26,7 @@ function nextPowerOfTwo(n: number) {
 /**
  * Epoch schedule
  * (see https://docs.solana.com/terminology#epoch)
- * Can be retrieved with the {@link connection.getEpochSchedule} method
+ * Can be retrieved with the {@link Connection.getEpochSchedule} method
  */
 export class EpochSchedule {
   /** The maximum number of slots in each epoch */

package/src/utils/send-and-confirm-transaction.ts

@@ -19,7 +19,11 @@ export async function sendAndConfirmTransaction(
   connection: Connection,
   transaction: Transaction,
   signers: Array<Signer>,
-  options?: ConfirmOptions,
+  options?: ConfirmOptions &
+    Readonly<{
+      // A signal that, when aborted, cancels any outstanding transaction confirmation operations
+      abortSignal?: AbortSignal;
+    }>,
 ): Promise<TransactionSignature> {
   const sendOptions = options && {
     skipPreflight: options.skipPreflight,
@@ -42,6 +46,7 @@ export async function sendAndConfirmTransaction(
     status = (
       await connection.confirmTransaction(
         {
+          abortSignal: options?.abortSignal,
           signature: signature,
           blockhash: transaction.recentBlockhash,
           lastValidBlockHeight: transaction.lastValidBlockHeight,
@@ -58,6 +63,7 @@ export async function sendAndConfirmTransaction(
     status = (
       await connection.confirmTransaction(
         {
+          abortSignal: options?.abortSignal,
           minContextSlot: transaction.minNonceContextSlot,
           nonceAccountPubkey,
           nonceValue: transaction.nonceInfo.nonce,
@@ -67,6 +73,13 @@ export async function sendAndConfirmTransaction(
       )
     ).value;
   } else {
+    if (options?.abortSignal != null) {
+      console.warn(
+        'sendAndConfirmTransaction(): A transaction with a deprecated confirmation strategy was ' +
+          'supplied along with an `abortSignal`. Only transactions having `lastValidBlockHeight` ' +
+          'or a combination of `nonceInfo` and `minNonceContextSlot` are abortable.',
+      );
+    }
     status = (
       await connection.confirmTransaction(
         signature,