Draft Community Group Report,

Issue Tracking:
Inline In Spec
Christopher Allen
Kim Hamilton Duffy (Learning Machine)
Ryan Grant
Dan Pape


The Bitcoin Reference 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.

1. Introduction

The Bitcoin Reference DID method (did:btcr) supports DIDs on the public Bitcoin blockchain. The Bitcoin Reference method has minimal design goals: a DID trust anchor based on the Bitcoin blockchain, updates publicly visible and auditable via Bitcoin transactions, and optionally, additional DID Document information referenced in the transaction OP_RETURN data field. No other Personal Identifiable Information (PII) would be placed on the immutable blockchain.

A secondary intent of the BTCR method is to serve as a very conservative, very secure example and some best practices for creating a DID method. The use cases for BTCR are focused on anonymous and pseudo-anonymous identities, web-of-trust style webs of identity, and absolute mimimal personal information disclosure. Other DID methods will likely need to loosen these standards.

Some aspects of the BTCR method will not be practical if inappropriately scaled — for instance, there is a transaction cost to update keys and DDO object, potential UTXO inflation (i.e. one additional unspent output for every BTCR-based identity), and even if segwit isn’t used it could cause blockchain bloat. However, identities using the BTCR method can be a strong as Bitcoin itself -- currently securing billions of dollars of digital value.

2. Terminology

block: A data structure that contains one or more ledger events.

blockchain: A ledger containing a series of blocks where the ordering of the blocks can be mathematically proven to be correct.

consensus algorithm: An algorithm that enables multiple nodes in a network to make a decision in a deterministic fashion.

continuation DID document: A continuation DID document is a partial document external to the Bitcoin transaction providing additional DID document keys, ...

cryptographic ledger: A method of recording changes in a state machine where the accuracy of the ledger can be mathematically proven to be correct.

DID: a distributed identitfier.

decentralized system: A system in which lower level components operate on local information to accomplish global goals. For example, an ant colony is a decentralized system as there is no central control determining when food must be collected or how new tunnels should be excavated.

decentralized ledger: A cryptographic ledger that uses a consensus algorithm that enables a network of ledger nodes to come to consensus in a decentralized yet deterministic fashion.

3. Basic Concepts

3.1. Txref and Txref-ext

Txref encoded transaction ids are detailed BIP-0136, Bech32 Encoded Transaction Position References. A txref encodes the chain, blockheight, and transaction index where the transaction is located.

EXAMPLE: txref (base)
txid 67c0ee676221d9e0e08b98a55a8bf8add9cba854f13dda393e38ffa1b982b833 is on the testnet3 chain, at blockheight 1201739, transaction position 2. Its txref is

BTCR uses txref-exts, or extended txrefs that also include a reference to the TXO index within the transaction. didm-btcr issue 1

This extended encoding is similar to the base encoding, but with the following modifications:

  1. Remove chain-specific prefixes (e.g. tx1 or txtest1)

  2. Support for additionally specifying tx output index (txref-ext)

  3. Future: support lightning ids

EXAMPLE: txref-ext
txid 67c0ee676221d9e0e08b98a55a8bf8add9cba854f13dda393e38ffa1b982b833 is on the testnet3 chain, at blockheight 1201739, transaction position 2 and we want to specify the second tx output (index 1). Its txref-ext is

3.2. BTCR DID Format

BTCR DIDs have the following format:

btcr-did        = "did:btcr:" btcr-identifier
                 [ ";" did-service ] [ "/" did-path ]
                 [ "?" did-query ] [ "#" did-fragment ]
btcr-identifier = txref-ext encoded transaction id
A BTCR DID for txid 67c0ee676221d9e0e08b98a55a8bf8add9cba854f13dda393e38ffa1b982b833, on the testnet3 chain, at blockheight 1201739, transaction position 2 and tx output index 1 is

3.3. Authentication

Authentication is the process the ledger uses to determine if an entity is associated with a DID. By convention, BTCR grants the transaction signing key the ability to authenticate. Authentication is the only default ability; meaning that if there is no continuation DID Document, then authentication with the transaction signing key is the only ability granted by the BTCR DID.

EXAMPLE: Expressing authentication credentials
  "@context": "",
  "id": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l",
  "authentication": [... array of acceptable authentication suites ...]

A detailed example of a valid set of authentication credentials follows:

EXAMPLE: Detailed example of authentication credentials entry
  "@context": "",
  "id": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l",
  "authentication": [{
    "type": "EdDsaSAPublicKeySecp256k1Authentication",
    "publicKey": {
      "id": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l#keys-1",
      "type": "EdDsaSAPublicKeySecp256k1",
      "owner": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l",
      "publicKeyHex": "0280e0b456b9e97eecb8028215664c5b99ffa79628b60798edd9d562c6db1e4f85"

3.4. Continuation DID Documents

Because BTCR DIDs have very limited capabilities (authentication with the tx signing key), BTCR uses the concept of continuation documents to provide additional key material, capabilities, and service endpoints.

The continuation DID document is referenced by a link from the transaction OP_RETURN field. The continuation DID document must be signed in one of the following ways:

  1. Continuation DID document is stored in an immutable store. In this case, the signature on the transaction suffices to sign the continuation DID document.

  2. Continuation DID document is signed with the transaction signing key, along with a timestamp. This is necessary if the document is in a mutable store; otherwise the document can be changed at any time.

Immutable storage for the DID document is preferred. A DID document in a mutable store MUST be signed exactly once with the timestamp.

4. Operations

4.1. Creating a DID

A BTCR DID is created by creating a Bitcoin transaction with an optional OP_RETURN data field referring to additional DID document material, as described in this section.


Creating the initial BTCR DID:

  1. Create key set (B0/P0/S0)

  2. Create key set (B1/P1/S1)

  3. Create Bitcoin transaction:

    1. Output: Change address B1

    2. Optional output: OP_RETURN

    3. Signing key is S0, which reveals public key P0 in the transaction

  4. Issue TX0 and wait for confirmation. didm-btcr issue 7

  5. Get Extended TX Ref encoding of the confirmed transaction TXREF(TX0) didm-btcr issue 1

At this point we have a DID of the format did:btcr:TXREF(TX0).

4.2. Reading a DID

  1. Extract the transaction references from the BTCR DID (i.e. did:btcr:TXREF(TX0))

  2. Look up transaction. Is the transaction output spent?

    • no: this is the latest version of the DID. From this we can construct the DID Description (described below)

    • yes: keep following transaction chain until the latest with an unspent output is found

See BTCR resolver for additional details. TODO: merge in

4.3. Updating a DID

An entity updates the BTCR DID Description by spending the current transaction output. The BTCR Transaction Structure diagram shows how that is done in this second transaction.

  1. Create new tx like above, but send to B2

  2. Set the OP_RETURN to the new DID Description

  3. Sign tx with S1 (P1 is revealed)

4.4. Deleting a DID


5. Versioning

Version of this Specification

[Define how this spec will be versioned. This SHOULD be by using the bikeshed versioning mechanism.]

Version of the JSON-LD Context

[Define how your JSON-LD context will be versioned. This MUST use the mechanism defined in the DID spec.]

6. Security Considerations

Requirements from Method Spec Template definition:

At least the following forms of attack MUST be considered:
eavesdropping, replay, message insertion, deletion, modification,
impersonation, and man-in-the-middle.

Potential denial of service attacks MUST be identified as well.

If the protocol incorporates cryptographic protection mechanisms, it
should be clearly indicated which portions of the data are protected and
what the protections are (i.e., integrity only, confidentiality, and/or
endpoint authentication, etc.).

Some indication should also be given to what sorts of attacks the
cryptographic protection is susceptible.

Data which should be held secret (keying material, random seeds, etc.)
should be clearly labeled.

If the technology involves authentication, particularly user-host
authentication, the security of the authentication method MUST be
clearly specified.

Residual risks (such as the risks from compromise in a related protocol,
incorrect implementation, or cipher) after threat mitigation has been

This section MUST provide integrity protection and update authentication
for all operations required by Section 7 of this specification (DID

6.1. Binding of Identity

6.2. Authentication Service Endpoints

6.3. Non-Repudiation

6.4. Notification of DDO Changes

6.5. Key and Signature Expiration

6.6. Key Revocation and Recovery

7. Privacy Considerations

7.1. Keep Personally-Identifiable Information (PII) Off-Ledger

7.2. DDO Correlation Risks

7.3. Herd Privacy

Appendix A: Examples

Typical DID Document

The following is a complete example of a typical BTCR DID Document:

EXAMPLE: Typical BTCR DID Document
  "@context": "",
  "id": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l",
  "publicKey": [
      "id": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l#keys-1",
      "owner": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l",
      "type": "EdDsaSAPublicKeySecp256k1",
      "publicKeyHex": "0280e0b456b9e97eecb8028215664c5b99ffa79628b60798edd9d562c6db1e4f85"
      "id": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l#keys-2",
      "type": "RsaVerificationKey2018",
      "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n",
      "owner": "did:btcr:8kyt-fzzq-qpqq-ljsc-5l"
  "authentication": [
      "type": "EdDsaSAPublicKeySecp256k1Authentication",
      "publicKey": "#keys-1"
      "type": "RsaSignatureAuthentication2018",
      "publicKey": "#keys-2"
  "service": [
      "type": "BTCREndpoint",
      "serviceEndpoint": ""
  "SatoshiAuditTrail": [
      "chain": "testnet",
      "blockhash": "0000000000000722ded9d85d67e145ba41c53ef2e8680f75540a08b885febba5",
      "blockindex": 2,
      "outputindex": 1,
      "blocktime": "2017-09-23T17:27:56.682Z",
      "time": 1499501000,
      "timereceived": "2017-09-23T17:27:56.682Z",
      "burn-fee": -0.05


Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.


Terms defined by this specification


Normative References

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL:

Issues Index

BTCR uses txref-exts, or extended txrefs that also include a reference to the TXO index within the transaction. didm-btcr issue 1