Auto-detect transaction version

Author: GuiBibeau

packages/client-core/README.md

@@ -14,10 +14,10 @@ pnpm add @solana/client-core
 ## Quick start
 
 ```ts
-import { createClient } from '@solana/client-core';
+import { createClient } from "@solana/client-core";
 
 const client = createClient({
-	endpoint: 'https://api.devnet.solana.com',
+  endpoint: "https://api.devnet.solana.com",
 });
 
 // Fetch an account once.
@@ -26,7 +26,7 @@ console.log(account.lamports?.toString());
 
 // Watch lamports in real time.
 const watcher = client.watchers.watchBalance({ address }, (lamports) => {
-	console.log('balance:', lamports.toString());
+  console.log("balance:", lamports.toString());
 });
 
 // Later…
@@ -50,8 +50,8 @@ watcher.abort();
 
 ```ts
 const prepared = await client.helpers.transaction.prepare({
-	authority: walletSession,
-	instructions: [instruction],
+  authority: walletSession,
+  instructions: [instruction],
 });
 
 const signature = await client.helpers.transaction.send(prepared);
@@ -62,6 +62,7 @@ console.log(signature.toString());
 - `sign` / `toWire` let you collect signatures or emit Base64 manually.
 - `send` submits the prepared transaction (or uses `signAndSend` if the wallet supports it).
 - `prepareAndSend` runs everything plus an optional simulation/logging pass via `prepareTransaction`.
+- Versions default to `0` automatically when any instruction references address lookup tables, otherwise `legacy`; pass `version` if you need to override.
 
 Need just the tuning step? Call `client.prepareTransaction` directly with your unsigned message.
 

packages/client-core/src/features/transactions.test.ts

@@ -165,3 +165,45 @@ describe('createTransactionHelper.prepareAndSend', () => {
 		);
 	});
 });
+
+describe('createTransactionHelper.prepare', () => {
+	const runtime = {
+		rpc: {
+			getLatestBlockhash: vi.fn(() => ({
+				send: vi.fn().mockResolvedValue({ value: { blockhash: 'abc', lastValidBlockHeight: 123n } }),
+			})),
+			sendTransaction: vi.fn(),
+		},
+		rpcSubscriptions: {} as never,
+	};
+	const getFallbackCommitment = () => 'confirmed' as Commitment;
+	const authority: TransactionSigner = { address: 'payer' } as TransactionSigner;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it('defaults to legacy when instructions do not reference address tables', async () => {
+		const helper = createTransactionHelper(runtime as never, getFallbackCommitment);
+		await helper.prepare({
+			authority,
+			instructions: [{ programAddress: 'Demo1111111111111111111111111111111111', data: new Uint8Array([1]) }],
+		});
+		expect(createTransactionMessageMock).toHaveBeenCalledWith({ version: 'legacy' });
+	});
+
+	it('selects version 0 automatically when instructions reference address tables', async () => {
+		const helper = createTransactionHelper(runtime as never, getFallbackCommitment);
+		await helper.prepare({
+			authority,
+			instructions: [
+				{
+					programAddress: 'Demo1111111111111111111111111111111111',
+					data: new Uint8Array([1]),
+					addressTableLookups: [{}],
+				},
+			],
+		});
+		expect(createTransactionMessageMock).toHaveBeenCalledWith({ version: 0 });
+	});
+});

packages/client-core/src/features/transactions.ts

@@ -132,11 +132,28 @@ function hasSetComputeUnitPriceInstruction(instructions: readonly TransactionIns
 	);
 }
 
-function resolveVersion(requested?: TransactionVersion | 'auto'): TransactionVersion {
+function instructionUsesAddressLookup(instruction: TransactionInstruction): boolean {
+	if ('addressTableLookup' in instruction && instruction.addressTableLookup != null) {
+		return true;
+	}
+	if (
+		'addressTableLookups' in instruction &&
+		Array.isArray(instruction.addressTableLookups) &&
+		instruction.addressTableLookups.length > 0
+	) {
+		return true;
+	}
+	return false;
+}
+
+function resolveVersion(
+	requested: TransactionVersion | 'auto' | undefined,
+	instructions: readonly TransactionInstruction[],
+): TransactionVersion {
 	if (requested && requested !== 'auto') {
 		return requested;
 	}
-	return 'legacy';
+	return instructions.some(instructionUsesAddressLookup) ? 0 : 'legacy';
 }
 
 function normaliseCommitment(request: TransactionPrepareRequest, getFallbackCommitment: () => Commitment): Commitment {
@@ -225,9 +242,8 @@ export function createTransactionHelper(
 			}
 		}
 
-		const version = resolveVersion(request.version);
-
 		const baseInstructions = [...request.instructions];
+		const version = resolveVersion(request.version, baseInstructions);
 
 		const lifetime =
 			request.lifetime ??