|
| 1 | +# ICA-Based Forwarding Implementation Plan |
| 2 | + |
| 3 | +## Overview |
| 4 | +Implementation plan for counterfactual address-based forwarding on Celestia using Cosmos SDK. Assets arriving on Celestia from Hyperlane chains or CEX withdrawals are forwarded to final destinations using cryptographically-bound forwarding addresses. |
| 5 | + |
| 6 | +**Key Architecture:** Celestia uses Cosmos SDK (Golang), not EVM. Celestia does not support CosmWasm. We will implement forwarding as a native Cosmos SDK module integrating with the existing `hyperlane-cosmos` SDK module. |
| 7 | + |
| 8 | +## Architecture |
| 9 | + |
| 10 | +### Three-Chain Setup |
| 11 | +``` |
| 12 | +EVM Chain 1 (Source) |
| 13 | + ↓ Native → Synthetic Warp Route |
| 14 | +Celestia (Forwarding Hub - Cosmos SDK + hyperlane-cosmos) |
| 15 | + ↓ Synthetic → Synthetic Warp Route |
| 16 | +EVM Chain 2 (Destination) |
| 17 | +``` |
| 18 | + |
| 19 | +### Technical Approach: Native Cosmos SDK Module |
| 20 | + |
| 21 | +**Implementation Strategy:** |
| 22 | +- Implement forwarding logic as a custom Cosmos SDK module in Golang |
| 23 | +- Integrate with existing `hyperlane-cosmos` module for cross-chain messaging |
| 24 | +- Use Cosmos SDK account model for address derivation |
| 25 | +- Leverage Cosmos SDK's deterministic address generation |
| 26 | +- Store forwarding intents in module state |
| 27 | + |
| 28 | +**Key Components:** |
| 29 | +1. **Forwarding Module**: Custom Cosmos SDK module for intent-bound forwarding |
| 30 | +2. **hyperlane-cosmos Integration**: Message passing to/from other chains |
| 31 | +3. **Address Derivation**: Deterministic account addresses bound to forwarding intents |
| 32 | +4. **Intent Storage**: On-chain storage of forwarding commitments |
| 33 | + |
| 34 | +## Phase 1: Testing Environment Setup (2-3 weeks) |
| 35 | + |
| 36 | +### 1.1 Chain Deployment |
| 37 | + |
| 38 | +#### EVM Chain 1 (Source) |
| 39 | +- [ ] Deploy first local EVM testnet (Anvil/Hardhat) |
| 40 | +- [ ] Configure network parameters (chain ID, RPC endpoints) |
| 41 | +- [ ] Fund test accounts |
| 42 | + |
| 43 | +#### Celestia Instance (Forwarding Hub) |
| 44 | +- [ ] Set up local Celestia testnet instance |
| 45 | +- [ ] Configure Celestia-app parameters |
| 46 | +- [ ] Initialize validator nodes |
| 47 | + |
| 48 | +#### EVM Chain 2 (Destination) |
| 49 | +- [ ] Deploy second local EVM testnet (different chain ID) |
| 50 | +- [ ] Configure network parameters |
| 51 | +- [ ] Fund test accounts |
| 52 | + |
| 53 | +### 1.2 Hyperlane Core Contract Deployment |
| 54 | + |
| 55 | +#### Deploy on EVM Chain 1 |
| 56 | +- [ ] Deploy Hyperlane Mailbox |
| 57 | +- [ ] Deploy NoOp ISM (for prototyping) |
| 58 | +- [ ] Deploy required Hooks |
| 59 | +- [ ] Deploy InterchainGasPaymaster (IGP) |
| 60 | +- [ ] Verify deployments |
| 61 | + |
| 62 | +#### Deploy on Celestia |
| 63 | +- [ ] Integrate `hyperlane-cosmos` module into Celestia-app |
| 64 | +- [ ] Configure Hyperlane Mailbox module |
| 65 | +- [ ] Set up NoOp ISM for prototyping |
| 66 | +- [ ] Configure message routing and handlers |
| 67 | +- [ ] Test module initialization and basic functionality |
| 68 | + |
| 69 | +#### Deploy on EVM Chain 2 |
| 70 | +- [ ] Deploy Hyperlane Mailbox |
| 71 | +- [ ] Deploy NoOp ISM |
| 72 | +- [ ] Deploy required Hooks |
| 73 | +- [ ] Deploy InterchainGasPaymaster (IGP) |
| 74 | +- [ ] Verify deployments |
| 75 | + |
| 76 | +### 1.3 Hyperlane Infrastructure |
| 77 | + |
| 78 | +#### Relayer Setup |
| 79 | +- [ ] Configure Hyperlane relayer for Chain 1 → Celestia |
| 80 | +- [ ] Configure Hyperlane relayer for Celestia → Chain 2 |
| 81 | +- [ ] Test message delivery between all chain pairs |
| 82 | +- [ ] Configure gas payment and fee structures |
| 83 | + |
| 84 | +#### Verification |
| 85 | +- [ ] Test message passing: Chain 1 → Celestia |
| 86 | +- [ ] Test message passing: Celestia → Chain 2 |
| 87 | +- [ ] Test message passing: Chain 2 → Celestia |
| 88 | +- [ ] Test message passing: Celestia → Chain 1 |
| 89 | +- [ ] Verify NoOp ISM works correctly |
| 90 | + |
| 91 | +## Phase 2: Warp Route Deployment (1-2 weeks) |
| 92 | + |
| 93 | +### 2.1 Native ↔ Synthetic Route (Chain 1 ↔ Celestia) |
| 94 | + |
| 95 | +#### EVM Side (Chain 1) |
| 96 | +- [ ] Deploy native token (or use existing) |
| 97 | +- [ ] Deploy HypERC20 collateral contract |
| 98 | +- [ ] Configure remote router (points to Celestia) |
| 99 | + |
| 100 | +#### Cosmos Side (Celestia) |
| 101 | +- [ ] Use `hyperlane-cosmos` warp module for synthetic tokens |
| 102 | +- [ ] Configure synthetic token denomination and metadata |
| 103 | +- [ ] Set up remote router connection to Chain 1 |
| 104 | +- [ ] Configure token minting/burning through hyperlane-cosmos |
| 105 | + |
| 106 | +#### Testing |
| 107 | +- [ ] Test token transfer: Chain 1 → Celestia |
| 108 | +- [ ] Verify synthetic token minted on Celestia |
| 109 | +- [ ] Test token transfer: Celestia → Chain 1 |
| 110 | +- [ ] Verify collateral unlocked on Chain 1 |
| 111 | + |
| 112 | +### 2.2 Synthetic ↔ Synthetic Route (Celestia ↔ Chain 2) |
| 113 | + |
| 114 | +#### Setup |
| 115 | +- [ ] Deploy synthetic token on Chain 2 |
| 116 | +- [ ] Configure routing between Celestia and Chain 2 |
| 117 | +- [ ] Set up symmetric minting/burning |
| 118 | + |
| 119 | +#### Testing |
| 120 | +- [ ] Test token transfer: Celestia → Chain 2 |
| 121 | +- [ ] Test token transfer: Chain 2 → Celestia |
| 122 | +- [ ] Verify total supply conservation |
| 123 | +- [ ] Test end-to-end: Chain 1 → Celestia → Chain 2 |
| 124 | + |
| 125 | +## Phase 3: Forwarding Module Implementation (3-4 weeks) |
| 126 | + |
| 127 | +**Implementation:** Native Cosmos SDK module in Golang, integrated with `hyperlane-cosmos`. |
| 128 | + |
| 129 | +### 3.1 Module Architecture Design |
| 130 | +- [ ] Design module structure following Cosmos SDK patterns |
| 131 | +- [ ] Design ForwardIntent proto definitions (token, destDomain, recipient) |
| 132 | +- [ ] Design address derivation scheme (module account derivation) |
| 133 | +- [ ] Design state storage (intent registry, execution tracking) |
| 134 | +- [ ] Plan integration points with hyperlane-cosmos module |
| 135 | + |
| 136 | +### 3.2 Address Derivation |
| 137 | +- [ ] Implement deterministic address generation from ForwardIntent |
| 138 | +- [ ] Use Cosmos SDK module account derivation patterns |
| 139 | +- [ ] Salt generation binding address to (token, destDomain, recipient) |
| 140 | +- [ ] Ensure addresses are computable off-chain |
| 141 | +- [ ] Add address validation and verification |
| 142 | + |
| 143 | +### 3.3 Core Module Implementation (Golang) |
| 144 | + |
| 145 | +#### Module Setup |
| 146 | +- [ ] Create `x/forwarding` module scaffolding |
| 147 | +- [ ] Define proto messages and types |
| 148 | +- [ ] Implement Keeper with state management |
| 149 | +- [ ] Add module genesis and initialization |
| 150 | + |
| 151 | +#### Intent Registration |
| 152 | +- [ ] Implement `RegisterIntent` transaction handler |
| 153 | +- [ ] Store intent commitments in module state |
| 154 | +- [ ] Emit events for intent registration |
| 155 | +- [ ] Add query methods for intent lookup |
| 156 | + |
| 157 | +#### Forwarding Execution |
| 158 | +- [ ] Implement `ExecuteForwarding` transaction handler (permissionless) |
| 159 | +- [ ] Verify intent matches registered commitment |
| 160 | +- [ ] Query balance at forwarding address |
| 161 | +- [ ] Call `hyperlane-cosmos` warp module to transfer tokens |
| 162 | +- [ ] Handle gas payment for remote execution |
| 163 | +- [ ] Emit execution events |
| 164 | + |
| 165 | +#### Integration with hyperlane-cosmos |
| 166 | +- [ ] Interface with hyperlane-cosmos Mailbox |
| 167 | +- [ ] Use hyperlane-cosmos warp routes for token transfers |
| 168 | +- [ ] Handle cross-chain message encoding |
| 169 | +- [ ] Implement proper error handling |
| 170 | + |
| 171 | +### 3.4 Key Features |
| 172 | +- [ ] Deterministic address computation (off-chain compatible) |
| 173 | +- [ ] Intent immutability (once registered, cannot change) |
| 174 | +- [ ] Permissionless execution (anyone can trigger) |
| 175 | +- [ ] Full balance forwarding (entire balance at address) |
| 176 | +- [ ] Integration with hyperlane-cosmos warp routes |
| 177 | + |
| 178 | +### 3.5 Security |
| 179 | +- [ ] Intent binding verification (address matches commitment) |
| 180 | +- [ ] Prevent unauthorized fund redirection |
| 181 | +- [ ] Implement proper access controls |
| 182 | +- [ ] Add comprehensive error handling |
| 183 | +- [ ] Prevent replay attacks through state tracking |
| 184 | + |
| 185 | +### 3.6 Build and Integration |
| 186 | +- [ ] Build custom Celestia binary with forwarding module |
| 187 | +- [ ] Test module initialization on local testnet |
| 188 | +- [ ] Verify module state persistence |
| 189 | +- [ ] Test integration with hyperlane-cosmos |
| 190 | + |
| 191 | +## Phase 4: Developer Tooling (2-3 weeks) |
| 192 | + |
| 193 | +### CLI Tools (Golang) |
| 194 | +- [ ] Extend Celestia CLI with forwarding commands |
| 195 | +- [ ] Add `compute-forward-address` command |
| 196 | +- [ ] Add `register-intent` command |
| 197 | +- [ ] Add `execute-forwarding` command |
| 198 | +- [ ] Add query commands (balance, intent status) |
| 199 | +- [ ] Support JSON output formats |
| 200 | + |
| 201 | +### SDK (TypeScript/JavaScript) |
| 202 | +- [ ] Implement address computation library (port from Golang) |
| 203 | +- [ ] Add Celestia RPC integration (Cosmos SDK RPC) |
| 204 | +- [ ] Add transaction building utilities (cosmjs) |
| 205 | +- [ ] Write usage examples for web applications |
| 206 | +- [ ] Document cross-chain integration patterns |
| 207 | + |
| 208 | +### Helper Contracts (EVM Chains) |
| 209 | +- [ ] Deploy IntentBuilder Solidity contracts on Chain 1 & 2 |
| 210 | +- [ ] Implement Celestia address computation (EVM/Solidity version) |
| 211 | +- [ ] Add helper functions for computing forwarding addresses |
| 212 | +- [ ] Test address computation matches Golang implementation |
| 213 | + |
| 214 | +## Phase 5: Testing (3-4 weeks) |
| 215 | + |
| 216 | +### End-to-End Tests |
| 217 | +- [ ] **Hyperlane Transfer**: Chain 1 → forwardAddr (Celestia) → Chain 2 |
| 218 | +- [ ] **CEX Withdrawal Simulation**: Direct transfer → forwardAddr → Chain 2 |
| 219 | +- [ ] **Multi-Hop**: Round-trip transfers across all chains |
| 220 | + |
| 221 | +### Security Tests |
| 222 | +- [ ] Attempt fund redirection (should fail) |
| 223 | +- [ ] Test with invalid intents |
| 224 | +- [ ] Test replay scenarios |
| 225 | +- [ ] Verify intent binding |
| 226 | + |
| 227 | +### Failure Mode Tests |
| 228 | +- [ ] Relayer offline scenarios |
| 229 | +- [ ] Insufficient gas scenarios |
| 230 | +- [ ] No execution submitted (funds stay safe) |
| 231 | +- [ ] Recovery procedures |
| 232 | + |
| 233 | +### Performance |
| 234 | +- [ ] Measure end-to-end latency |
| 235 | +- [ ] Profile gas/fee costs |
| 236 | +- [ ] Test concurrent forwards |
| 237 | + |
| 238 | +## Phase 6: Documentation (1-2 weeks) |
| 239 | + |
| 240 | +- [ ] Architecture diagrams |
| 241 | +- [ ] Contract/module API documentation |
| 242 | +- [ ] Integration guides (wallets, CEXs, relayers) |
| 243 | +- [ ] SDK documentation |
| 244 | +- [ ] Security model documentation |
| 245 | + |
| 246 | +## Phase 7: Deployment (2-3 weeks) |
| 247 | + |
| 248 | +### Testnet |
| 249 | +- [ ] Deploy to Celestia testnet (Mocha/Arabica) |
| 250 | +- [ ] Deploy to public EVM testnets |
| 251 | +- [ ] Run public testing campaign |
| 252 | + |
| 253 | +### Mainnet Prep |
| 254 | +- [ ] Security audits |
| 255 | +- [ ] Monitoring setup |
| 256 | +- [ ] Incident response plan |
| 257 | + |
| 258 | +## Success Criteria |
| 259 | + |
| 260 | +### Functional |
| 261 | +- ✅ Deterministic forwarding address computation |
| 262 | +- ✅ Funds only go to committed destinations |
| 263 | +- ✅ Permissionless execution |
| 264 | +- ✅ Works with Hyperlane and CEX deposits |
| 265 | +- ✅ <5 min end-to-end latency |
| 266 | + |
| 267 | +### Security |
| 268 | +- ✅ No unauthorized redirection |
| 269 | +- ✅ No fund loss in failure scenarios |
| 270 | +- ✅ Resistant to known attacks |
| 271 | + |
| 272 | +## Timeline |
| 273 | +- Phase 1: 2-3 weeks (chain setup + Hyperlane core) |
| 274 | +- Phase 2: 1-2 weeks (warp routes) |
| 275 | +- Phase 3: 3-4 weeks (forwarding module in Golang) |
| 276 | +- Phase 4: 2-3 weeks (CLI and SDKs) |
| 277 | +- Phase 5: 3-4 weeks (comprehensive testing) |
| 278 | +- Phase 6: 1-2 weeks (documentation) |
| 279 | +- Phase 7: 2-3 weeks (testnet deployment) |
| 280 | + |
| 281 | +**Total: 14-21 weeks (3.5-5 months)** |
| 282 | + |
| 283 | +**Note:** Timeline assumes familiarity with Cosmos SDK development. Add 1-2 weeks if team needs Cosmos SDK onboarding. |
| 284 | + |
| 285 | +## Key Risks |
| 286 | + |
| 287 | +| Risk | Mitigation | |
| 288 | +|------|------------| |
| 289 | +| Cosmos SDK learning curve | Reference hyperlane-cosmos implementation patterns | |
| 290 | +| Address computation cross-platform (Golang ↔ JS ↔ Solidity) | Comprehensive test vectors, reference implementations | |
| 291 | +| Custom Celestia binary deployment complexity | Thorough testing on local testnet first | |
| 292 | +| hyperlane-cosmos integration challenges | Study existing integrations, collaborate with Hyperlane team | |
| 293 | +| Module state management complexity | Follow Cosmos SDK best practices, comprehensive testing | |
| 294 | + |
| 295 | +## Next Steps |
| 296 | + |
| 297 | +1. **Week 1-2**: Deploy all three chains (Phase 1.1) |
| 298 | +2. **Week 2-3**: Deploy Hyperlane core contracts with NoOp ISM (Phase 1.2) |
| 299 | +3. **Week 3-4**: Set up warp routes between all chains (Phase 2) |
| 300 | +4. **Week 5-8**: Implement forwarding module in Golang (Phase 3) |
| 301 | +5. **Week 9+**: Testing, tooling, and documentation (Phases 4-6) |
| 302 | + |
| 303 | +### Immediate Action Items |
| 304 | +- [ ] Set up local development environment for Cosmos SDK |
| 305 | +- [ ] Clone and review `hyperlane-cosmos` repository |
| 306 | +- [ ] Set up local Celestia testnet |
| 307 | +- [ ] Deploy test EVM chains (Anvil/Hardhat) |
| 308 | + |
| 309 | +## References |
| 310 | + |
| 311 | +### Core Documentation |
| 312 | +- [Hyperlane Documentation](https://docs.hyperlane.xyz/) |
| 313 | +- [hyperlane-cosmos Repository](https://github.com/hyperlane-xyz/hyperlane-cosmos) |
| 314 | +- [Celestia Documentation](https://docs.celestia.org/) |
| 315 | +- [Cosmos SDK Documentation](https://docs.cosmos.network/) |
| 316 | +- [Counterfactual Forwarding Concept](./README.md) |
| 317 | + |
| 318 | +### Cosmos SDK Module Development |
| 319 | +- [Cosmos SDK Module Basics](https://docs.cosmos.network/main/building-modules/intro) |
| 320 | +- [Cosmos SDK Keepers](https://docs.cosmos.network/main/building-modules/keeper) |
| 321 | +- [Cosmos SDK Messages and Queries](https://docs.cosmos.network/main/building-modules/messages-and-queries) |
| 322 | +- [Module Account Addresses](https://docs.cosmos.network/main/building-modules/module-accounts) |
| 323 | + |
| 324 | +### Example Implementations |
| 325 | +- [hyperlane-cosmos Mailbox Module](https://github.com/hyperlane-xyz/hyperlane-cosmos/tree/main/x/core) |
| 326 | +- [hyperlane-cosmos Warp Module](https://github.com/hyperlane-xyz/hyperlane-cosmos/tree/main/x/warp) |
0 commit comments