@solana/rpc-api 6.3.1 → 6.3.2-canary-20260313112147

package/src/index.ts

@@ -0,0 +1,353 @@
+/**
+ * This package contains types that describe the [methods](https://solana.com/docs/rpc/http) of the
+ * Solana JSON RPC API, and utilities for creating a {@link RpcApi} implementation with sensible
+ * defaults. It can be used standalone, but it is also exported as part of Kit
+ * [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * @example
+ * Each RPC method is described in terms of a TypeScript type of the following form:
+ *
+ * ```ts
+ * type ExampleApi = {
+ *     getSomething(address: Address): Something;
+ * };
+ * ```
+ *
+ * A {@link RpcApi} that implements `ExampleApi` will ultimately expose its defined methods on any
+ * {@link Rpc} that uses it.
+ *
+ * ```ts
+ * const rpc: Rpc<ExampleApi> = createExampleRpc(/* ... *\/);
+ * const something: Something = await rpc.getSomething(address('95DpK3y3GF7U8s1k4EvZ7xqyeCkhsHeZaE97iZpHUGMN')).send();
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { createJsonRpcApi, RpcApi } from '@solana/rpc-spec';
+import {
+    AllowedNumericKeypaths,
+    getDefaultRequestTransformerForSolanaRpc,
+    getDefaultResponseTransformerForSolanaRpc,
+    innerInstructionsConfigs,
+    jsonParsedAccountsConfigs,
+    jsonParsedTokenAccountsConfigs,
+    KEYPATH_WILDCARD,
+    messageConfig,
+    RequestTransformerConfig,
+} from '@solana/rpc-transformers';
+
+import { GetAccountInfoApi } from './getAccountInfo';
+import { GetBalanceApi } from './getBalance';
+import { GetBlockApi } from './getBlock';
+import { GetBlockCommitmentApi } from './getBlockCommitment';
+import { GetBlockHeightApi } from './getBlockHeight';
+import { GetBlockProductionApi } from './getBlockProduction';
+import { GetBlocksApi } from './getBlocks';
+import { GetBlocksWithLimitApi } from './getBlocksWithLimit';
+import { GetBlockTimeApi } from './getBlockTime';
+import { GetClusterNodesApi } from './getClusterNodes';
+import { GetEpochInfoApi } from './getEpochInfo';
+import { GetEpochScheduleApi } from './getEpochSchedule';
+import { GetFeeForMessageApi } from './getFeeForMessage';
+import { GetFirstAvailableBlockApi } from './getFirstAvailableBlock';
+import { GetGenesisHashApi } from './getGenesisHash';
+import { GetHealthApi } from './getHealth';
+import { GetHighestSnapshotSlotApi } from './getHighestSnapshotSlot';
+import { GetIdentityApi } from './getIdentity';
+import { GetInflationGovernorApi } from './getInflationGovernor';
+import { GetInflationRateApi } from './getInflationRate';
+import { GetInflationRewardApi } from './getInflationReward';
+import { GetLargestAccountsApi } from './getLargestAccounts';
+import { GetLatestBlockhashApi } from './getLatestBlockhash';
+import { GetLeaderScheduleApi } from './getLeaderSchedule';
+import { GetMaxRetransmitSlotApi } from './getMaxRetransmitSlot';
+import { GetMaxShredInsertSlotApi } from './getMaxShredInsertSlot';
+import { GetMinimumBalanceForRentExemptionApi } from './getMinimumBalanceForRentExemption';
+import { GetMultipleAccountsApi } from './getMultipleAccounts';
+import { GetProgramAccountsApi } from './getProgramAccounts';
+import { GetRecentPerformanceSamplesApi } from './getRecentPerformanceSamples';
+import { GetRecentPrioritizationFeesApi } from './getRecentPrioritizationFees';
+import { GetSignaturesForAddressApi } from './getSignaturesForAddress';
+import { GetSignatureStatusesApi } from './getSignatureStatuses';
+import { GetSlotApi } from './getSlot';
+import { GetSlotLeaderApi } from './getSlotLeader';
+import { GetSlotLeadersApi } from './getSlotLeaders';
+import { GetStakeMinimumDelegationApi } from './getStakeMinimumDelegation';
+import { GetSupplyApi } from './getSupply';
+import { GetTokenAccountBalanceApi } from './getTokenAccountBalance';
+import { GetTokenAccountsByDelegateApi } from './getTokenAccountsByDelegate';
+import { GetTokenAccountsByOwnerApi } from './getTokenAccountsByOwner';
+import { GetTokenLargestAccountsApi } from './getTokenLargestAccounts';
+import { GetTokenSupplyApi } from './getTokenSupply';
+import { GetTransactionApi } from './getTransaction';
+import { GetTransactionCountApi } from './getTransactionCount';
+import { GetVersionApi } from './getVersion';
+import { GetVoteAccountsApi } from './getVoteAccounts';
+import { IsBlockhashValidApi } from './isBlockhashValid';
+import { MinimumLedgerSlotApi } from './minimumLedgerSlot';
+import { RequestAirdropApi } from './requestAirdrop';
+import { SendTransactionApi } from './sendTransaction';
+import { SimulateTransactionApi } from './simulateTransaction';
+
+type SolanaRpcApiForAllClusters = GetAccountInfoApi &
+    GetBalanceApi &
+    GetBlockApi &
+    GetBlockCommitmentApi &
+    GetBlockHeightApi &
+    GetBlockProductionApi &
+    GetBlocksApi &
+    GetBlocksWithLimitApi &
+    GetBlockTimeApi &
+    GetClusterNodesApi &
+    GetEpochInfoApi &
+    GetEpochScheduleApi &
+    GetFeeForMessageApi &
+    GetFirstAvailableBlockApi &
+    GetGenesisHashApi &
+    GetHealthApi &
+    GetHighestSnapshotSlotApi &
+    GetIdentityApi &
+    GetInflationGovernorApi &
+    GetInflationRateApi &
+    GetInflationRewardApi &
+    GetLargestAccountsApi &
+    GetLatestBlockhashApi &
+    GetLeaderScheduleApi &
+    GetMaxRetransmitSlotApi &
+    GetMaxShredInsertSlotApi &
+    GetMinimumBalanceForRentExemptionApi &
+    GetMultipleAccountsApi &
+    GetProgramAccountsApi &
+    GetRecentPerformanceSamplesApi &
+    GetRecentPrioritizationFeesApi &
+    GetSignaturesForAddressApi &
+    GetSignatureStatusesApi &
+    GetSlotApi &
+    GetSlotLeaderApi &
+    GetSlotLeadersApi &
+    GetStakeMinimumDelegationApi &
+    GetSupplyApi &
+    GetTokenAccountBalanceApi &
+    GetTokenAccountsByDelegateApi &
+    GetTokenAccountsByOwnerApi &
+    GetTokenLargestAccountsApi &
+    GetTokenSupplyApi &
+    GetTransactionApi &
+    GetTransactionCountApi &
+    GetVersionApi &
+    GetVoteAccountsApi &
+    IsBlockhashValidApi &
+    MinimumLedgerSlotApi &
+    SendTransactionApi &
+    SimulateTransactionApi;
+type SolanaRpcApiForTestClusters = RequestAirdropApi & SolanaRpcApiForAllClusters;
+/**
+ * Represents the RPC methods available on test clusters.
+ *
+ * For instance, the test clusters support the {@link RequestAirdropApi} while mainnet does not.
+ */
+export type SolanaRpcApi = SolanaRpcApiForTestClusters;
+/**
+ * Represents the RPC methods available on the devnet cluster.
+ *
+ * For instance, the devnet cluster supports the {@link RequestAirdropApi} while mainnet does not.
+ */
+export type SolanaRpcApiDevnet = SolanaRpcApiForTestClusters;
+/**
+ * Represents the RPC methods available on the testnet cluster.
+ *
+ * For instance, the testnet cluster supports the {@link RequestAirdropApi} while mainnet does not.
+ */
+export type SolanaRpcApiTestnet = SolanaRpcApiForTestClusters;
+/**
+ * Represents the RPC methods available on the mainnet cluster.
+ *
+ * For instance, the mainnet cluster does not support the {@link RequestAirdropApi} whereas test
+ * clusters do.
+ */
+export type SolanaRpcApiMainnet = SolanaRpcApiForAllClusters;
+
+export type {
+    GetAccountInfoApi,
+    GetBalanceApi,
+    GetBlockApi,
+    GetBlockCommitmentApi,
+    GetBlockHeightApi,
+    GetBlockProductionApi,
+    GetBlocksApi,
+    GetBlocksWithLimitApi,
+    GetBlockTimeApi,
+    GetClusterNodesApi,
+    GetEpochInfoApi,
+    GetEpochScheduleApi,
+    GetFeeForMessageApi,
+    GetFirstAvailableBlockApi,
+    GetGenesisHashApi,
+    GetHealthApi,
+    GetHighestSnapshotSlotApi,
+    GetIdentityApi,
+    GetInflationGovernorApi,
+    GetInflationRateApi,
+    GetInflationRewardApi,
+    GetLargestAccountsApi,
+    GetLatestBlockhashApi,
+    GetLeaderScheduleApi,
+    GetMaxRetransmitSlotApi,
+    GetMaxShredInsertSlotApi,
+    GetMinimumBalanceForRentExemptionApi,
+    GetMultipleAccountsApi,
+    GetProgramAccountsApi,
+    GetRecentPerformanceSamplesApi,
+    GetRecentPrioritizationFeesApi,
+    GetSignaturesForAddressApi,
+    GetSignatureStatusesApi,
+    GetSlotApi,
+    GetSlotLeaderApi,
+    GetSlotLeadersApi,
+    GetStakeMinimumDelegationApi,
+    GetSupplyApi,
+    GetTokenAccountBalanceApi,
+    GetTokenAccountsByDelegateApi,
+    GetTokenAccountsByOwnerApi,
+    GetTokenLargestAccountsApi,
+    GetTokenSupplyApi,
+    GetTransactionApi,
+    GetTransactionCountApi,
+    GetVersionApi,
+    GetVoteAccountsApi,
+    IsBlockhashValidApi,
+    MinimumLedgerSlotApi,
+    RequestAirdropApi,
+    SendTransactionApi,
+    SimulateTransactionApi,
+};
+
+type Config = RequestTransformerConfig;
+
+/**
+ * Creates a {@link RpcApi} implementation of the Solana JSON RPC API with some default behaviours.
+ *
+ * The default behaviours include:
+ * - A transform that converts `bigint` inputs to `number` for compatibility with version 1.0 of the
+ *   Solana JSON RPC.
+ * - A transform that calls the config's {@link Config.onIntegerOverflow | onIntegerOverflow}
+ *   handler whenever a `bigint` input would overflow a JavaScript IEEE 754 number. See
+ *   [this](https://github.com/solana-labs/solana-web3.js/issues/1116) GitHub issue for more
+ *   information.
+ * - A transform that applies a default commitment wherever not specified
+ */
+export function createSolanaRpcApi<
+    // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents
+    TRpcMethods extends SolanaRpcApi | SolanaRpcApiDevnet | SolanaRpcApiMainnet | SolanaRpcApiTestnet = SolanaRpcApi,
+>(config?: Config): RpcApi<TRpcMethods> {
+    return createJsonRpcApi<TRpcMethods>({
+        requestTransformer: getDefaultRequestTransformerForSolanaRpc(config),
+        responseTransformer: getDefaultResponseTransformerForSolanaRpc({
+            allowedNumericKeyPaths: getAllowedNumericKeypaths(),
+        }),
+    });
+}
+
+let memoizedKeypaths: AllowedNumericKeypaths<RpcApi<SolanaRpcApi>>;
+
+/**
+ * These are keypaths at the end of which you will find a numeric value that should *not* be upcast
+ * to a `bigint`. These are values that are legitimately defined as `u8` or `usize` on the backend.
+ */
+function getAllowedNumericKeypaths(): AllowedNumericKeypaths<RpcApi<SolanaRpcApi>> {
+    if (!memoizedKeypaths) {
+        memoizedKeypaths = {
+            getAccountInfo: jsonParsedAccountsConfigs.map(c => ['value', ...c]),
+            getBlock: [
+                ['transactions', KEYPATH_WILDCARD, 'meta', 'preTokenBalances', KEYPATH_WILDCARD, 'accountIndex'],
+                [
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'preTokenBalances',
+                    KEYPATH_WILDCARD,
+                    'uiTokenAmount',
+                    'decimals',
+                ],
+                ['transactions', KEYPATH_WILDCARD, 'meta', 'postTokenBalances', KEYPATH_WILDCARD, 'accountIndex'],
+                [
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'postTokenBalances',
+                    KEYPATH_WILDCARD,
+                    'uiTokenAmount',
+                    'decimals',
+                ],
+                ['transactions', KEYPATH_WILDCARD, 'meta', 'rewards', KEYPATH_WILDCARD, 'commission'],
+                ...innerInstructionsConfigs.map(c => [
+                    'transactions',
+                    KEYPATH_WILDCARD,
+                    'meta',
+                    'innerInstructions',
+                    KEYPATH_WILDCARD,
+                    ...c,
+                ]),
+                ...messageConfig.map(c => ['transactions', KEYPATH_WILDCARD, 'transaction', 'message', ...c] as const),
+                ['rewards', KEYPATH_WILDCARD, 'commission'],
+            ],
+            getClusterNodes: [
+                [KEYPATH_WILDCARD, 'featureSet'],
+                [KEYPATH_WILDCARD, 'shredVersion'],
+            ],
+            getInflationGovernor: [['initial'], ['foundation'], ['foundationTerm'], ['taper'], ['terminal']],
+            getInflationRate: [['foundation'], ['total'], ['validator']],
+            getInflationReward: [[KEYPATH_WILDCARD, 'commission']],
+            getMultipleAccounts: jsonParsedAccountsConfigs.map(c => ['value', KEYPATH_WILDCARD, ...c]),
+            getProgramAccounts: jsonParsedAccountsConfigs.flatMap(c => [
+                ['value', KEYPATH_WILDCARD, 'account', ...c],
+                [KEYPATH_WILDCARD, 'account', ...c],
+            ]),
+            getRecentPerformanceSamples: [[KEYPATH_WILDCARD, 'samplePeriodSecs']],
+            getTokenAccountBalance: [
+                ['value', 'decimals'],
+                ['value', 'uiAmount'],
+            ],
+            getTokenAccountsByDelegate: jsonParsedTokenAccountsConfigs.map(c => [
+                'value',
+                KEYPATH_WILDCARD,
+                'account',
+                ...c,
+            ]),
+            getTokenAccountsByOwner: jsonParsedTokenAccountsConfigs.map(c => [
+                'value',
+                KEYPATH_WILDCARD,
+                'account',
+                ...c,
+            ]),
+            getTokenLargestAccounts: [
+                ['value', KEYPATH_WILDCARD, 'decimals'],
+                ['value', KEYPATH_WILDCARD, 'uiAmount'],
+            ],
+            getTokenSupply: [
+                ['value', 'decimals'],
+                ['value', 'uiAmount'],
+            ],
+            getTransaction: [
+                ['meta', 'preTokenBalances', KEYPATH_WILDCARD, 'accountIndex'],
+                ['meta', 'preTokenBalances', KEYPATH_WILDCARD, 'uiTokenAmount', 'decimals'],
+                ['meta', 'postTokenBalances', KEYPATH_WILDCARD, 'accountIndex'],
+                ['meta', 'postTokenBalances', KEYPATH_WILDCARD, 'uiTokenAmount', 'decimals'],
+                ['meta', 'rewards', KEYPATH_WILDCARD, 'commission'],
+                ...innerInstructionsConfigs.map(c => ['meta', 'innerInstructions', KEYPATH_WILDCARD, ...c]),
+                ...messageConfig.map(c => ['transaction', 'message', ...c] as const),
+            ],
+            getVersion: [['feature-set']],
+            getVoteAccounts: [
+                ['current', KEYPATH_WILDCARD, 'commission'],
+                ['delinquent', KEYPATH_WILDCARD, 'commission'],
+            ],
+            simulateTransaction: [
+                ['value', 'loadedAccountsDataSize'],
+                ...jsonParsedAccountsConfigs.map(c => ['value', 'accounts', KEYPATH_WILDCARD, ...c]),
+                ...innerInstructionsConfigs.map(c => ['value', 'innerInstructions', KEYPATH_WILDCARD, ...c]),
+            ],
+        };
+    }
+    return memoizedKeypaths;
+}

package/src/isBlockhashValid.ts

@@ -0,0 +1,35 @@
+import type { Blockhash, Commitment, Slot, SolanaRpcResponse } from '@solana/rpc-types';
+
+type IsBlockhashValidApiResponse = boolean;
+
+export type IsBlockhashValidApi = {
+    /**
+     * Returns whether a blockhash is still valid or not.
+     *
+     * The last 300 blockhashes produced are considered valid. This equates to an age of ~2 minutes.
+     *
+     * @param blockhash A SHA-256 hash as base-58 encoded string
+     *
+     * @see https://solana.com/docs/rpc/http/isblockhashvalid
+     */
+    isBlockhashValid(
+        blockhash: Blockhash,
+        config?: Readonly<{
+            /**
+             * Evaluate whether the blockhash is valid as of the highest slot that has reached this
+             * level of commitment.
+             *
+             * @defaultValue Whichever default is applied by the underlying {@link RpcApi} in use.
+             * For example, when using an API created by a `createSolanaRpc*()` helper, the default
+             * commitment is `"confirmed"` unless configured otherwise. Unmitigated by an API layer
+             * on the client, the default commitment applied by the server is `"finalized"`.
+             */
+            commitment?: Commitment;
+            /**
+             * Prevents accessing stale data by enforcing that the RPC node has processed
+             * transactions up to this slot
+             */
+            minContextSlot?: Slot;
+        }>,
+    ): SolanaRpcResponse<IsBlockhashValidApiResponse>;
+};

package/src/minimumLedgerSlot.ts

@@ -0,0 +1,16 @@
+import type { Slot } from '@solana/rpc-types';
+
+type MinimumLedgerSlotApiResponse = Slot;
+
+export type MinimumLedgerSlotApi = {
+    /**
+     * Returns the lowest slot about which the node has information.
+     *
+     * Different nodes may offer more or less historical slot data, depending on their
+     * configuration. An appropriately configured node should be able to access all slots, from
+     * genesis onward. When it is not, this method will tell you the lowest slot available.
+     *
+     * @see https://solana.com/docs/rpc/http/minimumledgerslot
+     */
+    minimumLedgerSlot(): MinimumLedgerSlotApiResponse;
+};

package/src/requestAirdrop.ts

@@ -0,0 +1,34 @@
+import type { Address } from '@solana/addresses';
+import type { Signature } from '@solana/keys';
+import type { Commitment, Lamports } from '@solana/rpc-types';
+
+type RequestAirdropConfig = Readonly<{
+    /**
+     * Evaluate the request as of the highest slot that has reached this level of commitment.
+     *
+     * @defaultValue Whichever default is applied by the underlying {@link RpcApi} in use. For
+     * example, when using an API created by a `createSolanaRpc*()` helper, the default commitment
+     * is `"confirmed"` unless configured otherwise. Unmitigated by an API layer on the client, the
+     * default commitment applied by the server is `"finalized"`.
+     */
+    commitment?: Commitment;
+}>;
+
+type RequestAirdropResponse = Signature;
+
+export type RequestAirdropApi = {
+    /**
+     * Requests an airdrop of {@link Lamports} to the specified address.
+     *
+     * This method is offered by test clusters as a way to obtain SOL tokens to pay transaction
+     * fees.
+     *
+     * @returns The signature of the airdrop transaction, as a base-58 encoded string.
+     * @see https://solana.com/docs/rpc/http/requestairdrop
+     */
+    requestAirdrop(
+        recipientAccount: Address,
+        lamports: Lamports,
+        config?: RequestAirdropConfig,
+    ): RequestAirdropResponse;
+};

package/src/sendTransaction.ts

@@ -0,0 +1,80 @@
+import type { Signature } from '@solana/keys';
+import type { Commitment, Slot } from '@solana/rpc-types';
+import type { Base64EncodedWireTransaction } from '@solana/transactions';
+
+type SendTransactionConfig = Readonly<{
+    /**
+     * Maximum number of times for the RPC node to retry sending the transaction to the leader.
+     *
+     * @defaultValue When omitted, the RPC node will retry the transaction until it is finalized or
+     * until its lifetime specifier (ie. its recent blockhash or nonce) expires.
+     */
+    maxRetries?: bigint;
+    /**
+     * Prevents accessing stale data by enforcing that the RPC node has processed transactions up to
+     * this slot
+     */
+    minContextSlot?: Slot;
+    /**
+     * Simulate the transaction as of the highest slot that has reached this level of commitment.
+     *
+     * Has no effect when `skipPreflight` is set to `true`.
+     *
+     * @defaultValue Whichever default is applied by the underlying {@link RpcApi} in use. For
+     * example, when using an API created by a `createSolanaRpc*()` helper, the default commitment
+     * is `"confirmed"` unless configured otherwise. Unmitigated by an API layer on the client, the
+     * default commitment applied by the server is `"finalized"`.
+     */
+    preflightCommitment?: Commitment;
+    /** @defaultValue `false` */
+    skipPreflight?: boolean;
+}>;
+
+type SendTransactionResponse = Signature;
+
+export type SendTransactionApi = {
+    /** @deprecated Set `encoding` to `'base64'` when calling this method */
+    sendTransaction(
+        base64EncodedWireTransaction: Base64EncodedWireTransaction,
+        config?: SendTransactionConfig & { encoding?: 'base58' },
+    ): SendTransactionResponse;
+    /**
+     * Submits a signed transaction to the cluster for processing.
+     *
+     * This method does not alter the transaction in any way; it relays the transaction created by
+     * clients to the node as-is.
+     *
+     * If the node's RPC service receives the transaction, this method immediately succeeds, without
+     * waiting for any confirmations. A successful response from this method does not guarantee the
+     * transaction will be processed or confirmed by the cluster.
+     *
+     * While the RPC service will reasonably retry to submit it, the transaction could fail to be
+     * committed if the transaction's lifetime specifier (ie. its recent blockhash or nonce) expires
+     * before it lands.
+     *
+     * Use {@link GetSignatureStatusesApi.getSignatureStatuses} to ensure that a transaction has
+     * been processed and confirmed.
+     *
+     * Before submitting, the following preflight checks are performed:
+     *
+     *     1. The transaction signatures are verified
+     *     2. The transaction is simulated against the bank slot specified by the preflight
+     *        commitment. On failure, an error will be returned. It is recommended to specify the
+     *        same commitment and preflight commitment to avoid confusing behavior. You can disable
+     *        preflight checks if desired.
+     *
+     * @param base64EncodedWireTransaction A fully signed transaction in wire format, as a base-64
+     * encoded string. Use {@link getBase64EncodedWireTransaction} to obtain this.
+     *
+     * @returns The signature of the transaction, as a base-58 encoded string. This is the first
+     * signature in the transaction, which is used to uniquely identify it. You do not have to wait
+     * for this method to return to obtain the signature; you can extract it from the transaction
+     * before sending it.
+     *
+     * @see https://solana.com/docs/rpc/http/sendtransaction
+     */
+    sendTransaction(
+        base64EncodedWireTransaction: Base64EncodedWireTransaction,
+        config?: SendTransactionConfig & { encoding: 'base64' },
+    ): SendTransactionResponse;
+};