@solana/web3.js 1.95.2 → 2.0.0-20241006045741

package/README.md

@@ -6,150 +6,165 @@
 
 [code-style-prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square
 [code-style-prettier-url]: https://github.com/prettier/prettier
-[npm-downloads-image]: https://img.shields.io/npm/dm/@solana/web3.js.svg?style=flat
-[npm-image]: https://img.shields.io/npm/v/@solana/web3.js.svg?style=flat
-[npm-url]: https://www.npmjs.com/package/@solana/web3.js
+[npm-downloads-image]: https://img.shields.io/npm/dm/@solana/web3.js/rc.svg?style=flat
+[npm-image]: https://img.shields.io/npm/v/@solana/web3.js/rc.svg?style=flat
+[npm-url]: https://www.npmjs.com/package/@solana/web3.js/v/rc
 [semantic-release-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
 [semantic-release-url]: https://github.com/semantic-release/semantic-release
 
-# Solana JavaScript SDK
+# @solana/web3.js
 
-Use this to interact with accounts and programs on the Solana network through the Solana [JSON RPC API](https://solana.com/docs/rpc).
+This is the JavaScript SDK for building Solana apps for Node, web, and React Native.
 
-## Installation
+## Functions
 
-### For use in Node.js or a web application
+In addition to reexporting functions from packages in the `@solana/*` namespace, this package offers additional helpers for building Solana applications, with sensible defaults.
 
-```
-$ npm install --save @solana/web3.js
-```
+### `airdropFactory({rpc, rpcSubscriptions})`
+
+Returns a function that you can call to airdrop a certain amount of `Lamports` to a Solana address.
 
-### For use in a browser, without a build system
+```ts
+import {
+    address,
+    airdropFactory,
+    createSolanaRpc,
+    createSolanaRpcSubscriptions,
+    devnet,
+    lamports,
+} from '@solana/web3.js';
 
-```html
-<!-- Development (un-minified) -->
-<script src="https://unpkg.com/@solana/web3.js@latest/lib/index.iife.js"></script>
+const rpc = createSolanaRpc(devnet('http://127.0.0.1:8899'));
+const rpcSubscriptions = createSolanaRpcSubscriptions(devnet('ws://127.0.0.1:8900'));
 
-<!-- Production (minified) -->
-<script src="https://unpkg.com/@solana/web3.js@latest/lib/index.iife.min.js"></script>
+const airdrop = airdropFactory({ rpc, rpcSubscriptions });
+
+await airdrop({
+    commitment: 'confirmed',
+    recipientAddress: address('FnHyam9w4NZoWR6mKN1CuGBritdsEWZQa4Z4oawLZGxa'),
+    lamports: lamports(10_000_000n),
+});
 ```
 
-## Documentation and examples
+> [!NOTE] This only works on test clusters.
 
-- [The Solana Cookbook](https://solanacookbook.com/) has extensive task-based documentation using this library.
-- For more detail on individual functions, see the [latest API Documentation](https://solana-labs.github.io/solana-web3.js)
+### `decodeTransactionMessage(compiledTransactionMessage, rpc, config)`
 
-## Getting help
+Returns a `TransactionMessage` from a `CompiledTransactionMessage`. If any of the accounts in the compiled message require an address lookup table to find their address, this function will use the supplied RPC instance to fetch the contents of the address lookup table from the network.
 
-Have a question or a problem? Check the [Solana Stack Exchange](https://solana.stackexchange.com) to see if anyone else is having the same one. If not, [post a new question](https://solana.stackexchange.com/questions/ask).
+### `fetchLookupTables(lookupTableAddresses, rpc, config)`
 
-Include:
+Given a list of addresses belonging to address lookup tables, returns a map of lookup table addresses to an ordered array of the addresses they contain.
 
-- A detailed description of what you're trying to achieve
-- Source code, if possible
-- The text of any errors you encountered, with stacktraces if available
+### `getComputeUnitEstimateForTransactionMessageFactory({rpc})`
 
-## Compatibility
+Correctly budgeting a compute unit limit for your transaction message can increase the probability that your transaction will be accepted for processing. If you don't declare a compute unit limit on your transaction, validators will assume an upper limit of 200K compute units (CU) per instruction.
 
-This library requires a JavaScript runtime that supports [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) and the [exponentiation operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Exponentiation). Both are supported in the following runtimes:
+Since validators have an incentive to pack as many transactions into each block as possible, they may choose to include transactions that they know will fit into the remaining compute budget for the current block over transactions that might not. For this reason, you should set a compute unit limit on each of your transaction messages, whenever possible.
 
-- Browsers, by [release date](https://caniuse.com/bigint):
-  - Chrome: May 2018
-  - Firefox: July 2019
-  - Safari: September 2020
-  - Mobile Safari: September 2020
-  - Edge: January 2020
-  - Opera: June 2018
-  - Samsung Internet: April 2019
-- Runtimes, [by version](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt):
-  - Deno: >=1.0
-  - Node: >=10.4.0
-- React Native:
-  - \>=0.7.0 using the [Hermes](https://reactnative.dev/blog/2022/07/08/hermes-as-the-default) engine ([integration guide](https://solanacookbook.com/integrations/react-native.html#how-to-use-solana-web3-js-in-a-react-native-app)):
+Use this utility to estimate the actual compute unit cost of a given transaction message.
 
-## Development environment setup
+```ts
+import { getSetComputeUnitLimitInstruction } from '@solana-program/compute-budget';
+import { createSolanaRpc, getComputeUnitEstimateForTransactionMessageFactory, pipe } from '@solana/web3.js';
 
-### Testing
+// Create an estimator function.
+const rpc = createSolanaRpc('http://127.0.0.1:8899');
+const getComputeUnitEstimateForTransactionMessage = getComputeUnitEstimateForTransactionMessageFactory({
+    rpc,
+});
 
-#### Unit tests
+// Create your transaction message.
+const transactionMessage = pipe(
+    createTransactionMessage({ version: 'legacy' }),
+    /* ... */
+);
 
-To run the full suite of unit tests, execute the following in the root:
+// Request an estimate of the actual compute units this message will consume.
+const computeUnitsEstimate = await getComputeUnitEstimateForTransactionMessage(transactionMessage);
 
-```shell
-$ npm test
+// Set the transaction message's compute unit budget.
+const transactionMessageWithComputeUnitLimit = prependTransactionMessageInstruction(
+    getSetComputeUnitLimitInstruction({ units: computeUnitsEstimate }),
+    transactionMessage,
+);
 ```
 
-#### Integration tests
+> [!WARNING]
+> The compute unit estimate is just that &ndash; an estimate. The compute unit consumption of the actual transaction might be higher or lower than what was observed in simulation. Unless you are confident that your particular transaction message will consume the same or fewer compute units as was estimated, you might like to augment the estimate by either a fixed number of CUs or a multiplier.
+
+> [!NOTE]
+> If you are preparing an _unsigned_ transaction, destined to be signed and submitted to the network by a wallet, you might like to leave it up to the wallet to determine the compute unit limit. Consider that the wallet might have a more global view of how many compute units certain types of transactions consume, and might be able to make better estimates of an appropriate compute unit budget.
+
+### `sendAndConfirmDurableNonceTransactionFactory({rpc, rpcSubscriptions})`
+
+Returns a function that you can call to send a nonce-based transaction to the network and to wait until it has been confirmed.
+
+```ts
+import {
+    isSolanaError,
+    sendAndConfirmDurableNonceTransactionFactory,
+    SOLANA_ERROR__INVALID_NONCE,
+    SOLANA_ERROR__NONCE_ACCOUNT_NOT_FOUND,
+} from '@solana/web3.js';
+
+const sendAndConfirmNonceTransaction = sendAndConfirmDurableNonceTransactionFactory({ rpc, rpcSubscriptions });
+
+try {
+    await sendAndConfirmNonceTransaction(transaction, { commitment: 'confirmed' });
+} catch (e) {
+    if (isSolanaError(e, SOLANA_ERROR__NONCE_ACCOUNT_NOT_FOUND)) {
+        console.error(
+            'The lifetime specified by this transaction refers to a nonce account ' +
+                `\`${e.context.nonceAccountAddress}\` that does not exist`,
+        );
+    } else if (isSolanaError(e, SOLANA_ERROR__INVALID_NONCE)) {
+        console.error('This transaction depends on a nonce that is no longer valid');
+    } else {
+        throw e;
+    }
+}
+```
 
-Integration tests require a validator client running on your machine.
+### `sendAndConfirmTransactionFactory({rpc, rpcSubscriptions})`
 
-To install a test validator:
+Returns a function that you can call to send a blockhash-based transaction to the network and to wait until it has been confirmed.
 
-```shell
-$ npm run test:live-with-test-validator:setup
-```
+```ts
+import { isSolanaError, sendAndConfirmTransactionFactory, SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED } from '@solana/web3.js';
 
-To start the test validator and run all of the integration tests in live mode:
+const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
 
-```shell
-$ cd packages/library-legacy
-$ npm run test:live-with-test-validator
+try {
+    await sendAndConfirmTransaction(transaction, { commitment: 'confirmed' });
+} catch (e) {
+    if (isSolanaError(e, SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED)) {
+        console.error('This transaction depends on a blockhash that has expired');
+    } else {
+        throw e;
+    }
+}
 ```
 
-### Speed up build times with remote caching
-
-Cache build artifacts remotely so that you, others, and the CI server can take advantage of each others' build efforts.
-
-1. Log the Turborepo CLI into the Solana Vercel account
-   ```shell
-   pnpm turbo login
-   ```
-2. Link the repository to the remote cache
-   ```shell
-   pnpm turbo link
-   ```
-
-## Contributing
-
-If you found a bug or would like to request a feature, please [file an issue](https://github.com/solana-labs/solana-web3.js/issues/new). If, based on the discussion on an issue you would like to offer a code change, please make a [pull request](https://github.com/solana-labs/solana-web3.js/compare). If neither of these describes what you would like to contribute, read the [getting help](#getting-help) section above.
-
-## Disclaimer
-
-All claims, content, designs, algorithms, estimates, roadmaps,
-specifications, and performance measurements described in this project
-are done with the Solana Foundation's ("SF") best efforts. It is up to
-the reader to check and validate their accuracy and truthfulness.
-Furthermore nothing in this project constitutes a solicitation for
-investment.
-
-Any content produced by SF or developer resources that SF provides, are
-for educational and inspiration purposes only. SF does not encourage,
-induce or sanction the deployment, integration or use of any such
-applications (including the code comprising the Solana blockchain
-protocol) in violation of applicable laws or regulations and hereby
-prohibits any such deployment, integration or use. This includes use of
-any such applications by the reader (a) in violation of export control
-or sanctions laws of the United States or any other applicable
-jurisdiction, (b) if the reader is located in or ordinarily resident in
-a country or territory subject to comprehensive sanctions administered
-by the U.S. Office of Foreign Assets Control (OFAC), or (c) if the
-reader is or is working on behalf of a Specially Designated National
-(SDN) or a person subject to similar blocking or denied party
-prohibitions.
-
-The reader should be aware that U.S. export control and sanctions laws
-prohibit U.S. persons (and other persons that are subject to such laws)
-from transacting with persons in certain countries and territories or
-that are on the SDN list. As a project based primarily on open-source
-software, it is possible that such sanctioned persons may nevertheless
-bypass prohibitions, obtain the code comprising the Solana blockchain
-protocol (or other project code or applications) and deploy, integrate,
-or otherwise use it. Accordingly, there is a risk to individuals that
-other persons using the Solana blockchain protocol may be sanctioned
-persons and that transactions with such persons would be a violation of
-U.S. export controls and sanctions law. This risk applies to
-individuals, organizations, and other ecosystem participants that
-deploy, integrate, or use the Solana blockchain protocol code directly
-(e.g., as a node operator), and individuals that transact on the Solana
-blockchain through light clients, third party interfaces, and/or wallet
-software.
+### `sendTransactionWithoutConfirmingFactory({rpc, rpcSubscriptions})`
+
+Returns a function that you can call to send a transaction with any kind of lifetime to the network without waiting for it to be confirmed.
+
+```ts
+import {
+    sendTransactionWithoutConfirmingFactory,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
+} from '@solana/web3.js';
+
+const sendTransaction = sendTransactionWithoutConfirmingFactory({ rpc });
+
+try {
+    await sendTransaction(transaction, { commitment: 'confirmed' });
+} catch (e) {
+    if (isSolanaError(e, SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE)) {
+        console.error('The transaction failed in simulation', e.cause);
+    } else {
+        throw e;
+    }
+}
+```