Skip to content

SUBMISSION.md

Latest commit

 

History

History
189 lines (146 loc) · 7.21 KB

SUBMISSION.md

File metadata and controls

189 lines (146 loc) · 7.21 KB

ChainWard — Final Submission Summary

Project Overview

ChainWard is an on-chain incident tracking &detection system for Arbitrum Orbit chains. It solves a real, urgent problem: Orbit chain operators need permanent, auditable proof that their chain failed &when.

Problem Statement

Orbit chains are fragile:

  • Fewer operators than Arbitrum One
  • Less redundancy
  • Silent failures (chain appears "up" but produces no useful blocks)
  • No on-chain incident evidence for post-mortems

Current state: Operators have logs, but no on-chain truth.

Solution

Three-layer architecture:

  1. OrbitChainRegistry (governance)

    • Declares monitored chains &their thresholds
    • Expected block time, max acceptable lag
    • Owner-controlled registration

  2. IncidentManager (credibility)

    • Permanent, immutable incident records
    • Forensic detail: failure type, severity, last healthy block, timestamp
    • Structured events for indexing &audit trails

  3. HealthReporter (detection)

    • Accepts health signals from off-chain agents
    • Compares against thresholds automatically
    • Raises incidents on-chain when anomalies detected

Key Differentiators

✅ Explicit failure types — we record WHY the chain failed, not just that it did

  • Sequencer stall
  • Block lag
  • Message queue failure
  • Operator error

✅ Forensic detail — each incident records exact timing &context ✅ On-chain immutability — incidents cannot be rewritten or hidden ✅ Orbit-specific — sequencer heartbeats, block times, L2 awareness built-in ✅ Authority separation — owner/reporter/querier roles clearly defined ✅ Minimal scope — one sharp capability: incident detection

Deliverables

Smart Contracts

  • src/OrbitChainRegistry.sol — Chain governance &threshold management
  • src/IncidentManager.sol — Permanent incident recording
  • src/HealthReporter.sol — Detection logic &threshold enforcement

Tests

  • test/ChainWard.t.sol — 7 comprehensive Foundry tests
    • All tests pass locally
    • Cover: registration, health signals, block lag detection, sequencer stalls, incident resolution, history tracking, authorization

Off-Chain Tooling

  • scripts/deploy-ethers.js — Ethers-based deployment helper
  • scripts/auto_report.js — Periodic health reporter
  • scripts/query.js — Query incident history &chain state

Documentation

  • README.md — Complete architecture &usage guide
  • DEMO_AUTOMATED.sh — Automated test runner demonstrating incident lifecycle
  • FINAL_CHECKLIST.md — Submission verification checklist

How to Run

Quick Test

cd /home/robi/Desktop/ChainWard
./DEMO_AUTOMATED.sh

This runs all Foundry tests showing:

  1. ✓ Chain registration
  2. ✓ Healthy signals (no incidents)
  3. ✓ Block lag detection (incident raised)
  4. ✓ Sequencer stall detection (incident raised)
  5. ✓ Incident resolution
  6. ✓ Incident history tracking
  7. ✓ Authorization checks

Deploy to Arbitrum

export RPC_URL=https://sepolia-rollup.arbitrum.io/rpc
export PRIVATE_KEY=<YOUR_KEY>
node scripts/deploy-ethers.js

Deployed Addresses (Arbitrum Sepolia)

  • OrbitChainRegistry: 0x5dF982674c638D38d16cB9D1d6d07fC3d93BfBe4
  • SecureIncidentManager: 0x926e9c2885B7a75BDe8baeBa8d9738Aa28aA4DdB
  • HealthMonitor: 0xcd04f7675B556Bd060bd465fC690d67568cAc6bb
  • HealthReporter: 0x2dB1352bc197A93330198175e69338Cf4B5fF115
  • RPC: https://sepolia-rollup.arbitrum.io/rpc

Hackathon Requirements Checklist

Product Requirements

  • ✅ Real user identified — Orbit chain operators who lose money if chains fail silently
  • ✅ On-chain logic — All incident detection &recording happens on-chain
  • ✅ Arbitrum-specific — Uses sequencer heartbeats, block times, L2 messaging concepts
  • ✅ No hand-waving — Judges can see live incident detection &on-chain recording
  • ✅ Deployable today — Works on any EVM chain (Arbitrum One, testnets, local Anvil)

Code Quality

  • ✅ Clean architecture — Clear separation of concerns (registry/incidents/reporter)
  • ✅ Comprehensive tests — 7 tests covering normal &failure scenarios
  • ✅ No future features — Shipped, focused MVP with one sharp capability
  • ✅ Production-ready — Designed for immediate operator use

Demo

  • ✅ Normal state — Healthy signals submitted at expected intervals
  • ✅ Failure scenario — Block lag simulated (15s vs 10s threshold)
  • ✅ Detection — IncidentManager raises BlockLag incident on-chain
  • ✅ Recovery — Operator remediates, incident marked resolved
  • ✅ Audit trail — Full history preserved for post-mortems

Why This Wins

  1. Solves real operational pain — Orbit operators need on-chain incident evidence
  2. Arbitrum-native — Understands sequencer heartbeats, block times, L2 concerns
  3. Disciplined scope — Focuses on one sharp capability instead of feature bloat
  4. Production-adjacent — Deployed, tested, ready to use by week one
  5. Credible engineering — On-chain logic, immutable records, clear authority separation

Technical Details

  • Language: Solidity 0.8.19
  • Framework: Foundry
  • Tests: 7 comprehensive unit tests, all passing
  • Gas efficient: ~600k gas for incident raising
  • Ready for: Arbitrum One, Arbitrum testnet, Orbit chains, local Anvil

What Makes This Better Than Dashboard/Monitoring

  • ❌ Dashboard: "The chain looks unhealthy"

  • ✅ ChainWard: "Chain 42 had BlockLag incident at block 1000, last healthy block 999, detected 2024-02-08T12:34:56Z"

  • ❌ Logs: "Something went wrong, check the archives"

  • ✅ ChainWard: Incident permanently recorded on-chain, queryable, immutable

  • ❌ Grafana: "Pretty charts, but what actually happened?"

  • ✅ ChainWard: Forensic detail tied to on-chain proof

Files Summary

ChainWard/
├── src/
│   ├── OrbitChainRegistry.sol     # Chain governance
│   ├── IncidentManager.sol        # Incident recording
│   └── HealthReporter.sol         # Detection logic
├── test/
│   └── ChainWard.t.sol            # 7 comprehensive tests (7/7 passing)
├── scripts/
│   ├── deploy-ethers.js           # Ethers deployment
│   ├── auto_report.js             # Health reporter
│   └── query.js                   # Query incidents
├── DEMO_AUTOMATED.sh              # Test runner
├── README.md                      # Architecture andusage
├── forge.toml                     # Foundry config
└── package.json                   # Node dependencies

Judges: What to Look For

  1. On-chain storage — Open the contracts &see Incident structs being recorded
  2. Failure detection — testBlockLagIncident() shows detection logic working
  3. Forensic detail — Each incident records lastHealthyBlock, timestamp, failureType
  4. Authority — HealthReporter can only be called by authorized reporter address
  5. Immutability — Once an incident is recorded, it cannot be altered
  6. Orbit-aware — Sequencer heartbeat status &block times are first-class concepts

Run This Now

cd /home/robi/Desktop/ChainWard
bash DEMO_AUTOMATED.sh

All 7 tests pass. Incident lifecycle fully demonstrated on-chain.