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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/rpc-transformers",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Reusable transformers for patching RPC inputs and outputs",
   "homepage": "https://www.solanakit.com/api#solanarpc-transformers",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,11 +56,11 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "6.3.1",
-    "@solana/functional": "6.3.1",
-    "@solana/nominal-types": "6.3.1",
-    "@solana/rpc-spec-types": "6.3.1",
-    "@solana/rpc-types": "6.3.1"
+    "@solana/errors": "6.3.2-canary-20260313112147",
+    "@solana/nominal-types": "6.3.2-canary-20260313112147",
+    "@solana/functional": "6.3.2-canary-20260313112147",
+    "@solana/rpc-types": "6.3.2-canary-20260313112147",
+    "@solana/rpc-spec-types": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * This package contains helpers for transforming Solana JSON RPC and RPC Subscriptions requests,
+ * responses, and notifications in various ways appropriate for use in a JavaScript application.
+ *
+ * @packageDocumentation
+ */
+export * from './request-transformer';
+export * from './request-transformer-bigint-downcast';
+export * from './request-transformer-default-commitment';
+export * from './request-transformer-integer-overflow';
+export * from './response-transformer';
+export * from './response-transformer-allowed-numeric-values';
+export * from './response-transformer-bigint-upcast';
+export * from './response-transformer-result';
+export * from './response-transformer-throw-solana-error';
+export * from './tree-traversal';

package/src/request-transformer-bigint-downcast-internal.ts

@@ -0,0 +1,10 @@
+export function downcastNodeToNumberIfBigint(value: bigint): number;
+export function downcastNodeToNumberIfBigint<T>(value: T): T;
+export function downcastNodeToNumberIfBigint(value: unknown): unknown {
+    return typeof value === 'bigint'
+        ? // FIXME(solana-labs/solana/issues/30341) Create a data type to represent u64 in the Solana
+          // JSON RPC implementation so that we can throw away this entire patcher instead of unsafely
+          // downcasting `bigints` to `numbers`.
+          Number(value)
+        : value;
+}

package/src/request-transformer-bigint-downcast.ts

@@ -0,0 +1,17 @@
+import { downcastNodeToNumberIfBigint } from './request-transformer-bigint-downcast-internal';
+import { getTreeWalkerRequestTransformer } from './tree-traversal';
+
+/**
+ * Creates a transformer that downcasts all `BigInt` values to `Number`.
+ *
+ * @example
+ * ```ts
+ * import { getBigIntDowncastRequestTransformer } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getBigIntDowncastRequestTransformer();
+ * ```
+ *
+ */
+export function getBigIntDowncastRequestTransformer() {
+    return getTreeWalkerRequestTransformer([downcastNodeToNumberIfBigint], { keyPath: [] });
+}

package/src/request-transformer-default-commitment-internal.ts

@@ -0,0 +1,58 @@
+import { Commitment } from '@solana/rpc-types';
+
+export function applyDefaultCommitment({
+    commitmentPropertyName,
+    params,
+    optionsObjectPositionInParams,
+    overrideCommitment,
+}: Readonly<{
+    commitmentPropertyName: string;
+    optionsObjectPositionInParams: number;
+    overrideCommitment?: Commitment;
+    params: unknown[];
+}>) {
+    const paramInTargetPosition = params[optionsObjectPositionInParams];
+    if (
+        // There's no config.
+        paramInTargetPosition === undefined ||
+        // There is a config object.
+        (paramInTargetPosition && typeof paramInTargetPosition === 'object' && !Array.isArray(paramInTargetPosition))
+    ) {
+        if (
+            // The config object already has a commitment set.
+            paramInTargetPosition &&
+            commitmentPropertyName in paramInTargetPosition
+        ) {
+            if (
+                !paramInTargetPosition[commitmentPropertyName as keyof typeof paramInTargetPosition] ||
+                paramInTargetPosition[commitmentPropertyName as keyof typeof paramInTargetPosition] === 'finalized'
+            ) {
+                // Delete the commitment property; `finalized` is already the server default.
+                const nextParams = [...params];
+                const {
+                    [commitmentPropertyName as keyof typeof paramInTargetPosition]: _, // eslint-disable-line @typescript-eslint/no-unused-vars
+                    ...rest
+                } = paramInTargetPosition;
+                if (Object.keys(rest).length > 0) {
+                    nextParams[optionsObjectPositionInParams] = rest;
+                } else {
+                    if (optionsObjectPositionInParams === nextParams.length - 1) {
+                        nextParams.length--;
+                    } else {
+                        nextParams[optionsObjectPositionInParams] = undefined;
+                    }
+                }
+                return nextParams;
+            }
+        } else if (overrideCommitment !== 'finalized') {
+            // Apply the default commitment.
+            const nextParams = [...params];
+            nextParams[optionsObjectPositionInParams] = {
+                ...paramInTargetPosition,
+                [commitmentPropertyName]: overrideCommitment,
+            };
+            return nextParams;
+        }
+    }
+    return params;
+}

package/src/request-transformer-default-commitment.ts

@@ -0,0 +1,51 @@
+import type { RpcRequest, RpcRequestTransformer } from '@solana/rpc-spec-types';
+import type { Commitment } from '@solana/rpc-types';
+
+import { applyDefaultCommitment } from './request-transformer-default-commitment-internal';
+
+/**
+ * Creates a transformer that adds the provided default commitment to the configuration object of the request when applicable.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import { getDefaultCommitmentRequestTransformer, OPTIONS_OBJECT_POSITION_BY_METHOD } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getDefaultCommitmentRequestTransformer({
+ *     defaultCommitment: 'confirmed',
+ *     optionsObjectPositionByMethod: OPTIONS_OBJECT_POSITION_BY_METHOD,
+ * });
+ */
+export function getDefaultCommitmentRequestTransformer({
+    defaultCommitment,
+    optionsObjectPositionByMethod,
+}: Readonly<{
+    defaultCommitment?: Commitment;
+    optionsObjectPositionByMethod: Record<string, number>;
+}>): RpcRequestTransformer {
+    return <TParams>(request: RpcRequest<TParams>): RpcRequest => {
+        const { params, methodName } = request;
+
+        // We only apply default commitment to array parameters.
+        if (!Array.isArray(params)) {
+            return request;
+        }
+
+        // Find the position of the options object in the parameters and abort if not found.
+        const optionsObjectPositionInParams = optionsObjectPositionByMethod[methodName];
+        if (optionsObjectPositionInParams == null) {
+            return request;
+        }
+
+        return Object.freeze({
+            methodName,
+            params: applyDefaultCommitment({
+                commitmentPropertyName: methodName === 'sendTransaction' ? 'preflightCommitment' : 'commitment',
+                optionsObjectPositionInParams,
+                overrideCommitment: defaultCommitment,
+                params,
+            }),
+        });
+    };
+}

package/src/request-transformer-integer-overflow-internal.ts

@@ -0,0 +1,12 @@
+import { KeyPath, TraversalState } from './tree-traversal';
+
+export function getIntegerOverflowNodeVisitor(onIntegerOverflow: (keyPath: KeyPath, value: bigint) => void) {
+    return <T>(value: T, { keyPath }: TraversalState): T => {
+        if (typeof value === 'bigint') {
+            if (onIntegerOverflow && (value > Number.MAX_SAFE_INTEGER || value < -Number.MAX_SAFE_INTEGER)) {
+                onIntegerOverflow(keyPath as (number | string)[], value);
+            }
+        }
+        return value;
+    };
+}

package/src/request-transformer-integer-overflow.ts

@@ -0,0 +1,29 @@
+import { RpcRequest } from '@solana/rpc-spec-types';
+
+import { getIntegerOverflowNodeVisitor } from './request-transformer-integer-overflow-internal';
+import { getTreeWalkerRequestTransformer, KeyPath } from './tree-traversal';
+
+export type IntegerOverflowHandler = (request: RpcRequest, keyPath: KeyPath, value: bigint) => void;
+
+/**
+ * Creates a transformer that traverses the request parameters and executes the provided handler
+ * when an integer overflow is detected.
+ *
+ * @example
+ * ```ts
+ * import { getIntegerOverflowRequestTransformer } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getIntegerOverflowRequestTransformer((request, keyPath, value) => {
+ *     throw new Error(`Integer overflow at ${keyPath.join('.')}: ${value}`);
+ * });
+ * ```
+ */
+export function getIntegerOverflowRequestTransformer(onIntegerOverflow: IntegerOverflowHandler) {
+    return <TParams>(request: RpcRequest<TParams>): RpcRequest => {
+        const transformer = getTreeWalkerRequestTransformer(
+            [getIntegerOverflowNodeVisitor((...args) => onIntegerOverflow(request, ...args))],
+            { keyPath: [] },
+        );
+        return transformer(request);
+    };
+}

package/src/request-transformer-options-object-position-config.ts

@@ -0,0 +1,41 @@
+export const OPTIONS_OBJECT_POSITION_BY_METHOD: Record<string, number> = {
+    accountNotifications: 1,
+    blockNotifications: 1,
+    getAccountInfo: 1,
+    getBalance: 1,
+    getBlock: 1,
+    getBlockHeight: 0,
+    getBlockProduction: 0,
+    getBlocks: 2,
+    getBlocksWithLimit: 2,
+    getEpochInfo: 0,
+    getFeeForMessage: 1,
+    getInflationGovernor: 0,
+    getInflationReward: 1,
+    getLargestAccounts: 0,
+    getLatestBlockhash: 0,
+    getLeaderSchedule: 1,
+    getMinimumBalanceForRentExemption: 1,
+    getMultipleAccounts: 1,
+    getProgramAccounts: 1,
+    getSignaturesForAddress: 1,
+    getSlot: 0,
+    getSlotLeader: 0,
+    getStakeMinimumDelegation: 0,
+    getSupply: 0,
+    getTokenAccountBalance: 1,
+    getTokenAccountsByDelegate: 2,
+    getTokenAccountsByOwner: 2,
+    getTokenLargestAccounts: 1,
+    getTokenSupply: 1,
+    getTransaction: 1,
+    getTransactionCount: 0,
+    getVoteAccounts: 0,
+    isBlockhashValid: 1,
+    logsNotifications: 1,
+    programNotifications: 1,
+    requestAirdrop: 2,
+    sendTransaction: 1,
+    signatureNotifications: 1,
+    simulateTransaction: 1,
+};

package/src/request-transformer.ts

@@ -0,0 +1,59 @@
+import { pipe } from '@solana/functional';
+import { RpcRequest, RpcRequestTransformer } from '@solana/rpc-spec-types';
+import { Commitment } from '@solana/rpc-types';
+
+import { getBigIntDowncastRequestTransformer } from './request-transformer-bigint-downcast';
+import { getDefaultCommitmentRequestTransformer } from './request-transformer-default-commitment';
+import { getIntegerOverflowRequestTransformer, IntegerOverflowHandler } from './request-transformer-integer-overflow';
+import { OPTIONS_OBJECT_POSITION_BY_METHOD } from './request-transformer-options-object-position-config';
+
+export type RequestTransformerConfig = Readonly<{
+    /**
+     * An optional {@link Commitment} value to use as the default when none is supplied by the
+     * caller.
+     */
+    defaultCommitment?: Commitment;
+    /**
+     * An optional function that will be called whenever a `bigint` input exceeds that which can be
+     * expressed using JavaScript numbers.
+     *
+     * This is used in the default {@link SolanaRpcSubscriptionsApi} to throw an exception rather
+     * than to allow truncated values to propagate through a program.
+     */
+    onIntegerOverflow?: IntegerOverflowHandler;
+}>;
+
+/**
+ * Returns the default request transformer for the Solana RPC API.
+ *
+ * Under the hood, this function composes multiple
+ * {@link RpcRequestTransformer | RpcRequestTransformers} together such as the
+ * {@link getDefaultCommitmentTransformer}, the {@link getIntegerOverflowRequestTransformer} and the
+ * {@link getBigIntDowncastRequestTransformer}.
+ *
+ * @example
+ * ```ts
+ * import { getDefaultRequestTransformerForSolanaRpc } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getDefaultRequestTransformerForSolanaRpc({
+ *     defaultCommitment: 'confirmed',
+ *     onIntegerOverflow: (request, keyPath, value) => {
+ *         throw new Error(`Integer overflow at ${keyPath.join('.')}: ${value}`);
+ *     },
+ * });
+ * ```
+ */
+export function getDefaultRequestTransformerForSolanaRpc(config?: RequestTransformerConfig): RpcRequestTransformer {
+    const handleIntegerOverflow = config?.onIntegerOverflow;
+    return (request: RpcRequest): RpcRequest => {
+        return pipe(
+            request,
+            handleIntegerOverflow ? getIntegerOverflowRequestTransformer(handleIntegerOverflow) : r => r,
+            getBigIntDowncastRequestTransformer(),
+            getDefaultCommitmentRequestTransformer({
+                defaultCommitment: config?.defaultCommitment,
+                optionsObjectPositionByMethod: OPTIONS_OBJECT_POSITION_BY_METHOD,
+            }),
+        );
+    };
+}

package/src/response-transformer-allowed-numeric-values.ts

@@ -0,0 +1,55 @@
+import { KeyPath, KEYPATH_WILDCARD } from './tree-traversal';
+
+export type AllowedNumericKeypaths<TApi> = Partial<Record<keyof TApi, readonly KeyPath[]>>;
+
+// Numeric values nested in `jsonParsed` accounts
+export const jsonParsedTokenAccountsConfigs = [
+    // parsed Token/Token22 token account
+    ['data', 'parsed', 'info', 'tokenAmount', 'decimals'],
+    ['data', 'parsed', 'info', 'tokenAmount', 'uiAmount'],
+    ['data', 'parsed', 'info', 'rentExemptReserve', 'decimals'],
+    ['data', 'parsed', 'info', 'rentExemptReserve', 'uiAmount'],
+    ['data', 'parsed', 'info', 'delegatedAmount', 'decimals'],
+    ['data', 'parsed', 'info', 'delegatedAmount', 'uiAmount'],
+    ['data', 'parsed', 'info', 'extensions', KEYPATH_WILDCARD, 'state', 'olderTransferFee', 'transferFeeBasisPoints'],
+    ['data', 'parsed', 'info', 'extensions', KEYPATH_WILDCARD, 'state', 'newerTransferFee', 'transferFeeBasisPoints'],
+    ['data', 'parsed', 'info', 'extensions', KEYPATH_WILDCARD, 'state', 'preUpdateAverageRate'],
+    ['data', 'parsed', 'info', 'extensions', KEYPATH_WILDCARD, 'state', 'currentRate'],
+];
+export const jsonParsedAccountsConfigs = [
+    ...jsonParsedTokenAccountsConfigs,
+    // parsed AddressTableLookup account
+    ['data', 'parsed', 'info', 'lastExtendedSlotStartIndex'],
+    // parsed Config account
+    ['data', 'parsed', 'info', 'slashPenalty'],
+    ['data', 'parsed', 'info', 'warmupCooldownRate'],
+    // parsed Token/Token22 mint account
+    ['data', 'parsed', 'info', 'decimals'],
+    // parsed Token/Token22 multisig account
+    ['data', 'parsed', 'info', 'numRequiredSigners'],
+    ['data', 'parsed', 'info', 'numValidSigners'],
+    // parsed Stake account
+    ['data', 'parsed', 'info', 'stake', 'delegation', 'warmupCooldownRate'],
+    // parsed Sysvar rent account
+    ['data', 'parsed', 'info', 'exemptionThreshold'],
+    ['data', 'parsed', 'info', 'burnPercent'],
+    // parsed Vote account
+    ['data', 'parsed', 'info', 'commission'],
+    ['data', 'parsed', 'info', 'votes', KEYPATH_WILDCARD, 'confirmationCount'],
+];
+export const innerInstructionsConfigs = [
+    ['index'],
+    ['instructions', KEYPATH_WILDCARD, 'accounts', KEYPATH_WILDCARD],
+    ['instructions', KEYPATH_WILDCARD, 'programIdIndex'],
+    ['instructions', KEYPATH_WILDCARD, 'stackHeight'],
+];
+export const messageConfig = [
+    ['addressTableLookups', KEYPATH_WILDCARD, 'writableIndexes', KEYPATH_WILDCARD],
+    ['addressTableLookups', KEYPATH_WILDCARD, 'readonlyIndexes', KEYPATH_WILDCARD],
+    ['header', 'numReadonlySignedAccounts'],
+    ['header', 'numReadonlyUnsignedAccounts'],
+    ['header', 'numRequiredSignatures'],
+    ['instructions', KEYPATH_WILDCARD, 'accounts', KEYPATH_WILDCARD],
+    ['instructions', KEYPATH_WILDCARD, 'programIdIndex'],
+    ['instructions', KEYPATH_WILDCARD, 'stackHeight'],
+] as const;

package/src/response-transformer-bigint-upcast-internal.ts

@@ -0,0 +1,32 @@
+import { KeyPath, KEYPATH_WILDCARD, TraversalState } from './tree-traversal';
+
+export function getBigIntUpcastVisitor(allowedNumericKeyPaths: readonly KeyPath[]) {
+    return function upcastNodeToBigIntIfNumber(value: unknown, { keyPath }: TraversalState) {
+        const isInteger = (typeof value === 'number' && Number.isInteger(value)) || typeof value === 'bigint';
+        if (!isInteger) return value;
+        if (keyPathIsAllowedToBeNumeric(keyPath, allowedNumericKeyPaths)) {
+            return Number(value);
+        } else {
+            return BigInt(value);
+        }
+    };
+}
+
+function keyPathIsAllowedToBeNumeric(keyPath: KeyPath, allowedNumericKeyPaths: readonly KeyPath[]) {
+    return allowedNumericKeyPaths.some(prohibitedKeyPath => {
+        if (prohibitedKeyPath.length !== keyPath.length) {
+            return false;
+        }
+        for (let ii = keyPath.length - 1; ii >= 0; ii--) {
+            const keyPathPart = keyPath[ii];
+            const prohibitedKeyPathPart = prohibitedKeyPath[ii];
+            if (
+                prohibitedKeyPathPart !== keyPathPart &&
+                (prohibitedKeyPathPart !== KEYPATH_WILDCARD || typeof keyPathPart !== 'number')
+            ) {
+                return false;
+            }
+        }
+        return true;
+    });
+}

package/src/response-transformer-bigint-upcast.ts

@@ -0,0 +1,25 @@
+import { getBigIntUpcastVisitor } from './response-transformer-bigint-upcast-internal';
+import { getTreeWalkerResponseTransformer, KeyPath } from './tree-traversal';
+
+/**
+ * Returns a transformer that upcasts all `Number` values to `BigInts` unless they match within the
+ * provided {@link KeyPath | KeyPaths}. In other words, the provided {@link KeyPath | KeyPaths} will
+ * remain as `Number` values, any other numeric value will be upcasted to a `BigInt`.
+ *
+ * Note that you can use {@link KEYPATH_WILDCARD} to match any key within a {@link KeyPath}.
+ *
+ * @example
+ * ```ts
+ * import { getBigIntUpcastResponseTransformer } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getBigIntUpcastResponseTransformer([
+ *     ['index'],
+ *     ['instructions', KEYPATH_WILDCARD, 'accounts', KEYPATH_WILDCARD],
+ *     ['instructions', KEYPATH_WILDCARD, 'programIdIndex'],
+ *     ['instructions', KEYPATH_WILDCARD, 'stackHeight'],
+ * ]);
+ * ```
+ */
+export function getBigIntUpcastResponseTransformer(allowedNumericKeyPaths: readonly KeyPath[]) {
+    return getTreeWalkerResponseTransformer([getBigIntUpcastVisitor(allowedNumericKeyPaths)], { keyPath: [] });
+}

package/src/response-transformer-result.ts

@@ -0,0 +1,19 @@
+import { RpcResponseTransformer } from '@solana/rpc-spec-types';
+
+type JsonRpcResponse = { result: unknown };
+
+/**
+ * Returns a transformer that extracts the `result` field from the body of the RPC response.
+ *
+ * For instance, we go from `{ jsonrpc: '2.0', result: 'foo', id: 1 }` to `'foo'`.
+ *
+ * @example
+ * ```ts
+ * import { getResultResponseTransformer } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getResultResponseTransformer();
+ * ```
+ */
+export function getResultResponseTransformer(): RpcResponseTransformer {
+    return json => (json as JsonRpcResponse).result;
+}

package/src/response-transformer-throw-solana-error.ts

@@ -0,0 +1,63 @@
+import { getSolanaErrorFromJsonRpcError } from '@solana/errors';
+import { RpcResponseTransformer } from '@solana/rpc-spec-types';
+
+import { innerInstructionsConfigs, jsonParsedAccountsConfigs } from './response-transformer-allowed-numeric-values';
+import { getBigIntUpcastVisitor } from './response-transformer-bigint-upcast-internal';
+import { getTreeWalkerResponseTransformer, KeyPath, KEYPATH_WILDCARD } from './tree-traversal';
+
+type JsonRpcResponse = { error: Parameters<typeof getSolanaErrorFromJsonRpcError>[0] } | { result: unknown };
+
+// Keypaths for simulateTransaction result that should remain as Number (not BigInt)
+// Note: These are relative to the error.data root, not result.value like in success responses
+function getSimulateTransactionAllowedNumericKeypaths(): readonly KeyPath[] {
+    return [
+        ['loadedAccountsDataSize'],
+        ...jsonParsedAccountsConfigs.map(c => ['accounts', KEYPATH_WILDCARD, ...c]),
+        ...innerInstructionsConfigs.map(c => ['innerInstructions', KEYPATH_WILDCARD, ...c]),
+    ];
+}
+
+/**
+ * Returns a transformer that throws a {@link SolanaError} with the appropriate RPC error code if
+ * the body of the RPC response contains an error.
+ *
+ * @example
+ * ```ts
+ * import { getThrowSolanaErrorResponseTransformer } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getThrowSolanaErrorResponseTransformer();
+ * ```
+ */
+export function getThrowSolanaErrorResponseTransformer(): RpcResponseTransformer {
+    return (json, request) => {
+        const jsonRpcResponse = json as JsonRpcResponse;
+        if ('error' in jsonRpcResponse) {
+            const { error } = jsonRpcResponse;
+
+            // Check if this is a sendTransaction preflight failure (error code -32002)
+            // These errors contain RpcSimulateTransactionResult in error.data which needs
+            // BigInt values downcast to Number for fields that should be numbers
+            const isSendTransactionPreflightFailure =
+                error &&
+                typeof error === 'object' &&
+                'code' in error &&
+                (error.code === -32002 || error.code === -32002n);
+
+            if (isSendTransactionPreflightFailure && 'data' in error && error.data) {
+                // Apply BigInt downcast transformation to error.data
+                const treeWalker = getTreeWalkerResponseTransformer(
+                    [getBigIntUpcastVisitor(getSimulateTransactionAllowedNumericKeypaths())],
+                    { keyPath: [] },
+                );
+                const transformedData = treeWalker(error.data, request);
+
+                // Reconstruct error with transformed data
+                const transformedError = { ...error, data: transformedData };
+                throw getSolanaErrorFromJsonRpcError(transformedError);
+            }
+
+            throw getSolanaErrorFromJsonRpcError(jsonRpcResponse.error);
+        }
+        return jsonRpcResponse;
+    };
+}

package/src/response-transformer.ts

@@ -0,0 +1,74 @@
+import { pipe } from '@solana/functional';
+import { RpcRequest, RpcResponse, RpcResponseTransformer } from '@solana/rpc-spec-types';
+
+import { AllowedNumericKeypaths } from './response-transformer-allowed-numeric-values';
+import { getBigIntUpcastResponseTransformer } from './response-transformer-bigint-upcast';
+import { getResultResponseTransformer } from './response-transformer-result';
+import { getThrowSolanaErrorResponseTransformer } from './response-transformer-throw-solana-error';
+
+export type ResponseTransformerConfig<TApi> = Readonly<{
+    /**
+     * An optional map from the name of an API method to an array of {@link KeyPath | KeyPaths}
+     * pointing to values in the response that should materialize in the application as `Number`
+     * instead of `BigInt`.
+     */
+    allowedNumericKeyPaths?: AllowedNumericKeypaths<TApi>;
+}>;
+
+/**
+ * Returns the default response transformer for the Solana RPC API.
+ *
+ * Under the hood, this function composes multiple
+ * {@link RpcResponseTransformer | RpcResponseTransformers} together such as the
+ * {@link getThrowSolanaErrorResponseTransformer}, the {@link getResultResponseTransformer} and the
+ * {@link getBigIntUpcastResponseTransformer}.
+ *
+ * @example
+ * ```ts
+ * import { getDefaultResponseTransformerForSolanaRpc } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getDefaultResponseTransformerForSolanaRpc({
+ *     allowedNumericKeyPaths: getAllowedNumericKeypaths(),
+ * });
+ * ```
+ */
+export function getDefaultResponseTransformerForSolanaRpc<TApi>(
+    config?: ResponseTransformerConfig<TApi>,
+): RpcResponseTransformer {
+    return (response: RpcResponse, request: RpcRequest): RpcResponse => {
+        const methodName = request.methodName as keyof TApi;
+        const keyPaths =
+            config?.allowedNumericKeyPaths && methodName ? config.allowedNumericKeyPaths[methodName] : undefined;
+        return pipe(
+            response,
+            r => getThrowSolanaErrorResponseTransformer()(r, request),
+            r => getResultResponseTransformer()(r, request),
+            r => getBigIntUpcastResponseTransformer(keyPaths ?? [])(r, request),
+        );
+    };
+}
+
+/**
+ * Returns the default response transformer for the Solana RPC Subscriptions API.
+ *
+ * Under the hood, this function composes the {@link getBigIntUpcastResponseTransformer}.
+ *
+ * @example
+ * ```ts
+ * import { getDefaultResponseTransformerForSolanaRpcSubscriptions } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getDefaultResponseTransformerForSolanaRpcSubscriptions({
+ *     allowedNumericKeyPaths: getAllowedNumericKeypaths(),
+ * });
+ * ```
+ */
+export function getDefaultResponseTransformerForSolanaRpcSubscriptions<TApi>(
+    config?: ResponseTransformerConfig<TApi>,
+): RpcResponseTransformer {
+    return (response: RpcResponse, request: RpcRequest): RpcResponse => {
+        const methodName = request.methodName as keyof TApi;
+        const keyPaths =
+            config?.allowedNumericKeyPaths && methodName ? config.allowedNumericKeyPaths[methodName] : undefined;
+        return pipe(response, r => getBigIntUpcastResponseTransformer(keyPaths ?? [])(r, request));
+    };
+}

package/src/tree-traversal.ts

@@ -0,0 +1,79 @@
+import { RpcRequest, RpcRequestTransformer, RpcResponseTransformer } from '@solana/rpc-spec-types';
+
+export type KeyPathWildcard = { readonly ['__keyPathWildcard:@solana/kit']: unique symbol };
+export type KeyPath = ReadonlyArray<KeyPath | KeyPathWildcard | number | string>;
+
+export const KEYPATH_WILDCARD = {} as KeyPathWildcard;
+
+type NodeVisitor = <TState extends TraversalState>(value: unknown, state: TState) => unknown;
+export type TraversalState = Readonly<{
+    keyPath: KeyPath;
+}>;
+
+function getTreeWalker(visitors: NodeVisitor[]) {
+    return function traverse<TState extends TraversalState>(node: unknown, state: TState): unknown {
+        if (Array.isArray(node)) {
+            return node.map((element, ii) => {
+                const nextState = {
+                    ...state,
+                    keyPath: [...state.keyPath, ii],
+                };
+                return traverse(element, nextState);
+            });
+        } else if (typeof node === 'object' && node !== null) {
+            const out: Record<number | string | symbol, unknown> = {};
+            for (const propName in node) {
+                if (!Object.prototype.hasOwnProperty.call(node, propName)) {
+                    continue;
+                }
+                const nextState = {
+                    ...state,
+                    keyPath: [...state.keyPath, propName],
+                };
+                out[propName] = traverse(node[propName as keyof typeof node], nextState);
+            }
+            return out;
+        } else {
+            return visitors.reduce((acc, visitNode) => visitNode(acc, state), node);
+        }
+    };
+}
+
+/**
+ * Creates a transformer that traverses the request parameters and executes the provided visitors at
+ * each node. A custom initial state can be provided but must at least provide `{ keyPath: [] }`.
+ *
+ * @example
+ * ```ts
+ * import { getTreeWalkerRequestTransformer } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getTreeWalkerRequestTransformer(
+ *     [
+ *         // Replaces foo.bar with "baz".
+ *         (node, state) => (state.keyPath === ['foo', 'bar'] ? 'baz' : node),
+ *         // Increments all numbers by 1.
+ *         node => (typeof node === number ? node + 1 : node),
+ *     ],
+ *     { keyPath: [] },
+ * );
+ * ```
+ */
+export function getTreeWalkerRequestTransformer<TState extends TraversalState>(
+    visitors: NodeVisitor[],
+    initialState: TState,
+): RpcRequestTransformer {
+    return <TParams>(request: RpcRequest<TParams>): RpcRequest => {
+        const traverse = getTreeWalker(visitors);
+        return Object.freeze({
+            ...request,
+            params: traverse(request.params, initialState),
+        });
+    };
+}
+
+export function getTreeWalkerResponseTransformer<TState extends TraversalState>(
+    visitors: NodeVisitor[],
+    initialState: TState,
+): RpcResponseTransformer {
+    return json => getTreeWalker(visitors)(json, initialState);
+}