lfg2025/archy

Files

Dorian 0f6df9a021 docs: did:dht integration architecture and DWN protocol schemas

- DHT-01: docs/did-dht-integration.md — did:dht spec analysis, DNS packet
  encoding, mainline crate, publication/resolution flows, security notes
- SCHEMA-01: docs/dwn-protocols.md — 4 DWN protocol definitions with JSON
  schemas: node-identity, file-catalog, federation, app-deploy

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-14 02:59:16 +00:00

9.7 KiB

Raw Blame History

Archipelago DWN Protocol Definitions

Overview

These protocol definitions specify the data schemas used when Archipelago nodes exchange data via Decentralized Web Nodes (DWN). By defining protocols in the standard DWN format, any DWN-compatible application can read and write Archipelago data.

Each protocol defines:

A unique URI identifier
Data types with JSON schemas
Structure rules (who can read/write what)

Protocol 1: Node Identity Announcements

URI: https://archipelago.dev/protocols/node-identity/v1

Nodes publish their identity information so federated peers can discover capabilities and status.

{
  "protocol": "https://archipelago.dev/protocols/node-identity/v1",
  "published": true,
  "types": {
    "announcement": {
      "schema": "https://archipelago.dev/schemas/node-announcement/v1",
      "dataFormats": ["application/json"]
    }
  },
  "structure": {
    "announcement": {
      "$actions": [
        { "who": "anyone", "can": ["read"] },
        { "who": "author", "of": "announcement", "can": ["write", "update", "delete"] }
      ]
    }
  }
}

Schema: node-announcement/v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["did", "version", "apps", "timestamp"],
  "properties": {
    "did": {
      "type": "string",
      "description": "Node's DID (did:key or did:dht)"
    },
    "version": {
      "type": "string",
      "description": "Archipelago version (semver)"
    },
    "apps": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of installed app IDs"
    },
    "capabilities": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Node capabilities (e.g., 'file-sharing', 'dwn-sync', 'tor')"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of announcement"
    }
  }
}

URI: https://archipelago.dev/protocols/file-catalog/v1

Nodes publish their shared file catalogs so peers can browse available content.

{
  "protocol": "https://archipelago.dev/protocols/file-catalog/v1",
  "published": true,
  "types": {
    "entry": {
      "schema": "https://archipelago.dev/schemas/file-entry/v1",
      "dataFormats": ["application/json"]
    }
  },
  "structure": {
    "entry": {
      "$actions": [
        { "who": "anyone", "can": ["read"] },
        { "who": "author", "of": "entry", "can": ["write", "update", "delete"] }
      ]
    }
  }
}

Schema: file-entry/v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "title", "access", "size_bytes", "created_at"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique file entry ID"
    },
    "title": {
      "type": "string",
      "description": "Display title"
    },
    "description": {
      "type": "string",
      "description": "Optional description"
    },
    "content_type": {
      "type": "string",
      "description": "MIME type (e.g., 'application/pdf')"
    },
    "size_bytes": {
      "type": "integer",
      "description": "File size in bytes"
    },
    "access": {
      "type": "string",
      "enum": ["free", "peers-only", "paid"],
      "description": "Access level"
    },
    "price_sats": {
      "type": "integer",
      "description": "Price in satoshis (for paid access)"
    },
    "hash": {
      "type": "string",
      "description": "SHA-256 hash of file content"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Content tags for filtering"
    }
  }
}

Protocol 3: Federation State

URI: https://archipelago.dev/protocols/federation/v1

Nodes publish their federation membership and peer trust status.

{
  "protocol": "https://archipelago.dev/protocols/federation/v1",
  "published": false,
  "types": {
    "membership": {
      "schema": "https://archipelago.dev/schemas/federation-membership/v1",
      "dataFormats": ["application/json"]
    },
    "peerStatus": {
      "schema": "https://archipelago.dev/schemas/peer-status/v1",
      "dataFormats": ["application/json"]
    }
  },
  "structure": {
    "membership": {
      "$actions": [
        { "who": "recipient", "of": "membership", "can": ["read"] },
        { "who": "author", "of": "membership", "can": ["write", "update", "delete"] }
      ]
    },
    "peerStatus": {
      "$actions": [
        { "who": "recipient", "of": "peerStatus", "can": ["read"] },
        { "who": "author", "of": "peerStatus", "can": ["write", "update"] }
      ]
    }
  }
}

Schema: federation-membership/v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["node_did", "trust_level", "joined_at"],
  "properties": {
    "node_did": {
      "type": "string",
      "description": "DID of the federated node"
    },
    "trust_level": {
      "type": "string",
      "enum": ["trusted", "verified", "untrusted"],
      "description": "Trust level assigned to this peer"
    },
    "joined_at": {
      "type": "string",
      "format": "date-time"
    },
    "last_seen": {
      "type": "string",
      "format": "date-time"
    },
    "apps": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Apps reported by this peer"
    },
    "credential_id": {
      "type": "string",
      "description": "VC ID proving federation relationship"
    }
  }
}

Schema: peer-status/v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["node_did", "online", "timestamp"],
  "properties": {
    "node_did": {
      "type": "string"
    },
    "online": {
      "type": "boolean"
    },
    "cpu_percent": {
      "type": "number"
    },
    "memory_used_mb": {
      "type": "integer"
    },
    "disk_used_percent": {
      "type": "number"
    },
    "container_count": {
      "type": "integer"
    },
    "uptime_seconds": {
      "type": "integer"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    }
  }
}

Protocol 4: App Deployment Requests

URI: https://archipelago.dev/protocols/app-deploy/v1

Enables trusted peers to request app installations on remote nodes.

{
  "protocol": "https://archipelago.dev/protocols/app-deploy/v1",
  "published": false,
  "types": {
    "request": {
      "schema": "https://archipelago.dev/schemas/deploy-request/v1",
      "dataFormats": ["application/json"]
    },
    "response": {
      "schema": "https://archipelago.dev/schemas/deploy-response/v1",
      "dataFormats": ["application/json"]
    }
  },
  "structure": {
    "request": {
      "$actions": [
        { "who": "recipient", "of": "request", "can": ["read"] },
        { "who": "author", "of": "request", "can": ["write"] }
      ],
      "response": {
        "$actions": [
          { "who": "author", "of": "request", "can": ["read"] },
          { "who": "recipient", "of": "request", "can": ["write"] }
        ]
      }
    }
  }
}

Schema: deploy-request/v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["app_id", "requester_did", "target_did", "action"],
  "properties": {
    "app_id": {
      "type": "string",
      "description": "Application identifier (e.g., 'bitcoin-knots')"
    },
    "requester_did": {
      "type": "string",
      "description": "DID of the requesting node"
    },
    "target_did": {
      "type": "string",
      "description": "DID of the target node"
    },
    "action": {
      "type": "string",
      "enum": ["install", "update", "uninstall"],
      "description": "Deployment action"
    },
    "image": {
      "type": "string",
      "description": "Docker/OCI image reference"
    },
    "version": {
      "type": "string",
      "description": "Requested version"
    },
    "reason": {
      "type": "string",
      "description": "Human-readable reason for request"
    },
    "requested_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

Schema: deploy-response/v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["request_id", "status"],
  "properties": {
    "request_id": {
      "type": "string",
      "description": "ID of the original request"
    },
    "status": {
      "type": "string",
      "enum": ["accepted", "rejected", "completed", "failed"],
      "description": "Response status"
    },
    "reason": {
      "type": "string",
      "description": "Reason for rejection or failure"
    },
    "completed_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

Registration

On backend startup, all 4 protocols should be auto-registered via dwn.register-protocol:

const ARCHIPELAGO_PROTOCOLS: &[&str] = &[
    "https://archipelago.dev/protocols/node-identity/v1",
    "https://archipelago.dev/protocols/file-catalog/v1",
    "https://archipelago.dev/protocols/federation/v1",
    "https://archipelago.dev/protocols/app-deploy/v1",
];

Interoperability

These protocols follow the DWN protocol definition format. Any application that implements DWN can:

Read node announcements to discover Archipelago nodes
Browse file catalogs to find shared content
Query federation state to understand network topology
Request app deployments through the standard DWN messaging interface

The published: true flag on protocols 1 and 2 means any DWN node can query for these records. Protocols 3 and 4 are published: false (private — only shared with authorized peers).

9.7 KiB Raw Blame History