vaultsovereign/vm-core

Fork 0

Files

Vault Sovereign 110d644e10 Initialize repository snapshot

2025-12-27 00:10:32 +00:00

17 KiB

Raw Blame History

VAULTMESH-MESH-ENGINE.md

Civilization Ledger Federation Primitive

Nodes that anchor together, survive together.

Mesh is VaultMesh's topology memory — tracking how nodes discover each other, establish trust, share capabilities, and evolve their federation relationships over time. Every topology change becomes evidence.

1. Scroll Definition

Property	Value
Scroll Name	`Mesh`
JSONL Path	`receipts/mesh/mesh_events.jsonl`
Root File	`ROOT.mesh.txt`
Receipt Types	`mesh_node_join`, `mesh_node_leave`, `mesh_route_change`, `mesh_capability_grant`, `mesh_capability_revoke`, `mesh_topology_snapshot`

2. Core Concepts

2.1 Nodes

A node is any VaultMesh-aware endpoint that participates in the federation.

{
  "node_id": "did:vm:node:brick-01",
  "display_name": "BRICK-01 (Dublin Primary)",
  "node_type": "infrastructure",
  "endpoints": {
    "portal": "https://brick-01.vaultmesh.local:8443",
    "wireguard": "10.77.1.1",
    "tailscale": "brick-01.tail.net"
  },
  "public_key": "ed25519:abc123...",
  "capabilities": ["anchor", "storage", "compute", "oracle"],
  "status": "active",
  "joined_at": "2025-06-15T00:00:00Z",
  "last_seen": "2025-12-06T14:30:00Z",
  "tags": ["production", "eu-west", "akash"]
}

Node types:

infrastructure — BRICK servers, compute nodes
edge — mobile devices, sovereign phones, field endpoints
oracle — compliance oracle instances
guardian — dedicated anchor/sentinel nodes
external — federated nodes from other VaultMesh deployments

2.2 Routes

A route defines how traffic flows between nodes or segments.

{
  "route_id": "route-brick01-to-brick02",
  "source": "did:vm:node:brick-01",
  "destination": "did:vm:node:brick-02",
  "transport": "wireguard",
  "priority": 1,
  "status": "active",
  "latency_ms": 12,
  "established_at": "2025-06-20T00:00:00Z"
}

Routes can be:

Direct: Node-to-node (WireGuard, Tailscale)
Relayed: Through a gateway node
Redundant: Multiple paths with failover priority

2.3 Capabilities

Capabilities are the trust primitives — what a node is permitted to do within the federation.

{
  "capability_id": "cap:brick-01:anchor:2025",
  "node_id": "did:vm:node:brick-01",
  "capability": "anchor",
  "scope": "global",
  "granted_by": "did:vm:node:portal-01",
  "granted_at": "2025-06-15T00:00:00Z",
  "expires_at": "2026-06-15T00:00:00Z",
  "constraints": {
    "max_anchor_rate": "100/day",
    "allowed_scrolls": ["*"]
  }
}

Standard capabilities:

anchor — can submit roots to anchor backends
storage — can store receipts and artifacts
compute — can execute drills, run agents
oracle — can issue compliance answers
admin — can grant/revoke capabilities to other nodes
federate — can establish trust with external meshes

2.4 Topology Snapshots

Periodic snapshots capture the full mesh state — useful for auditing, disaster recovery, and proving historical topology.

3. Mapping to Eternal Pattern

3.1 Experience Layer (L1)

CLI (vm-mesh):

# Node operations
vm-mesh node list
vm-mesh node show brick-01
vm-mesh node join --config node-manifest.json
vm-mesh node leave --node brick-02 --reason "decommissioned"

# Route operations
vm-mesh route list
vm-mesh route add --from brick-01 --to brick-03 --transport tailscale
vm-mesh route test --route route-brick01-to-brick02

# Capability operations
vm-mesh capability list --node brick-01
vm-mesh capability grant --node brick-02 --capability oracle --expires 2026-01-01
vm-mesh capability revoke --node brick-02 --capability anchor --reason "security incident"

# Topology
vm-mesh topology show
vm-mesh topology snapshot --output snapshots/2025-12-06.json
vm-mesh topology diff --from snapshots/2025-11-01.json --to snapshots/2025-12-06.json

# Health
vm-mesh health --full
vm-mesh ping --all

MCP Tools:

mesh_node_status — get node details and health
mesh_list_nodes — enumerate active nodes
mesh_topology_summary — current topology overview
mesh_capability_check — verify if node has capability
mesh_route_health — check route latency and status

Portal HTTP:

GET /mesh/nodes — list nodes
GET /mesh/nodes/{node_id} — node details
POST /mesh/nodes/join — register new node
POST /mesh/nodes/{node_id}/leave — deregister node
GET /mesh/routes — list routes
POST /mesh/routes — add route
GET /mesh/capabilities/{node_id} — node capabilities
POST /mesh/capabilities/grant — grant capability
POST /mesh/capabilities/revoke — revoke capability
GET /mesh/topology — current topology
POST /mesh/topology/snapshot — create snapshot

3.2 Engine Layer (L2)

Step 1 — Plan → `mesh_change_contract.json`

For simple operations (single node join, route add), the contract is implicit.

For coordinated topology changes, an explicit contract:

{
  "change_id": "mesh-change-2025-12-06-001",
  "title": "Add BRICK-03 to Dublin Cluster",
  "initiated_by": "did:vm:node:portal-01",
  "initiated_at": "2025-12-06T11:00:00Z",
  "change_type": "node_expansion",
  "operations": [
    {
      "op_id": "op-001",
      "operation": "node_join",
      "target": "did:vm:node:brick-03",
      "config": {
        "display_name": "BRICK-03 (Dublin Secondary)",
        "node_type": "infrastructure",
        "endpoints": {
          "portal": "https://brick-03.vaultmesh.local:8443",
          "wireguard": "10.77.1.3"
        },
        "public_key": "ed25519:def456..."
      }
    },
    {
      "op_id": "op-002",
      "operation": "route_add",
      "config": {
        "source": "did:vm:node:brick-01",
        "destination": "did:vm:node:brick-03",
        "transport": "wireguard"
      }
    },
    {
      "op_id": "op-003",
      "operation": "route_add",
      "config": {
        "source": "did:vm:node:brick-02",
        "destination": "did:vm:node:brick-03",
        "transport": "wireguard"
      }
    },
    {
      "op_id": "op-004",
      "operation": "capability_grant",
      "config": {
        "node_id": "did:vm:node:brick-03",
        "capability": "storage",
        "scope": "local",
        "expires_at": "2026-12-06T00:00:00Z"
      }
    }
  ],
  "requires_approval": ["portal-01"],
  "rollback_on_failure": true
}

Step 2 — Execute → `mesh_change_state.json`

{
  "change_id": "mesh-change-2025-12-06-001",
  "status": "in_progress",
  "created_at": "2025-12-06T11:00:00Z",
  "updated_at": "2025-12-06T11:05:00Z",
  "operations": [
    {
      "op_id": "op-001",
      "status": "completed",
      "completed_at": "2025-12-06T11:02:00Z",
      "result": {
        "node_registered": true,
        "handshake_verified": true
      }
    },
    {
      "op_id": "op-002",
      "status": "completed",
      "completed_at": "2025-12-06T11:03:00Z",
      "result": {
        "route_established": true,
        "latency_ms": 8
      }
    },
    {
      "op_id": "op-003",
      "status": "in_progress",
      "started_at": "2025-12-06T11:04:00Z"
    },
    {
      "op_id": "op-004",
      "status": "pending"
    }
  ],
  "topology_before_hash": "blake3:aaa111...",
  "approvals": {
    "portal-01": {
      "approved_at": "2025-12-06T11:01:00Z",
      "signature": "ed25519:..."
    }
  }
}

Status transitions:

draft → pending_approval → in_progress → completed
                                       ↘ partial_failure → rollback → rolled_back
                                       ↘ failed → rollback → rolled_back

Step 3 — Seal → Receipts

Each operation in a change produces its own receipt, plus a summary receipt for coordinated changes.

Node Join Receipt:

{
  "type": "mesh_node_join",
  "node_id": "did:vm:node:brick-03",
  "display_name": "BRICK-03 (Dublin Secondary)",
  "node_type": "infrastructure",
  "timestamp": "2025-12-06T11:02:00Z",
  "initiated_by": "did:vm:node:portal-01",
  "change_id": "mesh-change-2025-12-06-001",
  "endpoints_hash": "blake3:...",
  "public_key_fingerprint": "SHA256:...",
  "tags": ["mesh", "node", "join", "infrastructure"],
  "root_hash": "blake3:bbb222..."
}

Route Change Receipt:

{
  "type": "mesh_route_change",
  "route_id": "route-brick01-to-brick03",
  "operation": "add",
  "source": "did:vm:node:brick-01",
  "destination": "did:vm:node:brick-03",
  "transport": "wireguard",
  "timestamp": "2025-12-06T11:03:00Z",
  "initiated_by": "did:vm:node:portal-01",
  "change_id": "mesh-change-2025-12-06-001",
  "latency_ms": 8,
  "tags": ["mesh", "route", "add"],
  "root_hash": "blake3:ccc333..."
}

Capability Grant Receipt:

{
  "type": "mesh_capability_grant",
  "capability_id": "cap:brick-03:storage:2025",
  "node_id": "did:vm:node:brick-03",
  "capability": "storage",
  "scope": "local",
  "granted_by": "did:vm:node:portal-01",
  "timestamp": "2025-12-06T11:06:00Z",
  "expires_at": "2026-12-06T00:00:00Z",
  "change_id": "mesh-change-2025-12-06-001",
  "tags": ["mesh", "capability", "grant", "storage"],
  "root_hash": "blake3:ddd444..."
}

Topology Snapshot Receipt (periodic):

{
  "type": "mesh_topology_snapshot",
  "snapshot_id": "snapshot-2025-12-06-001",
  "timestamp": "2025-12-06T12:00:00Z",
  "node_count": 5,
  "route_count": 12,
  "capability_count": 23,
  "nodes": ["brick-01", "brick-02", "brick-03", "portal-01", "oracle-01"],
  "topology_hash": "blake3:eee555...",
  "snapshot_path": "snapshots/mesh/2025-12-06-001.json",
  "tags": ["mesh", "snapshot", "topology"],
  "root_hash": "blake3:fff666..."
}

3.3 Ledger Layer (L3)

Receipt Types:

Type	When Emitted
`mesh_node_join`	Node registered in mesh
`mesh_node_leave`	Node deregistered
`mesh_route_change`	Route added, removed, or modified
`mesh_capability_grant`	Capability granted to node
`mesh_capability_revoke`	Capability revoked from node
`mesh_topology_snapshot`	Periodic full topology capture

Merkle Coverage:

All receipts append to receipts/mesh/mesh_events.jsonl
ROOT.mesh.txt updated after each append
Guardian anchors Mesh root in anchor cycles

4. Query Interface

mesh_query_events.py:

# All events for a node
vm-mesh query --node brick-01

# Events by type
vm-mesh query --type node_join
vm-mesh query --type capability_grant

# Date range
vm-mesh query --from 2025-11-01 --to 2025-12-01

# By change ID (coordinated changes)
vm-mesh query --change-id mesh-change-2025-12-06-001

# Capability history for a node
vm-mesh query --node brick-02 --type capability_grant,capability_revoke

# Export topology history
vm-mesh query --type topology_snapshot --format json > topology_history.json

Topology Diff Tool:

# Compare two snapshots
vm-mesh topology diff \
  --from snapshots/mesh/2025-11-01.json \
  --to snapshots/mesh/2025-12-06.json

# Output:
# + node: brick-03 (joined)
# + route: brick-01 → brick-03
# + route: brick-02 → brick-03
# + capability: brick-03:storage
# ~ route: brick-01 → brick-02 (latency: 15ms → 12ms)

5. Design Gate Checklist

Question	Mesh Answer
Clear entrypoint?	✅ CLI (`vm-mesh`), MCP tools, Portal HTTP
Contract produced?	✅ `mesh_change_contract.json` (explicit for coordinated changes, implicit for single ops)
State object?	✅ `mesh_change_state.json` tracking operation progress
Receipts emitted?	✅ Six receipt types covering all topology events
Append-only JSONL?	✅ `receipts/mesh/mesh_events.jsonl`
Merkle root?	✅ `ROOT.mesh.txt`
Guardian anchor path?	✅ Mesh root included in ProofChain
Query tool?	✅ `mesh_query_events.py` + topology diff

6. Mesh Health & Consensus

6.1 Heartbeat Protocol

Nodes emit periodic heartbeats to prove liveness:

{
  "type": "heartbeat",
  "node_id": "did:vm:node:brick-01",
  "timestamp": "2025-12-06T14:30:00Z",
  "sequence": 847293,
  "load": {
    "cpu_percent": 23,
    "memory_percent": 67,
    "disk_percent": 45
  },
  "routes_healthy": 4,
  "routes_degraded": 0
}

Heartbeats are not receipted individually (too high volume), but:

Aggregated into daily health summaries
Missed heartbeats trigger alerts
Prolonged absence → automatic mesh_node_leave with reason: "timeout"

6.2 Quorum Requirements

Critical mesh operations require quorum:

Operation	Quorum
Node join	1 admin node
Node forced leave	2 admin nodes
Capability grant (global scope)	2 admin nodes
Capability revoke	1 admin node (immediate security)
Federation trust establishment	All admin nodes

7. Federation (Multi-Mesh)

When VaultMesh instances need to federate (e.g., partner organizations, geographic regions):

7.1 Trust Establishment

{
  "type": "mesh_federation_trust",
  "local_mesh": "did:vm:mesh:vaultmesh-dublin",
  "remote_mesh": "did:vm:mesh:partner-berlin",
  "trust_level": "limited",
  "established_at": "2025-12-06T15:00:00Z",
  "expires_at": "2026-12-06T00:00:00Z",
  "shared_capabilities": ["oracle_query", "receipt_verify"],
  "gateway_node": "did:vm:node:portal-01",
  "remote_gateway": "did:vm:node:partner-gateway-01",
  "trust_anchor": "blake3:ggg777..."
}

Trust levels:

isolated — no cross-mesh communication
limited — specific capabilities only (e.g., query each other's Oracle)
reciprocal — mutual receipt verification, shared anchoring
full — complete federation (rare, high-trust scenarios)

7.2 Cross-Mesh Receipts

When a federated mesh verifies or references receipts:

{
  "type": "mesh_cross_verify",
  "local_receipt": "receipt:treasury:settle-2025-12-06-001",
  "remote_mesh": "did:vm:mesh:partner-berlin",
  "verified_by": "did:vm:node:partner-oracle-01",
  "verification_timestamp": "2025-12-06T16:00:00Z",
  "verification_result": "valid",
  "remote_root_at_verification": "blake3:hhh888..."
}

8. Integration Points

System	Integration
Guardian	Anchors `ROOT.mesh.txt`; alerts on unexpected topology changes
Treasury	Node join can auto-create Treasury accounts; node leave triggers account closure workflow
Oracle	Can query Mesh for node capabilities ("Does BRICK-02 have anchor capability?")
Drills	Multi-node drills require Mesh to verify all participants are active and routable
OffSec	Security incidents can trigger emergency capability revocations via Mesh

9. Future Extensions

Auto-discovery: Nodes find each other via mDNS/DHT in local networks
Geographic awareness: Route optimization based on node locations
Bandwidth metering: Track data flow between nodes for Treasury billing
Mesh visualization: Real-time topology graph in Portal UI
Chaos testing: Controlled route failures to test resilience
Zero-trust verification: Continuous capability re-verification

17 KiB Raw Blame History