S\P

Governance

Guardian Nodes

Regional enforcement nodes that mirror ledger shards and raise disputes.

Guardian Node Handbook

Complete guide for Guardian Node operators

What is a Guardian Node?

A Guardian Node is a regional integrity node that:

  • Mirrors the global ledger - Maintains a local copy of the SOVEREIGN\PROVENANCE ledger
  • Enforces rights - Evaluates Accord rules and cultural protocols for regional use
  • Generates integrity reports - Provides transparency and accountability
  • Participates in governance - Contributes to protocol decisions (future)

Guardian Nodes are typically operated by cities, institutions, cultural districts, and platforms to ensure regional integrity and enforce cultural protocols.

What a Node Operator Is Responsible For

As a Guardian Node operator, you are responsible for:

  1. Deployment & Configuration

    • Deploying and configuring the node
    • Setting up database and dependencies
    • Configuring regional and cultural protocol settings

  2. Monitoring & Maintenance

    • Monitoring node health and sync status
    • Ensuring the node stays in sync with the global ledger
    • Generating and reviewing integrity reports
    • Tracking cross-border replication jobs and sealing/unsealing actions tied to your sovereignZoneId

  3. Troubleshooting

    • Diagnosing sync issues
    • Resolving connectivity problems
    • Addressing database or storage issues

  4. Security

    • Keeping node software updated
    • Securing API access
    • Protecting node keys and credentials

How to Deploy a Node (Local Outline)

Prerequisites

  • Go 1.21+ (for building from source)
  • PostgreSQL 14+ (for local state storage)
  • Access to the global Ledger service
  • Docker (optional, for containerized deployment)

Configuration

The Guardian Node is configured via environment variables:

# Required
NODE_ID=urn:sp:node:your-node-id
SOVEREIGN_ZONE_ID=eu_central         # must match an entry from packages/sovereign-zones
JURISDICTION=EU
REGION=eu-central-1
LEDGER_SERVICE_URL=https://ledger.sovereign.provenance
DB_URL=postgres://user:pass@localhost/guardian_node?sslmode=disable

# Optional
MODE=sovereign  # or 'mirror'
HTTP_BIND_ADDRESS=:8083

Deployment Options

Option 1: Docker

docker run -d \
  -e NODE_ID=urn:sp:node:city-seattle \
  -e REGION=us-west \
  -e LEDGER_SERVICE_URL=https://ledger.sovereign.provenance \
  -e DB_URL=postgres://... \
  -e MODE=sovereign \
  -p 8083:8083 \
  sovprovenance/guardian-node:latest

Option 2: From Source

cd apps/guardian-node
go build -o guardian-node ./cmd/guardian-node
./guardian-node

Option 3: Kubernetes

See infra/k8s/guardian-node/ for Kubernetes deployment manifests.

How to Check Node Health & Reports

HTTP API Endpoints

The Guardian Node exposes an HTTP API for monitoring and operations:

Get Node Status

curl http://localhost:8083/v1/node/status

Response:

{
  "nodeId": "urn:sp:node:city-seattle",
  "region": "us-west",
  "lastLedgerSync": "2024-01-15T10:30:00Z",
  "mode": "sovereign",
  "integrityStatus": {
    "valid": true,
    "lastChecked": "2024-01-15T11:00:00Z"
  }
}

Generate Integrity Report

curl -X POST http://localhost:8083/v1/node/reports

Response:

{
  "nodeId": "urn:sp:node:city-seattle",
  "generatedAt": "2024-01-15T11:00:00Z",
  "period": {
    "start": "2024-01-14T11:00:00Z",
    "end": "2024-01-15T11:00:00Z"
  },
  "eventsMirrored": 1234,
  "enforcementChecks": 567,
  "integrityChecks": {
    "passed": 1234,
    "failed": 0
  }
}

Enforce Rights

curl -X POST http://localhost:8083/v1/node/enforce \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": "urn:sp:passport:abc123",
    "proposedUse": {
      "type": "display",
      "geographicRegion": "us-west"
    },
    "requestingIdentityId": "urn:sp:identity:xyz789"
  }'

CLI Help

Get help for the Guardian Node CLI:

guardian-node --help
# or
guardian-node -h

This shows:

  • Description of the Node
  • Configuration options
  • Dependencies
  • HTTP API endpoints
  • Examples

How Node Fits into Governance

Guardian Nodes play a crucial role in the SOVEREIGN\PROVENANCE governance model:

  1. Regional Representation - Nodes represent regional interests in protocol decisions
  2. Integrity Verification - Nodes verify ledger integrity and report issues
  3. Cultural Protocol Enforcement - Nodes enforce regional and cultural protocols
  4. Transparency - Nodes generate public integrity reports and sealed-proof unlock logs scoped to their jurisdiction

Future Governance Features

  • Voting - Nodes will participate in protocol update votes
  • Proposals - Nodes can submit governance proposals
  • Dispute Resolution - Nodes can participate in dispute resolution

Troubleshooting

Node Not Syncing

  1. Check connectivity to Ledger service:

    curl $LEDGER_SERVICE_URL/health

  2. Check database connection:

    psql $DB_URL -c "SELECT 1;"

  3. Review node logs for errors

Node Health Issues

  1. Check status endpoint for integrityStatus.valid
  2. Review integrity reports for failed checks
  3. Check database for sync gaps

Common Issues

  • Database connection errors - Verify DB_URL and PostgreSQL is running
  • Ledger service unreachable - Check network connectivity and service URL
  • Sync lag - Normal during high activity; monitor lastLedgerSync timestamp

Best Practices

  1. Regular Monitoring - Check node status daily
  2. Backup Strategy - Backup mirrored ledger data regularly
  3. Update Software - Keep node software updated
  4. Public Transparency - Publish integrity reports publicly
  5. Regional Coordination - Coordinate with other regional nodes

Resources