> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/product-suite/decentralization-manager.md). # Decentralization Manager ## Overview Decentralization Manager is the open-source framework for creating and managing Decentralized Parties and governed applications on Canton Network. It is currently in public beta. Use it to coordinate operators, configure governance, and deploy application logic through the Generalized Governance Core, Token Management Module, and Custody Module. Run it self-hosted, or use the BitSafe-hosted Admin UI where available. ## Features * **Web-Based Management UI**: React frontend for managing decentralized parties * **Multi-Party Onboarding**: Coordinated workflow for creating decentralized party namespaces * **Contract Deployment**: Upload DAR files and deploy governance contracts with multi-party signing * **Governance Actions**: View and manage governance confirmations with threshold-based execution * **Participant Management**: View party membership, kick participants with threshold-based voting * **OAuth Authentication (Keycloak or Auth0)**: Supports M2M (client\_credentials) and password flows for Ledger API access, with a per-node choice of provider for both frontend gating and outbound Canton tokens * **Secure P2P Communication**: Noise Protocol Framework for encrypted coordinator to peer communication * **Real-time Status**: Live peer connectivity monitoring and workflow progress tracking * **Canton Integration**: Native gRPC integration with Canton Admin and Ledger APIs ## Documentation * [Introduction](/product-suite/decentralization-manager/introduction.md): Start here - what Decentralization Manager does and why to decentralize your application on Canton * [Architecture Overview](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ARCHITECTURE.md): System architecture, core concepts, communication protocol, and technical constraints * [User Guide](https://github.com/DLC-link/decentralization-manager/blob/main/USER_GUIDE.md): Walkthrough of the web UI for day-to-day party and governance operations * [Custom DAML Templates](https://github.com/DLC-link/decentralization-manager/blob/main/docs/CUSTOM_DAML_TEMPLATES.md): Authoring and deploying your own DAML governance templates * [Contributing Guide](https://github.com/DLC-link/decentralization-manager/blob/main/docs/CONTRIBUTING.md): Development setup, coding standards, commit conventions, and the PR process ### Security The Decentralization Manager was audited by Quantstamp (May 2026). The full audit report is available here: [Quantstamp Audit Report](https://certificate.quantstamp.com/full/bitsafe-dec-manager/9d0b465f-46c1-41bc-8d56-cfb3d3c44a76/index.html) ## Architecture The application runs as an HTTP server with an embedded React frontend. Multiple instances coordinate via the Noise Protocol: * **Coordinator**: Initiates workflows and orchestrates multi-party operations * **Peers**: Respond to coordinator commands, sign proposals, and execute local operations * **Automatic Key Management**: Noise keypairs are generated automatically on first run ``` ┌─────────────────┐ Noise Protocol ┌─────────────────┐ │ Participant 1 │◄───────────────────────►│ Participant 2 │ │ (Coordinator) │ │ (Peer) │ │ HTTP :8081 │ │ HTTP :8082 │ │ Noise :9001 │ │ Noise :9002 │ └────────┬────────┘ └────────┬────────┘ │ │ │ Canton Network │ └───────────────────┬───────────────────────┘ │ ┌────────▼────────┐ │ Canton Nodes │ │ (Admin/Ledger │ │ APIs) │ └─────────────────┘ ``` ## Quick Start ### Prerequisites * Rust toolchain (for building from source) * Access to Canton participant nodes (Admin API and Ledger API) * Docker (optional, for containerized deployment) ### Running Locally ```bash # Build and run with env vars DECPM_DIR=./development/participant-1 \ DECPM_PORT=8081 \ DECPM_CANTON_ADMIN_HOST=localhost \ DECPM_CANTON_ADMIN_PORT=5002 \ DECPM_CANTON_ADMIN_LEDGER_HOST=localhost \ DECPM_CANTON_LEDGER_PORT=5001 \ DECPM_NOISE_PORT=9001 \ cargo run -- serve # Or with a .env file in the data directory cargo run -- -d ./development/participant-1 serve # Or with release build cargo build --release DECPM_PORT=8081 ./target/release/dec-party-manager -d ./development/participant-1 serve ``` Open [http://localhost:8081](http://localhost:8081/) in your browser. ### Running with Docker ```bash # Build the image docker build -t dec-party-manager . # Run a single instance docker run -p 8080:8080 -v ./data:/data \ -e DECPM_CANTON_ADMIN_HOST=canton-node \ -e DECPM_CANTON_ADMIN_PORT=5002 \ -e DECPM_CANTON_LEDGER_HOST=canton-node \ -e DECPM_CANTON_LEDGER_PORT=5001 \ -e DECPM_NOISE_PORT=9001 \ -e DECPM_CANTON_SYNCHRONIZER=global \ -e DECPM_CANTON_NETWORK=devnet \ dec-party-manager ``` ### Running Multiple Participants (Development) ```bash cd development docker compose up ``` This starts three participant instances on ports 8081, 8082, and 8083. ## Configuration All node configuration is done via environment variables (prefixed `DECPM_*`) or CLI arguments. The `--dir` (`-d`) flag points to a directory for persistent data. If a `.env` file exists in that directory, it is loaded automatically before parsing CLI arguments. ### Directory Structure ``` participant-dir/ ├── .env # Optional environment file (loaded automatically) └── data/ ├── noise.key # Auto-generated Noise keypair ├── decpm.db # SQLite database (peers, party credentials) └── dars/ # DAR files for contract deployment ``` The database file path can be overridden with the `--db` CLI flag. ### Environment Variables | Variable | Description | Default | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `DECPM_DIR` | Root directory for persistent data (`--dir`/`-d`) | . | | `DECPM_HOST` | Host address to bind the HTTP/UI server to | `0.0.0.0` | | `DECPM_PORT` | Port for the HTTP/UI server | `8080` | | `DECPM_DB_PATH` | SQLite database path override (CLI flag `--db`) | (defaults to `{dir}/data/decpm.db`) | | `DECPM_DB_ENCRYPTION_KEY` | Encryption key for secrets stored in the database | (none) | | `DECPM_ADMIN_ROLE` | Role name that gates sensitive endpoints (unset skips the role check) | (none) | | `DECPM_ALLOWED_ORIGIN` | Origin permitted by CORS (for example `https://dpm.example.com`) | (none, same-origin only) | | `DECPM_LISTEN_ADDRESS` | Address to listen on for Noise protocol connections | `0.0.0.0` | | `DECPM_NOISE_PORT` | Port for Noise protocol connections | `9000` | | `DECPM_PUBLIC_ADDRESS` | Public address that peers use to connect to this node | (falls back to listen address) | | `DECPM_CANTON_ADMIN_HOST` | Canton Admin API host | `127.0.0.1` | | `DECPM_CANTON_ADMIN_PORT` | Canton Admin API port | `5002` | | `DECPM_CANTON_LEDGER_HOST` | Canton Ledger API host | `127.0.0.1` | | `DECPM_CANTON_LEDGER_PORT` | Canton Ledger API port | `5001` | | `DECPM_CANTON_SYNCHRONIZER` | Canton synchronizer name | `global` | | `DECPM_CANTON_NETWORK` | Canton network environment (`devnet`, `testnet`, `mainnet`) | `devnet` | | `DECPM_KEYCLOAK_URL` | Keycloak server URL for frontend auth | (none) | | `DECPM_KEYCLOAK_REALM` | Keycloak realm name for frontend auth | (none) | | `DECPM_KEYCLOAK_CLIENT_ID` | Keycloak client ID for frontend auth | (none) | | `DECPM_KEYCLOAK_INTERNAL_URL` | Internal/backchannel Keycloak URL the server uses for OIDC discovery, JWKS, and introspection when it cannot reach the public Keycloak URL directly | DECPM\_KEYCLOAK\_URL | | `DECPM_AUTH0_DOMAIN` | Auth0 tenant domain for frontend auth (mutually exclusive with the Keycloak variables) | (none) | | `DECPM_AUTH0_CLIENT_ID` | Auth0 SPA client ID for frontend auth | (none) | | `DECPM_AUTH0_AUDIENCE` | Auth0 API audience the SPA's access tokens target | (none) | | `DECPM_TIMEOUT_HANDSHAKE` | Noise handshake timeout in seconds | 30 | | `DECPM_TIMEOUT_MESSAGE` | Noise message timeout in seconds | 120 | | `DECPM_TIMEOUT_RETRY_ATTEMPTS` | Connection retry attempts | 3 | | `DECPM_TIMEOUT_RETRY_DELAY` | Connection retry delay in seconds | 5 | | `DECPM_NOISE_RETRY_TIMEOUT_SEC` | Per-attempt timeout for the bounded peer-Noise retry wrapper, in seconds | 5 | | `DECPM_NOISE_RETRY_MAX_ATTEMPTS` | Total attempts (initial plus retries) for the bounded peer-Noise retry wrapper | 2 | | `DECPM_NOISE_RETRY_BACKOFF_MS` | Backoff between attempts of the bounded peer-Noise retry wrapper, in milliseconds | 250 | ## API Reference The manager exposes an HTTP API for configuration, workflow orchestration, and governance. A complete, interactive reference is available via the Swagger UI at /swagger-ui/ (OpenAPI document at /api-docs/openapi.json). Note that these interactive endpoints are only mounted in development and test builds; the shipped release image does not expose them. The main endpoint groups are: * Node and network configuration: node and network info, peer list management, and per-party credential configuration. * Decentralized parties: listing parties and viewing participant connectivity and key status. * Workflows: starting, tracking, cancelling, retrying, and dismissing the onboarding, contracts, and kick workflows, plus managing invitations. * Authentication: checking authentication status and testing outbound identity-provider auth per party. * Governance: viewing governance state and confirmations, and submitting, executing, expiring, or cancelling governance actions. * Contracts and services: querying deployed vaults, provider/user/registrar services, active contracts by template, configured package IDs, and token-standard contracts. * DAR distribution: uploading DARs to the current node, distributing them across all participants, and tracking distribution progress.