[experimental] A types-only RPC implementation using JavaScript proxies

packages/rpc-core/.gitignore

@@ -0,0 +1 @@
+dist/

packages/rpc-core/.prettierignore

@@ -0,0 +1 @@
+dist/

packages/rpc-core/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2018 Solana Labs, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/rpc-core/package.json

@@ -0,0 +1,99 @@
+{
+    "name": "@solana/rpc-core",
+    "version": "0.0.0-development",
+    "description": "A library for making calls to the Solana JSON RPC API",
+    "exports": {
+        "browser": {
+            "import": "./dist/index.browser.js",
+            "require": "./dist/index.browser.cjs"
+        },
+        "node": {
+            "import": "./dist/index.node.js",
+            "require": "./dist/index.node.cjs"
+        },
+        "react-native": "./dist/index.native.js",
+        "types": "./dist/types/index.d.ts"
+    },
+    "browser": {
+        "./dist/index.node.cjs": "./dist/index.browser.cjs",
+        "./dist/index.node.js": "./dist/index.browser.js"
+    },
+    "main": "./dist/index.node.cjs",
+    "module": "./dist/index.node.js",
+    "react-native": "./dist/index.native.js",
+    "types": "./dist/types/index.d.ts",
+    "type": "module",
+    "files": [
+        "./dist/"
+    ],
+    "sideEffects": false,
+    "keywords": [
+        "blockchain",
+        "solana",
+        "web3"
+    ],
+    "scripts": {
+        "compile:js": "tsup --config build-scripts/tsup.config.package.ts",
+        "compile:typedefs": "tsc -p ./tsconfig.declarations.json",
+        "dev": "jest -c node_modules/test-config/jest-dev.config.ts --rootDir . --watch",
+        "test:lint": "jest -c node_modules/test-config/jest-lint.config.ts --rootDir . --silent",
+        "test:prettier": "jest -c node_modules/test-config/jest-prettier.config.ts --rootDir . --silent",
+        "test:treeshakability:browser": "agadoo dist/index.browser.js",
+        "test:treeshakability:native": "agadoo dist/index.node.js",
+        "test:treeshakability:node": "agadoo dist/index.native.js",
+        "test:typecheck": "tsc --noEmit",
+        "test:unit:browser": "jest -c node_modules/test-config/jest-unit.config.browser.ts --rootDir . --silent",
+        "test:unit:node": "jest -c node_modules/test-config/jest-unit.config.node.ts --rootDir . --silent"
+    },
+    "author": "Solana Labs Maintainers <[email protected]>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/solana-labs/solana-web3.js"
+    },
+    "bugs": {
+        "url": "https://github.com/solana-labs/solana-web3.js/issues"
+    },
+    "browserslist": [
+        "supports bigint and not dead",
+        "maintained node versions"
+    ],
+    "dependencies": {
+        "@solana/keys": "workspace:*",
+        "@solana/rpc-transport": "workspace:*"
+    },
+    "devDependencies": {
+        "@solana/eslint-config-solana": "^0.0.4",
+        "@swc/core": "^1.3.18",
+        "@swc/jest": "^0.2.23",
+        "@types/jest": "^29.2.3",
+        "@typescript-eslint/eslint-plugin": "^5.43.0",
+        "@typescript-eslint/parser": "^5.43.0",
+        "agadoo": "^2.0.0",
+        "build-scripts": "workspace:*",
+        "eslint": "^8.27.0",
+        "eslint-plugin-jest": "^27.1.5",
+        "eslint-plugin-react-hooks": "^4.6.0",
+        "eslint-plugin-sort-keys-fix": "^1.1.2",
+        "jest": "^29.3.1",
+        "jest-environment-jsdom": "^29.3.1",
+        "jest-runner-eslint": "^1.1.0",
+        "jest-runner-prettier": "^1.0.0",
+        "postcss": "^8.4.12",
+        "prettier": "^2.7.1",
+        "test-config": "workspace:*",
+        "ts-node": "^10.9.1",
+        "tsconfig": "workspace:*",
+        "tsup": "6.5.0",
+        "turbo": "^1.6.3",
+        "typescript": "^4.9"
+    },
+    "bundlewatch": {
+        "defaultCompression": "gzip",
+        "files": [
+            {
+                "path": "./dist/index*.js"
+            }
+        ]
+    }
+}

packages/rpc-core/src/__tests__/rpc-test.ts

@@ -0,0 +1,26 @@
+import { IJsonRpcTransport } from '@solana/rpc-transport';
+import { rpc } from '../rpc';
+
+describe('rpc', () => {
+    let transport: jest.Mocked<IJsonRpcTransport>;
+    beforeEach(() => {
+        transport = { send: jest.fn() };
+    });
+    describe('a method call without params', () => {
+        beforeEach(async () => {
+            await rpc.getBlockHeight(transport);
+        });
+        it('calls `send` on the supplied transport with the function name as the method name and `undefined` params', () => {
+            expect(transport.send).toHaveBeenCalledWith('getBlockHeight', undefined);
+        });
+    });
+    describe('a method call with params', () => {
+        const params = [1, undefined, { commitment: 'finalized' }] as const;
+        beforeEach(async () => {
+            await rpc.getBlocks(transport, ...params);
+        });
+        it('calls `send` on the supplied transport with the function name as the method name and the supplied params', () => {
+            expect(transport.send).toHaveBeenCalledWith('getBlocks', params);
+        });
+    });
+});

packages/rpc-core/src/index.ts

@@ -0,0 +1 @@
+export * from './rpc';

packages/rpc-core/src/rpc.ts

@@ -0,0 +1,22 @@
+import { IJsonRpcTransport } from '@solana/rpc-transport';
+import { JsonRpcApi } from './types/jsonRpcApi';
+
+export const rpc = /* #__PURE__ */ new Proxy<JsonRpcApi>({} as JsonRpcApi, {
+    defineProperty() {
+        return false;
+    },
+    deleteProperty() {
+        return false;
+    },
+    get<TMethodName extends keyof JsonRpcApi>(target: JsonRpcApi, p: TMethodName) {
+        if (target[p] == null) {
+            const method = p.toString();
+            target[p] = async function (transport: IJsonRpcTransport, ...params: Parameters<JsonRpcApi[TMethodName]>) {
+                const normalizedParams = params.length ? params : undefined;
+                const result = await transport.send(method, normalizedParams);
+                return result;
+            } as unknown as JsonRpcApi[TMethodName];
+        }
+        return target[p];
+    },
+});

packages/rpc-core/src/types/global.d.ts

@@ -0,0 +1,4 @@
+declare const __BROWSER__: boolean;
+declare const __DEV__: boolean;
+declare const __NODEJS__: boolean;
+declare const __REACTNATIVE__: boolean;

packages/rpc-core/src/types/jsonRpcApi.d.ts

@@ -0,0 +1,5 @@
+import { GetAccountInfoApi } from './rpc-methods/getAccountInfo';
+import { GetBlockHeightApi } from './rpc-methods/getBlockHeight';
+import { GetBlocksApi } from './rpc-methods/getBlocks';
+
+declare interface JsonRpcApi extends GetAccountInfoApi, GetBlockHeightApi, GetBlocksApi {}

packages/rpc-core/src/types/rpc-methods/common.d.ts

@@ -0,0 +1,11 @@
+declare type DataSlice = readonly {
+    offset: number;
+    length: number;
+};
+
+// TODO: Eventually move this into whatever package implements transactions
+declare type Finality = 'confirmed' | 'finalized' | 'processed';
+
+declare type Slot =
+    // TODO(solana-labs/solana/issues/30341) Represent as bigint
+    number;

packages/rpc-core/src/types/rpc-methods/getAccountInfo.d.ts

@@ -0,0 +1,92 @@
+import { Base58EncodedAddress } from '@solana/keys';
+import { IJsonRPCTransport } from '../../rpc';
+
+type Base64EncodedBytes = string & { readonly __base64EncodedBytes: unique symbol };
+type Base64EncodedZStdCompressedBytes = string & { readonly __base64EncodedZStdCompressedBytes: unique symbol };
+
+type Base64EncodedDataResponse = [Base64EncodedBytes, 'base64'];
+type Base64EncodedZStdCompressedDataResponse = [Base64EncodedZStdCompressedBytes, 'base64+zstd'];
+
+type GetAccountInfoApiResponseBase = Readonly<{
+    context: Readonly<{
+        slot: Slot;
+    }>;
+    value: Readonly<{
+        executable: boolean;
+        lamports: number; // TODO(solana-labs/solana/issues/30341) Represent as bigint
+        owner: Base64EncodedAddress;
+        rentEpoch: number; // TODO(solana-labs/solana/issues/30341) Represent as bigint
+        space: number; // TODO(solana-labs/solana/issues/30341) Represent as bigint
+    }> | null;
+}>;
+
+type GetAccountInfoApiResponseWithEncodedData = Readonly<{
+    value: Readonly<{
+        data: Base64EncodedDataResponse;
+    }> | null;
+}>;
+
+type GetAccountInfoApiResponseWithEncodedZStdCompressedData = Readonly<{
+    value: Readonly<{
+        data: Base64EncodedZStdCompressedDataResponse;
+    }> | null;
+}>;
+
+type GetAccountInfoApiResponseWithJsonData = Readonly<{
+    value: Readonly<{
+        data:
+            | Readonly<{
+                  // Name of the program that owns this account.
+                  program: string;
+                  parsed: unknown;
+                  space: number; // TODO(solana-labs/solana/issues/30341) Represent as bigint
+              }>
+            // If `jsonParsed` encoding is requested but a parser cannot be found for the given
+            // account the `data` field falls back to `base64`.
+            | Base64EncodedDataResponse;
+    }> | null;
+}>;
+
+type GetAccountInfoApiCommonConfig = readonly {
+    // Defaults to `finalized`
+    commitment?: Finality;
+    // The minimum slot that the request can be evaluated at
+    minContextSlot?: Slot;
+};
+
+type GetAccountInfoApiBase64EncodingCommonConfig = readonly {
+    // Limit the returned account data using the provided "offset: <usize>" and "length: <usize>" fields.
+    dataSlice?: DataSlice;
+};
+
+declare interface GetAccountInfoApi {
+    /**
+     * Returns all information associated with the account of provided public key
+     */
+    getAccountInfo(
+        transport: IJsonRPCTransport,
+        address: Base58EncodedAddress,
+        config?: readonly {
+            encoding: 'base64';
+        } &
+            GetAccountInfoApiCommonConfig &
+            GetAccountInfoApiBase64EncodingCommonConfig
+    ): Promise<GetAccountInfoApiResponseBase & GetAccountInfoApiResponseWithEncodedData>;
+    getAccountInfo(
+        transport: IJsonRPCTransport,
+        address: Base58EncodedAddress,
+        config?: readonly {
+            encoding: 'base64+zstd';
+        } &
+            GetAccountInfoApiCommonConfig &
+            GetAccountInfoApiBase64EncodingCommonConfig
+    ): Promise<GetAccountInfoApiResponseBase & GetAccountInfoApiResponseWithEncodedZStdCompressedData>;
+    getAccountInfo(
+        transport: IJsonRPCTransport,
+        address: Base58EncodedAddress,
+        config?: readonly {
+            encoding: 'jsonParsed';
+        } &
+            GetAccountInfoApiCommonConfig
+    ): Promise<GetAccountInfoApiResponseBase & GetAccountInfoApiResponseWithJsonData>;
+}

packages/rpc-core/src/types/rpc-methods/getBlockHeight.d.ts

@@ -0,0 +1,20 @@
+import { IJsonRpcTransport } from '@solana/rpc-transport';
+
+type GetBlockHeightApiResponse =
+    // TODO(solana-labs/solana/issues/30341) Represent as bigint
+    number;
+
+declare interface GetBlockHeightApi {
+    /**
+     * Returns the current block height of the node
+     */
+    getBlockHeight(
+        transport: IJsonRpcTransport,
+        config?: readonly {
+            // Defaults to `finalized`
+            commitment?: Finality;
+            // The minimum slot that the request can be evaluated at
+            minContextSlot?: Slot;
+        }
+    ): Promise<GetBlockHeightApiResponse>;
+}

packages/rpc-core/src/types/rpc-methods/getBlocks.d.ts

@@ -0,0 +1,18 @@
+import { IJsonRpcTransport } from '@solana/rpc-transport';
+
+type GetBlocksApiResponse = Slot[];
+
+declare interface GetBlocksApi {
+    /**
+     * Returns a list of confirmed blocks between two slots
+     */
+    getBlocks(
+        transport: IJsonRpcTransport,
+        startSlot: Slot,
+        endSlotInclusive?: Slot,
+        config?: readonly {
+            // Defaults to `finalized`
+            commitment?: Exclude<Finality, 'processed'>;
+        }
+    ): Promise<GetBlocksApiResponse>;
+}

packages/rpc-core/tsconfig.declarations.json

@@ -0,0 +1,10 @@
+{
+    "compilerOptions": {
+        "declaration": true,
+        "declarationMap": true,
+        "emitDeclarationOnly": true,
+        "outDir": "./dist/types"
+    },
+    "extends": "./tsconfig.json",
+    "include": ["src/index.ts", "src/types"]
+}

packages/rpc-core/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "compilerOptions": {
+        "lib": ["ES2015.Proxy", "ES2015.Promise", "ES5"]
+    },
+    "display": "@solana/rpc-core",
+    "extends": "tsconfig/base.json",
+    "include": ["src"]
+}