Skip to content

VERSION_COMPATIBILITY.md

Latest commit

 

History

History
309 lines (224 loc) · 7.95 KB

VERSION_COMPATIBILITY.md

File metadata and controls

309 lines (224 loc) · 7.95 KB

Version Compatibility Matrix

This document tracks tested and compatible versions of Soroban SDK, CLI, and Stellar Protocol for RemitWise contracts.

Current Production Versions

Component Version Release Date Status
Soroban SDK 21.0.0 2024 ✅ Production
Soroban CLI 21.0.0 2024 ✅ Production
Rust Toolchain stable Latest ✅ Production
Protocol 20+ - ✅ Compatible

Version History

SDK 21.0.0 (Current)

Release Date: 2024
Status: ✅ Fully Tested and Production Ready

Tested Features:

  • ✅ Contract storage and TTL management
  • ✅ Event emission and querying
  • ✅ Cross-contract calls (orchestrator)
  • ✅ Authorization and signatures
  • ✅ Stellar Asset Contract integration
  • ✅ Archival and restoration patterns
  • ✅ Gas optimization

Known Issues: None

Breaking Changes: None from 20.x series

Contracts Validated:

  • ✅ remittance_split
  • ✅ savings_goals
  • ✅ bill_payments
  • ✅ insurance
  • ✅ family_wallet
  • ✅ reporting
  • ✅ orchestrator
  • ✅ data_migration

Test Results:

  • Unit Tests: 100% passing
  • Integration Tests: 100% passing
  • Gas Benchmarks: Within acceptable range
  • Testnet Deployment: Successful
  • Mainnet Ready: Yes

SDK 20.x (Legacy)

Status: ⚠️ Legacy - Upgrade Recommended

Notes: Previous stable release. Upgrade to 21.0.0 recommended for latest features and optimizations.

Protocol Compatibility

Protocol 20 (Soroban Phase 1)

Status: ✅ Fully Compatible

Features Used:

  • Contract storage (persistent, temporary, instance)
  • TTL extension and archival
  • Event emission
  • Cross-contract calls
  • Authorization framework
  • Stellar Asset Contract integration

Network Availability:

  • Testnet: ✅ Available
  • Mainnet: ✅ Available

Protocol 21+ (Future)

Status: ⚠️ Untested - Validation Required

Expected Compatibility: High (no breaking changes anticipated)

Action Required: Test on testnet when available

Network Protocol Versions

Testnet

Date Protocol Version SDK Compatibility Status
Current 20+ 21.0.0 ✅ Active

Mainnet

Date Protocol Version SDK Compatibility Status
Current 20+ 21.0.0 ✅ Active

Rust Toolchain Compatibility

Stable Channel (Recommended)

Status: ✅ Fully Compatible

Required Targets:

  • wasm32-unknown-unknown - Primary WASM target
  • wasm32v1-none - Alternative WASM target

Installation:

rustup target add wasm32-unknown-unknown
rustup target add wasm32v1-none

Nightly Channel

Status: ⚠️ Not Recommended for Production

Notes: May work but not officially tested. Use stable channel for production deployments.

Dependency Compatibility

Core Dependencies

[dependencies]
soroban-sdk = "21.0.0"

[dev-dependencies]
soroban-sdk = { version = "21.0.0", features = ["testutils"] }

Build Profile

[profile.release]
opt-level = "z"
overflow-checks = true
debug = 0
strip = "symbols"
debug-assertions = false
panic = "abort"
codegen-units = 1
lto = true

Status: ✅ Optimized for production

Testing Matrix

Unit Tests

Contract SDK 21.0.0 Notes
remittance_split ✅ Pass All 50+ tests passing
savings_goals ✅ Pass All 60+ tests passing
bill_payments ✅ Pass All 70+ tests passing
insurance ✅ Pass All 50+ tests passing
family_wallet ✅ Pass All 60+ tests passing
reporting ✅ Pass All 25+ tests passing
orchestrator ✅ Pass All 15+ tests passing

Integration Tests

Scenario SDK 21.0.0 Notes
Remittance flow ✅ Pass End-to-end allocation
Cross-contract calls ✅ Pass Orchestrator integration
Event emission ✅ Pass All events captured
Storage archival ✅ Pass Archive/restore working
Gas benchmarks ✅ Pass Within acceptable limits

Testnet Validation

Contract Deployment Functionality Events Notes
remittance_split ✅ ✅ ✅ Fully validated
savings_goals ✅ ✅ ✅ Fully validated
bill_payments ✅ ✅ ✅ Fully validated
insurance ✅ ✅ ✅ Fully validated
family_wallet ✅ ✅ ✅ Fully validated
reporting ✅ ✅ ✅ Fully validated
orchestrator ✅ ✅ ✅ Fully validated

Gas Cost Analysis

SDK 21.0.0 Benchmarks

Operation CPU Instructions Memory Bytes Status
initialize_split ~500K ~2KB ✅ Optimal
calculate_split ~300K ~1KB ✅ Optimal
create_goal ~600K ~3KB ✅ Optimal
add_to_goal ~400K ~2KB ✅ Optimal
create_bill ~550K ~3KB ✅ Optimal
pay_bill ~450K ~2KB ✅ Optimal
create_policy ~600K ~3KB ✅ Optimal
pay_premium ~400K ~2KB ✅ Optimal

Baseline: Established with SDK 21.0.0
Threshold: ±10% acceptable variance

Known Limitations

SDK 21.0.0

  1. Storage Limits: Standard Soroban storage limits apply

    • Max entry size: 64KB
    • TTL management required for long-term storage

  2. Cross-Contract Calls: Limited call depth

    • Max depth: 4 levels
    • Orchestrator designed within limits

  3. Event Size: Events have size limitations

    • Keep event data concise
    • Use references for large data

Protocol 20

  1. Network Limits: Standard network resource limits
    • Transaction size limits
    • Ledger entry limits
    • CPU/memory budgets

Upgrade Path

From SDK 20.x to 21.0.0

Difficulty: Easy
Breaking Changes: None
Estimated Time: 1-2 hours

Steps:

  1. Update Cargo.toml dependencies
  2. Run cargo update
  3. Run full test suite
  4. Deploy to testnet for validation
  5. Update documentation

See UPGRADE_GUIDE.md for detailed instructions.

Future Upgrades (SDK 22.0.0+)

Status: Not yet available

Preparation:

  • Monitor Soroban SDK releases
  • Review release notes for breaking changes
  • Test with release candidates when available
  • Follow upgrade guide procedures

Validation Checklist

When validating a new Soroban version:

  • Review release notes and breaking changes
  • Update all Cargo.toml files
  • Update Soroban CLI
  • Run cargo clean and rebuild
  • Run full unit test suite
  • Run gas benchmarks and compare
  • Deploy to testnet
  • Test all contract functions
  • Verify event emission
  • Test cross-contract calls
  • Validate storage operations
  • Check TTL management
  • Monitor for 7 days on testnet
  • Update documentation
  • Plan mainnet deployment

Support and Resources

Official Resources

Community

Issue Reporting

If you encounter compatibility issues:

  1. Check this document for known issues
  2. Review GitHub Issues
  3. Test with minimal reproduction case
  4. Report with full version details

Maintenance

This document is maintained alongside contract releases.

Last Updated: 2024
Next Review: Upon next SDK release
Maintainer: RemitWise Development Team

Legend:

  • ✅ Tested and working
  • ⚠️ Untested or requires attention
  • ❌ Known issues or incompatible
  • 🔄 In progress