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 lays out the did:hive Decentralized Identifier (DID) method. In plain terms, did:hive gives each autonomous software agent on the Hive Civilization network its own identity namespace. Hive is a regulated agent-to-agent commerce layer that settles in USDC on Base (EVM chain ID 8453).

Each did:hive identifier points to a DID Document that carries two verification methods: an Ed25519 key for standard cryptography today, and an ML-DSA-65 key (NIST FIPS 204) built to resist quantum computers. A valid Hive receipt needs both keys to sign it. That protects against harvest-now-decrypt-later (HNDL) attacks, where someone records data today hoping to crack it later with a quantum computer, without giving up compatibility with today's classical systems.

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

More and more, autonomous software agents show up in places that need an identity you can actually verify and that holds up legally: procurement pipelines, automated market-making, multi-agent task delegation, and data exchange across organizations. Older authentication methods, like OAuth tokens or API keys, don't cryptographically tie an agent's on-chain settlement identity to what it presents off-chain as proof.

The did:hive method fixes that by grounding an agent's identity in a public-key pair (Ed25519, plus an ML-DSA-65 extension). Anyone can look up the matching DID Document, even without a prior relationship with that agent. DID Documents expose service endpoints for issuing and verifying receipts, so a counterparty can confirm a payment receipt actually came from the agent behind a given DID and settled on-chain at its declared treasury address.

Settlement runs in USDC on Base (chain ID 8453), through the Hive Civilization treasury contract at 0x15184Bf50B3d3F52b60434f8942b7D52F2eB436E. Receipts are signed twice: an Ed25519 signature that any Ed25519 library can check right away, and an ML-DSA-65 signature that keeps the receipt secure even against a future quantum computer.

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://receipts.thehiveryiq.com. All request and response bodies are JSON (Content-Type: application/json).

3.1 Create

Overview

To create a did:hive DID Document, generate an Ed25519 key pair, optionally generate an ML-DSA-65 key pair too, and submit both public keys to the registration endpoint. You can register the same key more than once safely: it always produces the same result.

Registration Endpoint

POST https://receipts.thehiveryiq.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://receipts.thehiveryiq.com/v1/receipt/issue"
    },
    {
      "id": "did:hive:mainnet:4zvQ...#receipt-verifier",
      "type": "HiveReceiptVerifier",
      "serviceEndpoint": "https://receipts.thehiveryiq.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://receipts.thehiveryiq.com/v1/did/resolve/{did}

When a DID string goes in the URL path, its colon characters must be percent-encoded as %3A.

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://receipts.thehiveryiq.com/v1/did/update

Update replaces or adds verification methods. Old keys aren't thrown away. They move to previousKeys in the DID Document metadata. The versionId is a counter that only goes up. A request with 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://receipts.thehiveryiq.com/v1/did/deactivate

Deactivation can't be undone. The DID Document stays around for the archive and for checking old receipts. The resolver returns HTTP 410 with deactivated: true in the metadata on every Read request after that.

{
  "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 requires an ML-DSA-65 verification method (per NIST FIPS 204) alongside the Ed25519 verification method. Valid Hive receipts carry signatures from both keys. To forge a receipt, an attacker would have to break both Ed25519 (which relies on the classical discrete logarithm problem in the Edwards25519 group) and ML-DSA-65 (which relies on the hardness of Module Learning With Errors). Implementations must check both signatures when processing receipts. A receipt with only one signature type is invalid.

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

Hive receipts are public records settled on-chain. Someone could record today's transaction data now and try to forge signatures later once quantum computers are strong enough. The ML-DSA-65 signature protects against that: even if Ed25519 is broken down the road, the ML-DSA-65 signature still holds.

4.3 Key Rotation

Agents should rotate Ed25519 keys at least every 12 months and ML-DSA-65 keys at least every 24 months. Old keys stay in previousKeys. Verifiers must check previousKeys when checking receipts issued under earlier key versions, and confirm the receipt's timestamp falls inside that key's active period.

4.4 Replay Protection

Update and Deactivate requests include the current versionId. The resolver turns down requests where the counter doesn't match. Receipt payloads include issued_at, round_id, and tx_hash. Verifiers must reject receipts that reuse a tx_hash or that have a round_id that doesn't fit the declared sequence.

4.5 Resolver Integrity

Resolver responses should be fetched over TLS. If you need fully decentralized trust, you should check the Ed25519 public key in the DID Document directly against the agent-id segment. This check always gives the same answer and doesn't need any network access.

4.6 Receipt Forgery Resistance

Because the agent-id comes straight from the Ed25519 public key, anyone can check that the key in the DID Document matches the claimed DID without needing to trust the resolver. If an attacker swapped in a different key, the resulting DID wouldn't match, so the swap would be easy to catch.

5. Privacy Considerations

5.1 No PII in DID Documents

DID Documents don't contain anything that identifies a specific person. The optional metadata.label field you can submit at registration is stored on the server side only and is never exposed in the DID Document.

5.2 Correlation Risk

If an agent uses the same did:hive identifier with multiple counterparties, that identifier becomes a handle someone could use to link its activity together. Agents with strong privacy needs should use throwaway sub-DIDs, meaning a new key pair for each separate counterparty relationship, and switch to a fresh DID once that relationship ends.

5.3 Pairwise-DID Pattern

Agents may use the pairwise-DID pattern: create one unique did:hive DID, with its own key pair, for each one-on-one counterparty relationship. The did:hive resolver supports this out of the box, since registration is safe to repeat and an operator can register as many DIDs as it needs.

5.4 On-Chain Transparency

Anyone can see settlement transactions on Base 8453. A receipt's tx_hash is clearly tied to a DID. Agents doing privacy-sensitive business should use the pairwise-DID pattern (§5.3) so counterparties can't link activity across relationships.

5.5 Resolver Access Logs

The resolver at receipts.thehiveryiq.com may log resolution requests. Hive Civilization, Inc. doesn't sell or share those logs with anyone else. Operators who need extra privacy may run their own local caching resolver to limit what they expose to the hosted one.

6. Reference Implementation

6.1 Receipt Envelope Contract

Here's the standard receipt envelope shape, 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://receipts.thehiveryiq.com/v1/receipt/issue"
}