did:hive DID Method Specification

Status of This Document

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in RFC 2119.

Abstract

This document specifies the did:hive Decentralized Identifier (DID) method. The did:hive method defines a per-agent identity namespace for autonomous software agents operating within the Hive Civilization network — a regulated agent-to-agent commerce layer settled in USDC on Base (EVM chain ID 8453).

Each did:hive identifier resolves to a DID Document carrying dual verification methods: an Ed25519 key for classical cryptographic operations and an ML-DSA-65 key (NIST FIPS 204) for post-quantum resistance. Valid Hive receipts require both keys to co-sign, providing HNDL (harvest-now-decrypt-later) resistance without sacrificing classical compatibility.

The verifiable data registry is the Hive Civilization resolver service, which stores DID Documents derived from agent key material and exposes a JSON-based REST API for Create, Read, Update, and Deactivate operations.

1. Introduction

1.1 Motivation

Autonomous software agents are increasingly deployed in contexts that require verifiable, legally cognizable identities: procurement pipelines, automated market-making, multi-agent task delegation, and cross-organization data exchange. Classical authentication schemes based on OAuth tokens or API keys offer no cryptographic binding between an agent's on-chain settlement identity and its off-chain credential presentation.

The did:hive method addresses this gap by grounding agent identity in a public-key pair (Ed25519, with ML-DSA-65 extension) whose corresponding DID Document is resolvable by any party without a pre-existing relationship. DID Documents expose service endpoints for receipt issuance and verification, enabling counterparties to confirm that a payment receipt was produced by the agent identified by a given DID and settled on-chain at the declared treasury address.

The settlement layer is USDC on Base (chain ID 8453), operated through the Hive Civilization treasury contract at 0x15184Bf50B3d3F52b60434f8942b7D52F2eB436E. Receipts are dual-signed envelopes: an Ed25519 signature for immediate verifiability by any Ed25519 library, and an ML-DSA-65 signature for forward-security against cryptographically-relevant quantum adversaries.

1.2 Design Goals

1.3 Conformance

This specification conforms to W3C DID Core 1.0 and follows the normative guidance of W3C DID Resolution. DID Documents produced by this method are valid JSON-LD documents when processed with the https://www.w3.org/ns/did/v1 context.

2. Method Syntax

2.1 ABNF Grammar

A did:hive identifier conforms to the following ABNF grammar, which is a specialization of the DID Core syntax:

hive-did         = "did:hive:" network ":" agent-id
network          = "mainnet" / "testnet"
agent-id         = 44*44(base58btc-char)
base58btc-char   = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" /
                   "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "J" /
                   "K" / "L" / "M" / "N" / "P" / "Q" / "R" / "S" / "T" /
                   "U" / "V" / "W" / "X" / "Y" / "Z" /
                   "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" /
                   "j" / "k" / "m" / "n" / "o" / "p" / "q" / "r" / "s" /
                   "t" / "u" / "v" / "w" / "x" / "y" / "z"

The agent-id is exactly 44 characters of base58btc encoding (Bitcoin alphabet, no check digit) of the 32-byte Ed25519 public key used as the primary verification key.

2.2 Agent ID Derivation

Given an Ed25519 key pair (sk, pk) where pk is the 32-byte public key:

1. Encode pk as base58btc (Bitcoin alphabet) to produce agent-id.
2. The DID is did:hive:mainnet:<agent-id> (or testnet for testing).
3. The ML-DSA-65 public key is bound as a separate verification method in the DID Document under the assertionMethod and authentication relations; it does not alter the DID string itself.

The derivation is deterministic. Implementations must not include key material other than the 32-byte Ed25519 public key in the agent-id segment.

2.3 Network Identifiers

2.4 Examples

did:hive:mainnet:4zvQFDQyBxrqJpg2LH6JsLTqz9tJzM8uKsN1xP3RwYeh
did:hive:testnet:4zvQFDQyBxrqJpg2LH6JsLTqz9tJzM8uKsN1xP3RwYeh

3. CRUD Operations

All CRUD operations are performed over HTTPS against the Hive Civilization resolver service. The base URL for mainnet is https://hivemorph.onrender.com. All request and response bodies are JSON (Content-Type: application/json).

3.1 Create

Overview

Creating a did:hive DID Document consists of generating an Ed25519 key pair, optionally generating an ML-DSA-65 key pair, and submitting both public keys to the registration endpoint. Registration is idempotent.

Registration Endpoint

POST https://hivemorph.onrender.com/v1/did/register

Request Body

{
  "network": "mainnet",
  "ed25519_public_key_b58": "<base58btc-encoded 32-byte Ed25519 public key>",
  "mldsa65_public_key_b64": "<base64url-encoded ML-DSA-65 public key>",  // optional
  "metadata": {                                                              // optional
    "label": "<human-readable agent label, not exposed in DID Document>",
    "profile": "standard | swarm"
  }
}

Successful Response

{
  "did": "did:hive:mainnet:4zvQFDQyBxrqJpg2LH6JsLTqz9tJzM8uKsN1xP3RwYeh",
  "did_document": { /* full DID Document */ },
  "created": true
}

DID Document Structure (at creation)

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1",
    "https://w3id.org/security/suites/mldsa-2024/v1"
  ],
  "id": "did:hive:mainnet:4zvQFDQyBxrqJpg2LH6JsLTqz9tJzM8uKsN1xP3RwYeh",
  "verificationMethod": [
    {
      "id": "did:hive:mainnet:4zvQ...#ed25519-key-0",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:hive:mainnet:4zvQ...",
      "publicKeyMultibase": "z<base58btc-encoded Ed25519 public key>"
    },
    {
      "id": "did:hive:mainnet:4zvQ...#mldsa65-key-0",
      "type": "JsonWebKey2020",
      "controller": "did:hive:mainnet:4zvQ...",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "ML-DSA-65",
        "x": "<base64url-encoded ML-DSA-65 public key>"
      }
    }
  ],
  "authentication": [
    "did:hive:mainnet:4zvQ...#ed25519-key-0",
    "did:hive:mainnet:4zvQ...#mldsa65-key-0"
  ],
  "assertionMethod": [
    "did:hive:mainnet:4zvQ...#ed25519-key-0",
    "did:hive:mainnet:4zvQ...#mldsa65-key-0"
  ],
  "service": [
    {
      "id": "did:hive:mainnet:4zvQ...#receipt-issuer",
      "type": "HiveReceiptIssuer",
      "serviceEndpoint": "https://hivemorph.onrender.com/v1/receipt/issue"
    },
    {
      "id": "did:hive:mainnet:4zvQ...#receipt-verifier",
      "type": "HiveReceiptVerifier",
      "serviceEndpoint": "https://hivemorph.onrender.com/v1/receipt/verify"
    }
  ],
  "created": "2026-05-07T00:00:00Z",
  "updated": "2026-05-07T00:00:00Z",
  "versionId": 0
}

3.2 Read (Resolve)

Resolution Endpoint

GET https://hivemorph.onrender.com/v1/did/resolve/{did}

The colon characters in the DID string must be percent-encoded as %3A when included in the URL path.

Successful Response (HTTP 200)

{
  "did_document": { /* full DID Document */ },
  "did_document_metadata": {
    "created": "2026-05-07T00:00:00Z",
    "updated": "2026-05-07T00:00:00Z",
    "versionId": 0,
    "deactivated": false
  }
}

Error Responses

3.3 Update

POST https://hivemorph.onrender.com/v1/did/update

Update replaces or extends verification methods. Old keys are not discarded — they move to previousKeys in the DID Document metadata. The versionId is a monotonically increasing counter. A request bearing a mismatched versionId must be rejected with HTTP 409 (versionConflict).

{
  "did": "did:hive:mainnet:4zvQ...",
  "versionId": 0,
  "operations": [
    {
      "op": "addVerificationMethod",
      "verificationMethod": { /* new key object */ },
      "relationships": ["authentication", "assertionMethod"]
    },
    {
      "op": "removeVerificationMethod",
      "id": "did:hive:mainnet:4zvQ...#ed25519-key-0"
    }
  ],
  "proof": {
    "type": "Ed25519Signature2020",
    "proofPurpose": "authentication",
    "verificationMethod": "did:hive:mainnet:4zvQ...#ed25519-key-0",
    "created": "2026-05-07T00:00:00Z",
    "proofValue": "<base64url signature over canonical update payload>"
  }
}

3.4 Deactivate

POST https://hivemorph.onrender.com/v1/did/deactivate

Deactivation is permanent. The DID Document is retained for archival and historical receipt verification. The resolver returns HTTP 410 with deactivated: true in metadata for all subsequent Read requests.

{
  "did": "did:hive:mainnet:4zvQ...",
  "versionId": 1,
  "proof": {
    "type": "Ed25519Signature2020",
    "proofPurpose": "authentication",
    "verificationMethod": "did:hive:mainnet:4zvQ...#ed25519-key-0",
    "created": "2026-05-07T00:00:00Z",
    "proofValue": "<base64url signature over canonical deactivation payload>"
  }
}

4. Security Considerations

4.1 Post-Quantum Hybridization

The did:hive method mandates an ML-DSA-65 verification method (per NIST FIPS 204) alongside the Ed25519 verification method. Valid Hive receipts carry signatures from both keys. An adversary must break both Ed25519 (classical security under the discrete logarithm assumption in the Edwards25519 group) and ML-DSA-65 (secure under the hardness of Module Learning With Errors) to forge a receipt. Implementations must verify both signatures when processing receipts. A receipt bearing only one signature type is invalid.

4.2 HNDL (Harvest-Now-Decrypt-Later) Resistance

Hive receipts are public records settled on-chain. An adversary recording transaction data today could attempt to forge signatures in the future using a quantum computer. The ML-DSA-65 component provides forward-security: even if Ed25519 is broken in the future, the ML-DSA-65 signature remains intact.

4.3 Key Rotation

Agents should rotate Ed25519 keys no longer than 12 months and ML-DSA-65 keys no longer than 24 months. Old keys are retained in previousKeys. Verifiers must check previousKeys when verifying receipts issued under prior key versions and confirm the receipt timestamp falls within the key's active period.

4.4 Replay Protection

Update and Deactivate requests include the current versionId. The resolver rejects requests with a mismatched counter. Receipt payloads include issued_at, round_id, and tx_hash. Verifiers must reject receipts with a duplicate tx_hash or a round_id inconsistent with the declared sequence.

4.5 Resolver Integrity

Resolver responses should be fetched over TLS. Implementations requiring fully decentralized trust should verify the Ed25519 public key in the DID Document against the agent-id segment directly — this verification is deterministic and requires no network access.

4.6 Receipt Forgery Resistance

Because the agent-id is derived directly from the Ed25519 public key, any party can verify that the key in the DID Document corresponds to the claimed DID without trusting the resolver. Key substitution by an attacker would produce a DID that does not match the submitted key, making the substitution detectable.

5. Privacy Considerations

5.1 No PII in DID Documents

DID Documents contain no personally identifiable information. The optional metadata.label field accepted at registration is stored server-side and is never exposed in the DID Document.

5.2 Correlation Risk

An agent using the same did:hive identifier across multiple counterparties exposes a persistent correlation handle. Agents with strong privacy requirements should use ephemeral sub-DIDs — new key pairs generated for each distinct counterparty relationship — and rotate to fresh DIDs when the relationship terminates.

5.3 Pairwise-DID Pattern

Agents may implement the pairwise-DID pattern: a unique did:hive DID (and corresponding key pair) is created for each bilateral counterparty relationship. The did:hive resolver supports this natively since registration is idempotent and unlimited DIDs may be registered per operator.

5.4 On-Chain Transparency

Settlement transactions on Base 8453 are publicly visible. The association between a tx_hash in a receipt and a DID is explicit. Agents with privacy-sensitive commerce requirements should use the pairwise-DID pattern (§5.3) to reduce cross-counterparty linkability.

5.5 Resolver Access Logs

The resolver at hivemorph.onrender.com may log resolution requests. Hive Civilization, Inc. does not sell or share resolution logs with third parties. Operators with heightened privacy requirements may run a local caching resolver to reduce exposure to the hosted resolver.

6. Reference Implementation

6.1 Receipt Envelope Contract

The canonical receipt envelope shape, as defined in the Hive Embed Sprint Specification §1 (issuance endpoint, verification endpoint):

{
  "tx_hash":          "0x + 64 hex characters (Base transaction hash)",
  "agent_did":        "did:hive:mainnet:<agent-id>",
  "counterparty_did": "did:hive:mainnet:<counterparty-agent-id>",
  "profile":          "standard | swarm",
  "round_id":         0,
  "ed25519_sig":      "<base64url Ed25519 signature over canonical receipt payload>",
  "mldsa65_sig":      "<base64url ML-DSA-65 signature over canonical receipt payload>",
  "issued_at":        "ISO 8601 UTC timestamp",
  "endpoint":         "https://hivemorph.onrender.com/v1/receipt/issue"
}