@solana/web3.js 2.0.0-experimental.ffeddf6 → 2.0.0-preview.1

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);
 ```
@@ -576,21 +616,21 @@ Operations on `CryptoKey` objects using the Web Crypto API *or* the polyfill are
 
 ### String Addresses
 
-All addresses are now JavaScript strings. They are represented by the opaque type `Base58EncodedAddress`, which describes exactly what a Solana address actually is.
+All addresses are now JavaScript strings. They are represented by the opaque type `Address`, which describes exactly what a Solana address actually is.
 
 Consequently, that means no more `PublicKey`. 
 
 Here’s what they look like in development:
 
 ```tsx
-import { address, getAddressFromPublicKey, generateKeyPair, Base58EncodedAddress } from '@solana/web3.js';
+import { Address, address, getAddressFromPublicKey, generateKeyPair } from '@solana/web3.js';
 
-// Coerce a string to a `Base58EncodedAddress`
+// Coerce a string to an `Address`
 const myOtherAddress = address('AxZfZWeqztBCL37Mkjkd4b8Hf6J13WCcfozrBY6vZzv3');
 
 // Typecast it instead
 const myAddress =
-    'AxZfZWeqztBCL37Mkjkd4b8Hf6J13WCcfozrBY6vZzv3' as Base58EncodedAddress<'AxZfZWeqztBCL37Mkjkd4b8Hf6J13WCcfozrBY6vZzv3'>;
+    'AxZfZWeqztBCL37Mkjkd4b8Hf6J13WCcfozrBY6vZzv3' as Address<'AxZfZWeqztBCL37Mkjkd4b8Hf6J13WCcfozrBY6vZzv3'>;
 
 // From CryptoKey
 const keyPair = await generateKeyPair();
@@ -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';
@@ -744,6 +784,8 @@ Solana’s codecs libraries are broken up into modular components so you only ne
 - `@solana/codecs-data-structures`: Codecs and serializers for structs
 - `@solana/options`: Designed to build codecs and serializers for types that mimic Rust’s enums, which can include embedded data within their variants such as values, tuples, and structs
 
+These packages are included in the main `@solana/web3.js` library but you may also import them from `@solana/codecs` if you only need the codecs.
+
 Here’s an example of encoding and decoding a custom struct with some strings and numbers:
 
 ```tsx
@@ -770,7 +812,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 +911,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:
 
@@ -958,15 +1000,15 @@ const signature = rpc.requestAirdrop(myAddress, airdropAmount).send();With the n
 
 You will have noticed by now that web3.js is a complete and total breaking change from the 1.x line. We want to provide you with a strategy for interacting with 1.x APIs while building your application using 2.0. You need a tool for commuting between 1.x and 2.0 data types.
 
-The `@solana/compat` library allows for interoperability between functions and class objects from the legacy library - such as `VersionedTransaction`, `PublicKey`, and `Keypair` - and functions and types of the new library - such as `Transaction`, `Base58EncodedAddress`, and `CryptoKeyPair`.
+The `@solana/compat` library allows for interoperability between functions and class objects from the legacy library - such as `VersionedTransaction`, `PublicKey`, and `Keypair` - and functions and types of the new library - such as `Address`, `Transaction`, and `CryptoKeyPair`.
 
-Here’s how you can use `@solana/compat` to convert from a legacy `PublicKey` to a `Base58EncodedAddress`:
+Here’s how you can use `@solana/compat` to convert from a legacy `PublicKey` to an `Address`:
 
 ```tsx
 import { fromLegacyPublicKey } from '@solana/compat';
 
 const publicKey = new PublicKey('B3piXWBQLLRuk56XG5VihxR4oe2PSsDM8nTF6s1DeVF5');
-const base58Address: Base58EncodedAddress = fromLegacyPublicKey(publicKey);
+const address: Address = fromLegacyPublicKey(publicKey);
 ```
 
 Here’s how to convert from a legacy `Keypair` to a `CryptoKeyPair`: