561 lines
16 KiB
Markdown
561 lines
16 KiB
Markdown
# VAULTMESH-FEDERATION-PROTOCOL.md
|
|
**Cross-Mesh Trust and Receipt Sharing**
|
|
|
|
> *Sovereign meshes that verify each other become civilizations that remember together.*
|
|
|
|
The Federation Protocol defines how independent VaultMesh deployments establish trust, share receipts, and create a network of mutually-witnessing civilization ledgers.
|
|
|
|
---
|
|
|
|
## 1. Federation Philosophy
|
|
|
|
### 1.1 Sovereignty First
|
|
|
|
Each VaultMesh instance is **sovereign** — it controls its own:
|
|
- Identity roots
|
|
- Anchor backends
|
|
- Governance rules
|
|
- Data retention
|
|
- Access policies
|
|
|
|
Federation doesn't compromise sovereignty. It creates **voluntary witness relationships** where meshes choose to verify and attest to each other's receipts.
|
|
|
|
### 1.2 The Witness Network
|
|
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐
|
|
│ VaultMesh-A │◄───────►│ VaultMesh-B │
|
|
│ (Dublin) │ witness │ (Berlin) │
|
|
└────────┬────────┘ └────────┬────────┘
|
|
│ │
|
|
│ witness │
|
|
│ ┌─────────────────┐ │
|
|
└───►│ VaultMesh-C │◄───┘
|
|
│ (Singapore) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
When Mesh-A anchors a root, Mesh-B and Mesh-C can:
|
|
1. Verify the anchor independently
|
|
2. Record their verification as a receipt
|
|
3. Include Mesh-A's root in their own anchor cycles
|
|
|
|
This creates **redundant civilizational memory** — even if one mesh is compromised or lost, the others retain witnessed evidence.
|
|
|
|
### 1.3 Trust Levels
|
|
|
|
| Level | Name | Description | Use Case |
|
|
|-------|------|-------------|----------|
|
|
| 0 | `isolated` | No federation | Air-gapped deployments |
|
|
| 1 | `observe` | Read-only witness | Public audit |
|
|
| 2 | `verify` | Mutual verification | Partner organizations |
|
|
| 3 | `attest` | Cross-attestation | Compliance networks |
|
|
| 4 | `integrate` | Shared scrolls | Tight federation |
|
|
|
|
---
|
|
|
|
## 2. Federation Scroll
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| **Scroll Name** | `Federation` |
|
|
| **JSONL Path** | `receipts/federation/federation_events.jsonl` |
|
|
| **Root File** | `ROOT.federation.txt` |
|
|
| **Receipt Types** | `fed_trust_proposal`, `fed_trust_established`, `fed_trust_revoked`, `fed_witness_event`, `fed_cross_anchor`, `fed_schema_sync` |
|
|
|
|
---
|
|
|
|
## 3. Trust Establishment Protocol
|
|
|
|
### 3.1 Phase 1: Discovery
|
|
|
|
Meshes discover each other via:
|
|
- Manual configuration
|
|
- DNS-based discovery (`_vaultmesh._tcp.example.com`)
|
|
- DHT announcement (for public meshes)
|
|
|
|
**Discovery Record**:
|
|
```json
|
|
{
|
|
"mesh_id": "did:vm:mesh:vaultmesh-berlin",
|
|
"display_name": "VaultMesh Berlin Node",
|
|
"endpoints": {
|
|
"federation": "https://federation.vaultmesh-berlin.io",
|
|
"verification": "https://verify.vaultmesh-berlin.io"
|
|
},
|
|
"public_key": "ed25519:z6Mk...",
|
|
"scrolls_available": ["Drills", "Compliance", "Treasury"],
|
|
"trust_policy": {
|
|
"accepts_proposals": true,
|
|
"min_trust_level": 1,
|
|
"requires_mutual": true
|
|
},
|
|
"attestations": [
|
|
{
|
|
"attester": "did:vm:mesh:vaultmesh-dublin",
|
|
"attested_at": "2025-06-01T00:00:00Z",
|
|
"attestation_type": "identity_verified"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 3.2 Phase 2: Proposal
|
|
|
|
Mesh-A proposes federation to Mesh-B:
|
|
|
|
**Trust Proposal**:
|
|
```json
|
|
{
|
|
"proposal_id": "fed-proposal-2025-12-06-001",
|
|
"proposer": "did:vm:mesh:vaultmesh-dublin",
|
|
"target": "did:vm:mesh:vaultmesh-berlin",
|
|
"proposed_at": "2025-12-06T10:00:00Z",
|
|
"expires_at": "2025-12-13T10:00:00Z",
|
|
"proposed_trust_level": 2,
|
|
"proposed_terms": {
|
|
"scrolls_to_share": ["Compliance"],
|
|
"verification_frequency": "hourly",
|
|
"retention_period_days": 365,
|
|
"data_jurisdiction": "EU",
|
|
"audit_rights": true
|
|
},
|
|
"proposer_attestations": {
|
|
"identity_proof": "...",
|
|
"capability_proof": "...",
|
|
"compliance_credentials": ["ISO27001", "SOC2"]
|
|
},
|
|
"signature": {
|
|
"algorithm": "Ed25519",
|
|
"value": "z58D..."
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.3 Phase 3: Negotiation
|
|
|
|
Target mesh reviews and may counter-propose:
|
|
|
|
**Counter-Proposal**:
|
|
```json
|
|
{
|
|
"proposal_id": "fed-proposal-2025-12-06-001",
|
|
"response_type": "counter",
|
|
"responder": "did:vm:mesh:vaultmesh-berlin",
|
|
"responded_at": "2025-12-06T14:00:00Z",
|
|
"counter_terms": {
|
|
"scrolls_to_share": ["Compliance", "Drills"],
|
|
"verification_frequency": "daily",
|
|
"retention_period_days": 180,
|
|
"additional_requirement": "quarterly_audit_call"
|
|
},
|
|
"signature": "z47C..."
|
|
}
|
|
```
|
|
|
|
### 3.4 Phase 4: Establishment
|
|
|
|
Both parties sign the final agreement:
|
|
|
|
**Federation Agreement**:
|
|
```json
|
|
{
|
|
"agreement_id": "fed-agreement-2025-12-06-001",
|
|
"parties": [
|
|
"did:vm:mesh:vaultmesh-dublin",
|
|
"did:vm:mesh:vaultmesh-berlin"
|
|
],
|
|
"established_at": "2025-12-06T16:00:00Z",
|
|
"trust_level": 2,
|
|
"terms": {
|
|
"scrolls_shared": ["Compliance", "Drills"],
|
|
"verification_frequency": "daily",
|
|
"retention_period_days": 180,
|
|
"data_jurisdiction": "EU",
|
|
"audit_rights": true,
|
|
"dispute_resolution": "arbitration_zurich"
|
|
},
|
|
"key_exchange": {
|
|
"dublin_federation_key": "ed25519:z6MkDublin...",
|
|
"berlin_federation_key": "ed25519:z6MkBerlin..."
|
|
},
|
|
"signatures": {
|
|
"did:vm:mesh:vaultmesh-dublin": {
|
|
"signed_at": "2025-12-06T15:30:00Z",
|
|
"signature": "z58D..."
|
|
},
|
|
"did:vm:mesh:vaultmesh-berlin": {
|
|
"signed_at": "2025-12-06T16:00:00Z",
|
|
"signature": "z47C..."
|
|
}
|
|
},
|
|
"agreement_hash": "blake3:abc123..."
|
|
}
|
|
```
|
|
|
|
### 3.5 Phase 5: Activation
|
|
|
|
Both meshes:
|
|
1. Store the agreement in their Federation scroll
|
|
2. Exchange current Merkle roots
|
|
3. Begin scheduled verification cycles
|
|
4. Emit `fed_trust_established` receipt
|
|
|
|
---
|
|
|
|
## 4. Witness Protocol
|
|
|
|
### 4.1 Verification Cycle
|
|
|
|
```
|
|
┌─────────────┐ ┌─────────────┐
|
|
│ Mesh-A │ │ Mesh-B │
|
|
│ (Dublin) │ │ (Berlin) │
|
|
└──────┬──────┘ └──────┬──────┘
|
|
│ │
|
|
│ 1. Anchor cycle completes │
|
|
│ ROOT.compliance.txt updated │
|
|
│ │
|
|
│ 2. POST /federation/notify │
|
|
│────────────────────────────────►│
|
|
│ { │
|
|
│ scroll: "Compliance", │
|
|
│ root: "blake3:aaa...", │
|
|
│ anchor_proof: {...} │
|
|
│ } │
|
|
│ │
|
|
│ │ 3. Verify anchor proof
|
|
│ │ against known backends
|
|
│ │
|
|
│ │ 4. Optionally fetch
|
|
│ │ receipt samples
|
|
│ │
|
|
│ 5. POST /federation/witness │
|
|
│◄────────────────────────────────│
|
|
│ { │
|
|
│ witnessed_root: "blake3:aaa",│
|
|
│ witness_result: "verified", │
|
|
│ witness_signature: "z47C..." │
|
|
│ } │
|
|
│ │
|
|
│ 6. Store witness receipt │
|
|
│ │
|
|
└──────────────────────────────────┘
|
|
```
|
|
|
|
### 4.2 Witness Receipt
|
|
|
|
```json
|
|
{
|
|
"type": "fed_witness_event",
|
|
"witness_id": "witness-2025-12-06-001",
|
|
"witnessed_mesh": "did:vm:mesh:vaultmesh-dublin",
|
|
"witnessing_mesh": "did:vm:mesh:vaultmesh-berlin",
|
|
"timestamp": "2025-12-06T12:05:00Z",
|
|
"scroll": "Compliance",
|
|
"witnessed_root": "blake3:aaa111...",
|
|
"witnessed_anchor": {
|
|
"backend": "ethereum",
|
|
"tx_hash": "0x123...",
|
|
"block_number": 12345678
|
|
},
|
|
"verification_method": "anchor_proof_validation",
|
|
"verification_result": "verified",
|
|
"samples_checked": 5,
|
|
"discrepancies": [],
|
|
"witness_signature": "z47C...",
|
|
"tags": ["federation", "witness", "compliance", "verified"],
|
|
"root_hash": "blake3:bbb222..."
|
|
}
|
|
```
|
|
|
|
### 4.3 Cross-Anchor
|
|
|
|
At trust level 3+, meshes can include each other's roots in their anchor cycles:
|
|
|
|
**Cross-Anchor Receipt**:
|
|
```json
|
|
{
|
|
"type": "fed_cross_anchor",
|
|
"cross_anchor_id": "cross-anchor-2025-12-06-001",
|
|
"anchoring_mesh": "did:vm:mesh:vaultmesh-berlin",
|
|
"anchored_mesh": "did:vm:mesh:vaultmesh-dublin",
|
|
"timestamp": "2025-12-06T12:10:00Z",
|
|
"dublin_roots_included": {
|
|
"Compliance": "blake3:aaa111...",
|
|
"Drills": "blake3:bbb222..."
|
|
},
|
|
"combined_root": "blake3:ccc333...",
|
|
"anchor_proof": {
|
|
"backend": "bitcoin",
|
|
"tx_hash": "abc123...",
|
|
"merkle_path": [...]
|
|
},
|
|
"tags": ["federation", "cross-anchor", "bitcoin"],
|
|
"root_hash": "blake3:ddd444..."
|
|
}
|
|
```
|
|
|
|
This means Dublin's receipts are now anchored on **both** Dublin's chosen backend **and** Berlin's Bitcoin anchor — double civilizational durability.
|
|
|
|
---
|
|
|
|
## 5. Federation API
|
|
|
|
### 5.1 Endpoints
|
|
|
|
```yaml
|
|
# Federation API Specification
|
|
openapi: 3.0.0
|
|
info:
|
|
title: VaultMesh Federation API
|
|
version: 1.0.0
|
|
|
|
paths:
|
|
/federation/discovery:
|
|
get:
|
|
summary: Get mesh discovery record
|
|
responses:
|
|
200:
|
|
description: Discovery record
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DiscoveryRecord'
|
|
|
|
/federation/proposals:
|
|
post:
|
|
summary: Submit trust proposal
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TrustProposal'
|
|
responses:
|
|
202:
|
|
description: Proposal received
|
|
|
|
/federation/proposals/{id}:
|
|
get:
|
|
summary: Get proposal status
|
|
put:
|
|
summary: Respond to proposal (accept/reject/counter)
|
|
|
|
/federation/agreements:
|
|
get:
|
|
summary: List active federation agreements
|
|
|
|
/federation/agreements/{id}:
|
|
get:
|
|
summary: Get agreement details
|
|
delete:
|
|
summary: Revoke federation (with notice period)
|
|
|
|
/federation/notify:
|
|
post:
|
|
summary: Notify of new anchor (push)
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AnchorNotification'
|
|
|
|
/federation/witness:
|
|
post:
|
|
summary: Submit witness attestation
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WitnessAttestation'
|
|
|
|
/federation/roots:
|
|
get:
|
|
summary: Get current Merkle roots for all scrolls
|
|
parameters:
|
|
- name: scrolls
|
|
in: query
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
/federation/receipts/{scroll}:
|
|
get:
|
|
summary: Fetch receipt samples for verification
|
|
parameters:
|
|
- name: scroll
|
|
in: path
|
|
required: true
|
|
- name: from
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 100
|
|
|
|
/federation/verify:
|
|
post:
|
|
summary: Request verification of specific receipt
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
receipt_hash:
|
|
type: string
|
|
scroll:
|
|
type: string
|
|
```
|
|
|
|
### 5.2 Authentication
|
|
|
|
Federation API uses mutual TLS + signed requests:
|
|
|
|
```
|
|
POST /federation/notify HTTP/1.1
|
|
Host: federation.vaultmesh-berlin.io
|
|
Content-Type: application/json
|
|
X-Mesh-ID: did:vm:mesh:vaultmesh-dublin
|
|
X-Timestamp: 2025-12-06T12:00:00Z
|
|
X-Signature: z58D...
|
|
|
|
{
|
|
"scroll": "Compliance",
|
|
"root": "blake3:aaa111...",
|
|
...
|
|
}
|
|
```
|
|
|
|
Signature covers: `${method}|${path}|${timestamp}|${body_hash}`
|
|
|
|
---
|
|
|
|
## 6. Conflict Resolution
|
|
|
|
### 6.1 Discrepancy Types
|
|
|
|
| Type | Description | Severity |
|
|
|------|-------------|----------|
|
|
| `root_mismatch` | Claimed root doesn't match computed | Critical |
|
|
| `anchor_invalid` | Anchor proof fails verification | Critical |
|
|
| `timestamp_drift` | Timestamps outside tolerance (>5min) | Warning |
|
|
| `schema_incompatible` | Receipt schema version mismatch | Warning |
|
|
| `sample_missing` | Requested receipt not found | Info |
|
|
|
|
### 6.2 Discrepancy Protocol
|
|
|
|
```json
|
|
{
|
|
"type": "fed_discrepancy",
|
|
"discrepancy_id": "discrepancy-2025-12-06-001",
|
|
"reporting_mesh": "did:vm:mesh:vaultmesh-berlin",
|
|
"reported_mesh": "did:vm:mesh:vaultmesh-dublin",
|
|
"timestamp": "2025-12-06T12:15:00Z",
|
|
"discrepancy_type": "root_mismatch",
|
|
"severity": "critical",
|
|
"details": {
|
|
"scroll": "Compliance",
|
|
"claimed_root": "blake3:aaa111...",
|
|
"computed_root": "blake3:xxx999...",
|
|
"sample_receipts_checked": 50,
|
|
"first_divergence_at": "receipt-sequence-4721"
|
|
},
|
|
"evidence_hash": "blake3:evidence...",
|
|
"resolution_requested": true
|
|
}
|
|
```
|
|
|
|
### 6.3 Resolution Workflow
|
|
|
|
1. **Automatic**: Re-sync and recompute
|
|
2. **Manual**: Human review of divergence
|
|
3. **Arbitration**: Third-party mesh verification
|
|
4. **Escalation**: Federation suspension pending resolution
|
|
|
|
---
|
|
|
|
## 7. Schema Synchronization
|
|
|
|
Federated meshes must agree on receipt schemas:
|
|
|
|
**Schema Sync Receipt**:
|
|
```json
|
|
{
|
|
"type": "fed_schema_sync",
|
|
"sync_id": "schema-sync-2025-12-06-001",
|
|
"meshes": ["did:vm:mesh:vaultmesh-dublin", "did:vm:mesh:vaultmesh-berlin"],
|
|
"timestamp": "2025-12-06T10:00:00Z",
|
|
"schemas_synced": {
|
|
"Compliance": {
|
|
"version": "1.2.0",
|
|
"hash": "blake3:schema1..."
|
|
},
|
|
"Drills": {
|
|
"version": "1.1.0",
|
|
"hash": "blake3:schema2..."
|
|
}
|
|
},
|
|
"backward_compatible": true,
|
|
"migration_required": false,
|
|
"tags": ["federation", "schema", "sync"],
|
|
"root_hash": "blake3:eee555..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. CLI Commands
|
|
|
|
```bash
|
|
# Discovery
|
|
vm-federation discover --mesh vaultmesh-berlin.io
|
|
vm-federation list-known
|
|
|
|
# Proposals
|
|
vm-federation propose \
|
|
--target did:vm:mesh:vaultmesh-berlin \
|
|
--trust-level 2 \
|
|
--scrolls Compliance,Drills \
|
|
--terms federation-terms.json
|
|
|
|
vm-federation proposals list
|
|
vm-federation proposals show fed-proposal-2025-12-06-001
|
|
vm-federation proposals accept fed-proposal-2025-12-06-001
|
|
vm-federation proposals reject fed-proposal-2025-12-06-001 --reason "incompatible_jurisdiction"
|
|
vm-federation proposals counter fed-proposal-2025-12-06-001 --terms counter-terms.json
|
|
|
|
# Agreements
|
|
vm-federation agreements list
|
|
vm-federation agreements show fed-agreement-2025-12-06-001
|
|
vm-federation agreements revoke fed-agreement-2025-12-06-001 --notice-days 30
|
|
|
|
# Verification
|
|
vm-federation verify --mesh vaultmesh-berlin --scroll Compliance
|
|
vm-federation witness-history --mesh vaultmesh-berlin --last 30d
|
|
|
|
# Status
|
|
vm-federation status
|
|
vm-federation health --all-peers
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Design Gate Checklist
|
|
|
|
| Question | Federation Answer |
|
|
|----------|-------------------|
|
|
| Clear entrypoint? | ✅ CLI (`vm-federation`), Federation API |
|
|
| Contract produced? | ✅ `federation_agreement.json` |
|
|
| State object? | ✅ Agreement + witness state |
|
|
| Receipts emitted? | ✅ Six receipt types |
|
|
| Append-only JSONL? | ✅ `receipts/federation/federation_events.jsonl` |
|
|
| Merkle root? | ✅ `ROOT.federation.txt` |
|
|
| Guardian anchor path? | ✅ Federation root included in ProofChain |
|
|
| Query tool? | ✅ `vm-federation` CLI |
|