Skip to content

Commit 4065a7a

Browse files
commit initial plan
1 parent 107bd49 commit 4065a7a

File tree

14 files changed

+1087
-0
lines changed

14 files changed

+1087
-0
lines changed
Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
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

Comments
 (0)