Directory authority specification

Introduction

Katzenpost is a project for building mixnets tuned to different uses¹. Each network starts with a fixed group of computers called directory authorities (DAs). We usually call them dirauths. Different parties operate these dirauths, whether or not they trust one another. Their shared configuration defines the network and which nodes may join it.

Namenlos, the first public post-quantum hybrid mixnet, is one Katzenpost deployment². Operators create other networks by choosing parameters and allowed nodes, then distributing configurations to authorities, other servers, and end users.

The dirauths publish a signed network consensus document, or consensus, for each epoch, a fixed-length time period. Publication requires a simple majority to sign the same document and the network constraints to be met. The consensus gives users the network’s agreed view for that epoch. It supplies node keys, topology, and traffic rates for Katzenpost Sphinx packets. It is the network’s public-key infrastructure (PKI) document.

Nodes submit signed descriptors that announce their identities, addresses, keys, and roles. Authorities accept announcements only from allowed identities and include those that receive enough votes. Applications on one host SHOULD share one local kpclientd daemon. The daemon verifies the consensus before it uses the network. Nodes renew their announcements, and authorities repeat the process for the next epoch.

Namenlos network map

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: network
    accTitle: Configured Namenlos nodes and packet paths
    accDescr: Six configured directory authorities publish a consensus with at least four signatures. Users verify it through kpclientd. Packets use one of four gateways and one mix per layer. The mix layers contain two, two, and three mixes. Four service nodes host mixnet services. Courier services use four storage replicas. Each node role has its own icon and each node has its configured name.
    subgraph CONTROL["Directory authorities"]
        direction TB
        CONFIG["Shared authority configuration<br/>and allowed node identities"] --> AUTH["6 directory authorities<span class='node-roster authorities'><span class='node-badge role-authority'>annares</span><span class='node-badge role-authority'>gnunet</span><span class='node-badge role-authority'>luscus</span><span class='node-badge role-authority'>respectmy</span><span class='node-badge role-authority'>wauland</span><span class='node-badge role-authority'>windfall</span></span>"]
        AUTH -->|"4 or more matching signatures"| CONS["<img src='/docs/specs/dirauth/icons/directory.svg' alt='' width='32' height='32'/><br/>Consensus for one epoch<br/>Node keys, topology, and rates"]
    end
    subgraph PATH["Mixnet packet paths"]
        direction TB
        CLIENT["<img src='/docs/specs/dirauth/icons/client.svg' alt='' width='32' height='32'/><br/>User applications<br/>through kpclientd"] -->|"choose one gateway"| GW["4 gateways<span class='node-roster'><span class='node-badge role-gateway'>allmixedup</span><span class='node-badge role-gateway'>gnunet</span><span class='node-badge role-gateway'>haywood</span><span class='node-badge role-gateway'>waulandgateway</span></span>"]
        GW --> L1["Mix layer 1<span class='node-roster'><span class='node-badge role-mix'>windfall</span><span class='node-badge role-mix'>cryptonymity</span></span>"]
        L1 --> L2["Mix layer 2<span class='node-roster'><span class='node-badge role-mix'>omelas</span><span class='node-badge role-mix'>mixy</span></span>"]
        L2 --> L3["Mix layer 3<span class='node-roster'><span class='node-badge role-mix'>oneeyedman</span><span class='node-badge role-mix'>reed</span><span class='node-badge role-mix'>wauland</span></span>"]
        L3 -->|"choose one service node"| SN["4 service nodes<span class='node-roster'><span class='node-badge role-service'>annares</span><span class='node-badge role-service'>lilly</span><span class='node-badge role-service'>waulandservice</span><span class='node-badge role-service'>windfallservice</span></span>"]
        SN -. "courier storage requests" .-> REP["4 storage replicas<span class='node-roster'><span class='node-badge role-replica'>storagereplica0</span><span class='node-badge role-replica'>storagereplica1</span><span class='node-badge role-replica'>storagereplica2</span><span class='node-badge role-replica'>storagereplica3</span></span>"]
    end
    CONS -. "Consensus to client<br/>via gateway" .-> CLIENT
    class CONFIG,CLIENT local
    class AUTH,CONS directory
    class GW,L1,L2,L3,SN,REP link
    linkStyle 1,8 stroke:#f3bd66,stroke-width:2px
    linkStyle 2,3,4,5,6 stroke:#c3abff,stroke-width:2px
    linkStyle 7 stroke:#7acee9,stroke-width:2px
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

This network uses the Namenlos configuration. Six dirauths require four matching signatures. Packet routes use one gateway, one mix per layer, and one service node. Only allowed nodes with enough votes enter the consensus. Prerequisites distinguish configured counts from publication minimums.

History

This protocol continues the original Katzenpost PKI design, described in KATZMIXPKI. That design already used configured authorities, node allow-lists, and a majority-signed consensus. The post-quantum hybrid protocol adds new key schemes, encodings, node roles, and voting phases.

Conventions

The glossary defines shared terms. MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY have the meanings in RFC 2119. Reference tables and requirements appear in linked appendices.

The post-quantum hybrid protocol

The network configuration fixes membership and keys. In each voting round, dirauths agree on a consensus of signed directory data. Participants exchange that data over authenticated connections under the security requirements.

Network membership and node roles

Configured authority keys define which directory authorities a participant trusts. The authorities’ shared allow-lists define which other nodes can enter the consensus.

Node roles

The node roles include gateways, which connect clients to the mixnet. Mixes relay packets through layers, and service nodes host application endpoints. Storage replicas support Pigeonhole. The topology groups mixes into ordered layers. Node keys follow the cryptographic schemes.

Prerequisites

Clients need a usable consensus to reach mixnet services under the network prerequisites. Authorities can publish that consensus only when the network requirements are met.

All parties in a network MUST use the same epoch duration, cryptographic schemes, and packet geometry.

Layers is the configured number of mix layers. MinNodesPerLayer is the minimum configured mix count per layer.

At startup and reload, an authority MUST require at least Layers * MinNodesPerLayer configured mixes, one gateway, and one service node. A fixed topology MUST also meet MinNodesPerLayer in each layer. At signing, every mix layer MUST be non-empty. At least one gateway and one service node MUST remain (R-16-6).

One authority cannot complete voting, which needs at least two contributors. Let A be the number of configured authorities. Publication requires floor(A/2)+1 matching signatures (threshold). Replica requirements depend on the storage service (Pigeonhole).

Namenlos configures six authorities, seven mixes across three layers, four gateways, four service nodes, and four storage replicas. Its fixed layers contain two, two, and three mixes.

Client software and configuration

Applications on one host SHOULD share one local kpclientd daemon through the thin_client interface.

kpclientd fetches the consensus through a configured gateway. It MUST verify the consensus before use. The client configuration supplies gateway pins and the authority verification keys. The Namenlos configurations give example values.

Mixnet services

A mixnet service provides an application endpoint on a service node. Clients use an accepted consensus to find the mixnet service and select a route to it.

A service node lists its mixnet services in its descriptor’s Kaetzchen field. Each entry names a capability and a client endpoint. Clients reach the service through the mixnet without revealing their network addresses to it. Authorities copy Kaetzchen into the consensus under R-5-9. Mixnet services have no separate descriptor.

The courier service forwards requests to Pigeonhole storage replicas. Couriers and replicas can fetch the consensus directly from authorities.

Epochs and timing

Epoch boundaries set deadlines for uploads, votes, and publication. Each consensus names the epoch it describes.

Constants and notation

Each consensus covers one fixed-length time period, called an epoch. The current epoch has a number, denoted N. Each epoch has the same duration, denoted P. T is the instant that epoch N starts. Elapsed time is t = now - T. An authority prepares a document for a voting epoch, denoted V. In a normal round, the voting epoch is the next epoch: V = N+1.

The notation reference gives definitions and Namenlos example values.

Time

The network divides time into epochs. Every participant MUST use the same epoch length and starting point.

Epoch 0 starts at Z = 2017-06-01 00:00:00 UTC. Epoch N starts at Z + N*P. The next epoch starts at Z + (N+1)*P. P ranges from 2 minutes to 7 days, with a default of 1200 seconds. R-9-3 defines how a party selects P. Namenlos leaves EpochDuration unset, which selects the default unless the environment overrides it.

Phase boundaries scale with P. operation defaults indexes operation defaults and fixed time values.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: clock
    accTitle: Repeating epoch cycle
    accDescr: Epoch 0 starts at Z. Each turn lasts P, which is 1200 seconds or 20 minutes in the Namenlos configuration. At each boundary the epoch number increases, the start time advances by P, and elapsed time resets to zero.
    ZERO["Epoch 0 starts at Z<br/>N = 0, T = Z"] --> START(("Start epoch N<br/>at T<br/>t = 0"))
    START --> ELAPSED(("During epoch N<br/>0 <= t < P<br/>P = 20 min<br/>in Namenlos"))
    ELAPSED --> BOUNDARY(("After P seconds<br/>N = N + 1<br/>T = T + P"))
    BOUNDARY -->|"Next epoch<br/>t = 0"| START
    class ZERO,START,ELAPSED,BOUNDARY local
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

An epoch includes its start and excludes its end. The exact end boundary belongs to the next epoch. The clock also gives till, the time until the next epoch. At an absolute instant now at or after Z, the epoch clock is:

N       = floor((now - Z) / P)
T       = Z + N * P
t       = now - T
till    = P - t

Requirements R-9-1 through R-9-6.

Directory objects and signatures

Nodes announce their keys in descriptors. Authorities exchange signed proposals and publish a signed consensus. Producers MUST use canonical Concise Binary Object Representation (CBOR). Receivers MUST apply the decoding rules.

Descriptors

A descriptor announces one node’s identity, addresses, and keys. The node signs its upload so authorities can verify who sent it.

Mixes, gateways, and service nodes post a MixDescriptor. Storage replicas post a ReplicaDescriptor.

Descriptor fields

A node announces its identity, addresses, keys, and role in the descriptor fields. Its role determines the required fields.

An authority keeps SoftwareVersion and ContactInfo only when [Server].AcceptDescriptorMetadata is true, which defaults to false. Otherwise, it removes both fields after signature verification, before validation, storage, voting, and comparison.

Upload encoding and signatures

Mix servers and storage replicas use different upload structures. Each structure binds the descriptor to the node’s signature.

The upload types are SignedUpload and SignedReplicaUpload. LoopStats contains MixIdentityHash (32 bytes or null), Epoch (uint64), and SegmentRatios (64-byte segment ID to float64). To verify a signature, the authority decodes the upload, sets Signature to null, and re-encodes it canonically. The consensus preserves these descriptor encodings.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: publisher
    accTitle: Descriptor upload encodings
    accDescr: SignedUpload contains descriptor bytes and an inline LoopStats map. SignedReplicaUpload contains an inline replica map. Both contain an inline signature and sign their structure with Signature null.
    MIX["<img src='/docs/specs/dirauth/icons/mix.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/gateway.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/service.svg' alt='' width='32' height='32'/><br/>SignedUpload<br/>Signature: inline map<br/>MixDescriptor: byte string<br/>containing descriptor CBOR<br/>LoopStats: inline map or null"]
    REPLICA["<img src='/docs/specs/dirauth/icons/replica.svg' alt='' width='32' height='32'/><br/>SignedReplicaUpload<br/>Signature: inline map<br/>ReplicaDescriptor: inline map"]
    MIX --> INPUT["Canonical CBOR<br/>with Signature = null"]
    REPLICA --> INPUT
    INPUT --> SIGN["Sign with the node identity key"]
    class MIX,REPLICA local
    class INPUT,SIGN directory
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

Validation stages

Authorities verify an upload before they admit its descriptor. Consumers also parse keys when they use them.

The upload handler parses the identity key and verifies the signature and session binding. Descriptor validation verifies names, addresses, roles, and the current mix key. An upload receiver accepts empty future mix-key values, but their indexes MUST remain within NumMixKeys. Replica uploads require a non-empty envelope-key map with non-empty values. Upload validation imposes no replica-epoch window. Consumers parse other keys when they use them. Authorities verify retained metadata at upload.

Length and parsing alone do not establish that a public key is non-degenerate. The X25519 parser and X448 parser require the scheme’s public-key length. Sphinx rejects an all-zero derived shared secret during packet construction and unwrapping (construction, unwrapping). CTIDH parsing also rejects the base curve E0 and verifies supersingularity.

Requirements R-5-1 through R-5-11.

Votes and voting certificates

A vote is an authority’s signed proposal for the next consensus. It contains node announcements, traffic rates, notices, and a commitment to a random contribution.

A commitment fixes the contribution before its reveal. A reveal opens that commitment so peers can verify the contribution.

A voting certificate carries a tallied document and the matched signed commitment/reveal pairs the sender holds. Peers use these certificates to reconcile contributions before computing the shared random value.

The consensus document

The consensus describes the network for one epoch. Nodes and clients use it to select peers and apply shared settings.

A consensus lists allowed nodes whose descriptors receive enough votes (R-16-2). It records the full configured set only for replicas. A consumer MUST NOT infer other configured node sets from it. Missing nodes can have failed to upload.

Traffic rates

Traffic rates control packet frequency and mix delays. Authorities vote on the rates that the consensus publishes.

A traffic rate measures events per millisecond. Its inverse is the mean waiting time in an exponential distribution. Rates use float64 values. R-16-3 tallies five rates. R-16-8 derives LambdaG. The mixing strategy defines how these rates control traffic. Authority configuration replaces zero with 0.00025 for each voted rate and rejects negative values. It does not test finiteness (defaults and validation).

Signed document fields

The consensus stores the network description in one signed body. Votes and voting certificates use the same document structure.

The Document structure defines the signed fields. Document validation verifies them in votes, voting certificates, and the consensus.

Full document validation rejects duplicate identities across Topology, GatewayNodes, and ServiceNodes, but not StorageReplicas. An empty PriorSharedRandom is valid only when GenesisEpoch equals Epoch. Consumer validation differs by fetch path (gateway consensus transfer).

The decoder treats null and absent keys as empty. An encoder MUST preserve the distinctions in the field reference.

Votes supply five rates, descriptors, and notices. Reconciled commit/reveal pairs supply the shared random value (SRV), which seeds automatic topology assignment. Epoch is V. R-18-7 to R-18-9 define genesis and history. LambdaG, geometry hash, scheme, and configured replicas come from local configuration and MUST agree across authorities. Signatures remain outside the body in its certificate envelope. Descriptor nesting follows upload encoding. Commit/reveal map values contain serialized certificate envelopes.

R-6-5 limits mixing delays. SafetyCap is 27632 milliseconds at Mu = 0.001 and 110525 at Mu = 0.00025. Debug.DisableServicePreDelay disables the service-node hold. The authority’s [Notice] table defaults to empty.

Deterministic CBOR

Producers MUST encode equal data as identical bytes. Deterministic CBOR defines the encoding that every participant uses.

Producers MUST encode descriptors, documents, and certificate envelopes with deterministic CBOR.

Requirements R-6-1 through R-6-7.

Keys and schemes

Identity signatures authenticate directory data. Link and Sphinx keys protect different parts of mixnet communication.

Nodes and authorities have identity signing keys and link key encapsulation mechanism (KEM) keys. Mix servers also have Sphinx keys per epoch. Replicas have envelope non-interactive key exchange (NIKE) keys per replica epoch. Sphinx uses NIKE or KEM keys. Every network uses the same replica envelope scheme. Parties MUST configure matching schemes. Signature scheme details give component sizes and platform defaults. The Namenlos profile defines the deployed byte formats.

Certificate envelopes and signing

A certificate envelope holds data and the signatures that authenticate it. Several authorities can sign the same data.

Envelope fields

The envelope separates the payload from its signatures. Authorities can add signatures without changing the payload.

A certificate envelope holds a payload and its signatures. The implementation defines five fields:

• Version, a uint32 that is 0
• Expiration, an epoch
• KeyType, the scheme name
• Certified, a byte string containing the payload bytes
• Signatures, a map from signer hash to PublicKeySum256 and Payload

Producers MUST use canonical CBOR and the configured signature scheme name. Receiver decoding and envelope verification define accepted encodings and signature verification. The decoded envelope Version MUST be zero. KeyType MUST be nonempty and forms part of the signed message. The document schema has a separate Version field, “v1”.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: signer
    accTitle: Certificate signature input
    accDescr: Version, expiration, scheme name, and certified payload form the signed message. The envelope stores signatures outside that message.
    META["Version<br/>Expiration<br/>KeyType<br/>Certified: payload bytes"] --> MSG["signed message bytes"]
    MSG --> SIGN["sign with the identity key"]
    SIGN --> SIG["store signature in Signatures"]
    class META,MSG,SIG local
    class SIGN directory
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

Certified contains document CBOR, a raw 40-byte commit/reveal, or one CBOR cert.Signature for sig commands. Descriptor uploads use separate structures.

Signature input

Every signature covers the same four envelope fields. The signature map itself remains outside that input.

The signed message concatenates four fields with no separator and no length prefix:

signed_message = LE_uint32(Version)
              || LE_uint64(Expiration)
              || KeyType, the UTF-8 bytes of the scheme name
              || Certified

Requirements R-7-1 through R-7-7.

Byte identity

Authorities can combine signatures only when they build identical consensus bytes. Shared encoding, ordering, and configuration make this possible.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: authority
    accTitle: Four threshold gates and consensus byte identity
    accDescr: With six authorities, require four matching parameter votes, four voting certificates, four surviving commit/reveal pairs, and four valid signatures. Local configuration and history also enter the signed bytes.
    QV{"4 matching parameter<br/>votes"} --> QC{"4 voting certificates"}
    QC --> QR{"4 surviving commit/reveal<br/>pairs"}
    INPUTS["Inputs<br/>Voted and reconciled values<br/>Carried history<br/>Local configuration"]
    QR --> INPUTS
    INPUTS --> BODY["Build the signed body"]
    BODY --> CBOR["Canonical CBOR bytes"]
    CBOR --> MSG["Certificate signing bytes"]
    MSG --> SIG["Signatures over identical bytes"]
    SIG --> TH{"4 valid signatures over<br/>identical bytes"}
    TH --> PUB["<img src='/docs/specs/dirauth/icons/directory.svg' alt='' width='32' height='32'/><br/>Published consensus"]
    class QV,QC,QR,BODY,SIG,TH directory
    class INPUTS,CBOR,MSG,PUB local
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

Namenlos has A = 6. The general threshold is floor(A/2)+1. Document inputs, CBOR, signature input, SRV ordering and wire encoding MUST produce identical bytes. Different configuration or history can prevent signatures from combining.

Requirements R-26-1 through R-26-8.

A successful voting round

Nodes announce their keys for the next epoch. In a successful round, dirauths agree on one signed consensus. Clients fetch it through gateways and verify it before use.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
sequenceDiagram
    %% panel: network
    %% actors: N=other-servers,D=authority,G=gateway,C=client
    accTitle: Directory round
    accDescr: Mixes, service nodes, replicas, and gateways upload signed descriptors. Dirauths compare votes, reveal randomness, and collect majority signatures. Servers fetch the signed consensus. Clients fetch it through gateways and verify it before use. Each role follows its configured fetch schedule.
    autonumber
    box rgb(26,40,48)
        participant N as Mixes<br/>Service nodes<br/>Replicas
    end
    box rgb(49,38,23)
        participant D as Dirauths
    end
    box rgb(26,40,48)
        participant G as Gateway
    end
    box rgb(45,48,54)
        participant C as Client<br/>kpclientd
    end
    loop One successful round
        N->>D: Upload signed<br/>descriptors
        G->>D: Upload signed<br/>descriptor
        D->>D: Compare votes
        D->>D: Reveal randomness
        D->>D: Sign the same<br/>consensus
        D->>D: Publish at majority
        N->>D: Fetch consensus
        D-->>N: Signed consensus
        G->>D: Fetch consensus
        D-->>G: Signed consensus
        C->>G: Fetch consensus
        G-->>C: Signed consensus
        C->>C: Verify consensus
    end

Phases

Each voting round follows a fixed schedule. Different phases collect node announcements, exchange votes, and publish the next consensus.

The authority state machine starts each phase’s sends and computations at its boundary. The diagram uses P = 1200 seconds. Its times are offsets after T. Phase fractions measure elapsed time from T as a share of P.

Authority phases, node uploads and fetches.

Fetch retries follow R-10-9 to R-10-11. The descriptor upload rules are in R-10-3.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
sequenceDiagram
    %% panel: clock
    %% actors: N=other-servers,D=authority,G=gateway,C=client
    accTitle: Epoch phase schedule
    accDescr: Node uploads end at 125 seconds during Phase_DESC. Dirauth phases advance at 150-second boundaries. Mixes, gateways, and service nodes fetch at 750 seconds. Couriers, replicas, and clients fetch at 825 seconds. Clients fetch through gateways. Mixes, gateways, and service nodes admit next-epoch peers strictly after 1050 seconds. The next epoch starts at 1200 seconds.
    box rgb(26,40,48)
        participant N as Mixes<br/>Service nodes<br/>Replicas
    end
    box rgb(49,38,23)
        participant D as Dirauths
    end
    box rgb(26,40,48)
        participant G as Gateway
    end
    box rgb(45,48,54)
        participant C as Client<br/>kpclientd
    end
    Note over N,C: 0-150 s: Phase_DESC
    N->>D: Until 125 s:<br/>signed descriptors
    G->>D: Until 125 s:<br/>signed descriptor
    Note over D: 150-300 s:<br/>Phase_VOTE
    D->>D: Send votes
    Note over D: 300-450 s:<br/>Phase_REVEAL
    D->>D: Send reveals
    Note over D: 450-600 s:<br/>Phase_CERT
    D->>D: Tally and send<br/>certificates
    Note over D: 600-750 s:<br/>Phase_SIG
    D->>D: Build and sign<br/>the consensus<br/>Exchange<br/>signatures
    Note over N,C: 750-1050 s: Phase_PUB
    D->>D: Publish N+1<br/>at threshold
    N->>D: Mixes and<br/>service nodes:<br/>fetch N+1<br/>from 750 s
    D-->>N: Consensus N+1
    G->>D: Fetch N+1<br/>from 750 s
    D-->>G: Consensus N+1
    N->>D: Couriers and<br/>replicas:<br/>fetch N+1<br/>from 825 s
    D-->>N: Consensus N+1
    C->>G: Fetch N+1<br/>from 825 s
    G-->>C: Consensus N+1
    Note over N,C: 1050-1200 s: Phase_TAIL
    N->>N: Mixes and<br/>service nodes:<br/>admit N+1 peers<br/>strictly after<br/>1050 s
    G->>G: Admit N+1 peers<br/>strictly after<br/>1050 s
    D->>D: Gone if N+1<br/>is missing
    Note over N,C: 1200 s: Epoch N+1 starts

Each send window starts at its phase boundary and ends according to R-10-1 and R-10-8.

Requirements R-10-1 through R-10-14.

Phase_DESC. Descriptor upload

Nodes MUST attempt descriptor uploads to every configured authority. Retries MAY omit authorities that already accepted that descriptor. Nodes MAY fetch a consensus from any configured authority.

Nodes send signed announcements with post_descriptor or post_replica_descriptor. After upload validation, the authority applies the descriptor storage rules. It compares an existing descriptor before it tests whether it voted or published.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
stateDiagram-v2
    %% panel: authority
    direction TB
    accTitle: Descriptor storage and replay
    accDescr: A dirauth stores one live descriptor per command epoch and node identity after upload validation. The authority persists an accepted upload before retaining its descriptor. Identical canonical descriptors succeed even after voting or publication. A finality race can persist an upload without retaining its descriptor.
    state "No live descriptor" as Empty
    state "Descriptor retained" as Stored
    [*] --> Empty
    Empty --> Stored: No own vote<br/>or consensus:<br/>persist and retain,<br/>DescriptorOk 0
    Empty --> Empty: Own vote or consensus<br/>before or after writing:<br/>DescriptorConflict 2
    Stored --> Stored: Same: DescriptorOk 0<br/>Changed:<br/>DescriptorConflict 2

An authority MUST serialize uploads per node identity across epochs. Different identities MAY proceed concurrently. DescriptorInternalError triggers an uploader retry. A failure to persist the upload is fatal to the authority. DescriptorInvalid, DescriptorForbidden, and DescriptorConflict are final for that authority, as is a strict QUIC pin mismatch (R-24-11). R-14-10 defines durable storage before acknowledgment.

Requirements R-14-1 through R-14-10.

Phase_VOTE, Phase_REVEAL. Commit and reveal

Authorities exchange random contributions in two steps. Each authority commits to a value before it reveals that value.

With RN a 32-byte random value and H = BLAKE2b-256, each commit or reveal is 40 bytes:

RN     = 32 bytes from the random source
REVEAL = BE_uint64(epoch) || H(RN)
COMMIT = BE_uint64(epoch) || H(REVEAL)

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
sequenceDiagram
    %% panel: authority
    %% actors: A=authority,B=authority
    accTitle: Commit and reveal exchange
    accDescr: Dirauth 1 sends its vote and commitment to Dirauth 2. During the reveal phase it sends the signed reveal. Dirauth 2 checks the reveal against the stored commitment and returns the relevant status.
    box rgb(49,38,23)
        participant A as Dirauth 1
    end
    box rgb(49,38,23)
        participant B as Dirauth 2
    end
    Note over A,B: Phase_VOTE, from P/8
    A->>B: vote 22, Epoch V, PublicKey<br/>Document with one commit
    B-->>A: vote_status 23, VoteOk 0
    Note over A,B: Phase_REVEAL, from 2/8
    A->>B: reveal 25, PublicKey<br/>Signed 40-byte reveal
    B->>B: Verify reveal<br/>against stored<br/>commit
    B-->>A: reveal_status 26, RevealOk 8
    Note over B: No stored commit:<br/>RevealTooEarly 9<br/>From 3/8:<br/>RevealTooLate 13

R-15-8 prevents an authority from contributing a late commit during the reveal phase. Without this restriction, it could observe other reveals before deciding whether to contribute its own committed value.

Requirements R-15-1 through R-15-8.

Phase_CERT, Phase_SIG. Tabulation

Each authority counts votes for node announcements and traffic settings. Only results with enough matching votes enter the consensus.

The tally compares descriptor and parameter bytes. R-16-3 keeps signed zeros separate and groups NaNs. History comes from the prior consensus, not a vote tally. R-16-6 separates startup provisioning from per-epoch topology usability.

Requirements R-16-1 through R-16-8.

Phase_CERT. Voting certificates

Authorities exchange certificates that summarize the contributions they received. Other authorities verify this evidence before they compute the shared random value.

A voting certificate contains the tallied document and commit/reveal pairs in a signed envelope. Authorities send it between the reveal and signature phases. The receiver verifies voting certificates before it computes the SRV.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
sequenceDiagram
    %% panel: authority
    %% actors: A=authority,B=authority
    accTitle: Voting certificate exchange
    accDescr: Dirauth 1 tallies its votes and sends its voting certificate. Dirauth 2 verifies the cited signatures and pairs under the document validation rules, then returns a certificate status.
    box rgb(49,38,23)
        participant A as Dirauth 1
    end
    box rgb(49,38,23)
        participant B as Dirauth 2
    end
    Note over A,B: Phase_CERT, from 3/8
    A->>A: Tally votes<br/>Build full<br/>document
    A->>B: cert 29, Epoch V, PublicKey<br/>Document with every held pair
    B->>B: Verify cited<br/>signatures from<br/>authorized<br/>authorities
    B->>B: Validate reveals<br/>against commits
    B-->>A: cert_status 30, CertOk 14
    Note over B: Validation failure:<br/>CertNotSigned 17<br/>Sender's vote<br/>missing:<br/>CertTooEarly 19<br/>From 4/8:<br/>CertTooLate 15

Document validation treats exactly one commit as a vote and rejects a reveal alongside it. A certificate built from matched commitments and reveals needs at least two pairs to pass validation. The zero-commit receiver case does not inspect reveals. A one-authority network cannot complete this phase. An authority sends no voting certificate if its tally lacks a usable topology or it has exactly one pair. It still advances to the next phase.

Reconciliation compares complete serialized commit and reveal certificate envelopes, after signature verification. Equal 40-byte payloads do not establish envelope equality. Differences in signatures or other envelope bytes can produce a conflict. R-6-1 permits an additional signature during individual-envelope verification. It does not change the equality comparison during reconciliation. The SRV calculation uses the extracted 40-byte reveal, not its envelope.

Requirements R-17-1 through R-17-9.

Phase_SIG. Shared random value and topology

Authorities combine verified random contributions into one shared value. This value controls automatic mix placement and links the round to the previous round.

The authority needs at least a threshold of voting certificates before reconciliation. It needs the same threshold of surviving commit/reveal pairs before it computes the SRV. The epoch in this calculation is the voting epoch V. H is BLAKE2b-256 and PREV is the previous epoch’s SRV or 32 zero bytes. The authority computes the shared random value as follows:

SRV = H( "shared-random"
      || BE_uint64(epoch)
      || identity_hash(1) || reveal(1)
      || ...
      || identity_hash(k) || reveal(k)
      || PREV )

Each reveal is the 40-byte certified payload of that authority’s signed reveal. R-18-2 gives the order of the k pairs.

The Namenlos authority config pins three fixed layers. With gateways configured, document construction requires a fixed Topology. Omitting it reaches a nil topology during LambdaG calculation. The automatic assignment subroutine defines automatic layer placement. An empty resulting layer prevents signing.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: authority
    accTitle: Shared random value and automatic topology
    accDescr: Hash the domain label, voting epoch, ordered identity and reveal pairs, and previous shared random value. The output seeds the automatic topology draw, which also uses prior placement when available.
    INPUT["Inputs in byte order:<br/>label shared-random<br/>BE_uint64(V)<br/>identity / reveal pairs in R-18-2 order<br/>previous SRV or 32 zero bytes"] --> HASH["BLAKE2b-256"]
    HASH --> SRV["SharedRandomValue:<br/>32 bytes"]
    SRV --> STREAM["ChaCha20:<br/>8-byte zero nonce"]
    STREAM --> DRAW["Automatic topology draw<br/>with prior placement, if held"]
    DRAW --> TOPOLOGY["Topology:<br/>mix layers"]
    class INPUT,HASH,SRV,STREAM,DRAW,TOPOLOGY directory
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

Requirements R-18-1 through R-18-10.

The topology draw and layer assignment define the complete automatic placement algorithms.

Phase_SIG, Phase_PUB. Signatures and publication

Each authority signs the consensus it built. Matching signatures let the authorities publish that document for the network.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
sequenceDiagram
    %% panel: network
    %% actors: A=authority,B=authority,N=publisher
    accTitle: Signature receipt and publication
    accDescr: Each dirauth signs its own consensus and sends the signature to every peer. A receiver verifies the envelope before storing the inner signature. At publication it attaches only signatures that authenticate its own consensus, then publishes at threshold.
    box rgb(49,38,23)
        participant A as Dirauth 1
    end
    box rgb(49,38,23)
        participant B as Dirauth 2
    end
    box rgb(26,40,48)
        participant N as Fetching node
    end
    Note over A,B: Phase_SIG, from 4/8
    A->>A: Tally votes<br/>Compute SRV<br/>Build and sign<br/>doc V
    A->>B: sig 27, Epoch V<br/>Signed cert.Signature envelope
    B->>B: Verify envelope<br/>Parse and store<br/>inner signature
    B-->>A: sig_status 28, SigOk 20
    Note over A,B: Every dirauth sends to every peer
    Note over A,B: Phase_PUB, at 5/8
    A->>A: Verify stored<br/>inner signatures<br/>against own<br/>consensus
    A->>A: Attach valid<br/>signatures<br/>At threshold:<br/>publish and<br/>persist doc V
    N->>A: get_consensus 18, Epoch N+1
    A-->>N: consensus 19, ConsensusOk 0

Requirements R-19-1 through R-19-4.

Receiver states, failures, and retention

Receiver state controls message acceptance. Epoch windows limit how long documents and keys remain usable.

The authority state machine

After startup or restart, an authority enters bootstrap to select its voting epoch. Each authority runs the same sequence of voting steps. Timers move the authority from one step to the next. If processing misses a deadline, the next timer fires immediately. Remaining phases run in sequence. If an action panics, the authority recovers and retries that state after one second.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
stateDiagram-v2
    %% panel: authority
    accTitle: Authority state machine
    accDescr: Bootstrap selects a voting epoch. Descriptor, vote, reveal, certificate, and signature states advance on timers. Publication succeeds at threshold or returns to bootstrap.
    state "Signatures" as accept_signature
    [*] --> bootstrap: start or<br/>restart
    bootstrap --> accept_desc: t <= P/8, V =<br/>N+1
    bootstrap --> bootstrap: t > P/8, wait<br/>for next epoch
    accept_desc --> accept_vote: 1/8, send vote
    accept_vote --> accept_reveal: 2/8, send<br/>reveal
    accept_reveal --> accept_cert: 3/8, tally and<br/>send cert
    accept_cert --> accept_signature: 4/8, build and<br/>sign consensus
    accept_signature --> accept_desc: 5/8, threshold<br/>reached,<br/>publish
    accept_signature --> bootstrap: 5/8, no<br/>threshold

Requirements R-12-1 through R-12-5.

Acceptance windows and status codes

An authority accepts messages only for the round it is processing. Response codes tell a sender whether to retry or stop.

An authority can publish consensus N during the preceding epoch, N-1. Its scheduled publication time is T - 3*P/8, before epoch N starts. After successful publication, it advances V to N+1 and can accept votes and commits for that voting epoch.

Vote, reveal, cert, and sig handlers use V and authority state to decide acceptance. They do not compare elapsed time. Handlers evaluate phase and duplicate status only for messages at epoch V. Vote, voting certificate, and signature handlers verify the command’s Epoch field. The reveal handler verifies the epoch in the signed payload and ignores the command’s Epoch field.

After building its voting certificate, an authority can still accept a valid vote for the consensus tally until it enters the signature state. Its existing voting certificate does not change. NotFound permits a retry. Gone is final for N+1 and past epochs. A courier also retries Gone for its current epoch.

Requirements R-13-1 through R-13-3.

Clocks and retention

Authorities manage clock and retention settings outside this protocol. Operators SHOULD keep clocks within a few seconds of UTC. The timing margins depend on delivery time, retries, and successful preceding phases. They are not clock synchronization targets.

A reveal, detached-signature envelope, or commit for N+1 passes expiration verification only through the receiver’s epoch N. A document, vote, or voting certificate for N remains unexpired through epoch N+4. Other validation rules still apply.

The replica clock gives RE = floor((now - Z) / 604800 seconds), independently of P. A client MAY adjust its clock from the gateway handshake.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: clock
    accTitle: Independent epoch and key lifetimes
    accDescr: Mixnet epochs have length P. Mix servers retain keys N-1 through N+3 and publish N+1 through N+3. Replica epochs always last seven days. Shared-random history rotates every 504 mixnet epochs, except initialization takes precedence.
    subgraph M["<img src='/docs/specs/dirauth/icons/mix.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/gateway.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/service.svg' alt='' width='32' height='32'/><br/>Mixes, gateways, and service nodes<br/>Mix keys: epoch length P"]
        direction TB
        MK["Retain mix keys N-1 through N+3"]
        MK --> USE["Unwrap with N-1, N, and N+1"]
        USE --> ADV["Advertise N+1 through N+3"]
    end
    subgraph R["<img src='/docs/specs/dirauth/icons/replica.svg' alt='' width='32' height='32'/><br/>Replica clock: 7 days"]
        RK["Publish RE and RE+1,<br/>plus RE-1 while retained"]
        RK --> DEL["Older key deletion:<br/>3-hour grace"]
    end
    subgraph H["<img src='/docs/specs/dirauth/icons/authority.svg' alt='' width='32' height='32'/><br/>Dirauth shared-random history"]
        INIT["Initialize at genesis or empty history"]
        INIT --> ROT["Otherwise rotate every 504 epochs"]
    end
    M ~~~ R ~~~ H
    class MK,USE,ADV packet
    class RK,DEL local
    class INIT,ROT directory
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

504 epochs equal seven days only at P = 1200 seconds. Replica epochs do not scale with P.

Requirements R-11-1 through R-11-6.

Connections and messages

Directory commands travel over encrypted links. Each connection also applies peer authorization and resource limits.

Transport layers

Directory commands carry signed CBOR objects directly over PQ Noise, outside Sphinx packets. The direct consensus reply gives the directory encoding and link records. PQ Noise protects each connection over TCP or QUIC.

Descriptor map keys and URL schemes select transports and address protocols. The mix server’s address conversion places tcp:// IPv4 addresses under tcp4 and tcp:// IPv6 addresses under tcp6.

Mix-server dialing selects map keys tcp4, tcp6, and quic (transport selectors). A tcp entry alone cannot provide a mix-server destination. Replicas instead preserve the lowercased URL scheme as the descriptor map key (replica conversion). Their outgoing connections use ClientTransports, which includes tcp (replica dialing). Upload validation accepts more URL schemes than mix servers publish (R-5-6).

Authorities use configured address lists, not descriptors. Their listeners accept tcp:// and quic:// URLs only (listeners). Mixes, gateways, and service nodes MUST advertise a reachable tcp4 or tcp6 entry. Replicas MUST advertise a reachable tcp entry. Authorities MUST advertise a reachable tcp:// endpoint. A dialer uses QUIC only with the peer’s pinned QUIC key hash (QUIC transport).

PQ Noise carries commands over each transport. An authority PKI session carries one command and one reply unless configuration enables persistent peer connections (R-22-15). kpclientd uses a persistent gateway session for packets, replies, and consensus retrieval (connection loop).

An authority MUST accept only commands allowed for the sender’s role. It MUST drop others without reply (R-23-4).

Wire protocol

A command carries one request or response. PQ Noise encrypts each command and its length before it sends them.

Commands travel over the PQ Noise link: pattern PqXX, ChaChaPoly, BLAKE2b-512, the configured KEM and a one-byte prologue 0x03. The handshake profile defines its four flights. The responder MUST send NoOp as its first transport command. Each command uses two encrypted Noise transport messages in the data-transfer phase. The first encrypts the four-byte big-endian command-ciphertext length. Its tag makes this header 20 bytes. The second encrypts the command with a separate 16-byte tag. The length includes the second tag. Each endpoint MUST rekey the affected direction after both encrypted messages (sender, receiver).

Before encryption, a command has a 6-byte header, command_id (1) || reserved (1, zero) || BE_uint32(body_length), and a body. PublicKey is the sender’s full marshaled identity key. The command reference defines each Payload type.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: data
    accTitle: Six-byte plaintext command header
    accDescr: Byte zero is command_id. Byte one is zero. Bytes two through five are the unsigned big-endian body length. The declared body follows, then any zero padding.
    CID["Byte 0<br/>command_id: 1 byte"] --> ZERO["Byte 1<br/>reserved: zero"]
    ZERO --> LENGTH["Bytes 2-5<br/>body length: uint32, big-endian"]
    LENGTH --> BODY["Body: the declared number of bytes"]
    BODY --> PADDING["Optional zero padding"]
    class CID,ZERO,LENGTH,BODY local
    class PADDING local
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

The wire session selects the Noise primitives. Noise uses BLAKE2b-512. The directory’s H is BLAKE2b-256. The command encoders define the bodies and command constants define their IDs.

Direct authority fetchers send empty additional data to identify an unauthenticated client. kpclientd’s gateway handshake carries a generated queue identifier and keeps the session open.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
sequenceDiagram
    %% panel: layers
    %% actors: I=initiator,R=authority
    accTitle: Authority link framing
    accDescr: The initiator establishes TCP or QUIC and completes PqXX with an authority. The authority sends NoOp first. Each command and reply has an encrypted length header and separate ciphertext. Each sender rekeys after its two messages.
    box rgb(26,40,48)
        participant I as Initiator<br/>Node, dirauth,<br/>or client
    end
    box rgb(49,38,23)
        participant R as Dirauth
    end
    I->>R: TCP or QUIC connect
    I->>R: PqXX, prologue 0x03
    Note over I: Node or dirauth:<br/>AD = identity hash<br/>Unauthenticated client:<br/>empty AD
    R-->>I: PqXX handshake<br/>Static link key
    R-->>I: NoOp: first encrypted command
    I->>R: Encrypted length header<br/>20 bytes including tag
    I->>R: Command ciphertext<br/>Separate 16-byte tag
    I->>I: Rekey sending<br/>direction
    R-->>I: Reply length header<br/>then reply ciphertext
    R->>R: Rekey sending<br/>direction
    I->>I: Close or reuse<br/>persistent<br/>authority link

Gateway consensus transfer

Clients fetch the consensus through their gateway connection. The gateway compresses the document and sends it in chunks.

kpclientd MUST fetch the consensus through a configured gateway with get_consensus2. It uses its existing gateway connection. On success, the gateway gzip-compresses the signed consensus envelope and sends consensus2 chunks numbered 0 through ChunkTotal-1. The chunk capacity comes from the connection’s configured packet geometry. An error uses one empty chunk, ChunkNum 0 and ChunkTotal 1, with the consensus status code below (gateway handler).

The client MUST verify chunk order, totals, and sizes before it decompresses the envelope. It MUST verify the authority signature threshold, requested epoch, and local geometry before using the consensus. Chunks carry one document. Gateway commands have separate padding and size bounds from direct authority sessions.

The direct authority fetcher also calls IsDocumentWellFormed before accepting a consensus (fetch validation). kpclientd’s gateway path uses Deserialize to verify the signature threshold and decode the document (Deserialize). It also verifies epoch and geometry, but does not call IsDocumentWellFormed (client verification).

A client reports Gone only when replies from queried authorities make a signing threshold impossible. With fewer Gone replies, it can retry.

Receive size ceiling

A size ceiling bounds the largest directory command a receiver accepts. The default ceiling depends on network size and cryptographic sizes.

R-22-17 uses EstimateConsensusSize. The ceiling bounds the command ciphertext, including its 16-byte tag. The encrypted 20-byte length header is separate. Let sign and sig be the PKI scheme’s public-key and signature sizes. Let link, sphinx and envelope be the public-key sizes of the wire KEM, Sphinx scheme, and replica NIKE. Let nodes, replicas, and authorities be their counts.

mix      = sign + link + 3 * sphinx + 4096
replica  = sign + link + 3 * envelope + 4096
unsigned = 8192 + nodes * mix + replicas * replica
signed   = unsigned + authorities * (sig + 96)
                   + 2 * authorities * (sig + 96 + 40)
ceiling  = min(500000000, max(262144, 2 * signed))

The factor 3 counts per-epoch keys. The 4096 and 8192 allowances cover names, addresses, service data and framing. The 96 covers the signature key hash and framing. The 40 counts a shared-random value. The second authority term includes commit and reveal envelopes in a voting certificate. The final factor 2 provides headroom.

An authority uses its configured counts of mixes, gateways, service nodes, replicas, and authorities. Before its first consensus, a client uses 64 nodes and 16 replicas. A configured MaxConsensusSize above zero replaces the calculated ceiling for that party.

Requirements R-22-1 through R-22-18.

Authentication and authorization

Authorities distinguish configured nodes from unauthenticated clients. Each role has its own permitted commands.

The authority listener authorizes peers by role. Gateway clients use a separate path. Allow-lists map identity hashes to names, adding ReplicaID for replicas and a pinned link key for authorities. Lookup order is mix/gateway/service, authority, then replica. Unauthenticated fetchers, including couriers and replicas, send empty additional data and a fresh random link key. R-23-7 permits unpinned nodes to upload. Their identity signature and session-key binding remain mandatory.

Requirements R-23-1 through R-23-7.

Authority message delivery

Authorities send each voting message to every peer. A retry loop handles temporary failures while the voting schedule continues.

All four message families use one retry loop. Default backoff starts at 10 ms. A 3-second cap applies before 0.2 jitter, so delays can approach 3.6 seconds (calculation). Phase sends use the deadline, with an additional retry cap when PeerRetryMaxAttempts is positive. Bootstrap defaults to 20 retries plus the initial attempt. After a bounded wait, the loop can start an attempt without testing the deadline again. The state machine advances independently of delivery. A peer needs the sender’s vote and commit before it can accept the reveal.

Requirements R-21-1 through R-21-4.

QUIC transport

A node or authority MAY listen on QUIC as well as TCP. PQ Noise authenticates the peer over one QUIC stream. QUIC also requires a pinned TLS key. The dialer MUST compare SHA-256 of the certificate’s SubjectPublicKeyInfo with QUICKeyHash. For nodes, the hash comes from the descriptor. Authorities use configured hashes. Before its first consensus, a client uses its configured gateway hash.

Mixes, service nodes, and replicas rotate TLS keys each epoch. Each key comes from a random Ed25519 seed in DataDir/quic. Gateways with QUIC listeners and authorities keep one long-term key in DataDir/quic-tls.key. The authority’s -g option writes this key and quic-tls.hash. TCP-only authorities neither read nor create the key file.

The QUIC configuration supplies defaults for ALPN, CurvePreferences, AddressValidation, KeepAlivePeriod, KeepAliveJitter, PinMismatch, and CloseLinger.

Requirements R-24-1 through R-24-15.

Connection bounds and operation

One listener carries descriptor uploads, voting, and consensus retrieval. The listener applies connection limits and deadlines before and after the handshake.

An authority MUST refuse connections above a nonzero pool cap before the handshake. Each epoch, it updates the peer pool from consensus and configured authority addresses. A failed refresh keeps the previous set. A panic in one connection handler MUST NOT stop the authority. Persistent authority connections default to off.

Stored state carries a schema version. An authority MUST refuse to start if that version differs from the expected version. It MUST also refuse to start unless its configured authority list contains its own identity and link key.

An operator MAY reload the authorized node set. Every authority MUST reload the same set in the same epoch, or their votes disagree. An authority MUST reject a reload that would fail startup validation (R-16-6) and keep the old set.

Mixnet packet paths

Sphinx packets protect routing information and payloads through successive hops. For a client forward path, Namenlos uses a gateway, three mixes, and a service node. Each relay removes one Sphinx layer and forwards the packet over a separately authenticated PQ Noise link.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: layers
    accTitle: Protocol encapsulation
    accDescr: A client-to-gateway PQ Noise connection carries a send_packet command over TCP/IP or QUIC/UDP/IP. The command contains a Sphinx packet with five concentric protection layers around the data. The outer layer belongs to the gateway, followed by three mixes and the service node. Each receiving hop removes its Sphinx layer. Each forwarded packet uses the next neighbor link's independent encryption. Namenlos uses five hops, 3082-byte packets, and up to 2000 bytes of user payload.
    PACKET@{img: "/docs/specs/dirauth/sphinx-layers.svg", label: "", w: 244, h: 453, constraint: "on"}
    PACKET -->|"gateway decrypts link command"| UNWRAP["<img src='/docs/specs/dirauth/icons/gateway.svg' alt='' width='32' height='32'/><br/>Gateway removes its<br/>Sphinx layer"]
    UNWRAP -->|"four Sphinx layers remain"| FORWARD["<img src='/docs/specs/dirauth/icons/gateway.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/mix.svg' alt='' width='32' height='32'/><br/>Gateway forwards to Mix 1<br/>over their own PQ Noise link"]
    class PACKET local
    class UNWRAP,FORWARD link
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

The forward path selects these five hops from the consensus. Sphinx protection spans the route. PQ Noise protects only one neighbor connection. Sphinx packets retain their configured length as each hop unwraps them. The Sphinx packet format defines the byte layout.

Security considerations

Clients trust the configured authority keys. A threshold of authorities can sign a network view that clients accept.

• Any two signing quorums overlap in at least 2*threshold - A authorities. With a simple majority, this minimum is two for even A and one for odd A. Quorum intersection prevents conflicting signed consensuses only if the overlap exceeds the number of dishonest authorities and honest authorities sign once per epoch. At A = 3 or A = 5, one dishonest signer can belong to both quorums. A simple majority cannot guarantee agreement with two dishonest authorities, regardless of A. Crash and omission faults do not create conflicting signed consensuses if honest authorities sign once per epoch.
• Verified conflicting commits or reveals exclude their signer from the SRV calculation only (R-17-4). A dishonest authority can still send different descriptor sets to different peers and prevent matching consensus bytes.
• Authorities with different PriorSharedRandom rules can sign different bytes at multiples of 504. Only a group with threshold matching signatures can publish its document.
• Nodes can authenticate peers with descriptors from N, N-1, and N-2. A superseded link key can remain valid for up to three epochs while the current consensus still lists that node. Removing a node from all authority allow-lists prevents its inclusion in later consensuses. Nodes reject its older descriptors when they apply a current consensus that omits it (authentication). A key listed only in N+1 becomes eligible strictly after 7/8 of N (R-11-2). A peer key that cannot be marshaled MUST fail authentication without stopping the node.
• A consensus records accepted descriptors, not live node availability. Clients can select a failed node from a cached document and lose packets sent to it. An absent descriptor can mean a missing upload, insufficient votes, or removal from the allow-lists.
• A mix creates a Sphinx key pair for each epoch and removes expired keys. The key manager maintains this window. Forward secrecy depends on erasing expired private keys, including any copies. Epoch changes also limit the lifetime of the replay cache.
• A node retains peer connections while the peer remains authorized by the applicable documents (R-11-2). Authentication and permission to send can change at an epoch boundary.
• Five authorities require three signatures. Six require four. Both configurations can publish with two authorities unavailable, but not three. Quorum overlap determines agreement when authorities sign conflicting documents.
• Without node link-key pinning (authentication and authorization) anyone could present a node’s identity hash, hold its per-identity slots and keep it from uploading.
• With fresh authority connections and no retries, each send phase can require A*(A-1) peer handshakes. Retries can increase this count. HandshakeTimeoutSec defaults to 3 seconds. Persistent authority connections can reduce the count (connection bounds and operation).

Appendix A. Formats and validation

Producers MUST encode CBOR objects using CDDL. Command and transport-record encodings MUST follow ABNF. Encoding and validation rules also govern canonical bytes, signatures, authorization, and epoch acceptance.

Configuration defaults and limits come from authority configuration and QUIC options.

TLS curve names are X25519, X25519MLKEM768, SecP256r1MLKEM768, SecP384r1MLKEM1024, CurveP256, CurveP384, and CurveP521. These local settings do not replace network-wide scheme agreement.

Let M be the positive decompressed limit. Set C = M + 18 + 5 * (floor(M/16384) + 2). The dechunker requires:

• Sequential chunk numbers starting at zero, with one constant total between 1 and C.
• A non-empty first payload of size S and total at most ceil(C/S).
• Every non-final payload exactly S bytes, and the final payload between 1 and S bytes.
• At most C compressed bytes and M decompressed bytes.

Error responses use a single empty chunk instead. Signature, epoch, and geometry verification follow reassembly.

Appendix B. Existing TLA+ models

Katzenpost includes TLA+ models for authority voting, node state, key retention, and client retransmission.

Appendix C. Field and encoding reference

Descriptors and consensus documents carry node identities, network parameters, and cryptographic material. Their encodings determine the signed bytes.

Directory formation overview

Nodes submit descriptors, and authorities reconcile contributions before signing a consensus.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: network
    accTitle: Directory publication
    accDescr: Nodes upload descriptors. Authorities reconcile votes and random contributions, exchange signatures, and serve a threshold-signed consensus.
    N(["<img src='/docs/specs/dirauth/icons/mix.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/gateway.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/service.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/replica.svg' alt='' width='32' height='32'/><br/>Mixes, gateways,<br/>service nodes, and replicas"])
    subgraph D["<img src='/docs/specs/dirauth/icons/authority.svg' alt='' width='32' height='32'/><br/>Dirauths"]
        direction TB
        V["Exchange votes and reveals"] --> C["Reconcile commit and reveal pairs"]
        C --> B["Build the local consensus bytes"]
        B --> S["Exchange signatures"]
        S --> P["Publish at the signing threshold"]
    end
    N -- "Signed descriptors" --> D
    D --> CONS["<img src='/docs/specs/dirauth/icons/directory.svg' alt='' width='32' height='32'/><br/>Signed consensus"]
    CONS -- "get_consensus responses" --> R["<img src='/docs/specs/dirauth/icons/mix.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/gateway.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/service.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/replica.svg' alt='' width='32' height='32'/><br/>Nodes and couriers"]
    class N,R link
    class V,C,B,S,P directory
    class CONS local
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

The network map includes all configured node roles.

Descriptor fields

Mixes, gateways, and service nodes use MixDescriptor. Storage replicas use ReplicaDescriptor.

Required fields describe producer output. Receiver decoding, descriptor validation, and upload validation define acceptance of missing fields and alternate encodings.

Traffic rates

Consensus traffic rates control packet delays and transmission frequency.

Signed document fields

The document body contains the topology, traffic rates, and signed directory contributions.

Transport addresses

Descriptor address maps select link transports and endpoint URLs.

Directory commands

Directory peers exchange descriptors, votes, reveals, certificates, and signatures through numbered wire commands.

Connection limits

Limits bound message sizes, timeouts, connection pools, and concurrent handlers.

Signature schemes

Ed25519 Sphincs+ concatenates an Ed25519 signature and a SPHINCS+ signature. Ed25519 has a 32-byte public key and a 64-byte signature. SPHINCS+ runs at the sphincs-shake-256f parameter set, with a 64-byte public key and a 49856-byte signature (parameter selection, sizes). The hybrid implementation adds the component sizes. A verifier MUST verify both components (verification). On Windows the authority default is Ed25519 alone. A network that mixes platforms MUST configure the same signature scheme explicitly.

Deterministic CBOR

R-6-3 applies these encoding requirements to descriptors, documents, and certificate envelopes:

• Map keys MUST use the descriptor fields, document fields, and envelope fields. They MUST be sorted by encoded key length first, then bytewise. This is the canonical order of RFC 7049 section 3.9, retained in RFC 8949 section 4.2.6.
• Integers MUST use their shortest form. All lengths MUST be definite.
• Floats MUST use the shortest of float16, float32, and float64 that represents them exactly. NaN MUST be 0xf97e00. Infinities MUST use float16.
• Each field MUST be present, omitted, or null as the field tables specify. A nil map or list encodes as null. An empty map encodes as {}, and an empty list as []. These are distinct byte sequences.

RFC 8949 section 4.2.3 sorts keys bytewise without comparing length first. A library that supports both orders MUST use the length-first order here.

Reply status codes

A response status tells the sender whether its command succeeded or why it failed.

Protocol components

The protocol combines network configuration, voting, signed objects, and authenticated transport.

Constants and notation

Epoch and quorum parameters set the voting schedule and signature threshold.

Prerequisites

A network’s configuration supplies trusted authorities, allowed nodes, cryptographic schemes, and transport addresses.

Mixnet services

Service nodes advertise mixnet services through the Kaetzchen descriptor field.

Node roles

Descriptors identify node roles and their published keys.

Key schemes

Parties use identity signatures, link KEMs, Sphinx keys, and replica envelope keys for separate tasks.

Client software and configuration

The client daemon loads its listeners, gateway pins, and authority keys from client.toml.

Authority phases

Authorities collect descriptors and exchange voting material on the epoch schedule. The times below are fractions of the epoch duration P. Each phase includes its start and excludes its end.

Phases: Mix, gateway, service node

Mixes, gateways, and service nodes upload next-epoch descriptors before they fetch the next consensus.

Clocks and retention

Epoch windows determine key retention, document expiry, and retry timing.

Clocks and retention: authority

Authorities retain voting state and limit retries using separate timing settings.

Acceptance windows and status codes

Receivers use the request epoch and local state to select a response status.

Commands by role

The authenticated peer role determines which directory commands the receiver accepts.

Appendix D. Requirements

R-s-n identifies requirement n in group R-s. For example, R-6-3 is the third requirement in R-6. The consensus document.

R-5. Descriptors

Nodes publish signed descriptors with identity keys, addresses, and role fields.

R-6. The consensus document

Nodes and clients use the consensus to select peers and apply network settings.

R-7. Certificate envelopes and signing

A certificate envelope binds a payload to one or more identity signatures.

R-9. Time

Participants use the same epoch clock to select current and next-epoch data.

R-10. Phases

The voting phases schedule uploads, authority exchanges, and consensus publication.

R-11. Clocks and retention

Authorities, nodes, and clients apply separate clock and retention limits.

R-12. The authority state machine

Each authority advances through voting states on the epoch schedule.

R-13. Acceptance windows and status codes

Message acceptance windows determine the status returned to a sender.

R-14. Phase_DESC. Descriptor upload

Authorities accept descriptor uploads from authorized nodes.

R-15. Phase_VOTE, Phase_REVEAL. Commit and reveal

Authorities commit to random values before revealing them.

R-16. Phase_CERT, Phase_SIG. Tabulation

Authorities tally votes for descriptors and traffic rates.

R-17. Phase_CERT. Voting certificates

Authorities verify voting certificates before reconciling random contributions.

R-18. Phase_SIG. Shared random value and topology

Authorities derive the shared random value and assign mix layers.

R-19. Phase_SIG, Phase_PUB. Signatures and publication

Authorities exchange consensus signatures and publish when the threshold is met.

R-21. Authority message delivery

Authorities deliver voting messages through peer connections and retry within phase deadlines.

R-22. Wire protocol

Directory wire commands carry signed protocol objects over PQ Noise.

R-23. Authentication and authorization

Session authentication and authorization bind commands to configured identities and roles.

R-24. QUIC transport

Peers authenticate QUIC endpoints with pinned keys.

R-26. Byte identity

Authorities require identical consensus bytes before combining signatures.

Appendix E. Cryptographic configuration

Namenlos uses hybrid identity signatures and post-quantum link keys.

Appendix F. Receiver and construction algorithms

Receivers parse signed inputs, authorize senders, verify epochs, and construct the consensus. A receiver can accept an input that violates a producer requirement.

Receivers MUST evaluate the applicable algorithm’s conditions in order and return its first failure. A later condition does not change an earlier status. Decoded maps have no iteration order unless an operation sorts them.

Go reference implementation

The Katzenpost reference implementation uses the Go programming language. Internal data types and library calls can differ between languages. Compatible implementations MUST produce the same accepted values, canonical bytes, and consensus fields.

The Go CBOR library determines conversion and normalization behavior for received objects. The conversion of binary64 values to int64 can depend on the Go runtime and target architecture. The receiver decoding rules retain those distinctions.

Go’s math.Log computes the natural logarithm for the gateway rate. Other mathematics libraries can round the result differently. A different LambdaG encoding changes the signed consensus bytes. Compatible results require the binary64 evaluation order and logarithm constants.

CBOR decoding

The reference uses github.com/fxamacker/cbor/v2 v2.9.1 with DecOptions{} for these objects (pinned dependency). Encoding with CanonicalEncOptions does not configure the decoder. Each Unmarshal call first verifies the structure and limits of one complete CBOR item. It rejects trailing bytes, then decodes that item into the destination type. If either step returns an error, the caller rejects the result, including any fields set before the error (decoder).

These settings follow the decoder options, struct field rules, map decoding, byte conversion, and structural conditions. The limits apply again when the receiver decodes an embedded byte string as another CBOR object. They do not impose a combined nesting limit across separate decodes of an envelope, its certified payload, and an embedded descriptor.

The producer encodes a MixDescriptor as a byte string containing its CBOR map. The receiver invokes MixDescriptor.UnmarshalBinary on that byte string. The default decoder also accepts a direct CBOR map for this destination type. A ReplicaDescriptor has no UnmarshalBinary method and uses a direct map. Its Unmarshal method does not give it the byte-string conversion used for a mix descriptor. Descriptor methods, replica methods.

Canonical encoding after decoding

Upload verification and descriptor tallying encode decoded values again. Arbitrary mixnet service parameters therefore use these conversions before canonical encoding.

The time decoder, time encoder, and encoding defaults define these conversions. The map decoder defines scalar reuse. These byte examples use hexadecimal CBOR. The receiver tests verify them against the pinned decoder.

Certificate parsing and signature verification

Certificate operations verify the signed payload and its expiration. H(key) is the hash of the serialized identity public key. N is the current local epoch number at verification.

Envelope(raw):
    Decode raw into a new Certificate, using receiver-decoding.
    Require Version == 0.
    Require N < Expiration.
    Require KeyType to be nonempty.
    Require Certified to be nonempty.
    Replace a nil Signatures map with an empty map.
    Return the decoded certificate.

VerifyEnvelope(key, raw):
    c = Envelope(raw).
    For each signature value s in c.Signatures, in unspecified map order:
        If s.PublicKeySum256 == H(key):
            Require len(s.Payload) == key.scheme.SignatureSize.
            Require key.scheme.Verify(key,
                LE32(c.Version) || LE64(c.Expiration) ||
                UTF8(c.KeyType) || c.Certified, s.Payload).
            Return c.Certified.
    Fail because no signature value identifies key.

ParseDocument(raw):
    c = Envelope(raw).
    Require at least one entry in c.Signatures.
    Create a new Document, with an empty detached-signature map.
    For each signature value s in c.Signatures:
        Set document.Signatures[s.PublicKeySum256] = s.
    Decode c.Certified into the document body, using receiver-decoding.
    Return the document.

ParseDocument does not run outer signature verification or document validation. In the reference, it calls GetCertified and GetSignatures separately. Each call decodes the envelope and repeats its validity tests before body decoding (envelope validation). The body excludes the detached Signatures field (document parsing).

Envelope verification does not compare the envelope map key with the inner signature’s PublicKeySum256. It searches signature values. It also does not compare KeyType with the verifier’s configured scheme name. It requires a nonempty KeyType and includes that string in the signed message (signature search).

If different map entries contain signatures with the same inner identity hash, the first matching value visited controls verification. Conflicting entries can therefore give an order-dependent result. Producers use matching outer and inner identity hashes and one signature per identity.

Threshold verification calls VerifyEnvelope for each configured verifier and counts distinct hashes of successful verifier keys. Unknown or invalid signatures do not invalidate an otherwise sufficient threshold. A threshold greater than the number of supplied verifier entries fails before verification. Duplicate configured keys cannot provide more than one successful identity. Threshold verification.

Descriptor validation

A dirauth applies MixShape(d, e) to mix descriptors and ReplicaShape(d, e) to replica descriptors. The caller supplies e. MixShape uses it for the key window. Neither algorithm uses the descriptor’s Epoch.

MixShape(d, e):
    Require d != nil.
    Require 1 <= byte_length(d.Name) <= 32.
    Require d.LinkKey and d.IdentityKey to be nonempty.
    Require d.MixKeys[e] to be nonempty.
    For each key epoch k in d.MixKeys:
        Require e <= k < e + 3.
    Require d.Addresses to be nonempty.
    For each address list in d.Addresses:
        Require the list to be nonempty.
        Check each URL with AddressShape(URL, d.IsGatewayNode, true).
    Require that IsGatewayNode and IsServiceNode are not both true.
    If IsServiceNode is false:
        Require Kaetzchen == nil.
    Otherwise, for each capability and parameter map in Kaetzchen:
        Require a nonempty capability name and a non-nil parameter map.
        Require parameter "endpoint" to exist and to be a string.
        Require 1 <= byte_length(endpoint) <= 32.

ReplicaShape(d, e):
    Require d != nil.
    Require 1 <= byte_length(d.Name) <= 32.
    Require d.LinkKey and d.IdentityKey to be nonempty.
    Require d.EnvelopeKeys to be nonempty.
    Require each EnvelopeKeys value to be nonempty.
    Require d.Addresses to be nonempty.
    For each address list in d.Addresses:
        Require the list to be nonempty.
        Check each URL with AddressShape(URL, false, false).

AddressShape(URL, isGateway, allowOnion):
    Parse the URL with the reference URL syntax.
    If its scheme is tcp, tcp4, tcp6, ws, or quic:
        Require its host component to split into host and port.
    Else if its scheme is onion:
        Require allowOnion and isGateway.
    Else:
        Fail.

The URL syntax is that of Go net/url.Parse, and host-port splitting is that of net.SplitHostPort. This is a syntax rule. It does not require a nonempty host, a numeric nonempty port, a particular address family, or equality between the address-map key and the URL scheme. The onion branch omits host-port validation. Additional URL components are not rejected by this validator. Address validation.

MixShape permits missing or empty future key values when their epoch lies in the permitted window. It does not require a consecutive set of three keys. It does not verify d.Epoch, d.Version, key lengths, or key decoding. A service can have nil or empty Kaetzchen, and multiple capabilities can use the same endpoint. Other capability parameters and KaetzchenAdvertizedData have no additional shape validation here. ReplicaShape does not use its epoch argument, does not verify envelope-key epochs, and does not verify ReplicaID against configuration. A replica descriptor has no Version field. Mix validation, replica validation.

Live descriptor uploads

Upload validation starts after the wire session and command parser accept the command. peerID is the session’s authenticated identity hash, peerLinkKey is its authenticated link public key, and e is the command epoch. The handler uses the same sequence for mix and replica uploads.

For step 6, require a non-nil signature with the configured scheme’s exact signature size. Make a new upload object with Signature = nil. Retain the decoded descriptor and, for a mix upload, the decoded LoopStats. Encode this new object canonically. Run signature verification on Signature.Payload over those bytes with the decoded descriptor identity key (upload signature operations).

This operation does not verify the upload signature’s PublicKeySum256 or include it in the preimage. The decoder already discarded unknown fields. The receiver therefore verifies the canonical encoding of the decoded object, rather than the received upload bytes.

For step 9, a mix descriptor with only IsGatewayNode set uses the gateway authorization map. A descriptor with only IsServiceNode set uses the service map. A descriptor with neither flag set uses the mix map. Both flags set cause rejection. The selected map MUST contain the identity hash and the exact descriptor name. A replica MUST have an identity hash, name, and ReplicaID that match one current storage-replica entry. Authorization.

For step 10, if AcceptDescriptorMetadata is false, clear ContactInfo and SoftwareVersion before validation and storage. Otherwise, retain them. Require SoftwareVersion to contain at most 128 bytes and ContactInfo to contain at most 256 bytes. Each retained byte MUST be in the inclusive range 0x20 through 0x7e. Empty strings are valid (printable-string validation).

The implementation evaluates the core shape validation, the software-version validation, and the contact-information validation, and joins their errors. Any error gives the same wire status. The signature verification always occurs before metadata removal (metadata policy).

The handler does not compare descriptor.Epoch with e. For a mix, e selects the required mix key and its permitted window. For a replica, shape validation leaves both descriptor and envelope-key epochs unchecked. Storage uses e in both cases.

The command handlers do not require QUICKeyHash to match a QUIC session key (replica upload order). They also do not require a gateway to advertise a TCP or onion address. A QUIC-only gateway can produce a warning after acceptance (mix upload order).

Upload storage and replay

Storage serializes upload decisions for an identity hash. After metadata policy, the receiver compares the incoming descriptor with any descriptor stored for (command epoch, identity hash). Comparison uses canonical descriptor bytes, and excludes the upload signature and LoopStats.

StoreUpload(e, identity, rawUpload, decodedDescriptor):
    If a descriptor already exists at (e, identity):
        Canonically encode both descriptors.
        If either encoding fails: return DescriptorInternalError.
        If the encodings differ: return DescriptorConflict.
        Return DescriptorOk.
    If a document for e exists, or this authority's own vote for e exists:
        Return DescriptorConflict.

    Persist the original rawUpload at (e, identity).
    If persistence fails:
        Report a fatal persistence error, and return DescriptorInternalError.

    Recheck state while committing the in-memory descriptor:
        If a descriptor now exists at (e, identity): return DescriptorOk.
        If a document or this authority's own vote now exists for e:
            Return DescriptorConflict.
        Store decodedDescriptor, and notify the state worker.
    Return DescriptorOk.

An unchanged upload can therefore succeed after the authority votes or publishes, because comparison precedes the late-upload condition. The nominal upload deadline causes a warning. It is not itself a rejection condition. Persistence can succeed before a later finality comparison produces DescriptorConflict, so a conflict response does not prove the absence of a write. The live descriptor has the applied metadata policy, while the stored signed upload preserves its original bytes (storage and vote cut).

Document validation

The shared base validator operates on a parsed body and a set of verifier keys. It does not authenticate the document envelope. VerifyEnvelope includes the current-epoch expiration condition for each embedded commitment or reveal.

BaseDocument(d, verifiers):
    Require d.Version == "v1".
    Require d.GenesisEpoch != 0.
    If PriorSharedRandom is empty:
        Require d.GenesisEpoch == d.Epoch.
    Build verifierByHash from verifiers.

    For each (identity, signedCommit) in SharedRandomCommit:
        Require verifierByHash[identity] to exist.
        commit = VerifyEnvelope(verifierByHash[identity], signedCommit).
        Require len(commit) == 40.
        Require BE64(commit[0:8]) == d.Epoch.
        If SharedRandomCommit has exactly one entry:
            Require SharedRandomReveal to have zero entries.
        Otherwise:
            Require reveal count == commitment count.
            Require SharedRandomReveal[identity] to exist.
            reveal = VerifyEnvelope(verifierByHash[identity], that entry).
            Require len(reveal) == 40.
            Require BE64(reveal[0:8]) == BE64(commit[0:8]).
            Require H(reveal) == commit[8:40].

    seen = empty identity-hash set.
    For each descriptor in Topology, in layer and list order:
        Run MixShape(descriptor, d.Epoch).
        Require H(descriptor.IdentityKey) not in seen, then add it.
    For each descriptor in GatewayNodes:
        Run MixShape(descriptor, d.Epoch).
        Require descriptor.IsGatewayNode.
        Require H(descriptor.IdentityKey) not in seen, then add it.
    For each descriptor in ServiceNodes:
        Run MixShape(descriptor, d.Epoch).
        Require descriptor.IsServiceNode.
        Require H(descriptor.IdentityKey) not in seen, then add it.
    For each descriptor in StorageReplicas:
        Run ReplicaShape(descriptor, d.Epoch).

VoteDocument(d, verifiers):
    Run BaseDocument(d, verifiers).

FullDocument(d, verifiers):
    Run BaseDocument(d, verifiers).
    Require Topology to contain at least one layer.
    Require every layer to contain at least one descriptor.
    Require GatewayNodes to contain at least one descriptor.
    Require ServiceNodes to contain at least one descriptor.

If SharedRandomCommit is empty, the commitment loop does not run. The base validator then neither rejects nonempty SharedRandomReveal nor runs verification on it. The one-commit case rejects every nonempty reveal map. The two-or-more-commit case requires the same identity set and a valid matching reveal for each commitment (commitment opening). The vote handler adds its own exact count and sender conditions below (document validators).

The base validator does not require role flags to be clear for entries in Topology. It does require the appropriate flag for entries in the gateway and service lists, and the core descriptor validation rejects contradictory flags. It rejects repeated identity hashes across those three collections. It does not verify replica identity uniqueness, replica-ID uniqueness, or identity overlap with replicas. It does not consult the receiver’s node authorization tables.

This document validator omits descriptor metadata and QUIC hash lengths. It does not parse descriptor keys, compare descriptor epochs, or require a configured topology size. It also omits delay and rate ranges, floating-point finiteness, SharedRandomValue length, and geometry-hash length or equality. It does not constrain the body PKI scheme name, notice text, or the length and contents of nonempty PriorSharedRandom. Such producer rules or conditions in a later consumer are distinct from this validator (complete base-validation body).

Authority message acceptance

Authority message validation starts after wire command decoding and authority-role dispatch. Command decoding verifies the minimum command length. It takes the declared key from the fixed-size public-key field, then decodes it with the configured signature scheme. A decoding failure does not reach these handlers (command decoding).

The session role controls command dispatch (role dispatch):

• A client session can request consensus.
• A mix, gateway, or service session can request consensus or post a mix descriptor.
• A replica session can only post a replica descriptor.
• An authority session can request consensus or send Vote, Reveal, Cert, or Sig.

An unsupported command for the session role receives no command status.

V is the receiver’s current votingEpoch, and S is its current state. Message authorization first compares H(command.PublicKey) with the session identity hash, then verifies membership in the configured authority authorization map. Either failure returns that command’s NotAuthorized status. Message validation and storage are atomic with respect to the state machine.

ReceiveVote(command):
    Check authorization; otherwise return VoteNotAuthorized.
    If command.Epoch < V: return VoteTooLate.
    If command.Epoch > V: return VoteTooEarly.
    Ensure the vote and commitment maps for V exist.
    If this sender already has a vote for V: return VoteAlreadyReceived.
    If S == accept_signature: return VoteTooLate.
    VerifyEnvelope(command.PublicKey, command.Payload);
        on failure, return VoteNotSigned.
    d = ParseDocument(command.Payload);
        on failure, return VoteNotSigned.
    If d.Epoch != V: return VoteMalformed.
    Run VoteDocument(d, verifiers);
        on failure, return VoteMalformed.
    Require exactly one commitment and zero reveals;
        otherwise return VoteMalformed.
    Require the commitment map to contain this sender's identity;
        otherwise return VoteMalformed.
    Store d as this sender's vote for V.
    If S == accept_desc or S == accept_vote:
        Store the sender's commitment for V.
    Return VoteOk.

ReceiveReveal(command):
    Check authorization; otherwise return RevealNotAuthorized.
    reveal = VerifyEnvelope(command.PublicKey, command.Payload);
        on failure, return RevealNotSigned.
    If len(reveal) < 8: return RevealNotSigned.
    e = BE64(reveal[0:8]).
    If e < V: return RevealTooLate.
    If e > V: return RevealTooEarly.
    If S == accept_cert or S == accept_signature:
        If this sender already has a reveal for V:
            Return RevealAlreadyReceived.
        Return RevealTooLate.
    If no commitment exists for this sender at V: return RevealTooEarly.
    commit = VerifyEnvelope(command.PublicKey, the stored commitment);
        on failure, return RevealNotSigned.
    Require len(commit) == 40 and len(reveal) == 40,
        equal eight-byte epoch prefixes, and H(reveal) == commit[8:40];
        otherwise return RevealNotSigned.
    If this sender already has a reveal for V: return RevealAlreadyReceived.
    Store command.Payload as this sender's signed reveal for V.
    Return RevealOk.

ReceiveCert(command):
    Check authorization; otherwise return CertNotAuthorized.
    If command.Epoch < V: return CertTooLate.
    If command.Epoch > V: return CertTooEarly.
    If S == accept_signature:
        If this sender already has a certificate for V:
            Return CertAlreadyReceived.
        Return CertTooLate.
    VerifyEnvelope(command.PublicKey, command.Payload);
        on failure, return CertNotSigned.
    d = ParseDocument(command.Payload);
        on failure, return CertNotSigned.
    If d.Epoch != V: return CertNotSigned.
    If d.SharedRandomReveal is empty: return CertNotSigned.
    If this sender has no stored vote for V: return CertTooEarly.
    Run FullDocument(d, verifiers);
        on failure, return CertNotSigned.
    If this sender already has a certificate for V: return CertAlreadyReceived.
    Store d as this sender's certificate for V.
    Return CertOk.

ReceiveSig(command):
    Check authorization; otherwise return SigNotAuthorized.
    If command.Epoch < V: return SigTooLate.
    If command.Epoch > V: return SigTooEarly.
    body = VerifyEnvelope(command.PublicKey, command.Payload);
        on failure, return SigNotSigned.
    If this sender already has a signature for V: return SigAlreadyReceived.
    Decode body into a new Signature, using receiver-decoding;
        on failure, return SigInvalid.
    Store that Signature under this sender's identity for V.
    Return SigOk.

The reveal handler does not use command.Epoch for its epoch decision. It uses the signed body’s epoch prefix. It verifies the full 40-byte length only after the epoch, state, and stored-commitment conditions (vote and reveal handlers).

The signature handler has no state gate. It verifies the outer envelope signature before the duplicate test, but it does not decode a duplicate’s inner signature. For a new signature, it omits inner-signature verification, sender-hash comparison, and payload-length conditions at receipt. A valid outer envelope whose certified body is CBOR null can therefore decode to a zero-valued inner Signature and receive SigOk. Publication verifies whether collected signatures authenticate the locally constructed consensus (signature handler).

There is no general rule that limits a command to the state named after that command. For a matching epoch, the receiver can store a new valid vote in bootstrap, accept_desc, accept_vote, accept_reveal, or accept_cert. It stores the commitment only in accept_desc and accept_vote. It can store a valid certificate before accept_cert if its sender’s vote already exists (certificate handler). It can store a reveal before accept_reveal if its commitment exists.

The explicit closed-state conditions still apply. Bootstrap does not reject all messages.

When t <= P/8, the bootstrap transition sets V to N+1. When t > P/8, it sets V to N+2 and remains in bootstrap until the next epoch. Successful publication increments V. Failed publication sets it to N+2 and returns to bootstrap (publication transition). Epoch comparisons use this stored V, rather than a fresh calculation from the nominal phase deadline.

Consensus reception and restoration

Network retrieval, client deserialization, and restoration apply different validation sequences.

The network fetch operations do not compare the geometry hash in this sequence. An application that verifies its local geometry does so separately. Client fetch and deserialize, authority fetch, consensus restoration.

Descriptor restoration and node reload

At startup, the reference restores descriptor and document records for the current local epoch minus one, the current epoch, and the current epoch plus one. It creates fresh in-memory vote, commitment, reveal, certificate, and signature maps. It does not restore these round messages. It then starts in bootstrap (state initialization).

For each descriptor record, the database bucket supplies the upload epoch e, and the record key supplies the expected identity hash. The restoration sequence is:

RestoreUpload(rawUpload, e, storedIdentity):
    Decode the corresponding signed upload.
    Require a non-nil descriptor.
    Require the configured identity public-key length, and decode the key.
    Verify the signed upload over its canonical unsigned form.
    Apply the current AcceptDescriptorMetadata policy.
    Run MixShape(descriptor, e) or ReplicaShape(descriptor, e),
        and validate retained SoftwareVersion and ContactInfo.
    Require H(descriptor.IdentityKey) == storedIdentity.
    Require current identity, role, name, and, for replicas, ReplicaID authorization.
    Insert the descriptor under (e, storedIdentity).

A failed descriptor validation discards that record and allows restoration to continue. A database record key whose identity-hash length is not 32 bytes causes a panic before these descriptor validations (restoration loop). Restoration does not recheck QUICKeyHash, bind the descriptor to a live session link key, or apply the live late-upload cut. The receiver runs signature verification before metadata removal. Thus, a different AcceptDescriptorMetadata setting can change the restored in-memory metadata without a change to the stored upload (restored-upload validation).

A node reload verifies the new node counts using the running layer and minimum-node settings (node-count validation). It loads all proposed node identity keys. It then replaces the mix, gateway, service, replica, and reverse-key tables as one operation. Any failure retains the current tables (node reload).

Reload does not change the startup-only Server, Authorities, Logging, Parameters, Debug, Topology, or SphinxGeometry settings. It also does not remove accepted descriptors or existing round messages. New uploads use the new authorization tables. Descriptor selection from the vote tally verifies current authorization again. Thus an accepted descriptor can remain in memory after a reload but fail later selection (tally authorization).

Document construction

Votes, voting certificates, and consensuses share the document body format. Their inputs differ as follows. V is the stored voting epoch.

The builder sets Version to “v1”, Epoch to V, and GenesisEpoch to the stored genesis epoch. It copies the supplied five voted rates. LambdaG comes from local configuration under gateway rate arithmetic. It copies the configured PKISignatureScheme and geometry hash, the supplied notice, and stored prior-random history. Configured replica IDs and keys include the full authorized set in R-26-7 order. Empty optional fields follow the field reference.

Split mix descriptors by flags: gateway first, then service node, then ordinary mix. Place ordinary mixes by the configured fixed topology order. Gateway and service lists retain the supplied descriptor order. Replica descriptors retain their supplied order. The vote uses locally collected descriptors. Tallying sorts the included descriptors and replicas for certificate and consensus construction. Voting documents therefore need not share one descriptor order across different authors.

Before building the consensus, initialize history to [SRV, SRV] when history is empty or V equals GenesisEpoch. Otherwise, at V modulo 504 equal to zero, set history to [SRV, old_history[0]]. Other rounds preserve history. This update precedes tallying and final document validation. It changes stored state even if a later construction condition fails.

The tagged constructors and common builder implement these steps.

Ordered reconciliation

Reconciliation processes accepted voting certificates. It compares signed envelope bytes, not only their certified payloads. Certificate authors and cited identities use ascending 32-byte identity-hash order.

Start with empty commit and reveal maps. Do not seed them from separately received votes or reveals. For each entry, verify these conditions in order:

1. The cited identity is an authorized authority.
2. Its commit envelope passes certificate verification.
3. A reveal envelope exists under the same identity.
4. That reveal envelope passes certificate verification under that identity’s key.
5. Both certified payloads have 40 bytes and start with BE_uint64(V).
6. The commit’s last 32 bytes equal H of the entire reveal payload.

A failed condition excludes the certificate author and stops its entry loop. A verified pair enters reconciliation.

bad = empty set
commits = empty map
reveals = empty map

for author in sorted(certificate authors):
    if author in bad:
        continue
    certificate = certificates[author]
    for signer in sorted(certificate.commit identities):
        if signer in bad:
            continue
        if the ordered pair checks fail:
            bad.add(author)
            break
        commit = certificate.commits[signer]
        reveal = certificate.reveals[signer]
        if signer not in commits:
            commits[signer] = commit
        else if commits[signer] != commit:
            bad.add(signer)
        if signer not in reveals:
            reveals[signer] = reveal
        else if reveals[signer] != reveal:
            bad.add(signer)

for signer in bad:
    delete commits[signer]
    delete reveals[signer]

The reveal comparison still runs when the commit comparison excludes its signer. An exclusion does not remove earlier entries attributed to other identities. A certificate author excluded during its own entry loop does not automatically stop that loop. Only a failed pair condition stops it. At each certificate’s turn, skip its author if already excluded.

The resulting maps supply the surviving-pair threshold and SRV. The tagged reconciliation implements this order.

The topology draw

The shared random value seeds one deterministic generator. Every authority MUST consume that generator in the same order.

The generator uses original ChaCha20 with a 256-bit SRV key, an eight-byte zero nonce, and initial 64-bit block counter zero. It reads consecutive keystream bytes without reset. It MUST stop before the counter wraps. Every draw from the topology generator MUST use this integer algorithm.

• One draw, called Int63, reads 8 bytes of keystream and clears the top bit of the last byte. It then reads those 8 bytes as a little-endian unsigned 64-bit integer.
• Int31 is Int63 shifted right by 32 and read as a signed 32-bit integer.
• Intn(n), for n of at least 1 and at most 2^31-1, is as follows. When n is a power of two, it is Int31 masked with n-1. In every other case the party draws Int31 again while the value is above 2^31-1-(2^31 mod n), and then takes the value modulo n. A larger n is outside this definition. n is the size of the input list, which may include all mixes.
• The permutation of n items MUST iterate i from 0 to n-1 inclusive. At each step it draws j = Intn(i+1), then sets m[i] to m[j], then sets m[j] to i.

The iteration at i = 0 MUST NOT be skipped. It assigns m[0] = 0 and consumes one draw. Skipping it changes all later draws.

Layer assignment

The assignment algorithm places accepted mixes into layers. A fixed topology takes precedence over automatic placement.

R-18-5 uses the following assignment algorithms. Sort input mix descriptors by identity-key hash (R-16-5). The prior consensus is the document for V-1. An older retained document does not select this algorithm. Layer indexes start at zero. Each append preserves the layer’s order.

With no prior consensus and no configured fixed topology, an authority MUST:

1. Start a fresh generator keyed by the SRV and draw Perm(number of input mixes).
2. Read mixes in that permutation order. Append each to successive layers, wrapping from the last layer back to layer zero.

With a prior consensus and no configured fixed topology, an authority MUST:

1. Start one fresh generator keyed by the SRV. Create Layers empty output lists and a pending set containing every input mix, keyed by identity hash.
2. Set target = floor(number of input mixes / Layers). Set priorLayers to the smaller of the prior layer count and Layers.
3. Visit prior layers 0 through priorLayers-1 in order. For each layer, draw Perm of its full prior list, including absent nodes. Visit entries in that order. If the output layer contains target nodes, stop visiting entries in that layer. Otherwise, append a prior entry’s current descriptor if its identity remains pending. Remove each appended identity from the pending set.
4. Sort the remaining descriptors by identity hash. Draw Perm of this pending list with the same generator. Keep one cursor into that permutation for the next steps.
5. Visit output layers 0 through priorLayers-1. Fill each to target by appending the next pending descriptor and advancing the cursor.
6. Starting at layer zero, append each remaining pending descriptor to successive layers, wrapping to layer zero after the last layer. Preserve descriptors already appended in steps 3 and 5.

An empty permutation consumes no draws. Draw each prior-layer permutation in full, even when target is zero or the algorithm uses few entries. Then draw the pending permutation from the same generator.

With a configured fixed topology, an authority MUST visit configured layers and their identity lists in configuration order. It appends the current descriptor for each included identity and skips identities with no included descriptor. It uses no random draws for this assignment. This case takes precedence over prior-consensus placement.

Gateway rate arithmetic

LambdaG uses the configured largest layer size n and configured gateway count g. It does not use the number of surviving descriptors. If g is zero or n is at most one, add configured LambdaP and LambdaL. Otherwise, evaluate (((n * n) * Log(n)) * Mu) / g from left to right. Convert n and g to binary64 first. Mu, LambdaP, and LambdaL are binary64 configuration values.

Round every arithmetic operation to binary64 with nearest-even rounding. Do not fuse multiply-add operations. The recorded bit patterns come from separate multiply and add operations. Go can emit fused multiply-add on arm64. On such a platform, evaluate each product and sum separately. Parentheses fix evaluation order. The logarithm constants are binary64 bit patterns.

For positive integer n of at least two, define Log as follows. Decompose its binary64 value exactly as fraction * 2^exponent, with 0.5 <= fraction < 1.

if fraction < SQRT_HALF:
    fraction = fraction * 2
    exponent = exponent - 1
f = fraction - 1
k = binary64(exponent)
s = f / (2 + f)
z = s * s
w = z * z
a = z * (C1 + w * (C3 + w * (C5 + w * C7)))
b = w * (C2 + w * (C4 + w * C6))
r = a + b
q = (0.5 * f) * f
Log(n) = (k * LN2_HI) - ((q - ((s * (q + r)) + (k * LN2_LO))) - f)

The Go logarithm uses this reduction and polynomial. For n = 3, Log(n) has bits 3ff193ea7aad030a. The tagged rate calculation uses these configured inputs.

Appendix G. References

Network operation depends on the packet, transport, client, storage, and certificate protocols.

Appendix H. Conformance and vectors

Conformance testing MUST cover:

1. A named test passes for every protocol requirement.
2. A mixed network with the reference implementation produces matching, threshold-signed consensuses under successful-round conditions. This test includes an epoch divisible by 504.

epoch   245448 (245448 mod 504 == 0; 2026-10-01 00:00 UTC)
RN      0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20
REVEAL  000000000003bec8441edc56cebc8e285d02267aa650819f15add7b06ef9b41b2690128dce655924
COMMIT  000000000003bec8e95138c6f44dfe875fa3daa92364a1ece9b315f25a7c7777f6f2064745a254c0

KEY_A   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
REV_A   000000000003bec8f15f1ea681af55bcdc2aff6ae09ca8ca122c84c4770d9571293f73e5d1e032f3
KEY_B   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
REV_B   000000000003bec8afa49d096346b9834fdc42890e35cae35b3ff4546094e747aa5468fe7a961334
PREV    (absent: 32 zero bytes)
order   A then B (descending by reveal bytes)
SRV     702b1bb93f15155761dc058d56edd07d2a5127478566f520366fb4b490a5e8ae

BODY contains the Certified bytes of a document’s envelope, encoded under R-6-3. This encoding fixture has one empty layer, no nodes, no commits, no reveals, and short byte strings. It is not a well-formed document.

Epoch 245448, GenesisEpoch 245439, Mu 0.001, LambdaP 0.5, LambdaL 0.0005,
LambdaM 0.0005, LambdaG 0.25, LambdaR 0.02, Topology [nil], GatewayNodes [],
ServiceNodes [], StorageReplicas [], SharedRandomValue 00000000,
PriorSharedRandom [01, 02], SphinxGeometryHash aa, Version "v1",
PKISignatureScheme "Ed25519", every other field empty or nil

BODY
b3624d75fb3f50624dd2f1a9fc6545706f63681a0003bec8674c616d62646147
f93400674c616d6264614cfb3f40624dd2f1a9fc674c616d6264614dfb3f4062
4dd2f1a9fc674c616d62646150f93800674c616d62646152fb3f947ae147ae14
7b6756657273696f6e62763168546f706f6c6f677981f66c476174657761794e
6f646573806c47656e6573697345706f63681a0003bebf6c536572766963654e
6f646573806f53746f726167655265706c6963617380715072696f7253686172
656452616e646f6d82410141027153686172656452616e646f6d56616c756544
0000000072504b495369676e6174757265536368656d65674564323535313972
53686172656452616e646f6d436f6d6d6974f67253686172656452616e646f6d
52657665616cf672537068696e7847656f6d657472794861736841aa

PARAMKEY groups the example network’s five voted rates under R-16-3.

Mu 0.001, LambdaP 0.001, LambdaL 0.0005, LambdaM 0.0005, LambdaR 0.02

PARAMKEY (81 bytes)
a5624d75fb3f50624dd2f1a9fc674c616d6264614cfb3f40624dd2f1a9fc674c
616d6264614dfb3f40624dd2f1a9fc674c616d62646150fb3f50624dd2f1a9fc
674c616d62646152fb3f947ae147ae147b

GEOMETRY_CBOR and SPHINXGEOMETRYHASH encode the example network’s Sphinx geometry (R-26-2). The list gives the 14 fields in struct order. CBOR uses the length-first key order of R-6-3.

NrHops 5, PacketLength 3082, HeaderLength 476, RoutingInfoLength 410,
PerHopRoutingInfoLength 82, SURBLength 572, SphinxPlaintextHeaderLength 2,
PayloadTagLength 32, ForwardPayloadLength 2574, UserForwardPayloadLength 2000,
NextNodeHopLength 65, SPRPKeyMaterialLength 64, NIKEName "x25519", KEMName ""

GEOMETRY_CBOR (273 bytes)
ae664e72486f707305674b454d4e616d6560684e494b454e616d656678323535
31396a535552424c656e67746819023c6c4865616465724c656e6774681901dc
6c5061636b65744c656e677468190c0a705061796c6f61645461674c656e6774
681820714e6578744e6f6465486f704c656e677468184171526f7574696e6749
6e666f4c656e67746819019a74466f72776172645061796c6f61644c656e6774
68190a0e75535052504b65794d6174657269616c4c656e677468184077506572
486f70526f7574696e67496e666f4c656e6774681852781855736572466f7277
6172645061796c6f61644c656e6774681907d0781b537068696e78506c61696e
746578744865616465724c656e67746802

SPHINXGEOMETRYHASH (32 bytes)
ed57ca3bc2165a0483e0d16d97511e15f318ed5cedfc3e7388c85ee8a2c0fb47

The message ceiling is 264512 bytes for these synthetic inputs. The synthetic key sizes differ from the Namenlos keys.

sign 32, sig 64, link 1216, sphinx 32, envelope 1024
nodes 16, replicas 4, authorities 6

mix      = 32 + 1216 + 3 * 32 + 4096            = 5440
replica  = 32 + 1216 + 3 * 1024 + 4096          = 8416
unsigned = 8192 + 16 * 5440 + 4 * 8416          = 128896
signed   = 128896 + 6 * (64 + 96)
                  + 2 * 6 * (64 + 96 + 40)      = 132256
ceiling  = 2 * 132256 = 264512, above the 262144 floor

CERT_CBOR holds REVEAL in an envelope with an artificial expiration and a short signature. It tests encoding only. Signature verification fails.

Version 0, Expiration 245453, KeyType "Ed25519", Certified = REVEAL above,
one signature keyed by 32 bytes of 0xaa, with Payload 01020304

CERT_CBOR (204 bytes)
a5674b65795479706567456432353531396756657273696f6e00694365727469
666965645828000000000003bec8441edc56cebc8e285d02267aa650819f15ad
d7b06ef9b41b2690128dce6559246a45787069726174696f6e1a0003becd6a53
69676e617475726573a15820aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
aaaaaaaaaaaaaaaaaaaaaaaaa2675061796c6f616444010203046f5075626c69
634b657953756d3235365820aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
aaaaaaaaaaaaaaaaaaaaaaaa

SIGNEDUPLOAD_CBOR uses the upload encoding. Its MixDescriptor byte string starts with 0x58cb, which encodes a length of 203 bytes. The contents are the descriptor’s own canonical CBOR. Signature and LoopStats are inline maps.

Signature {PublicKeySum256 32 bytes of 0xbb, Payload 0506}
MixDescriptor {Name "mix1", Epoch 245448, IdentityKey bb, LinkKey cc,
  MixKeys {245448: dd}, Addresses {"tcp": ["tcp://127.0.0.1:1"]},
  every other field empty, nil, or false}
LoopStats {MixIdentityHash 32 bytes of 0xbb, Epoch 245448,
  SegmentRatios {01 then 63 zero bytes: 0.5}}

SIGNEDUPLOAD_CBOR (448 bytes)
a3694c6f6f705374617473a36545706f63681a0003bec86d5365676d656e7452
6174696f73a15840010000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000f938006f4d69784964656e74697479486173685820bbbbbb
bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb695369
676e6174757265a2675061796c6f61644205066f5075626c69634b657953756d
3235365820bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
bbbbbbbbbb6d4d697844657363726970746f7258cbad644e616d65646d697831
6545706f63681a0003bec8674c696e6b4b657941cc674d69784b657973a11a00
03bec841dd6756657273696f6e6069416464726573736573a163746370817174
63703a2f2f3132372e302e302e313a31694b6165747a6368656ef66a4c6f6164
576569676874006b4964656e746974794b657941bb6d4973476174657761794e
6f6465f46d4973536572766963654e6f6465f47241757468656e746963617469
6f6e5479706560774b6165747a6368656e416476657274697a656444617461f6

Automatic topology assignment starts with this SRV, no prior consensus, six mixes, and Layers 3. The authority permutes all six mixes and assigns them to successive layers, under the layer assignment algorithm. The mix numbers 0 through 5 represent ascending identity-key hash order (R-16-5).

SRV     702b1bb93f15155761dc058d56edd07d2a5127478566f520366fb4b490a5e8ae
Perm(6) = [1 5 2 4 3 0]

layer 0 = mix 1, mix 4
layer 1 = mix 5, mix 3
layer 2 = mix 2, mix 0

Direct consensus reply

A successful direct fetch from the Namenlos dirauth annares returns a consensus command. Let B be the byte length of its certificate envelope.

%%{init: {"flowchart":{"diagramPadding":6,"useMaxWidth":false},"gantt":{"useMaxWidth":false},"look":"classic","packet":{"bitWidth":7,"bitsPerRow":48,"rowHeight":48,"useMaxWidth":false},"sequence":{"actorFontSize":14,"actorMargin":24,"diagramMarginX":24,"height":96,"messageFontSize":14,"messageMargin":22,"noteMargin":10,"useMaxWidth":false,"width":128,"wrap":false},"state":{"useMaxWidth":false},"theme":"base","themeCSS":".edgeLabel p { font-family: sans-serif; font-size: 13px; line-height: 1.4; color: #e6edf3; background-color: #34383d; border: 1px solid #c3cbd5; border-radius: 4px; padding: 3px 7px; margin: 0; } .edgeLabel .labelBkg { fill: #34383d; }","themeVariables":{"activationBkgColor":"#48351f","activationBorderColor":"#f3bd66","activeTaskBkgColor":"#48351f","activeTaskBorderColor":"#f3bd66","actorBkg":"#1c3c4c","actorBorder":"#7acee9","actorLineColor":"#7acee9","actorTextColor":"#e6edf3","altSectionBkgColor":"#24282d","background":"#24282d","clusterBkg":"#24282d","clusterBorder":"#c3cbd5","darkMode":true,"edgeLabelBackground":"#24282d","fontFamily":"sans-serif","fontSize":"14px","gridColor":"#59616b","labelBoxBkgColor":"#34383d","labelBoxBorderColor":"#c3cbd5","labelTextColor":"#e6edf3","lineColor":"#c3cbd5","noteBkgColor":"#34383d","noteBorderColor":"#c3cbd5","noteTextColor":"#e6edf3","packet":{"blockFillColor":"#48351f","blockStrokeColor":"#f3bd66","endByteColor":"#c3cbd5","labelColor":"#e6edf3","startByteColor":"#c3cbd5","titleColor":"#e6edf3"},"primaryBorderColor":"#c3cbd5","primaryColor":"#34383d","primaryTextColor":"#e6edf3","secondaryColor":"#34383d","secondaryTextColor":"#e6edf3","sectionBkgColor":"#34383d","sectionBkgColor2":"#1c3c4c","signalColor":"#7acee9","signalTextColor":"#e6edf3","taskBkgColor":"#48351f","taskBorderColor":"#f3bd66","taskTextColor":"#e6edf3","taskTextOutsideColor":"#e6edf3","tertiaryColor":"#24282d","tertiaryTextColor":"#e6edf3","textColor":"#e6edf3","todayLineColor":"#f3bd66"}} }%%
flowchart TB
    %% panel: layers
    accTitle: Direct consensus reply encoding
    accDescr: The Namenlos dirauth annares sends a successful consensus reply to a fetching node. Canonical document CBOR is the Certified field of a certificate envelope with hybrid signatures. That envelope is the payload after the success status in command 19. PQ Noise separately encrypts a four-byte length and the complete command. TCP segments carry the resulting stream over IPv4 datagrams. Segments and datagrams need not align with command boundaries. Numbered layers use different shapes, colors, and outline patterns.
    DOC["<img src='/docs/specs/dirauth/icons/authority.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/directory.svg' alt='' width='32' height='32'/><br/>1. Consensus CBOR<br/>annares dirauth<br/>Version: v1, Epoch: N<br/>Mu: 0.001, LambdaP: 0.001<br/>Topology: 2, 2, 3 mixes<br/>SphinxGeometryHash:<br/>hash of 5-hop geometry<br/>with 3082-byte packets"]
    CERT[["<img src='/docs/specs/dirauth/icons/signature.svg' alt='' width='32' height='32'/><br/>2. Certificate envelope<br/>Canonical CBOR: B bytes<br/>Certified: consensus CBOR<br/>Version: 0, Expiration: N+5<br/>KeyType: Ed25519 Sphincs+<br/>Signatures: at least 4 of 6"]]
    COMMAND["<img src='/docs/specs/dirauth/icons/data.svg' alt='' width='32' height='32'/><br/>3. Directory command<br/>ID: 19 = 0x13, reserved: 0<br/>Body length: BE32(B+1)<br/>Status: 0 = ConsensusOk<br/>Payload: certificate envelope<br/>Total: B+7 bytes"]
    RECORDS("<img src='/docs/specs/dirauth/icons/connection.svg' alt='' width='32' height='32'/><br/>4. PQ Noise records<br/>Handshake: PqXX<br/>Handshake prologue: 0x03<br/>KEM: KYBER768-X25519<br/>ChaCha20-Poly1305<br/>Hash: BLAKE2b-512<br/>Length record: 20 bytes<br/>BE32(B+23), encrypted<br/>plus a 16-byte tag<br/>Command record: B+23 bytes<br/>B+7 encrypted command bytes<br/>plus a 16-byte tag<br/>Advance nonce twice<br/>then rekey")
    TCP(["5. TCP segments<br/>Source port: 65534<br/>Destination: ephemeral port<br/>Header: 20 to 60 bytes<br/>Payload: stream slice<br/>Reply: B+43 stream bytes"])
    IP["6. IPv4 datagrams<br/>Source: 192.87.90.45<br/>Destination: fetching node<br/>Version: 4, protocol: 6 = TCP<br/>Header: 20 to 60 bytes<br/>Payload before fragmentation:<br/>one TCP segment"]
    RECEIVER["<img src='/docs/specs/dirauth/icons/mix.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/gateway.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/service.svg' alt='' width='32' height='32'/><img src='/docs/specs/dirauth/icons/replica.svg' alt='' width='32' height='32'/><br/>Fetching node<br/>Reassemble and decrypt<br/>Verify consensus signatures<br/>and acceptance conditions"]
    DOC -->|"Certified byte string"| CERT
    CERT -->|"status byte, then payload"| COMMAND
    COMMAND -->|"encrypt complete command"| RECORDS
    RECORDS -->|"concatenate records<br/>and split stream into segments"| TCP
    TCP -->|"encapsulate segment"| IP
    IP -->|"receiver processes layers<br/>in reverse"| RECEIVER
    classDef documentLayer fill:#48351f,stroke:#f3bd66,color:#ffffff
    classDef certificateLayer fill:#153d35,stroke:#73d6b8,color:#ffffff,stroke-dasharray:6 3
    classDef commandLayer fill:#34383d,stroke:#c3cbd5,color:#ffffff
    classDef noiseLayer fill:#1c3c4c,stroke:#7acee9,color:#ffffff,stroke-dasharray:2 3
    classDef tcpLayer fill:#342b4c,stroke:#c3abff,color:#ffffff,stroke-dasharray:8 3
    classDef ipLayer fill:#492d38,stroke:#eab2ce,color:#ffffff,stroke-dasharray:8 3 2 3
    class DOC documentLayer
    class CERT certificateLayer
    class COMMAND commandLayer
    class RECORDS noiseLayer
    class TCP tcpLayer
    class IP ipLayer
    class RECEIVER local
classDef directory fill:#48351f,stroke:#f3bd66,color:#ffffff
classDef packet fill:#342b4c,stroke:#c3abff,color:#ffffff
classDef link fill:#1c3c4c,stroke:#7acee9,color:#ffffff
classDef local fill:#34383d,stroke:#c3cbd5,color:#ffffff

The Namenlos authority configuration sets the address and cryptographic schemes. The consensus command encoder adds the status and command header. The session encoder adds the two encrypted records after the PQ Noise handshake. TCP segments carry slices of the encrypted stream inside IPv4 datagrams. Their boundaries need not align with directory commands. IPv4 datagrams can fragment in transit. Directory commands travel directly between peers, outside Sphinx packets. The gateway consensus commands use different framing.