Improve type safety when adding instructions

lorisleiva · lorisleiva · commit 04da52aa0636 · 2025-05-06T09:26:21.000+01:00
diff --git a/.changeset/cold-beans-relax.md b/.changeset/cold-beans-relax.md
@@ -0,0 +1,5 @@
+---
+'@solana/transaction-messages': patch
+---
+
+Keep type safety when appending or prepending instructions to transaction messages
diff --git a/packages/transaction-messages/src/__typetests__/durable-nonce-typetests.ts b/packages/transaction-messages/src/__typetests__/durable-nonce-typetests.ts
@@ -1,5 +1,9 @@
 import type { Address } from '@solana/addresses';
+import { pipe } from '@solana/functional';
+import { IInstruction } from '@solana/instructions';
 
+import { CompilableTransactionMessage } from '../compilable-transaction-message';
+import { createTransactionMessage } from '../create-transaction-message';
 import {
     assertIsTransactionMessageWithDurableNonceLifetime,
     isTransactionMessageWithDurableNonceLifetime,
@@ -8,6 +12,8 @@ import {
     TransactionMessageWithDurableNonceLifetime,
 } from '../durable-nonce';
 import { AdvanceNonceAccountInstruction } from '../durable-nonce-instruction';
+import { setTransactionMessageFeePayer } from '../fee-payer';
+import { appendTransactionMessageInstruction } from '../instructions';
 import { BaseTransactionMessage, TransactionMessage } from '../transaction-message';
 
 const mockNonceConfig = {
@@ -16,6 +22,13 @@ const mockNonceConfig = {
     nonceAuthorityAddress: null as unknown as Address<'nonceAuthority'>,
 };
 
+const newMockNonceConfig = {
+    nonce: null as unknown as Nonce<'newNonce'>,
+    nonceAccountAddress: null as unknown as Address<'newNonce'>,
+    nonceAuthorityAddress: null as unknown as Address<'newNonceAuthority'>,
+};
+
+type InstructionA = IInstruction & { identifier: 'A' };
 type LegacyTransactionMessage = Extract<TransactionMessage, { version: 'legacy' }>;
 type V0TransactionMessage = Extract<TransactionMessage, { version: 0 }>;
 
@@ -72,4 +85,43 @@ type V0TransactionMessage = Extract<TransactionMessage, { version: 0 }>;
         // @ts-expect-error Should not be a v0 message.
         newMessage satisfies TransactionMessageWithDurableNonceLifetime & V0TransactionMessage & { some: 1 };
     }
+
+    // It prepends the nonce instruction to the transaction message.
+    {
+        const feePayer = null as unknown as Address;
+        const message = pipe(
+            createTransactionMessage({ version: 0 }),
+            m => setTransactionMessageFeePayer(feePayer, m),
+            m => appendTransactionMessageInstruction(null as unknown as InstructionA, m),
+            m => setTransactionMessageLifetimeUsingDurableNonce(mockNonceConfig, m),
+        );
+
+        message satisfies CompilableTransactionMessage;
+        message satisfies BaseTransactionMessage &
+            TransactionMessageWithDurableNonceLifetime<'nonce', 'nonceAuthority', 'nonce'>;
+        message.instructions satisfies readonly [
+            AdvanceNonceAccountInstruction<'nonce', 'nonceAuthority'>,
+            InstructionA,
+        ];
+    }
+
+    // It replaces the existing nonce instruction with the new one.
+    {
+        const feePayer = null as unknown as Address;
+        const message = pipe(
+            createTransactionMessage({ version: 0 }),
+            m => setTransactionMessageFeePayer(feePayer, m),
+            m => appendTransactionMessageInstruction(null as unknown as InstructionA, m),
+            m => setTransactionMessageLifetimeUsingDurableNonce(mockNonceConfig, m),
+            m => setTransactionMessageLifetimeUsingDurableNonce(newMockNonceConfig, m),
+        );
+
+        message satisfies CompilableTransactionMessage;
+        message satisfies BaseTransactionMessage &
+            TransactionMessageWithDurableNonceLifetime<'newNonce', 'newNonceAuthority', 'newNonce'>;
+        message.instructions satisfies readonly [
+            AdvanceNonceAccountInstruction<'newNonce', 'newNonceAuthority'>,
+            InstructionA,
+        ];
+    }
 }
diff --git a/packages/transaction-messages/src/__typetests__/instructions-typetests.ts b/packages/transaction-messages/src/__typetests__/instructions-typetests.ts
@@ -1,5 +1,15 @@
-import { TransactionMessageWithBlockhashLifetime } from '../blockhash';
-import { TransactionMessageWithDurableNonceLifetime } from '../durable-nonce';
+import { Address } from '@solana/addresses';
+import { pipe } from '@solana/functional';
+
+import { setTransactionMessageLifetimeUsingBlockhash, TransactionMessageWithBlockhashLifetime } from '../blockhash';
+import { CompilableTransactionMessage } from '../compilable-transaction-message';
+import { createTransactionMessage } from '../create-transaction-message';
+import {
+    setTransactionMessageLifetimeUsingDurableNonce,
+    TransactionMessageWithDurableNonceLifetime,
+} from '../durable-nonce';
+import { AdvanceNonceAccountInstruction } from '../durable-nonce-instruction';
+import { setTransactionMessageFeePayer } from '../fee-payer';
 import {
     appendTransactionMessageInstruction,
     appendTransactionMessageInstructions,
@@ -9,6 +19,9 @@ import {
 import { BaseTransactionMessage } from '../transaction-message';
 
 type IInstruction = BaseTransactionMessage['instructions'][number];
+type InstructionA = IInstruction & { identifier: 'A' };
+type InstructionB = IInstruction & { identifier: 'B' };
+type InstructionC = IInstruction & { identifier: 'C' };
 
 // [DESCRIBE] appendTransactionMessageInstruction
 {
@@ -18,6 +31,56 @@ type IInstruction = BaseTransactionMessage['instructions'][number];
         const newMessage = appendTransactionMessageInstruction(null as unknown as IInstruction, message);
         newMessage satisfies BaseTransactionMessage & { some: 1 };
     }
+
+    // It concatenates the instruction types
+    {
+        const message = null as unknown as { instructions: [InstructionA]; version: 0 };
+        const newMessage = appendTransactionMessageInstruction(null as unknown as InstructionB, message);
+        newMessage.instructions satisfies readonly [InstructionA, InstructionB];
+        // @ts-expect-error Wrong order.
+        newMessage.instructions satisfies readonly [InstructionB, InstructionA];
+        // @ts-expect-error Not readonly.
+        newMessage.instructions satisfies [InstructionA, InstructionB];
+    }
+
+    // It adds instruction types to base transaction messages
+    {
+        const message = null as unknown as BaseTransactionMessage;
+        const newMessage = appendTransactionMessageInstruction(null as unknown as InstructionA, message);
+        newMessage.instructions satisfies readonly [...IInstruction[], InstructionA];
+    }
+
+    // It keeps the blockhash lifetime type safety.
+    {
+        const feePayer = null as unknown as Address;
+        const blockhash = null as unknown as Parameters<typeof setTransactionMessageLifetimeUsingBlockhash>[0];
+        const message = pipe(
+            createTransactionMessage({ version: 0 }),
+            m => setTransactionMessageFeePayer(feePayer, m),
+            m => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
+            m => appendTransactionMessageInstruction(null as unknown as InstructionA, m),
+        );
+
+        message satisfies CompilableTransactionMessage;
+        message satisfies BaseTransactionMessage & TransactionMessageWithBlockhashLifetime;
+        message.instructions satisfies readonly [InstructionA];
+    }
+
+    // It keeps the durable nonce lifetime type safety.
+    {
+        const feePayer = null as unknown as Address;
+        const nonceConfig = null as unknown as Parameters<typeof setTransactionMessageLifetimeUsingDurableNonce>[0];
+        const message = pipe(
+            createTransactionMessage({ version: 0 }),
+            m => setTransactionMessageFeePayer(feePayer, m),
+            m => setTransactionMessageLifetimeUsingDurableNonce(nonceConfig, m),
+            m => appendTransactionMessageInstruction(null as unknown as InstructionA, m),
+        );
+
+        message satisfies CompilableTransactionMessage;
+        message satisfies BaseTransactionMessage & TransactionMessageWithDurableNonceLifetime;
+        message.instructions satisfies readonly [AdvanceNonceAccountInstruction, InstructionA];
+    }
 }
 
 // [DESCRIBE] appendTransactionMessageInstructions
@@ -28,6 +91,30 @@ type IInstruction = BaseTransactionMessage['instructions'][number];
         const newMessage = appendTransactionMessageInstructions(null as unknown as IInstruction[], message);
         newMessage satisfies BaseTransactionMessage & { some: 1 };
     }
+
+    // It concatenates the instruction types
+    {
+        const message = null as unknown as { instructions: [InstructionA]; version: 0 };
+        const newMessage = appendTransactionMessageInstructions(
+            [null as unknown as InstructionB, null as unknown as InstructionC],
+            message,
+        );
+        newMessage.instructions satisfies readonly [InstructionA, InstructionB, InstructionC];
+        // @ts-expect-error Wrong order.
+        newMessage.instructions satisfies readonly [InstructionC, InstructionB, InstructionA];
+        // @ts-expect-error Not readonly.
+        newMessage.instructions satisfies [InstructionA, InstructionB, InstructionC];
+    }
+
+    // It adds instruction types to base transaction messages
+    {
+        const message = null as unknown as BaseTransactionMessage;
+        const newMessage = appendTransactionMessageInstructions(
+            [null as unknown as InstructionA, null as unknown as InstructionB],
+            message,
+        );
+        newMessage.instructions satisfies readonly [...IInstruction[], InstructionA, InstructionB];
+    }
 }
 
 // [DESCRIBE] prependTransactionMessageInstruction
@@ -56,6 +143,58 @@ type IInstruction = BaseTransactionMessage['instructions'][number];
         const newMessage = prependTransactionMessageInstruction(null as unknown as IInstruction, message);
         newMessage satisfies BaseTransactionMessage & TransactionMessageWithBlockhashLifetime & { some: 1 };
     }
+
+    // It concatenates the instruction types
+    {
+        const message = null as unknown as { instructions: [InstructionA]; version: 0 };
+        const newMessage = prependTransactionMessageInstruction(null as unknown as InstructionB, message);
+        newMessage.instructions satisfies readonly [InstructionB, InstructionA];
+        // @ts-expect-error Wrong order.
+        newMessage.instructions satisfies readonly [InstructionA, InstructionB];
+        // @ts-expect-error Not readonly.
+        newMessage.instructions satisfies [InstructionB, InstructionA];
+    }
+
+    // It adds instruction types to base transaction messages
+    {
+        const message = null as unknown as BaseTransactionMessage;
+        const newMessage = prependTransactionMessageInstruction(null as unknown as InstructionA, message);
+        newMessage.instructions satisfies readonly [InstructionA, ...IInstruction[]];
+    }
+
+    // It keeps the blockhash lifetime type safety.
+    {
+        const feePayer = null as unknown as Address;
+        const blockhash = null as unknown as Parameters<typeof setTransactionMessageLifetimeUsingBlockhash>[0];
+        const message = pipe(
+            createTransactionMessage({ version: 0 }),
+            m => setTransactionMessageFeePayer(feePayer, m),
+            m => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
+            m => prependTransactionMessageInstruction(null as unknown as InstructionA, m),
+        );
+
+        message satisfies CompilableTransactionMessage;
+        message satisfies BaseTransactionMessage & TransactionMessageWithBlockhashLifetime;
+        message.instructions satisfies readonly [InstructionA];
+    }
+
+    // It removes the durable nonce lifetime type safety but keep the nonce instruction.
+    {
+        const feePayer = null as unknown as Address;
+        const nonceConfig = null as unknown as Parameters<typeof setTransactionMessageLifetimeUsingDurableNonce>[0];
+        const message = pipe(
+            createTransactionMessage({ version: 0 }),
+            m => setTransactionMessageFeePayer(feePayer, m),
+            m => setTransactionMessageLifetimeUsingDurableNonce(nonceConfig, m),
+            m => prependTransactionMessageInstruction(null as unknown as InstructionA, m),
+        );
+
+        message.instructions satisfies readonly [InstructionA, AdvanceNonceAccountInstruction];
+        // @ts-expect-error No longer a durable nonce lifetime.
+        message satisfies CompilableTransactionMessage;
+        // @ts-expect-error No longer a durable nonce lifetime.
+        message satisfies BaseTransactionMessage & TransactionMessageWithDurableNonceLifetime;
+    }
 }
 
 // [DESCRIBE] prependTransactionMessageInstructions
@@ -76,4 +215,28 @@ type IInstruction = BaseTransactionMessage['instructions'][number];
         // @ts-expect-error The durable nonce transaction message type should be stripped.
         newMessage satisfies TransactionMessageWithDurableNonceLifetime;
     }
+
+    // It concatenates the instruction types
+    {
+        const message = null as unknown as { instructions: [InstructionA]; version: 0 };
+        const newMessage = prependTransactionMessageInstructions(
+            [null as unknown as InstructionB, null as unknown as InstructionC],
+            message,
+        );
+        newMessage.instructions satisfies readonly [InstructionB, InstructionC, InstructionA];
+        // @ts-expect-error Wrong order.
+        newMessage.instructions satisfies readonly [InstructionA, InstructionC, InstructionB];
+        // @ts-expect-error Not readonly.
+        newMessage.instructions satisfies [InstructionB, InstructionC, InstructionA];
+    }
+
+    // It adds instruction types to base transaction messages
+    {
+        const message = null as unknown as BaseTransactionMessage;
+        const newMessage = prependTransactionMessageInstructions(
+            [null as unknown as InstructionA, null as unknown as InstructionB],
+            message,
+        );
+        newMessage.instructions satisfies readonly [InstructionA, InstructionB, ...IInstruction[]];
+    }
 }
diff --git a/packages/transaction-messages/src/blockhash.ts b/packages/transaction-messages/src/blockhash.ts
@@ -120,20 +120,20 @@ export function setTransactionMessageLifetimeUsingBlockhash<
     blockhashLifetimeConstraint: BlockhashLifetimeConstraint,
     transactionMessage: TTransactionMessage,
 ): ExcludeTransactionMessageLifetime<TTransactionMessage> & TransactionMessageWithBlockhashLifetime {
+    type ReturnType = ExcludeTransactionMessageLifetime<TTransactionMessage> & TransactionMessageWithBlockhashLifetime;
+
     if (
         'lifetimeConstraint' in transactionMessage &&
         transactionMessage.lifetimeConstraint &&
         'blockhash' in transactionMessage.lifetimeConstraint &&
         transactionMessage.lifetimeConstraint.blockhash === blockhashLifetimeConstraint.blockhash &&
         transactionMessage.lifetimeConstraint.lastValidBlockHeight === blockhashLifetimeConstraint.lastValidBlockHeight
     ) {
-        return transactionMessage as ExcludeTransactionMessageLifetime<TTransactionMessage> &
-            TransactionMessageWithBlockhashLifetime;
+        return transactionMessage as ReturnType;
     }
-    const out = {
+
+    return Object.freeze({
         ...transactionMessage,
         lifetimeConstraint: Object.freeze(blockhashLifetimeConstraint),
-    };
-    Object.freeze(out);
-    return out as ExcludeTransactionMessageLifetime<TTransactionMessage> & TransactionMessageWithBlockhashLifetime;
+    }) as ReturnType;
 }
diff --git a/packages/transaction-messages/src/create-transaction-message.ts b/packages/transaction-messages/src/create-transaction-message.ts
@@ -17,7 +17,7 @@ type TransactionConfig<TVersion extends TransactionVersion> = Readonly<{
  */
 export function createTransactionMessage<TVersion extends TransactionVersion>(
     config: TransactionConfig<TVersion>,
-): Extract<TransactionMessage, { version: TVersion }>;
+): Omit<Extract<TransactionMessage, { version: TVersion }>, 'instructions'> & { instructions: readonly [] };
 export function createTransactionMessage<TVersion extends TransactionVersion>({
     version,
 }: TransactionConfig<TVersion>): TransactionMessage {
diff --git a/packages/transaction-messages/src/decompile-message.ts b/packages/transaction-messages/src/decompile-message.ts
@@ -18,9 +18,9 @@ import type { getCompiledAddressTableLookups } from './compile/address-table-loo
 import { createTransactionMessage } from './create-transaction-message';
 import { Nonce, setTransactionMessageLifetimeUsingDurableNonce } from './durable-nonce';
 import { isAdvanceNonceAccountInstruction } from './durable-nonce-instruction';
-import { setTransactionMessageFeePayer } from './fee-payer';
+import { setTransactionMessageFeePayer, TransactionMessageWithFeePayer } from './fee-payer';
 import { appendTransactionMessageInstruction } from './instructions';
-import { TransactionVersion } from './transaction-message';
+import { BaseTransactionMessage, TransactionVersion } from './transaction-message';
 
 function getAccountMetas(message: CompiledTransactionMessage): IAccountMeta[] {
     const { header } = message;
@@ -241,9 +241,10 @@ export function decompileTransactionMessage(
         createTransactionMessage({ version: compiledTransactionMessage.version as TransactionVersion }),
         m => setTransactionMessageFeePayer(feePayer, m),
         m =>
-            instructions.reduce((acc, instruction) => {
-                return appendTransactionMessageInstruction(instruction, acc);
-            }, m),
+            instructions.reduce(
+                (acc, instruction) => appendTransactionMessageInstruction(instruction, acc),
+                m as BaseTransactionMessage & TransactionMessageWithFeePayer,
+            ),
         m =>
             'blockhash' in lifetimeConstraint
                 ? setTransactionMessageLifetimeUsingBlockhash(lifetimeConstraint, m)
diff --git a/packages/transaction-messages/src/durable-nonce.ts b/packages/transaction-messages/src/durable-nonce.ts
diff --git a/packages/transaction-messages/src/instructions.ts b/packages/transaction-messages/src/instructions.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@solana/transaction-messages': patch
 +---
++
 +Keep type safety when appending or prepending instructions to transaction messages