docs: improve readme (#119)

## Description

This PR improves Readme 

## Checklist

- [x] I have updated the
[docs/SPEC.md](https://github.com/babylonlabs-io/rollup-bsn-contracts/blob/main/docs/SPEC.md)
file if this change affects the specification
- [x] I have updated the schema by running `cargo gen-schema`

Author: 0xAleksaOpacic

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
 

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.