Concepts

Knot is about one idea: enough of the right people signed the same action. This page names the pieces without assuming you already know the contracts.

Prove vs Coord

Two ways people talk about "is this quorum good enough?"

• Prove - the chain checks again for itself: are these signers current members? Is the threshold met? Do the signatures verify? Your inputs are evidence; the contract does not take your word for it.
• Coord - an off-chain tool says "quorum met" and the chain trusts that without an equal check.

Knot's contracts are Prove. The Lab helps you sign; it is not the final yes/no for on-chain writes. More detail: Security.

A group (registry account)

A registry account is a named group: a list of member public keys and a threshold (for example 2-of-3).

The registry answers one question: did enough current members sign this message? It does not hold money. For most messages it also does not decide what the message means - your app must put its own domain label, action, and replay protection (nonce or similar) into those bytes.

Anyone can create an account and name other people's keys as members. That does not give the creator control of those keys. After create, read the account back (and the returned id) before you wire it into another contract - do not guess the id.

To change members or threshold later, current members sign a change_account message. That path has its own digest format and includes the on-chain nonce, so replays of old change signatures fail.

Two ways to check a quorum

Style	What happens on-chain
One-by-one	verify_quorum checks each signature separately
Aggregate	verify_quorum_aggregate checks one combined signature

Aggregation is a Dusk strength: one expensive check instead of one per signer. Live clients use the secure post-hardfork signing APIs.

Cheap "free read" verify calls over the node HTTP API are useful for debugging only. Do not treat them as proof that a real transaction would succeed - use real writes and account reads for that.

Proposals (propose, approve, finalize)

A proposal is a structured action: which contract to call, which function, which arguments, and a deadline. Members approve by signing a digest built from those fields (plus chain and contract context in v3).

Anyone may open a proposal, pass approvals around, or call finalize once enough approvals exist. That lets a funded helper pay gas while members hold no DUSK.

On finalize, the proposals contract runs the action via call_raw (a low-level call into the target contract). The target must check that the caller is the proposals contract - Knot does not keep a list of allowed targets.

Any human-readable summary attached off-chain is display-only. Sign from the canonical fields, not from the summary text.

Delay (timelock)

After the group has signed, the action can still wait. Each registry account has timelock_blocks (default 0).

• 0 - membership changes and finalize apply in the same call
• Above 0 - membership sits in pending until anyone calls execute_pending; proposals go Queued until anyone calls execute after execute_at
• deadline is "must run by"; delay is "must not run before"
• If now + delay would pass the deadline, finalize refuses - pick a later deadline
• Cancel is immediate (a new quorum). The wait is a window to stop a stolen-key action, not another signature delay

The Lab's Delay (blocks) field is this knob.

Another layer: Atlas

Knot is the council. Atlas is a different job: a named service directory, roles, and a consistent admin gate. It can sit on those councils.

Atlas can delay its own admin path too. Two delays on one intent means two waits. If Knot already delays, leave Atlas timelock_blocks at 0. Knot does not need Atlas; Atlas is the extra layer when you want services and roles named in one place.

Signing gate (anti blind-sign)

Before you sign, the Lab recomputes the digest from the proposal fields and refuses if it does not match what you were asked to sign (gate_blob_for_signing / recompute_and_verify in knot-encoding).

That gate is what stops blind signing and a lying collector from tricking you into the wrong intent.

Co-signers can also compare a full fingerprint of the digest (hex, or a 24-word mnemonic of the full hash). Never truncate the hash for compare.

Why no separate key-possession ceremony

Membership keys use Dusk's multisig construction that resists rogue-key attacks. Knot does not require a separate "prove you own this key" ceremony just to list a key as a member.

Sharing work: blobs and collector

A ProposalBlob is a portable file: the proposal fields plus any partial signatures collected so far. You can pass that file around yourself (chat, USB, your own channel).

An optional collector is a small HTTP service that stores those blobs so people do not have to email JSON. It never holds keys, never signs, and never submits chain transactions. See Collector.