vaultsovereign/vm-core

Fork 0

Files

Vault Sovereign 110d644e10 Initialize repository snapshot

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

16 KiB

Raw Permalink Blame History

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:

Verify the anchor independently
Record their verification as a receipt
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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

Store the agreement in their Federation scroll
Exchange current Merkle roots
Begin scheduled verification cycles
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

{
  "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:

{
  "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

# 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

{
  "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

Automatic: Re-sync and recompute
Manual: Human review of divergence
Arbitration: Third-party mesh verification
Escalation: Federation suspension pending resolution

7. Schema Synchronization

Federated meshes must agree on receipt schemas:

Schema Sync Receipt:

{
  "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

# 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

16 KiB Raw Permalink Blame History