d-bis/smom-dbis-138
4
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity
Files
50ab378da90d1cf5e847ed3ff2e991fba21fa2e9
smom-dbis-138/docs/bridge/trustless/ENV_VARIABLES_REFERENCE.md
defiQUG 50ab378da9 feat: Implement Universal Cross-Chain Asset Hub - All phases complete 
PRODUCTION-GRADE IMPLEMENTATION - All 7 Phases Done

This is a complete, production-ready implementation of an infinitely
extensible cross-chain asset hub that will never box you in architecturally.

## Implementation Summary

### Phase 1: Foundation ✅
- UniversalAssetRegistry: 10+ asset types with governance
- Asset Type Handlers: ERC20, GRU, ISO4217W, Security, Commodity
- GovernanceController: Hybrid timelock (1-7 days)
- TokenlistGovernanceSync: Auto-sync tokenlist.json

### Phase 2: Bridge Infrastructure ✅
- UniversalCCIPBridge: Main bridge (258 lines)
- GRUCCIPBridge: GRU layer conversions
- ISO4217WCCIPBridge: eMoney/CBDC compliance
- SecurityCCIPBridge: Accredited investor checks
- CommodityCCIPBridge: Certificate validation
- BridgeOrchestrator: Asset-type routing

### Phase 3: Liquidity Integration ✅
- LiquidityManager: Multi-provider orchestration
- DODOPMMProvider: DODO PMM wrapper
- PoolManager: Auto-pool creation

### Phase 4: Extensibility ✅
- PluginRegistry: Pluggable components
- ProxyFactory: UUPS/Beacon proxy deployment
- ConfigurationRegistry: Zero hardcoded addresses
- BridgeModuleRegistry: Pre/post hooks

### Phase 5: Vault Integration ✅
- VaultBridgeAdapter: Vault-bridge interface
- BridgeVaultExtension: Operation tracking

### Phase 6: Testing & Security ✅
- Integration tests: Full flows
- Security tests: Access control, reentrancy
- Fuzzing tests: Edge cases
- Audit preparation: AUDIT_SCOPE.md

### Phase 7: Documentation & Deployment ✅
- System architecture documentation
- Developer guides (adding new assets)
- Deployment scripts (5 phases)
- Deployment checklist

## Extensibility (Never Box In)

7 mechanisms to prevent architectural lock-in:
1. Plugin Architecture - Add asset types without core changes
2. Upgradeable Contracts - UUPS proxies
3. Registry-Based Config - No hardcoded addresses
4. Modular Bridges - Asset-specific contracts
5. Composable Compliance - Stackable modules
6. Multi-Source Liquidity - Pluggable providers
7. Event-Driven - Loose coupling

## Statistics

- Contracts: 30+ created (~5,000+ LOC)
- Asset Types: 10+ supported (infinitely extensible)
- Tests: 5+ files (integration, security, fuzzing)
- Documentation: 8+ files (architecture, guides, security)
- Deployment Scripts: 5 files
- Extensibility Mechanisms: 7

## Result

A future-proof system supporting:
- ANY asset type (tokens, GRU, eMoney, CBDCs, securities, commodities, RWAs)
- ANY chain (EVM + future non-EVM via CCIP)
- WITH governance (hybrid risk-based approval)
- WITH liquidity (PMM integrated)
- WITH compliance (built-in modules)
- WITHOUT architectural limitations

Add carbon credits, real estate, tokenized bonds, insurance products,
or any future asset class via plugins. No redesign ever needed.

Status: Ready for Testing → Audit → Production
2026-01-24 07:01:37 -08:00

7.5 KiB
Raw Blame History

Environment Variables Reference

Complete reference for all environment variables needed for the trustless bridge deployment.

Required Variables (Must Be Set)

Deployment Account

PRIVATE_KEY=0x...  # Deployer private key (NEVER commit to git)

RPC Endpoints

ETHEREUM_MAINNET_RPC=https://eth.llamarpc.com  # Ethereum Mainnet RPC URL
RPC_URL_138=http://chain138.example.com:8545    # ChainID 138 RPC URL

Etherscan Verification

ETHERSCAN_API_KEY=your_etherscan_api_key  # For contract verification

Contract Addresses (Populated During Deployment)

Core Bridge Contracts (ChainID 138)

LOCKBOX_138=0x...  # Lockbox contract address on ChainID 138

Core Bridge Contracts (Ethereum Mainnet)

BOND_MANAGER=0x...              # BondManager contract address
CHALLENGE_MANAGER=0x...         # ChallengeManager contract address
LIQUIDITY_POOL=0x...            # LiquidityPoolETH contract address
INBOX_ETH=0x...                 # InboxETH contract address
SWAP_ROUTER=0x...               # Basic SwapRouter contract address
BRIDGE_SWAP_COORDINATOR=0x...   # BridgeSwapCoordinator contract address

Enhanced Routing

ENHANCED_SWAP_ROUTER=0x...  # EnhancedSwapRouter contract address

Integration Contracts

STABLECOIN_PEG_MANAGER=0x...      # StablecoinPegManager contract address
COMMODITY_PEG_MANAGER=0x...       # CommodityPegManager contract address
ISO_CURRENCY_MANAGER=0x...        # ISOCurrencyManager contract address
BRIDGE_RESERVE_COORDINATOR=0x...  # BridgeReserveCoordinator contract address

Reserve System

RESERVE_SYSTEM=0x...  # ReserveSystem contract address (ChainID 138)
XAU_ADDRESS=0x...    # XAU token address (if tokenized)

Optional Configuration Variables

Bridge Configuration

BOND_MULTIPLIER_BPS=11000              # 110% (default)
MIN_BOND=1000000000000000000           # 1 ETH (default)
CHALLENGE_WINDOW_SECONDS=1800           # 30 minutes (default)
LP_FEE_BPS=5                           # 0.05% (default)
MIN_LIQUIDITY_RATIO_BPS=11000          # 110% (default)

Peg Configuration

USD_PEG_THRESHOLD_BPS=50                # 0.5% (default)
ETH_PEG_THRESHOLD_BPS=10                # 0.1% (default)
COMMODITY_PEG_THRESHOLD_BPS=100        # 1.0% (default)
MIN_RESERVE_RATIO_BPS=11000             # 110% (default)

Liquidity Configuration

LIQUIDITY_AMOUNT=100                    # ETH amount for initial liquidity (default: 100)
RESERVE_AMOUNT=100000                   # USDT amount for reserves (default: 100000)

Token Addresses (Ethereum Mainnet)

These are standard addresses and typically don't need to be changed:

WETH=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
USDT=0xdAC17F958D2ee523a2206206994597C13D831ec7
USDC=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
DAI=0x6B175474E89094C44Da98b954EedeAC495271d0F

DEX Protocol Addresses (Ethereum Mainnet)

These are standard addresses and typically don't need to be changed:

UNISWAP_V3_ROUTER=0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45
CURVE_3POOL=0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7
DODOEX_ROUTER=0xa356867fDCEa8e71AEaF87805808803806231FdC
BALANCER_VAULT=0xBA12222222228d8Ba445958a75a0704d566BF2C8
ONEINCH_ROUTER=0x1111111254EEB25477B68fb85Ed929f73A960582

Balancer Pool IDs (Configure After Deployment)

# BALANCER_WETH_USDT_POOL_ID=0x...
# BALANCER_WETH_USDC_POOL_ID=0x...
# Add more pool IDs as needed

Service Configuration

Market Reporting Service

MARKET_REPORTING_API_KEY=your_api_key_here  # API key for market reporting service

Service Ports (Optional - defaults provided)

# Liquidity Engine Service
LIQUIDITY_ENGINE_PORT=3000

# Market Reporting Service
MARKET_REPORTING_PORT=3001

# Bridge Reserve Service
BRIDGE_RESERVE_PORT=3002

# ISO Currency Service
ISO_CURRENCY_PORT=3003

Phase-by-Phase Requirements

Phase 1: Environment Setup

Required:

  • PRIVATE_KEY
  • ETHEREUM_MAINNET_RPC
  • RPC_URL_138
  • ETHERSCAN_API_KEY

Phase 2: Deploy Core Contracts

Required:

  • All Phase 1 variables

Populated After:

  • LOCKBOX_138 (ChainID 138)
  • BOND_MANAGER
  • CHALLENGE_MANAGER
  • LIQUIDITY_POOL
  • INBOX_ETH
  • SWAP_ROUTER
  • BRIDGE_SWAP_COORDINATOR

Phase 3: Deploy Enhanced Router

Required:

  • All Phase 1 variables
  • BRIDGE_SWAP_COORDINATOR (from Phase 2)

Populated After:

  • ENHANCED_SWAP_ROUTER

Phase 4: Deploy Integration Contracts

Required:

  • All Phase 1 variables
  • BRIDGE_SWAP_COORDINATOR (from Phase 2)
  • RESERVE_SYSTEM (must be set if deploying)

Populated After:

  • STABLECOIN_PEG_MANAGER
  • COMMODITY_PEG_MANAGER
  • ISO_CURRENCY_MANAGER
  • BRIDGE_RESERVE_COORDINATOR

Phase 5: Initialize System

Required:

  • All Phase 1 variables
  • ENHANCED_SWAP_ROUTER (from Phase 3)
  • BRIDGE_SWAP_COORDINATOR (from Phase 2)

Phase 6: Provide Liquidity

Required:

  • All Phase 1 variables
  • LIQUIDITY_POOL (from Phase 2)
  • RESERVE_SYSTEM (must be set)

Optional:

  • LIQUIDITY_AMOUNT (default: 100)
  • RESERVE_AMOUNT (default: 100000)

Phase 7: Configure Access Control

Required:

  • All Phase 1 variables
  • ENHANCED_SWAP_ROUTER (from Phase 3)
  • BRIDGE_SWAP_COORDINATOR (from Phase 2)

Phase 8: Deploy Backend Services

Required:

  • All Phase 1 variables
  • Contract addresses from previous phases

Service-Specific:

  • MARKET_REPORTING_API_KEY (for Market Reporting Service)

Phase 9: Deploy Frontend

Required:

  • Contract addresses from previous phases (for frontend configuration)

Phase 10: Verification

Required:

  • All contract addresses from previous phases

Validation Checklist

Before starting deployment, ensure:

  • PRIVATE_KEY is set and valid
  • ETHEREUM_MAINNET_RPC is accessible
  • RPC_URL_138 is accessible (or will be)
  • ETHERSCAN_API_KEY is valid
  • Deployer has sufficient ETH (5-10 ETH recommended)
  • RESERVE_SYSTEM address is known (if deploying integration contracts)

Security Notes

  1. Never commit .env file to version control
  2. Use .env.template as a reference
  3. Store private keys securely - use hardware wallets for production
  4. Rotate API keys regularly
  5. Use environment-specific values for different networks (testnet vs mainnet)

Example .env File

# Deployment Account
PRIVATE_KEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

# RPC Endpoints
ETHEREUM_MAINNET_RPC=https://eth.llamarpc.com
RPC_URL_138=http://chain138.example.com:8545

# Etherscan Verification
ETHERSCAN_API_KEY=ABC123XYZ789

# Reserve System
RESERVE_SYSTEM=0x1111111111111111111111111111111111111111
XAU_ADDRESS=0x2222222222222222222222222222222222222222

# Contract Addresses (populated during deployment)
LOCKBOX_138=
BOND_MANAGER=
CHALLENGE_MANAGER=
LIQUIDITY_POOL=
INBOX_ETH=
SWAP_ROUTER=
BRIDGE_SWAP_COORDINATOR=
ENHANCED_SWAP_ROUTER=
STABLECOIN_PEG_MANAGER=
COMMODITY_PEG_MANAGER=
ISO_CURRENCY_MANAGER=
BRIDGE_RESERVE_COORDINATOR=

# Service Configuration
MARKET_REPORTING_API_KEY=your_api_key_here

Troubleshooting

Variable Not Found

  • Check .env file exists
  • Verify variable name spelling
  • Ensure no extra spaces around =
  • Check for comments (lines starting with #)

Variable Not Set

  • Run phase1-env-setup.sh to verify
  • Check script output for missing variables
  • Review this reference for required variables

Contract Address Not Found

  • Ensure previous phase completed successfully
  • Check deployment output for addresses
  • Verify addresses are saved to .env
Reference in New Issue View Git Blame Copy Permalink