p2ns/docs/plugins/domain.consensus.md

Domain Consensus Plugin

A comprehensive interface for visualizing and analyzing consensus within the P2NS network. This plugin provides real-time insights into domain consensus states, voting patterns, claims, and quorum information.

Overview

The Domain Consensus plugin offers an advanced dashboard for monitoring and understanding how domains achieve consensus in the P2NS network. It provides detailed views of:

• Domain consensus statuses (resolved, insufficient quorum, ties, etc.)
• Vote counts and distributions
• Claims and claimants
• Quorum progress and requirements
• Real-time consensus metrics
• Sidecar health (open, bootstrapComplete, event/domain counts) on the overview dashboard

Resolution data comes from the Autobase consensus sidecar (RFC 0001); see CONSENSUS.md for algorithm details.

Features

Overview Dashboard

• Aggregate Statistics: High-level metrics showing total domains, resolved domains, domains with insufficient quorum, tied domains, and active peers
• Consensus Metrics: Total resolutions, quorum failures, total votes cast, and average votes per domain
• Visual Charts:
  • Pie chart showing consensus status distribution
  • Bar chart displaying consensus metrics (resolutions, quorum failures, ties, validation failures)

Domain List View

• Comprehensive Domain Table: Lists all domains with their consensus information
• Search Functionality: Search domains by name
• Status Filtering: Filter domains by consensus status (resolved, insufficient quorum, tie, no claims, error)
• Sortable Columns: Sort by domain name, status, resolved claimant, votes, quorum, or active peers
• Quick Actions: View detailed information for any domain with a single click

Domain Detail View

• Detailed Consensus Information: Complete consensus state for a specific domain
• Claims Display: All claims with claimant IDs, hashes, timestamps, and vote counts
• Votes Display: All votes showing which voters voted for which claimants
• Quorum Progress: Visual progress indicator showing quorum status
• Vote Distribution Chart: Bar chart showing vote distribution across claimants
• Resolved Information: Displays resolved claimant and hash when consensus is reached

Real-Time Updates

• WebSocket Integration: Real-time updates as consensus changes occur
• Live Metrics: Automatically updates statistics and charts without page refresh
• Connection Status: Visual indicator showing WebSocket connection status

Usage

Accessing the Plugin

Once P2NS is running and the plugin is loaded, access the Domain Consensus interface at:

https://domain.consensus

Navigation

• Overview: Click "Overview" in the sidebar to view the main dashboard with aggregate metrics
• Domain List: Click "Domain List" to see all domains and their consensus statuses
• Domain Details: Click "View Details" on any domain in the domain list to see detailed information

Understanding Consensus Statuses

• Resolved (Green): Domain has reached consensus with a resolved claimant and hash
• Insufficient Quorum (Yellow): Domain has claims and votes but hasn't met the minimum quorum requirement
• Tie (Orange): Multiple claimants have the same number of votes
• No Claims (Gray): Domain has no claims registered
• Error (Red): An error occurred while determining consensus

Domain List Features

1. Search: Type in the search box to filter domains by name
2. Filter: Use the status dropdown to filter by consensus status
3. Sort: Click column headers to sort the table
4. View Details: Click "View Details" button to see comprehensive domain information

Domain Detail Features

1. Overview Cards: Quick view of total votes, minimum required, quorum status, and active peers
2. Quorum Progress: Visual progress bar showing quorum percentage
3. Resolved Information: When resolved, shows the resolved claimant and hash with copy buttons
4. Claims Table: All claims with their vote counts
5. Votes Table: Complete list of all votes
6. Vote Distribution Chart: Visual representation of vote distribution

Architecture

Backend API Endpoints

The plugin exposes the following API endpoints:

• GET /api/overview - Returns aggregate consensus metrics, statistics, and sidecar health
• GET /api/domains - Returns list of all domains with consensus status
• GET /api/domain/:domain - Returns detailed consensus state for a specific domain
• GET /api/metrics - Returns consensus metrics
• GET /api/peers - Returns active peer count and quorum information

Frontend Components

• app.js: Main application logic, view management, and WebSocket handling
• views/overview.js: Overview dashboard with charts and statistics
• views/domain-list.js: Domain list table with search, filter, and sort
• views/domain-detail.js: Detailed domain view with claims, votes, and charts
• api.js: API client with caching
• websocket.js: WebSocket client for real-time updates
• utils.js: Utility functions for formatting and display

Real-Time Updates

The plugin uses WebSocket connections to receive real-time updates:

• Update Events: Periodic updates every 5 seconds with current system state
• Domain Events: Immediate notifications when domains are added or removed
• Chart Updates: Charts automatically update without full page re-render

Technical Details

Overview Response (sidecar)

The overview endpoint includes a sidecar object (same shape as admin GET /api/consensus/status):

{
  open: boolean,
  ready: boolean,
  writable: boolean,
  bootstrapComplete: boolean,
  eventCount: number,
  domainCount: number,
  lastApplyAt: number | null,
  indexedLength: number,
  length: number,
  key: string | null  // hex
}

Consensus State Structure

Each domain's consensus state includes:

{
  status: 'resolved' | 'insufficient_quorum' | 'tie' | 'no_claims' | 'error',
  hash: string | null,
  resolvedClaimant: string | null,
  voteCounts: { [claimant: string]: number },
  activePeers: number,
  quorumMet: boolean,
  minVotes: number,
  totalVotes: number,
  lastResolution: number | null
}

Quorum Calculation

Quorum is calculated based on:

• Active Peers: Number of connected peers in the network
• Quorum Threshold: Configurable threshold (default: 50% of active peers)
• Minimum Votes: Maximum of configured minimum votes and calculated threshold

Quorum is met when totalVotes >= minVotes.

Data Caching

• API responses are cached for 30 seconds to reduce server load
• Cache is automatically invalidated on WebSocket updates
• Manual cache invalidation available through API calls

Requirements

• P2NS system running with DNS service initialized
• WebSocket support enabled
• Modern browser with JavaScript enabled
• Chart.js library (loaded via CDN)

Browser Compatibility

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)

Troubleshooting

Charts Not Displaying

• Ensure the view container is visible before charts render
• Check browser console for JavaScript errors
• Verify Chart.js library is loaded

WebSocket Connection Issues

• Check connection status indicator in header
• Verify P2NS is running and WebSocket server is active
• Check browser console for WebSocket errors

Domain List Not Showing

• Verify DNS service is initialized
• Check that domains exist in the network
• Look for errors in browser console

Real-Time Updates Not Working

• Check WebSocket connection status
• Verify WebSocket server is running
• Check browser console for errors

Development

File Structure

domain.consensus/
├── config.json              # Plugin configuration
├── index.js                 # Backend handler and API endpoints
├── README.md                # This file
└── www/                     # Frontend files
    ├── index.html           # Main HTML structure
    ├── css/
    │   ├── style.css        # Custom styles
    │   └── tailwind.css     # Tailwind CSS framework
    └── js/
        ├── app.js           # Main application logic
        ├── api.js           # API client
        ├── websocket.js     # WebSocket client
        ├── utils.js         # Utility functions
        └── views/
            ├── overview.js      # Overview dashboard
            ├── domain-list.js   # Domain list view
            └── domain-detail.js # Domain detail view

Building

The plugin uses Tailwind CSS. To rebuild the CSS:

npm run build:css

Testing

1. Start P2NS
2. Navigate to https://domain.consensus
3. Verify all views load correctly
4. Test search, filter, and sort functionality
5. Verify WebSocket updates work

License

MIT License - Same as P2NS project

Author

P2NS Team

Related Documentation

• Plugin System Documentation - Complete plugin system guide
• Plugin SDK Reference - Full SDK API reference
• Plugin Overview - Plugin system overview
• Consensus Mechanism - P2NS consensus deep dive
• RFC 0001: Autobase Consensus - Implemented sidecar specification