From 3655bf718f20a501948cbb7650c477d288d12d1b Mon Sep 17 00:00:00 2001 From: Alvaro Lillo Date: Tue, 24 Mar 2026 11:57:46 +0100 Subject: [PATCH] Replace stub README with comprehensive technical documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous README was a 5-line stub with just links. The new README covers architecture, security model, repository layout, Move package structure, protocol flows, development workflow, and gRPC services — grounded in the actual codebase and aimed at technically capable developers and contributors. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 245 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3555a05a6..5f63a5c5c 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,249 @@ -# hashi +# Hashi -Native BTC collateral project +Sui-native Bitcoin bridge using threshold cryptography. -[rustdoc](https://mystenlabs.github.io/hashi/rustdoc/hashi) +[Rustdoc](https://mystenlabs.github.io/hashi/rustdoc/hashi) | +[Design Book](https://mystenlabs.github.io/hashi/design) | +[Frontend](https://devnet.hashi.sui.io) -[design](https://mystenlabs.github.io/hashi/design) +## Overview -[frontend](https://devnet.hashi.sui.io) +Hashi is a protocol for securing and managing BTC on the Sui blockchain. It enables users to deposit native Bitcoin into a managed pool and receive `hBTC` (a fungible `Coin`) on Sui, which can be used in DeFi. When users want their BTC back, the protocol builds, signs, and broadcasts a Bitcoin transaction to return it. + +The protocol is operated by a **committee** — a subset of Sui validators who run the Hashi node alongside their validator software. The committee collectively holds a shared Bitcoin key via threshold MPC (BLS12-381 for committee certificates, threshold Schnorr for Bitcoin signatures). A second signer, the **Guardian** (an AWS Nitro Enclave), forms a 2-of-2 Taproot multisig with the committee key, ensuring no single party can unilaterally spend pooled BTC. + +## Architecture + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Sui Blockchain │ +│ │ +│ ┌─────────────────────────────┐ ┌───────────────────────────────┐ │ +│ │ Hashi Move Package │ │ Hashi Shared Object (on-chain)│ │ +│ │ (packages/hashi/) │ │ - Committee & Config │ │ +│ │ deposit, withdraw, reconfig│ │ - UTXO Pool │ │ +│ │ governance proposals │ │ - Deposit/Withdrawal Queues │ │ +│ └──────────────┬──────────────┘ └──────────┬────────────────────┘ │ +│ │ Sui RPC │ │ +└─────────────────┼──────────────────────────────┼─────────────────────┘ + │ │ + ┌─────────────┴──────────────────────────────┴─────────────┐ + │ Hashi Validator Nodes │ + │ (crates/hashi/ binary) │ + │ │ + │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ + │ │ gRPC Server │ │ MPC Protocol │ │ BTC Monitor │ │ + │ │ (TLS, mTLS) │ │ (DKG, Sign) │ │ (kyoto-cbf) │ │ + │ └──────┬───────┘ └──────────────┘ └────────┬─────────┘ │ + │ │ gRPC (BridgeService, MpcService) │ │ + │ │ between validators │ JSON-RPC │ + └─────────┼──────────────────────────────────────┼───────────┘ + │ │ + ▼ ▼ + ┌──────────────────┐ ┌─────────────────────┐ + │ Guardian Enclave │ │ Bitcoin Network │ + │ (AWS Nitro) │ │ (mainnet/testnet/ │ + │ GuardianService │◄── gRPC ────────│ regtest) │ + │ + S3 audit logs │ └─────────────────────┘ + └──────────────────┘ + + ┌──────────────────┐ ┌──────────────────────┐ + │ Screener Service │ │ Hashi Monitor │ + │ (hashi-screener) │ │ (hashi-monitor) │ + │ AML/sanctions │ │ Withdrawal audit │ + │ via Merkle/TRM │ │ E1→E2→E3 checks │ + └──────────────────┘ └──────────────────────┘ +``` + +**Hashi validator nodes** are Rust binaries that watch both Sui and Bitcoin, coordinate with peers via gRPC (TLS with self-signed ed25519 certs), and run the MPC signing protocol. A leader is elected per epoch to drive deposit confirmations, withdrawal batching, and Bitcoin transaction construction. + +**The Guardian enclave** runs in AWS Nitro and provides the second Schnorr signature for every Bitcoin spend. It enforces rate limits and writes an immutable audit trail to S3. + +**The screener** is an optional gRPC service that checks deposit and withdrawal addresses against AML/sanctions databases (MerkleScience, TRM Labs, or a static list). Each validator configures its own screening endpoint. + +**The monitor** audits the withdrawal pipeline by correlating events across three systems: Sui approval (E1), Guardian approval (E2), and Bitcoin confirmation (E3). + +## Security model + +Hashi's trust model is built on two independent signing layers: + +- **Threshold MPC committee**: A subset of Sui validators collectively hold a single Bitcoin private key via threshold Schnorr. All protocol actions (deposit confirmation, withdrawal approval, transaction signing) require a **2/3 stake-weighted quorum** of BLS signatures. +- **Guardian 2-of-2**: Every Bitcoin transaction requires signatures from *both* the MPC committee key and the Guardian key, combined in a Taproot P2TR script path. The Guardian is a hardened AWS Nitro Enclave with rate limiting and immutable S3 logging. +- **AML screening**: Before signing, each validator independently screens addresses via a configurable screener service. +- **Epoch-based key rotation**: When the Sui validator set changes at epoch boundaries, MPC key shares are redistributed from the old committee to the new one. The committee then runs a presigning protocol to pre-generate partial signatures for the epoch. + +No single validator, the Guardian alone, or any external party can spend pooled BTC without committee quorum *and* Guardian co-signature. + +## Repository layout + +| Path | Type | Description | +|------|------|-------------| +| `crates/hashi/` | Binary + Library | Validator node and CLI. Server, MPC, gRPC services, BTC monitor, deposits, withdrawals, leader election, Sui watcher, transaction executor. | +| `crates/hashi-types/` | Library | Shared types, protobuf definitions (`.proto` files), and generated gRPC code for all services. | +| `crates/hashi-guardian-enclave/` | Binary + Library | Guardian enclave service (AWS Nitro). 2-of-2 signing, key setup, rate limiting, S3 audit logs. | +| `crates/hashi-screener/` | Binary + Library | AML/sanctions screening service. Queries MerkleScience; auto-approves non-mainnet requests. | +| `crates/hashi-monitor/` | Binary + Library | Withdrawal audit tool. Correlates E1 (Sui) → E2 (Guardian) → E3 (Bitcoin) events in batch or continuous mode. | +| `crates/e2e-tests/` | Tests + Binary | End-to-end test infrastructure. Also provides the `hashi-localnet` binary for local dev environments. | +| `crates/proto-build/` | Build tool | Compiles `.proto` files from `hashi-types` into generated Rust code. | +| `packages/hashi/` | Sui Move | On-chain smart contract: committee management, UTXO pool, deposits, withdrawals, governance, treasury. | +| `design/` | mdbook | Design documentation: committee, MPC protocol, guardian, fees, address scheme, flows. | +| `docker/` | Containers | Containerfiles for `hashi` and `hashi-screener`. | + +## Move package + +The on-chain state lives in a single shared `Hashi` object (`packages/hashi/sources/hashi.move`): + +```move +public struct Hashi has key { + id: UID, + committee_set: CommitteeSet, // Active + pending committees by epoch + config: Config, // Protocol parameters (fees, thresholds, pause) + treasury: Treasury, // BTC coin minting and burning + deposit_queue: DepositRequestQueue, + withdrawal_queue: WithdrawalRequestQueue, + utxo_pool: UtxoPool, // Tracked Bitcoin UTXOs + proposals: Bag, // Active governance proposals + tob: Bag, // TOB certificates by (epoch, batch_index) +} +``` + +The package contains 24 source modules organized as: + +| Area | Modules | +|------|---------| +| Core | `hashi`, `btc`, `treasury`, `threshold`, `cert_submission`, `tob` | +| Deposits | `deposit`, `deposit_queue` | +| Withdrawals | `withdraw`, `withdrawal_queue`, `utxo`, `utxo_pool` | +| Committee | `committee/committee`, `committee/committee_set`, `validator`, `reconfig`, `guardian` | +| Configuration | `config/config`, `config/config_value` | +| Governance | `proposal/proposal`, `proposal/events`, `proposal/types/upgrade`, `proposal/types/update_config`, `proposal/types/enable_version`, `proposal/types/disable_version` | + +Tests live in `packages/hashi/tests/` (8 test modules). + +## Protocol flows + +### Deposit (BTC → hBTC) + +1. User sends BTC to a Taproot deposit address derived from their Sui address and the committee+guardian keys +2. User calls `deposit()` on Sui with the UTXO details and a deposit fee in SUI +3. Validators watch Bitcoin for confirmations, screen the address, and collect BLS signatures +4. Once quorum is reached, a validator calls `confirm_deposit()` — the UTXO is added to the pool and `hBTC` is minted to the user + +### Withdrawal (hBTC → BTC) + +1. User calls `request_withdrawal()` with their `hBTC` balance and a destination Bitcoin address +2. Committee screens the destination, votes, and submits an approval certificate (`approve_request()`) +3. The leader batches approved requests, selects UTXOs, and proposes a Bitcoin transaction on-chain (`commit_withdrawal_tx()`) +4. The Guardian provides one Schnorr signature; the committee runs threshold signing for the second (`sign_withdrawal()`) +5. The transaction is broadcast to Bitcoin; once confirmed, the committee submits `confirm_withdrawal()` on Sui + +### Reconfiguration + +At each Sui epoch boundary, the committee membership may change. Hashi runs: +1. **Key rotation** — MPC key shares are redistributed from the old committee to the new one +2. **Presigning** — the new committee pre-generates partial Schnorr signatures to speed up signing during the epoch + +## Getting started + +### Prerequisites + +- **Rust 1.91+** (pinned in `rust-toolchain.toml`) +- **cargo-nextest** — `cargo install cargo-nextest` +- **buf** — `brew install bufbuild/buf/buf` (protobuf linting/formatting) +- **Sui CLI** — `cargo install --locked --git https://github.com/MystenLabs/sui.git sui` +- **prettier-move** — `npm install -g @mysten/prettier-plugin-move` (Move formatter) +- **bitcoind** (optional) — required for e2e tests and localnet +- **mdbook + mdbook-mermaid** (optional) — required to build the design book + +See the [Design Book](https://mystenlabs.github.io/hashi/design) for detailed protocol documentation. + +### Building + +```bash +cargo build # builds crates/hashi (the default member) +cargo build --workspace # builds all crates +make proto # regenerate Rust code from .proto files +``` + +### Running locally + +```bash +# Start the validator server +cargo run -- server --config path/to/config.toml + +# Start a full local environment (Bitcoin regtest + Sui localnet + N validators) +cargo run -p e2e-tests --bin hashi-localnet -- start --num-validators 4 +``` + +## Development + +### Testing + +```bash +make test # all Rust tests (nextest + doc tests) +make test-move # all Move tests +cargo nextest run -p e2e-tests # e2e tests (requires bitcoind + sui on PATH) +``` + +E2E tests spin up Bitcoin regtest, Sui localnet, and multiple Hashi validator nodes. They require 4 threads per test (configured in `.config/nextest.toml`). + +### Code quality + +```bash +make fmt # format Rust + protobuf + Move +make clippy # lint +make ci # full CI pipeline: check-fmt → buf-lint → clippy → test +``` + +### Protobuf workflow + +Proto definitions live in `crates/hashi-types/proto/sui/hashi/v1alpha/`. After editing `.proto` files: + +```bash +make proto # compiles protos → generated Rust in hashi-types/src/proto/generated/ +``` + +The generated code and FDS binaries must be committed. + +### Localnet commands + +The `hashi-localnet` binary provides additional dev utilities: + +```bash +cargo run -p e2e-tests --bin hashi-localnet -- status # show running status +cargo run -p e2e-tests --bin hashi-localnet -- info # print connection details +cargo run -p e2e-tests --bin hashi-localnet -- mine # mine Bitcoin blocks +cargo run -p e2e-tests --bin hashi-localnet -- faucet-sui # send SUI to an address +cargo run -p e2e-tests --bin hashi-localnet -- faucet-btc # mine BTC to an address +cargo run -p e2e-tests --bin hashi-localnet -- deposit # execute full deposit flow +``` + +## gRPC services + +Validators communicate over gRPC with TLS. Proto definitions are in `crates/hashi-types/proto/sui/hashi/v1alpha/`. + +| Service | Description | +|---------|-------------| +| `BridgeService` | Validator-to-validator: service info, deposit confirmation, withdrawal approval, TX construction, signing, and confirmation. | +| `GuardianService` | Validator-to-Guardian: key setup, operator/provisioner init, withdrawal signing. | +| `MpcService` | MPC protocol messages: DKG, key rotation, presigning, and signing rounds. | +| `ScreenerService` | AML screening: takes an address and transaction type, returns approve/deny. | + +## Configuration + +The validator reads a TOML config file (`--config`). Protocol parameters live on-chain in the `Config` object and are modified through `UpdateConfig` governance proposals requiring 2/3 stake-weighted quorum. + +For the full configuration reference, see `crates/hashi/src/config.rs` and the on-chain parameter definitions in `packages/hashi/sources/config/config.move`. + +## Further reading + +| Resource | Description | +|----------|-------------| +| [Design Book](https://mystenlabs.github.io/hashi/design) | Protocol design: committee, MPC, guardian, address scheme, fees, deposit/withdrawal/reconfiguration flows. Build locally with `make book`. | +| [Rustdoc](https://mystenlabs.github.io/hashi/rustdoc/hashi) | API documentation for all crates. Build locally with `make doc-open`. | +| [Monitor README](crates/hashi-monitor/README.md) | Withdrawal audit tool usage and E1→E2→E3 event correlation. | +| [Guardian Enclave README](crates/hashi-guardian-enclave/README.md) | Guardian service architecture and S3 logging format. | + +## License + +[Apache 2.0](LICENSE)