refactor(experimental): add function to create a Solana RPC using only an URL (#2238)

lorisleiva · web-flow · commit cd0b6c616ded · 2024-03-04T15:34:16.000+05:00
This PR changes the `createSolanaRpc` function so that it accepts a `ClusterUrl` as a first parameter and an optional config object as a second parameter. This makes it much easier for 95% of RPC use-cases to get started with the library: ```ts const rpc = createSolanaRpc("http://localhost:8899"); // Cluster-aware RPCs: const rpc = createSolanaRpc(devnet("https://api.devnet.solana.com")); const rpc = createSolanaRpc(testnet("https://api.testnet.solana.com")); const rpc = createSolanaRpc(mainnet("https://api.mainnet-beta.solana.com")); // With configs: const rpc = createSolanaRpc("http://localhost:8899", { headers: myHeaders, dispatcher_NODE_ONLY: myDispatcher, }); ``` Additionally, this PR adds a `createSolanaRpcFromTransport` function that allows the remaining 5% of use-cases to customize their own transport just as easily: ```ts const rpc = createSolanaRpcFromTransport(myCustomTransport); ``` Note that `createSolanaRpcFromTransport` is cluster aware so, if `myCustomTransport` is of type `RpcTransportMainnet`, then `rpc` will automatically be of type `RpcMainnet<SolanaRpcApiMainnet>`. Finally, this PR refactors the cluster typetests to make it clearer what we are trying to tests. --- See #2119
diff --git a/packages/rpc/src/__tests__/rpc-integer-overflow-test.ts b/packages/rpc/src/__tests__/rpc-integer-overflow-test.ts
@@ -1,18 +1,18 @@
 import { SolanaError } from '@solana/errors';
 import type { RpcTransport } from '@solana/rpc-spec';
 
-import { createSolanaRpc } from '../rpc';
+import { createSolanaRpcFromTransport } from '../rpc';
 
 describe('RPC integer overflow behavior', () => {
-    let rpc: ReturnType<typeof createSolanaRpc>;
+    let rpc: ReturnType<typeof createSolanaRpcFromTransport>;
     beforeEach(() => {
         const transport = jest.fn(
             () =>
                 new Promise(_ => {
                     /* never resolve */
                 }),
         ) as RpcTransport;
-        rpc = createSolanaRpc({ transport });
+        rpc = createSolanaRpcFromTransport(transport);
     });
     it('does not throw when called with a value up to `Number.MAX_SAFE_INTEGER`', () => {
         expect(() => {
diff --git a/packages/rpc/src/__typetests__/rpc-clusters-typetest.ts b/packages/rpc/src/__typetests__/rpc-clusters-typetest.ts
@@ -2,7 +2,7 @@ import type { SolanaRpcApi, SolanaRpcApiDevnet, SolanaRpcApiMainnet, SolanaRpcAp
 import type { Rpc, RpcTransport } from '@solana/rpc-spec';
 import { devnet, mainnet, testnet } from '@solana/rpc-types';
 
-import { createSolanaRpc } from '../rpc';
+import { createSolanaRpc, createSolanaRpcFromTransport } from '../rpc';
 import type {
     RpcDevnet,
     RpcMainnet,
@@ -13,85 +13,165 @@ import type {
 } from '../rpc-clusters';
 import { createDefaultRpcTransport } from '../rpc-transport';
 
-// Creating default HTTP transports
+// Define cluster-aware URLs and transports.
 
 const genericUrl = 'http://localhost:8899';
 const devnetUrl = devnet('https://api.devnet.solana.com');
 const testnetUrl = testnet('https://api.testnet.solana.com');
 const mainnetUrl = mainnet('https://api.mainnet-beta.solana.com');
 
-// No cluster specified should be generic `RpcTransport`
-createDefaultRpcTransport({ url: genericUrl }) satisfies RpcTransport;
-//@ts-expect-error Should not be a devnet transport
-createDefaultRpcTransport({ url: genericUrl }) satisfies RpcTransportDevnet;
-//@ts-expect-error Should not be a testnet transport
-createDefaultRpcTransport({ url: genericUrl }) satisfies RpcTransportTestnet;
-//@ts-expect-error Should not be a mainnet transport
-createDefaultRpcTransport({ url: genericUrl }) satisfies RpcTransportMainnet;
-
-// Devnet cluster should be `RpcTransportDevnet`
-createDefaultRpcTransport({ url: devnetUrl }) satisfies RpcTransportDevnet;
-//@ts-expect-error Should not be a testnet transport
-createDefaultRpcTransport({ url: devnetUrl }) satisfies RpcTransportTestnet;
-//@ts-expect-error Should not be a mainnet transport
-createDefaultRpcTransport({ url: devnetUrl }) satisfies RpcTransportMainnet;
-
-// Testnet cluster should be `RpcTransportTestnet`
-createDefaultRpcTransport({ url: testnetUrl }) satisfies RpcTransportTestnet;
-//@ts-expect-error Should not be a devnet transport
-createDefaultRpcTransport({ url: testnetUrl }) satisfies RpcTransportDevnet;
-//@ts-expect-error Should not be a mainnet transport
-createDefaultRpcTransport({ url: testnetUrl }) satisfies RpcTransportMainnet;
-
-// Mainnet cluster should be `RpcTransportMainnet`
-createDefaultRpcTransport({ url: mainnetUrl }) satisfies RpcTransportMainnet;
-//@ts-expect-error Should not be a devnet transport
-createDefaultRpcTransport({ url: mainnetUrl }) satisfies RpcTransportDevnet;
-//@ts-expect-error Should not be a testnet transport
-createDefaultRpcTransport({ url: mainnetUrl }) satisfies RpcTransportTestnet;
-
-// Creating JSON RPC clients
-
 const genericTransport = createDefaultRpcTransport({ url: genericUrl });
 const devnetTransport = createDefaultRpcTransport({ url: devnetUrl });
 const testnetTransport = createDefaultRpcTransport({ url: testnetUrl });
 const mainnetTransport = createDefaultRpcTransport({ url: mainnetUrl });
 
-// No cluster specified should be generic `Rpc`
-createSolanaRpc({ transport: genericTransport }) satisfies Rpc<SolanaRpcApi>;
-//@ts-expect-error Should not be a devnet RPC
-createSolanaRpc({ transport: genericTransport }) satisfies RpcDevnet<SolanaRpcApi>;
-//@ts-expect-error Should not be a testnet RPC
-createSolanaRpc({ transport: genericTransport }) satisfies RpcTestnet<SolanaRpcApi>;
-//@ts-expect-error Should not be a mainnet RPC
-createSolanaRpc({ transport: genericTransport }) satisfies RpcMainnet<SolanaRpcApi>;
-
-// Devnet cluster should be `RpcDevnet`
-createSolanaRpc({ transport: devnetTransport }) satisfies Rpc<SolanaRpcApi>;
-createSolanaRpc({ transport: devnetTransport }) satisfies Rpc<SolanaRpcApiDevnet>;
-createSolanaRpc({ transport: devnetTransport }) satisfies RpcDevnet<SolanaRpcApi>;
-createSolanaRpc({ transport: devnetTransport }) satisfies RpcDevnet<SolanaRpcApiDevnet>; // Same types
-//@ts-expect-error Should not be a testnet RPC
-createSolanaRpc({ transport: devnetTransport }) satisfies RpcTestnet<SolanaRpcApi>;
-//@ts-expect-error Should not be a mainnet RPC
-createSolanaRpc({ transport: devnetTransport }) satisfies RpcMainnet<SolanaRpcApi>;
-
-// Testnet cluster should be `RpcTestnet`
-createSolanaRpc({ transport: testnetTransport }) satisfies Rpc<SolanaRpcApi>;
-createSolanaRpc({ transport: testnetTransport }) satisfies Rpc<SolanaRpcApiTestnet>;
-createSolanaRpc({ transport: testnetTransport }) satisfies RpcTestnet<SolanaRpcApi>;
-createSolanaRpc({ transport: testnetTransport }) satisfies RpcTestnet<SolanaRpcApiTestnet>; // Same types
-//@ts-expect-error Should not be a devnet RPC
-createSolanaRpc({ transport: testnetTransport }) satisfies RpcDevnet<SolanaRpcApi>;
-//@ts-expect-error Should not be a mainnet RPC
-createSolanaRpc({ transport: testnetTransport }) satisfies RpcMainnet<SolanaRpcApi>;
-
-// Mainnet cluster should be `RpcMainnet`
-createSolanaRpc({ transport: mainnetTransport }) satisfies Rpc<SolanaRpcApiMainnet>;
-createSolanaRpc({ transport: mainnetTransport }) satisfies RpcMainnet<SolanaRpcApiMainnet>;
-//@ts-expect-error Should not have `requestAirdrop` method
-createSolanaRpc({ transport: mainnetTransport }) satisfies Rpc<RequestAirdropApi>;
-//@ts-expect-error Should not be a devnet RPC
-createSolanaRpc({ transport: mainnetTransport }) satisfies RpcDevnet<SolanaRpcApi>;
-//@ts-expect-error Should not be a testnet RPC
-createSolanaRpc({ transport: mainnetTransport }) satisfies RpcTestnet<SolanaRpcApi>;
+// [DEFINE] createDefaultRpcTransport.
+{
+    // No cluster specified should be generic `RpcTransport`.
+    {
+        genericTransport satisfies RpcTransport;
+        //@ts-expect-error Should not be a devnet transport
+        genericTransport satisfies RpcTransportDevnet;
+        //@ts-expect-error Should not be a testnet transport
+        genericTransport satisfies RpcTransportTestnet;
+        //@ts-expect-error Should not be a mainnet transport
+        genericTransport satisfies RpcTransportMainnet;
+    }
+
+    // Devnet cluster should be `RpcTransportDevnet`.
+    {
+        devnetTransport satisfies RpcTransportDevnet;
+        //@ts-expect-error Should not be a testnet transport
+        devnetTransport satisfies RpcTransportTestnet;
+        //@ts-expect-error Should not be a mainnet transport
+        devnetTransport satisfies RpcTransportMainnet;
+    }
+
+    // Testnet cluster should be `RpcTransportTestnet`.
+    {
+        testnetTransport satisfies RpcTransportTestnet;
+        //@ts-expect-error Should not be a devnet transport
+        testnetTransport satisfies RpcTransportDevnet;
+        //@ts-expect-error Should not be a mainnet transport
+        testnetTransport satisfies RpcTransportMainnet;
+    }
+
+    // Mainnet cluster should be `RpcTransportMainnet`.
+    {
+        mainnetTransport satisfies RpcTransportMainnet;
+        //@ts-expect-error Should not be a devnet transport
+        mainnetTransport satisfies RpcTransportDevnet;
+        //@ts-expect-error Should not be a testnet transport
+        mainnetTransport satisfies RpcTransportTestnet;
+    }
+}
+
+// [DEFINE] createSolanaRpcFromTransport.
+{
+    const genericRpc = createSolanaRpcFromTransport(genericTransport);
+    const devnetRpc = createSolanaRpcFromTransport(devnetTransport);
+    const testnetRpc = createSolanaRpcFromTransport(testnetTransport);
+    const mainnetRpc = createSolanaRpcFromTransport(mainnetTransport);
+
+    // No cluster specified should be generic `Rpc`.
+    {
+        genericRpc satisfies Rpc<SolanaRpcApi>;
+        //@ts-expect-error Should not be a devnet RPC
+        genericRpc satisfies RpcDevnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a testnet RPC
+        genericRpc satisfies RpcTestnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a mainnet RPC
+        genericRpc satisfies RpcMainnet<SolanaRpcApi>;
+    }
+
+    // Devnet cluster should be `RpcDevnet`.
+    {
+        devnetRpc satisfies Rpc<SolanaRpcApi>;
+        devnetRpc satisfies Rpc<SolanaRpcApiDevnet>;
+        devnetRpc satisfies RpcDevnet<SolanaRpcApi>;
+        devnetRpc satisfies RpcDevnet<SolanaRpcApiDevnet>; // Same types
+        //@ts-expect-error Should not be a testnet RPC
+        devnetRpc satisfies RpcTestnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a mainnet RPC
+        devnetRpc satisfies RpcMainnet<SolanaRpcApi>;
+    }
+
+    // Testnet cluster should be `RpcTestnet`.
+    {
+        testnetRpc satisfies Rpc<SolanaRpcApi>;
+        testnetRpc satisfies Rpc<SolanaRpcApiTestnet>;
+        testnetRpc satisfies RpcTestnet<SolanaRpcApi>;
+        testnetRpc satisfies RpcTestnet<SolanaRpcApiTestnet>; // Same types
+        //@ts-expect-error Should not be a devnet RPC
+        testnetRpc satisfies RpcDevnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a mainnet RPC
+        testnetRpc satisfies RpcMainnet<SolanaRpcApi>;
+    }
+
+    // Mainnet cluster should be `RpcMainnet`.
+    {
+        mainnetRpc satisfies Rpc<SolanaRpcApiMainnet>;
+        mainnetRpc satisfies RpcMainnet<SolanaRpcApiMainnet>;
+        //@ts-expect-error Should not have `requestAirdrop` method
+        mainnetRpc satisfies Rpc<RequestAirdropApi>;
+        //@ts-expect-error Should not be a devnet RPC
+        mainnetRpc satisfies RpcDevnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a testnet RPC
+        mainnetRpc satisfies RpcTestnet<SolanaRpcApi>;
+    }
+}
+
+// [DEFINE] createSolanaRpc.
+{
+    const genericRpc = createSolanaRpc(genericUrl);
+    const devnetRpc = createSolanaRpc(devnetUrl);
+    const testnetRpc = createSolanaRpc(testnetUrl);
+    const mainnetRpc = createSolanaRpc(mainnetUrl);
+
+    // No cluster specified should be generic `Rpc`.
+    {
+        genericRpc satisfies Rpc<SolanaRpcApi>;
+        //@ts-expect-error Should not be a devnet RPC
+        genericRpc satisfies RpcDevnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a testnet RPC
+        genericRpc satisfies RpcTestnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a mainnet RPC
+        genericRpc satisfies RpcMainnet<SolanaRpcApi>;
+    }
+
+    // Devnet cluster should be `RpcDevnet`.
+    {
+        devnetRpc satisfies Rpc<SolanaRpcApi>;
+        devnetRpc satisfies Rpc<SolanaRpcApiDevnet>;
+        devnetRpc satisfies RpcDevnet<SolanaRpcApi>;
+        devnetRpc satisfies RpcDevnet<SolanaRpcApiDevnet>; // Same types
+        //@ts-expect-error Should not be a testnet RPC
+        devnetRpc satisfies RpcTestnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a mainnet RPC
+        devnetRpc satisfies RpcMainnet<SolanaRpcApi>;
+    }
+
+    // Testnet cluster should be `RpcTestnet`.
+    {
+        testnetRpc satisfies Rpc<SolanaRpcApi>;
+        testnetRpc satisfies Rpc<SolanaRpcApiTestnet>;
+        testnetRpc satisfies RpcTestnet<SolanaRpcApi>;
+        testnetRpc satisfies RpcTestnet<SolanaRpcApiTestnet>; // Same types
+        //@ts-expect-error Should not be a devnet RPC
+        testnetRpc satisfies RpcDevnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a mainnet RPC
+        testnetRpc satisfies RpcMainnet<SolanaRpcApi>;
+    }
+
+    // Mainnet cluster should be `RpcMainnet`.
+    {
+        mainnetRpc satisfies Rpc<SolanaRpcApiMainnet>;
+        mainnetRpc satisfies RpcMainnet<SolanaRpcApiMainnet>;
+        //@ts-expect-error Should not have `requestAirdrop` method
+        mainnetRpc satisfies Rpc<RequestAirdropApi>;
+        //@ts-expect-error Should not be a devnet RPC
+        mainnetRpc satisfies RpcDevnet<SolanaRpcApi>;
+        //@ts-expect-error Should not be a testnet RPC
+        mainnetRpc satisfies RpcTestnet<SolanaRpcApi>;
+    }
+}
diff --git 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<typeof createHttpTransport>[0];
-interface Config<TClusterUrl extends ClusterUrl> extends RpcTransportConfig {
+export interface DefaultRpcTransportConfig<TClusterUrl extends ClusterUrl> extends RpcTransportConfig {
     url: TClusterUrl;
 }
 
@@ -25,7 +25,7 @@ function normalizeHeaders<T extends Record<string, string>>(
 }
 
 export function createDefaultRpcTransport<TClusterUrl extends ClusterUrl>(
-    config: Config<TClusterUrl>,
+    config: DefaultRpcTransportConfig<TClusterUrl>,
 ): RpcTransportFromClusterUrl<TClusterUrl> {
     return pipe(
         createHttpTransport({
diff --git a/packages/rpc/src/rpc.ts b/packages/rpc/src/rpc.ts
@@ -1,16 +1,23 @@
 import { createSolanaRpcApi } from '@solana/rpc-api';
 import { createRpc, RpcTransport } from '@solana/rpc-spec';
+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';
 
-type RpcConfig<TTransport extends RpcTransport> = Readonly<{
-    transport: TTransport;
-}>;
+/** Creates a new Solana RPC using the default decorated HTTP transport. */
+export function createSolanaRpc<TClusterUrl extends ClusterUrl>(
+    clusterUrl: TClusterUrl,
+    config?: Omit<DefaultRpcTransportConfig<TClusterUrl>, 'url'>,
+) {
+    return createSolanaRpcFromTransport(createDefaultRpcTransport({ url: clusterUrl, ...config }));
+}
 
-export function createSolanaRpc<TTransport extends RpcTransport>(
-    config: RpcConfig<TTransport>,
-): RpcFromTransport<SolanaRpcApiFromTransport<TTransport>, TTransport> {
-    const api = createSolanaRpcApi(DEFAULT_RPC_CONFIG);
-    return createRpc({ ...config, api }) as RpcFromTransport<SolanaRpcApiFromTransport<TTransport>, TTransport>;
+/** Creates a new Solana RPC using a custom transport. */
+export function createSolanaRpcFromTransport<TTransport extends RpcTransport>(transport: TTransport) {
+    return createRpc({
+        api: createSolanaRpcApi(DEFAULT_RPC_CONFIG),
+        transport,
+    }) as RpcFromTransport<SolanaRpcApiFromTransport<TTransport>, TTransport>;
 }

Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ import { getRpcTransportWithRequestCoalescing } from './rpc-request-coalescer';`
`7`	`7`	`import { getSolanaRpcPayloadDeduplicationKey } from './rpc-request-deduplication';`
`8`	`8`
`9`	`9`	`type RpcTransportConfig = Parameters<typeof createHttpTransport>[0];`
`10`		`-interface Config<TClusterUrl extends ClusterUrl> extends RpcTransportConfig {`
	`10`	`+export interface DefaultRpcTransportConfig<TClusterUrl extends ClusterUrl> extends RpcTransportConfig {`
`11`	`11`	`url: TClusterUrl;`
`12`	`12`	`}`
`13`	`13`
`@@ -25,7 +25,7 @@ function normalizeHeaders<T extends Record<string, string>>(`
`25`	`25`	`}`
`26`	`26`
`27`	`27`	`export function createDefaultRpcTransport<TClusterUrl extends ClusterUrl>(`
`28`		`- config: Config<TClusterUrl>,`
	`28`	`+ config: DefaultRpcTransportConfig<TClusterUrl>,`
`29`	`29`	`): RpcTransportFromClusterUrl<TClusterUrl> {`
`30`	`30`	`return pipe(`
`31`	`31`	`createHttpTransport({`