About

The BNB DID method specification conforms to the requirements specified in the DID specification currently published by the W3C Credentials Community Group. For more information about DIDs and DID method specifications, please see the DID Primer and DID Spec.

BNB Smart Chain is a high-speed, low-fee public ledger based on a combination of Proof of Authority (PoA) and delegated Proof of Stake (dPoS). The BNB DID method is a method for storing DIDs and managing DID documents on BNB Smart Chain, built and maintained by Identity.com in conjunction with BNB Smart Chain.

 

BNB DID Method

The namestring that shall identify this DID method is: bnb

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

Target System(s)

This DID method applies to the BNB Smart Chain mainnet network as well as the testnet and devnet clusters.

Namespace Specific Identifier (NSI)

The BNB DID scheme is defined by the following ABNF:

bnb-did = "did:bnb" *(":" network) ":" idstring
idstring = "0x" 40*HEXDIG
network = "testnet" / "devnet" / "localnet"

All BNB DID identifier elements are hex encoded using the 20-byte key of an ethereum address. Ideally, the given address is a checksum-address where uppercase and lowercase lettered are mixed. However, a unique did:bnb identifier is ALWAYS represented by checksum-address and therefore a checksum and a lower-case representation of a did:bnb DO represent the same identifier.

Optionally, a network may be specified to indicate which BNB Smart Chain cluster contains the DID document.

Identifier Generation Method

The 20-byte address underlying a BNB DID is generated from the following deterministic algorithm.

  1. Generate a Secp256k1 Keypair
  2. Hash the public key using the Keccak-256 algorithm
  3. Take the last 20 bytes of the hash
  4. Encode the 20 bytes as a hex string
  5. Apply ERC-55 checksum encoding

The program ID is TBD on all networks.

A convenient regex to match BNB DID identifiers is:

^[1-9A-HJ-NP-Za-km-z]{40,48}$

A convenient regex to match the entire DID string is:

^did\:bnb(\:(testnet|devnet|localnet))?\:0x[a-fA-F0-9]{40}$

Examples

Valid BNB DIDs might be:

Operations

The following section outlines the DID operations for the did:bnb method.

Create (Register)

A BNB DID can be created by combining the did:bnb(:network) prefix with the AUTHORITY. An initial 'sparse' DID document can be generated without the need to register it on the BNB Smart Chain blockchain: 

{
    "@context": [
        "https://w3id.org/did/v1.0",
        "https://w3id.org/bnb/v1"
    ],
    "id": "did:bnb:IDENTIFIER",
    "verificationMethod": [
        {
            "id": "did:bnb:IDENTIFIER#key1",
            "type": "Ed25519VerificationKey2018",
            "controller": "did:bnb:IDENTIFIER",
            "blockchainAccountId": "IDENTIFIER"
        }
    ],
    "authentication": [
        "did:bnb:IDENTIFIER#key1"
    ],
    "assertionMethod": [],
    "keyAgreement": [],
    "capabilityInvocation": [
        "did:bnb:IDENTIFIER#key1"
    ],
    "capabilityDelegation": [],
    "service": [],
}

where: IDENTIFIER is the DID method identifier derived from the authority.

Changing the default data of a BNB DID involves submitting a transaction to the BNB Smart Chain blockchain calling the "Initialize" instruction on the BNB Smart Contract. The only required input to this program is the address of the 'authority', that is, the initial owner of the DID. The transaction must be signed by the address owner.

The authority is a special key from which the DID is derived. It is always present in the verification methods list, and by default is added as the only key in the capabilityInvocations list, indicating that it is permitted to change the DID Document contents. It can, however be removed from the list by submitting an update instruction where the capabilityInvocation list is explicitly set (e.g. to the empty list or some other list of keys).

An optional additional field may be added, containing additional document data, such as service endpoints or additional keys.

Fees

Updating a BNB DID on BNB Smart Chain incurs fees, imposed by the BNB Smart Chain blockchain and paid in the chain's native token, BNB.

By default, the fee payer is the owner of the DID that will be created. However, the implementation supports a separate fee payer, that will incur the charges of registration/updating/deletion of the DID without having any permissions on the DID itself. This allows a central body to generate DIDs for its customers, without requiring them to have a BNB balance.

Read (Resolve)

A BNB DID record can be looked up on BNB Smart Chain, by stripping the did:bnb: prefix from the DID, and network identifier if present, and looking up the resultant account on-chain. If no data is present on-chain, the generated DID document (see above) should be returned.

Anyone can query a DID record, by sending the above request. The response contains the DID document, encoded in a binary form defined by the Borsh serialization library. A client library is required to convert it to a DID Document. The schema for this format is defined in the reference implementation client.

Update (Replace)

The DID can be updated by invoking the matching Smart Contract function on the BNB Smart Chain blockchain. This transaction must be signed by a key that is referenced in the capabilityInvocation property.

Each value is expected to be calculated by a client library, rather than calculated manually (see the reference implementation for details).

For example, adding the following DID sub-document: 

{
    "service": [
        {
            "id": "did:bnb:IDENTIFIER#agent",
            "type": "AgentService",
            "serviceEndpoint": "https://hub.myhub.com/did:bnb:IDENTIFIER/agent"
        }, {
            "id": "did:bnb:ygGfLvAyuRymPNv2fJDK1ZMpdy59m8cV5dak6A8uHKa#messages",
            "type": "MessagingService",
            "serviceEndpoint": "https://hub.myhub.com/did:bnb:IDENTIFIER/messages"
        }
    ]
}
to the above document, results in: 
{
    "@context": [
        "https://w3id.org/did/v1.0",
        "https://w3id.org/bnb/v1"
    ],
    "id": "did:bnb:IDENTIFIER",
    "verificationMethod": [
        {
            "id": "did:bnb:IDENTIFIER#key1",
            "type": "Ed25519VerificationKey2018",
            "controller": "did:bnb:IDENTIFIER",
            "publicKeyBase58": "AUTHORITY"
        }
    ],
    "authentication": [
        "did:bnb:IDENTIFIER#key1"
    ],
    "assertionMethod": [],
    "keyAgreement": [],
    "capabilityInvocation": [
        "did:bnb:IDENTIFIER#key1"
    ],
    "capabilityDelegation": [],
    "service": [
        {
            "id": "did:bnb:IDENTIFIER#agent",
            "type": "AgentService",
            "serviceEndpoint": "https://hub.myhub.com/did:bnb:IDENTIFIER/agent"
        }, {
            "id": "did:bnb:ygGfLvAyuRymPNv2fJDK1ZMpdy59m8cV5dak6A8uHKa#messages",
            "type": "MessagingService",
            "serviceEndpoint": "https://hub.myhub.com/did:bnb:IDENTIFIER/messages"
        }
    ],
    "publicKey": [
        {
            "id": "did:bnb:IDENTIFIER#key1",
            "type": "Ed25519VerificationKey2018",
            "controller": "did:bnb:IDENTIFIER",
            "publicKeyBase58": "AUTHORITY"
        }
    ]
}
Only an AUTHORITY key can make this change, as that is the only one referenced inside capabilityInvocation.
An update can add an entry to or remove an entry from the capabilityInvocation list.
As with creation, an update transaction can specify a separate fee payer account to pay the transaction fee.

Delete (Revoke)

A BNB DID can be irreversibly deleted or revoked.

To revoke the document of the DID, the owner of the DID should send a transaction with a CloseAccount instruction.

When a BNB DID has been deleted, the DID document will resolve to the generated version.

Security Considerations

Recovery From Key Compromise

It is recommended, although not enforced by did:bnb, that more than one key be included in the capabilityInvocation list. This allows a second trusted key to remove the reference to the first in the event of a key compromise. It is also recommended to include additional verification methods and keys that have permissions to perform actions with the DID (such as sign messages), but do not have permissions to update the document itself. This allows the capabilityInvocation keys to be stored in cold-storage, and only used when a key needs to be revoked. This protects against malicious rewriting of the document to add attackers' keys.

Privacy Considerations

DIDs should be assumed to be pseudonymous. Since the DID is registered on a decentralized ledger, it is not fully revocable, and this risk should be recognised by users of the DID method. As with all public pseudonymous persistent identifiers, there exists a risk of correlation when associating any other information with the DID in a way that exposes this information publicly.

Reference Implementations

It is expected that integrators of the BNB DID method do not interact with the BNB Smart Chain directly, but use a client library. A reference implementation, written in Typescript, is available at https://github.com/identity-com/did-bnb and as an NPM library (TBD)