test(soroban): add comprehensive error handling and validation test suite

[Shredder401k]

Stellar Contract Validation Suite

Summary

Implements comprehensive validation infrastructure for Stellar and Soroban operations, including contract error taxonomy, trustline validation, WASM size constraints, and transaction envelope serialization tests.

Changes

Issue #633: Soroban Contract Error Code Taxonomy

• Extended StellarErrorCode type with 7 new Soroban error categories
• Added SOROBAN_ERROR_CODES mapping with 23 contract error codes covering:
  • Host function errors (type mismatch, invalid input, arithmetic errors)
  • Contract panics (unwrap failures, assertion failures)
  • Resource limit errors (CPU, memory, storage exhaustion)
  • Storage errors (key not found, access errors)
  • Authorization errors (invalid signatures, auth failures)
  • WASM errors (traps, memory errors, invalid binaries)
• Implemented mapSorobanError() function with fallback for unknown codes
• Updated parseStellarError() to detect and categorize Soroban errors
• Added error guidance with remediation steps and documentation links
• Created comprehensive test suite with 100% error code coverage

Files Modified:

• packages/stellar/src/errors.ts - Added Soroban error taxonomy
• packages/stellar/src/soroban-errors.test.ts - Test coverage for all error codes

Issue #634: Trustline Validation Logic

• Created trustline-validation.ts module with deployment validation
• Implemented validateTrustlines() for checking required trustlines
• Added canEstablishTrustlines() to verify account capacity
• Implemented validateAssetIssuanceDeployment() for pre-deployment checks
• Added formatTrustlineError() for user-friendly error messages
• Validates trustline existence, authorization status, and limit constraints
• Enforces MAX_TRUSTLINES_PER_ACCOUNT limit (1000)
• Handles native XLM (no trustline required)
• Provides actionable error messages with missing trustline details

Files Added:

• packages/stellar/src/trustline-validation.ts - Trustline validation logic
• packages/stellar/src/trustline-validation.test.ts - Comprehensive test suite

Issue #635: Transaction Envelope Serialization Tests

• Created comprehensive test suite for multi-operation transaction batches
• Tests operation order preservation through serialize/deserialize cycles
• Validates signature integrity after serialization round-trips
• Covers all operation types used by templates:
  • createAccount, payment, changeTrust, setOptions, manageData
• Tests mixed operation batches with multiple asset types
• Validates operation source account preservation
• Tests byte-level serialization correctness
• Verifies base64 and hex encoding consistency
• Tests large batches (10+ operations) with signature preservation

Files Added:

• packages/stellar/src/transaction-envelope.test.ts - Serialization test suite

Issue #636: WASM Binary Size Validation

• Added MAX_WASM_SIZE_BYTES constant (65536 bytes / 64 KB)
• Implemented validateWasmSize() for pre-deployment size checks
• Added assertValidWasmSize() for throwing validation
• Provides clear error messages with:
  • Actual binary size
  • Maximum allowed size
  • Exact bytes to reduce
• Supports both Buffer and Uint8Array inputs
• Enforces Soroban network deployment constraints
• Prevents deployment failures with early validation

Files Modified:

• packages/stellar/src/soroban.ts - Added WASM size validation
• packages/stellar/src/soroban-wasm-validation.test.ts - Boundary and integration tests

Package Exports

• Updated packages/stellar/src/index.ts to export trustline validation

Testing

All features include comprehensive test coverage:

• Soroban Errors: 23 error codes mapped, fallback tested, categorization verified
• Trustline Validation: Missing trustlines, unauthorized, maxed limits, account capacity
• Transaction Serialization: Operation order, signature preservation, byte-level correctness
• WASM Validation: Boundary testing (limit ±1), error messages, integration scenarios

Documentation

• Added JSDoc comments for all public functions
• Included usage examples in function documentation
• Documented error code taxonomy with Stellar developer links
• Provided remediation steps for each error category

Breaking Changes

None. All changes are additive.

Closes

Closes #633
Closes #634
Closes #635
Closes #636

[drips-wave]

@Shredder401k 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