555 lines
17 KiB
Markdown
555 lines
17 KiB
Markdown
# 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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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`):
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
```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**:
|
|
|
|
```json
|
|
{
|
|
"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**:
|
|
|
|
```json
|
|
{
|
|
"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**:
|
|
|
|
```json
|
|
{
|
|
"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):
|
|
|
|
```json
|
|
{
|
|
"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`:
|
|
|
|
```bash
|
|
# 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**:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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
|