fix: stop upcasting transaction version to bigint

.changeset/small-birds-cheer.md

@@ -0,0 +1,9 @@
+---
+'@solana/rpc-api': patch
+---
+
+Stop upcasting transaction `version` to `bigint`
+
+The response transformer upcasts every JSON integer to a `bigint` unless its keypath appears in an allow-list. `version` was missing from that allow-list on `getTransaction`, `getBlock` transactions, and `getTransactionsForAddress`, so it arrived at runtime as `0n` while still typechecking as `TransactionVersion` (`'legacy' | 0 | 1`).
+
+A check like `if (transaction.version === 0)` therefore compiled cleanly and was always false, with no compiler error and no runtime error. The keypath is now allow-listed and `version` arrives as a number, matching its declared type.

packages/rpc-api/src/__tests__/allowed-numeric-keypaths-test.ts

@@ -0,0 +1,65 @@
+import type { Address } from '@solana/addresses';
+import type { Signature } from '@solana/keys';
+import { createRpc, type Rpc } from '@solana/rpc-spec';
+
+import { createSolanaRpcApi, GetBlockApi, GetTransactionApi, GetTransactionsForAddressApi } from '../index';
+
+const MOCK_SIGNATURE =
+    '4nHvMbxHURt2AXd7yQpKSKM5XCVKQiNbfsFmvPtHNJnJPSJHFT6cGUUNQGYK3wcxDCTvBMTLpQFf6HGqhLTUsxwj' as Signature;
+
+function createMockRpc<TApi>(result: unknown): Rpc<TApi> {
+    return createRpc({
+        api: createSolanaRpcApi<never>(),
+        transport: jest.fn().mockResolvedValue({ result }),
+    });
+}
+
+describe('the default response transformer for the Solana RPC', () => {
+    describe('getTransaction', () => {
+        it('leaves `version` as a number', async () => {
+            expect.assertions(1);
+            const rpc = createMockRpc<GetTransactionApi>({ meta: null, slot: 1, version: 0 });
+            const result = await rpc
+                .getTransaction(MOCK_SIGNATURE, { encoding: 'json', maxSupportedTransactionVersion: 0 })
+                .send();
+            expect(result?.version).toBe(0);
+        });
+        it('leaves the string `version` of a legacy transaction alone', async () => {
+            expect.assertions(1);
+            const rpc = createMockRpc<GetTransactionApi>({ meta: null, slot: 1, version: 'legacy' });
+            const result = await rpc
+                .getTransaction(MOCK_SIGNATURE, { encoding: 'json', maxSupportedTransactionVersion: 0 })
+                .send();
+            expect(result?.version).toBe('legacy');
+        });
+    });
+
+    describe('getBlock', () => {
+        it('leaves the `version` of each transaction as a number', async () => {
+            expect.assertions(1);
+            const rpc = createMockRpc<GetBlockApi>({
+                blockhash: '4nHvMbxHURt2AXd7yQpKSKM5XCVKQiNbfsFmvPtHNJnJ',
+                transactions: [{ meta: null, version: 0 }],
+            });
+            const result = await rpc.getBlock(1n, { encoding: 'json', maxSupportedTransactionVersion: 0 }).send();
+            expect(result?.transactions[0].version).toBe(0);
+        });
+    });
+
+    describe('getTransactionsForAddress', () => {
+        it('leaves the `version` of each transaction as a number', async () => {
+            expect.assertions(1);
+            const rpc = createMockRpc<GetTransactionsForAddressApi>({
+                data: [{ meta: null, version: 0 }],
+            });
+            const result = await rpc
+                .getTransactionsForAddress('11111111111111111111111111111111' as Address, {
+                    encoding: 'json',
+                    maxSupportedTransactionVersion: 0,
+                    transactionDetails: 'full',
+                })
+                .send();
+            expect(result.data[0].version).toBe(0);
+        });
+    });
+});

packages/rpc-api/src/index.ts

@@ -300,6 +300,7 @@ function getAllowedNumericKeypaths(): AllowedNumericKeypaths<RpcApi<SolanaRpcApi
                     ...c,
                 ]),
                 ...messageConfig.map(c => ['transactions', KEYPATH_WILDCARD, 'transaction', 'message', ...c] as const),
+                ['transactions', KEYPATH_WILDCARD, 'version'],
                 ['rewards', KEYPATH_WILDCARD, 'commission'],
             ],
             getClusterNodes: [
@@ -348,6 +349,7 @@ function getAllowedNumericKeypaths(): AllowedNumericKeypaths<RpcApi<SolanaRpcApi
                 ['meta', 'rewards', KEYPATH_WILDCARD, 'commission'],
                 ...innerInstructionsConfigs.map(c => ['meta', 'innerInstructions', KEYPATH_WILDCARD, ...c]),
                 ...messageConfig.map(c => ['transaction', 'message', ...c] as const),
+                ['version'],
             ],
             getTransactionsForAddress: [
                 ['data', KEYPATH_WILDCARD, 'transactionIndex'],
@@ -365,6 +367,7 @@ function getAllowedNumericKeypaths(): AllowedNumericKeypaths<RpcApi<SolanaRpcApi
                     ...c,
                 ]),
                 ...messageConfig.map(c => ['data', KEYPATH_WILDCARD, 'transaction', 'message', ...c] as const),
+                ['data', KEYPATH_WILDCARD, 'version'],
             ],
             getVersion: [['feature-set']],
             getVoteAccounts: [