index.bs

<pre class='metadata'>
Title: BTCR DID Method
Shortname: didm-btcr
Level: 1
Status: w3c/CG-DRAFT
Group: Credentials Community Group
URL: https://w3c-ccg.github.io/didm-btcr/

Editor: Christopher Allen, http://www.lifewithalacrity.com/
Editor: Kim Hamilton Duffy, https://github.com/kimdhamilton
Editor: Ryan Grant
Editor: Dan Pape, https://github.com/danpape

Abstract: The Bitcoin Reference DID method specification conforms to the requirements specified in the <a href="https://w3c-ccg.github.io/did-spec/">DID specification</a> currently published by the W3C Credentials Community Group. For more information about DIDs and DID method specifications, please see the <a href="https://github.com/WebOfTrustInfo/rwot7/blob/master/topics-and-advance-readings/did-primer.md">DID Primer</a>.

</pre>

Introduction {#intro}
=====================

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.

Terminology {#terminology}
===========

<dfn>block</dfn>: A data structure that contains one or more [=ledger=] events.

<dfn>blockchain</dfn>: A [=ledger=] containing a series of [=block=]s
where the ordering of the blocks can be mathematically proven to be
correct.

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

<dfn>continuation [=DID=] document</dfn>: A continuation [=DID=] document is an optional document external to the Bitcoin transaction providing
additional DID document keys, ...

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

<dfn>DID</dfn>: a distributed identitfier.

<dfn>decentralized system</dfn>: 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.

<dfn>decentralized ledger</dfn>: 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.

<dfn>ledger</dfn>: TODO.

<dfn>outpoint</dfn>: [=outpoint index=].

<dfn>outpoint index</dfn>: A bitcoin transaction output. Also called outpoint (without index). 
This terminology is chosen for consistency with <a href="https://github.com/bitcoin/bips/blob/master/bip-0136.mediawiki">BIP-136</a>.

Basic Concepts {#concepts}
==============

Txref {#txref}
--------------

BTCR identifiers use the TxRef encoding to refer to a transaction position within the Bitcoin blockchain, as described in BIP-0136, <a href="https://github.com/bitcoin/bips/blob/master/bip-0136.mediawiki">Bech32 Encoded Transaction Position References</a>. 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.


<div class="example" heading="TxRef (without outpoint index)"> txid
67c0ee676221d9e0e08b98a55a8bf8add9cba854f13dda393e38ffa1b982b833 is on
the testnet3 chain, at blockheight 1201739, transaction position 2. Its
TxRef is <pre>xkyt-fzzq-q4wq-f2d</pre></div>


<div class="example" heading="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
<pre>8kyt-fzzq-qpqq-ljsc-5l</pre></div>

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

<div class="example" heading="BTCR Transaction outpoint index 0 ambiguity example">
For testnet transaction <pre>f8cdaff3ebd9e862ed5885f8975489090595abe1470397f79780ead1c7528107</pre>, if referring to outpoint index 0, the BTCR DID must be resolved as follows:

VALID: <pre>did:btcr:xyv2-xzpq-q9wa-p7t</pre>
INVALID: <pre>did:btcr:8yv2-xzpq-qqqq-9yce-nk</pre>
</div>


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:
- clarity for resolution implementers
- ambiguous id is a potential security issue

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


BTCR DID Format {#format}
---------------

BTCR DIDs have the following format:

<pre>
      btcr-did        = "did:btcr:" btcr-identifier
                       [ ";" did-service ] [ "/" did-path ]
                       [ "?" did-query ] [ "#" did-fragment ]
      btcr-identifier = TxRef encoded transaction id
</pre>

<div class="example" heading="BTCR DID"> A BTCR DID for txid
67c0ee676221d9e0e08b98a55a8bf8add9cba854f13dda393e38ffa1b982b833, on the
testnet3 chain, at blockheight 1201739, transaction position 2 and tx
[=outpoint index=] 1 is <pre>did:btcr:8kyt-fzzq-qpqq-ljsc-5l</pre></div>

BTCR DID construction {#btcr_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.


Default Capabilities {#default_cap}
--------------------
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


<div class="example" heading="Detailed example of default capabilities">
<pre>
{
    "@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"]
}
</pre>
</div>

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.


Continuation DID Documents {#continuation}
--------------------------

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.


Following the tip {#following}
-----------------

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)

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

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.

Operations {#operations}
==========

Creating a DID {#creating}
--------------

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:
* Bi = bitcoin address i
* Pi = public key i
* Si = signing key i (or private key i)

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 <link to DDO continuation>
    3. Signing key is S0, which reveals public key P0 in the transaction
4. Issue TX0 and wait for confirmation. <a href="https://github.com/w3c-ccg/didm-btcr/issues/7">didm-btcr issue 7</a>
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). 

Reading a DID {#reading}
-------------

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 <a
href="https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-spring2018/pull/74">
BTCR resolver</a> for additional details. TODO: merge in


Updating a DID {#updating}
--------------

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)

<img src="diagrams/btcr-tx-ref.png" alt="BTCR Transaction Structure">


Deleting a DID {#deleting}
--------------

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)

Versioning {#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.]


Security Considerations {#security}
=======================

Requirements from Method Spec Template definition: 

<pre> 

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).
</pre>

Binding of Identity
-------------------

Authentication Service Endpoints
--------------------------------

Non-Repudiation
---------------

Notification of DDO Changes
---------------------------

Key and Signature Expiration
----------------------------

Key Revocation and Recovery
---------------------------

Privacy Considerations
======================

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

DDO Correlation Risks
---------------------

Herd Privacy
------------

Appendix A: Examples
====================

Typical DID Document
--------------------

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

<div class="example" heading="Typical BTCR DID Document">
<pre>

{
    "@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"
      },
}

</pre>
</div>