1---
2title: "Advanced: Manual Transactions, Direct RPC & Custom Plugins"
3description: Manual transaction building with pipe composition, direct RPC client usage, RPC method reference, building custom plugins, and assembling domain-specific clients.
4---
5 
6# Advanced: Manual Transactions, Direct RPC & Custom Plugins
7 
8This reference covers low-level patterns for when you need full control over the transaction lifecycle, direct RPC access, or want to build custom plugins and domain-specific clients.
9 
10For most use cases, prefer the plugin clients in [overview.md](overview.md) and [plugins.md](plugins.md).
11 
12---
13 
14## Manual Transaction Pipeline
15 
16### Transaction Flow
17 
181. Create message → 2. Fee payer → 3. Lifetime → 4. Instructions → 5. Sign → 6. Send
19 
20### Pipe Composition
21 
22```ts
23import {
24  pipe, createTransactionMessage, setTransactionMessageFeePayerSigner,
25  setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstruction,
26  prependTransactionMessageInstruction,
27} from '@solana/kit';
28 
29const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
30 
31const message = pipe(
32  createTransactionMessage({ version: 0 }),
33  m => setTransactionMessageFeePayerSigner(signer, m),
34  m => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, m),
35  m => appendTransactionMessageInstruction(instruction, m),
36);
37```
38 
39### Fee Payer
40 
41```ts
42// With signer (recommended) — enables signTransactionMessageWithSigners()
43const msg = setTransactionMessageFeePayerSigner(signer, message);
44 
45// Address only — for multisig or when fee payer is a different party
46const msg = setTransactionMessageFeePayer(feePayerAddress, message);
47```
48 
49### Lifetime
50 
51```ts
52// Blockhash
53const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
54const msg = setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, message);
55 
56// Durable nonce — auto-adds AdvanceNonceAccount instruction
57const msg = setTransactionMessageLifetimeUsingDurableNonce(nonceInfo, message);
58```
59 
60### Instructions
61 
62```ts
63// Append
64const msg = appendTransactionMessageInstruction(instruction, message);
65const msg = appendTransactionMessageInstructions([i1, i2, i3], message);
66 
67// Prepend (for compute budget)
68const msg = prependTransactionMessageInstruction(computeBudgetIx, message);
69```
70 
71### Creating Raw Instructions
72 
73```ts
74import { AccountRole } from '@solana/instructions';
75 
76const instruction: Instruction = {
77  programAddress: address('Token...'),
78  accounts: [
79    { address: source, role: AccountRole.WRITABLE_SIGNER },
80    { address: dest, role: AccountRole.WRITABLE },
81    { address: owner, role: AccountRole.READONLY_SIGNER },
82  ],
83  data: instructionData,
84};
85```
86 
87---
88 
89## Compute Budget
90 
91Should be used for production transactions.
92 
93### Setup CU Estimator
94 
95```ts
96import {
97  getSetComputeUnitPriceInstruction,
98  estimateComputeUnitLimitFactory,
99  estimateAndUpdateProvisoryComputeUnitLimitFactory,
100} from '@solana-program/compute-budget';
101 
102const estimateAndUpdateCU = estimateAndUpdateProvisoryComputeUnitLimitFactory(
103  estimateComputeUnitLimitFactory({ rpc })
104);
105```
106 
107### Full Pattern: Priority Fee + CU Estimation + Blockhash Refresh
108 
109```ts
110// 1. Build message with priority fee
111let message = pipe(
112  createTransactionMessage({ version: 0 }),
113  m => setTransactionMessageFeePayerSigner(signer, m),
114  m => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
115  m => appendTransactionMessageInstruction(instruction, m),
116  m => prependTransactionMessageInstruction(
117    getSetComputeUnitPriceInstruction({ microLamports: 1000n }), m
118  ),
119);
120 
121// 2. Estimate CU via simulation
122message = await estimateAndUpdateCU(message);
123 
124// 3. REFRESH blockhash (simulation takes time, old one may expire)
125const { value: freshBlockhash } = await rpc.getLatestBlockhash().send();
126message = setTransactionMessageLifetimeUsingBlockhash(freshBlockhash, message);
127 
128// 4. Sign and send
129await signAndSendTransactionMessageWithSigners(message);
130```
131 
132### Update Priority Fee Dynamically
133 
134```ts
135import { updateOrAppendSetComputeUnitPriceInstruction } from '@solana-program/compute-budget';
136 
137const updated = updateOrAppendSetComputeUnitPriceInstruction(
138  (current) => current === null ? 1000n : current * 2n,
139  message
140);
141```
142 
143See [programs/compute-budget.md](programs/compute-budget.md) for the full CU reference.
144 
145---
146 
147## Signing
148 
149### With Embedded Signers (Recommended)
150 
151```ts
152import { signTransactionMessageWithSigners } from '@solana/kit';
153 
154// Auto-discovers signers from fee payer + instruction accounts
155const signed = await signTransactionMessageWithSigners(message);
156```
157 
158### Sign and Send
159 
160```ts
161import { signAndSendTransactionMessageWithSigners } from '@solana/kit';
162const signature = await signAndSendTransactionMessageWithSigners(message);
163```
164 
165### Manual: Compile + Sign Separately
166 
167```ts
168import { compileTransaction, signTransaction, partiallySignTransaction } from '@solana/transactions';
169 
170const compiled = compileTransaction(message);
171const signed = await signTransaction([keypair1, keypair2], compiled);
172 
173// Partial signing for multi-party flows
174const partial = await partiallySignTransaction([keypair1], compiled);
175```
176 
177---
178 
179## Sending
180 
181### Send and Confirm Factory
182 
183```ts
184const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
185const signed = await signTransactionMessageWithSigners(message);
186 
187// Required type assertions before sending
188assertIsTransactionWithBlockhashLifetime(signed);
189assertIsTransactionWithinSizeLimit(signed);
190await sendAndConfirm(signed, { commitment: 'confirmed' });
191```
192 
193### Durable Nonce
194 
195```ts
196const sendNonceTx = sendAndConfirmDurableNonceTransactionFactory({ rpc, rpcSubscriptions });
197assertIsFullySignedTransaction(signed);
198assertIsTransactionWithDurableNonceLifetime(signed);
199assertIsTransactionWithinSizeLimit(signed);
200await sendNonceTx(signed, { commitment: 'confirmed' });
201```
202 
203### Utilities
204 
205```ts
206import { getSignatureFromTransaction, getBase64EncodedWireTransaction } from '@solana/transactions';
207 
208const sig = getSignatureFromTransaction(signedTx);
209const base64 = getBase64EncodedWireTransaction(signedTx);
210```
211 
212---
213 
214## Complete Manual Example
215 
216```ts
217import {
218  pipe, createTransactionMessage, setTransactionMessageFeePayerSigner,
219  setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstruction,
220  prependTransactionMessageInstruction, signTransactionMessageWithSigners,
221  sendAndConfirmTransactionFactory, assertIsTransactionWithBlockhashLifetime,
222  assertIsTransactionWithinSizeLimit,
223} from '@solana/kit';
224import {
225  getSetComputeUnitPriceInstruction,
226  estimateComputeUnitLimitFactory,
227  estimateAndUpdateProvisoryComputeUnitLimitFactory,
228} from '@solana-program/compute-budget';
229 
230async function sendTx(rpc, rpcSubscriptions, signer, instruction) {
231  const estimateAndUpdateCU = estimateAndUpdateProvisoryComputeUnitLimitFactory(
232    estimateComputeUnitLimitFactory({ rpc })
233  );
234 
235  const { value: simBlockhash } = await rpc.getLatestBlockhash().send();
236 
237  let message = pipe(
238    createTransactionMessage({ version: 0 }),
239    m => setTransactionMessageFeePayerSigner(signer, m),
240    m => setTransactionMessageLifetimeUsingBlockhash(simBlockhash, m),
241    m => appendTransactionMessageInstruction(instruction, m),
242    m => prependTransactionMessageInstruction(
243      getSetComputeUnitPriceInstruction({ microLamports: 1000n }), m
244    ),
245  );
246 
247  message = await estimateAndUpdateCU(message);
248 
249  // Refresh blockhash after estimation
250  const { value: freshBlockhash } = await rpc.getLatestBlockhash().send();
251  message = setTransactionMessageLifetimeUsingBlockhash(freshBlockhash, message);
252 
253  const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });
254  const signed = await signTransactionMessageWithSigners(message);
255  assertIsTransactionWithBlockhashLifetime(signed);
256  assertIsTransactionWithinSizeLimit(signed);
257  await sendAndConfirm(signed, { commitment: 'confirmed' });
258}
259```
260 
261---
262 
263## Direct RPC Client
264 
265### Creating Clients
266 
267```ts
268import { createSolanaRpc, createSolanaRpcSubscriptions } from '@solana/kit';
269 
270const rpc = createSolanaRpc('https://api.devnet.solana.com');
271const rpcSubs = createSolanaRpcSubscriptions('wss://api.devnet.solana.com');
272```
273 
274### Custom Transport
275 
276```ts
277const transport = createDefaultRpcTransport({
278  url: 'https://my-rpc.example.com',
279  headers: { 'Authorization': 'Bearer token' },
280});
281const rpc = createSolanaRpcFromTransport(transport);
282```
283 
284### Making Calls
285 
286```ts
287// All methods return pending request — call .send()
288const { value: balance } = await rpc.getBalance(address).send();
289 
290// With abort
291const controller = new AbortController();
292await rpc.getBalance(address).send({ abortSignal: controller.signal });
293```
294 
295### Return Types
296 
297Most methods return `{ value: T }`:
298```ts
299const { value: balance } = await rpc.getBalance(address).send();
300const { value: blockhash } = await rpc.getLatestBlockhash().send();
301```
302 
303Some return `T` directly:
304```ts
305const rentExempt = await rpc.getMinimumBalanceForRentExemption(80n).send();
306const slot = await rpc.getSlot().send();
307```
308 
309### Subscriptions
310 
311```ts
312const sub = await rpcSubs.accountNotifications(address, {
313  encoding: 'base64',
314  commitment: 'confirmed',
315}).subscribe();
316 
317for await (const notif of sub) {
318  console.log('Changed:', notif);
319}
320```
321 
322### Commitment Levels
323 
324```ts
325type Commitment = 'processed' | 'confirmed' | 'finalized';
326// processed: seen by node
327// confirmed: supermajority confirmed
328// finalized: max lockout
329```
330 
331### Airdrop (devnet/testnet)
332 
333```ts
334import { airdropFactory, lamports } from '@solana/kit';
335 
336const airdrop = airdropFactory({ rpc, rpcSubscriptions });
337await airdrop({
338  recipientAddress: address('...'),
339  lamports: lamports(1_000_000_000n),
340  commitment: 'confirmed',
341});
342```
343 
344### RPC Method Reference
345 
346**Accounts**: `getAccountInfo`, `getMultipleAccounts`, `getBalance`, `getTokenAccountBalance`, `getTokenAccountsByOwner`, `getProgramAccounts`
347 
348**Transactions**: `sendTransaction`, `simulateTransaction`, `getTransaction`, `getSignatureStatuses`, `getSignaturesForAddress`
349 
350**Blocks**: `getBlock`, `getBlockHeight`, `getSlot`, `getLatestBlockhash`, `isBlockhashValid`
351 
352**Cluster**: `getClusterNodes`, `getEpochInfo`, `getHealth`, `getVersion`
353 
354**Misc**: `requestAirdrop`, `getMinimumBalanceForRentExemption`, `getFeeForMessage`
355 
356---
357 
358## Error Handling
359 
360```ts
361import {
362  isSolanaError,
363  SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED,
364  SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
365} from '@solana/errors';
366 
367try {
368  await sendAndConfirm(tx, { commitment: 'confirmed' });
369} catch (e) {
370  if (isSolanaError(e, SOLANA_ERROR__BLOCK_HEIGHT_EXCEEDED)) {
371    console.error('Blockhash expired');
372  }
373  if (isSolanaError(e, SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE)) {
374    console.error('Preflight failed:', e.cause);
375  }
376}
377```
378 
379---
380 
381## Building Custom Plugins
382 
383A plugin is a function that takes a client object and returns a new one (or a promise):
384 
385```ts
386export type ClientPlugin<TInput extends object, TOutput extends Promise<object> | object> =
387  (input: TInput) => TOutput;
388```
389 
390### Basic Plugin
391 
392```ts
393import { createClient } from '@solana/kit';
394 
395function apple() {
396  return <T extends object>(client: T) => ({
397    ...client,
398    fruit: 'apple' as const,
399  });
400}
401 
402const client = createClient().use(apple());
403client.fruit; // 'apple'
404```
405 
406### Plugin with Requirements
407 
408Require that other plugins are installed first:
409 
410```ts
411function appleTart() {
412  return <T extends { fruit: 'apple' }>(client: T) => ({
413    ...client,
414    dessert: 'appleTart' as const,
415  });
416}
417 
418createClient().use(apple()).use(appleTart()); // ✅ Ok
419createClient().use(appleTart());              // ❌ TypeScript error
420```
421 
422### Async Plugin
423 
424```ts
425function magicFruit() {
426  return async <T extends object>(client: T) => {
427    const fruit = await fetchSomeMagicFruit();
428    return { ...client, fruit };
429  };
430}
431 
432// use() handles awaiting automatically
433const client = await createClient().use(magicFruit()).use(apple());
434```
435 
436---
437 
438## Assembling Domain-Specific Clients
439 
440The plugin system enables building purpose-built clients for specific domains. Here are real-world examples:
441 
442### Example: Kora (Gasless Transactions)
443 
444[Kora](https://github.com/solana-foundation/kora) builds a gasless payment client by composing standard plugins with a custom Kora plugin:
445 
446```ts
447import { createClient } from '@solana/kit';
448import { planAndSendTransactions, transactionPlanExecutor, transactionPlanner } from '@solana/kit-plugin-instruction-plan';
449import { payer } from '@solana/kit-plugin-signer';
450import { rpc } from '@solana/kit-plugin-rpc';
451 
452export async function createKitKoraClient(config) {
453  return createClient()
454    .use(rpc(config.rpcUrl))
455    .use(koraPlugin({ apiKey: config.apiKey, endpoint: config.endpoint }))
456    .use(payer(payerSigner))
457    .use(transactionPlanner(koraTransactionPlanner))      // Custom planning logic
458    .use(transactionPlanExecutor(koraTransactionExecutor)) // Custom execution via Kora API
459    .use(planAndSendTransactions());
460}
461 
462// Usage
463const client = await createKitKoraClient({ endpoint, rpcUrl, feeToken, feePayerWallet });
464await client.sendTransaction([myInstruction]); // Gasless!
465```
466 
467Key pattern: Standard plugins (`rpc`, `payer`, `planAndSendTransactions`) combined with custom `transactionPlanner` and `transactionPlanExecutor` that route through Kora's gasless API.
468 
469### Example: Solana Pay
470 
471[Solana Pay](https://github.com/amilz/solana-pay) builds role-specific clients — a read-only merchant client and a full wallet client:
472 
473```ts
474import { createClient } from '@solana/kit';
475import { planAndSendTransactions } from '@solana/kit-plugin-instruction-plan';
476import { payer } from '@solana/kit-plugin-signer';
477import { rpc, rpcTransactionPlanExecutor, rpcTransactionPlanner } from '@solana/kit-plugin-rpc';
478 
479// Merchant: read-only, no payer needed
480function createMerchantClient(config) {
481  return createClient()
482    .use(rpc(config.rpcUrl))
483    .use(solanaPayMerchant()); // Adds client.pay.encodeURL, findReference, validateTransfer
484}
485 
486// Wallet: full tx capabilities
487function createWalletClient(config) {
488  return createClient()
489    .use(rpc(config.rpcUrl))
490    .use(payer(config.payer))
491    .use(rpcTransactionPlanner())
492    .use(rpcTransactionPlanExecutor())
493    .use(planAndSendTransactions())
494    .use(solanaPayWallet()); // Adds client.pay.parseURL, createTransfer
495}
496 
497// Usage
498const merchant = createMerchantClient({ rpcUrl });
499const url = merchant.pay.encodeURL({ recipient, amount: 1.5 });
500 
501const wallet = createWalletClient({ rpcUrl, payer: myWalletSigner });
502const instructions = await wallet.pay.createTransfer({ recipient, amount: 1.5 });
503await wallet.sendTransaction(instructions);
504```
505 
506Key pattern: Same base plugins, different compositions for different roles. Domain logic added as custom plugins (`solanaPayMerchant`, `solanaPayWallet`).
507 
508### Pattern Summary
509 
510When building a domain-specific client:
511 
5121. Start with `createClient()` from `@solana/kit`
5132. Add standard plugins for capabilities you need (`rpc`, `payer` from `@solana/kit-plugin-signer`, `planAndSendTransactions`)
5143. Swap `transactionPlanner` / `transactionPlanExecutor` if you need custom tx lifecycle (like Kora)
5154. Add your domain plugin(s) that extend the client with domain-specific methods
5165. Export a factory function (`createMyClient(config)`) for consumers
517