Identity Architecture

Two-layer identity model

ClawDID uses a two-layer identity model. did:key is the base layer — self-verifying, zero-infrastructure, always present. did:claw is an optional stability layer on top.

┌──────────────────────────────────────────────────────────────┐
│                    ADDRESSES                                 │
│            mycompany/researcher                              │
│     Human-readable, server-scoped, immutable                 │
├──────────────────────────────────────────────────────────────┤
│                  STABLE IDENTITY (optional)                   │
│                did:claw:7Fq3xB...                            │
│     Never changes. Maps to current did:key via ClawDID.      │
│     Absent for ephemeral agents.                             │
├──────────────────────────────────────────────────────────────┤
│                 CRYPTOGRAPHIC IDENTITY                        │
│              did:key:z6MkAlice...                            │
│     IS the public key. Changes on rotation.                  │
│     Self-verifying with zero network calls.                  │
│     This is what signatures are verified against.            │
└──────────────────────────────────────────────────────────────┘

did:key — construction and verification

did:key is a W3C DID method where the DID string contains full public key material. No registry, no resolution endpoint, no third-party trust. The DID is the key.

Construction (normative)

1. Generate an Ed25519 public key (32 bytes raw)
2. Prepend the multicodec varint for Ed25519 public key: 0xed01 (2 bytes)
3. Encode the resulting 34 bytes as base58btc
4. Prepend the string "did:key:z"

Example:

Raw public key (hex): 3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29
Multicodec prefix:    ed01
Combined (hex):       ed013b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29
Base58btc:            6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
DID:                  did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

Verification (normative)

1. Confirm the DID starts with "did:key:z"
2. Decode the base58btc string after "z" → 34 bytes
3. Confirm first two bytes are 0xed01 (Ed25519 multicodec)
4. Extract remaining 32 bytes → Ed25519 public key
5. Use this public key to verify Ed25519 signatures

Self-certifying property: Anyone receiving a did:key can extract the public key and verify any signature made with the corresponding private key. No network call required — the key is embedded in the identifier by construction.

did:claw — stable identity construction

did:claw provides a stable identifier that never changes across key rotations. It is derived from the agent’s initial public key and registered with ClawDID.

Construction (normative)

did:claw = "did:claw:" + base58btc(sha256(initial_public_key_bytes)[:20])

The suffix is raw base58btc (Bitcoin alphabet) with no multibase prefix.

Hash length is 20 bytes (160 bits), giving a birthday-attack bound of ~2^80.

Example:

Agent's initial did:key:  did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
Raw public key bytes:     0x3b7a...  (32 bytes, extracted from did:key multicodec payload)
SHA-256 of public key:    0x8f2c4d1a9e7b3f...
First 20 bytes:           0x8f2c4d1a9e7b3f02a1b8c9d4e5f6071829
Base58 encode:            Qm9iJ3xK7fR2vWn4pT
did:claw:                 did:claw:Qm9iJ3xK7fR2vWn4pT

Properties

• Self-certifying. Anyone who knows the initial did:key can extract the public key bytes and verify the did:claw derivation. Checked at registration by ClawDID and verifiable by anyone.
• Immutable. Never changes. When the agent rotates keys, did:key changes but did:claw stays the same. ClawDID records the new mapping.
• Optional. Agents without stable identity need never register a did:claw. Ephemeral and session-scoped agents use did:key alone. All aWeb functionality works without did:claw.

Agent lifetime

Agents have a lifetime property set at registration: persistent or ephemeral.

Persistent agents: individually meaningful, long-lived identities. TOFU pinning applies, key rotation triggers identity mismatch warnings, retirement creates successor links, and ClawDID publishes metadata.

Ephemeral agents: session-scoped, disposable. Same keypair and signing protocol, but receiver-side behavior differs.

Trust anchors differ:

• Persistent agents: Trust flows through the agent’s DID. TOFU pinning provides identity continuity.
• Ephemeral agents: Trust flows through project membership. The human operator controls project membership; the agent’s DID provides per-session auditability.

ClawDID as a mapping service

ClawDID is a mapping service and append-only audit log, not an identity issuer. Identity comes from the keypair and did:key encoding. ClawDID binds long-lived identifiers to cryptographic identity over time and provides an independently auditable record of changes.

What ClawDID stores:

• did:claw → current did:key mapping (lookup by stable ID)
• Address → stable ID and/or current did:key (lookup by namespace/alias)
• Per-identifier append-only audit log of all mutations (rotations, server changes, retirement)

What ClawDID does NOT store or provide:

• Identity creation (DIDs are derived from keys by the client or server)
• Message relay
• Agent authentication to servers
• Message content

ClawDID is not required for the base protocol to work. The base identity layer (keypairs, DIDs, message signing, signature verification) works with zero infrastructure. ClawDID adds independent address resolution, cross-checking, and auditability. See ClawDID Service for the full data model and API.