anza-xyz · lorisleiva · May 14, 2025 · May 6, 2025
diff --git a/.changeset/better-crabs-taste.md b/.changeset/better-crabs-taste.md
@@ -0,0 +1,7 @@
+---
+'@solana/transaction-messages': minor
+'@solana/transactions': minor
+'@solana/signers': minor
+---
+
+Add, remove and forward the `TransactionMessageWithinSizeLimit` and `TransactionWithinSizeLimit` types in all helpers that may affect the size of a transaction or transaction message.
diff --git a/packages/signers/src/__typetests__/sign-transaction-typetest.ts b/packages/signers/src/__typetests__/sign-transaction-typetest.ts
@@ -4,12 +4,14 @@ import {
     CompilableTransactionMessage,
     TransactionMessageWithBlockhashLifetime,
     TransactionMessageWithDurableNonceLifetime,
+    TransactionMessageWithinSizeLimit,
 } from '@solana/transaction-messages';
 import {
     FullySignedTransaction,
     Transaction,
     TransactionWithBlockhashLifetime,
     TransactionWithDurableNonceLifetime,
+    TransactionWithinSizeLimit,
     TransactionWithLifetime,
 } from '@solana/transactions';
 
@@ -49,6 +51,15 @@ type CompilableTransactionMessageWithSigners = CompilableTransactionMessage & Tr
     >;
 }
 
+{
+    // [partiallySignTransactionMessageWithSigners]: returns a transaction with a `TransactionWithinSizeLimit` flag
+    const transacti
10000
 as unknown as CompilableTransactionMessageWithSigners &
+        TransactionMessageWithinSizeLimit;
+    partiallySignTransactionMessageWithSigners(transactionMessage) satisfies Promise<
+        Readonly<Transaction & TransactionWithinSizeLimit>
+    >;
+}
+
 {
     // [signTransactionMessageWithSigners]: returns a fully signed transaction with a blockhash lifetime
     const transactionMessage = null as unknown as CompilableTransactionMessageWithSigners &
@@ -75,6 +86,15 @@ type CompilableTransactionMessageWithSigners = CompilableTransactionMessage & Tr
     >;
 }
 
+{
+    // [signTransactionMessageWithSigners]: returns a transaction with a `TransactionWithinSizeLimit` flag
+    const transactionMessage = null as unknown as CompilableTransactionMessageWithSigners &
+        TransactionMessageWithinSizeLimit;
+    signTransactionMessageWithSigners(transactionMessage) satisfies Promise<
+        Readonly<FullySignedTransaction & Transaction & TransactionWithinSizeLimit>
+    >;
+}
+
 {
     // [signAndSendTransactionMessageWithSigners]: returns a signature
     const transactionMessage = null as unknown as CompilableTransactionMessageWithSigners &

diff --git a/packages/signers/src/sign-transaction.ts b/packages/signers/src/sign-transaction.ts
@@ -1,17 +1,12 @@
 import { SOLANA_ERROR__SIGNER__TRANSACTION_SENDING_SIGNER_MISSING, SolanaError } from '@solana/errors';
 import { SignatureBytes } from '@solana/keys';
-import {
-    CompilableTransactionMessage,
-    TransactionMessageWithBlockhashLifetime,
-    TransactionMessageWithDurableNonceLifetime,
-} from '@solana/transaction-messages';
+import { CompilableTransactionMessage } from '@solana/transaction-messages';
 import {
     assertTransactionIsFullySigned,
     compileTransaction,
     FullySignedTransaction,
     Transaction,
-    TransactionWithBlockhashLifetime,
-    TransactionWithDurableNonceLifetime,
+    TransactionFromCompilableTransactionMessage,
     TransactionWithLifetime,
 } from '@solana/transactions';
 
@@ -72,36 +67,11 @@ type CompilableTransactionMessageWithSigners = CompilableTransactionMessage & Tr
  * @see {@link signAndSendTransactionMessageWithSigners}
  */
 export async function partiallySignTransactionMessageWithSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners &
-        TransactionMessageWithBlockhashLifetime = CompilableTransactionMessageWithSigners &
-        TransactionMessageWithBlockhashLifetime,
->(
-    transactionMessage: TTransactionMessage,
-    config?: TransactionPartialSignerConfig,
-): Promise<Transaction & TransactionWithBlockhashLifetime>;
-
-export async function partiallySignTransactionMessageWithSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners &
-        TransactionMessageWithDurableNonceLifetime = CompilableTransactionMessageWithSigners &
-        TransactionMessageWithDurableNonceLifetime,
->(
-    transactionMessage: TTransactionMessage,
-    config?: TransactionPartialSignerConfig,
-): Promise<Readonly<Transaction & TransactionWithDurableNonceLifetime>>;
-
-export async function partiallySignTransactionMessageWithSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners = CompilableTransactionMessageWithSigners,
->(
-    transactionMessage: TTransactionMessage,
-    config?: TransactionPartialSignerConfig,
-): Promise<Readonly<Transaction & TransactionWithLifetime>>;
-
-export async function partiallySignTransactionMessageWithSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners = CompilableTransactionMessageWithSigners,
+    TTransactionMessage extends CompilableTransactionMessageWithSigners,
 >(
     transactionMessage: TTransactionMessage,
     config?: TransactionPartialSignerConfig,
-): Promise<Readonly<Transaction & TransactionWithLifetime>> {
+): Promise<TransactionFromCompilableTransactionMessage<TTransactionMessage>> {
     const { partialSigners, modifyingSigners } = categorizeTransactionSigners(
         deduplicateSigners(getSignersFromTransactionMessage(transactionMessage).filter(isTransactionSigner)),
         { identifySendingSigner: false },
@@ -142,36 +112,11 @@ export async function partiallySignTransactionMessageWithSigners<
  * @see {@link signAndSendTransactionMessageWithSigners}
  */
 export async function signTransactionMessageWithSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners &
-        TransactionMessageWithBlockhashLifetime = CompilableTransactionMessageWithSigners &
-        TransactionMessageWithBlockhashLifetime,
+    TTransactionMessage extends CompilableTransactionMessageWithSigners,
 >(
     transactionMessage: TTransactionMessage,
     config?: TransactionPartialSignerConfig,
-): Promise<Readonly<FullySignedTransaction & TransactionWithBlockhashLifetime>>;
-
-export async function signTransactionMessageWithSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners &
-        TransactionMessageWithDurableNonceLifetime = CompilableTransactionMessageWithSigners &
-        TransactionMessageWithDurableNonceLifetime,
->(
-    transactionMessage: TTransactionMessage,
-    config?: TransactionPartialSignerConfig,
-): Promise<Readonly<FullySignedTransaction & TransactionWithDurableNonceLifetime>>;
-
-export async function signTransactionMessageWithSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners = CompilableTransactionMessageWithSigners,
->(
-    transactionMessage: TTransactionMessage,
-    config?: TransactionPartialSignerConfig,
-): Promise<Readonly<FullySignedTransaction & TransactionWithLifetime>>;
-
-export async function signTransactionMessageWithSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners = CompilableTransactionMessageWithSigners,
->(
-    transactionMessage: TTransactionMessage,
-    config?: TransactionPartialSignerConfig,
-): Promise<Readonly<FullySignedTransaction & TransactionWithLifetime>> {
+): Promise<FullySignedTransaction & TransactionFromCompilableTransactionMessage<TTransactionMessage>> {
     const signedTransaction = await partiallySignTransactionMessageWithSigners(transactionMessage, config);
     assertTransactionIsFullySigned(signedTransaction);
     return signedTransaction;
@@ -334,13 +279,15 @@ function identifyTransactionModifyingSigners(
  * sequentially followed by the TransactionPartialSigners in parallel.
  */
 async function signModifyingAndPartialTransactionSigners<
-    TTransactionMessage extends CompilableTransactionMessageWithSigners = CompilableTransactionMessageWithSigners,
+    TTransactionMessage extends CompilableTransactionMessageWithSigners,
 >(
     transactionMessage: TTransactionMessage,
     modifyingSigners: readonly TransactionModifyingSigner[] = [],
     partialSigners: readonly TransactionPartialSigner[] = [],
     config?: TransactionModifyingSignerConfig,
-): Promise<Readonly<Transaction & TransactionWithLifetime>> {
+): Promise<TransactionFromCompilableTransactionMessage<TTransactionMessage>> {
+    type ReturnType = TransactionFromCompilableTransactionMessage<TTransactionMessage>;
+
     // serialize the transaction
     const transaction = compileTransaction(transactionMessage);
 
@@ -362,14 +309,13 @@ async function signModifyingAndPartialTransactionSigners<
             return signatures;
         }),
     );
-    const signedTransaction: Readonly<Transaction & TransactionWithLifetime> = {
+
+    return Object.freeze({
         ...modifiedTransaction,
         signatures: Object.freeze(
             signatureDictionaries.reduce((signatures, signatureDictionary) => {
                 return { ...signatures, ...signatureDictionary };
             }, modifiedTransaction.signatures ?? {}),
         ),
-    };
-
-    return Object.freeze(signedTransaction);
+    }) as ReturnType;
 }
diff --git a/packages/transaction-messages/src/__typetests__/create-transaction-message-typetest.ts b/packages/transaction-messages/src/__typetests__/create-transaction-message-typetest.ts
@@ -1,5 +1,6 @@
 import { createTransactionMessage } from '../create-transaction-message';
 import { TransactionMessage } from '../transaction-message';
+import { TransactionMessageWithinSizeLimit } from '../transaction-message-size';
 
 type LegacyTransactionMessage = Extract<TransactionMessage, { version: 'legacy' }>;
 type V0TransactionMessage = Extract<TransactionMessage, { version: 0 }>;
@@ -19,3 +20,9 @@ type V0TransactionMessage = Extract<TransactionMessage, { version: 0 }>;
     // @ts-expect-error Should not be legacy.
     message satisfies LegacyTransactionMessage;
 }
+
+// It returns an empty transaction message with size limit type safety.
+{
+    createTransactionMessage({ version: 'legacy' }) satisfies TransactionMessageWithinSizeLimit;
+    createTransactionMessage({ version: 0 }) satisfies TransactionMessageWithinSizeLimit;
+}
diff --git a/packages/transaction-messages/src/__typetests__/durable-nonce-typetest.ts b/packages/transaction-messages/src/__typetests__/durable-nonce-typetest.ts
@@ -2,6 +2,7 @@ import type { Address } from '@solana/addresses';
 import { pipe } from '@solana/functional';
 import { IInstruction } from '@solana/instructions';
 
+import { TransactionMessageWithBlockhashLifetime } from '../blockhash';
 import { CompilableTransactionMessage } from '../compilable-transaction-message';
 import { createTransactionMessage } from '../create-transaction-message';
 import {
@@ -15,6 +16,7 @@ import { AdvanceNonceAccountInstruction } from '../durable-nonce-instruction';
 import { setTransactionMessageFeePayer } from '../fee-payer';
 import { appendTransactionMessageInstruction } from '../instructions';
 import { BaseTransactionMessage, TransactionMessage } from '../transaction-message';
+import { TransactionMessageWithinSizeLimit } from '../transaction-message-size';
 
 const mockNonceConfig = {
     nonce: null as unknown as Nonce<'nonce'>,
@@ -124,4 +126,31 @@ type V0TransactionMessage = Extract<TransactionMessage, { version: 0 }>;
             InstructionA,
         ];
     }
+
+    // It keeps the size limit type safety if we are only updating the durable nonce lifetime.
+    {
+        const message = null as unknown as BaseTransactionMessage &
+            TransactionMessageWithDurableNonceLifetime &
+            TransactionMessageWithinSizeLimit;
+        const newMessage = setTransactionMessageLifetimeUsingDurableNonce(mockNonceConfig, message);
+        newMessage satisfies TransactionMessageWithinSizeLimit;
+    }
+
+    // It removes the size limit type safety if we previously has a blockhash lifetime.
+    {
+        const message = null as unknown as BaseTransactionMessage &
+            TransactionMessageWithBlockhashLifetime &
+            TransactionMessageWithinSizeLimit;
+        const newMessage = setTransactionMessageLifetimeUsingDurableNonce(mockNonceConfig, message);
+        // @ts-expect-error The message may no longer be within size limit.
+        newMessage satisfies TransactionMessageWithinSizeLimit;
+    }
+
+    // It removes the size limit type safety if we previously had no lifetime set.
+        {
+        const message = null as unknown as BaseTransactionMessage & TransactionMessageWithinSizeLimit;
+        const newMessage = setTransactionMessageLifetimeUsingDurableNonce(mockNonceConfig, message);
+        // @ts-expect-error The message may no longer be within size limit.
+        newMessage satisfies TransactionMessageWithinSizeLimit;
+    }
 }
diff --git a/packages/transaction-messages/src/__typetests__/instructions-typetest.ts b/packages/transaction-messages/src/__typetests__/instructions-typetest.ts
@@ -17,6 +17,7 @@ import {
     prependTransactionMessageInstructions,
 } from '../instructions';
 import { BaseTransactionMessage } from '../transaction-message';
+import { TransactionMessageWithinSizeLimit } from '../transaction-message-size';
 
 type IInstruction = BaseTransactionMessage['instructions'][number];
 type InstructionA = IInstruction & { identifier: 'A' };
@@ -81,6 +82,14 @@ type InstructionC = IInstruction & { identifier: 'C' };
         message satisfies BaseTransactionMessage & TransactionMessageWithDurableNonceLifetime;
         message.instructions satisfies readonly [AdvanceNonceAccountInstruction, InstructionA];
     }
+
+    // It removes the size limit type safety.
+    {
+        const message = null as unknown as BaseTransactionMessage & TransactionMessageWithinSizeLimit;
+        const newMessage = appendTransactionMessageInstruction(null as unknown as IInstruction, message);
+        // @ts-expect-error Potentially no longer within size limit.
+        newMessage satisfies TransactionMessageWithinSizeLimit;
+    }
 }
 
 // [DESCRIBE] appendTransactionMessageInstructions
@@ -115,6 +124,14 @@ type InstructionC = IInstruction & { identifier: 'C' };
         );
         newMessage.instructions satisfies readonly [...IInstruction[], InstructionA, InstructionB];
     }
+
+    // It removes the size limit type safety.
+    {
+        const message = null as unknown as BaseTransactionMessage & TransactionMessageWithinSizeLimit;
+        const newMessage = appendTransactionMessageInstructions([null as unknown as IInstruction], message);
+        // @ts-expect-error Potentially no longer within size limit.
+        newMessage satisfies TransactionMessageWithinSizeLimit;
+    }
 }
 
 // [DESCRIBE] prependTransactionMessageInstruction
@@ -195,6 +212,14 @@ type InstructionC = IInstruction & { identifier: 'C' };
         // @ts-expect-error No longer a durable nonce lifetime.
         message satisfies BaseTransactionMessage & TransactionMessageWithDurableNonceLifetime;
     }
+
+    // It removes the size limit type safety.
+    {
+        const message = null as unknown as BaseTransactionMessage & TransactionMessageWithinSizeLimit;
+        const newMessage = prependTransactionMessageInstruction(null as unknown as IInstruction, message);
+        // @ts-expect-error Potentially no longer within size limit.
+        newMessage satisfies TransactionMessageWithinSizeLimit;
+    }
 }
 
 // [DESCRIBE] prependTransactionMessageInstructions
@@ -239,4 +264,12 @@ type InstructionC = IInstruction & { identifier: 'C' };
         );
         newMessage.instructions satisfies readonly [InstructionA, InstructionB, ...IInstruction[]];
     }
+
+    // It removes the size limit type safety.
+    {
+        const message = null as unknown as BaseTransactionMessage & TransactionMessageWithinSizeLimit;
+        const newMessage = prependTransactionMessageInstructions([null as unknown as IInstruction], message);
+        // @ts-expect-error Potentially no longer within size limit.
+        newMessage satisfies TransactionMessageWithinSizeLimit;
+    }
 }
diff --git a/packages/transaction-messages/src/create-transaction-message.ts b/packages/transaction-messages/src/create-transaction-message.ts
@@ -1,9 +1,16 @@
 import { TransactionMessage, TransactionVersion } from './transaction-message';
+import { TransactionMessageWithinSizeLimit } from './transaction-message-size';
 
 type TransactionConfig<TVersion extends TransactionVersion> = Readonly<{
     version: TVersion;
 }>;
 
+type EmptyTransactionMessage<TVersion extends TransactionVersion> = Omit<
+    Extract<TransactionMessage, { version: TVersion }>,
+    'instructions'
+> &
+    TransactionMessageWithinSizeLimit & { instructions: readonly [] };
+
 /**
  * Given a {@link TransactionVersion} this method will return an empty transaction having the
  * capabilities of that version.
@@ -17,12 +24,9 @@ type TransactionConfig<TVersion extends TransactionVersion> = Readonly<{
  */
 export function createTransactionMessage<TVersion extends TransactionVersion>(
     config: TransactionConfig<TVersion>,
-): Omit<Extract<TransactionMessage, { version: TVersion }>, 'instructions'> & { instructions: readonly [] };
-export function createTransactionMessage<TVersion extends TransactionVersion>({
-    version,
-}: TransactionConfig<TVersion>): TransactionMessage {
+): EmptyTransactionMessage<TVersion> {
     return Object.freeze({
         instructions: Object.freeze([]),
-        version,
-    }) as TransactionMessage;
+        version: config.version,
+    }) as EmptyTransactionMessage<TVersion>;
 }
diff --git a/packages/transaction-messages/src/durable-nonce.ts b/packages/transaction-messages/src/durable-nonce.ts
@@ -10,6 +10,7 @@ import {
 } from './durable-nonce-instruction';
 import { ExcludeTransactionMessageLifetime } from './lifetime';
 import { BaseTransactionMessage } from './transaction-message';
+import { ExcludeTransactionMessageWithinSizeLimit } from './transaction-message-size';
 
 type DurableNonceConfig<
     TNonceAccountAddress extends string = string,
@@ -260,7 +261,15 @@ type SetTransactionMessageWithDurableNonceLifetime<
     TNonceAccountAddress extends string = string,
     TNonceAuthorityAddress extends string = string,
     TNonceValue extends string = string,
-> = Omit<TTransactionMessage, 'instructions'> & {
+> = Omit<
+    // 1. The transaction message only grows in size if it currently has a different (or no) lifetime.
+    TTransactionMessage extends TransactionMessageWithDurableNonceLifetime
+        ? TTransactionMessage
+        : ExcludeTransactionMessageWithinSizeLimit<TTransactionMessage>,
+    // 2. Remove the instructions array as we are going to replace it with a new one.
+    'instructions'
+> & {
+    // 3. Replace or prepend the first instruction with the advance nonce account instruction.
     readonly instructions: TTransactionMessage['instructions'] extends readonly [
         AdvanceNonceAccountInstruction,
         ...infer TTail extends readonly IInstruction[],
@@ -270,5 +279,6 @@ type SetTransactionMessageWithDurableNonceLifetime<
               AdvanceNonceAccountInstruction<TNonceAccountAddress, TNonceAuthorityAddress>,
               ...TTransactionMessage['instructions'],
           ];
+    // 4. Set the lifetime constraint to the nonce value.
     readonly lifetimeConstraint: NonceLifetimeConstraint<TNonceValue>;
 };
diff --git a/packages/transaction-messages/src/index.ts b/packages/transaction-messages/src/index.ts
@@ -39,6 +39,7 @@ export * from './durable-nonce';
 export { isAdvanceNonceAccountInstruction } from './durable-nonce-instruction';
 export * from './fee-payer';
 export * from './instructions';
+export * from './transaction-message-size';
 export * from './transaction-message';
 
 // Remove in the next major version.