Skip to content

refactor: Switch stQRL from rebasing to fixed-balance model #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
moscowchill merged 1 commit into from
Mar 12, 2026
Merged

refactor: Switch stQRL from rebasing to fixed-balance model #11

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 93 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@ QuantaPool enables QRL holders to participate in Proof-of-Stake validation witho
- **Fixed-Balance Token**: Share balance stays constant (tax-friendly), QRL value grows with rewards
- **Slashing-Safe**: Fixed-balance design handles slashing by proportionally reducing all holders' QRL value
- **Trustless Sync**: No oracle needed - rewards detected via EIP-4895 balance increases
- **Post-Quantum Secure**: Built on QRL's Dilithium signature scheme
- **Post-Quantum Secure**: Built on QRL's Dilithium ML-DSA-87 signature scheme
- **Production Infrastructure**: Terraform + Ansible for automated validator deployment
- **Monitoring Stack**: Prometheus, Grafana dashboards, and Alertmanager with Discord/Telegram alerts

## Architecture

Expand All @@ -27,7 +29,7 @@ QuantaPool enables QRL holders to participate in Proof-of-Stake validation witho
│ - Accepts deposits, mints stQRL shares │
│ - Queues and processes withdrawals │
│ - Trustless reward sync via balance checking │
│ - Funds validators (MVP: stays in contract) │
│ - Funds validators via beacon deposit contract │
└───────────────────────────┬─────────────────────────────────┘
│ mintShares() / burnShares()
▼
Expand All @@ -42,17 +44,58 @@ QuantaPool enables QRL holders to participate in Proof-of-Stake validation witho
┌─────────────────────────────────────────────────────────────┐
│ ValidatorManager.sol │
│ - Tracks validator states (pending → active → exited) │
│ - Stores Dilithium pubkeys (2,592 bytes) │
│ - MVP: single trusted operator model │
└─────────────────────────────────────────────────────────────┘
└───────────────────────────┬─────────────────────────────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌──────────────────────┐ ┌──────────────────────────────┐
│ Infrastructure │ │ Monitoring │
│ Terraform + Ansible │ │ Prometheus + Grafana │
│ gzond, qrysm nodes │ │ Contract exporter + alerts │
└──────────────────────┘ └──────────────────────────────┘
```

## Project Structure

```
QuantaPool/
├── contracts/solidity/ # Solidity smart contracts (source of truth)
│ ├── stQRL-v2.sol # Fixed-balance liquid staking token
│ ├── DepositPool-v2.sol # Deposits, withdrawals, reward sync
│ └── ValidatorManager.sol # Validator lifecycle tracking
├── hyperion/ # Hyperion language port (.hyp mirrors)
│ ├── contracts/ # Auto-synced from Solidity sources
│ └── test/
├── test/ # Foundry test suite (217 tests)
│ ├── stQRL-v2.t.sol # 55 core token tests
│ ├── DepositPool-v2.t.sol # 68 deposit/withdrawal tests
│ ├── ValidatorManager.t.sol# 55 validator lifecycle tests
│ └── Audit-*.t.sol # 39 security audit-driven tests
├── infrastructure/ # Production validator deployment
│ ├── terraform/ # Hetzner Cloud provisioning
│ ├── ansible/ # Node configuration (gzond, qrysm)
│ ├── scripts/ # deploy.sh, failover.sh, health-check.sh
│ └── docs/ # Runbooks and deployment guides
├── monitoring/ # Observability stack
│ ├── prometheus/ # Scrape config + alert rules
│ ├── grafana/ # Dashboards (validator, contract, system)
│ ├── alertmanager/ # Discord/Telegram routing by severity
│ └── contract-exporter/ # Custom Node.js exporter for on-chain metrics
├── key-management/ # Validator key lifecycle scripts
├── scripts/ # Build & deployment automation
├── config/ # Network deployment configs
└── docs/ # Architecture docs
```

## Contracts

| Contract | Purpose |
|----------|---------|
| `stQRL-v2.sol` | Fixed-balance liquid staking token |
| `DepositPool-v2.sol` | User entry point, deposits/withdrawals, reward sync |
| `ValidatorManager.sol` | Validator lifecycle tracking |
| Contract | LOC | Purpose |
|----------|-----|---------|
| `stQRL-v2.sol` | 496 | Fixed-balance liquid staking token (shares-based) |
| `DepositPool-v2.sol` | 773 | User entry point, deposits/withdrawals, trustless reward sync |
| `ValidatorManager.sol` | 349 | Validator lifecycle: Pending → Active → Exiting → Exited |

Solidity sources are maintained under `contracts/solidity/`. Hyperion mirrors live separately under `hyperion/contracts/` so the `.hyp` port does not get mixed into the Foundry tree.

Expand All @@ -69,6 +112,30 @@ If slashing occurs (pool drops to 950 QRL):
- User's `getQRLValue()` = 100 × 950 / 1000 = **95 QRL**
- Loss distributed proportionally to all holders

## Infrastructure

Production-ready validator infrastructure using Terraform and Ansible.

**Components provisioned:**
- **Primary validator node** — gzond (execution) + qrysm-beacon + qrysm-validator
- **Backup validator node** — hot standby with failover script
- **Monitoring server** — Prometheus, Grafana, Alertmanager

**Key management scripts** handle the full Dilithium key lifecycle: generation, encryption, backup, restore, and import to the validator client.

See `infrastructure/docs/DEPLOYMENT.md` for the step-by-step deployment guide and `infrastructure/docs/runbooks/` for operational procedures.

## Monitoring

Docker Compose stack providing full observability:

- **Prometheus**: Scrapes metrics from gzond, qrysm-beacon, qrysm-validator, and the custom contract exporter
- **Grafana**: Three dashboards — Validator Overview, Contract State, System Resources
- **Alertmanager**: Routes alerts by severity (Critical/Warning/Info) to Discord and Telegram
- **Contract Exporter**: Custom Node.js service exposing on-chain metrics (stQRL exchange rate, TVL, deposit queue, validator count)

See `monitoring/README.md` for setup and configuration.

## Development

### Prerequisites
Expand Down Expand Up @@ -104,31 +171,41 @@ npm run deploy:hyperion

See `hyperion/README.md` for the dedicated Hyperion layout and deploy config.

### CI

GitHub Actions runs `forge fmt --check`, `forge build --sizes`, and `forge test -vvv` on every push and pull request.

## Test Coverage

- **173 tests passing** (55 stQRL-v2 + 63 DepositPool-v2 + 55 ValidatorManager)
- **217 tests passing** across 10 test files
- **Core tests** (178): stQRL-v2 (55), DepositPool-v2 (68), ValidatorManager (55)
- **Audit-driven tests** (39): Critical findings (QP-01, QP-05), PoC reproductions, FIFO queue, buffered QRL edge cases, post-fix verification
- Share/QRL conversion math, multi-user rewards, slashing scenarios
- Withdrawal flow with delay enforcement
- Withdrawal flow with 128-block delay enforcement
- Validator lifecycle (registration, activation, exit, slashing)
- Access control and pause functionality
- All error paths and revert conditions
- Event emission verification
- Admin functions (ownership, pause, emergency)
- Virtual shares to prevent first-depositor attacks
- Access control, pause functionality, and reentrancy protection
- Fuzz testing for edge cases

## Status

**v2 contracts ready** - awaiting Zond testnet deployment.
**v2 contracts ready** — infrastructure and monitoring built, awaiting Zond testnet deployment.

### Roadmap

- [x] v2 fixed-balance contracts with audit remediations
- [x] Validator infrastructure (Terraform + Ansible)
- [x] Monitoring and alerting stack
- [x] Key management tooling
- [ ] Deploy v2 contracts to Zond testnet
- [ ] Integrate staking UI into [qrlwallet.com](https://qrlwallet.com)

## Security

- Slither static analysis completed (0 critical/high findings)
- See `slither-report.txt` for full audit results
- Audit-driven test suite covering critical findings QP-01 and QP-05
- Virtual shares (1e3) to prevent first-depositor/inflation attacks
- See `slither-report.txt` for full analysis results

## Acknowledgments

Expand Down