§ The DID DHT Method Specification Registry 1.0

Specification Status: Working Draft

Latest Draft: did-dht.com

Latest Registry: did-dht.com/registry

Draft Created: November 20, 2023

Latest Update: March 28, 2024

Editors:
Gabe Cohen
Daniel Buchner
Contributors:
Moe Jangda
Frank Hinek
Participate:
GitHub repo
File a bug
Commit history

§ Abstract

This document serves as an official registry for all known extensions to the DID DHT Method specification.

All are welcome to propose changes to this registry.

§ Extensions

§ Key Type Index

Corresponds to the mapping, for a DID Document’s DNS packet representation, of a cryptographic key type to its index value. For each key type a default algorithm is provided to be used with the key’s JWK [RFC7517] representation.

Index Key Type Default Algorithm
0 Ed25519 EdDSA Fully-Specified Algorithms for JOSE and COSE
1 secp256k1 ES256K [RFC8812]
2 secp256r1 / P-256 ES256 [RFC7518]
3 X25519 [RFC7748] ECDH-ES+A256KW [RFC7518]
NOTE

All keys are represented as JWKs [RFC7517] in their uncompressed form.

An example Verification Method record represented as a DNS TXT record is as follows:

Name Type TTL Rdata
_k0._did. TXT 7200 id=abcd;t=0;k=r96mnGNgWGOmjt6g_3_0nd4Kls5-kknrd4DdPW8qtfw

§ Indexed Types

Represents an optional extension to a DID Document’s DNS packet representation exposed as a type index.

NOTE

Type 0 is reserved for DIDs that do not wish to associate themselves with a specific type but wish to make themselves discoverable via a Gateway's API.

Type Name Schema Type Integer
Discoverable - 0
Organization https://schema.org/Organization 1
Government Organization https://schema.org/GovernmentOrganization 2
Corporation https://schema.org/Corporation 3
Local Business https://schema.org/LocalBusiness 4
Software Package https://schema.org/SoftwareSourceCode 5
Web App https://schema.org/WebApplication 6
Financial Institution https://schema.org/FinancialService 7

§ Additional Properties

DID Documents may contain additional properties not defined by the core data model. These properties MAY be registered in the [DID-SPEC-REGISTRIES], or in the following table. Independent of where the property is registered, a mapping MUST be provided between the property and its DNS packet representation.

To add additional properties and note their mappings, please open a pull request.

§ Service

These properties are for use on a service object, in the value of service.

Property Name Type DNS Packet Representation Example
sig String or array of strings enc=E where E is a string or array of strings id=s1;t=TestService;se=https://test-service.com/1;enc=1
enc String or array of strings sig=S where S is a string or array of strings id=s1;t=TestService;se=https://test-service.com/1;sig=2

§ Interoperable DID Methods

As an OPTIONAL extension, some existing DID methods can leverage did:dht to broaden their feature set. This registry serves to define such DID methods that are interoperable with did:dht. To enter into the registry each DID method MUST define sections on publishing and resolving interoperable DIDs.

§ did:key

DID DHT is interoperable with the DID Key method when using Ed25519 keys represented as JWKs [RFC7517].

§ Publishing

To publish a DID Key to the DHT, the process is as follows:

  1. Verify the did:key value begins with the prefix z6Mk.
  2. Decode the Ed25519 key in the did:key identifier, and re-encode it using z-base-32.
  3. Expand the did:key using the process outlined in the did:key spec, with options.publicKeyFormat set to JsonWebKey.
  4. Optionally, amend the DID Document with additional properties (Verification Methods, Services, etc.).
  5. Follow steps 3 onward as outlined in the create section of the spec, using the identifier from step 2.
TODO

Update this algorithm after the did:key spec is updated to support did:dht.

§ Resolving

To resolve a DID Key, the process is as follows:

  1. Verify the did:key value begins with the prefix z6Mk.
  2. Decode the Ed25519 key in the did:key identifier, and re-encode it using z-base-32.
  3. Follow the process outlined in the read section of the spec using the identifier from the prior step.
  4. If lookup fails, fallback to the guidance provided in the did:key spec.

§ did:jwk

DID DHT is interoperable with the DID JWK method when using JWKS [RFC7517] representing Ed25519 keys.

§ Publishing

To publish a DID JWK to the DHT, the process is as follows:

  1. Expand the did:jwk using the process outlined in the did:jwk spec.
  2. Verify that the JWK represents an Ed25519 key.
  3. Transform the Ed25519 key to its bytes representation and re-encode it using z-base-32.
  4. Optionally, amend the DID Document with additional properties (Verification Methods, Services, etc.).
  5. Follow steps 3 onward as outlined in the create section above, using the identifier from step 3.
§ Resolving
  1. Expand the did:jwk using the process outlined in the did:jwk spec.
  2. Verify that the JWK represents an Ed25519 key.
  3. Transform the Ed25519 key to its bytes representation and re-encode it using z-base-32.
  4. Follow the process outlined in the Read section above using the identifier from the prior step.
  5. If lookup fails, fallback to the guidance provided in the did:jwk spec.

§ Gateways

As an OPTIONAL feature of the DID DHT Method, Gateway operators have the opportunity to make their gateways discoverable. This serves as a registry for such gateways.

Gateways MUST specify the source of their HASH value and the mechanism by which their gateway(s) can be discovered.

§ Bitcoin Anchored Gateways

The Bitcoin network serves as a mechanism for discovering gateways. By scanning the Bitcoin blockchain, active gateways can be identified. To be considered an active gateway, you *MUST follow the steps outlined below. These steps ensure the maintenance of an active timelock, which serves as a proof-of-legitimacy for the gateway.

  1. Generate a relative timelock transaction for the Bitcoin blockchain with the following attributes:
    • Set the lock duration to 1000
    • Add locked value locked must be no less than the mean value of the upper quintile of UTXOs as of a block that is no more than 10 blocks earlier from the block the locking transaction is included in (this effectively provides a 10 block grace period for the transaction to make it into the chain).
    • Add an OP_RETURN string composed of the following comma-separated values:
      • The block number used to compute the mean value of the upper quintile of UTXOs.
      • The URI where your node can be addressed
  2. Include the timelock transaction within 10 blocks of the block number specified for the average UTXO value calculation.
  3. If this is a relocking transaction that refreshes an existing registration of a node:
    • The relocking transaction MUST spend the outputs of the lock it replaces.
    • If the operator wants to prevent other nodes and clients using the decentralized registry from dropping the Registered Gateway from their Registered Gateway list, the relocking transaction MUST be included in the blockchain within ten blocks of the previous lock’s expiration.
§ Hash

The hash source to be used is Bitcoin block hashes. It is RECOMMENDED to use the most recent block hash value.

§ Discovery

To discover Bitcoin Anchored Gateways one must follow the following steps:

  1. Starting at block height of 817714 traverse the chain, checking the value of the OP_RETURN field of transactions with at least 6 confirmations.
  2. Find transactions that match the form block number + uri, as per the steps outlined in the section above.

§ References

Timelock
Timelock. P. Todd. 01 October 2014. Bitcoin.
DID Key
The did:key Method v0.7. A DID Method for Static Cryptographic Keys. D. Longley, D. Zagidulin, M. Sporny. W3C CCG.
DID JWK
did:jwk. did:jwk is a deterministic transformation of a JWK into a DID Document. J. Miller.
Ed25519
Ed25519. D. J. Bernstein, N. Duif, T. Lange, P. Schwabe, B.-Y. Yang; 26 September 2011. ed25519.cr.yp.to.
z-base-32
z-base-32. Human-oriented base-32 encoding. Z. O’Whielacronx; November 2002.
Fully-Specified Algorithms for JOSE and COSE
Fully-Specified Algorithms for JOSE and COSE. M. Jones, O. Steele; 28 February 2024. Internet Engineering Task Force.

DID-SPEC-REGISTRIES
DID Specification Registries. Orie Steele; Manu Sporny; 2020-06-18. Status: NOTE.
RFC7517
JSON Web Key (JWK). M. Jones; 2015-05. Status: Proposed Standard.
RFC7518
JSON Web Algorithms (JWA). M. Jones; 2015-05. Status: Proposed Standard.
RFC7748
Elliptic Curves for Security. A. Langley; M. Hamburg; S. Turner; 2016-01. Status: Informational.
RFC8812
CBOR Object Signing and Encryption (COSE) and JSON Object Signing and Encryption (JOSE) Registrations for Web Authentication (WebAuthn) Algorithms. M. Jones; 2020-08. Status: Proposed Standard.

✕
Table of Contents ✕