Skip to content

STELLAR_MIGRATION_NOTES.md

Latest commit

 

History

History
134 lines (105 loc) · 7.19 KB

STELLAR_MIGRATION_NOTES.md

File metadata and controls

134 lines (105 loc) · 7.19 KB
Raw

Stellar/Soroban Migration Notes

Overview

LumenPulse has undergone a strategic migration from prior chain-specific assumptions to a Stellar-first architecture leveraging Soroban smart contracts. This document provides clarity on what has changed, what has been migrated, and what legacy elements remain to ensure contributors can align new work with the platform's current direction.

What Changed: From Prior Chain Assumptions to Stellar/Soroban

Prior Assumptions (Pre-Migration)

The platform was initially conceptualized with EVM (Ethereum Virtual Machine) patterns in mind, including:

  • Gas Model: Assumed variable gas costs, gas limits, and gas optimization strategies typical of EVM chains
  • Reentrancy Protection: Expected reentrancy attacks via callback patterns common in Solidity
  • Storage Patterns: Persistent storage with direct key-value access, similar to EVM's storage slots
  • Contract Interactions: Cross-contract calls with potential for reentrancy and state inconsistencies
  • Token Standards: ERC-20/ERC-721 like interfaces and behaviors
  • Event Logging: EVM-style event emission for off-chain indexing
  • Upgrade Patterns: Proxy patterns and delegate calls for upgradability

Current Stellar/Soroban Architecture

The migration shifted to Soroban-specific patterns:

  • Resource Fees: Stellar's fixed fee structure (base fee + resource fee) instead of gas auctions
  • Storage Model: Instance, persistent, and temporary storage tiers with different costs and lifetimes
  • Contract Calls: Host functions for cross-contract interactions with built-in safety
  • Token Interface: SEP-41 token standard adapted for Soroban
  • Events: Soroban event system with structured data
  • Upgradability: WASM deployment updates with migration functions for state compatibility

What Has Been Migrated

✅ Completed Migrations

Smart Contracts (apps/onchain/contracts/)

  • All contracts rewritten in Rust/Soroban: lumen_token, crowdfund_vault, contributor_registry, matching_pool, vesting_wallet, etc.
  • Reentrancy Protection: Implemented Soroban-specific guard using instance storage
  • Token Standard: Migrated to SEP-41 compliant token with Soroban host functions
  • Event System: Converted to Soroban events with proper data structures
  • Storage Optimization: Leveraged Soroban's storage tiers (instance for contract state, persistent for user data)
  • Cross-Contract Calls: Updated to use Soroban host functions instead of direct calls

Backend Integration (apps/backend/)

  • SDK Migration: Replaced EVM SDKs with Stellar SDK (JavaScript)
  • Transaction Building: Updated to Stellar transaction format and Soroban invocations
  • Wallet Integration: Adapted to Freighter/Albedo wallets instead of MetaMask
  • Event Monitoring: Switched to Stellar Horizon API and Soroban events

Data Processing (apps/data-processing/)

  • On-Chain Data: Updated to fetch from Stellar network instead of EVM chains
  • Asset Tracking: Modified to handle XLM and Soroban tokens
  • Price Feeds: Adapted to Stellar-based price sources

Mobile/Web Apps

  • Wallet Connection: Integrated Stellar wallets (Freighter)
  • Transaction Signing: Updated for Stellar transaction envelopes
  • Asset Display: Shows XLM and Stellar-based assets

Deployment and Tooling

  • Build System: Migrated from Hardhat/Truffle to Soroban CLI and Rust toolchain
  • Testing: Converted to Soroban test framework
  • Deployment Scripts: Updated for Stellar network deployment

Active Gaps and Legacy Cleanup Needed

🔄 Legacy Terminology and Naming

  • File References: Some documentation still references "Ethereum" or "EVM" in examples (acceptable for crypto context)
  • Variable Names: Occasional use of EVM-inspired naming like "gas" in comments (should be updated to "fees")
  • Error Messages: Some error codes still use EVM-style terminology

🔄 Deprecated Integration Patterns

  • Direct Contract Calls: Any remaining direct contract invocation patterns should use Soroban host functions
  • Storage Assumptions: Code assuming unlimited storage should be reviewed for Soroban's storage costs
  • Event Handling: Legacy event parsing that assumes EVM log formats

🔄 Documentation Updates Needed

  • Architecture Diagrams: Update any diagrams showing EVM-style patterns
  • API Examples: Replace EVM transaction examples with Stellar equivalents
  • Contributing Guides: Ensure all examples use Soroban/Rust patterns

🔄 Testing and Validation

  • Reentrancy Tests: Ensure all tests validate Soroban-specific reentrancy protection
  • Gas/Fee Tests: Update tests to validate Stellar fee structures
  • Cross-Chain Assumptions: Remove any tests assuming multi-chain deployments

Contributor Guidance for New Work

✅ Stellar-First Principles

  1. Always use Soroban patterns: New contracts must be written in Rust using soroban-sdk
  2. Leverage Stellar features: Take advantage of Stellar's speed, low fees, and built-in compliance
  3. Follow SEP standards: Use Stellar Ecosystem Proposals for tokens, NFTs, etc.
  4. Optimize for fees: Design contracts considering Stellar's resource fees

✅ Code Standards

  • Storage: Use appropriate storage tiers (instance for config, persistent for user data, temporary for caches)
  • Events: Emit structured events for off-chain monitoring
  • Auth: Use Soroban's require_auth() for authorization
  • Cross-contract: Use host functions for safe contract interactions

✅ Documentation Requirements

  • Contract Interfaces: Document all public functions, events, and storage layouts
  • Migration Notes: For any contract updates, document storage compatibility
  • Fee Estimates: Include resource fee considerations in design docs

✅ Testing Standards

  • Unit Tests: Test all functions with Soroban test framework
  • Integration Tests: Validate cross-contract interactions
  • Fee Testing: Ensure operations stay within reasonable fee bounds

🚫 Avoid These Patterns

  • EVM-style reentrancy assumptions (Soroban has different attack vectors)
  • Gas optimization micro-patterns (Stellar fees are predictable)
  • Direct storage manipulation (use Soroban storage APIs)
  • Callback-based patterns (use host functions)

Migration Timeline

  • Phase 1 (Completed): Core contract rewrite in Soroban
  • Phase 2 (Completed): Backend and API integration updates
  • Phase 3 (Completed): Frontend wallet and transaction updates
  • Phase 4 (Ongoing): Documentation and legacy cleanup
  • Phase 5 (Future): Advanced Soroban features adoption

Resources

Questions?

If you encounter unclear migration artifacts or need guidance on Stellar/Soroban patterns, please:

  1. Check existing documentation first
  2. Open an issue with the migration label
  3. Reference this document in your PR descriptions c:\Users\SWAYY\Downloads\Lumenpulse\document\STELLAR_MIGRATION_NOTES.md