p2ns/docs/rfcs/0001-autobase-consensus.md

RFC 0001: Autobase Consensus

Status

Implemented

Background

P2NS resolves domain ownership with quorum-based voting over claim and vote records stored in the Autopass KV ledger. The previous resolver scanned all KV entries on every query, which caused maintenance overhead, non-deterministic duplicate-vote handling (iteration order), and legacy timestamp instability.

Goals

• Replace the KV-scan resolver with an Autobase apply-based consensus sidecar as the sole production read path.
• Deterministic event replay in Autobase linearized order.
• Bootstrap replay from existing dnsPass claim/vote entries for network migration.
• Sidecar health diagnostics in admin API and domain.consensus plugin.

Non-Goals

• Changing claim/vote KV key format or plugin SDK method signatures.
• In-process legacy engine fallback or feature-flagged dual resolver.
• Removing Autopass KV as the durable write store for claims and votes.

Architecture

flowchart TD
    Writes[domains.js voteForDomain] --> Queue[dns-pass-queue.js]
    Queue --> DnsPass[Autopass KV]
    Queue --> Events[Consensus Autobase append]
    Events --> Apply[consensus-apply.js]
    Apply --> View[consensus-view.js]
    View --> GetState[getConsensusState]
    Resolver[consensus-resolver.js] --> View

Autopass KV remains the durable store. Every local claim/vote mutation dual-writes a typed event to the consensus Autobase. The apply handler maintains per-domain state; getConsensusState reads from the view and runs the pure resolver.

Event Model

Type	Payload	Source KV
claim_upsert	domain, claimant, hash, timestamp, ssl, clients	claim:{domain}:{claimant} add
claim_remove	domain, claimant	claim:{domain}:{claimant} remove
vote_upsert	domain, claimant, voter	vote:{domain}:{claimant}:{voter} add
vote_remove	domain, claimant, voter	vote:{domain}:{claimant}:{voter} remove

Events are JSON-encoded buffers appended to the consensus Autobase.

Apply Semantics

Events are processed in Autobase linearized order:

1. claim_upsert — set or replace claim for claimant on domain.
2. claim_remove — remove claim; drop votes for that claimant on the domain.
3. vote_upsert — set voter's vote (last event per voter wins).
4. vote_remove — remove voter's vote.

Resolution (consensus-resolver.js) runs at read time with the same quorum, tie-break, vote-validation, and single-local-claim rules as the prior implementation.

Determinism Fixes

• Legacy hash-only claims use timestamp: 0 (not runtime Date.now()).
• Duplicate votes resolved by event order in the Autobase stream, not KV list iteration order.

Migration

1. Genesis or first peer with empty sidecar bootstraps by replaying dnsPass claim/vote entries sorted by (type, domain, timestamp, claimant, voter).
2. Network manifest stores consensusAutobaseKey for joiners.
3. Joiners open the sidecar with the manifest bootstrap key and replicate via consensusBase.replicate(connection) on swarm connections.
4. Local claim/vote writes dual-append events after successful dnsPass operations.

Configuration

Existing consensus env vars unchanged (CONSENSUS_QUORUM_THRESHOLD, CONSENSUS_MIN_VOTES, CONSENSUS_TIE_BREAKER, CONSENSUS_VOTE_VALIDATION).

Variable	Default	Description
CONSENSUS_INIT_TIMEOUT_MS	30000	Timeout for sidecar ready() / update() during init

Sidecar Lifecycle

• Background init: startConsensusForNetwork() runs after Autopass pairing so swarm join is not blocked.
• Corestore namespace: p2ns-consensus
• Bootstrap: Writable nodes replay dnsPass claim/vote entries into the sidecar when empty; manifest stores consensusAutobaseKey.
• Hydration: Read-only joiners rebuild the apply view from local dnsPass without appending bootstrap events when the replicated sidecar is empty or lagging.
• Replication: consensusBase.replicate(connection) on swarm connections alongside Autopass replication.

Acceptance Criteria

• Legacy KV-scan getConsensusState removed from codebase.
• test-scripts/consensus-resolver.test.js and test-scripts/consensus-apply.test.js pass in CI.
• Admin GET /api/consensus/status reports sidecar health.
• docs/CONSENSUS.md aligned with implementation.

Rollback

Deploy the previous P2NS release. Autopass KV data is unchanged; upgrading again rebuilds the sidecar from bootstrap replay.

Implementation Map

Module	Path
Pure resolver	includes/core/consensus-resolver.js
Event codec	includes/core/consensus-events.js
Apply handler	includes/core/consensus-apply.js
Autobase lifecycle	includes/core/consensus-autobase.js
Read API	includes/core/consensus-view.js
Dual-write	includes/core/dns-pass-queue.js
Manifest key	includes/infrastructure/network-manifest.js

Changelog

• 2026-05-30: Production cutover — Autobase sidecar replaces KV-scan resolver; background init, joiner hydration, and CONSENSUS_INIT_TIMEOUT_MS added; RFC expanded from evaluation draft to implemented spec.