add initial components

Author: Manav-Aggarwal

ICA-based forwarding/E2E_TEST_GUIDE.md

@@ -0,0 +1,323 @@
+# End-to-End Testing Guide
+
+This guide walks through testing the complete ICA-based forwarding flow from EVM Chain 1 → Celestia → EVM Chain 2.
+
+## Prerequisites
+
+1. Three-chain environment running (see `PHASE1_STATUS.md`)
+2. Hyperlane contracts deployed on all chains
+3. Warp routes configured
+4. ICA module integrated into Celestia
+
+## Test Flow Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         E2E Test Flow                                │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  1. Compute forwarding address off-chain                            │
+│         │                                                            │
+│         ▼                                                            │
+│  2. Send tokens from EVM Chain 1 to forwarding address on Celestia  │
+│         │                                                            │
+│         ▼                                                            │
+│  3. (Automatic) Hyperlane relayer delivers message to Celestia      │
+│         │                                                            │
+│         ▼                                                            │
+│  4. Execute forwarding on Celestia (permissionless)                 │
+│         │                                                            │
+│         ▼                                                            │
+│  5. (Automatic) Hyperlane relayer delivers to EVM Chain 2           │
+│         │                                                            │
+│         ▼                                                            │
+│  6. Verify tokens received at destination on EVM Chain 2            │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Step 1: Compute Forwarding Address
+
+### Using TypeScript SDK
+
+```bash
+cd "ICA-based forwarding/sdk"
+npm install
+npm run build
+
+# Parameters for the test
+TOKEN_ID="0x0000000000000000000000000000000000000000000000000000000000000001"  # Warp token on Celestia
+DEST_DOMAIN="31338"  # EVM Chain 2 domain
+DEST_RECIPIENT="0x000000000000000000000000f39Fd6e51aad88F6F4ce6aB8827279cffFb92266"  # Recipient on Chain 2
+
+# Compute the forwarding address
+npx ts-node src/cli/index.ts compute-address \
+  --token-id $TOKEN_ID \
+  --dest-domain $DEST_DOMAIN \
+  --dest-recipient $DEST_RECIPIENT
+```
+
+### Using Web UI
+
+1. Start the local server:
+   ```bash
+   cd "ICA-based forwarding/sdk/ui"
+   python3 -m http.server 3000
+   ```
+
+2. Open http://localhost:3000 in your browser
+
+3. Enter the parameters:
+   - Token ID: The warp token address on Celestia
+   - Destination Domain: EVM Chain 2 domain ID
+   - Destination Recipient: Final recipient address
+
+4. Click "Compute Address" to get the forwarding address
+
+## Step 2: Send Tokens to Forwarding Address
+
+### From EVM Chain 1
+
+Use the Hyperlane warp route to send tokens to the computed forwarding address:
+
+```bash
+# Example using cast (Foundry)
+FORWARDING_ADDR="celestia1..."  # Forwarding address from Step 1
+AMOUNT="1000000000000000000"     # 1 token (18 decimals)
+
+# Approve the warp route contract
+cast send $TOKEN_ADDRESS "approve(address,uint256)" $WARP_ROUTE $AMOUNT \
+  --rpc-url http://localhost:8545 \
+  --private-key $PRIVATE_KEY
+
+# Transfer via warp route
+# The recipient should be the forwarding address (as bytes32)
+cast send $WARP_ROUTE "transferRemote(uint32,bytes32,uint256)" \
+  69420 \  # Celestia domain
+  $(cast --from-utf8 $FORWARDING_ADDR) \
+  $AMOUNT \
+  --rpc-url http://localhost:8545 \
+  --private-key $PRIVATE_KEY
+```
+
+### Alternative: Direct Synthetic Transfer
+
+If you already have synthetic tokens on Celestia, you can send directly to the forwarding address:
+
+```bash
+celestiad tx bank send $FROM_ADDR $FORWARDING_ADDR 1000000hyperlane/... \
+  --from $KEY_NAME \
+  --chain-id $CHAIN_ID \
+  --node http://localhost:26657
+```
+
+## Step 3: Verify Message Delivery
+
+Monitor the Hyperlane relayer logs:
+
+```bash
+docker logs relayer -f
+```
+
+Look for:
+- Message dispatch on EVM Chain 1
+- Message delivery on Celestia
+
+## Step 4: Execute Forwarding
+
+Forwarding is permissionless - anyone can trigger it.
+
+### Using Celestia CLI
+
+```bash
+celestiad tx ica execute-forward \
+  --ica-address $FORWARDING_ADDR \
+  --token-id $TOKEN_ID \
+  --dest-domain $DEST_DOMAIN \
+  --dest-recipient $DEST_RECIPIENT \
+  --from $KEY_NAME \
+  --chain-id $CHAIN_ID \
+  --node http://localhost:26657
+```
+
+### Verify Balance Before Execution
+
+```bash
+celestiad query bank balances $FORWARDING_ADDR \
+  --node http://localhost:26657
+```
+
+## Step 5: Verify Cross-Chain Delivery
+
+Monitor the relayer for the second hop:
+
+```bash
+docker logs relayer -f
+```
+
+Look for:
+- Message dispatch on Celestia
+- Message delivery on EVM Chain 2
+
+## Step 6: Verify Final Receipt
+
+Check the recipient balance on EVM Chain 2:
+
+```bash
+# Check synthetic token balance
+cast call $SYNTHETIC_TOKEN "balanceOf(address)" $DEST_RECIPIENT \
+  --rpc-url http://localhost:9545
+```
+
+## Automated Test Script
+
+Create `test/e2e_forward.sh`:
+
+```bash
+#!/bin/bash
+set -e
+
+# Configuration
+EVM1_RPC="http://localhost:8545"
+CELESTIA_RPC="http://localhost:26657"
+EVM2_RPC="http://localhost:9545"
+
+TOKEN_ID="0x0000000000000000000000000000000000000000000000000000000000000001"
+DEST_DOMAIN="31338"
+DEST_RECIPIENT="0x000000000000000000000000f39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+
+echo "=== ICA Forwarding E2E Test ==="
+
+echo "Step 1: Computing forwarding address..."
+cd "ICA-based forwarding/sdk"
+FORWARD_ADDR=$(npx ts-node src/cli/index.ts compute-address \
+  --token-id $TOKEN_ID \
+  --dest-domain $DEST_DOMAIN \
+  --dest-recipient $DEST_RECIPIENT \
+  --json | jq -r '.address')
+echo "Forwarding address: $FORWARD_ADDR"
+
+echo "Step 2: Sending tokens to forwarding address..."
+# (Add warp route transfer command here)
+
+echo "Step 3: Waiting for message delivery (30s)..."
+sleep 30
+
+echo "Step 4: Checking balance at forwarding address..."
+# celestiad query bank balances $FORWARD_ADDR
+
+echo "Step 5: Executing forwarding..."
+# celestiad tx ica execute-forward ...
+
+echo "Step 6: Waiting for final delivery (30s)..."
+sleep 30
+
+echo "Step 7: Verifying final balance..."
+# cast call $SYNTHETIC_TOKEN "balanceOf(address)" $DEST_RECIPIENT
+
+echo "=== Test Complete ==="
+```
+
+## Troubleshooting
+
+### Message Not Delivered
+
+1. Check relayer logs:
+   ```bash
+   docker logs relayer
+   ```
+
+2. Verify ISM is configured correctly:
+   ```bash
+   # On EVM Chain 1
+   cast call $MAILBOX "defaultIsm()"
+   
+   # On Celestia
+   celestiad query hyperlane mailbox
+   ```
+
+### Forwarding Fails
+
+1. Check balance at forwarding address:
+   ```bash
+   celestiad query bank balances $FORWARD_ADDR
+   ```
+
+2. Verify address derivation matches:
+   - Compare TypeScript SDK output
+   - Compare Celestia module output
+
+### Cross-Chain Gas Issues
+
+Ensure sufficient gas payment:
+```bash
+# Check IGP balance
+cast call $IGP "balanceOf(address)" $SENDER
+```
+
+## Test Vectors
+
+Use these known test vectors to verify address derivation consistency:
+
+### Test Vector 1: All Zeros
+```
+tokenId:       0x0000000000000000000000000000000000000000000000000000000000000000
+destDomain:    0
+destRecipient: 0x0000000000000000000000000000000000000000000000000000000000000000
+
+Expected Salt: 0x... (compute and document)
+Expected Addr: celestia1... (compute and document)
+```
+
+### Test Vector 2: Specific Values
+```
+tokenId:       0x0000000000000000000000000000000000000000000000000000000000000001
+destDomain:    31337
+destRecipient: 0x000000000000000000000000f39Fd6e51aad88F6F4ce6aB8827279cffFb92266
+
+Expected Salt: 0x... (compute and document)
+Expected Addr: celestia1... (compute and document)
+```
+
+## Success Criteria
+
+- [ ] Forwarding address computed identically across all implementations
+- [ ] Tokens successfully bridged to forwarding address on Celestia
+- [ ] Forwarding executed successfully
+- [ ] Tokens received at final destination on EVM Chain 2
+- [ ] Total latency < 5 minutes
+- [ ] No fund loss in any scenario
+
+## Security Tests
+
+### 1. Redirection Attempt (Should Fail)
+
+Try to forward to a different destination:
+```bash
+celestiad tx ica execute-forward \
+  --ica-address $FORWARD_ADDR \
+  --token-id $TOKEN_ID \
+  --dest-domain 99999 \  # Wrong domain
+  --dest-recipient $WRONG_RECIPIENT \
+  --from $KEY_NAME
+```
+
+Expected: Transaction should fail with "address mismatch" error.
+
+### 2. Double Execution (Should Handle Gracefully)
+
+Execute forwarding twice:
+```bash
+# First execution
+celestiad tx ica execute-forward ...
+
+# Second execution
+celestiad tx ica execute-forward ...
+```
+
+Expected: Second execution should fail gracefully (no funds to forward).
+
+---
+
+**Last Updated**: December 2024
+