io.github.beepboop2025/umbra-proof
Verify Umbra bridge accountability proofs (signed receipts, checkpoints, Merkle inclusion).
Open source Open in the app JSON README (API)
About
Verify Umbra bridge accountability proofs (signed receipts, checkpoints, Merkle inclusion).
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- beepboop2025
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Stars
- 1
- Open pull requests
- 6
- Last push
- 2026-09-05T22:38:21Z
- Repository state
- ativo
- Language
- Rust
- License
- NOASSERTION
- Added
- 2026-08-29 03:02:30
- Updated
- 2026-08-29 03:02:30
- Origin id
io.github.beepboop2025/umbra-proof
README
<!-- textura-banner -->
<div align="center">
<a href="https://github.com/beepboop2025/umbra-xmr-bridge"><img src="./banner.svg" width="100%" alt="umbra-xmr-bridge" /></a>
</div>
<p align="center">
<a href="https://github.com/beepboop2025/umbra-xmr-bridge/actions/workflows/tests.yml"><img src="https://github.com/beepboop2025/umbra-xmr-bridge/actions/workflows/tests.yml/badge.svg" alt="tests" /></a>
<img src="https://img.shields.io/badge/coverage-85%25-brightgreen" alt="coverage" />
</p>
<p align="center">
<img src="public/monero.svg" width="40" alt="XMR" />
<strong style="font-size: 2em;">UMBRA</strong>
<img src="public/ton.svg" width="40" alt="TON" />
</p>
<h3 align="center">Privacy-first cross-chain bridge</h3>
<p align="center">
Swap XMR, BTC, ETH, TON, SOL and more — trustless MPC threshold signatures, real-time rates, zero KYC.
</p>
<p align="center">
<img src="https://img.shields.io/badge/Rust-000000?style=for-the-badge&logo=rust&logoColor=white" alt="Rust" />
<img src="https://img.shields.io/badge/Next.js-000000?style=for-the-badge&logo=next.js&logoColor=white" alt="Next.js" />
<img src="https://img.shields.io/badge/Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram" />
<img src="https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge&logo=postgresql&logoColor=white" alt="PostgreSQL" />
<img src="https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker" />
</p>
---
## What is Umbra?
Umbra is a non-custodial cross-chain bridge built around **Monero** — the only cryptocurrency with mandatory privacy. It enables trustless swaps between privacy coins and public blockchains using **FROST threshold signatures** (2-of-3 MPC), meaning no single party ever holds your funds.
What makes Umbra different from every other bridge is the **Proof Layer**: the bridge does not ask to be trusted — it produces cryptographic evidence for everything it does, and ships the tools to check that evidence offline.
---
## The Proof Layer
Bridges are the most-hacked primitive in crypto (Ronin $624M, Multichain $126M, Nomad $190M, Harmony $100M — drained over minutes-to-hours while nothing watched). Umbra's answer is a layer of verifiable accountability that no major bridge ships today:
```
┌─────────────────────────────────────────────────────────┐
│ PROOF LAYER │
│ │
every │ ┌────────────┐ sealed ┌──────────────────┐ │
order ────►│ │ Signed │ every 5m │ Transparency │ │
event │ │ Receipts │────────────►│ Log (Merkle) │ │
│ │ Ed25519 + │ │ RFC 6962 proofs │ │
│ │ ML-DSA-65 │ └────────┬─────────┘ │
│ └────────────┘ │ anchors │
│ ▼ │
│ ┌──────────────────┐ ┌──────────────┐ │
│ │ Sentinel │ │ Signed │ │
│ │ 5 guards, 30s │ │ Canary │ │
│ │ + Isolation │ │ (freshness- │ │
│ │ Forest (ML) │ │ bound) │ │
│ └──────────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
▲ verify offline: browser page, single-file
HTML, or pure-stdlib Python CLI — zero trust
```
### 1. Signed swap receipts — a flight recorder for every order
Every lifecycle event of every order (`order_created`, `status_confirming`, `status_completed`, …) produces a receipt signed with the bridge's **Ed25519** key over canonical JSON. Receipts for one order are **hash-chained** (each embeds the SHA-256 of the previous receipt), so a user holding their final receipt can detect any retroactive edit to their order's history. Receipts carry a *hash* of the destination address, not the address — the proof layer never becomes a metadata leak.
```bash
curl -s https://your-bridge/v1/proof/receipt/br_ab12cd34ef56 | \
python3 tools/verify_receipt.py receipts - --pin <PUBLIC_KEY>
```
### 2. Post-quantum hybrid signatures
Receipts are archival evidence with a multi-decade shelf life. Alongside Ed25519, every receipt and checkpoint is signed with **ML-DSA-65 (FIPS 204, CRYSTALS-Dilithium)** over the same canonical bytes. Ed25519 stays the cheap, universally verifiable online layer; the ML-DSA signature keeps the archive forgery-proof against a future quantum adversary. Forging history requires breaking **both** schemes.
### 3. Transparency log — Certificate Transparency for a bridge
The audit hash-chain is sealed every few minutes into a **signed Merkle checkpoint** (the RFC 6962 construction used by Certificate Transparency, validated against the CT known-answer vectors). Anyone can then demand:
- **Inclusion proofs** — `GET /v1/proof/inclusion/{audit_id}` proves a specific audit entry is committed to by a checkpoint (log₂ n hashes, verifiable offline).
- **Consistency proofs** — `GET /v1/proof/consistency?old_size=&new_size=` proves a newer checkpoint is a pure append-only extension of an older one. **History cannot be rewritten without detection.**
Mirror `GET /v1/proof/checkpoint/latest` on a cron job and you become an external witness the operator cannot silently contradict.
### 4. The Sentinel — a circuit breaker between the bridge and catastrophe
Five guards run every 30 seconds:
| Guard | Trips when | Would have caught |
|-------|-----------|-------------------|
| Outflow velocity | per-chain outbound volume exceeds hourly caps | Ronin, Harmony (key-compromise drains) |
| Order velocity | order creation rate spikes | bot floods, probing attacks |
| Failure spike | failed orders cluster | subsystem exploitation |
| Rate divergence | independent price sources disagree > 5% | oracle poisoning |
| **ML anomaly** (optional) | Isolation Forest flags order-flow combinations vs the 7-day baseline | drain signatures no fixed threshold expresses |
A trip pauses **new intake only** — in-flight swaps keep settling, so a false positive costs minutes of intake, not user funds. The sentinel never auto-resumes: a human must investigate and resume with a note. Every trip, pause, and resume lands in the tamper-evident audit chain and the public `GET /v1/proof/status` endpoint — **the bridge cannot be paused or unpaused in secret**. The ML guard fails open: a risk-engine outage never blocks the bridge.
### 5. Signed, freshness-bound warrant canary
`GET /v1/proof/canary` returns a signed statement embedding the current time **and the latest checkpoint root** — it cannot be replayed against a rewound log. A canary that stops updating is itself a signal.
### Verify without trusting anything
Three independent verifiers ship in this repo, all validated against RFC 8032 test vectors and against each other:
| Verifier | Trust required |
|----------|---------------|
| `website /verify` page | verification runs client-side in your browser |
| [`verifier/umbra-verify.html`](verifier/umbra-verify.html) | **none** — save the file, open from `file://`, zero network requests, pure-BigInt Ed25519 with an on-load self-test |
| [`tools/verify_receipt.py`](tools/verify_receipt.py) | **none** — pure Python stdlib, no dependencies; `receipts`/`checkpoint`/`inclusion` subcommands |
Pin the bridge's public key (`GET /v1/proof/key`) out-of-band once; from then on, every receipt either verifies or it doesn't. Telegram users get the same via `/receipt <order_id>` and `/trust`.
The full wire-format specification — exact canonical forms, algorithms, threat model, and test vectors for building your own verifier — lives in [`docs/PROOF_LAYER.md`](docs/PROOF_LAYER.md).
### Supported Chains
| Chain | Ticker | Type |
|-------|--------|------|
| Monero | XMR | Privacy L1 |
| Bitcoin | BTC | L1 |
| Ethereum | ETH | L1 |
| TON | TON | L1 |
| Solana | SOL | L1 |
| Arbitrum | ARB | L2 (EVM) |
| Base | BASE | L2 (EVM) |
| USDT / USDC | Stablecoins | Multi-chain |
---
## Architecture
```
+------------------+
| Nginx Proxy |
| :80 / :443 |
+--------+---------+
|
+------------------+------------------+
| | |
/app | / | /api |
v v v
+--------+------+ +------+-------+ +-------+-------+
| Telegram Mini | | Next.js | | Rust Backend |
| App (Vite) | | Website | | (axum) |
| :3000 | | :3001 | | :8000 |
+----------------+ +--------------+ +---+---+-------+
| |
+------------------+ +--------+
| |
+-------v------+ +--------v-------+
| PostgreSQL | | Redis |
| :5432 | | :6379 |
+--------------+ +----------------+
|
+-------------------------------------------+
| |
+--------v-------+ +--------v--------+
| Telegram Bot | | Prometheus + |
| (aiogram) | | Grafana |
+----------------+ +-----------------+
```
**Single Rust binary** replaces what would typically be 3+ Python processes. The backend handles HTTP API, WebSocket streaming, background task scheduling, and blockchain RPC — all in one process using `tokio`.
---
## Three Interfaces, One Backend
### 1. Telegram Mini App
Mobile-optimized bridge UI that runs inside Telegram. Tap, swap, done.
### 2. Telegram Bot
Full conversational bridge — `/bridge`, `/rate`, `/history`, `/status`. Works without ever leaving the chat.
### 3. Enterprise Website
Desktop dashboard with portfolio tracking, analytics charts, order history, public transaction explorer, admin panel — plus `/verify` (client-side receipt verification) and `/transparency` (live sentinel status, checkpoints, canary).
All three share the same Rust API and real-time WebSocket feed.
---
## Tech Stack
| Layer | Technology |
|-------|-----------|
| **Backend** | Rust, axum 0.7, sqlx, tokio, tower |
| **Database** | PostgreSQL 17, Redis 7 |
| **MPC** | FROST threshold signatures (`frost-secp256k1`) |
| **Blockchain** | monero-wallet-rpc, toncenter, EVM JSON-RPC, Solana RPC, Bitcoin Core |
| **Website** | Next.js 15, React 19, Tailwind CSS 4, Zustand, Recharts, TON Connect |
| **Mini App** | Vite 6, vanilla JS, Telegram WebApp SDK |
| **Bot** | Python, aiogram 3, httpx |
| **Monitoring** | Prometheus, Grafana |
| **Proxy** | Nginx with rate limiting |
| **Rates** | CoinGecko -> Binance -> CoinCap (triple fallback) |
---
## Quick Start
```bash
# Clone
git clone https://github.com/beepboop2025/umbra.git
cd umbra
# Configure
cp backend/.env.example .env
# Edit .env with your keys (Telegram bot token, RPC endpoints, etc.)
# Launch everything
docker compose up --build
```
| Service | URL |
|---------|-----|
| Website | http://localhost |
| Mini App | http://localhost/app |
| API | http://localhost/api/health |
| Grafana | http://localhost:3002 |
| Prometheus | http://localhost:9090 |
---
## Project Structure
```
umbra/
├── backend/ # Rust API (axum + sqlx + tokio)
│ ├── src/
│ │ ├── routes/ # HTTP + WebSocket endpoints (incl. /v1/proof/*)
│ │ ├── services/ # Rates, orders, attestations, transparency, sentinel
│ │ ├── blockchain/ # Monero, Bitcoin, EVM, TON, Solana RPC clients
│ │ ├── mpc/ # FROST threshold signatures, coordinator, signers
│ │ ├── middleware/ # Security headers, rate limiting, Telegram auth
│ │ ├── tasks/ # Deposit monitor, confirmations, expiry, sentinel, sealing
│ │ ├── models/ # SQLx models (orders, rates, audit, MPC)
│ │ └── utils/ # Crypto helpers, address validation, RFC 6962 Merkle
│ └── migrations/ # PostgreSQL schema
├── bot/ # Telegram bot (aiogram 3)
│ └── bot/
│ ├── handlers/ # /start, /bridge, /rate, /history, /admin
│ ├── keyboards/ # Inline keyboards for bridge flow
│ └── services/ # Backend API client
├── website/ # Enterprise dashboard (Next.js 15)
│ └── src/
│ ├── app/ # Pages: bridge, dashboard, explorer, admin
│ ├── components/ # UI, bridge, charts, wallet, layout
│ ├── hooks/ # useRate, useOrders, useWebSocket, useWallet
│ ├── stores/ # Zustand state management
│ └── lib/ # API client, validators, utilities
├── src/ # Telegram Mini App (Vite)
├── risk-engine/ # Python risk service (FastAPI)
│ └── services/ # Isolation Forest, MAD z-score, drain scoring
├── verifier/ # Single-file offline verifier (umbra-verify.html)
├── tools/ # verify_receipt.py — pure-stdlib CLI verifier
├── docker-compose.yml # Full stack orchestration (10 services)
├── nginx.conf # Reverse proxy + rate limiting
└── monitoring/ # Prometheus + Grafana config
```
---
## How a Bridge Swap Works
```
1. User selects pair XMR -> TON, enters amount
2. Rate lock Cross-rate from CoinGecko (30s cache)
3. Sentinel gate Intake refused instantly if the circuit breaker is tripped
4. Order created Deposit address generated, 30min expiry, signed receipt #0
5. Deposit detected Monero wallet-rpc monitors subaddress
6. Confirmations 10 confirms for XMR, 1 for TON
7. MPC signing 2-of-3 FROST threshold signature
8. Withdrawal sent TON transfer broadcast
9. Complete Signed receipt binds the withdrawal tx hash;
user notified via WebSocket + Telegram
```
Every step from 4 onward emits a hash-chained, dual-signed receipt the user can verify offline — the order's history is provable end to end.
---
## Security
- **FROST 2-of-3 MPC** — No single party can sign transactions
- **Proof Layer** — Signed receipts (Ed25519 + ML-DSA-65), RFC 6962 transparency log, sentinel circuit breaker, signed canary (see above)
- **Hash-chain audit log** — Every state change is tamper-evident (SHA-256 chain), sealed into signed Merkle checkpoints
- **Telegram WebApp auth** — HMAC-SHA-256 verification of `initData`
- **Rate limiting** — Redis sliding window (60/min API, 10/min orders, 5 WS/IP)
- **Security headers** — CSP, HSTS, X-Frame-Options, X-Content-Type-Options
- **Argon2id** — Password hashing for admin accounts
- **JWT** — Admin authentication with configurable expiry
- **Anti-replay** — Nonce-based protection on order creation and MPC signing
- **Address validation** — Per-chain regex validation (XMR base58, BTC bech32, ETH checksum, TON friendly/raw, SOL base58)
### Key custody for the Proof Layer
The attestation identity is derived deterministically from `SECRET_KEY` by default (fine for development). In production set independent seeds — `ATTESTATION_SECRET_KEY` (Ed25519) and `ATTESTATION_PQ_SEED` (ML-DSA-65) — so receipt-signing custody can be separated from JWT custody, and publish the public keys from `GET /v1/proof/key` somewhere you don't control (a tweet, a git tag, another bridge's transparency page) so users can pin them.
---
## API Reference
### Rates
```
GET /v1/rate?direction=XMR_TO_TON Current rate + 24h change + sparkline
GET /v1/rate/history?direction=&period=1h Rate history (1h/4h/24h/7d/30d)
```
### Orders
```
POST /v1/order Create bridge order
GET /v1/order/:id Order details
GET /v1/orders?telegram_user_id=&limit=50 Order history
POST /v1/order/:id/cancel Cancel pending order
```
### WebSocket
```
WS /v1/ws/order/:id Real-time order status updates
WS /v1/ws/rates Live rate feed
```
### Proof Layer (public — no auth, by design)
```
GET /v1/proof/key Bridge public keys (Ed25519 + ML-DSA-65) — pin these
GET /v1/proof/receipt/:order_id Signed receipts for an order (full lifecycle)
GET /v1/proof/checkpoint/latest Latest signed Merkle tree head
GET /v1/proof/checkpoints?limit=20 Checkpoint history
GET /v1/proof/inclusion/:audit_id RFC 6962 inclusion proof for an audit entry
GET /v1/proof/consistency?old_size=&new_size= Append-only proof between two checkpoints
GET /v1/proof/audit/verify Server-side full hash-chain walk
GET /v1/proof/canary Signed, freshness-bound warrant canary
GET /v1/proof/status Sentinel state: accepting orders? why not?
```
### Risk Engine (internal, X-API-Key)
```
POST /v1/risk/anomaly Statistical drain scores (MAD z-score, burst, round amounts)
POST /v1/risk/anomaly/ml Isolation Forest anomaly scores over order-flow features
```
### Admin
```
POST /v1/admin/login JWT authentication
GET /v1/admin/stats System statistics
POST /v1/admin/order/:id/refund Manual refund
GET /v1/admin/sentinel Sentinel state + last 50 events
POST /v1/admin/sentinel/pause Manual pause (reason required)
POST /v1/admin/sentinel/resume Resume (investigation note required)
```
### System
```
GET /health Liveness probe
GET /ready Readiness probe (DB + Redis)
GET /metrics Prometheus metrics
```
---
## Monitoring
Prometheus scrapes the `/metrics` endpoint for:
- API request latency (p50/p95/p99)
- Order throughput and failure rate
- Rate source health and fetch duration
- WebSocket connection count
- Background task execution metrics
Grafana dashboards available at `:3002` (default password: `admin`).
---
## Development
```bash
# Backend only (requires local Postgres + Redis)
cd backend
cargo run
# Website only
cd website
npm install && npm run dev
# Mini App only
npm run dev
# Run backend tests
cd backend
cargo test
```
---
## Environment Variables
See [`backend/.env.example`](backend/.env.example) for the full list. Key ones:
| Variable | Description |
|----------|-------------|
| `SECRET_KEY` | JWT signing key (64+ chars) |
| `TELEGRAM_BOT_TOKEN` | From @BotFather |
| `MONERO_RPC_URL` | monero-wallet-rpc endpoint |
| `TON_API_URL` | toncenter API |
| `ETH_RPC_URL` | Ethereum JSON-RPC |
| `BRIDGE_FEE_PERCENT` | Fee per swap (default: 0.3%) |
| `MPC_THRESHOLD` | Signatures required (default: 2) |
| `ATTESTATION_SECRET_KEY` | Ed25519 receipt-signing seed, 64 hex chars (derived from `SECRET_KEY` if unset) |
| `ATTESTATION_PQ_SEED` | ML-DSA-65 seed, 64 hex chars (derived if unset) |
| `PQ_SIGNATURES_ENABLED` | Post-quantum hybrid signatures (default: true) |
| `TRANSPARENCY_SEAL_INTERVAL_SECS` | Checkpoint sealing cadence (default: 300) |
| `CANARY_STATEMENT` | Warrant-canary text served at `/v1/proof/canary` |
| `SENTINEL_ENABLED` | Circuit breaker (default: true) |
| `SENTINEL_OUTFLOW_CAPS` | Per-chain hourly caps, e.g. `XMR:1000,BTC:20` |
| `RISK_ENGINE_URL` | Enables the Isolation Forest sentinel guard (optional) |
---
## License
Source-available under the [Source-Available License v1.0](LICENSE.md). You may view, study, fork, and run it locally for non-commercial evaluation and research. Commercial use, operating it as a service, or redistribution require a separate written license.