Self Certifying Decentralized Identifiers

Orb DIDs are self certifying. The data structure that encodes the ordered updates to a DID document form their own verifiable chain from inception to the current state of the DID document. We inherit this property due to our usage of the [[[SIDETREE]]] protocol for encoding the DID document updates.

Propagation via Decentralized Federation

Orb makes use of decentralized federation protocols to propagate announcements and replicate content in a gossip manner. We use [[[ACTIVITYSTREAMS-CORE]]] and [[[ACTIVITYPUB]]]. In later sections, we describe the vocabulary and profile for using these protocols in Orb.

Orb does not rely on public blockchains nor DLTs to coordinate - there is no need for network consensus. Instead, we rely on self certifying DIDs being propagated and the ability to replicate VDRs in a gossip manner.

DID Updates Are Batched

Modifications to DID documents that are sent to an Orb servers are aggregated into batches prior to being announced on the decentralized network. By supporting batching, we enhance the scalability properties due to a reduction in messages and objects being stored. We inherit this property due to our usage of the [[[SIDETREE]]] protocol for encoding the DID document updates.

DID Updates Batches Form a Graph

When writing a batch of DID document updates, an Orb server also includes immutable references to the prior batches. These references form a graph (in the form of a Merkle Tree) such that the ancestor operations can be processed prior to a newly observed batch. This property is needed in the Orb data structures since we do not have a common blockchain to provide this history.

When a DID controller supplies their DID, they also include a reference to a batch in their DID string. This reference allows an Orb server to discover the graph where a DID was created (or more generally where a core Sidetree update occurred). This reference also enables the DID controller to specify a minimum version of the DID document that must be discovered in order to resolve.

CAS-based Verifiable Data Registry

The Orb VDR leverages Content-Addressable Storage (CAS) to hold the DID document batch files. The processed batch files result in hosting resolvable DID documents. By supporting a CAS, we enhance the ability to replicate immutable content across the decentralized network. We inherit this property due to our usage of the [[[SIDETREE]]] protocol for encoding the DID document updates and batches.

We also leverage the CAS to hold the graph of batches. The immutable references to prior batches are in the form of hashlinks [[HASHLINK]].

Witnesses Resolve Late Publishing

The Orb method relies on decentralized federation, gossip and CAS replication mechanisms to propagate the VDR among servers. The self certifying nature of Orb DIDs enables confidence in the DID validity without the need for network consensus. As the DID controller is fully responsible for the changes to their DIDs, they can create a new branch in their operation chain even after time has passed. This situation is called late publishing. The resolver systems require a mechanism to decide which branch should be used to represent the current DID state. It is also beneficial to create rules that enable a consistent viewpoint of the active branch among interconnected Orb servers. Resolver systems use rules to determine the first published branch and use observations from Witness systems to assist in that decision.

In the absence of Witnesses, we start with a simple rule: the first branch of a DID observed by an Orb server is the first published branch for that DID from that server's point of view. As Orb servers become increasingly interconnected, batches are gossiped between the Orb servers. Each server that forwards a batch includes a signed timestamp of when they observed the batch. The Orb Server MAY designate some of the other Orb servers as trusted. These trusted servers are then used to determine relative timing between batches. In the case that a majority viewpoint of itself and the other trusted Orb servers exists, that majority viewpoint will be used to determine the relative timing of the batches. From the relative timing of the batches, we also resolve the relative timing of the branch in the DID. An Orb server does not wait for consensus - its viewpoint may eventually converge to a majority view, over time, in these situations.

Rules exist to resolve the active branch so that Orb servers can consistently resolve the DID controller's intended and current DID document. To mitigate against initial divergences, we also introduce the Witness role to observe a transaction prior to propagation. The Orb transaction writer preannounces the existence of an Orb transaction by submitting it to a Witness. A Witness creates a proof that they observed an Orb transaction at a certain time. Witnesses have the capability to provide timestamping and also host a Witness Ledger to provide relative ordering between merged sets of Orb Transactions.

Although each Orb Server decides who to designate as trusted, it is also important that an Orb Server's behavior can be monitored. We use a Witness ledger as the mechanism for monitoring behavior - if inconsistencies are detected, other systems can adjust their viewpoint for trustworthiness. A Witness ledger is responsible for recording individual Orb transactions, providing signed transaction timestamps that can be embedded within a propagated Orb transaction, providing ledger consistency proofs, and providing an API that exposes their ledger. A Witness ledger is not responsible for maintaining the Orb transaction graph structure nor is it responsible for maintaining a complete history of Orb transactions. An Orb server is monitorable by exposing a Witness ledger API.

We structure witnesses ledgers in a similar manner to certificate transparency [[RFC6962]], as append-only Merkle Trees with proof capabilities. A Witness ledger promises to include a submitted Orb transaction within a time period known as the Maximum Merge Delay (MMD). Once the ledger merges a set of Orb transactions into the Merkle Tree, a Signed Tree Head (STH) is produced. The STH (and associated Merkle Proofs) is used to validate consistency between older and newer ledger revisions.

When an Orb server creates a transaction, the server requests other Orb servers (as Witnesses) to include the transaction into their Witness ledger. The Orb server preannounces a transaction to Witnesses after preparing and writing the Sidetree CAS objects. The transaction announcement is then sent to Witnesses for validation and inclusion by the Witnesses. Each witnesses validates the Orb transaction structure and that it was issued within an acceptable delta of their current time. Upon successful validation, each witness returns a signed transaction timestamp and a promise to include the Orb transaction into their Ledger. The Orb transaction (combined with the signed transaction timestamps) is then written into the CAS and propagated. When an Orb Server receives a propagated transaction, they invalidate (as stale) each Sidetree operation that has a timestamp that is not within an acceptable delta of the Orb transaction's timestamp. When these proofs originate from trusted servers, their timing information is immediately applied after receiving an Orb transaction propagation. An Orb server that receives witnessed transactions from trusted servers likely holds the majority timing view immediately in these situations.

Witnesses Propagate for a DID

As Orb relies on gossip replication, it is possible for a resolver system to miss transactions originating from other servers that they do not follow. To mitigate this issue for a particular DID, we allow the DID controller to specify a witness policy. This policy contains a set of witnesses that MUST be used when an Orb transaction includes changes to the associated DID. The Writer server ensures that, according to the DID's policy, a sufficient number of these server(s) are also acceptable as Witnesses to the Writer server. If the DID's policy is unacceptable to the Writer server, the operation MUST be rejected and not included into the Orb transaction. The DID policy ensures that the Resolver Servers can determine if they have the latest propagations and that the DID controller can use any Writer server that has mutually acceptable policies.

As a DID can be associated to a particular Witness, that Witness provides observations of the DID controller's behavior. In addition to propagating for a DID, the associated Witness is also given extra weight as a tie-breaker for resolving the late publishing scenario described in the previous section.

The ability to set (or change) the policy is an operation that is included into a propagated Sidetree core index.

Web Discovery APIs are Supported

The Orb DID method enables CAS discovery and usage via Web APIs. The WebFinger protocol [[RFC7033]] allows systems to query for both [[ACTIVITYPUB]] endpoints and also for CAS endpoints for a given resource. By enabling a fully Web-enabled model, we do not introduce a requirement on Distributed Hash Table (DHT) usage into the method.

Distributed Hash Tables are Supported

Although Orb DIDs can be created that do not have a dependency on DHTs, we also enable optional support for registering CAS resources on a DHT. Orb servers MAY choose to expose their CAS-based VDRs on a Distributed Hash Table (DHT) network such as IPFS. When using a DHT, we gain the advantage of not needing to specify any Web domain to be queried for discovery.

Graphs Enable Propagation Discovery

The Orb transaction graph that is stored into the content-addressable storage (CAS) also enables discovery of propagation properties. Each node in the transaction graph includes known CAS discovery information and witness endpoints. The CAS discovery information enable Orb servers to include additional endpoints when responding to WebFinger [[RFC7033]] queries. The witness endpoints enable Orb servers to follow additional systems for propagation.

Create

An Orb DID is created by submitting a create to the operations endpoint of an Orb Server, as specified in Sidetree.

Detailed steps are specified in the Sidetree API.

Read

An Orb Server exposes a DID resolution API as defined in [[DID-CORE]] using the HTTP(S) Binding specified by [[DIDRESOLUTION]].

Detailed steps and additional method metadata properties are specified in the Sidetree API.

Update

An Orb DID is created by submitting an update to the operations endpoint of an Orb Server, as specified in Sidetree.

Detailed steps are specified in the Sidetree API.

Recover

An Orb DID is recovered by submitting a recover to the operations endpoint of an Orb Server, as specified in Sidetree.

Detailed steps are specified in the Sidetree API.

Deactivate

An Orb DID is deactivated by submitting a deactivate to the operations endpoint of an Orb Server, as specified in Sidetree.

Detailed steps are specified in the Sidetree API.

Propagation Delay and Canonical IDs

            did:orb:https:example.com:uAAA:EiA329wd6Aj36YRmp7NGkeB5ADnVt8ARdMZMPzfXsjwTJA
          

            did:orb:https:example.com:uAAA:EiA329wd6Aj36YRmp7NGkeB5ADnVt8ARdMZMPzfXsjwTJA:ey...
          

CAS Discovery and Equivalent IDs

Discovery

              GET /.well-known/did-orb HTTP/1.1
              Host: alice.example.com
              Accept-Encoding: gzip, deflate
            

              HTTP/1.1 200 OK
              Date: Sat, 30 Jan 2021 18:31:58 GMT
              Content-Type: application/json; charset=utf-8
              Connection: keep-alive
              Access-Control-Allow-Origin: *

              {
                "resolutionEndpoint": "https://alice.example.com/sidetree/0.1/identifiers",
                "operationEndpoint": "https://alice.example.com/sidetree/0.1/operations"
              }
            

              GET /.well-known/did-orb HTTP/1.1
              Host: shared.example.com
              Accept-Encoding: gzip, deflate
            

              HTTP/1.1 200 OK
              Date: Sat, 30 Jan 2021 18:31:58 GMT
              Content-Type: application/json; charset=utf-8
              Connection: keep-alive
              Access-Control-Allow-Origin: *
  
              {
                "resolutionEndpoint": "https://shared.example.com/sidetree/0.1/identifiers",
                "operationEndpoint": "https://shared.example.com/sidetree/0.1/operations"
              }
            

              GET /.well-known/webfinger?resource=https%3A%2F%2Fshared.example.com%2Fsidetree%2F0.1%2Fidentifiers HTTP/1.1
              Host: shared.example.com
              Accept-Encoding: gzip, deflate
            

              HTTP/1.1 200 OK
              Date: Sat, 30 Jan 2021 18:31:58 GMT
              Content-Type: application/jrd+json
              Connection: keep-alive
              Access-Control-Allow-Origin: *
  
              {
                "subject": "https://shared.example.com/sidetree/0.1/identifiers",
                "properties": {
                  "https://trustbloc.dev/ns/min-resolvers": 2
                },
                "links": [
                  {
                    "rel": "self",
                    "href": "https://shared.example.com/sidetree/0.1/identifiers"
                  },
                  {
                    "rel": "alternate",
                    "href": "https://charlie.example.com/sidetree/0.1/identifiers"
                  },
                  {
                    "rel": "alternate",
                    "href": "https://oscar.example.com/sidetree/0.1/identifiers"
                  },
                  {
                    "rel": "alternate",
                    "href": "https://mike.example.com/sidetree/0.1/identifiers"
                  }
                ]
              }
            

Operation Origin and Policy

The DID controller declares their origin policy by setting the URI of their desired witness into the anchorOrigin property in the Create or Replace operation.

TODO: In a followup revision, we might specify additional origin policy information.

Operation Anchoring Validity

The DID Controller includes their skew-adjusted current timestamp in the anchorFrom property of an operation's data object payload. To allow for clock skew, the DID Controller subtracts five minutes from their current timestamp. The timestamp is formatted as a [[RFC7519]] NumericDate.

The DID Controller includes their skew-adjusted current timestamp in the anchorUntil property of an operation's data object payload. To allow for batching and clock skew, the DID Controller adds 25 minutes to their current timestamp. The timestamp is formatted as a [[RFC7519]] NumericDate.

The delta range between anchorFrom and anchorUntil is 30 minutes.

TODO: In a followup revision, we will specify protocol parameters to constrain the delta range.

Anchor Properties

Orb specifies anchoring metadata for the Sidetree core index file. This metadata includes each DID included in the index along with a hashlink to the previous anchor. The metadata is formatted as a Linkset [[LINKSET]].

The anchor property contains the hashlink to the Sidetree core index file. The profile property contains the version of the Orb spec (e.g., https://w3id.org/orb#v1). The author property contains the Orb server URI that published the anchor. The item property contains a collection of the DIDs contained in the Sidetree files (referenced by anchor). The previous property (within an item contains a hashlink to the previous anchor that contained a Sidetree operation for the DID.

            {
              "linkset": [
                {
                  "anchor": "hl:uEiDkZV2rw2XKdqPoGKy6Vg0HEk36HfsxyWfnY3jp3Q2K-g",
                  "author": "https://orb.domain2.com/services/orb",
                  "item":[
                    {"href": "did:orb:uAAA:EiBTRfNkzKwW3ZVDl6WwXsYhre6HPE8jQ7e9l3m6pii-iw"},
                    {
                      "href": "did:orb:uAAA:EiCUt537plK2HuI0k2rQNP3MgDtq1T5Wj_LZ7yQOJY2gcA",
                      "previous": ["hl:uEiA30C_KU_wogvUhJKLUA8bXHqSM_75X1QZQN3z_4VacXQ"]
                    },
                    {"href": "did:orb:uAAA:EiDpy0--tFbSNGG-UNce9_yXfRBFQ9kkme8SREFLUiaK6g"},
                    {"href": "did:orb:uAAA:EiAVOBVLnwIgF6f83JfJUi82mhfAQ2oVKpsZCfkt5tX2aQ"}
                  ],
                  "profile": "https://w3id.org/orb#v1"
                }
              ]
            }
          

Schemes

Hashlink

The scheme uses a hashlink [[HASHLINK]] including the multihash of the latest anchor object and metadata containing URLs to the anchor object. The first segment after `did:orb` contains the anchor multihash, the second segment contains the hashlink metadata and the third segment contains the Sidetree DID suffix.

          did:orb:hl:uEiDlXjleTwr4eZalpXVy086zs-TPK-h54ojbpl7EBvZeHQ:uoQ-Bc2h0dHBzOi8vZXhhbXBsZS5jb20:EiDyOQbbZAa3aiRzeCkV7LOx3SERjjH93EXoIM3UoN4oWg
        

Hostmeta

The hostmeta schemes fetch service discovery information using the JRD form of hostmeta [[RFC6415]]. To retrieve `host-meta.json`, the `scheme` and `path` segments of the Orb DID are converted into a URL. The DID is transformed into a URL by replacing `:` in the `path` segments with `/` and prefixing the `scheme`. From the transformed URL, the host-meta.json can be retrieved according to [[RFC6415]].

          did:orb:https:example.com:uEiDlXjleTwr4eZalpXVy086zs-TPK-h54ojbpl7EBvZeHQ:EiDyOQbbZAa3aiRzeCkV7LOx3SERjjH93EXoIM3UoN4oWg
        

          did:orb:ipns:k51qzi5uqu5dl3ua2aal8vdw82j4i8s112p495j1spfkd2blqygghwccsw1z0p:uEiDlXjleTwr4eZalpXVy086zs-TPK-h54ojbpl7EBvZeHQ:EiDyOQbbZAa3aiRzeCkV7LOx3SERjjH93EXoIM3UoN4oWg
        

Add description and example of Orb JRD.

IPFS

The scheme retrieves the anchor object from IPFS. To retrieve the anchor object, the multihash must be converted into an IPFS URL (containing an IPFS CID). The multihash is transformed into a CID as follows:

• Multibase: base32
• CID version: 1
• Multicodec: raw (0x55)
• Multihash: the anchor multihash in the DID

          DID: did:orb:ipfs:uEiDlXjleTwr4eZalpXVy086zs-TPK-h54ojbpl7EBvZeHQ:EiDyOQbbZAa3aiRzeCkV7LOx3SERjjH93EXoIM3UoN4oWg
          URL: ipfs://bafkreihfly4v4tyk7b4znjnfovznhtvtwpsm6k7iphrirw5gl3can5s6du
        

Ledger Types

Discovery

The linked data proof includes a domain property that indicates the ledger that promises to include an Orb transaction. The type of the ledger can be determined using the WebFinger protocol [[RFC7033]] along with known replicas, if any. The replica links have the relation field set to alternate.

          GET /.well-known/webfinger?resource=https%3A%2F%2Fwitness1.example.com%2Fledgers%2Fmaple2021 HTTP/1.1
          Host: witness1.example.com
          Accept-Encoding: gzip, deflate
        

When the ledger exists, an HTTP 200 status code is returned.

          HTTP/1.1 200 OK
          Date: Sat, 30 Jan 2021 18:31:58 GMT
          Content-Type: application/jrd+json
          Connection: keep-alive
          Access-Control-Allow-Origin: *

          {
            "subject": "https://witness1.example.com/ledgers/maple2021",
            "properties": {
              "https://trustbloc.dev/ns/ledger-type": "vct-v1"
            },
            "links": [
              {
                "rel": "self",
                "href": "https://witness1.example.com/ledgers/maple2021"
              },
              {
                "rel": "alternate",
                "href": "https://replica.example.com/ledgers/maple2021"
              }
            ]
          }
        

Verifiable Credential Transparency (VCT)

The Verifiable Credential Transparency (VCT) Witness ledger is based on on certificate transparency [[RFC6962]]. The Anchor Credentials are included into VCT ledgers (as append-only Merkle Tree logs). VCT ledgers may be named to enable rollover.

We extend [[RFC6962]] to include Verifiable Credential (VC) [[VC-DATA-MODEL]] objects. The following subsections describe the endpoints and the additional VC type for the Merkle Tree.

            GET /ledgers/maple2021/ct/v1/get-sth HTTP/1.1
            Host: witness1.example.com
            Accept-Encoding: gzip, deflate
          

            HTTP/1.1 200 OK
            Date: Sat, 30 Jan 2021 13:20:11 GMT
            Content-Type: application/json
            Connection: keep-alive
            Access-Control-Allow-Origin: *

            {
              "tree_size": 100,
              "timestamp": 1612097791,
              "sha256_root_hash": "qOK55eWhQ96DmRbAsHTridM1BrxZtqJAW2uF0ceQcTo=",
              "tree_head_signature": "6UIXmSf8Pg9jY6e8DUPguEW3sl0HxX0fckMnP5ckUchcnsjlXee0722AV4RL1+xNEGVX/poCKu/wPH9teprMyw",
            }