docs: improve readme

README.md

@@ -1,92 +1,118 @@
 # 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.
+**Bitcoin-secured finality for rollups through Babylon's Bitcoin staking
+protocol.**
 
-## Specification
+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.
 
-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.
+## What is Rollup BSN?
 
-## Development
+**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.
 
-### Prerequisites
+### How It Works
 
-Make sure you have `cargo-run-script` installed and docker running.
+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
 
-```bash
-cargo install cargo-run-script
-```
+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.
 
-### Clean the build
+> **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).
 
-```bash
-cargo clean
-```
+### Security Through Cryptography
 
-### Build the contract
+The system uses **EOTS (Extractable One-Time Signatures)** to ensure finality
+provider honesty:
 
-```bash
-cargo build
-```
+- **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
 
-### Formatting and Linting
+## Repository Structure
 
-Check whether the code is formatted correctly.
+- **`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
 
-```bash
-cargo fmt --all -- --check
-cargo check
-cargo clippy --all-targets -- -D warnings
-```
+## Quick Start
 
-Alternatively, you can run the following command to run all the checks at once.
+### Prerequisites
 
 ```bash
-cargo run-script lint
+# Install dependencies
+cargo install cargo-run-script
 ```
 
-### Build the optimized contract
+### Build & Test
 
 ```bash
+# Build the contract
+cargo build
+
+# Run tests
+cargo test --lib
+
+# 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-managment.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.
+## Contributing
 
-```bash
-cargo run-script integration
-```
-
-### 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.