The Union Bridge Client is a key part of the Union Bridge Protocol. It helps connect Bitcoin and Rootstock, together with BitVMX, in a trust-minimized way. In practice, it watches Rootstock for protocol-relevant events and triggers the next steps needed to execute peg-in and peg-out flows.
This project is a work in progress and should be considered experimental. It may contain bugs, security vulnerabilities, and incomplete features.
Use it at your own risk. The author(s) make no guarantees of functionality, stability, or security.
Do not use this software in production environments or for handling sensitive data.
Contributions, feedback, and issue reports are welcome while development is ongoing.
The Union Bridge Client is a Rust application that connects Rootstock with BitVMX and implements the client-side logic
required by the Union Bridge protocol. It observes Rootstock by subscribing to new block headers and smart contract logs
through JSON-RPC, filtering only the events that matter for the protocol and persisting the minimum state needed to
recover from interruptions or chain reorganizations; this part is implemented in the log-indexer and
block-indexer crates. It also sends transactions to Rootstock through the transaction-dispatcher crate,
which centralizes contract interactions, key usage, and transaction submission. User-facing operations,
including requesting peg-in addresses and peg-outs, are exposed through the user-api crate. The end-to-end
coordination of the different multi-step flows is handled by the coordinator crate, which connects blockchain events,
contract state, broker messaging, BitVMX interactions, and timeout handling.
Main local commands, run from the repo root after the one-time setup in the Local Setup Guide:
bash scripts/run-infra.sh --start # start local blockchains, BitVMX, and mining (Docker)
bash scripts/run-clients.sh # run the operator client services locally
bash scripts/test-flows.sh # run the automated end-to-end happy-path flowsFor funding, peg-in/peg-out, and wallet operations (scripts/operations.sh, scripts/bitcoin-wallet.sh), see the
CLI Tools Guide. The full recommended path lives in the Local Setup Guide.
| If you need to... | Read |
|---|---|
| get the recommended local setup, shared env rules, and runtime modes | Local Setup Guide |
| understand engineering standards and commit conventions | Contributing Guide |
| install or troubleshoot git hooks | Local Setup Guide and Hooks Guide |
| follow AI-agent guidance, project routing, and verification commands | Agent Guide |
| use the local wrappers and operations CLI | CLI Tools Guide |
| choose a Docker flow | Docker Guide |
| run local blockchains and BitVMX in Docker | Local Infra Guide |
| run local operators in Docker | Operator Docker Runtime Guide |
| build or publish Docker images | Docker Build Guide |
| read detailed e2e flow documentation | E2E Flow Documentation |
| inspect crate-specific detail | nearby component READMEs such as CheckFork Guide, Transaction Dispatcher Guide, Key Manager Guide, and Wallet CLI Guide |
Engineering standards and commit conventions live in the Contributing Guide. Local setup, hook installation, shared configuration, runtime modes, and the recommended development path live in the Local Setup Guide. Per-hook details live in the Hooks Guide.
This project is licensed under the MIT License.