From 21761b9c2acb9564a7aa815febbbe0f764c41528 Mon Sep 17 00:00:00 2001 From: steveluscher Date: Fri, 26 Jul 2024 19:30:30 +0000 Subject: [PATCH] Update the README for `@solana/rpc` --- packages/rpc/README.md | 106 ++++++++++++++++++++++++- packages/rpc/src/index.ts | 1 + packages/rpc/src/rpc-clusters.ts | 1 - packages/rpc/src/rpc-default-config.ts | 4 +- packages/rpc/src/rpc-transport.ts | 2 +- packages/rpc/src/rpc.ts | 6 +- 6 files changed, 114 insertions(+), 6 deletions(-) diff --git a/packages/rpc/README.md b/packages/rpc/README.md index 559e43cf1487..ca513cbd54f3 100644 --- a/packages/rpc/README.md +++ b/packages/rpc/README.md @@ -14,4 +14,108 @@ # @solana/rpc -TODO +This package contains utilities for creating objects that you can use to communicate with a Solana JSON RPC server. It can be used standalone, but it is also exported as part of the Solana JavaScript SDK [`@solana/web3.js@experimental`](https://github.com/solana-labs/solana-web3.js/tree/master/packages/library). + +## Types + +### `RpcTransport{Devnet|Testnet|Mainnet}` + +These types refine the base `RpcTransport` type. Each describes a transport that is specific in some way to a particular Solana cluster. + +For instance, a `RpcTransportDevnet` is understood to communicate with a RPC server related to devnet, and as such might only be accepted for use as the transport of a `RpcDevnet`. + +This is useful in cases where you need to make assertions about what capabilities a RPC offers. For example, RPC methods like `requestAirdrop` are not available on mainnet. You can use the ability to assert on the type of RPC transport at compile time to prevent calling unimplemented methods or presuming the existence of unavailable capabilities. + +### `RpcTransportFromClusterUrl` + +Given a `ClusterUrl`, this utility type will resolve to as specific a `RpcTransport` as possible. + +```ts +function createCustomTransport( + clusterUrl: TClusterUrl, +): RpcTransportFromClusterUrl { + /* ... */ +} +const transport = createCustomTransport(testnet('http://api.testnet.solana.com')); +transport satisfies RpcTransportTestnet; // OK +``` + +### `Rpc{Devnet|Testnet|Mainnet}` + +These types refine the base `Rpc` type. Each describes a RPC that is specific in some way to a particular Solana cluster and a corpus of RPC methods. + +This is useful in cases where you need to make assertions about the suitablilty of a RPC for a given purpose. For example, you might like to make it a type error to combine certain types with RPC belonging to certain clusters, at compile time. + +```ts +async function getSpecialAccountInfo( + address: Address<'ReAL1111111111111111111111111111'>, + rpc: RpcMainnet, +): Promise; +async function getSpecialAccountInfo( + address: Address<'TeST1111111111111111111111111111'>, + rpc: RpcDevnet | RpcTestnet, +): Promise; +async function getSpecialAccountInfo(address: Address, rpc: Rpc): Promise { + /* ... */ +} +const rpc = getSolanaRpc({ url: devnet('https://api.devnet.solana.com') }); +await getSpecialAccountInfo(address('TeST1111111111111111111111111111'), rpc); // ERROR +``` + +### `RpcFromTransport` + +Given a `RpcTransport`, this utility type will resolve to as specific a `Rpc` as possible. + +```ts +function createCustomRpc( + transport: TRpcTransport, +): RpcFromTransport { + /* ... */ +} +const transport = createDefaultRpcTransport({ url: mainnet('http://rpc.company') }); +transport satisfies RpcTransportMainnet; // OK +const rpc = createCustomRpc(transport); +rpc satisfies RpcMainnet; // OK +``` + +### SolanaRpcApiFromTransport + +## Constants + +### `DEFAULT_RPC_CONFIG` + +When you create `Rpc` instances with custom transports but otherwise the default RPC API behaviours, use this. + +```ts +const myCustomRpc = createRpc({ + api: createSolanaRpcApi(DEFAULT_RPC_CONFIG), + transport: myCustomTransport, +}); +``` + +## Functions + +### `createDefaultRpcTransport(config)` + +Creates a `RpcTransport` with some default behaviours. + +The default behaviours include: + +- An automatically-set `Solana-Client` request header, containing the version of `@solana/web3.js` +- Logic that coalesces multiple calls in the same runloop, for the same methods with the same arguments, into a single network request. + +#### Arguments + +A config object with the following properties: + +- `dispatcher_NODE_ONLY`: An optional `Undici.Dispatcher` instance that governs how the networking stack should behave. This option is only relevant in Node applications. Consult the documentation for the various subclasses of `Undici.Dispatcher`, such as `Agent`, `Client`, and `Pool`, at https://undici.nodejs.org/#/docs/api/Client. +- `headers`: An optional object where the keys are HTTP header names and the values are HTTP header values. This parameter is typed to disallow certain headers from being overwritten. +- `url`: A `ClusterUrl` at which the RPC server can be contacted. + +### `createSolanaRpc(clusterUrl, config)` + +Creates a `Rpc` instance that exposes the Solana JSON RPC API given a cluster URL and some optional transport config. See `createDefaultRpcTransport` for the shape of the transport config. + +### `createSolanaRpcFromTransport(transport)` + +Creates a `Rpc` instance that exposes the Solana JSON RPC API given the supplied `RpcTransport`. diff --git a/packages/rpc/src/index.ts b/packages/rpc/src/index.ts index a53cabe6c4d4..26b7f47639d9 100644 --- a/packages/rpc/src/index.ts +++ b/packages/rpc/src/index.ts @@ -2,5 +2,6 @@ export * from '@solana/rpc-api'; export * from '@solana/rpc-spec'; export * from './rpc'; +export * from './rpc-default-config'; export * from './rpc-clusters'; export * from './rpc-transport'; diff --git a/packages/rpc/src/rpc-clusters.ts b/packages/rpc/src/rpc-clusters.ts index b4beea4bdbf1..348317a65010 100644 --- a/packages/rpc/src/rpc-clusters.ts +++ b/packages/rpc/src/rpc-clusters.ts @@ -5,7 +5,6 @@ import type { ClusterUrl, DevnetUrl, MainnetUrl, TestnetUrl } from '@solana/rpc- export type RpcTransportDevnet = RpcTransport & { '~cluster': 'devnet' }; export type RpcTransportTestnet = RpcTransport & { '~cluster': 'testnet' }; export type RpcTransportMainnet = RpcTransport & { '~cluster': 'mainnet' }; -export type RpcTransportWithCluster = RpcTransportDevnet | RpcTransportMainnet | RpcTransportTestnet; export type RpcTransportFromClusterUrl = TClusterUrl extends DevnetUrl ? RpcTransportDevnet : TClusterUrl extends TestnetUrl diff --git a/packages/rpc/src/rpc-default-config.ts b/packages/rpc/src/rpc-default-config.ts index 6dee7f603dc1..776f635c2667 100644 --- a/packages/rpc/src/rpc-default-config.ts +++ b/packages/rpc/src/rpc-default-config.ts @@ -2,9 +2,9 @@ import type { createSolanaRpcApi } from '@solana/rpc-api'; import { createSolanaJsonRpcIntegerOverflowError } from './rpc-integer-overflow-error'; -export const DEFAULT_RPC_CONFIG: Partial[0]> = { +export const DEFAULT_RPC_CONFIG: Partial[0]>> = { defaultCommitment: 'confirmed', onIntegerOverflow(methodName, keyPath, value) { throw createSolanaJsonRpcIntegerOverflowError(methodName, keyPath, value); }, -}; +} as const; diff --git a/packages/rpc/src/rpc-transport.ts b/packages/rpc/src/rpc-transport.ts index adcb7b3d9a3e..40b1f25166f4 100644 --- a/packages/rpc/src/rpc-transport.ts +++ b/packages/rpc/src/rpc-transport.ts @@ -7,7 +7,7 @@ import { getRpcTransportWithRequestCoalescing } from './rpc-request-coalescer'; import { getSolanaRpcPayloadDeduplicationKey } from './rpc-request-deduplication'; type RpcTransportConfig = Parameters[0]; -export interface DefaultRpcTransportConfig extends RpcTransportConfig { +interface DefaultRpcTransportConfig extends RpcTransportConfig { url: TClusterUrl; } diff --git a/packages/rpc/src/rpc.ts b/packages/rpc/src/rpc.ts index 9b47483215cd..97e2fbb7e2ba 100644 --- a/packages/rpc/src/rpc.ts +++ b/packages/rpc/src/rpc.ts @@ -4,7 +4,11 @@ import { ClusterUrl } from '@solana/rpc-types'; import type { RpcFromTransport, SolanaRpcApiFromTransport } from './rpc-clusters'; import { DEFAULT_RPC_CONFIG } from './rpc-default-config'; -import { createDefaultRpcTransport, DefaultRpcTransportConfig } from './rpc-transport'; +import { createDefaultRpcTransport } from './rpc-transport'; + +type DefaultRpcTransportConfig = Parameters< + typeof createDefaultRpcTransport +>[0]; /** Creates a new Solana RPC using the default decorated HTTP transport. */ export function createSolanaRpc(