github.com/anza-xyz/kit @v7.0.0
Chat with this repoWhat it actually does AI analysis from the code graph — generated when you open this
README
Kit
This is the JavaScript SDK for building Solana apps for Node, web, and React Native.
[!NOTE] Did you expect to find
@solana/web3.jshere? You're in the right place! We have renamed the 2.x line of@solana/web3.jsto@solana/kit.The code for the 1.x line of
@solana/web3.jscan be found here and the documentation here.
Installation
For use in a Node.js or web application:
npm install --save @solana/kit
For use in a browser, without a build system:
<script src="https://unpkg.com/@solana/kit/dist/index.development.js"></script>
<script src="https://unpkg.com/@solana/kit/dist/index.production.min.js"></script>
Quick Start
To get a feel for the API, run and modify the live examples in the examples/ directory. There, you will find a series of single-purpose Node scripts that demonstrate a specific feature or use case. You will also find a React application that you can run in a browser, that demonstrates being able to create, sign, and send transactions using browser wallets.
For a fully baked intro, see: Getting started with Solana kit
What's New in Kit
Kit is a response to many of the pain points you have communicated to us when developing Solana applications with web3.js.
Tree-Shakability
The object-oriented design of the web3.js (1.x) API prevents optimizing compilers from being able to ‘tree-shake’ unused code from your production builds. No matter how much of the web3.js API you use in your application, you have until now been forced to package all of it.
Read more about tree-shaking here:
- Mozilla Developer Docs: Tree Shaking
- WebPack Docs: Tree Shaking
- Web.Dev Blog Article: Reduce JavaScript Payloads with Tree Shaking
One example of an API that can’t be tree-shaken is the Connection class. It has dozens of methods, but because it’s a class you have no choice but to include every method in your application’s final bundle, no matter how many you actually use.
Needlessly large JavaScript bundles can cause issues with deployments to cloud compute providers like Cloudflare or AWS Lambda. They also impact webapp startup performance because of longer download and JavaScript parse times.
Kit is fully tree-shakable and will remain so, enforced by build-time checks. Optimizing compilers can now eliminate those parts of the library that your application does not use.
Kit is comprised of several smaller, modular packages under the @solana organization, including:
@solana/accounts: For fetching and decoding accounts@solana/codecs: For composing data (de)serializers from a set of primitives or building custom ones@solana/errors: For identifying and refining coded errors thrown in the@solananamespace@solana/rpc: For sending RPC requests@solana/rpc-subscriptions: For subscribing to RPC notifications@solana/signers: For building message and/or transaction signer objects@solana/sysvars: For fetching and decoding sysvar accounts@solana/transaction-messages: For building and transforming Solana transaction message objects@solana/transactions: For compiling and signing transactions for submission to the network- And many more!
Some of these packages are themselves composed of smaller packages. For instance, @solana/rpc is composed of @solana/rpc-spec (for core JSON RPC specification types), @solana/rpc-api (for the Solana-specific RPC methods), @solana/rpc-transport-http (for the default HTTP transport) and so on.
Developers can use the default configurations within the main library (@solana/kit) or import any of its subpackages where customization-through-composition is desired.
Composable Internals
Depending on your use case and your tolerance for certain application behaviours, you may wish to configure your application to make a different set of tradeoffs than another developer. The web3.js (1.x) API imposed a rigid set of common-case defaults on all developers, some of which were impossible to change.
The inability to customize web3.js up until now has been a source of frustration:
- The Mango team wanted to customize the transaction confirmation strategy, but all of that functionality is hidden away behind
confirmTransaction– a static method ofConnection. Here’s the code forconfirmTransactionon GitHub. - Solana developer ‘mPaella’ wanted us to add a feature in the RPC that would failover to a set of backup URLs in case the primary one failed.
- Solana developer ‘epicfaace’ wanted first-class support for automatic time-windowed batching in the RPC transport. Here’s their pull request.
- Multiple folks have expressed the need for custom retry logic for failed requests or transactions. Here’s a pull request from ‘dafyddd’ and another from ‘abrkn’ attempting to modify retry logic to suit their individual use cases.
Kit exposes far more of its internals, particularly where communication with an RPC is concerned, and allows willing developers the ability to compose new implementations from the default ones that manifest a nearly limitless array of customizations.
The individual modules that make up Kit are assembled in a default configuration reminiscent of the legacy library as part of the npm package @solana/kit, but those who wish to assemble them in different configurations may do so.
Generic types are offered in numerous places, allowing you to specify new functionality, to make extensions to each API via composition and supertypes, and to encourage you to create higher-level opinionated abstractions of your own.
In fact, we expect you to do so, and to open source some of those for use by others with similar needs.
Modern JavaScript; Zero-Dependency
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, and support has already landed in most modern JavaScript runtimes.
Engine support for bigint values has also become commonplace. The older number primitive in JavaScript has a maximum value of 2^53 - 1, whereas Rust’s u64 can represent values up to 2^64.
Kit eliminates userspace implementations of Ed25519 cryptography, large number polyfills, and more, in favour of custom implementations or the use of native JavaScript features, reducing the size of the library. It has no third-party dependencies.
Functional Architecture
The object oriented, class-based architecture of web3.js (1.x) causes unnecessary bundle bloat. Your application has no choice but to bundle all of the functionality and dependencies of a class no matter how many methods you actually use at runtime.
Class-based architecture also presents unique risks to developers who trigger the dual-package hazard. This describes a situation you can find yourself in if you build for both CommonJS and ES modules. It arises when two copies of the same class are present in the dependency tree, causing checks like instanceof to fail. This introduces aggravating and difficult to debug problems.
Read more about dual-package hazard:
Kit implements no classes (with the notable exception of the SolanaError class) and implements the thinnest possible interfaces at function boundaries.
Statistics
Consider these statistical comparisons between Kit and the legacy web3.js 1.x.
| 1.x (Legacy) | Kit | +/- % | |
|---|---|---|---|
| Total minified size of library | 81 KB | 57.5 KB | -29% |
| Total minified size of library (when runtime supports Ed25519) | 81 KB | 53 KB | -33% |
| Bundled size of a web application that executes a transfer of lamports | 111 KB | 23.9 KB | -78% |
| Bundled size of a web application that executes a transfer of lamports (when runtime supports Ed25519) | 111 KB | 18.2 KB | -83% |
| Performance of key generation, signing, and verifying signatures (Brave with Experimental API flag) | 700 ops/s | 7000 ops/s | +900% |
| First-load size for Solana Explorer | 311 KB | 228 KB | -26% |
The re-engineered library achieves these speedups and reductions in bundle size in large part through use of modern JavaScript APIs.
To validate our work, we replaced the legacy 1.x library with Kit on the homepage of the Solana Explorer. Total first-load bundle size dropped by 26% without removing a single feature. Here’s an X thread by Callum McIntyre if you would like to dig deeper.
A Tour of the Kit API
Here’s an overview of how to use the new library to interact with the RPC, configure network transports, work with Ed25519 keys, and to serialize data.
RPC
Kit ships with an implementation of the JSON RPC specification and a type spec for the Solana JSON RPC.
The main package responsible for managing communication with an RPC is @solana/rpc. However, this package makes use of more granular packages to break down the RPC logic into smaller pieces. Namely, these packages are:
@solana/rpc: Contains all logic related to sending Solana RPC calls.@solana/rpc-api: Describes all Solana RPC methods using types.@solana/rpc-transport-http: Provides a concrete implementation of an RPC transport using HTTP requests.@solana/rpc-spec: Defines the JSON RPC spec for sending RPC requests.@solana/rpc-spec-types: Shared JSON RPC specifications types and helpers that are used by both@solana/rpcand@solana/rpc-subscriptions(described in the next section).@solana/rpc-types: Shared Solana RPC types and helpers that are used by both@solana/rpcand@solana/rpc-subscriptions.
The main @solana/kit package re-exports the @solana/rpc package so, going forward, we will import RPC types and functions from the library directly.
RPC Calls
You can use the createSolanaRpc function by providing the URL of a Solana JSON RPC server. This will create a default client for interacting with the Solana JSON RPC API.
import { createSolanaRpc } from '@solana/kit';
// Create an RPC client.
const rpc = createSolanaRpc('http://127.0.0.1:8899');
// ^? Rpc<SolanaRpcApi>
// Send a request.
const slot = await rpc.getSlot().send();
Custom RPC Transports
The createSolanaRpc function communicates with the RPC server using a default HTTP transport that should satisfy most use cases. You can provide your own transport or wrap an existing one to communicate with RPC servers in any way you see fit. In the example below, we explicitly create a transport and use it to create a new RPC client via the createSolanaRpcFromTransport function.
import { createSolanaRpcFromTransport, createDefaultRpcTransport } from '@solana/kit';
// Create an HTTP transport or any custom transport of your choice.
const transport = createDefaultRpcTransport({ url: 'https://api.devnet.solana.com' });
// Create an RPC client using that transport.
const rpc = createSolanaRpcFromTransport(transport);
// ^? Rpc<SolanaRpcApi>
// Send a request.
const slot = await rpc.getSlot().send();
A custom transport can implement specialized functionality such as coordinating multiple transports, implementing retries, and more. Let's take a look at some concrete examples.
Round Robin
A ‘round robin’ transport is one that distributes requests to a list of endpoints in sequence.
```ts import { createDefaultRpcTransport, createSolanaRpcFromTransport, type RpcTransport } from '@solana/kit';
// Create an HTTP transport for each RPC server. const transports = [ createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-1.com' }), createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-2.com' }), createDefaultRpcTransport({ url: 'https://mainnet-beta.my-server-3.com' }), ];
// Set up the roun