{"id":31953562,"url":"https://github.com/0xheartcode/evmrelayer-lite","last_synced_at":"2025-10-14T13:52:35.737Z","repository":{"id":318209135,"uuid":"1070345639","full_name":"0xheartcode/EVMRelayer-Lite","owner":"0xheartcode","description":"Lightweight EVM Crosschain Relayer","archived":false,"fork":false,"pushed_at":"2025-10-05T21:01:30.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T21:10:20.266Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xheartcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-05T18:34:33.000Z","updated_at":"2025-10-05T21:01:33.000Z","dependencies_parsed_at":"2025-10-05T21:11:02.108Z","dependency_job_id":"ae63a2aa-a04b-48ca-be57-626cb2111f1b","html_url":"https://github.com/0xheartcode/EVMRelayer-Lite","commit_stats":null,"previous_names":["0xheartcode/evmrelayer-lite"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/0xheartcode/EVMRelayer-Lite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xheartcode%2FEVMRelayer-Lite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xheartcode%2FEVMRelayer-Lite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xheartcode%2FEVMRelayer-Lite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xheartcode%2FEVMRelayer-Lite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xheartcode","download_url":"https://codeload.github.com/0xheartcode/EVMRelayer-Lite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xheartcode%2FEVMRelayer-Lite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018721,"owners_count":26086615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-14T13:52:34.159Z","updated_at":"2025-10-14T13:52:35.728Z","avatar_url":"https://github.com/0xheartcode.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cross-Chain Messaging Protocol\n\nA demo implementation of a cross-chain messaging protocol with 3-phase accountability and delivery tracking on origin chain.\n\n## Overview\n\nThis project implements a trustless cross-chain messaging system where users submit messages on a source chain, and a relayer service observes, attests, and delivers them to a destination chain with full accountability. Unlike traditional \"fire-and-forget\" bridges, this protocol maintains audit trails and cryptographic delivery proofs, allowing users to check message states on the origin network.\n\n### Key Innovation: 3-Phase Accountability Model\n\n1. **Phase 1 - Message Observation:** Relayer claims entire blocks on source chain\n2. **Phase 2 - Attested Delivery:** Relayer delivers messages to destination with EIP-712 attestations\n3. **Phase 3 - Proof Submission:** Relayer submits cryptographic delivery proofs back to source chain\n\nThis creates an accountability loop where the source chain tracks the delivery status of every cross-chain message.\n\n## Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐\n│   Source Chain  │    │     Relayer     │    │  Dest Chain      │\n│                 │    │    Service      │    │                  │\n│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌──────────────┐ │\n│ │submitMessage│ │───▶│ │ Observes    │ │───▶│ │executeMessage│ │\n│ │emit Event   │ │    │ │ Events      │ │    │ │+ EIP712      │ │\n│ └─────────────┘ │    │ └─────────────┘ │    │ └──────────────┘ │\n│        │        │    │        │        │    │        │         │\n│ ┌─────────────┐ │    │ ┌─────────────┐ │    │        │         │\n│ │confirmBlock │ │◀───│ │ Submits     │ │◀───│────────┘         │\n│ │Delivery     │ │    │ │ Proofs      │ │    │                  │\n│ └─────────────┘ │    │ └─────────────┘ │    │                  │\n└─────────────────┘    └─────────────────┘    └──────────────────┘\n    Phase 3 ◀──────────── Phase 1 ──────────▶ Phase 2\n```\n\n## Project Structure\n\n```\nevmrelayer-lite/\n├── contracts/                 # Smart contracts (Solidity + Foundry)\n│   ├── src/\n│   │   ├── CrossChainSource.sol       # Source chain message acceptance\n│   │   └── CrossChainDestination.sol  # Destination chain attestation verification\n│   ├── test/                          # Comprehensive contract tests (52 tests)\n│   ├── script/                        # Deployment and integration scripts\n│   └── README.md                      # Smart contract documentation\n├── relayer/                           # Off-chain relayer service (TypeScript)\n│   ├── src/\n│   │   ├── services/                  # Core relayer logic\n│   │   ├── chains/                    # Blockchain clients\n│   │   ├── state/                     # State persistence\n│   │   └── utils/                     # EIP-712 signatures, logging\n│   ├── utils/dockerfiles/             # Docker deployment\n│   └── README.md                      # relayer documentation  \n├── Makefile                           # Automated demo and development commands\n├── DESIGN.md                          # Architectural decisions and reflection\n└── README.md                          # We are here (x) \n```\n\n## Quick Start\n\n### Prerequisites\n- [Foundry](https://getfoundry.sh/) - Smart contract development\n- [Node.js 20+](https://nodejs.org/) - Relayer service\n- [pnpm](https://pnpm.io/) - Package management\n- [Docker](https://docker.com/) (optional) - Containerized deployment\n\n### One-Command Setup\n```bash\n# Clone and install everything\ngit clone \u003crepository-url\u003e\ncd evmrelayer-lite\nmake install  # Installs Foundry dependencies, pnpm packages, builds everything\n```\n\n## Automated Demos (Recommended)\n\nThe Makefile provides fully automated demos that handle the entire end-to-end flow:\n\n### Option 1: Complete Docker Demo (Simplest)\n```bash\nmake demo-docker\n```\n\n**What it does automatically:**\n1. Clears relayer state for fresh start\n2. Starts two Anvil instances (Chain 31337 \u0026 31338)\n3. Deploys contracts to both chains\n4. Configures cross-chain contract references and permissions\n5. Sends test message: \"Hello today we are Thursday 09 October\"\n6. **Starts relayer in Docker container** with volume persistence\n7. Monitors all 3 phases with automatic detection:\n   - 🎉 PHASE 1: Block claimed and transaction picked up\n   - 🎉 PHASE 2: Message executed on destination chain\n   - 🎉 PHASE 3: Delivery proof submitted back to source\n8. Shows comprehensive summary and gracefully stops everything\n\n### Option 2: Local Node Demo\n```bash\nmake demo\n```\n\n**Same as above but:**\n- Runs relayer locally with Node.js (not in Docker)\n- Shows TypeScript build process\n- Direct access to relayer logs without Docker layers\n\n### Option 3: Custom Message Demo\n```bash\nMESSAGE=\"Your custom cross-chain message\" make demo-custom-message\n```\n\n**Customization:**\n- Uses your custom message instead of default\n- Otherwise identical to `make demo`\n- Perfect for testing specific payloads\n\n## What You'll See During Demo\n\n### Phase 1 - Source Chain Processing\n```\nWeb3 Call: claimBlock(\n  blockNumber: 9,\n  expectedMessageCount: 1\n)\n[Tx 0x6c2e25a641777e59...] Block 9 claim transaction sent\nPHASE 1 DETECTED: Block claimed!\n```\n\n### Phase 2 - Destination Chain Execution  \n```\nWeb3 Call: executeMessage(\n  sourceChainId: 31337,\n  sourceBlockNumber: 9,\n  messageId: 0,\n  sender: 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC,\n  payload: 0x2f049bf3000000000000000000000000000000000000000000000000000000...,\n  destContract: 0x8464135c8F25Da09e49BC8782676a84730C318bC,\n  nonce: 0,\n  deadline: 1759797595,\n  signature: { v: 28, r: 0xc42f27aa3c82b3f3c25cf51ea0d307..., s: 0x19f95b2b71572f5b9b397... }\n)\n[Tx 0x07bdef10cf2d4d97...] Message 0 execution transaction sent\nPHASE 2 DETECTED: Message executed on destination!\n```\n\n### Phase 3 - Proof Submission Back to Source\n```\nWeb3 Call: confirmBlockDelivery(\n  blockNumber: 9,\n  proofs: [\n    1. { destTxHash: 0x07bdef10cf2d4d9752ee6fb2d8cfd6dfe2ef1ba4db026a5c8b66bb0288ab9b04, success: true, receiptsRoot: 0x00000000... }\n  ]\n)\n[Tx 0xb30137aa28e7ecf4...] Delivery proof submission for block 9\nPHASE 3 DETECTED: Delivery proof submitted!\n\n\\o.o/ You have arrived at the end of this script!\n🎉 3-Phase Cross-Chain Protocol completed successfully!\n```\n\n## Manual Setup (Step-by-Step)\n\nFor developers who want granular control or to understand each step:\n\n### 1. Infrastructure Setup\n```bash\n# Start two local blockchain networks\nmake start-anvil\n# This runs:\n# - anvil --port 8545 --chain-id 31337 (Source chain)  \n# - anvil --port 8546 --chain-id 31338 (Destination chain)\n# - Both use default Anvil test accounts with 10,000 ETH each\n```\n\n### 2. Smart Contract Deployment\n```bash\n# Deploy and configure everything in one command\nmake setup\n```\n\n**This runs sequentially:**\n```bash\nmake deploy-source      # Deploy CrossChainSource to chain 31337\nmake deploy-dest        # Deploy CrossChainDestination to chain 31338  \nmake configure-source   # Grant RELAYER_ROLE permissions on source\nmake configure-dest     # Configure cross-chain references on destination\nmake verify-source      # Verify source chain deployment and config\nmake verify-dest        # Verify destination chain deployment and config\n```\n\n**What each deploy step does:**\n- **Source Chain:** Deploys `CrossChainSource.sol` with domain separator for EIP-712\n- **Destination Chain:** Deploys `CrossChainDestination.sol` with source chain references\n- **Configuration:** Sets up cross-chain contract addresses and relayer permissions\n- **Verification:** Comprehensive checks of deployment state and configuration\n\n### 3. Send Cross-Chain Message\n```bash\n# Send a test message (customizable)\nmake demo-send-message\n\n# Or with custom message:\nMESSAGE=\"Hello Cross-Chain World\" make demo-send-message  \n```\n\n**What happens:**\n```bash\nforge script script/integration/SendMessageScript.s.sol \\\n  --rpc-url http://localhost:8545 --broadcast\n```\n\n- User submits message with EIP-712 signature\n- `submitMessage()` function called on source chain\n- `MessageSubmitted` event emitted for relayer observation\n- Returns message ID and block number for tracking\n\n### 4. Start Relayer Service\n\n**Option A: Local TypeScript**\n```bash\nmake relayer-build      # Compile TypeScript to dist/\nmake relayer-start      # Start with: node dist/index.js\n```\n\n**Option B: Development Mode** \n```bash\nmake relayer-dev        # Hot reload with: tsx watch src/index.ts\n```\n\n**Option C: Docker Container**\n```bash\nmake dockercompose-up   # Starts with volume persistence\nmake dockercompose-logs # Follow real-time logs\n```\n\n### 5. Monitor Progress\n\n**Relayer exposes HTTP endpoints:**\n```bash\ncurl http://localhost:8080/health    # Service health status\ncurl http://localhost:8080/status    # Current processing state  \ncurl http://localhost:8080/metrics   # Prometheus metrics\n```\n\n**Health Response:**\n```json\n{\n  \"status\": \"healthy\",\n  \"lastProcessedBlock\": \"9\",\n  \"sourceChainConnected\": true,\n  \"destChainConnected\": true,\n  \"relayerBalance\": {\n    \"source\": \"9999.5 ETH\", \n    \"dest\": \"9998.2 ETH\"\n  }\n}\n```\n\n### 6. Cleanup\n```bash\nmake stop-anvil            # Stop blockchain networks\nmake demo-cleanup          # Kill any running relayer processes\nmake dockercompose-down    # Stop Docker containers\n```\n\n## Understanding the Flow\n\n### 1. User Message Submission\n```solidity\n// User calls submitMessage() on source chain\nCrossChainSource.submitMessage(\n    destChainId: 31338,\n    destContract: 0x8464135c8F25Da09e49BC8782676a84730C318bC,\n    payload: \"Hello Cross-Chain World\",\n    nonce: userNonce,\n    deadline: block.timestamp + 1 hours,\n    signature: userEIP712Signature\n);\n\n// Contract emits event for relayer observation\nemit MessageSubmitted(messageId, sender, destChainId, destContract, payload);\n```\n\n### 2. Relayer Observation (Phase 1)  \n```typescript\n// Relayer monitors source chain for events\nconst logs = await sourceChain.getLogs(fromBlock, toBlock);\n\n// When messages found, relayer claims the entire block\nawait sourceChain.claimBlock(blockNumber, expectedMessageCount);\n```\n\n### 3. Message Delivery (Phase 2)\n```typescript\n// Relayer creates EIP-712 attestation  \nconst signature = await relayer.signMessage({\n    sourceChainId: 31337,\n    sourceBlockNumber: blockNumber,\n    messageId: messageId, \n    sender: originalSender,\n    payload: messagePayload,\n    destContract: targetContract,\n    nonce: relayerNonce,\n    deadline: deadline\n});\n\n// Submits to destination chain with attestation\nawait destChain.executeMessage(...messageParams, signature);\n```\n\n### 4. Proof Submission (Phase 3)\n```typescript\n// Relayer collects delivery receipts\nconst deliveryProof = {\n    destTxHash: executionTransaction.hash,\n    receiptsRoot: block.receiptsRoot, \n    destBlockHash: block.hash,\n    relayerEOA: relayer.address,\n    relayerNonce: transaction.nonce,\n    success: transaction.status === 'success'\n};\n\n// Submits proof back to source chain\nawait sourceChain.confirmBlockDelivery(blockNumber, [deliveryProof]);\n```\n\n## Makefile Command Reference\n\n### Demo Commands (Automated)\n```bash\nmake demo              # Complete end-to-end local demo\nmake demo-docker       # Complete end-to-end Docker demo  \nmake demo-custom-message MESSAGE=\"text\"  # Custom message demo\n```\n\n### Smart Contract Commands\n```bash\nmake install           # Install all dependencies and build everything\nmake build             # Build contracts only\nmake test              # Run contract tests (52 tests)\nmake setup             # Deploy + configure + verify contracts\nmake deploy-source     # Deploy to source chain (31337)\nmake deploy-dest       # Deploy to destination chain (31338)\n```\n\n### Relayer Commands  \n```bash\nmake relayer-build     # Build TypeScript relayer\nmake relayer-start     # Start built relayer\nmake relayer-dev       # Development mode with hot reload\nmake dockercompose-up  # Start relayer in Docker\nmake dockercompose-down # Stop Docker relayer\n```\n\n### Infrastructure Commands\n```bash\nmake start-anvil       # Start both Anvil instances\nmake stop-anvil        # Stop all Anvil instances\nmake demo-cleanup      # Clean up demo processes\n```\n\n## Key Features\n\n### Smart Contracts\n\n**CrossChainSource.sol** - Source chain contract:\n- ✅ **Message Acceptance:** `submitMessage()` with EIP-712 signature verification\n- ✅ **Event Emission:** Emits `MessageSubmitted` events for relayer observation\n- ✅ **Block-based Processing:** Relayers claim entire blocks for batch processing\n- ✅ **Delivery Tracking:** Maintains complete audit trail of all cross-chain messages\n- ✅ **Proof Verification:** Accepts and verifies cryptographic delivery proofs\n\n**CrossChainDestination.sol** - Destination chain contract:\n- ✅ **Attestation Verification:** Verifies EIP-712 signatures before message execution\n- ✅ **Replay Protection:** Nonce-based protection against message replay attacks\n- ✅ **Access Control:** Role-based permissions for authorized relayers only\n- ✅ **Message Execution:** Safe execution of cross-chain payloads\n\n### Off-Chain Relayer Service\n\n**Core Architecture:**\n- ✅ **TypeScript Implementation:** Built with Viem for type-safe blockchain interactions\n- ✅ **3-Phase Processing:** Implements complete accountability protocol\n- ✅ **State Persistence:** JSON-based state with automatic recovery\n- ✅ **Comprehensive Logging:** Full web3 call parameter visibility\n- ✅ **Health Monitoring:** HTTP endpoints for service health and metrics\n- ✅ **Docker Support:** Containerized deployment with volume persistence\n\n## Testing\n\n### Test Coverage\n```\n╭---------------------------------+------------------+------------------+----------------+-----------------╮\n| File                            | % Lines          | % Statements     | % Branches     | % Funcs         |\n+==========================================================================================================+\n| src/CrossChainDestination.sol   | 75.56% (34/45)   | 80.43% (37/46)   | 87.50% (7/8)   | 66.67% (6/9)    |\n| src/CrossChainSource.sol        | 84.14% (122/145) | 78.95% (135/171) | 80.65% (25/31) | 100.00% (19/19) |\n╰---------------------------------+------------------+------------------+----------------+-----------------╯\n```\n\n### Running Tests\n```bash\n# Smart contract tests\ncd contracts \u0026\u0026 forge test              # 52 tests across 4 suites\ncd contracts \u0026\u0026 forge test -vvv         # Verbose output\ncd contracts \u0026\u0026 forge coverage          # Coverage report\n\n# Relayer tests  \ncd relayer \u0026\u0026 pnpm test                 # TypeScript service tests\n\n# Integration tests\nmake demo                               # Full end-to-end testing\n```\n\n## Trust Model \u0026 Security\n\n### EIP-712 Signature Attestation\n```solidity\nstruct CrossChainMessage {\n    uint256 sourceChainId;\n    uint256 sourceBlockNumber; \n    uint256 messageId;\n    address sender;\n    bytes payload;\n    address destContract;\n    uint256 nonce;\n    uint256 deadline;\n}\n```\n\n### Security Features\n- **Domain Separation:** EIP-712 prevents signature replay across chains\n- **Nonce Protection:** Prevents message replay attacks\n- **Deadline Enforcement:** Time-bounded message validity\n- **Role-Based Access:** Only authorized relayers can execute messages\n- **Cryptographic Proofs:** Receipt roots provide tamper-proof delivery evidence\n- **Complete Audit Trail:** Source chain maintains record of all activity\n\n## Configuration\n\nThe project uses a shared `.env` file with sensible defaults:\n\n```env\n# Chain Configuration\nCHAIN_ID_ONE=31337          # Source chain (Anvil default)\nCHAIN_ID_TWO=31338          # Destination chain\nRPC_URL_ONE=http://localhost:8545\nRPC_URL_TWO=http://localhost:8546\n\n# Test Accounts (Anvil defaults)\nPRIVATE_KEY_DEPLOYER=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80\nPRIVATE_KEY_RELAYER=0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d\n\n# Contract Addresses (consistent across Foundry local deployments)\nSOURCE_CONTRACT=0x8464135c8F25Da09e49BC8782676a84730C318bC\nDEST_CONTRACT=0x8464135c8F25Da09e49BC8782676a84730C318bC\n```\n\n**Note:** All values are for local development - no sensitive data included.\n\n## Considerations \n\n### ✅ Testing\n- **Unit Tests:** Comprehensive contract testing with Foundry (52 tests)\n- **Integration:** Automated end-to-end demos with real blockchain interaction\n- **Documentation:** Every component documented\n\n### ✅ Setup \u0026 Documentation\n- **Self-Contained:** Everything runs locally with Anvil\n- **Minimal Setup:** Single `make install` command followed by `make demo`\n\n## Production Considerations\n\nFor production deployment, consider checking everything. This code was written in a rush. It does what it should but you never know.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xheartcode%2Fevmrelayer-lite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xheartcode%2Fevmrelayer-lite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xheartcode%2Fevmrelayer-lite/lists"}