Feat/soroban mapper

[Damola-Sodiq]

Summary

Adds a dedicated result mapper for Soroban contract invocations and vault-related operations (deposit, withdraw, get_balance). This converts raw Soroban RPC simulation, submission, and execution responses into stable, strongly-typed SDK values to improve developer experience and support mobile vault integration.

Key Changes

• Invocation Result Mappers (src/soroban/mapper.ts):

  • mapSorobanInvocationResult<T>: Parses raw Soroban RPC responses (simulations, transaction submissions, status checks, or native ScVal returns) into typed SorobanInvocationResult<T>.
  • mapVaultInvocationResult: Maps vault operation outputs into structured VaultMappedResult objects (including stroop-to-XLM balance conversions and operation tracking).
  • mapSorobanContractError: Standardizes contract errors and classifies error codes.

• Types & Interfaces (src/types/index.ts):

  • Added SorobanInvocationStatus ('success' | 'failed' | 'simulation_error' | 'error' | 'pending').
  • Added SorobanInvocationResult<T>, VaultMappedResult, VaultOperationType, and SorobanInvocationMapperOptions.

• Module Entrypoints & Integration:

  • Updated depositToVault, withdrawFromVault, and getVaultBalance in src/soroban/index.ts to utilize the new mappers under the hood.
  • Added dedicated src/vault/index.ts entrypoint and re-exported mappers in src/index.ts.

• Documentation (docs/soroban-vault.md):

  • Added "Result Mapping & Mobile Integration" section with interface definitions and usage examples.

Verification & Testing

• Unit Tests:
  • Added tests/sorobanMapper.test.ts covering 18 test cases (simulation success/error, send errors, transaction status, error classification, primitive return values).
  • Updated tests/vault.test.ts to assert against mapped result shapes.
  • npx vitest run tests/sorobanMapper.test.ts tests/vault.test.ts tests/exports.test.ts passing (38 tests).
• TypeScript Build:
  • Verified clean compilation via npm run build (tsc).

closes #187