BTCR DID Method

Draft Community Group Report,

Issue Tracking:
GitHub
Editors:
Christopher Allen
Kim Hamilton Duffy
Ryan Grant
Dan Pape

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 8 August 2019, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

Abstract

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 an optional 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 decentralized 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.

ledger: TODO.

outpoint: outpoint index.

outpoint index: A bitcoin transaction output. Also called outpoint (without index). This terminology is chosen for consistency with BIP-136.

3. Basic Concepts

3.1. Txref

BTCR identifiers use the TxRef encoding to refer to a transaction position within the Bitcoin blockchain, as described in BIP-0136, Bech32 Encoded Transaction Position References. A TxRef encodes the chain, blockheight, and transaction index where the transaction is located, and an optional reference to the outpoint index within the transaction.

Because the TxRef encodes the transaction’s position in the Bitcoin blockchain, that means it is only known after a transaction has been confirmed. That distinguishes it from, for example, transaction ids (hashes), which are known even before confirmation.

Modifications to BIP-0136:

  1. The BTCR Method Specification has chosen to elide chain-specific prefixes (e.g. tx1 or txtest1), as permitted by BIP-0136.

EXAMPLE: TxRef (without outpoint index)
txid 67c0ee676221d9e0e08b98a55a8bf8add9cba854f13dda393e38ffa1b982b833 is on the testnet3 chain, at blockheight 1201739, transaction position 2. Its TxRef is 
xkyt-fzzq-q4wq-f2d
EXAMPLE: TxRef (with outpoint index)
txid 67c0ee676221d9e0e08b98a55a8bf8add9cba854f13dda393e38ffa1b982b833 is on the testnet3 chain, at blockheight 1201739, transaction position 2 and we want to specify the second transaction outpoint index (index 1). Its TxRef is 
8kyt-fzzq-qpqq-ljsc-5l

  1. The BTCR Method Specification does not allow ambiguity that arises when the transaction outpoint index is 0

In the case where a BTCR-related transaction specifies an outpoint index, and that outpoint index is 0, the short form of the BTCR DID must be used.

EXAMPLE: BTCR Transaction outpoint index 0 ambiguity example
For testnet transaction 
f8cdaff3ebd9e862ed5885f8975489090595abe1470397f79780ead1c7528107
, if referring to outpoint index 0, the BTCR DID must be resolved as follows:

VALID: 

did:btcr:xyv2-xzpq-q9wa-p7t
INVALID: 
did:btcr:8yv2-xzpq-qqqq-9yce-nk

BIP136 supports both forms for index 0, but we are making the decision that BTCR supports only the short form when index==0. This is for the following reasons:

If a DID resolver encounters the invalid form, it must reject the input as invalid.

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 encoded transaction id
EXAMPLE: BTCR DID
A BTCR DID for txid 67c0ee676221d9e0e08b98a55a8bf8add9cba854f13dda393e38ffa1b982b833, on the testnet3 chain, at blockheight 1201739, transaction position 2 and tx outpoint index 1 is 
did:btcr:8kyt-fzzq-qpqq-ljsc-5l

3.3. BTCR DID construction

BTCR DID transactions can be constructed in two ways: with or without an OP_RETURN field. If the transaction does not have an OP_RETURN field, it is granted default capabilities constructed from the transaction itself, resulting in a generated DID document. Otherwise, its capabilities are determined by the DID document (called continuation document) referenced in the OP_RETURN field.

3.4. Default Capabilities

If an (unspent) BTCR DID’s transaction does not contain an OP_RETURN field, a DID resolver must generate the DID Document from the transaction itself. Specifically, it grants the transaction signing key the following capabilities:

  1. Authentication

  2. Sign Verifiable Credentials

EXAMPLE: Detailed example of default capabilities
{
    "@context": ["https://w3id.org/did/v0.11", "https://w3id.org/btcr/v1"],
    "id": "did:btcr:xyv2-xzpq-q9wa-p7t",
    "publicKey": [
       {
            "id": "did:btcr:xyv2-xzpq-q9wa-p7t#satoshi",
            "controller": "did:btcr:xyv2-xzpq-q9wa-p7t",
            "type": "EcdsaSecp256k1VerificationKey2019",
            "publicKeyBase58": "owh12LKNuphe97teJTZKQTKNewSVTwjHcskPbq34epCY"
        },
        {
             "id": "did:btcr:xyv2-xzpq-q9wa-p7t#vckey-0",
             "controller": "did:btcr:xyv2-xzpq-q9wa-p7t",
             "type": "EcdsaSecp256k1VerificationKey2019",
             "publicKeyBase58": "owh12LKNuphe97teJTZKQTKNewSVTwjHcskPbq34epCY"
         }
    ],
    "authentication": ["#satoshi"],
    "assertionMethod": ["#vckey-0"]
}

We will see in the following sections that this option of BTCR DID construction is only possible for the first transaction in a BTCR transaction chain; i.e. all subsequent transactions must use an OP_RETURN, or the DID is considered revoked or deleted.

3.5. Continuation DID Documents

If an (unspent) BTCR DID’s transaction contains an OP_RETURN field, the OP_RETURN field must contain an HTTP URL pointing to a DID document (specifying the key material, capabilities, and service endpoints). Note that the default capabilities described above are not granted; a DID resolver must return the referenced DID document as is.

With this construction, the DID document referenced by the transaction must be updated after confirmation with the BTCR DID (which is known only after the tx is confirmed) and signed with the transaction signing key with a timestamp.

The OP_RETURN field may be used in the first transaction in a BTCR chain, and must be used for all subsequent transactions in the chain, up to the point of revocation or deletion.

Note: If the OP_RETURN exists, the continuation DID document obviates the need for additional implicit capabilities; we assume each capability is listed explicitly in the continuation DID document.

3.6. Following the tip

The transaction outpoint index specified by DID, or first monetary outpoint index if not specified, is used for "following the tip". A spent outpoint indicates an updated or deleted (revoked) DID. A DID resolver determines whether it’s updated (and finds the latest) or deleted by walking the chain of spent transaction outpoint (or "following the tip) as follows.

Note: If any transaction outpoint is spent, then the transaction chain is greater than one by definition. This algorithm applies only to transaction chains greater than one. (TODO: awkward)

DO
    transaction := (transaction that spent Outpoint)
WHILE (current transaction Outpoint is spent OR OP_RETURN field is missing)

If the latest transaction in the chain has no OP_RETURN, a BTCR DID is considered deleted (revoked).

Otherwise, the BTCR DID is not revoked, and the latest transaction in the chain should be used by the resolver.

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.

Abbreviations:

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 TX Ref encoding of the confirmed transaction TxRef(TX0)

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 outpoint index 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 outpoint 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 outpoint. 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)

BTCR Transaction Structure

4.4. Deleting a DID

A BTCR DID is considered deleted (or revoked) if the latest transaction has no OP_RETURN and there is more than one transaction in the BTCR DID chain.

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. Omit the OP_RETURN

  3. Sign tx with S1 (P1 is revealed)

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
deployed.

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

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": ["https://w3id.org/did/v0.11", "https://w3id.org/btcr/v1"],
    "id": "did:btcr:xyv2-xzpq-q9wa-p7t",
    "publicKey": [
       {
            "id": "did:btcr:xyv2-xzpq-q9wa-p7t#satoshi",
            "controller": "did:btcr:xyv2-xzpq-q9wa-p7t",
            "type": "EcdsaSecp256k1VerificationKey2019",
            "publicKeyBase58": "owh12LKNuphe97teJTZKQTKNewSVTwjHcskPbq34epCY"
        },
        {
             "id": "did:btcr:xyv2-xzpq-q9wa-p7t#vckey-0",
             "controller": "did:btcr:xyv2-xzpq-q9wa-p7t",
             "type": "EcdsaSecp256k1VerificationKey2019",
             "publicKeyBase58": "owh12LKNuphe97teJTZKQTKNewSVTwjHcskPbq34epCY"
         }
    ],
    "authentication": ["#satoshi"],
    "assertionMethod": ["#vckey-0"],
    "service":
      {
        "id": "did:btcr:xyv2-xzpq-q9wa-p7t#CRS",
        "type": "BTCR-CredentialRepositoryService",
      "serviceEndpoint": "https://github.com/ChristopherA/self/blob/master/ddo.jsonld?hl=z87f623hkjh578v76dsf873h"
      },
}

Conformance

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.

Index

Terms defined by this specification

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119