Design Goals

Syntax

did-yadacoin       = "did:yadacoin:" method-specific-id
method-specific-id = 66HEXDIG   ; 33-byte compressed secp256k1 public key, lowercase hex
HEXDIG             = DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
DIGIT              = %x30-39

The method-specific identifier is the 66-character lowercase hexadecimal encoding of a compressed secp256k1 public key (33 bytes: a one-byte prefix 02 or 03 followed by the 32-byte X coordinate).

Example DIDs

did:yadacoin:02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
did:yadacoin:03f1e2d3c4b5a6978869504132beef01234567890abcdef01234567890abcdef0102

Address Derivation

A P2PKH address is derived from a public key using the Bitcoin-compatible procedure:

address = Base58Check( 0x00 || RIPEMD160( SHA256( compressed_public_key_bytes ) ) )

This address form is used within the KEL as public_key_hash, prerotated_key_hash, twice_prerotated_key_hash, and prev_public_key_hash.

KEL Entry Fields

Key Event Types

Chain Integrity Rules

1. kel[n+1].prev_public_key_hash == kel[n].public_key_hash for all n ≥ 0.
2. kel[n+1].public_key corresponds to the key whose P2PKH address equals kel[n].prerotated_key_hash.
3. A key is revoked if its P2PKH address appears as any public_key_hash in the KEL.
4. The active key is the public_key of kel[-1] (the latest confirming entry).

Production Rules

A DID Document for did:yadacoin:<pubkey_hex> is produced as follows:

1. Resolve the KEL for <pubkey_hex> (see ).
2. Determine the active key:
   • If the KEL is empty: the DID is unresolvable; return error: "notFound".
   • If addr(<pubkey_hex>) appears as a public_key_hash in the KEL: the key is revoked — return a deactivated DID Document (see ).
   • Otherwise: <pubkey_hex> is the active key and the DID Document is constructed as below.

DID Document Example

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/secp256k1-2019/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:yadacoin:02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "verificationMethod": [
    {
      "id": "did:yadacoin:02a1b2c3...#key-1",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "controller": "did:yadacoin:02a1b2c3...",
      "publicKeyHex": "02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
    },
    {
      "id": "did:yadacoin:02a1b2c3...#jws-key-1",
      "type": "JsonWebKey2020",
      "controller": "did:yadacoin:02a1b2c3...",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "<base64url-encoded X coordinate>",
        "y": "<base64url-encoded Y coordinate>"
      }
    }
  ],
  "authentication": [
    "did:yadacoin:02a1b2c3...#key-1"
  ],
  "assertionMethod": [
    "did:yadacoin:02a1b2c3...#key-1"
  ],
  "keyAgreement": [],
  "yadacoinKel": {
    "depth": 3,
    "headTransactionId": "abcdef0123456789...",
    "prerotatedKeyHash": "1BpEi6DfDAUFd152iiBFiEkioYCf...",
    "twicePrerotatedKeyHash": "1AXm5SomeDifferentAddress..."
  }
}

The yadacoinKel Extension Property

The yadacoinKel property is a method-specific extension exposing the current KEL head state:

Resolvers that do not understand yadacoinKel MUST ignore it. This property is informational only and is derived from on-chain data.

Create

To create a did:yadacoin DID:

1. Generate a compressed secp256k1 key pair (K₀_private, K₀_public).
2. Pre-generate at least two additional key pairs (K₁, K₂) for pre-rotation.
3. Compute P2PKH addresses: addr₀ = addr(K₀), addr₁ = addr(K₁), addr₂ = addr(K₂).
4. Construct and broadcast an inception transaction (version-7) to the YadaCoin network:

   Field	Value
   public_key	K₀ (hex)
   public_key_hash	addr₀
   prerotated_key_hash	addr₁
   twice_prerotated_key_hash	addr₂
   prev_public_key_hash	""
   relationship	""
   outputs	Single output to addr₁

5. Once the inception transaction is confirmed on-chain, the DID did:yadacoin:<K₀_hex> is created and resolvable.

The inception transaction MUST have exactly one output (sent to prerotated_key_hash), MUST have relationship == "", and MUST have prev_public_key_hash == "".

Read (Resolve)

To resolve did:yadacoin:<pubkey_hex>, retrieve the KEL using one of the following options:

GET https://yadacoin.io/key-event-log?public_key=<pubkey_hex>

from yadacoin.core.keyeventlog import KeyEventLog

kel = await KeyEventLog.build_from_public_key(pubkey_hex)
# kel is an ordered list of KeyEvent objects

Update (Key Rotation)

To rotate the active key from Kₙ to Kₙ₊₁:

1. Pre-generate additional key pairs Kₙ₊₂, Kₙ₊₃ as needed.
2. Broadcast an unconfirmed rotation transaction (signed by Kₙ):

   Field	Value
   public_key	Kₙ (hex)
   public_key_hash	addr(Kₙ)
   prerotated_key_hash	addr(Kₙ₊₁)
   twice_prerotated_key_hash	addr(Kₙ₊₂)
   prev_public_key_hash	addr(Kₙ₋₁)
   relationship	Base64-encoded JSON scope document (optional)
   outputs	Sent to addr(Kₙ₊₁)

3. Broadcast a confirming rotation transaction (signed by Kₙ₊₁):

   Field	Value
   public_key	Kₙ₊₁ (hex)
   public_key_hash	addr(Kₙ₊₁)
   prerotated_key_hash	addr(Kₙ₊₂)
   twice_prerotated_key_hash	addr(Kₙ₊₃)
   prev_public_key_hash	addr(Kₙ)
   relationship	""
   outputs	Sent to addr(Kₙ₊₂)

After both transactions are accepted into the mempool (or confirmed on-chain), resolving did:yadacoin:<Kₙ₊₁_hex> returns the updated DID Document. The old DID did:yadacoin:<Kₙ_hex> resolves as revoked.

Mempool transactions are sufficient for resolution. Resolvers SHOULD check both mempool and confirmed chain entries to support agent credentials that have not yet been included in a block.

Deactivate

To deactivate a DID, the current key holder broadcasts a final rotation transaction that moves funds to a well-known burn address or a dedicated tombstone address with no corresponding private key. Once this transaction appears in the KEL the public_key_hash of the current key is present, causing all future resolutions to return a deactivated DID Document.

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:yadacoin:<pubkey_hex>",
  "deactivated": true,
  "verificationMethod": [],
  "authentication": [],
  "assertionMethod": []
}

If the private key is destroyed without a rotation, the DID becomes permanently unresolvable-as-active. This is equivalent to abandonment, not a formal deactivation.

Conforming Resolver

A conforming did:yadacoin resolver:

1. MUST implement the Read operation as specified in .
2. MUST return "error": "notFound" when the KEL is empty.
3. MUST return "deactivated": true when the resolved public key's address appears as a public_key_hash in the KEL.
4. MUST check both the confirmed blockchain and the mempool when building the KEL.
5. MUST apply the chain integrity rules in and discard invalid KEL entries.
6. MUST NOT require the yadacoinKel extension property to produce a valid DID Document.

Conforming DID Controller

A conforming did:yadacoin DID controller:

1. MUST use a compressed secp256k1 public key as the method-specific identifier.
2. MUST pre-generate at least two additional key pairs before broadcasting the inception transaction.
3. MUST NOT reuse a public key once its P2PKH address appears as a public_key_hash in the KEL.
4. SHOULD use low-S normalized ECDSA signatures in all transactions.