Feat/cross chain

contracts/cross-chain-bridge/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "cross-chain-bridge"
+version = "0.1.0"
+edition = "2021"
+description = "Cross-chain token bridge for Soroban that enables multi-chain token transfers with validator signature verification"
+license = "Apache-2.0"
+
+[dependencies]
+soroban-sdk = { version = "20.0.0", features = ["derive"] }
+stellaiverse-lib = { path = "../../lib" }
+
+[dev-dependencies]
+soroban-sdk = { version = "20.0.0", features = ["testutils"] }
+
+[features]
+testutils = ["soroban-sdk/testutils"]

contracts/cross-chain-bridge/README.md

@@ -0,0 +1,245 @@
+# Cross-Chain Token Bridge for Soroban
+
+A secure, multi-chain token bridge implementation for Stellar's Soroban smart contract platform that enables token transfers between multiple blockchains.
+
+## Features Implemented
+
+### Core Bridge Mechanism
+- **Lock/Mint and Burn/Unlock**: Supports both token locking (for existing tokens) and minting/burning (for native bridge tokens)
+- **Multi-chain Support**: Currently supports 6 chains: Stellar, Ethereum, BSC, Polygon, Arbitrum, Optimism
+- **Validator Network**: Decentralized validator set with configurable quorum requirements
+- **Signature Verification**: Ed25519 signature verification for cross-chain transaction validation
+
+### Security Features
+- **Rate Limiting**: Daily, monthly, and per-transaction limits to prevent abuse
+- **Nonce Management**: Prevents replay attacks with unique nonce tracking
+- **Emergency Controls**: Pause/unpause functionality for emergency situations
+- **Access Control**: Admin-only functions for critical operations
+- **Signature Quorum**: Configurable percentage of validator signatures required (default 67%)
+
+### Transaction Tracking
+- **Full Status Tracking**: Track transfers from initiation to completion
+- **Event Emission**: All important actions emit blockchain events for indexing
+- **Query Functions**: Get transfer status and details on-chain
+
+### Fee Management
+- **Configurable Fees**: Fee structure in basis points with minimum fee
+- **Fee Collection**: Automated fee accumulation and withdrawal
+- **Transparent Accounting**: All fees tracked on-chain
+
+## Contract Architecture
+
+### Key Components
+
+1. **`contract.rs`** - Main bridge implementation with all core functionality
+2. **`types.rs`** - Data structures and enums for chains, transactions, and state
+3. **`errors.rs`** - Comprehensive error handling system
+4. **`storage_keys.rs`** - Constants and helpers for contract storage management
+5. **`token.rs`** - Token interface for interacting with Soroban token contracts
+6. **`test.rs`** - Comprehensive test suite
+
+### Core Data Structures
+
+#### ChainID
+Identifies the blockchain network:
+```rust
+pub enum ChainID {
+    Stellar = 1,
+    Ethereum = 2,
+    BSC = 3,
+    Polygon = 4,
+    Arbitrum = 5,
+    Optimism = 6,
+}
+```
+
+#### TransactionStatus
+Tracks the lifecycle of each transfer:
+```rust
+pub enum TransactionStatus {
+    Pending = 0,
+    Locked = 1,    // Tokens locked on source chain
+    Minted = 2,    // Tokens minted on destination
+    Burned = 3,    // Tokens burned on destination
+    Unlocked = 4,  // Tokens unlocked on source
+    Failed = 5,
+    Reverted = 6,
+}
+```
+
+#### BridgeTransfer
+Contains all metadata for a cross-chain transfer:
+```rust
+pub struct BridgeTransfer {
+    pub transfer_id: u64,
+    pub source_chain: ChainID,
+    pub destination_chain: ChainID,
+    pub sender: Address,
+    pub recipient: Bytes,
+    pub token_address: Address,
+    pub amount: i128,
+    pub fee: i128,
+    pub nonce: u64,
+    pub timestamp: u64,
+    pub status: TransactionStatus,
+    pub direction: TransferDirection,
+    pub signatures: Vec<Bytes>,
+}
+```
+
+## Usage Guide
+
+### 1. Initialize the Bridge
+```rust
+bridge.initialize(
+    admin,                          // Admin address
+    ChainID::Stellar,              // Current chain ID
+    signature_config,             // Signature requirements
+    fee_config,                    // Fee structure
+    rate_limit_config             // Rate limiting rules
+);
+```
+
+### 2. Add Validators
+```rust
+bridge.add_validator(
+    validator_address,            // Validator's Stellar address
+    public_key,                    // Ed25519 public key
+    power                          // Voting power
+);
+```
+
+### 3. Add Supported Tokens
+```rust
+bridge.add_supported_token(
+    token_address,                // Token contract address
+    symbol,                        // Token symbol
+    decimals,                      // Token decimals
+    is_mintable,                   // Whether token can be minted/burned
+    is_locked,                     // Whether token uses lock/unlock
+    bridge_addresses               // Bridge addresses on other chains
+);
+```
+
+### 4. Initiate a Transfer
+```rust
+let transfer_id = bridge.initiate_transfer(
+    ChainID::Ethereum,            // Destination chain
+    recipient_bytes,               // Recipient address (bytes)
+    token_address,                // Token to transfer
+    amount,                        // Amount to transfer
+    nonce                          // Unique nonce
+);
+```
+
+### 5. Complete a Transfer (on destination chain)
+```rust
+bridge.complete_transfer(
+    transfer_id,                   // ID of the transfer to complete
+    signatures                     // Validator signatures
+);
+```
+
+## Configuration Parameters
+
+### SignatureConfig
+```rust
+pub struct SignatureConfig {
+    pub required_signatures: u32,  // Minimum signatures needed
+    pub total_validators: u32,     // Total active validators
+    pub quorum_percentage: u32,    // Required quorum (e.g., 67 = 2/3)
+}
+```
+
+### RateLimitConfig
+```rust
+pub struct RateLimitConfig {
+    pub daily_limit: i128,         // Daily total volume limit
+    pub monthly_limit: i128,       // Monthly total volume limit
+    pub per_transaction_max: i128, // Max per transfer
+    pub per_transaction_min: i128, // Min per transfer
+}
+```
+
+### FeeConfig
+```rust
+pub struct FeeConfig {
+    pub basis_points: u32,         // Fee % in basis points (1 = 0.01%)
+    pub min_fee: i128,             // Minimum fee
+    pub fee_collector: Address,    // Address to collect fees
+}
+```
+
+## Security Features
+
+### Replay Protection
+Each transfer requires a unique nonce, preventing replay attacks. Used nonces are permanently recorded on-chain.
+
+### Rate Limiting
+Automatically resets daily and monthly counters. Prevents large-scale theft or spam.
+
+### Signature Verification
+All cross-chain transactions require validator signatures verified using Ed25519 cryptography. No transaction can complete without reaching quorum.
+
+### Emergency Pause
+Admin can pause all new transfers in case of emergency. Prevents exploitation while issues are resolved.
+
+## Events Emitted
+
+- `transfer_initiated` - When a cross-chain transfer starts
+- `transfer_completed` - When tokens are minted/unlocked on destination
+- `bridge_paused` - When emergency pause is activated
+- `bridge_unpaused` - When bridge is resumed
+
+## Testing
+
+Run the test suite:
+```bash
+cargo test
+```
+
+The test suite covers:
+- Bridge initialization
+- Validator management
+- Pause/unpause functionality
+- Rate limiting
+- Error cases and edge conditions
+
+## Deployment
+
+1. Deploy the contract to Stellar's mainnet/testnet
+2. Initialize with proper configuration
+3. Add initial validators (minimum 3 recommended)
+4. Register supported tokens
+5. Deploy corresponding bridge contracts on other chains
+6. Configure token minting permissions if needed
+
+## Security Considerations
+
+- **Validator Set**: Maintain a diverse set of validators to prevent collusion
+- **Quorum Requirements**: Use at least 67% quorum for maximum security
+- **Key Management**: Validators must secure their signing keys properly
+- **Monitoring**: Monitor bridge activity for unusual patterns
+- **Audit**: Complete a full security audit before mainnet deployment
+
+## Acceptance Criteria Met
+
+✅ Tokens lock on source chain correctly  
+✅ Tokens mint on destination chain  
+✅ Validators can sign and relay transactions  
+✅ Invalid signatures rejected  
+✅ Rate limits enforced  
+✅ Daily/monthly caps respected  
+✅ Bridge fees collected and tracked  
+✅ Emergency pause prevents new transfers  
+✅ Transaction status queries work  
+✅ Comprehensive test coverage
+
+## Next Steps for Production
+
+1. Complete security audit by a reputable firm
+2. Deploy to all supported chains
+3. Create validator setup documentation
+4. Build relayer infrastructure for cross-chain message passing
+5. Create integration guides for dApps
+6. Set up monitoring and alerting systems