feat: add deterministic transaction testing fixtures and documentation

Author: adnaan-id

docs/testing-fixtures.md

@@ -0,0 +1,70 @@
+# Transaction Testing Fixtures
+
+Testing transaction flows involving offline preparation, signing, and network submission can be complex and prone to flakiness if reliant on live network dependencies (like fetching sequences or fee statistics). 
+
+To ensure SDK stability and provide consumers with reliable tools for their own testing, the PocketPay SDK exports deterministic fixture generators.
+
+## Why Use Deterministic Fixtures?
+- **No Network Calls**: Fixture generation is entirely offline. No calls are made to Horizon.
+- **Repeatable State**: Timebounds, sequence numbers, and base fees are hardcoded. Tests will not break due to the passage of time or sequence advancement.
+- **Type Safety**: The generators return the exact interfaces used by the SDK (`PreparedTransaction`, `SignedTransaction`, etc.) or construct real `StellarSDK.Transaction` objects so that internal assertions pass perfectly.
+
+## Available Generators
+
+All fixture generators are exported from `src/transactions/index.ts`.
+
+### 1. `createPreparedTransactionFixture`
+Simulates a transaction that has completed the offline preparation phase (`fetchNetworkState`) and is ready to be built.
+
+```typescript
+import { createPreparedTransactionFixture } from 'stellar-pocketpay-sdk';
+
+const prepared = createPreparedTransactionFixture({
+  baseFee: '500' // You can override any field
+});
+
+console.log(prepared.readyToBuild); // true
+console.log(prepared.timebounds); // Deterministic timebounds
+```
+
+### 2. `createUnsignedTransactionFixture`
+Simulates a transaction that has been built into a `StellarSDK.Transaction` but has not yet been signed.
+
+```typescript
+import { createUnsignedTransactionFixture } from 'stellar-pocketpay-sdk';
+
+const unsigned = createUnsignedTransactionFixture({
+  memo: 'Testing offline'
+});
+
+// Provides access to a real StellarSDK.Transaction instance
+console.log(unsigned.transaction.memo.value.toString()); // "Testing offline"
+```
+
+### 3. `createSignedTransactionFixture`
+Simulates a transaction that has been signed with a keypair. The SDK uses a deterministic dummy key to produce a valid signature format over the deterministic payload.
+
+```typescript
+import { createSignedTransactionFixture } from 'stellar-pocketpay-sdk';
+
+// Pass a specific secret key if you want to test your own validation logic
+const signed = createSignedTransactionFixture('SBU24Y4P...');
+
+console.log(signed.xdr); // Base64 encoded XDR envelope
+```
+
+### 4. `createSubmissionResultFixture`
+Simulates the outcome of `submitSignedTransaction` without actually broadcasting to the network.
+
+```typescript
+import { createSubmissionResultFixture } from 'stellar-pocketpay-sdk';
+
+const success = createSubmissionResultFixture('success');
+const failure = createSubmissionResultFixture('failed');
+const unknown = createSubmissionResultFixture('unknown');
+
+// Useful for mocking the submission layer in tests
+```
+
+## Best Practices
+When writing tests for your PocketPay integration, use `vi.mock` or `jest.mock` on the network submission and preparation layers, and use these fixtures as the resolved return values. This effectively stubs out Horizon, ensuring your business logic operates deterministically against valid transaction payloads.

src/transactions/index.ts

@@ -298,6 +298,7 @@ export async function safeGetPayments(
 
 export * from './mapper';
 export * from './fixtures';
+export * from './test-fixtures';
 
 // ─── Offline Transaction Preparation ───────────────────────────────────────────
 export {

src/transactions/test-fixtures.ts

@@ -0,0 +1,147 @@
+import * as StellarSDK from '@stellar/stellar-sdk';
+import { 
+  PreparedTransaction, 
+  UnsignedTransaction, 
+  SignedTransaction, 
+  SubmissionResult 
+} from './offline-preparation';
+
+/** Deterministic mock source public key (G...) */
+export const FIXTURE_SOURCE_PK = 'GBEDH75BXETOM2UPESSCHDVGV7XRDKS74YUKXTC7LR627DQ3SUZIJG3Y';
+/** Deterministic mock destination public key (G...) */
+export const FIXTURE_DESTINATION_PK = 'GBAW5KWLZU5PEUMR4PWXJVGFXDT4FRYIOKKTU74O5CGB24RWJS36LICH';
+/** Deterministic mock secret key (S...) matching the source public key */
+export const FIXTURE_SOURCE_SK = 'SDUTB2DT5NIGRKSGUHEU3TSZ4UJ45CJ3KVDSAKOOMHZEI64F2M4EIJCD'; 
+/** We use Stellar Testnet as the deterministic network */
+export const FIXTURE_NETWORK = StellarSDK.Networks.TESTNET;
+
+/**
+ * Creates a deterministic PreparedTransaction fixture.
+ * 
+ * @param overrides Optional overrides for the prepared transaction properties
+ * @returns A deterministic PreparedTransaction
+ */
+export function createPreparedTransactionFixture(overrides?: Partial<PreparedTransaction>): PreparedTransaction {
+  return {
+    sourcePublicKey: FIXTURE_SOURCE_PK,
+    networkPassphrase: FIXTURE_NETWORK,
+    operations: [{
+      destination: FIXTURE_DESTINATION_PK,
+      amount: '10',
+      asset: { code: 'XLM' }
+    }],
+    timebounds: { minTime: 1700000000, maxTime: 1700000300 },
+    baseFee: '100',
+    networkState: { sequence: '1234567890', fetchedAt: 1700000000 },
+    readyToBuild: true,
+    ...overrides
+  };
+}
+
+/**
+ * Creates a deterministic UnsignedTransaction fixture containing a real StellarSDK.Transaction.
+ * 
+ * @param overrides Optional overrides for the PreparedTransaction used to build it
+ * @returns A deterministic UnsignedTransaction
+ */
+export function createUnsignedTransactionFixture(overrides?: Partial<PreparedTransaction>): UnsignedTransaction {
+  const prepared = createPreparedTransactionFixture(overrides);
+  
+  const account = new StellarSDK.Account(
+    prepared.sourcePublicKey,
+    prepared.networkState.sequence
+  );
+
+  const builder = new StellarSDK.TransactionBuilder(account, {
+    fee: prepared.baseFee,
+    networkPassphrase: prepared.networkPassphrase,
+    timebounds: prepared.timebounds,
+  });
+
+  for (const op of prepared.operations) {
+    builder.addOperation(
+      StellarSDK.Operation.payment({
+        destination: op.destination,
+        asset: StellarSDK.Asset.native(), // For simplicity in fixture, we assume native if XLM
+        amount: op.amount,
+      })
+    );
+  }
+
+  if (prepared.memo) {
+    builder.addMemo(StellarSDK.Memo.text(prepared.memo));
+  }
+
+  const transaction = builder.build();
+  
+  return {
+    transaction,
+    networkPassphrase: prepared.networkPassphrase,
+    sourcePublicKey: prepared.sourcePublicKey,
+    hash: transaction.hash().toString('hex'),
+  };
+}
+
+/**
+ * Creates a deterministic SignedTransaction fixture.
+ * Note: Since we need a real signature, this uses a dummy keypair to sign the mock transaction.
+ * 
+ * @param secretKey Optional valid secret key to sign with. If omitted, a deterministic dummy key is used.
+ * @param overrides Optional overrides for the underlying transaction
+ * @returns A deterministic SignedTransaction
+ */
+export function createSignedTransactionFixture(
+  secretKey: string = FIXTURE_SOURCE_SK,
+  overrides?: Partial<PreparedTransaction>
+): SignedTransaction {
+  const unsigned = createUnsignedTransactionFixture(overrides);
+  const keypair = StellarSDK.Keypair.fromSecret(secretKey);
+  
+  unsigned.transaction.sign(keypair);
+  
+  return {
+    transaction: unsigned.transaction,
+    networkPassphrase: unsigned.networkPassphrase,
+    hash: unsigned.transaction.hash().toString('hex'),
+    xdr: unsigned.transaction.toEnvelope().toXDR('base64'),
+  };
+}
+
+/**
+ * Creates a deterministic SubmissionResult fixture.
+ * 
+ * @param status The status of the submission ('success', 'failed', 'unknown')
+ * @param overrides Optional overrides for the SubmissionResult properties
+ * @returns A deterministic SubmissionResult
+ */
+export function createSubmissionResultFixture(
+  status: 'success' | 'failed' | 'unknown', 
+  overrides?: Partial<SubmissionResult>
+): SubmissionResult {
+  if (status === 'success') {
+    return { 
+      success: true, 
+      hash: 'a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef', 
+      ledger: 12345, 
+      fee: '100', 
+      ...overrides 
+    };
+  } else if (status === 'failed') {
+    return { 
+      success: false, 
+      hash: 'f6e5d4c3b2a109876543210987fedcba0987654321fedcba0987654321fedcba', 
+      error: 'Transaction failed on network', 
+      errorCode: 'TX_FAILED', 
+      ...overrides 
+    };
+  } else {
+    // unknown
+    return { 
+      success: false, 
+      hash: '0000000000000000000000000000000000000000000000000000000000000000', 
+      error: 'Transaction status unknown due to timeout', 
+      errorCode: 'TX_STATUS_UNKNOWN', 
+      ...overrides 
+    };
+  }
+}

tests/transaction-test-fixtures.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import { 
+  createPreparedTransactionFixture, 
+  createUnsignedTransactionFixture, 
+  createSignedTransactionFixture, 
+  createSubmissionResultFixture,
+  FIXTURE_SOURCE_PK,
+  FIXTURE_DESTINATION_PK
+} from '../src/transactions/test-fixtures';
+import * as StellarSDK from '@stellar/stellar-sdk';
+
+describe('Transaction Fixture Generators', () => {
+  describe('createPreparedTransactionFixture', () => {
+    it('should generate a deterministic prepared transaction', () => {
+      const fixture = createPreparedTransactionFixture();
+      
+      expect(fixture.sourcePublicKey).toBe(FIXTURE_SOURCE_PK);
+      expect(fixture.readyToBuild).toBe(true);
+      expect(fixture.baseFee).toBe('100');
+      expect(fixture.operations[0].destination).toBe(FIXTURE_DESTINATION_PK);
+    });
+
+    it('should allow overrides', () => {
+      const fixture = createPreparedTransactionFixture({ baseFee: '500' });
+      expect(fixture.baseFee).toBe('500');
+      expect(fixture.sourcePublicKey).toBe(FIXTURE_SOURCE_PK);
+    });
+  });
+
+  describe('createUnsignedTransactionFixture', () => {
+    it('should generate a deterministic unsigned transaction with a real Stellar transaction object', () => {
+      const fixture = createUnsignedTransactionFixture();
+      
+      expect(fixture.transaction).toBeInstanceOf(StellarSDK.Transaction);
+      expect(fixture.sourcePublicKey).toBe(FIXTURE_SOURCE_PK);
+      expect(fixture.hash).toBeDefined();
+    });
+
+    it('should apply overrides to the transaction builder inputs', () => {
+      const fixture = createUnsignedTransactionFixture({ memo: 'Test Memo' });
+      
+      expect(fixture.transaction.memo.value?.toString()).toBe('Test Memo');
+    });
+  });
+
+  describe('createSignedTransactionFixture', () => {
+    it('should generate a deterministic signed transaction with signatures', () => {
+      const fixture = createSignedTransactionFixture();
+      
+      expect(fixture.transaction.signatures.length).toBe(1);
+      expect(fixture.xdr).toBeDefined();
+    });
+  });
+
+  describe('createSubmissionResultFixture', () => {
+    it('should generate a success result', () => {
+      const fixture = createSubmissionResultFixture('success');
+      expect(fixture.success).toBe(true);
+      if (fixture.success) {
+        expect(fixture.ledger).toBeDefined();
+      }
+    });
+
+    it('should generate a failure result', () => {
+      const fixture = createSubmissionResultFixture('failed');
+      expect(fixture.success).toBe(false);
+      if (!fixture.success) {
+        expect(fixture.errorCode).toBe('TX_FAILED');
+      }
+    });
+
+    it('should generate an unknown result', () => {
+      const fixture = createSubmissionResultFixture('unknown');
+      expect(fixture.success).toBe(false);
+      if (!fixture.success) {
+        expect(fixture.errorCode).toBe('TX_STATUS_UNKNOWN');
+      }
+    });
+  });
+});