Citadel 2

Private credentials. Public confidence. Prove, don’t reveal.

This repository contains the implementation of Citadel 2, the second generation of the Dusk-oriented self-sovereign identity protocol. Citadel 2 refines the original design with a simpler protocol boundary, stronger domain separation and validation rules, request-based issuance, and a clearer security model. A user requests an encrypted license from a License Provider, proves on-chain in zero knowledge that a registered license exists, and discloses a session cookie to a Service Provider that applies its own policy.

The protocol reference is docs/specs.md. The threat model and residual risks are documented in docs/security.md. Our implementation is based on the original idea from this paper.

⚠️ DISCLAIMER: the code in this repository has not gone through an exhaustive security review, so it is not intended to be used in a production environment.

This repository is structured as follows:

• 💻 Core: protocol objects, request/license/session workflows, domain-separated helpers, Citadel Schnorr transcripts, and the license circuit.
• 📝 License Contract: license registry, Merkle root history, proof verification, session registry, and deployment metadata.
• 💼 Wallet: host-side CLI/TUI for Citadel wallet, deployment, and contract interactions.
• 📜 Docs: the normative protocol specification and threat model for Citadel.

Getting Started

Use the Rust toolchain from rust-toolchain.toml. The root Makefile is the preferred entry point for local and CI workflows.

All build, test, benchmark, and wallet targets compile in release mode. The ZK targets keep Cargo default features enabled while adding zk, so dusk-plonk/std remains enabled and PlonK can use its parallel std/rayon path.

Build Contract

make contract

Builds the release contract artifacts, ensures the wasm32-unknown-unknown target is installed, and compiles the contract wasm as described in contract/README.md.

Test Contract

make test-contract

Builds contract artifacts first, then runs the contract VM tests.

Test Core

make test-core

Runs the core test suite in release mode with zk enabled.

Benchmarks

make bench

Runs the core benchmarks with zk enabled. To compile benchmarks without running them, use:

make bench BENCH_ARGS=--no-run

Test Wallet

make test-wallet

Runs the wallet test suite in release mode.

Run Wallet

make run-wallet

Builds and runs the Citadel wallet. Pass CLI arguments with WALLET_ARGS:

make run-wallet WALLET_ARGS="--help"

License

This project is licensed under the Mozilla Public License 2.0.