Feature/135 transaction impact simulator

[Oluwasuyi-Timilehin]

#closes #135

Description

This PR resolves issue #135 by adding a dry-run transaction impact simulator (simulateTransactionImpact) to the sorokit-core transaction module. This allows developers and wallets to predict liquid asset balance changes (both native XLM and credit trustline assets) for a given account before committing and submitting the transaction to the network.

In alignment with the ecosystem's design principles, this feature is completely stateless, framework-agnostic, and implements the no-throw result model, cleanly packaging errors into SorokitResult values rather than throwing exceptions.

Changes

src/transaction/index.ts

• Implemented simulateTransactionImpact(publicKey, transactionXdr).
• Added structural decoding using TransactionBuilder.fromXDR.
• Added sequential operation simulation loops supporting payment and createAccount mutations.
• Integrated internal side-effect utilities (mutateAssetBalance) to calculate precision updates cleanly.

src/tests/transaction.test.ts

• Added an isolated test suite targeting simulateTransactionImpact.
• Covered outbound payment tracking (deductions).
• Covered inbound asset tracking (influx/credit additions).
• Covered syntax parsing boundary failure modes to guarantee SorokitResult<"error"> layout standards.

Verification Results

Automated Unit Tests

Executed vitest suite to verify execution stability:

ux-dev@sorokit-core:~$ npm run test src/tests/transaction.test.ts

 ✓ src/tests/transaction.test.ts (28)
   ✓ memo builders (#114) (7)
   ✓ analyzeFeeHistory (3)
   ✓ transaction streaming filters (11)
   ✓ simulateTransactionImpact — Dry Run Simulator (3)
     ✓ successfully simulates balance deductions when an account sends native payment
     ✓ successfully simulates balance influx when an account receives a credit asset payment
     ✓ returns error safely matching the no-throw result layout if XDR conversion throws

Test Files  1 passed (1)
     Tests  28 passed (28)
#closes 

[drips-wave]

@Oluwasuyi-Timilehin Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits