.bit DID Method Specification

Status

⚠️ This document is a work in progress draft

Summary

.bit is a blockchain-based, open source, decentralized cross-chain account system that provides a worldwide unique naming system with a .bit suffix that can be used in different scenarios, such as cryptocurrency transfer, domain name resolution, identity authentication, etc.

This .bit DID method specification describes a new DID method and how to do CRUD operations on .bit DID documents.

This specification conforms to the requirements specified in the DIDs specification currently published by the W3C Credentials Community Group.

DID Method

The name string that shall identify this DID method is: bit.

A DID that uses this method MUST begin with the following prefix: did:bit. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is specified below.

DID Method-Specific Identifier

.bit DID Method-Specific Identifier have the following format:

DID Method-Specific Identifier := [:<network>]:<name>
network                        := mainnet | pudge | ...
name                           := <.bit-name>

If the network is omitted, the network defaults to mainnet, so a did:bit:example.bit is equivalent to did:bit:mainnet:example.bit. However, the canonical form is did:bit:mainnet:example.bit.

Examples

Example with full .bit DID format:

- did:bit:example.bit
- did:bit:my.example.bit
- did:bit:mainnet:my.example.bit
- ...

CRUD Operations

.bit names can have CUSTOM records. This specification defines CUSTOM record names that will have an impact on DID resolution of .bit DIDs.

The following named CUSTOM records are defined for now:

org_w3c_did_service

OPTIONAL. A set of services as per W3C DID Core specification. The service id property MAY be omitted. In that case the DID resolver will generate a canonical value for the specific service entry.

NOTE: the .bit Service will be automatically propagated as a service during DID resolution.
org_w3c_did_verificationMethod

OPTIONAL. A set of verification methods as per W3C DID Core specification. Verification method id property values MUST be relative DID URIs.

NOTE: the owner of the .bit name will be automatically propagated as a verification method during DID resolution.
org_w3c_did_verificationRelationship

OPTIONAL. A map of verification relationship as per W3C DID Core specification to a set of verification relationship identifiers (id property).

NOTE: the verification method that relates to the owner of the .bit name can be used for all verification relationships.

Create

See .bit doc or .bit official website on how to register .bit names.

Read

DID resolution will perform .bit resolution for a given .bit name. Additionally, the DID resolver will then retrieve the DID specific CUSTOM records for the .bit name and add default values for service endpoints and verification methods.

The default verification method will always include the owner of the .bit name as follows:

{
  "id": "<.bit-name>#<sha256-of-blockchainAccountId>",
  "type": "EcdsaSecp256k1RecoveryMethod2020",
  "controller": "<.bit-name>",
  "blockchainAccountId": "<algorithmIndex-payload>"
}

The id of the default verification method is the concatenation of the .bit DID followed by the # and the hex representation of sha256(blockchainAccountId). Additional verification methods that MAY be added MUST not use that verification method id and will be ignored in the DID Document.
.bit's blockchainAccountId consists of two parts: algorithmIndex and payload. Now .bit supports the following algorithms:

index	algorithm	curve	payload	Scenario
03	ECDSA	secp256k1	address	EVM compatible chain
04	ECDSA	secp256k1	hex format on address	TRON
05	ECDSA ( EIP712 )	secp256k1	address	EVM compatible chain
06	EdDSA	ed25519	publick key	Mixin
07	ECDSA	secp256k1	hex format on address	DOGE
08	ECDSA	secp256r1	hash(cid)+hash(pk)	WebAuthn

The default service will always include the .bit service as follows:

{
  "id":"<DID-.bit>#Web3PublicProfile-<sha256-of-blockchainAccountId>",
  "type": "Web3PublicProfile", 
  "serviceEndpoint": { 
    "profileService": ".bit",
    "name": "<.bit-name>",
    "network": "mainnet" 
  }
}

The id of the default service is the concatenation of the .bit DID followed by the #Web3PublicProfile- and the hex representation of sha256(blockchainAccountId). Additional services that MAY be added MUST not use that service id and will be ignored in the DID Document.

If the DID specific CUSTOM records are malformed, the entire CUSTOM record will be ignored in the DID resolution process.

Example (no CUSTOM records)

For did:bit:example.bit (with no CUSTOM records added), the DID Document would look as follows:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/ens/v1",
    "https://w3id.org/casa/profile-services/v1"
  ],
  "id": "did:bit:example.bit",
  "canonicalId": "did:bit:mainnet:example.bit",
  "verificationMethod": [{
    "id": "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b",
    "type": "EcdsaSecp256k1RecoveryMethod2020",
    "controller": "did:bit:mainnet:example.bit",
    "blockchainAccountId": "03ab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"
  }],
  "service": [{
    "id":"did:bit:mainnet:example.bit#Web3PublicProfile-85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b",
    "type": "Web3PublicProfile", 
    "serviceEndpoint": { 
      "profileService": ".bit",
      "name": "example.bit",
      "network": "mainnet" 
    }
  }],
  "authentication": [
    "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b"
  ],
  "assertionMethod": [
    "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b"
  ],
  "capabilityInvocation": [
    "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b"
  ],
  "capabilityDelegation": [
    "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b"
  ]
}

Example (with keyAgreement)

For did:bit:example.bit with DID specific CUSTOM records added, the DID Document would look as follows:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/ens/v1",
    "https://w3id.org/casa/profile-services/v1"
  ],
  "id": "did:bit:example.bit",
  "canonicalId": "did:bit:mainnet:example.bit",
  "verificationMethod": [{
      "id": "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b",
      "type": "EcdsaSecp256k1RecoveryMethod2020",
      "controller": "did:bit:mainnet:example.bit",
      "blockchainAccountId": "03ab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"
    },
    {
      "id": "did:bit:mainnet:example.bit#zC9ByQ8aJs8vrNXyDhPHHNNMSHPcaSgNpjjsBYpMMjsTdS",
      "type": "X25519KeyAgreementKey2019", 
      "controller": "did:bit:mainnet:example.bit",
      "publicKeyMultibase": "z9hFgmPVfmBZwRvFEyniQDBkz9LmV7gDEqytWyGZLmDXE" 
    }
  ],
  "service": [{
    "id":"did:bit:mainnet:example.bit#Web3PublicProfile-85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b",
    "type": "Web3PublicProfile", 
    "serviceEndpoint": { 
      "profileService": ".bit",
      "ensName": "example.bit",
      "network": "mainnet" 
    }
  }],
  "authentication": [
    "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b"
  ],
  "assertionMethod": [
    "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b"
  ],
  "capabilityInvocation": [
    "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b"
  ],
  "capabilityDelegation": [
    "did:bit:mainnet:example.bit#85c4952fd6252377167e5de56017724e2687fa153bbd4b53b10bb3cac482978b"
  ],
  "keyAgreement": [
    "did:bit:mainnet:example.bit#zC9ByQ8aJs8vrNXyDhPHHNNMSHPcaSgNpjjsBYpMMjsTdS"  
  ]
}

The following CUSTOM records have to be set:

org_w3c_did_verificationRelationship
org_w3c_did_verificationMethod

Update

See related documents on how to add/update CUSTOM records.

Delete

When an account expires and is not renewed for a long time, it will be reclaimed by the system. Once it is reclaimed, the DID information is essentially deleted and will remain deleted until a new user registers it. More details see related documents to know the lifecycle of a .bit name.

Privacy Considerations

The data of the .bit name will be referred to as "The Data" in the following text.

Keeping PII off-chain

Regardless of encryption, The Data should not include Personally Identifiable Information (PII). The Data should contain only did, public keys, and service endpoints.

Name Tracing

When any data (e.g. W3C Verifiable Credentials) is associated with .bit DIDs, sharing that data would also impose sharing the onchain data graph (e.g. transaction history, NFTs etc.) of the payload that owns the .bit name.

Disclosure

The Data and its historical data are stored in the blockchain. Users should understand that on-chain data is public and does not have limitations on its use or disclosure.

Security considerations

The .bit name's DID document contract is deployed on the Nervos BlockChain，all of the write operations MUST be signed by the private key which corresponds to the public key in the DID document.

Document was protected by blockchain ledger security mechanism, so replay, eavesdropping, denial of service, man-in-the-middle，message insertion，deletion，modification attack are impossible, which can only be modified by one of the controllers who has related private key. All of the fields already been defined in document, user can insert incorrect implementation into document.

We provide integrity protection and update authentication for all operations, which makes it impossible to insert, modify or delete message by attacker. Only controllers in document can modify document, which contain controller's public key.

Unsecure verifiable data registries

There are a number of risks associated to the use of any unsecure verifiable data registries:

Resolver's blockchain nodes falling behind mainnet height.
The Nervos network became unstable causing resolvers to end up collecting incorrect data.
When some operations is in progress, the owner of the .bit name has changed.

In such cases, the validity of transactions is not guaranteed, and denial-of-service attacks can take place, leading to dropped updates, or even the disappearance of the DIDs altogether.

To mitigate that risk, it is recommended to build a resolver and perform secondary verification after a short period of time (5 minutes).

References

https://www.w3.org/TR/did-core

janx/did-bit-spec