Federation Protocol

XMDB Federation enables multi-agent belief sharing with cryptographic provenance. Share events and beliefs between agents while maintaining full audit trails and trust controls.

Overview

Federation solves a critical problem: how do autonomous agents share knowledge without losing provenance? When Agent A shares a belief with Agent B, how does Agent B know:

The belief is authentic (Agent A really created it)
The reasoning chain is complete (all supporting events exist)
The belief hasn't been tampered with (cryptographic integrity)
Whether to trust it (policy-based acceptance)

XMDB Federation provides all of this through:

Merkle proofs for every shared event
Trust policies that control what you accept
Federation receipts that audit every trust decision
Foreign origin tracking for shared beliefs

Core Concepts

A share is a package of events or beliefs sent from one agent to another. Each share includes:

bash

{
  "share_id": "share_abc123",
  "sender_id": "agent_alice",
  "recipient_id": "agent_bob",
  "payload": {
    "beliefs": ["bel_xxx", "bel_yyy"],
    "events": ["evt_aaa", "evt_bbb"]
  },
  "proofs": {
    "bel_xxx": { "root": "0x...", "path": [...], "leaf": "0x..." },
    "bel_yyy": { "root": "0x...", "path": [...], "leaf": "0x..." }
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "signature": "0x..."
}

Every shared item includes a Merkle inclusion proof, allowing the recipient to verify it was part of the sender's authenticated event chain.

Trust Policies

Trust policies define rules for accepting or rejecting incoming shares. Policies can match on:

Peer identity - Which agents to trust
Content type - What kinds of beliefs to accept
Confidence threshold - Minimum confidence level
Anchoring requirement - Whether external timestamps are required
Scope restrictions - Which scopes can receive shares

bash

{
  "policy_id": "pol_prod_agents",
  "name": "Production Agents",
  "rules": [
    {
      "match": { "peer_pattern": "agent_prod_*" },
      "action": "accept",
      "require_anchored": true,
      "min_confidence": 0.8
    },
    {
      "match": { "peer_pattern": "*" },
      "action": "review"
    }
  ]
}

Federation Receipts

Every trust decision generates a receipt for audit purposes:

bash

{
  "receipt_id": "frc_xyz789",
  "share_id": "share_abc123",
  "decision": "accepted",
  "policy_id": "pol_prod_agents",
  "rule_matched": 0,
  "timestamp": "2025-01-15T10:30:05Z",
  "verification": {
    "proofs_valid": true,
    "signature_valid": true,
    "anchored": true
  }
}

Receipts provide a complete audit trail of what was shared, what was accepted or rejected, and why.

Foreign Origin Tracking

When you accept a shared belief, XMDB tracks its foreign origin:

bash

{
  "belief_id": "bel_local_123",
  "conclusion": "User prefers dark mode",
  "foreign_origin": {
    "original_id": "bel_xxx",
    "source_agent": "agent_alice",
    "share_id": "share_abc123",
    "received_at": "2025-01-15T10:30:05Z"
  }
}

This ensures you always know where a belief came from, even after it's been integrated into your local event chain.

API Reference

Share Events

Send events or beliefs to another agent.

bash

POST /v1/federation/share

bash

{
  "recipient_id": "agent_bob",
  "beliefs": ["bel_xxx", "bel_yyy"],
  "events": ["evt_aaa"]
}

Response includes the share ID and generated proofs:

bash

{
  "share_id": "share_abc123",
  "proofs_generated": 3,
  "signature": "0x..."
}

Receive Shares

List and process incoming shares.

bash

GET /v1/federation/inbox

bash

{
  "shares": [
    {
      "share_id": "share_abc123",
      "sender_id": "agent_alice",
      "status": "pending",
      "payload_summary": {
        "belief_count": 2,
        "event_count": 1
      },
      "received_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Accept or reject a share:

bash

POST /v1/federation/inbox/{share_id}/accept
POST /v1/federation/inbox/{share_id}/reject

List Receipts

Query federation receipts for audit.

bash

GET /v1/federation/receipts

Query parameters:

| Parameter | Description | |-----------|-------------| | peer_id | Filter by sender agent | | decision | Filter by decision (accepted, rejected, review) | | since | Filter by timestamp | | limit | Maximum results |

Manage Trust Policies

bash

# List policies
GET /v1/federation/policies

# Create policy
POST /v1/federation/policies

# Update policy
PUT /v1/federation/policies/{policy_id}

# Delete policy
DELETE /v1/federation/policies/{policy_id}

CLI Commands

Sharing

bash

# Share a belief with another agent
xmdbctl federation share --workspace prod --scope project \
  --peer-id agent_bob \
  --belief-id bel_xxx

# Share multiple items
xmdbctl federation share --workspace prod --scope project \
  --peer-id agent_bob \
  --belief-id bel_xxx,bel_yyy \
  --event-id evt_aaa

Receiving

bash

# List pending shares
xmdbctl federation receive --workspace prod --scope project --list

# Accept a share
xmdbctl federation receive --workspace prod --scope project \
  --share-id share_abc123 --accept

# Reject a share
xmdbctl federation receive --workspace prod --scope project \
  --share-id share_abc123 --reject --reason "Untrusted source"

# Auto-process with policies
xmdbctl federation receive --workspace prod --scope project --auto

Trust Policies

bash

# Create a policy
xmdbctl trust policy create --workspace prod --scope project \
  --name "trusted-agents" \
  --peer-pattern "agent_prod_*" \
  --action accept \
  --require-anchored true \
  --min-confidence 0.8

# List policies
xmdbctl trust policy list --workspace prod --scope project

# Update a policy
xmdbctl trust policy update --workspace prod --scope project \
  --policy-id pol_xxx \
  --action review

# Delete a policy
xmdbctl trust policy delete --workspace prod --scope project \
  --policy-id pol_xxx

Receipts

bash

# List all receipts
xmdbctl federation receipts --workspace prod --scope project

# Filter by peer
xmdbctl federation receipts --workspace prod --scope project \
  --peer-id agent_alice

# Filter by decision
xmdbctl federation receipts --workspace prod --scope project \
  --decision rejected

Verification

Verifying Shared Proofs

When you receive a share, XMDB automatically verifies:

Signature validity - The share was signed by the claimed sender
Merkle proof validity - Each item's proof verifies against the claimed root
Chain continuity - The root matches a known checkpoint from the sender

You can also verify manually:

bash

# Verify a share's proofs
xmdbctl federation verify --share-id share_abc123

# Verify a specific proof
xmdbctl checkpoints verify --local \
  --root 0x... \
  --leaf 0x... \
  --path '[...]'

Anchored Shares

For maximum trust, require shares to be anchored with RFC 3161 timestamps:

bash

{
  "rules": [
    {
      "match": { "peer_pattern": "*" },
      "action": "accept",
      "require_anchored": true
    }
  ]
}

This ensures shared beliefs have third-party timestamp attestation, proving they existed at the claimed time.

Best Practices

Policy Design

Start restrictive - Default to review action, explicitly allow trusted peers
Require anchoring for production - External timestamps prevent backdating
Set confidence thresholds - Don't accept low-confidence beliefs automatically
Audit regularly - Review federation receipts for unexpected patterns

Security Considerations

Verify peer identity - Ensure you're sharing with the intended agent
Monitor receipt patterns - Watch for unusual share volumes or rejections
Rotate trust policies - Update policies as your agent network evolves
Keep receipts - Federation receipts are your audit trail for compliance

Performance

Batch shares - Share multiple beliefs in a single request when possible
Use policy auto-processing - Let policies handle routine accepts/rejects
Index by foreign origin - Query beliefs by their original source when needed

Next Steps

Beliefs - Understand belief tracking
Merkle Proofs - Learn about cryptographic proofs
External Anchoring - Third-party timestamp attestation
Security - Trust policies and access control

Documentation

Federation Protocol

Overview

Core Concepts

Shares

Trust Policies

Federation Receipts

Foreign Origin Tracking

API Reference

Share Events

Receive Shares

List Receipts

Manage Trust Policies

CLI Commands

Sharing

Receiving

Trust Policies

Receipts

Verification

Verifying Shared Proofs

Anchored Shares

Best Practices

Policy Design

Security Considerations

Performance

Next Steps

Ready to add durable memory?