# 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 |