Master List: Bridges, Contracts, Routers, Oracles, Mappers & Infrastructure
A single reference for all bridges, core contracts, routers, oracles, mappers, registries, and related infrastructure in the smom-dbis-138 repo. Use this for deployment checklists, .env setup, and architecture overview.
See also: STATUS_AND_TOKEN_ROUTING.md for current status of all components, token-aggregation API (all endpoints), token routing (quote, pools, bridge, token-mapping), and multihop routing (on-chain vs API; swap+bridge+swap).
1. Bridges
1.1 CCIP (Chainlink Cross-Chain Interoperability)
| Contract |
Path |
Purpose |
| CCIPWETH9Bridge |
contracts/ccip/CCIPWETH9Bridge.sol |
Cross-chain bridge for WETH9 via CCIP. Source/destination chains (e.g. Chain 138 ↔ Ethereum). |
| CCIPWETH10Bridge |
contracts/ccip/CCIPWETH10Bridge.sol |
Cross-chain bridge for WETH10 via CCIP. |
| UniversalCCIPBridge |
contracts/bridge/UniversalCCIPBridge.sol |
Base CCIP bridge logic; extended by token-specific bridges. |
| GRUCCIPBridge |
contracts/bridge/GRUCCIPBridge.sol |
CCIP bridge for GRU (Global Reserve Unit) tokens. |
| ISO4217WCCIPBridge |
contracts/bridge/ISO4217WCCIPBridge.sol |
CCIP bridge for ISO-4217 W tokens. |
| CommodityCCIPBridge |
contracts/bridge/CommodityCCIPBridge.sol |
CCIP bridge for commodity-backed tokens. |
Typical .env: CCIP_ROUTER, CCIPWETH9_BRIDGE_*, CCIPWETH10_BRIDGE_*, *_SELECTOR, LINK_TOKEN, per chain.
1.2 Trustless Bridge (Chain 138 ↔ Ethereum)
| Contract |
Path |
Purpose |
| Lockbox138 |
contracts/bridge/trustless/Lockbox138.sol |
On Chain 138: locks assets; initiates claims to Ethereum. |
| InboxETH |
contracts/bridge/trustless/InboxETH.sol |
On Ethereum: receives claims; relayer posts bond and releases to recipient. |
| BondManager |
contracts/bridge/trustless/BondManager.sol |
Holds relayer bonds; releases on finalization or pays challenger on dispute. |
| ChallengeManager |
contracts/bridge/trustless/ChallengeManager.sol |
Dispute window and resolution for claims. |
| LiquidityPoolETH |
contracts/bridge/trustless/LiquidityPoolETH.sol |
ETH/WETH liquidity pool for payouts and deposits. |
| SwapBridgeSwapCoordinator |
contracts/bridge/trustless/SwapBridgeSwapCoordinator.sol |
Coordinates swap → bridge → swap flows. |
Typical .env: LOCKBOX_138, BOND_MANAGER, CHALLENGE_MANAGER, LIQUIDITY_POOL, INBOX_ETH, SWAP_ROUTER, BRIDGE_SWAP_COORDINATOR, RESERVE_SYSTEM.
1.3 Other Bridge / Interop
| Contract |
Path |
Purpose |
| AlltraCustomBridge |
contracts/bridge/AlltraCustomBridge.sol |
Alltra transport for custom bridge messaging. |
| EtherlinkRelayReceiver |
contracts/bridge/EtherlinkRelayReceiver.sol |
Receives relayed messages (e.g. Etherlink). |
| BridgeRegistry |
contracts/bridge/interop/BridgeRegistry.sol |
Registry of tokens and routes for bridge operations. |
| BridgeEscrowVault |
contracts/bridge/interop/BridgeEscrowVault.sol |
Escrow for bridge-in/bridge-out flows. |
| BridgeVerifier |
contracts/bridge/interop/BridgeVerifier.sol |
Verification of bridge messages (e.g. EIP-712). |
| MintBurnController |
contracts/bridge/interop/MintBurnController.sol |
Mint/burn control for bridged tokens. |
| VaultBridgeAdapter |
contracts/bridge/VaultBridgeAdapter.sol |
Adapter for vault ↔ bridge. |
| BridgeOrchestrator |
contracts/bridge/BridgeOrchestrator.sol |
Orchestrates multi-bridge flows. |
2. Routers
| Contract |
Path |
Purpose |
| CCIP Router (external) |
Chainlink-provided |
Entry point for CCIP; bridges call ccipSend / receive via router. .env: CCIP_*_ROUTER, ORACLE_AGGREGATOR_ADDRESS (for some scripts). |
| SwapRouter |
contracts/bridge/trustless/SwapRouter.sol |
Basic swap router (trustless bridge context). |
| EnhancedSwapRouter |
contracts/bridge/trustless/EnhancedSwapRouter.sol |
Aggregates Uniswap V3, Dodoex, Curve, Balancer, 1inch for swap+bridge+swap. |
| CCIPRouter |
contracts/ccip/CCIPRouter.sol |
Optional custom router logic (project-specific). |
| CCIPRouterOptimized |
contracts/ccip/CCIPRouterOptimized.sol |
Optimized fee/router variant. |
Typical .env: SWAP_ROUTER, ENHANCED_SWAP_ROUTER, UNISWAP_V3_ROUTER, DODOEX_ROUTER, CURVE_3POOL, BALANCER_VAULT, ONEINCH_ROUTER.
3. Oracles
| Contract |
Path |
Purpose |
| XAUOracle |
contracts/vault/XAUOracle.sol |
ETH/XAU (gold) price for vault/Ledger; multi-feed aggregation, liquidation price. |
| ReserveSystem (price) |
contracts/reserve/ReserveSystem.sol |
Holds asset prices (from OraclePriceFeed); getPrice(asset), getConversionPrice(). Used by PMM (getPoolPriceOrOracle) and peg managers. |
| OraclePriceFeed |
contracts/reserve/OraclePriceFeed.sol |
Pushes Chainlink-style aggregator data into ReserveSystem. |
| PriceFeedKeeper |
contracts/reserve/PriceFeedKeeper.sol |
Keeper that triggers price feed updates on a schedule. |
| ReserveOracle |
contracts/iso4217w/oracle/ReserveOracle.sol |
Quorum-based reserve verification for ISO-4217 W mint/burn. |
| Aggregator |
contracts/oracle/Aggregator.sol |
Chainlink-compatible price aggregator (on-chain). |
| Proxy |
contracts/oracle/Proxy.sol |
Oracle proxy (consumer-facing). |
| OracleWithCCIP |
contracts/oracle/OracleWithCCIP.sol |
Oracle that uses CCIP for cross-chain data. |
| PMMPriceProvider |
contracts/vault/adapters/PMMPriceProvider.sol |
Returns asset price in quote token from DODO PMM (oracle-backed when ReserveSystem set). |
Typical .env: ORACLE_AGGREGATOR_ADDRESS, ORACLE_PROXY_ADDRESS, RESERVE_SYSTEM, ORACLE_PRICE_FEED, RPC_URL_138. See docs/integration/ORACLE_AND_KEEPER_CHAIN138.md.
4. Mappers & Address Mapping
| Contract |
Path |
Purpose |
| AddressMapper |
contracts/utils/AddressMapper.sol |
On Chain 138: maps genesis (CREATE2) addresses to deployed addresses for cross-chain consistency. |
| AddressMapperEmpty |
contracts/utils/AddressMapperEmpty.sol |
On other chains: same interface, no mappings; used where no 138-style mapping is needed. |
Deploy: script/DeployAddressMapper.s.sol (138), script/DeployAddressMapperOtherChain.s.sol (others). .env: populated after deploy; scripts use ADDRESS_MAPPER_* or equivalent per chain.
5. Registries & Factories
| Contract |
Path |
Purpose |
| ChainRegistry |
contracts/registry/ChainRegistry.sol |
Registry of chains and chain-specific config. |
| UniversalAssetRegistry |
contracts/registry/UniversalAssetRegistry.sol |
Registry of asset types and handlers (GRU, ISO4217W, Commodity, etc.). |
| GRUHandler |
contracts/registry/handlers/GRUHandler.sol |
Asset type handler for GRU. |
| ISO4217WHandler |
contracts/registry/handlers/ISO4217WHandler.sol |
Asset type handler for ISO-4217 W tokens. |
| CommodityHandler |
contracts/registry/handlers/CommodityHandler.sol |
Asset type handler for commodities. |
| ERC20Handler |
contracts/registry/handlers/ERC20Handler.sol |
Generic ERC20 handler. |
| SecurityHandler |
contracts/registry/handlers/SecurityHandler.sol |
Security-type asset handler. |
| BridgeRegistry |
contracts/bridge/interop/BridgeRegistry.sol |
Registry of bridgeable tokens and routes. |
| BridgeModuleRegistry |
contracts/bridge/modules/BridgeModuleRegistry.sol |
Registry of bridge modules. |
| ConfigurationRegistry |
contracts/config/ConfigurationRegistry.sol |
System configuration registry. |
| PluginRegistry |
contracts/plugins/PluginRegistry.sol |
Plugin registration. |
| MirrorRegistry |
contracts/mirror/MirrorRegistry.sol |
Mirror/duplicate contract registry. |
| PrivatePoolRegistry |
contracts/dex/PrivatePoolRegistry.sol |
Registry of private (e.g. XAU-anchored) DODO pools. |
| VaultFactory |
contracts/vault/VaultFactory.sol |
Creates Vault instances and associated tokens. |
| TokenFactory (ISO4217W) |
contracts/iso4217w/TokenFactory.sol |
Creates ISO-4217 W tokens. |
| TokenRegistry (ISO4217W) |
contracts/iso4217w/registry/TokenRegistry.sol |
Registry of W tokens by currency code. |
| TokenRegistry (tokenization) |
contracts/tokenization/TokenRegistry.sol |
Generic token registry. |
| ProxyFactory |
contracts/upgrades/ProxyFactory.sol |
Creates upgradeable proxies. |
6. Reserve System
| Contract |
Path |
Purpose |
| ReserveSystem |
contracts/reserve/ReserveSystem.sol |
Core reserve accounting; price feeds; conversions; redemptions. |
| OraclePriceFeed |
contracts/reserve/OraclePriceFeed.sol |
Feeds prices from aggregators into ReserveSystem. |
| PriceFeedKeeper |
contracts/reserve/PriceFeedKeeper.sol |
Keeper for periodic price updates. |
| MockPriceFeed |
contracts/reserve/MockPriceFeed.sol |
Test/mock price feed. |
| ReserveTokenIntegration |
contracts/reserve/ReserveTokenIntegration.sol |
Token integration with reserve. |
| StablecoinReserveVault |
contracts/reserve/StablecoinReserveVault.sol |
Vault for stablecoin reserves. |
Typical .env: RESERVE_SYSTEM, ORACLE_PRICE_FEED, XAU_ADDRESS, RESERVE_KEEPER.
7. Vault System (GRU Smart Vault)
| Contract |
Path |
Purpose |
| Ledger |
contracts/vault/Ledger.sol |
Single source of truth: collateral, debt, risk params; uses XAUOracle for valuation. |
| Vault |
contracts/vault/Vault.sol |
User-facing vault: deposit, borrow, repay, withdraw. |
| VaultFactory |
contracts/vault/VaultFactory.sol |
Deploys Vaults and deposit/debt tokens. |
| XAUOracle |
contracts/vault/XAUOracle.sol |
ETH/XAU price for Ledger. |
| RegulatedEntityRegistry |
contracts/vault/RegulatedEntityRegistry.sol |
Regulated entities and authorized wallets. |
| CollateralAdapter |
contracts/vault/adapters/CollateralAdapter.sol |
Deposits/withdrawals and liquidation seizure. |
| eMoneyJoin |
contracts/vault/adapters/eMoneyJoin.sol |
Join/exit for eMoney (mint/burn). |
| RateAccrual |
contracts/vault/RateAccrual.sol |
Interest accrual for debt. |
| Liquidation |
contracts/vault/Liquidation.sol |
Liquidation logic. |
| DepositToken |
contracts/vault/tokens/DepositToken.sol |
Receipt token for collateral. |
| DebtToken |
contracts/vault/tokens/DebtToken.sol |
Debt position token. |
| PMMPriceProvider |
contracts/vault/adapters/PMMPriceProvider.sol |
Optional PMM-based price for assets (vault/UI). |
| BridgeVaultExtension |
contracts/vault/BridgeVaultExtension.sol |
Vault extension for bridge flows. |
8. DEX & PMM (Liquidity)
| Contract |
Path |
Purpose |
| DODOPMMIntegration |
contracts/dex/DODOPMMIntegration.sol |
Creates and manages DODO PMM (DVM) pools; swaps cUSDT/cUSDC vs official USDT/USDC; optional ReserveSystem for oracle mid. |
| DODOPMMProvider |
contracts/liquidity/providers/DODOPMMProvider.sol |
ILiquidityProvider wrapper; uses getPoolPriceOrOracle for quotes. |
| PrivatePoolRegistry |
contracts/dex/PrivatePoolRegistry.sol |
Registry of private (e.g. XAU) pools. |
| LiquidityManager |
contracts/liquidity/LiquidityManager.sol |
Aggregates liquidity providers. |
| PoolManager |
contracts/liquidity/PoolManager.sol |
Pool management. |
| Stabilizer |
contracts/bridge/trustless/integration/Stabilizer.sol |
Uses private DODO PMM pools for peg stabilization. |
Typical .env: DODO_VENDING_MACHINE_ADDRESS, DODOPMM_INTEGRATION_ADDRESS, CHAIN_138_DODO_PMM_INTEGRATION (token-aggregation), OFFICIAL_USDT_ADDRESS, OFFICIAL_USDC_ADDRESS, COMPLIANT_USDT_ADDRESS, COMPLIANT_USDC_ADDRESS.
9. Trustless Bridge Integration (Peg & Reserve)
| Contract |
Path |
Purpose |
| StablecoinPegManager |
contracts/bridge/trustless/integration/StablecoinPegManager.sol |
Monitors and enforces USD/ETH peg via ReserveSystem. |
| CommodityPegManager |
contracts/bridge/trustless/integration/CommodityPegManager.sol |
Commodity (e.g. XAU) peg management. |
| ISOCurrencyManager |
contracts/bridge/trustless/integration/ISOCurrencyManager.sol |
ISO currency support for bridge. |
| BridgeReserveCoordinator |
contracts/bridge/trustless/integration/BridgeReserveCoordinator.sol |
Coordinates reserve system with bridge (peg, assets). |
Typical .env: STABLECOIN_PEG_MANAGER, COMMODITY_PEG_MANAGER, ISO_CURRENCY_MANAGER, BRIDGE_RESERVE_COORDINATOR, RESERVE_SYSTEM.
10. Tokenization & Compliance
| Contract |
Path |
Purpose |
| ISO4217WToken |
contracts/iso4217w/ISO4217WToken.sol |
ISO-4217 W wrapped currency (reserve-backed, m=1.0). |
| ComplianceGuard |
contracts/iso4217w/ComplianceGuard.sol |
Validates money multiplier, GRU isolation, reserve rules. |
| MintController |
contracts/iso4217w/controllers/MintController.sol |
Mint authority; uses ReserveOracle. |
| BurnController |
contracts/iso4217w/controllers/BurnController.sol |
Burn/redeem authority. |
| ReserveOracle |
contracts/iso4217w/oracle/ReserveOracle.sol |
Quorum reserve verification for W tokens. |
| CompliantFiatToken |
contracts/tokens/CompliantFiatToken.sol |
Compliant fiat-like token. |
| TokenizedEUR |
contracts/tokenization/TokenizedEUR.sol |
Tokenized EUR. |
| WTokenComplianceEnforcer |
contracts/bridge/integration/WTokenComplianceEnforcer.sol |
Enforces W-token compliance on bridge. |
| WTokenReserveVerifier |
contracts/bridge/integration/WTokenReserveVerifier.sol |
Verifies reserve for W tokens on bridge. |
| eMoneyPolicyEnforcer |
contracts/bridge/integration/eMoneyPolicyEnforcer.sol |
eMoney policy enforcement on bridge. |
11. Bridge Integration (Auto-Registration)
| Contract |
Path |
Purpose |
| WTokenBridgeIntegration |
contracts/bridge/integration/WTokenBridgeIntegration.sol |
Registers W tokens with BridgeRegistry on creation. |
| VaultBridgeIntegration |
contracts/bridge/integration/VaultBridgeIntegration.sol |
Registers vault deposit tokens with BridgeRegistry. |
| eMoneyBridgeIntegration |
contracts/bridge/integration/eMoneyBridgeIntegration.sol |
Registers eMoney tokens with BridgeRegistry. |
12. CCIP Integration & Relay
| Contract |
Path |
Purpose |
| CCIPLogger |
contracts/ccip-integration/CCIPLogger.sol |
Logs CCIP messages (receiver); onlyRouter. |
| IRouterClient |
contracts/ccip/IRouterClient.sol |
Interface for Chainlink CCIP router. |
Relay (off-chain + optional contracts): Relay Router + Relay Bridge on Ethereum; source chain 138 CCIP router. See services/relay/README.md, script/DeployCCIPRelay.s.sol. .env: RELAY_*, CCIP_ROUTER (138).
13. Chain Adapters (Multi-Chain)
| Contract |
Path |
Purpose |
| EVMAdapter |
contracts/bridge/adapters/evm/EVMAdapter.sol |
Generic EVM chain adapter. |
| XDCAdapter |
contracts/bridge/adapters/evm/XDCAdapter.sol |
XDC chain adapter. |
| AlltraAdapter |
contracts/bridge/adapters/evm/AlltraAdapter.sol |
Alltra chain adapter. |
| TezosAdapter |
contracts/bridge/adapters/non-evm/TezosAdapter.sol |
Tezos adapter. |
| CactiAdapter |
contracts/bridge/adapters/hyperledger/CactiAdapter.sol |
Hyperledger Cacti. |
| FabricAdapter |
contracts/bridge/adapters/hyperledger/FabricAdapter.sol |
Hyperledger Fabric. |
| FireflyAdapter |
contracts/bridge/adapters/hyperledger/FireflyAdapter.sol |
Hyperledger Firefly. |
| SolanaAdapter |
contracts/bridge/adapters/non-evm/SolanaAdapter.sol |
Solana. |
| XRPLAdapter |
contracts/bridge/adapters/non-evm/XRPLAdapter.sol |
XRPL. |
| TronAdapter |
contracts/bridge/adapters/non-evm/TronAdapter.sol |
Tron. |
| StellarAdapter |
contracts/bridge/adapters/non-evm/StellarAdapter.sol |
Stellar. |
| CosmosAdapter |
contracts/bridge/adapters/non-evm/CosmosAdapter.sol |
Cosmos. |
| HederaAdapter |
contracts/bridge/adapters/non-evm/HederaAdapter.sol |
Hedera. |
| AlgorandAdapter |
contracts/bridge/adapters/non-evm/AlgorandAdapter.sol |
Algorand. |
| TONAdapter |
contracts/bridge/adapters/non-evm/TONAdapter.sol |
TON. |
14. NFT & Misc Contracts
| Contract |
Path |
Purpose |
| GRUFormulasNFT |
contracts/nft/GRUFormulasNFT.sol |
ERC-721 with on-chain SVG for three GRU formulas (Money Supply, Velocity, Multiplier). |
| GovernanceController |
contracts/governance/GovernanceController.sol |
Governance control. |
| TokenlistGovernanceSync |
contracts/sync/TokenlistGovernanceSync.sol |
Sync token list with governance. |
| AccountWalletRegistryExtended |
contracts/smart-accounts/AccountWalletRegistryExtended.sol |
Account wallet registry. |
| IndyVerifier |
contracts/compliance/IndyVerifier.sol |
Indy-based verification. |
| wXRP |
contracts/bridge/interop/wXRP.sol |
Wrapped XRP. |
15. Environment Variables Summary (Key)
| Category |
Examples |
| Deploy / RPC |
PRIVATE_KEY, RPC_URL_138, ETHEREUM_MAINNET_RPC, ETHERSCAN_API_KEY |
| CCIP |
CCIP_ROUTER, CCIP_*_ROUTER, *_SELECTOR, LINK_TOKEN, CCIPWETH9_BRIDGE_*, CCIPWETH10_BRIDGE_* |
| Oracle |
ORACLE_AGGREGATOR_ADDRESS, ORACLE_PROXY_ADDRESS, RESERVE_SYSTEM, ORACLE_PRICE_FEED |
| Trustless |
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 |
| Reserve / Vault |
RESERVE_SYSTEM, XAU_ADDRESS, ORACLE_PRICE_FEED, RESERVE_KEEPER |
| PMM / DEX |
DODO_VENDING_MACHINE_ADDRESS, DODOPMM_INTEGRATION_ADDRESS, CHAIN_138_DODO_PMM_INTEGRATION, OFFICIAL_USDT_ADDRESS, OFFICIAL_USDC_ADDRESS, COMPLIANT_USDT_ADDRESS, COMPLIANT_USDC_ADDRESS |
| Mapper |
Set after deploy: AddressMapper (138), AddressMapperEmpty (others). |
16. Deployment Scripts (Selected)
| Script |
Purpose |
script/DeployAddressMapper.s.sol |
Deploy AddressMapper on Chain 138. |
script/DeployAddressMapperOtherChain.s.sol |
Deploy AddressMapperEmpty on other chains. |
script/DeployOracle.s.sol |
Deploy oracle (aggregator/proxy). |
script/DeployCCIPRouter.s.sol |
Deploy custom CCIP router (if used). |
script/DeployCCIPWETH9Bridge.s.sol |
Deploy CCIP WETH9 bridge. |
script/DeployCCIPRelay.s.sol |
Deploy relay router + bridge (Ethereum). |
script/DeployAll.s.sol |
Deploy CCIP bridges + WETH per chain. |
script/bridge/trustless/DeployTrustlessBridge.s.sol |
Deploy trustless bridge (Lockbox 138 + Ethereum stack). |
script/reserve/DeployReserveSystem.s.sol |
Deploy ReserveSystem. |
script/reserve/SetupPriceFeeds.s.sol |
Configure OraclePriceFeed / mock feeds. |
script/reserve/DeployKeeper.s.sol |
Deploy PriceFeedKeeper. |
script/dex/DeployDODOPMMIntegration.s.sol |
Deploy DODOPMMIntegration. |
script/deploy/02_DeployBridges.s.sol |
Phase 2 bridges. |
script/deploy/vault/DeployVaultSystem.s.sol |
Deploy vault system (Ledger, XAUOracle, VaultFactory, etc.). |
17. External / Canonical Addresses (Examples)
- WETH9 (Ethereum):
0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
- WETH10 (Ethereum):
0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f
- CCIP Router (Ethereum): e.g.
0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D
- LINK: e.g.
0x514910771AF9Ca656af840dff83E8264EcF986CA
- USDT / USDC (Ethereum): Standard mainnet addresses.
Chain-specific CCIP selectors and router addresses: see Chainlink CCIP Supported Networks.
This list is the single reference for bridges, contracts, routers, oracles, mappers, and related infrastructure. Update it when adding or retiring components.
