@solana/web3.js 2.0.0-experimental.63683a4 → 2.0.0-experimental.6466d76

package/README.md

@@ -34,17 +34,17 @@ In response to your feedback, we began a process of modernizing the library to p
 ### For use in Node.js or a web application
 
 ```shell
-npm install --save @solana/web3.js@ts
+npm install --save @solana/web3.js@tp
 ```
 
 ### For use in a browser, without a build system
 
 ```html
 <!-- Development (debug mode, unminified) -->
-<script src="https://unpkg.com/@solana/web3.js@ts/dist/index.development.js"></script>
+<script src="https://unpkg.com/@solana/web3.js@tp/dist/index.development.js"></script>
 
 <!-- Production (minified) -->
-<script src="https://unpkg.com/@solana/web3.js@ts/dist/index.production.min.js"></script>
+<script src="https://unpkg.com/@solana/web3.js@tp/dist/index.production.min.js"></script>
 ```
 
 What follows is an overview of *why* the library was re-engineered, what changes have been introduced, and how the JavaScript landscape might look across Solana in the near future.
@@ -80,7 +80,7 @@ The inability to customize web3.js has been a source of frustration for some:
 
 ## Lagging Behind Modern JavaScript
 
-The advance of modern JavaScript features presents an opportunity to developers of crypto applcations, such as the ability to use native Ed25519 keys and to express large values as native `bigint`.
+The advance of modern JavaScript features presents an opportunity to developers of crypto applications, such as the ability to use native Ed25519 keys and to express large values as native `bigint`.
 
 The Web Incubator Community Group has advocated for the addition of Ed25519 support to the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API), and support has already landed in *most* modern JavaScript runtimes.
 
@@ -102,7 +102,7 @@ Enter web3.js 2.0. The new API aims to deliver a re-imagined experience of build
 
 ## Features
 
-The new (2.0) version of `@solana/web3.js` aims to address shortcomings in the legacy library first, then goes even further .
+The new (2.0) version of `@solana/web3.js` aims to address shortcomings in the legacy library first, then goes even further.
 
 ### Tree-Shaking
 
@@ -251,8 +251,7 @@ const rpc = createJsonRpc<SolanaRpcMethods>({ api, transport });
 If you want to, you can also reduce the scope of the API’s type-spec so you are left only with the types you need. Keep in mind types don’t affect bundle size, but you may choose to scope the type-spec for a variety of reasons, including reducing TypeScript noise.
 
 ```tsx
-import { createSolanaRpcApi } from '@solana/rpc-core';
-import type { GetAccountInfoApi } from '@solana/rpc-core/dist/types/rpc-methods/getAccountInfo';
+import { createSolanaRpcApi, type GetAccountInfoApi } from '@solana/rpc-core';
 import { createHttpTransport, createJsonRpc } from '@solana/rpc-transport';
 
 const api = createSolanaRpcApi();
@@ -325,8 +324,7 @@ Here’s an example of how someone might implement a “round robin” approach
 
 ```tsx
 import { createSolanaRpcApi } from '@solana/rpc-core';
-import { createJsonRpc } from '@solana/rpc-transport';
-import { IRpcTransport } from '@solana/rpc-transport/dist/types/transports/transport-types';
+import { createJsonRpc, type IRpcTransport } from '@solana/rpc-transport';
 import { createDefaultRpcTransport } from '@solana/web3.js';
 
 // Create a transport for each RPC server
@@ -364,7 +362,50 @@ Another example of a possible customization for RPC transports is sharding. Here
 The transport library can also be used to implement custom retry logic on any request:
 
 ```tsx
-// TODO: Your turn; send us a pull request with an example.
+import { createDefaultRpcTransport } from '@solana/web3.js';
+import { createJsonRpc, IRpcTransport } from '@solana/rpc-transport';
+import { createSolanaRpcApi } from '@solana/rpc-core';
+
+// Set the maximum number of attempts to retry a request
+const MAX_ATTEMPTS = 4;
+
+// Create the default transport
+const defaultTransport = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-1.com' });
+
+// Sleep function to wait for a given number of milliseconds
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Calculate the delay for a given attempt
+function calculateRetryDelay(attempt: number): number {
+  // Exponential backoff with a maximum of 1.5 seconds
+  return Math.min(100 * Math.pow(2, attempt), 1500);
+}
+
+// A retrying transport that will retry up to MAX_ATTEMPTS times before failing
+async function retryingTransport<TResponse>(...args: Parameters<IRpcTransport>): Promise<TResponse> {
+  let requestError;
+  for (let attempts = 0; attempts < MAX_ATTEMPTS; attempts++) {
+    try {
+      return await defaultTransport(...args);
+    } catch (err) {
+      requestError = err;
+      // Only sleep if we have more attempts remaining
+      if (attempts < MAX_ATTEMPTS - 1) {
+        const retryDelay = calculateRetryDelay(attempts);
+        await sleep(retryDelay);
+      }
+    }
+  }
+  throw requestError;
+}
+
+// Create the RPC client
+const rpc = createJsonRpc({
+  api: createSolanaRpcApi(),
+  transport: retryingTransport,
+});
 ```
 
 ### Failover
@@ -381,15 +422,14 @@ Perhaps your application needs to make a large number of requests, or needs to f
 
 ```tsx
 import { createSolanaRpcApi } from '@solana/rpc-core';
-import { createJsonRpc } from '@solana/rpc-transport';
-import { IRpcTransport } from '@solana/rpc-transport/dist/types/transports/transport-types';
+import { createJsonRpc, IRpcTransport } from '@solana/rpc-transport';
 import { createDefaultRpcTransport } from '@solana/web3.js';
 
 // Create multiple transports
-const transportA = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-1.com' }));
-const transportB = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-2.com' }));
-const transportC = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-3.com' }));
-const transportD = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-4.com' }));
+const transportA = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-1.com' });
+const transportB = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-2.com' });
+const transportC = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-3.com' });
+const transportD = createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-4.com' });
 
 // Function to determine which shard to use based on the request method
 function selectShard(method: string): IRpcTransport {
@@ -507,7 +547,7 @@ for await (const notification of accountNotifications) {
 
 One of the most crucial aspects of any subscription API is managing potential missed messages. Missing messages, such as account state updates, could be catastrophic for an application. That’s why the new library provides native support for recovering missed messages using the `AsyncIterator`.
 
-When a connection fails unexpectedly, any messages you miss while disconnected can result in your UI falling behind or becoming corrupt. Because subscription failure is now made explicit in the new API, you can implement ‘catch up’ logic after re-estabilshing the subscription.
+When a connection fails unexpectedly, any messages you miss while disconnected can result in your UI falling behind or becoming corrupt. Because subscription failure is now made explicit in the new API, you can implement ‘catch up’ logic after re-establishing the subscription.
 
 Here’s an example of such logic:
 
@@ -548,7 +588,7 @@ const keyPair: CryptoKeyPair = await generateKeyPair();
 const message = new Uint8Array(8).fill(0);
 
 const signedMessage = await signBytes(keyPair.privateKey, message);
-//    ^ Ed25519Signature
+//    ^ Signature
 
 const verified = await verifySignature(keyPair.publicKey, signedMessage, message);
 ```
@@ -710,7 +750,7 @@ const transactionSignedWithFeePayer = await signTransaction([signer], transactio
 
 Transaction objects are also ********frozen by these functions******** to prevent transactions from being mutated in place by functions you pass them to.
 
-Building transactions in this manner might feel different to what you’re used to. Also, we certainly wouldn’t want you to have to bind transformed transactions to a new variable at each step, so we have released a functional programming library dubbed `@solana/functional` that lets you build transactions in **********************************pipelines**********************************. Here’s how it can be used:
+Building transactions in this manner might feel different from what you’re used to. Also, we certainly wouldn’t want you to have to bind transformed transactions to a new variable at each step, so we have released a functional programming library dubbed `@solana/functional` that lets you build transactions in **********************************pipelines**********************************. Here’s how it can be used:
 
 ```tsx
 import { pipe } from '@solana/functional';
@@ -770,7 +810,7 @@ const myToken = {
 };
 
 const myEncodedToken: Uint8Array = structCodec.encode(myToken);
-const myDecodedToken = structCodec.decode(myEncodedToken)[0];
+const myDecodedToken = structCodec.decode(myEncodedToken);
 
 myDecodedToken satisfies {
   amount: bigint;
@@ -869,7 +909,7 @@ const blockWithRewardsAndTransactionsResponse = await rpc.getBlock(0n, {
 
 ### Catching Compile-Time Bugs with TypeScript
 
-As previously mentioned, the type coverage in web3.js 2.0 allow developers to catch common bugs at compile time, rather than runtime.
+As previously mentioned, the type coverage in web3.js 2.0 allows developers to catch common bugs at compile time, rather than runtime.
 
 In the example below, a transaction is created and then attempted to be compiled without setting the fee payer. This would result in a runtime error from the RPC, but instead you will see a type error from TypeScript as you type:
 

package/dist/index.browser.cjs

@@ -1,11 +1,12 @@
 'use strict';
 
+var accounts = require('@solana/accounts');
 var addresses = require('@solana/addresses');
+var functional = require('@solana/functional');
 var instructions = require('@solana/instructions');
 var keys = require('@solana/keys');
 var rpcTypes = require('@solana/rpc-types');
 var transactions = require('@solana/transactions');
-var functional = require('@solana/functional');
 var rpcCore = require('@solana/rpc-core');
 var rpcTransport = require('@solana/rpc-transport');
 var fastStableStringify = require('fast-stable-stringify');
@@ -175,23 +176,30 @@ async function requestAndConfirmAirdrop({
 
 // src/rpc-integer-overflow-error.ts
 var SolanaJsonRpcIntegerOverflowError = class extends Error {
+  methodName;
+  keyPath;
+  value;
   constructor(methodName, keyPath, value) {
-    const argPosition = (typeof keyPath[0] === "number" ? keyPath[0] : parseInt(keyPath[0], 10)) + 1;
-    let ordinal = "";
-    const lastDigit = argPosition % 10;
-    const lastTwoDigits = argPosition % 100;
-    if (lastDigit == 1 && lastTwoDigits != 11) {
-      ordinal = argPosition + "st";
-    } else if (lastDigit == 2 && lastTwoDigits != 12) {
-      ordinal = argPosition + "nd";
-    } else if (lastDigit == 3 && lastTwoDigits != 13) {
-      ordinal = argPosition + "rd";
+    let argumentLabel = "";
+    if (typeof keyPath[0] === "number") {
+      const argPosition = keyPath[0] + 1;
+      const lastDigit = argPosition % 10;
+      const lastTwoDigits = argPosition % 100;
+      if (lastDigit == 1 && lastTwoDigits != 11) {
+        argumentLabel = argPosition + "st";
+      } else if (lastDigit == 2 && lastTwoDigits != 12) {
+        argumentLabel = argPosition + "nd";
+      } else if (lastDigit == 3 && lastTwoDigits != 13) {
+        argumentLabel = argPosition + "rd";
+      } else {
+        argumentLabel = argPosition + "th";
+      }
     } else {
-      ordinal = argPosition + "th";
+      argumentLabel = `\`${keyPath[0].toString()}\``;
     }
     const path = keyPath.length > 1 ? keyPath.slice(1).map((pathPart) => typeof pathPart === "number" ? `[${pathPart}]` : pathPart).join(".") : null;
     super(
-      `The ${ordinal} argument to the \`${methodName}\` RPC method${path ? ` at path \`${path}\`` : ""} was \`${value}\`. This number is unsafe for use with the Solana JSON-RPC because it exceeds \`Number.MAX_SAFE_INTEGER\`.`
+      `The ${argumentLabel} argument to the \`${methodName}\` RPC method${path ? ` at path \`${path}\`` : ""} was \`${value}\`. This number is unsafe for use with the Solana JSON-RPC because it exceeds \`Number.MAX_SAFE_INTEGER\`.`
     );
     this.keyPath = keyPath;
     this.methodName = methodName;
@@ -204,6 +212,7 @@ var SolanaJsonRpcIntegerOverflowError = class extends Error {
 
 // src/rpc-default-config.ts
 var DEFAULT_RPC_CONFIG = {
+  defaultCommitment: "confirmed",
   onIntegerOverflow(methodName, keyPath, value) {
     throw new SolanaJsonRpcIntegerOverflowError(methodName, keyPath, value);
   }
@@ -363,11 +372,11 @@ function getRpcSubscriptionsWithSubscriptionCoalescing({
             return {
               ...iterable,
               async *[Symbol.asyncIterator]() {
-                abortPromise || (abortPromise = abortSignal.aborted ? Promise.reject(EXPLICIT_ABORT_TOKEN) : new Promise((_, reject) => {
+                abortPromise ||= abortSignal.aborted ? Promise.reject(EXPLICIT_ABORT_TOKEN) : new Promise((_, reject) => {
                   abortSignal.addEventListener("abort", () => {
                     reject(EXPLICIT_ABORT_TOKEN);
                   });
-                }));
+                });
                 try {
                   const iterator = iterable[Symbol.asyncIterator]();
                   while (true) {
@@ -610,22 +619,52 @@ function createDefaultRpcSubscriptionsTransport(config) {
 }
 
 // src/transaction-confirmation-strategy-blockheight.ts
-function createBlockHeightExceedencePromiseFactory(rpcSubscriptions) {
-  return async function getBlockHeightExceedencePromise({ abortSignal: callerAbortSignal, lastValidBlockHeight }) {
+function createBlockHeightExceedencePromiseFactory({
+  rpc,
+  rpcSubscriptions
+}) {
+  return async function getBlockHeightExceedencePromise({
+    abortSignal: callerAbortSignal,
+    commitment,
+    lastValidBlockHeight
+  }) {
     const abortController = new AbortController();
-    function handleAbort() {
+    const handleAbort = () => {
       abortController.abort();
-    }
+    };
     callerAbortSignal.addEventListener("abort", handleAbort, { signal: abortController.signal });
-    const slotNotifications = await rpcSubscriptions.slotNotifications().subscribe({ abortSignal: abortController.signal });
+    async function getBlockHeightAndDifferenceBetweenSlotHeightAndBlockHeight() {
+      const { absoluteSlot, blockHeight } = await rpc.getEpochInfo({ commitment }).send({ abortSignal: abortController.signal });
+      return {
+        blockHeight,
+        differenceBetweenSlotHeightAndBlockHeight: absoluteSlot - blockHeight
+      };
+    }
     try {
-      for await (const slotNotification of slotNotifications) {
-        if (slotNotification.slot > lastValidBlockHeight) {
-          throw new Error(
-            "The network has progressed past the last block for which this transaction could have committed."
-          );
+      const [slotNotifications, { blockHeight, differenceBetweenSlotHeightAndBlockHeight }] = await Promise.all([
+        rpcSubscriptions.slotNotifications().subscribe({ abortSignal: abortController.signal }),
+        getBlockHeightAndDifferenceBetweenSlotHeightAndBlockHeight()
+      ]);
+      if (blockHeight <= lastValidBlockHeight) {
+        let lastKnownDifferenceBetweenSlotHeightAndBlockHeight = differenceBetweenSlotHeightAndBlockHeight;
+        for await (const slotNotification of slotNotifications) {
+          const { slot } = slotNotification;
+          if (slot - lastKnownDifferenceBetweenSlotHeightAndBlockHeight > lastValidBlockHeight) {
+            const {
+              blockHeight: currentBlockHeight,
+              differenceBetweenSlotHeightAndBlockHeight: currentDifferenceBetweenSlotHeightAndBlockHeight
+            } = await getBlockHeightAndDifferenceBetweenSlotHeightAndBlockHeight();
+            if (currentBlockHeight > lastValidBlockHeight) {
+              break;
+            } else {
+              lastKnownDifferenceBetweenSlotHeightAndBlockHeight = currentDifferenceBetweenSlotHeightAndBlockHeight;
+            }
+          }
         }
       }
+      throw new Error(
+        "The network has progressed past the last block for which this transaction could have been committed."
+      );
     } finally {
       abortController.abort();
     }
@@ -652,7 +691,7 @@ function createNonceInvalidationPromiseFactory(rpc, rpcSubscriptions) {
     function getNonceFromAccountData([base64EncodedBytes]) {
       const data = base64Encoder.encode(base64EncodedBytes);
       const nonceValueBytes = data.slice(NONCE_VALUE_OFFSET, NONCE_VALUE_OFFSET + 32);
-      return base58Decoder.decode(nonceValueBytes)[0];
+      return base58Decoder.decode(nonceValueBytes);
     }
     const nonceAccountDidAdvancePromise = (async () => {
       for await (const accountNotification of accountNotifications) {
@@ -717,7 +756,10 @@ function createDefaultRecentTransactionConfirmer({
   rpc,
   rpcSubscriptions
 }) {
-  const getBlockHeightExceedencePromise = createBlockHeightExceedencePromiseFactory(rpcSubscriptions);
+  const getBlockHeightExceedencePromise = createBlockHeightExceedencePromiseFactory({
+    rpc,
+    rpcSubscriptions
+  });
   const getRecentSignatureConfirmationPromise = createRecentSignatureConfirmationPromiseFactory(
     rpc,
     rpcSubscriptions
@@ -750,10 +792,16 @@ async function waitForRecentTransactionConfirmation(config) {
   await raceStrategies(
     transactions.getSignatureFromTransaction(config.transaction),
     config,
-    function getSpecificStrategiesForRace({ abortSignal, getBlockHeightExceedencePromise, transaction }) {
+    function getSpecificStrategiesForRace({
+      abortSignal,
+      commitment,
+      getBlockHeightExceedencePromise,
+      transaction
+    }) {
       return [
         getBlockHeightExceedencePromise({
           abortSignal,
+          commitment,
           lastValidBlockHeight: transaction.lifetimeConstraint.lastValidBlockHeight
         })
       ];
@@ -893,12 +941,24 @@ exports.sendAndConfirmDurableNonceTransaction = sendAndConfirmDurableNonceTransa
 exports.sendAndConfirmTransaction = sendAndConfirmTransaction;
 exports.waitForDurableNonceTransactionConfirmation = waitForDurableNonceTransactionConfirmation;
 exports.waitForRecentTransactionConfirmation = waitForRecentTransactionConfirmation;
+Object.keys(accounts).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return accounts[k]; }
+  });
+});
 Object.keys(addresses).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
     enumerable: true,
     get: function () { return addresses[k]; }
   });
 });
+Object.keys(functional).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return functional[k]; }
+  });
+});
 Object.keys(instructions).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
     enumerable: true,