Architecture
Knot is five crates that fit together: two contracts on Dusk, shared signing helpers, a Lab you run locally, and an optional shared mailbox.
Crates
| Crate | License | Role in plain terms |
|---|---|---|
knot-encoding | Apache-2.0 | Builds the bytes everyone signs; fingerprints for compare |
knot-registry | Apache-2.0 | On-chain groups and quorum checks |
knot-proposals | Apache-2.0 | Propose, approve, then run the action |
knot-tool | Apache-2.0 | Local Lab: CLI + browser UI (mock or testnet) |
knot-collector | AGPL-3.0-only | Optional mailbox for proposal files and partials |
Apache pieces and the AGPL collector stay separate on purpose. Secret keys stay in the Lab; the collector never sees them.
Another layer: Atlas
Other products live in their own repos and call Knot as a client. Knot works alone.
Atlas is the reference service-directory to pair with Knot: named services, roles, and a consistent admin gate on top of an M-of-N council. Each product can delay. Two delays stack. If Knot already waits after quorum, leave Atlas timelock_blocks at 0 so the wait is not stacked. Atlas stays optional.
How the pieces connect
Left to right: keys stay on your machine, the Lab talks to the chain, and an optional mailbox sits off to the side.
| Piece | Holds keys? | Sends chain transactions? |
|---|---|---|
Lab (knot-tool) | Yes (on your machine only) | Yes (gas-paying writes) |
| Collector mailbox | No | No |
| Registry / Proposals | No | They are the contracts |
Lab modes
Starting the Lab (knot-tool serve) requires an explicit mode:
| Mode | What you get |
|---|---|
mock | Fake in-memory ledger for demos; still uses real local signing; no live chain submit |
testnet | Talks to real DuskDS testnet (reads + gas-paying writes) |
If DEMO_MODE is missing or unknown, the Lab refuses to start. It listens on loopback only (default 127.0.0.1:8877). You open a one-shot bootstrap link; the browser gets a session cookie and never receives secret keys.
Talking to the chain
- Writes (create group, submit quorum, change members, proposal steps, and similar): the Lab shells out to
rusk-wallet. That costs testnet gas and needsRUSK_WALLET_PWD. - Reads (look up an account, proposal status, and similar): plain HTTP to the node with raw binary bodies. Do not hex-encode those request bodies - the node will misread them.
Method-level detail: Contracts. Cold start: Run locally.