9afe93a5b4
- 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>
401 lines
9.7 KiB
Markdown
401 lines
9.7 KiB
Markdown
# 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.
|
|
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
```json
|
|
{
|
|
"$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"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Protocol 2: File Sharing Catalog
|
|
|
|
**URI**: `https://archipelago.dev/protocols/file-catalog/v1`
|
|
|
|
Nodes publish their shared file catalogs so peers can browse available content.
|
|
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
```json
|
|
{
|
|
"$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.
|
|
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
```json
|
|
{
|
|
"$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`
|
|
|
|
```json
|
|
{
|
|
"$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.
|
|
|
|
```json
|
|
{
|
|
"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`
|
|
|
|
```json
|
|
{
|
|
"$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`
|
|
|
|
```json
|
|
{
|
|
"$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`:
|
|
|
|
```rust
|
|
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:
|
|
|
|
1. **Read** node announcements to discover Archipelago nodes
|
|
2. **Browse** file catalogs to find shared content
|
|
3. **Query** federation state to understand network topology
|
|
4. **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).
|