refactor(experimental): add a function to assert a transaction has a blockhash lifetime

packages/transactions/src/__tests__/blockhash-test.ts

@@ -3,7 +3,12 @@ import 'test-matchers/toBeFrozenObject';
 import { Encoder } from '@solana/codecs-core';
 import { getBase58Encoder } from '@solana/codecs-strings';
 
-import { Blockhash, ITransactionWithBlockhashLifetime, setTransactionLifetimeUsingBlockhash } from '../blockhash';
+import {
+    assertIsTransactionWithBlockhashLifetime,
+    Blockhash,
+    ITransactionWithBlockhashLifetime,
+    setTransactionLifetimeUsingBlockhash,
+} from '../blockhash';
 import { ITransactionWithSignatures } from '../signatures';
 import { BaseTransaction } from '../types';
 
@@ -109,6 +114,71 @@ describe('assertIsBlockhash()', () => {
     });
 });
 
+describe('assertIsBlockhashLifetimeTransaction', () => {
+    beforeEach(() => {
+        // use real implementation
+        jest.mocked(getBase58Encoder).mockReturnValue(originalGetBase58Encoder);
+    });
+    it('throws for a transaction with no lifetime constraint', () => {
+        const transaction: BaseTransaction = {
+            instructions: [],
+            version: 0,
+        };
+        expect(() => assertIsTransactionWithBlockhashLifetime(transaction)).toThrow();
+    });
+    it('throws for a transaction with a durable nonce constraint', () => {
+        const transaction = {
+            instructions: [],
+            lifetimeConstraint: {
+                nonce: 'abcd',
+            },
+            version: 0,
+        } as unknown as BaseTransaction;
+        expect(() => assertIsTransactionWithBlockhashLifetime(transaction)).toThrow();
+    });
+    it('throws for a transaction with a blockhash but no lastValidBlockHeight in lifetimeConstraint', () => {
+        const transaction = {
+            instructions: [],
+            lifetimeConstraint: {
+                blockhash: '11111111111111111111111111111111',
+            },
+            version: 0,
+        } as unknown as BaseTransaction;
+        expect(() => assertIsTransactionWithBlockhashLifetime(transaction)).toThrow();
+    });
+    it('throws for a transaction with a lastValidBlockHeight but no blockhash in lifetimeConstraint', () => {
+        const transaction = {
+            instructions: [],
+            lifetimeConstraint: {
+                lastValidBlockHeight: 1234n,
+            },
+            version: 0,
+        } as unknown as BaseTransaction;
+        expect(() => assertIsTransactionWithBlockhashLifetime(transaction)).toThrow();
+    });
+    it('throws for a transaction with a blockhash lifetime but an invalid blockhash value', () => {
+        const transaction = {
+            instructions: [],
+            lifetimeConstraint: {
+                blockhash: 'not a valid blockhash value',
+            },
+            version: 0,
+        } as unknown as BaseTransaction;
+        expect(() => assertIsTransactionWithBlockhashLifetime(transaction)).toThrow();
+    });
+    it('does not throw for a transaction with a valid blockhash lifetime constraint', () => {
+        const transaction = {
+            instructions: [],
+            lifetimeConstraint: {
+                blockhash: '11111111111111111111111111111111',
+                lastValidBlockHeight: 1234n,
+            },
+            version: 0,
+        } as unknown as BaseTransaction;
+        expect(() => assertIsTransactionWithBlockhashLifetime(transaction)).not.toThrow();
+    });
+});
+
 describe('setTransactionLifetimeUsingBlockhash', () => {
     let baseTx: BaseTransaction;
     const BLOCKHASH_CONSTRAINT_A = {

packages/transactions/src/__typetests__/transaction-typetests.ts

@@ -2,6 +2,7 @@ import { Address } from '@solana/addresses';
 
 import {
     appendTransactionInstruction,
+    assertIsTransactionWithBlockhashLifetime,
     assertTransactionIsFullySigned,
     Blockhash,
     IDurableNonceTransaction,
@@ -18,7 +19,7 @@ import {
 import { createTransaction } from '../create-transaction';
 import { ITransactionWithFeePayer, setTransactionFeePayer } from '../fee-payer';
 import { CompiledMessage, compileMessage } from '../message';
-import { Transaction } from '../types';
+import { BaseTransaction, Transaction } from '../types';
 import { getUnsignedTransaction } from '../unsigned-transaction';
 
 const mockFeePayer = null as unknown as Address<'feePayer'>;
@@ -538,10 +539,43 @@ async () => {
     } & ITransactionWithFeePayer<'feePayer'> &
         ITransactionWithSignatures;
 
-    // assertTransactionIsFullySigned
-    const transaction = {} as Parameters<typeof assertTransactionIsFullySigned>[0];
-    // @ts-expect-error Should not be fully signed
-    transaction satisfies IFullySignedTransaction;
-    assertTransactionIsFullySigned(transaction);
-    transaction satisfies IFullySignedTransaction;
+    {
+        // assertTransactionIsFullySigned
+        const transaction = {} as Parameters<typeof assertTransactionIsFullySigned>[0];
+        // @ts-expect-error Should not be fully signed
+        transaction satisfies IFullySignedTransaction;
+        assertTransactionIsFullySigned(transaction);
+        transaction satisfies IFullySignedTransaction;
+    }
+
+    {
+        // assertIsBlockhashLifetimeTransaction
+        const transaction = null as unknown as BaseTransaction;
+        // @ts-expect-error Should not be blockhash lifetime
+        transaction satisfies ITransactionWithBlockhashLifetime;
+        // @ts-expect-error Should not satisfy has blockhash
+        transaction satisfies {
+            lifetimeConstraint: {
+                blockhash: Blockhash;
+            };
+        };
+        // @ts-expect-error Should not satisfy has lastValidBlockHeight
+        transaction satisfies {
+            lifetimeConstraint: {
+                lastValidBlockHeight: bigint;
+            };
+        };
+        assertIsTransactionWithBlockhashLifetime(transaction);
+        transaction satisfies ITransactionWithBlockhashLifetime;
+        transaction satisfies {
+            lifetimeConstraint: {
+                blockhash: Blockhash;
+            };
+        };
+        transaction satisfies {
+            lifetimeConstraint: {
+                lastValidBlockHeight: bigint;
+            };
+        };
+    }
 };

packages/transactions/src/blockhash.ts

@@ -44,6 +44,31 @@ export function assertIsBlockhash(putativeBlockhash: string): asserts putativeBl
     }
 }
 
+function isTransactionWithBlockhashLifetime(
+    transaction: BaseTransaction | (BaseTransaction & ITransactionWithBlockhashLifetime)
+): transaction is BaseTransaction & ITransactionWithBlockhashLifetime {
+    const lifetimeConstraintShapeMatches =
+        'lifetimeConstraint' in transaction &&
+        typeof transaction.lifetimeConstraint.blockhash === 'string' &&
+        typeof transaction.lifetimeConstraint.lastValidBlockHeight === 'bigint';
+    if (!lifetimeConstraintShapeMatches) return false;
+    try {
+        assertIsBlockhash(transaction.lifetimeConstraint.blockhash);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function assertIsTransactionWithBlockhashLifetime(
+    transaction: BaseTransaction | (BaseTransaction & ITransactionWithBlockhashLifetime)
+): asserts transaction is BaseTransaction & ITransactionWithBlockhashLifetime {
+    if (!isTransactionWithBlockhashLifetime(transaction)) {
+        // TODO: Coded error.
+        throw new Error('Transaction does not have a blockhash lifetime');
+    }
+}
+
 export function setTransactionLifetimeUsingBlockhash<TTransaction extends BaseTransaction & IDurableNonceTransaction>(
     blockhashLifetimeConstraint: BlockhashLifetimeConstraint,
     transaction: TTransaction | (TTransaction & ITransactionWithSignatures)