diff --git a/CHANGELOG.md b/CHANGELOG.md index 003ab1b..2fbd174 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,6 +39,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ### Improvements +* [#119](https://github.com/babylonlabs-io/rollup-bsn-contracts/pull/119) docs: + improve readme * [#120](https://github.com/babylonlabs-io/rollup-bsn-contracts/pull/120) docs: add reward mechanism diff --git a/README.md b/README.md index e10eabb..010af7f 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,121 @@ # Rollup BSN Contracts -This repo contains the Wasm smart contract for rollup BSN integration. The -contract is intended to be deployed on Babylon Genesis and will maintain -finality signatures and block finalisation status of rollups. - -## Specification - -For detailed technical specifications and requirements of the finality contract, -please see [SPEC.md](docs/SPEC.md). The spec document outlines the contract's -interfaces, message handlers, queries, and provides guidance for integrators. - -## Development +**Bitcoin-secured finality for rollups through Babylon's Bitcoin staking +protocol.** + +This repository contains the finality contract that enables Ethereum Rollups to +become Bitcoin Supercharged Networks (BSNs) by inheriting Bitcoin's economic +security through Babylon's staking infrastructure. + +## What is Rollup BSN? + +**Bitcoin Supercharged Networks (BSNs)** are blockchain networks that leverage +Bitcoin's economic security through Babylon's Bitcoin staking protocol. BSNs +enhance their security by tapping into Bitcoin's massive economic security, +where Bitcoin stakers delegate their BTC to provide cryptographic attestations +for network finality. + +### How It Works + +1. **Deploy Contract** - Deploy this finality contract on Babylon Genesis chain +2. **Register BSN** - Register your rollup as a Bitcoin Supercharged Network +3. **BTC Delegation** - Bitcoin stakers delegate their BTC to finality providers +4. **Block Finalization** - Finality providers sign rollup blocks and submit + signatures to the contract +5. **Cross-Chain Security** - Your rollup inherits Bitcoin's economic security + through Babylon's infrastructure + +The finality contract acts as the bridge between your rollup and Babylon's +Bitcoin staking protocol, maintaining an immutable record of block finalization +and ensuring finality providers remain honest through economic incentives. + +> **Note:** To read finalized data from contracts on Babylon Genesis, you should +> use an already built off-chain service or build your own. We have a +> proof-of-concept available at +> [rollup-finality-gadget](https://github.com/babylonlabs-io/rollup-finality-gadget). +> +> **Learn More:** To understand how finality providers work and how to become one, +> visit the [finality-provider repository](https://github.com/babylonlabs-io/finality-provider). + +### Security Through Cryptography + +The system uses **EOTS (Extractable One-Time Signatures)** to ensure finality +provider honesty: + +- **Public Randomness Commitment** - Finality providers pre-commit to randomness + values they'll use for signing +- **Block Finality Signatures** - Finality providers sign rollup block data + using their private keys +- **One-Time Signatures** - Each signature uses unique randomness and can only + be used once safely +- **Automatic Slashing** - If a provider signs two different blocks at the same + height (double-signing), the contract automatically extracts their private key + and triggers slashing + +## Repository Structure + +- **`contracts/finality/`** - Core finality contract implementing BSN + integration +- **`docs/`** - Comprehensive technical specifications and guides +- **`e2e/`** - End-to-end integration tests +- **`scripts/`** - Development and deployment utilities + +## Quick Start ### Prerequisites -Make sure you have `cargo-run-script` installed and docker running. - ```bash +# Install dependencies cargo install cargo-run-script ``` -### Clean the build - -```bash -cargo clean -``` - -### Build the contract +### Build & Test ```bash +# Build the contract cargo build -``` - -### Formatting and Linting - -Check whether the code is formatted correctly. - -```bash -cargo fmt --all -- --check -cargo check -cargo clippy --all-targets -- -D warnings -``` - -Alternatively, you can run the following command to run all the checks at once. - -```bash -cargo run-script lint -``` -### Build the optimized contract +# Run tests +cargo test --lib -```bash +# Build optimized version for deployment cargo run-script optimize ``` -## Tests +### Deploy to Babylon -### Unit tests +1. **Upload Contract**: Deploy WASM bytecode to Babylon Genesis +2. **Instantiate**: Configure your BSN parameters +3. **Register BSN**: Register with Babylon's consumer registry +4. **Go Live**: Start accepting finality signatures from Finality Providers -Note: Requires the optimized contract to be built (`cargo optimize`) +See our [Contract Management Guide](docs/contract-management.md) for detailed +deployment instructions. -Runs all the CI checks locally (in your actual toolchain). +## Development Commands ```bash -cargo test --lib -``` +# Linting & formatting +cargo run-script lint -### Integration tests +# Integration tests (requires optimized build) +cargo run-script integration -Note: Requires the optimized contract to be built (`cargo optimize`) +# End-to-end tests +cargo run-script e2e -```bash -cargo test --test integration +# Generate contract schema +cargo run-script schema ``` -Alternatively, you can run the following command, that makes sure to build the -optimized contract before running the integration tests. - -```bash -cargo run-script integration -``` +## Contributing -### End-to-End Tests +We welcome contributions! This project follows the same guidelines as the +[Babylon node repository](https://github.com/babylonlabs-io/babylon/blob/main/CONTRIBUTING.md). -Note: Requires the optimized contract to be built (`cargo optimize`) +--- -Run the end-to-end tests for the contract. +**Need Help?** Check our [documentation](docs/) or open an issue for support. -```bash -cargo run-script e2e -``` +**Learn More:** Visit [Babylon Labs](https://babylonlabs.io) to understand the +broader Bitcoin staking ecosystem. \ No newline at end of file diff --git a/docs/contract-managment.md b/docs/contract-management.md similarity index 100% rename from docs/contract-managment.md rename to docs/contract-management.md