Add SendableTransaction type

Author: lorisleiva

examples/transfer-lamports/src/example.ts

@@ -12,6 +12,7 @@ import pressAnyKeyPrompt from '@solana/example-utils/pressAnyKeyPrompt.js';
 import {
     address,
     appendTransactionMessageInstruction,
+    assertIsSendableTransaction,
     createKeyPairSignerFromBytes,
     createSolanaRpc,
     createSolanaRpcSubscriptions,
@@ -183,6 +184,7 @@ log.warn(
         'connections. Use Chrome.',
 );
 try {
+    assertIsSendableTransaction(signedTransaction);
     await sendAndConfirmTransaction(signedTransaction, { commitment: 'confirmed' });
     log.info('[success] Transfer confirmed');
     await pressAnyKeyPrompt('Press any key to quit');

packages/kit/src/__tests__/send-transaction-internal-test.ts

@@ -3,8 +3,8 @@ import type { Rpc, SendTransactionApi } from '@solana/rpc';
 import type { Commitment } from '@solana/rpc-types';
 import {
     Base64EncodedWireTransaction,
-    FullySignedTransaction,
     getBase64EncodedWireTransaction,
+    SendableTransaction,
     Transaction,
     TransactionWithBlockhashLifetime,
     TransactionWithDurableNonceLifetime,
@@ -22,7 +22,7 @@ const FOREVER_PROMISE = new Promise(() => {
 });
 
 describe('sendAndConfirmTransaction', () => {
-    const MOCK_TRANSACTION = {} as FullySignedTransaction & Transaction & TransactionWithBlockhashLifetime;
+    const MOCK_TRANSACTION = {} as SendableTransaction & Transaction & TransactionWithBlockhashLifetime;
     let confirmRecentTransaction: jest.Mock;
     let createPendingRequest: jest.Mock;
     let rpc: Rpc<SendTransactionApi>;
@@ -176,7 +176,7 @@ describe('sendAndConfirmTransaction', () => {
 });
 
 describe('sendAndConfirmDurableNonceTransaction', () => {
-    const MOCK_DURABLE_NONCE_TRANSACTION = {} as unknown as FullySignedTransaction &
+    const MOCK_DURABLE_NONCE_TRANSACTION = {} as unknown as SendableTransaction &
         Transaction &
         TransactionWithDurableNonceLifetime;
     let confirmDurableNonceTransaction: jest.Mock;

packages/kit/src/send-and-confirm-durable-nonce-transaction.ts

@@ -5,12 +5,12 @@ import {
     createRecentSignatureConfirmationPromiseFactory,
     waitForDurableNonceTransactionConfirmation,
 } from '@solana/transaction-confirmation';
-import { FullySignedTransaction, Transaction, TransactionWithDurableNonceLifetime } from '@solana/transactions';
+import { SendableTransaction, Transaction, TransactionWithDurableNonceLifetime } from '@solana/transactions';
 
 import { sendAndConfirmDurableNonceTransaction_INTERNAL_ONLY_DO_NOT_EXPORT } from './send-transaction-internal';
 
 type SendAndConfirmDurableNonceTransactionFunction = (
-    transaction: FullySignedTransaction & Transaction & TransactionWithDurableNonceLifetime,
+    transaction: SendableTransaction & Transaction & TransactionWithDurableNonceLifetime,
     config: Omit<
         Parameters<typeof sendAndConfirmDurableNonceTransaction_INTERNAL_ONLY_DO_NOT_EXPORT>[0],
         'confirmDurableNonceTransaction' | 'rpc' | 'transaction'

packages/kit/src/send-and-confirm-transaction.ts

@@ -6,12 +6,12 @@ import {
     TransactionWithLastValidBlockHeight,
     waitForRecentTransactionConfirmation,
 } from '@solana/transaction-confirmation';
-import { FullySignedTransaction, Transaction } from '@solana/transactions';
+import { SendableTransaction, Transaction } from '@solana/transactions';
 
 import { sendAndConfirmTransactionWithBlockhashLifetime_INTERNAL_ONLY_DO_NOT_EXPORT } from './send-transaction-internal';
 
 type SendAndConfirmTransactionWithBlockhashLifetimeFunction = (
-    transaction: FullySignedTransaction & Transaction & TransactionWithLastValidBlockHeight,
+    transaction: SendableTransaction & Transaction & TransactionWithLastValidBlockHeight,
     config: Omit<
         Parameters<typeof sendAndConfirmTransactionWithBlockhashLifetime_INTERNAL_ONLY_DO_NOT_EXPORT>[0],
         'confirmRecentTransaction' | 'rpc' | 'transaction'

packages/kit/src/send-transaction-internal.ts

@@ -7,8 +7,8 @@ import {
     waitForRecentTransactionConfirmation,
 } from '@solana/transaction-confirmation';
 import {
-    FullySignedTransaction,
     getBase64EncodedWireTransaction,
+    SendableTransaction,
     Transaction,
     TransactionWithDurableNonceLifetime,
 } from '@solana/transactions';
@@ -22,7 +22,7 @@ interface SendAndConfirmDurableNonceTransactionConfig
             'getNonceInvalidationPromise' | 'getRecentSignatureConfirmationPromise'
         >,
     ) => Promise<void>;
-    transaction: FullySignedTransaction & Transaction & TransactionWithDurableNonceLifetime;
+    transaction: SendableTransaction & Transaction & TransactionWithDurableNonceLifetime;
 }
 
 interface SendAndConfirmTransactionWithBlockhashLifetimeConfig
@@ -34,14 +34,14 @@ interface SendAndConfirmTransactionWithBlockhashLifetimeConfig
             'getBlockHeightExceedencePromise' | 'getRecentSignatureConfirmationPromise'
         >,
     ) => Promise<void>;
-    transaction: FullySignedTransaction & Transaction & TransactionWithLastValidBlockHeight;
+    transaction: SendableTransaction & Transaction & TransactionWithLastValidBlockHeight;
 }
 
 interface SendTransactionBaseConfig extends SendTransactionConfigWithoutEncoding {
     abortSignal?: AbortSignal;
     commitment: Commitment;
     rpc: Rpc<SendTransactionApi>;
-    transaction: FullySignedTransaction & Transaction;
+    transaction: SendableTransaction & Transaction;
 }
 
 type SendTransactionConfigWithoutEncoding = Omit<

packages/kit/src/send-transaction-without-confirming.ts

@@ -1,10 +1,10 @@
 import type { Rpc, SendTransactionApi } from '@solana/rpc';
-import { FullySignedTransaction, Transaction } from '@solana/transactions';
+import { SendableTransaction, Transaction } from '@solana/transactions';
 
 import { sendTransaction_INTERNAL_ONLY_DO_NOT_EXPORT } from './send-transaction-internal';
 
 type SendTransactionWithoutConfirmingFunction = (
-    transaction: FullySignedTransaction & Transaction,
+    transaction: SendableTransaction & Transaction,
     config: Omit<Parameters<typeof sendTransaction_INTERNAL_ONLY_DO_NOT_EXPORT>[0], 'rpc' | 'transaction'>,
 ) => Promise<void>;
 

packages/transactions/README.md

@@ -37,7 +37,16 @@ In order to be landed on the network, a transaction must be signed by all of the
 
 #### `FullySignedTransaction`
 
-This type represents a transaction that is signed by all of its required signers. Being fully signed is a prerequisite of functions designed to land transactions on the network.
+This type represents a transaction that is signed by all of its required signers.
+
+#### `SendableTransaction`
+
+This type represents a transaction that has all the required conditions to be sent to the network. Namely:
+
+- It must be fully signed (ie. conform to `FullySignedTransaction`)
+- It must be within size limit (ie. conform to `TransactionWithSizeLimit`)
+
+The `SendableTransaction` type is a prerequisite of functions designed to land transactions on the network.
 
 ### Functions
 

packages/transactions/src/__typetests__/sendable-transaction-typetest.ts

@@ -0,0 +1,60 @@
+import { assertIsSendableTransaction, isSendableTransaction, SendableTransaction } from '../sendable-transaction';
+import { FullySignedTransaction } from '../signatures';
+import { Transaction } from '../transaction';
+import { TransactionWithinSizeLimit } from '../transaction-size';
+
+// [DESCRIBE] SendableTransaction.
+{
+    // It must have all the required conditions.
+    {
+        null as unknown as FullySignedTransaction &
+            Transaction &
+            TransactionWithinSizeLimit satisfies SendableTransaction;
+    }
+
+    // It does not satify Transaction alone.
+    {
+        // @ts-expect-error No required conditions.
+        null as unknown as Transaction satisfies SendableTransaction;
+    }
+
+    // It does not satify Transaction with missing required conditions.
+    {
+        // @ts-expect-error Not enough required conditions.
+        null as unknown as FullySignedTransaction & Transaction satisfies SendableTransaction;
+        // @ts-expect-error Not enough required conditions.
+        null as unknown as Transaction & TransactionWithinSizeLimit satisfies SendableTransaction;
+    }
+}
+
+// [DESCRIBE] isSendableTransaction.
+{
+    // It narrows the type to a SendableTransaction.
+    {
+        const transaction = null as unknown as Transaction;
+        if (isSendableTransaction(transaction)) {
+            transaction satisfies SendableTransaction;
+            transaction satisfies FullySignedTransaction;
+            transaction satisfies TransactionWithinSizeLimit;
+        } else {
+            // @ts-expect-error Not sendable.
+            transaction satisfies SendableTransaction;
+            // @ts-expect-error Not fully signed.
+            transaction satisfies FullySignedTransaction;
+            // @ts-expect-error Not within size limit.
+            transaction satisfies TransactionWithinSizeLimit;
+        }
+    }
+}
+
+// [DESCRIBE] assertIsSendableTransaction.
+{
+    // It narrows the type to a SendableTransaction.
+    {
+        const transaction = null as unknown as Transaction;
+        assertIsSendableTransaction(transaction);
+        transaction satisfies SendableTransaction;
+        transaction satisfies FullySignedTransaction;
+        transaction satisfies TransactionWithinSizeLimit;
+    }
+}

packages/transactions/src/index.ts

@@ -13,6 +13,7 @@ export * from './lifetime';
 export * from './compile-transaction';
 export * from './signatures';
 export * from './wire-transaction';
+export * from './sendable-transaction';
 export * from './transaction-message-size';
 export * from './transaction-size';
 export * from './transaction';

packages/transactions/src/sendable-transaction.ts

@@ -0,0 +1,77 @@
+import { assertIsFullySignedTransaction, FullySignedTransaction, isFullySignedTransaction } from './signatures';
+import { Transaction } from './transaction';
+import {
+    assertIsTransactionWithinSizeLimit,
+    isTransactionWithinSizeLimit,
+    TransactionWithinSizeLimit,
+} from './transaction-size';
+
+/**
+ * Helper type that includes all transaction types required
+ * for the transaction to be sent to the network.
+ *
+ * @see {@link isSendableTransaction}
+ * @see {@link assertIsSendableTransaction}
+ */
+export type SendableTransaction = FullySignedTransaction & TransactionWithinSizeLimit;
+
+/**
+ * Checks if a transaction has all the required
+ * conditions to be sent to the network.
+ *
+ * @example
+ * ```ts
+ * import { isSendableTransaction } from '@solana/transactions';
+ *
+ * const transaction = getTransactionDecoder().decode(transactionBytes);
+ * if (isSendableTransaction(transaction)) {
+ *   // At this point we know that the transaction can be sent to the network.
+ * }
+ * ```
+ *
+ * @see {@link assertIsSendableTransaction}
+ */
+export function isSendableTransaction<TTransaction extends Transaction>(
+    transaction: TTransaction,
+): transaction is SendableTransaction & TTransaction {
+    return isFullySignedTransaction(transaction) && isTransactionWithinSizeLimit(transaction);
+}
+
+/**
+ * Asserts that a given transaction has all the
+ * required conditions to be sent to the network.
+ *
+ * From time to time you might acquire a {@link Transaction}
+ * from an untrusted network API or user input and you are not sure
+ * that it has all the required conditions to be sent to the network
+ * — such as being fully signed and within the size limit.
+ * This function can be used to assert that such a transaction
+ * is in fact sendable.
+ *
+ * @example
+ * ```ts
+ * import { assertIsSendableTransaction } from '@solana/transactions';
+ *
+ * const transaction = getTransactionDecoder().decode(transactionBytes);
+ * try {
+ *     // If this type assertion function doesn't throw, then Typescript will upcast `transaction`
+ *     // to `SendableTransaction`.
+ *     assertIsSendableTransaction(transaction);
+ *     // At this point we know that the transaction can be sent to the network.
+ *     await sendAndConfirmTransaction(transaction, { commitment: 'confirmed' });
+ * } catch(e) {
+ *     if (isSolanaError(e, SOLANA_ERROR__TRANSACTION__SIGNATURES_MISSING)) {
+ *         setError(`Missing signatures for ${e.context.addresses.join(', ')}`);
+ *     } else if (isSolanaError(e, SOLANA_ERROR__TRANSACTION__EXCEEDS_SIZE_LIMIT)) {
+ *         setError(`Transaction exceeds size limit of ${e.context.transactionSizeLimit} bytes`);
+ *     }
+ *     throw;
+ * }
+ * ```
+ */
+export function assertIsSendableTransaction<TTransaction extends Transaction>(
+    transaction: TTransaction,
+): asserts transaction is SendableTransaction & TTransaction {
+    assertIsFullySignedTransaction(transaction);
+    assertIsTransactionWithinSizeLimit(transaction);
+}