feat: add transaction rpc helper and prep utilities

Author: GuiBibeau

examples/react-hooks/src/App.tsx

@@ -1,4 +1,4 @@
-import type { SolanaClientConfig, WalletConnector } from '@solana/client-core';
+import { createSolanaRpcClient, type SolanaClientConfig, type WalletConnector } from '@solana/client-core';
 import { SolanaClientProvider, useConnectWallet, useWallet, useWalletStandardConnectors } from '@solana/react-hooks';
 import { useEffect, useMemo, useRef } from 'react';
 
@@ -18,13 +18,23 @@ const DEFAULT_CLIENT_CONFIG: SolanaClientConfig = {
 
 export default function App() {
 	const walletConnectors = useWalletStandardConnectors();
+	const rpcClient = useMemo(
+		() =>
+			createSolanaRpcClient({
+				commitment: DEFAULT_CLIENT_CONFIG.commitment,
+				endpoint: DEFAULT_CLIENT_CONFIG.endpoint,
+				websocketEndpoint: DEFAULT_CLIENT_CONFIG.websocketEndpoint,
+			}),
+		[],
+	);
 
 	const clientConfig = useMemo<SolanaClientConfig>(
 		() => ({
 			...DEFAULT_CLIENT_CONFIG,
+			rpcClient,
 			walletConnectors,
 		}),
-		[walletConnectors],
+		[rpcClient, walletConnectors],
 	);
 
 	return (

packages/client-core/src/client/actions.test.ts

@@ -6,8 +6,6 @@ import type { ClientActions, SolanaClientRuntime, WalletConnector, WalletRegistr
 import { createActions } from './actions';
 import { createDefaultClientStore } from './createClientStore';
 
-const createSolanaRpcMock = vi.hoisted(() => vi.fn());
-const createSolanaRpcSubscriptionsMock = vi.hoisted(() => vi.fn());
 const getBase64EncodedWireTransactionMock = vi.hoisted(() => vi.fn((tx: unknown) => `wire:${String(tx)}`));
 const airdropFactoryMock = vi.hoisted(() => vi.fn());
 const createBlockHeightExceedencePromiseFactoryMock = vi.hoisted(() => vi.fn());
@@ -20,13 +18,27 @@ const nowMock = vi.hoisted(() => {
 	return vi.fn(() => ++current);
 });
 
+const createSolanaRpcClientMock = vi.hoisted(() =>
+	vi.fn(() => ({
+		commitment: 'confirmed',
+		endpoint: 'https://rpc.test',
+		rpc: {} as SolanaClientRuntime['rpc'],
+		rpcSubscriptions: {} as SolanaClientRuntime['rpcSubscriptions'],
+		sendAndConfirmTransaction: vi.fn(),
+		simulateTransaction: vi.fn(),
+		websocketEndpoint: 'wss://rpc.test',
+	})),
+);
+
 vi.mock('@solana/kit', () => ({
-	createSolanaRpc: createSolanaRpcMock,
-	createSolanaRpcSubscriptions: createSolanaRpcSubscriptionsMock,
 	getBase64EncodedWireTransaction: getBase64EncodedWireTransactionMock,
 	airdropFactory: airdropFactoryMock,
 }));
 
+vi.mock('../rpc/createSolanaRpcClient', () => ({
+	createSolanaRpcClient: createSolanaRpcClientMock,
+}));
+
 vi.mock('@solana/transaction-confirmation', () => ({
 	createBlockHeightExceedencePromiseFactory: createBlockHeightExceedencePromiseFactoryMock,
 	createRecentSignatureConfirmationPromiseFactory: createRecentSignatureConfirmationPromiseFactoryMock,
@@ -92,14 +104,21 @@ describe('client actions', () => {
 			signatureNotifications: vi.fn(),
 		} as unknown as SolanaClientRuntime['rpcSubscriptions'];
 
-		createSolanaRpcMock.mockReturnValue(rpc);
-		createSolanaRpcSubscriptionsMock.mockReturnValue(rpcSubscriptions);
-
 		runtime = {
 			rpc: rpc as unknown as SolanaClientRuntime['rpc'],
 			rpcSubscriptions,
 		};
 
+		createSolanaRpcClientMock.mockImplementation(({ commitment, endpoint, websocketEndpoint }) => ({
+			commitment: commitment ?? 'confirmed',
+			endpoint,
+			rpc: { endpoint } as SolanaClientRuntime['rpc'],
+			rpcSubscriptions: { endpoint: websocketEndpoint ?? endpoint } as SolanaClientRuntime['rpcSubscriptions'],
+			sendAndConfirmTransaction: vi.fn(),
+			simulateTransaction: vi.fn(),
+			websocketEndpoint: websocketEndpoint ?? endpoint,
+		}));
+
 		walletConnector = {
 			id: 'wallet-1',
 			name: 'Wallet 1',
@@ -134,8 +153,11 @@ describe('client actions', () => {
 		const state = store.getState();
 		expect(state.cluster.endpoint).toBe('https://new.rpc');
 		expect(state.cluster.status).toMatchObject({ status: 'ready' });
-		expect(createSolanaRpcMock).toHaveBeenCalledWith('https://new.rpc');
-		expect(createSolanaRpcSubscriptionsMock).toHaveBeenCalledWith('wss://new');
+		expect(createSolanaRpcClientMock).toHaveBeenCalledWith({
+			commitment: 'processed',
+			endpoint: 'https://new.rpc',
+			websocketEndpoint: 'wss://new',
+		});
 	});
 
 	it('connects and disconnects a wallet, handling errors', async () => {

packages/client-core/src/client/actions.ts

@@ -7,12 +7,7 @@ import type {
 	Signature,
 	Transaction,
 } from '@solana/kit';
-import {
-	airdropFactory,
-	createSolanaRpc,
-	createSolanaRpcSubscriptions,
-	getBase64EncodedWireTransaction,
-} from '@solana/kit';
+import { airdropFactory, getBase64EncodedWireTransaction } from '@solana/kit';
 import type { TransactionWithLastValidBlockHeight } from '@solana/transaction-confirmation';
 import {
 	createBlockHeightExceedencePromiseFactory,
@@ -21,6 +16,7 @@ import {
 } from '@solana/transaction-confirmation';
 
 import { createLogger, formatError } from '../logging/logger';
+import { createSolanaRpcClient } from '../rpc/createSolanaRpcClient';
 import type { ClientActions, ClientState, ClientStore, SolanaClientRuntime, WalletRegistry } from '../types';
 import { now } from '../utils';
 
@@ -113,8 +109,13 @@ export function createActions({ connectors, logger: inputLogger, runtime, store
 			lastUpdatedAt: now(),
 		}));
 		try {
-			runtime.rpc = createSolanaRpc(endpoint);
-			runtime.rpcSubscriptions = createSolanaRpcSubscriptions(websocketEndpoint);
+			const newRpcClient = createSolanaRpcClient({
+				commitment: nextCommitment,
+				endpoint,
+				websocketEndpoint,
+			});
+			runtime.rpc = newRpcClient.rpc;
+			runtime.rpcSubscriptions = newRpcClient.rpcSubscriptions;
 			const latencyMs = await warmupCluster(endpoint, nextCommitment);
 			store.setState((state) => ({
 				...state,

packages/client-core/src/client/createClient.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
+import type { SolanaRpcClient } from '../rpc/createSolanaRpcClient';
 import type { SolanaClientConfig } from '../types';
 import { createClient } from './createClient';
 
@@ -9,8 +10,6 @@ type Logger = ReturnType<ReturnType<typeof createLoggerMock>>;
 
 type Helpers = ReturnType<typeof createClientHelpersMock>;
 
-const createSolanaRpcMock = vi.hoisted(() => vi.fn(() => ({ rpc: true })));
-const createSolanaRpcSubscriptionsMock = vi.hoisted(() => vi.fn(() => ({ sub: true })));
 const createActionsMock = vi.hoisted(() =>
 	vi.fn(() => ({
 		setCluster: vi.fn().mockResolvedValue(undefined),
@@ -37,10 +36,23 @@ const createWalletRegistryMock = vi.hoisted(() =>
 const createLoggerMock = vi.hoisted(() => vi.fn(() => vi.fn()));
 const formatErrorMock = vi.hoisted(() => vi.fn((error: unknown) => ({ formatted: error })));
 const nowMock = vi.hoisted(() => vi.fn(() => 111));
+const createSolanaRpcClientMock = vi.hoisted(() =>
+	vi.fn(
+		() =>
+			({
+				commitment: 'confirmed',
+				endpoint: 'https://rpc.example',
+				rpc: { tag: 'rpc' },
+				rpcSubscriptions: { tag: 'sub' },
+				sendAndConfirmTransaction: vi.fn(),
+				simulateTransaction: vi.fn(),
+				websocketEndpoint: 'wss://rpc.example',
+			}) satisfies SolanaRpcClient,
+	),
+);
 
-vi.mock('@solana/kit', () => ({
-	createSolanaRpc: createSolanaRpcMock,
-	createSolanaRpcSubscriptions: createSolanaRpcSubscriptionsMock,
+vi.mock('../rpc/createSolanaRpcClient', () => ({
+	createSolanaRpcClient: createSolanaRpcClientMock,
 }));
 
 vi.mock('../logging/logger', () => ({
@@ -87,8 +99,11 @@ describe('createClient', () => {
 
 	it('instantiates the client with runtime wiring and helpers', async () => {
 		const client = createClient(config);
-		expect(createSolanaRpcMock).toHaveBeenCalledWith('https://rpc.example');
-		expect(createSolanaRpcSubscriptionsMock).toHaveBeenCalledWith('https://rpc.example');
+		expect(createSolanaRpcClientMock).toHaveBeenCalledWith({
+			commitment: 'finalized',
+			endpoint: 'https://rpc.example',
+			websocketEndpoint: 'https://rpc.example',
+		});
 		expect(createWalletRegistryMock).toHaveBeenCalledWith(config.walletConnectors);
 		expect(createActionsMock).toHaveBeenCalled();
 		expect(createWatchersMock).toHaveBeenCalled();
@@ -110,6 +125,24 @@ describe('createClient', () => {
 		expect(client.store.getState().cluster.status).toEqual({ status: 'idle' });
 	});
 
+	it('respects a provided rpcClient instance', () => {
+		const rpcClient = {
+			commitment: 'processed',
+			endpoint: 'https://rpc.example',
+			rpc: { tag: 'external-rpc' },
+			rpcSubscriptions: { tag: 'external-sub' },
+			sendAndConfirmTransaction: vi.fn(),
+			simulateTransaction: vi.fn(),
+			websocketEndpoint: 'wss://rpc.example',
+		} satisfies SolanaRpcClient;
+		createClient({
+			...config,
+			commitment: 'processed',
+			rpcClient,
+		});
+		expect(createSolanaRpcClientMock).not.toHaveBeenCalled();
+	});
+
 	it('logs errors when initial cluster setup fails', async () => {
 		const logger = vi.fn();
 		createLoggerMock.mockReturnValueOnce(logger as Logger);

packages/client-core/src/client/createClient.ts

@@ -1,6 +1,5 @@
-import { createSolanaRpc, createSolanaRpcSubscriptions } from '@solana/kit';
-
 import { createLogger, formatError } from '../logging/logger';
+import { createSolanaRpcClient } from '../rpc/createSolanaRpcClient';
 import type { ClientStore, SolanaClient, SolanaClientConfig, SolanaClientRuntime } from '../types';
 import { now } from '../utils';
 import { createWalletRegistry } from '../wallet/registry';
@@ -24,9 +23,16 @@ export function createClient(config: SolanaClientConfig): SolanaClient {
 		websocketEndpoint,
 	});
 	const store: ClientStore = config.createStore ? config.createStore(initialState) : createClientStore(initialState);
+	const rpcClient =
+		config.rpcClient ??
+		createSolanaRpcClient({
+			commitment,
+			endpoint: config.endpoint,
+			websocketEndpoint,
+		});
 	const runtime: SolanaClientRuntime = {
-		rpc: createSolanaRpc(config.endpoint),
-		rpcSubscriptions: createSolanaRpcSubscriptions(websocketEndpoint),
+		rpc: rpcClient.rpc,
+		rpcSubscriptions: rpcClient.rpcSubscriptions,
 	};
 	const connectors = createWalletRegistry(config.walletConnectors ?? []);
 	const logger = createLogger(config.logger);
@@ -78,6 +84,7 @@ export function createClient(config: SolanaClientConfig): SolanaClient {
 		get transaction() {
 			return helpers.transaction;
 		},
+		prepareTransaction: helpers.prepareTransaction,
 		watchers,
 	};
 }

packages/client-core/src/client/createClientHelpers.test.ts

@@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { SolTransferPrepareConfig } from '../features/sol';
 import type { SplTokenHelperConfig } from '../features/spl';
+import type { PrepareTransactionMessage } from '../transactions/prepareTransaction';
 import { createClientHelpers } from './createClientHelpers';
 import { createDefaultClientStore } from './createClientStore';
 
@@ -33,6 +34,8 @@ const createTransactionHelperMock = vi.hoisted(() =>
 	})),
 );
 
+const prepareTransactionMock = vi.hoisted(() => vi.fn());
+
 vi.mock('../features/sol', () => ({
 	createSolTransferHelper: createSolTransferHelperMock,
 }));
@@ -45,6 +48,10 @@ vi.mock('../features/transactions', () => ({
 	createTransactionHelper: createTransactionHelperMock,
 }));
 
+vi.mock('../transactions/prepareTransaction', () => ({
+	prepareTransaction: prepareTransactionMock,
+}));
+
 describe('client helpers', () => {
 	const runtime = {
 		rpc: {} as unknown,
@@ -61,6 +68,7 @@ describe('client helpers', () => {
 		createSolTransferHelperMock.mockClear();
 		createSplTokenHelperMock.mockClear();
 		createTransactionHelperMock.mockClear();
+		prepareTransactionMock.mockClear();
 	});
 
 	it('lazily creates sol transfer helper and injects default commitment', async () => {
@@ -108,4 +116,13 @@ describe('client helpers', () => {
 		const splDifferent = helpers.splToken({ ...splDifferentConfig });
 		expect(splDifferent).not.toBe(splA);
 	});
+
+	it('prepares transactions using the runtime RPC', async () => {
+		const store = createDefaultClientStore(config);
+		const rpc = { tag: 'rpc' };
+		const helpers = createClientHelpers({ ...runtime, rpc } as never, store);
+		const transaction = { tag: 'message' } as unknown as PrepareTransactionMessage;
+		await helpers.prepareTransaction({ transaction });
+		expect(prepareTransactionMock).toHaveBeenCalledWith({ transaction, rpc });
+	});
 });

packages/client-core/src/client/createClientHelpers.ts

@@ -3,6 +3,11 @@ import type { Commitment } from '@solana/kit';
 import { createSolTransferHelper, type SolTransferHelper } from '../features/sol';
 import { createSplTokenHelper, type SplTokenHelper, type SplTokenHelperConfig } from '../features/spl';
 import { createTransactionHelper, type TransactionHelper } from '../features/transactions';
+import {
+	type PrepareTransactionMessage,
+	type PrepareTransactionOptions,
+	prepareTransaction as prepareTransactionUtility,
+} from '../transactions/prepareTransaction';
 import type { ClientHelpers, ClientStore, SolanaClientRuntime } from '../types';
 
 type SplTokenCacheEntry = Readonly<{
@@ -108,6 +113,14 @@ export function createClientHelpers(runtime: SolanaClientRuntime, store: ClientS
 		return scoped;
 	}
 
+	const prepareTransactionWithRuntime = <TMessage extends PrepareTransactionMessage>(
+		options: PrepareTransactionOptions<TMessage>,
+	) =>
+		prepareTransactionUtility({
+			...options,
+			rpc: runtime.rpc as Parameters<typeof prepareTransactionUtility>[0]['rpc'],
+		});
+
 	return Object.freeze({
 		get solTransfer() {
 			return getSolTransfer();
@@ -116,5 +129,6 @@ export function createClientHelpers(runtime: SolanaClientRuntime, store: ClientS
 		get transaction() {
 			return getTransaction();
 		},
+		prepareTransaction: prepareTransactionWithRuntime,
 	});
 }

packages/client-core/src/index.ts

@@ -41,7 +41,25 @@ export {
 	toBigint,
 } from './numeric/math';
 export { type ApplyRatioOptions, applyRatio, createRatio, type Ratio, type RoundingMode } from './numeric/rational';
+export {
+	type CreateSolanaRpcClientConfig,
+	createSolanaRpcClient,
+	type SendAndConfirmTransactionOptions,
+	type SimulateTransactionOptions,
+	type SolanaRpcClient,
+} from './rpc/createSolanaRpcClient';
 export { bigintFromJson, bigintToJson, lamportsFromJson, lamportsToJson } from './serialization/json';
+export {
+	transactionToBase64,
+	transactionToBase64WithSigners,
+} from './transactions/base64';
+export {
+	type PrepareTransactionConfig,
+	type PrepareTransactionMessage,
+	type PrepareTransactionOptions,
+	prepareTransaction,
+} from './transactions/prepareTransaction';
+export { insertReferenceKey, insertReferenceKeys } from './transactions/referenceKeys';
 export type {
 	AccountCache,
 	AccountCacheEntry,