How riftresearch/protocol works
Project type and purpose
• Rift Protocol is a Rust-based monorepo implementing a trustless cross-chain swap protocol between Bitcoin and Ethereum.
• It contains:
• On-chain smart contracts (in contracts/) for auctions, order settlement, and light-client state.
• Rust “circuits” (crates/bitcoin-light-client-core, crates/rift-core) for verifying Bitcoin consensus and handling state updates.
• Off-chain indexers and servers (e.g. bin/hypernode, bin/data-engine-server) that watch both chains, build proofs, and submit transactions.
• Auxiliary tooling: devnet launcher, market-maker bot, checkpoint downloader, benchmarks, SDK, and Python lab experiments.
File structure
Top-level layout:
├─ contracts/ Solidity code, artifacts, tests, Foundry config
├─ crates/ Core Rust libraries: light-client, rift-core, data-engine, SDK, Sol-bindings
├─ bin/ Executables: devnet, hypernode, data-engine-server, market-maker, etc.
├─ integration-tests/ End-to-end tests across components
├─ lab/ Python research scripts (optional)
├─ test-data/ Sample Bitcoin blocks and headers for local testing
├─ Dockerfile.* / Makefile / GitHub workflows for CI/CD and container builds
Patterns & clues:
• “crates” embody core business logic and proof circuits.
• “bin” modules wire those crates into runnable services.
• “contracts” deploy on Ethereum and form the trust root for swaps.
• Integration tests simulate full protocol flows.
README
• Emphasizes three pillars:
1. Bitcoin light-client circuit (bitcoin-light-client-core)
2. Settlement & proof circuit (rift-core)
3. Solidity contracts (contracts/)
• Highlights hypernode as the off-chain indexer+relayer.
• Mentions DevNet to stand up local test chains.
a. Main components:
• Bitcoin Network (Full Node RPC)
• Ethereum Network (RPC + Smart Contracts)
• Off-chain Services:
– Hypernode (indexer, proof generator, watcher)
– Data Engine Server (database for block data, MMR leaves)
– Market-maker bot, checkpoint downloader, benchmarks
• Proof circuits (Rust crates)
• DevNet orchestrator / Docker environment
• SDK for client integrations
b. Relationships & interactions:
1. Hypernode polls Bitcoin full node → feeds blocks to Data Engine → runs light-client circuit to update MMR state.
2. Proof generator (rift-core) builds SPV/settlement proofs → submits them via Ethereum RPC to Contracts.
3. Ethereum Contracts emit events (OrderCreated, ChallengeRaised) → Hypernode listens → triggers off-chain actions.
4. Market-maker or external client calls Contracts → Contracts lock/swap assets → events.
5. DevNet simulates both chains locally for end-to-end loops.
c. Architectural patterns/design principles:
• Microservice style: each binary is a standalone service using shared crates.
• Clean separation: “crates” for domain logic, “bin” for orchestration.
• On-chain vs off-chain trust boundary: circuits + proofs vs Solidity code.
• Event-driven interplay between chains mediated by hypernode.
d. Key technologies & frameworks:
• Rust + Cargo for core logic and services.
• Foundry + SP1 for contract development & succinct proofs.
• Docker for DevNet & CI workflows.
• PostgreSQL or embedded KV (dep. of data-engine-server).
• Ethereum & Bitcoin node RPC endpoints.