@solana/rpc-spec 6.3.1 → 6.3.2-canary-20260313112147
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +5 -4
- package/src/index.ts +23 -0
- package/src/rpc-api.ts +136 -0
- package/src/rpc-transport.ts +55 -0
- package/src/rpc.ts +103 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@solana/rpc-spec",
|
|
3
|
-
"version": "6.3.
|
|
3
|
+
"version": "6.3.2-canary-20260313112147",
|
|
4
4
|
"description": "A generic implementation of JSON RPCs using proxies",
|
|
5
5
|
"homepage": "https://www.solanakit.com/api#solanarpc-spec",
|
|
6
6
|
"exports": {
|
|
@@ -33,7 +33,8 @@
|
|
|
33
33
|
"types": "./dist/types/index.d.ts",
|
|
34
34
|
"type": "commonjs",
|
|
35
35
|
"files": [
|
|
36
|
-
"./dist/"
|
|
36
|
+
"./dist/",
|
|
37
|
+
"./src/"
|
|
37
38
|
],
|
|
38
39
|
"sideEffects": false,
|
|
39
40
|
"keywords": [
|
|
@@ -55,8 +56,8 @@
|
|
|
55
56
|
"maintained node versions"
|
|
56
57
|
],
|
|
57
58
|
"dependencies": {
|
|
58
|
-
"@solana/errors": "6.3.
|
|
59
|
-
"@solana/rpc-spec-types": "6.3.
|
|
59
|
+
"@solana/errors": "6.3.2-canary-20260313112147",
|
|
60
|
+
"@solana/rpc-spec-types": "6.3.2-canary-20260313112147"
|
|
60
61
|
},
|
|
61
62
|
"peerDependencies": {
|
|
62
63
|
"typescript": "^5.0.0"
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This package contains types that describe the implementation of the JSON RPC API, as well as
|
|
3
|
+
* methods to create one. It can be used standalone, but it is also exported as part of Kit
|
|
4
|
+
* [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
|
|
5
|
+
*
|
|
6
|
+
* This API is designed to be used as follows:
|
|
7
|
+
*
|
|
8
|
+
* ```ts
|
|
9
|
+
* const rpc =
|
|
10
|
+
* // Step 1 - Create a `Rpc` instance. This may be stateful.
|
|
11
|
+
* createSolanaRpc(mainnet('https://api.mainnet-beta.solana.com'));
|
|
12
|
+
* const response = await rpc
|
|
13
|
+
* // Step 2 - Call supported methods on it to produce `PendingRpcRequest` objects.
|
|
14
|
+
* .getLatestBlockhash({ commitment: 'confirmed' })
|
|
15
|
+
* // Step 3 - Call the `send()` method on those pending requests to trigger them.
|
|
16
|
+
* .send({ abortSignal: AbortSignal.timeout(10_000) });
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* @packageDocumentation
|
|
20
|
+
*/
|
|
21
|
+
export * from './rpc';
|
|
22
|
+
export * from './rpc-api';
|
|
23
|
+
export * from './rpc-transport';
|
package/src/rpc-api.ts
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import {
|
|
2
|
+
Callable,
|
|
3
|
+
createRpcMessage,
|
|
4
|
+
RpcRequestTransformer,
|
|
5
|
+
RpcResponse,
|
|
6
|
+
RpcResponseTransformer,
|
|
7
|
+
} from '@solana/rpc-spec-types';
|
|
8
|
+
|
|
9
|
+
import type { RpcTransport } from './rpc-transport';
|
|
10
|
+
|
|
11
|
+
export type RpcApiConfig = Readonly<{
|
|
12
|
+
/**
|
|
13
|
+
* An optional function that transforms the {@link RpcRequest} before it is sent to the JSON RPC
|
|
14
|
+
* server.
|
|
15
|
+
*
|
|
16
|
+
* This is useful when the params supplied by the caller need to be transformed before
|
|
17
|
+
* forwarding the message to the server. Use cases for this include applying defaults,
|
|
18
|
+
* forwarding calls to renamed methods, and serializing complex values.
|
|
19
|
+
*/
|
|
20
|
+
requestTransformer?: RpcRequestTransformer;
|
|
21
|
+
/**
|
|
22
|
+
* An optional function that transforms the {@link RpcResponse} before it is returned to the
|
|
23
|
+
* caller.
|
|
24
|
+
*
|
|
25
|
+
* Use cases for this include constructing complex data types from serialized data, and throwing
|
|
26
|
+
* exceptions.
|
|
27
|
+
*/
|
|
28
|
+
responseTransformer?: RpcResponseTransformer;
|
|
29
|
+
}>;
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* This type allows an {@link RpcApi} to describe how a particular request should be issued to the
|
|
33
|
+
* JSON RPC server.
|
|
34
|
+
*
|
|
35
|
+
* Given a function that was called on a {@link Rpc}, this object exposes an `execute` function that
|
|
36
|
+
* dictates which request will be sent, how the underlying transport will be used, and how the
|
|
37
|
+
* responses will be transformed.
|
|
38
|
+
*
|
|
39
|
+
* This function accepts a {@link RpcTransport} and an `AbortSignal` and asynchronously returns a
|
|
40
|
+
* {@link RpcResponse}. This gives us the opportunity to:
|
|
41
|
+
*
|
|
42
|
+
* - define the `payload` from the requested method name and parameters before passing it to the
|
|
43
|
+
* transport.
|
|
44
|
+
* - call the underlying transport zero, one or multiple times depending on the use-case (e.g.
|
|
45
|
+
* caching or aggregating multiple responses).
|
|
46
|
+
* - transform the response from the JSON RPC server, in case it does not match the `TResponse`
|
|
47
|
+
* specified by the {@link PendingRpcRequest | PendingRpcRequest<TResponse>} returned from that
|
|
48
|
+
* function.
|
|
49
|
+
*/
|
|
50
|
+
export type RpcPlan<TResponse> = {
|
|
51
|
+
execute: (
|
|
52
|
+
config: Readonly<{
|
|
53
|
+
signal?: AbortSignal;
|
|
54
|
+
transport: RpcTransport;
|
|
55
|
+
}>,
|
|
56
|
+
) => Promise<RpcResponse<TResponse>>;
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* For each of `TRpcMethods`, this object exposes a method with the same name that maps between its
|
|
61
|
+
* input arguments and a {@link RpcPlan | RpcPlan<TResponse>} that implements the execution of a
|
|
62
|
+
* JSON RPC request to fetch `TResponse`.
|
|
63
|
+
*/
|
|
64
|
+
export type RpcApi<TRpcMethods> = {
|
|
65
|
+
[MethodName in keyof TRpcMethods]: RpcReturnTypeMapper<TRpcMethods[MethodName]>;
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
type RpcReturnTypeMapper<TRpcMethod> = TRpcMethod extends Callable
|
|
69
|
+
? (...rawParams: unknown[]) => RpcPlan<ReturnType<TRpcMethod>>
|
|
70
|
+
: never;
|
|
71
|
+
|
|
72
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
73
|
+
type RpcApiMethod = (...args: any) => any;
|
|
74
|
+
interface RpcApiMethods {
|
|
75
|
+
[methodName: string]: RpcApiMethod;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Creates a JavaScript proxy that converts _any_ function call called on it to a {@link RpcPlan} by
|
|
80
|
+
* creating an `execute` function that:
|
|
81
|
+
*
|
|
82
|
+
* - sets the transport payload to a JSON RPC v2 payload object with the requested `methodName` and
|
|
83
|
+
* `params` properties, optionally transformed by {@link RpcApiConfig.requestTransformer}.
|
|
84
|
+
* - transforms the transport's response using the {@link RpcApiConfig.responseTransformer}
|
|
85
|
+
* function, if provided.
|
|
86
|
+
*
|
|
87
|
+
* @example
|
|
88
|
+
* ```ts
|
|
89
|
+
* // For example, given this `RpcApi`:
|
|
90
|
+
* const rpcApi = createJsonRpcApi({
|
|
91
|
+
* requestTransformer: (...rawParams) => rawParams.reverse(),
|
|
92
|
+
* responseTransformer: response => response.result,
|
|
93
|
+
* });
|
|
94
|
+
*
|
|
95
|
+
* // ...the following function call:
|
|
96
|
+
* rpcApi.foo('bar', { baz: 'bat' });
|
|
97
|
+
*
|
|
98
|
+
* // ...will produce a `RpcPlan` that:
|
|
99
|
+
* // - Uses the following payload: { id: 1, jsonrpc: '2.0', method: 'foo', params: [{ baz: 'bat' }, 'bar'] }.
|
|
100
|
+
* // - Returns the "result" property of the RPC response.
|
|
101
|
+
* ```
|
|
102
|
+
*/
|
|
103
|
+
export function createJsonRpcApi<TRpcMethods extends RpcApiMethods>(config?: RpcApiConfig): RpcApi<TRpcMethods> {
|
|
104
|
+
return new Proxy({} as RpcApi<TRpcMethods>, {
|
|
105
|
+
defineProperty() {
|
|
106
|
+
return false;
|
|
107
|
+
},
|
|
108
|
+
deleteProperty() {
|
|
109
|
+
return false;
|
|
110
|
+
},
|
|
111
|
+
get<TMethodName extends keyof RpcApi<TRpcMethods>>(
|
|
112
|
+
...args: Parameters<NonNullable<ProxyHandler<RpcApi<TRpcMethods>>['get']>>
|
|
113
|
+
) {
|
|
114
|
+
const [_, p] = args;
|
|
115
|
+
const methodName = p.toString() as keyof TRpcMethods as string;
|
|
116
|
+
return function (
|
|
117
|
+
...rawParams: Parameters<
|
|
118
|
+
TRpcMethods[TMethodName] extends CallableFunction ? TRpcMethods[TMethodName] : never
|
|
119
|
+
>
|
|
120
|
+
): RpcPlan<ReturnType<TRpcMethods[TMethodName]>> {
|
|
121
|
+
const rawRequest = Object.freeze({ methodName, params: rawParams });
|
|
122
|
+
const request = config?.requestTransformer ? config?.requestTransformer(rawRequest) : rawRequest;
|
|
123
|
+
return Object.freeze(<RpcPlan<ReturnType<TRpcMethods[TMethodName]>>>{
|
|
124
|
+
execute: async ({ signal, transport }) => {
|
|
125
|
+
const payload = createRpcMessage(request);
|
|
126
|
+
const response = await transport({ payload, signal });
|
|
127
|
+
if (!config?.responseTransformer) {
|
|
128
|
+
return response;
|
|
129
|
+
}
|
|
130
|
+
return config.responseTransformer(response, request);
|
|
131
|
+
},
|
|
132
|
+
});
|
|
133
|
+
};
|
|
134
|
+
},
|
|
135
|
+
});
|
|
136
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { RpcResponse } from '@solana/rpc-spec-types';
|
|
2
|
+
|
|
3
|
+
type Config = Readonly<{
|
|
4
|
+
/** A value of arbitrary type to be sent to a RPC server */
|
|
5
|
+
payload: unknown;
|
|
6
|
+
/**
|
|
7
|
+
* An optional `AbortSignal` on which the `'abort'` event will be fired if the request should be
|
|
8
|
+
* cancelled.
|
|
9
|
+
*/
|
|
10
|
+
signal?: AbortSignal;
|
|
11
|
+
}>;
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* A function that can act as a transport for a {@link Rpc}. It need only return a promise for a
|
|
15
|
+
* response given the supplied config.
|
|
16
|
+
*/
|
|
17
|
+
export type RpcTransport = {
|
|
18
|
+
<TResponse>(config: Config): Promise<RpcResponse<TResponse>>;
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Returns `true` if the given payload is a JSON RPC v2 payload.
|
|
23
|
+
*
|
|
24
|
+
* This means, the payload is an object such that:
|
|
25
|
+
*
|
|
26
|
+
* - It has a `jsonrpc` property with a value of `'2.0'`.
|
|
27
|
+
* - It has a `method` property that is a string.
|
|
28
|
+
* - It has a `params` property of any type.
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```ts
|
|
32
|
+
* import { isJsonRpcPayload } from '@solana/rpc-spec';
|
|
33
|
+
*
|
|
34
|
+
* if (isJsonRpcPayload(payload)) {
|
|
35
|
+
* const payloadMethod: string = payload.method;
|
|
36
|
+
* const payloadParams: unknown = payload.params;
|
|
37
|
+
* }
|
|
38
|
+
* ```
|
|
39
|
+
*/
|
|
40
|
+
export function isJsonRpcPayload(payload: unknown): payload is Readonly<{
|
|
41
|
+
jsonrpc: '2.0';
|
|
42
|
+
method: string;
|
|
43
|
+
params: unknown;
|
|
44
|
+
}> {
|
|
45
|
+
if (payload == null || typeof payload !== 'object' || Array.isArray(payload)) {
|
|
46
|
+
return false;
|
|
47
|
+
}
|
|
48
|
+
return (
|
|
49
|
+
'jsonrpc' in payload &&
|
|
50
|
+
payload.jsonrpc === '2.0' &&
|
|
51
|
+
'method' in payload &&
|
|
52
|
+
typeof payload.method === 'string' &&
|
|
53
|
+
'params' in payload
|
|
54
|
+
);
|
|
55
|
+
}
|
package/src/rpc.ts
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import { SOLANA_ERROR__RPC__API_PLAN_MISSING_FOR_RPC_METHOD, SolanaError } from '@solana/errors';
|
|
2
|
+
import { Callable, Flatten, OverloadImplementations, UnionToIntersection } from '@solana/rpc-spec-types';
|
|
3
|
+
|
|
4
|
+
import { RpcApi, RpcPlan } from './rpc-api';
|
|
5
|
+
import { RpcTransport } from './rpc-transport';
|
|
6
|
+
|
|
7
|
+
export type RpcConfig<TRpcMethods, TRpcTransport extends RpcTransport> = Readonly<{
|
|
8
|
+
api: RpcApi<TRpcMethods>;
|
|
9
|
+
transport: TRpcTransport;
|
|
10
|
+
}>;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* An object that exposes all of the functions described by `TRpcMethods`.
|
|
14
|
+
*
|
|
15
|
+
* Calling each method returns a {@link PendingRpcRequest | PendingRpcRequest<TResponse>} where
|
|
16
|
+
* `TResponse` is that method's response type.
|
|
17
|
+
*/
|
|
18
|
+
export type Rpc<TRpcMethods> = {
|
|
19
|
+
[TMethodName in keyof TRpcMethods]: PendingRpcRequestBuilder<OverloadImplementations<TRpcMethods, TMethodName>>;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Pending requests are the result of calling a supported method on a {@link Rpc} object. They
|
|
24
|
+
* encapsulate all of the information necessary to make the request without actually making it.
|
|
25
|
+
*
|
|
26
|
+
* Calling the {@link PendingRpcRequest.send | `send(options)`} method on a
|
|
27
|
+
* {@link PendingRpcRequest | PendingRpcRequest<TResponse>} will trigger the request and return a
|
|
28
|
+
* promise for `TResponse`.
|
|
29
|
+
*/
|
|
30
|
+
export type PendingRpcRequest<TResponse> = {
|
|
31
|
+
send(options?: RpcSendOptions): Promise<TResponse>;
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
export type RpcSendOptions = Readonly<{
|
|
35
|
+
/**
|
|
36
|
+
* An optional signal that you can supply when triggering a {@link PendingRpcRequest} that you
|
|
37
|
+
* might later need to abort.
|
|
38
|
+
*/
|
|
39
|
+
abortSignal?: AbortSignal;
|
|
40
|
+
}>;
|
|
41
|
+
|
|
42
|
+
type PendingRpcRequestBuilder<TMethodImplementations> = UnionToIntersection<
|
|
43
|
+
Flatten<{
|
|
44
|
+
[P in keyof TMethodImplementations]: PendingRpcRequestReturnTypeMapper<TMethodImplementations[P]>;
|
|
45
|
+
}>
|
|
46
|
+
>;
|
|
47
|
+
|
|
48
|
+
type PendingRpcRequestReturnTypeMapper<TMethodImplementation> =
|
|
49
|
+
// Check that this property of the TRpcMethods interface is, in fact, a function.
|
|
50
|
+
TMethodImplementation extends Callable
|
|
51
|
+
? (...args: Parameters<TMethodImplementation>) => PendingRpcRequest<ReturnType<TMethodImplementation>>
|
|
52
|
+
: never;
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Creates a {@link Rpc} instance given a {@link RpcApi | RpcApi<TRpcMethods>} and a
|
|
56
|
+
* {@link RpcTransport} capable of fulfilling them.
|
|
57
|
+
*/
|
|
58
|
+
export function createRpc<TRpcMethods, TRpcTransport extends RpcTransport>(
|
|
59
|
+
rpcConfig: RpcConfig<TRpcMethods, TRpcTransport>,
|
|
60
|
+
): Rpc<TRpcMethods> {
|
|
61
|
+
return makeProxy(rpcConfig);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function makeProxy<TRpcMethods, TRpcTransport extends RpcTransport>(
|
|
65
|
+
rpcConfig: RpcConfig<TRpcMethods, TRpcTransport>,
|
|
66
|
+
): Rpc<TRpcMethods> {
|
|
67
|
+
return new Proxy(rpcConfig.api, {
|
|
68
|
+
defineProperty() {
|
|
69
|
+
return false;
|
|
70
|
+
},
|
|
71
|
+
deleteProperty() {
|
|
72
|
+
return false;
|
|
73
|
+
},
|
|
74
|
+
get(target, p, receiver) {
|
|
75
|
+
if (p === 'then') {
|
|
76
|
+
return undefined;
|
|
77
|
+
}
|
|
78
|
+
return function (...rawParams: unknown[]) {
|
|
79
|
+
const methodName = p.toString();
|
|
80
|
+
const getApiPlan = Reflect.get(target, methodName, receiver);
|
|
81
|
+
if (!getApiPlan) {
|
|
82
|
+
throw new SolanaError(SOLANA_ERROR__RPC__API_PLAN_MISSING_FOR_RPC_METHOD, {
|
|
83
|
+
method: methodName,
|
|
84
|
+
params: rawParams,
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
const apiPlan = getApiPlan(...rawParams);
|
|
88
|
+
return createPendingRpcRequest(rpcConfig, apiPlan);
|
|
89
|
+
};
|
|
90
|
+
},
|
|
91
|
+
}) as Rpc<TRpcMethods>;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function createPendingRpcRequest<TRpcMethods, TRpcTransport extends RpcTransport, TResponse>(
|
|
95
|
+
{ transport }: RpcConfig<TRpcMethods, TRpcTransport>,
|
|
96
|
+
plan: RpcPlan<TResponse>,
|
|
97
|
+
): PendingRpcRequest<TResponse> {
|
|
98
|
+
return {
|
|
99
|
+
async send(options?: RpcSendOptions): Promise<TResponse> {
|
|
100
|
+
return await plan.execute({ signal: options?.abortSignal, transport });
|
|
101
|
+
},
|
|
102
|
+
};
|
|
103
|
+
}
|