§ Sidetree

Specification Status: Editor’s Draft

Latest published version: identity.foundation/sidetree/spec

Editors:
Daniel Buchner (Microsoft)
Orie Steele (Transmute)
Contributors:
Henry Tsai (Microsoft)
Troy Ronda (SecureKey)
Mudassir Ali (Microsoft)
Guillaume Dardelet (Transmute)
Isaac Chen (Microsoft)
Christian Lundkvist (Consensys)
Kyle Den Hartog (Mattr)
Participate:
GitHub repo
File a bug
Commit history

Sidetree REST API specification: identity.foundation/sidetree/api


§ Abstract

Sidetree is a protocol for creating scalable decentralized public key infrastructure (DPKI) networks that can run atop of any existing decentralized ledger system (e.g. Bitcoin) and be as open, public, and permissionless as the underlying ledger they utilize. The protocol allows users to create globally unique, user-controlled identifiers and manage their associated metadata, all without the need for centralized authorities or trusted third parties. The syntax of the identifier and accompanying data model used by the protocol is conformant to that defined by W3C Decentralized Identifiers. Implementations of the protocol can be codified as their own distinct DID Methods and registered in the W3C DID Method Registry.

§ Introduction

This section is non-normative

Decentralized ledgers (e.g. Bitcoin) introduced the first-ever solution to the linear chronological oracle problem, which unlocked the ability to create robust decentralized identifier networks. However, current approaches that utilize these ledger systems to create decentralized identifier networks suffer from severely limited transactional volumes and other performance issues. Sidetree is a ‘Layer 2’ protocol that runs atop decentralized ledger systems to enable scalable W3C Decentralized Identifier (DID) implementations that can be fully open, public, and permissionless. Sidetree is able to do all this without requiring trusted intermediaries, centralized authorities, special protocol tokens, or secondary consensus mechanisms, while preserving the core attributes of decentralization and immutability of the underlying ledger systems it is implemented on.

Architecturally, Sidetree-based DID Method implementations are overlay networks composed of independent peer nodes (Sidetree nodes) that observe an underlying decentralized ledger (as illustrated under Network Topology), replicate ledger-anchored DID PKI state operations, and execute against that data a set of deterministic protocol rules to produce an eventually strongly consistent view of all DIDs in the network. The Sidetree protocol defines a core set of DID PKI state change operations, structured as delta-based Conflict-Free Replicated Data Types (i.e. Create, Update, Recover, or Deactivate), that mutate a Decentralized Identifier’s DID Document state. Sidetree nodes that participate in writing operations into the overlay network do so by anchoring Content-Addressable Storage (CAS) (e.g. IPFS) references to aggregated bundles of operations in an underlying ledger. The ledger acts as a linear chronological sequencing oracle, which the protocol leverages to order DID PKI operations in an immutable history all observing nodes can replay and validate. It is this ability to replay the precise sequence of DID PKI state change events, and process those events using a common set of deterministic rules, that allows Sidetree nodes to achieve a consistent view of DIDs and their DID Document states, without requiring any additional consensus mechanism.

§ Terminology

Term Description
Ledger A decentralized linear sequencing oracle (e.g. Bitcoin) that can be used to anchor the PKI state transformations of Decentralized Identifiers (DIDs) in a shared record that can be deterministically replayed by observers to derive the current PKI state of DIDs.
Core Index File JSON Document containing proving and index data for Create, Recovery, and Deactivate operations, and a CAS URI for the associated Provisional Index File. This file is anchored to the target ledger.
Provisional Index File JSON Document containing Update operation proving and index data, as well as CAS URI for Chunk File chunks.
Core Proof File JSON Document containing the cryptographic proofs for Recovery and Deactivate operations, which form the persistent backbone of DID PKI lineages.
Provisional Proof File JSON Document containing the cryptographic proofs for Update operations, which can be pruned via decentralized checkpointing mechanisms (this mechanism will arrive in future versions of the Sidetree protocol).
Chunk File JSON Document containing all verbose operation data for the corresponding set of DIDs specified in the related Provisional Index File.
CAS Content-addressable storage protocol/network (e.g. IPFS)
CAS URI The unique content-bound identifier used to locate a resource via the CAS protocol/network (e.g. IPFS)
Commit Value A chosen value that is used with a commitment scheme
Commitment The output of a commitment scheme
Commitment Scheme A cryptographic primative that allows one to commit to a chosen value, known as the commit value resulting in the generation of a commitment. A commitment can then be shared without revealing the commit value forming a proof of commitment where the possessor of the commit value can then later reveal the commit value proving the original commitment.
DID Document JSON Document containing public key references, service endpoints, and other PKI metadata that corresponds to a given DID (as defined in the W3C DID Specification).
DID Suffix The unique identifier string within a DID URI. e.g. The unique suffix of did:sidetree:123 would be 123.
DID Suffix Data Data required to deterministically generate a DID.
Multihash Protocol for differentiating outputs from common cryptographic hash functions, addressing size + encoding considerations: https://multiformats.io/multihash/
DID Operation Set of delta-based modifications that change the state of a DID Document when applied.
Operation Request JWS formatted request sent to a Sidetree Node to include a DID Operation in a batch of operations.
Update Key Pair A cryptographic key used to produce an Update Request JWS. Public key representation MAY be present in the DID Document. Public key representation MUST be used to produce Update Request commitment.
Recovery Key Pair A cryptographic key used to produce an Operation Request of type Recover or Deactivate. Public key representation MAY be present in the DID Document. Public key representation MUST be used to produce Operation Request commitment.
Public Key Commitment The resulting commitment obtained by applying the defined commitment scheme to a public key
Recovery Commitment The resulting commitment obtained by applying the defined commitment scheme to the public key of a recovery key pair
Sidetree Node Executable code that implements all the required components, functionality, and rules specified in the Sidetree protocol specification.
Transaction Ledger transaction that anchors a set of Sidetree operations, via a CAS URI for an associated Core Index File.
Anchor String The string anchored to the ledger, composed of the CAS URI to the Core Index File, prefixed with the declared operation count.
Ledger Time The deterministic logical clock variable manifested in the underlying ledger system that can be used as a deterministic chronological reference (e.g. Bitcoin block numbers).
Transaction Number A monotonically increasing number deterministically ordered and assigned to every transaction relative to its position in Ledger Time.
Light Node A node that downloads and processes only Core Index Files and Provisional Index Files on a proactive basis, waiting until resolution time to download and process the Chunk File related to a given DID. This type of configuration enables a node to operate trustlessly while consuming approximately one order of magnitude less storage.

§ Protocol Versioning

The rules and parameters of the Sidetree protocol MAY change in the future, resulting in new versions of the specification. The Sidetree specification and reference implementation follow SemVer 2.0.

Versions of the specification can be found on the Decentralized Identity Foundation’s website at the following version-based paths:

Latest Draft

https://identity.foundation/sidetree/spec/

Specific Versions

https://identity.foundation/sidetree/spec/v<major>.<minor>.<patch>/

Versions of the Sidetree reference implementation are also provided as npm modules and GitHub releases:

{
  "name": "@decentralized-identity/sidetree",
  "version": "<major>.<minor>.<patch>",
  ...

§ Version Segment Definitions

§ New Version Activation

New versions of the protocol, or modifications to parameter values by implementers, MUST be activated at a specified Ledger Time so all nodes can remain in sync by enforcing the same ruleset and parameters beginning at the same logical starting point. All transactions that occur after the specified Ledger Time will adhere to the associated version’s rules and parameters until a newer version of the protocol is defined and implemented at a future Ledger Time.

§ Default Parameters

Each version of the protocol will define a set of protocol rules and parameters with default suggested values. The following are the parameters used by this version of the Sidetree protocol - implementers MAY choose different options than the defaults listed below:

Protocol Parameter Description Suggested Defaults
HASH_ALGORITHM Algorithm for generating hashes of protocol-related values. SHA256
HASH_PROTOCOL Protocol for generating hash representations in Sidetree implementations, using the HASH_ALGORITHM Multihash
DATA_ENCODING_SCHEME Encoding selected for various data (JSON, hashes, etc.) used within an implementation, the output of which MUST be in ASCII format. Base64URL
JSON_CANONICALIZATION_SCHEME The scheme selected for canonicalizing JSON structures used throughout the specification. JCS
KEY_ALGORITHM Asymmetric public key algorithm for signing DID operations. Must be a valid JWK crv. secp256k1
SIGNATURE_ALGORITHM Asymmetric public key signature algorithm. Must be a valid JWS alg. ES256K
CAS_PROTOCOL The CAS network protocol used within an implementation. IPFS
CAS_URI_ALGORITHM Algorithm for generating unique content-bound identifiers for the implementation-selected CAS protocol IPFS CID
COMPRESSION_ALGORITHM File compression algorithm ZIP
REVEAL_VALUE Cryptographic hash of the commitment value. SHA256 Multihash
GENESIS_TIME The point in the target ledger’s transaction history at which Sidetree implementation is first activated (e.g. block number in a blockchain). 630000
MAX_CORE_INDEX_FILE_SIZE Maximum compressed Core Index File size. 1 MB (zipped)
MAX_PROVISIONAL_INDEX_FILE_SIZE Maximum compressed Provisional Index File size. 1 MB (zipped)
MAX_PROOF_FILE_SIZE Maximum compressed Proof File size. 2.5 MB (zipped)
MAX_CHUNK_FILE_SIZE Maximum compressed chunk file size. 10 MB
MAX_MEMORY_DECOMPRESSION_FACTOR Maximum size after decompression. 3x file size
MAX_CAS_URI_LENGTH Maximum length of CAS URIs. 100 bytes
MAX_DELTA_SIZE Maximum canonicalized operation delta buffer size. 1,000 bytes
MAX_OPERATION_COUNT Maximum number of operations per batch. 10,000 ops
MAX_OPERATION_HASH_LENGTH Maximum length of all hashes in CAS URI files. SHA256 Multihash
TODO
  • Put REVEAL_VALUE in places where reveal value is used.
  • All hashes will be base64Url encoded, ensure the spec reads that way.

§ Common Functions

The following is a list of functional procedures that are commonly used across the protocol. These functions are defined once here and referenced throughout the specification, wherever an implementer must invoke them to comply with normative processes.

§ Hashing Process

All data hashed within the bounds of the protocol follow the same procedural steps, and yield a consistently encoded output. Given a data value, the following steps are used to generated a hashed output:

  1. Generate a hash of the data value using the HASH_PROTOCOL with the HASH_ALGORITHM.
  2. Encode the resulting output using the DATA_ENCODING_SCHEME.
  3. Return the encoded hashing output.

Pseudo-code example using current protocol defaults:

let HashingOutput = Base64URL( Multihash(DATA, 'sha2-256') );

§ Commitment Schemes

Commitment schemes are used by the Sidetree protocol in important ways to preserve the integrity of operations and assist in recovery.

§ Public Key Commitment Scheme

The following steps define the commitment scheme for generating a public key commitment from a public key.

  1. Encode the public key into the form of a valid JWK.
  2. Canonicalize the JWK encoded public key using the implementation’s JSON_CANONICALIZATION_SCHEME.
  3. Use the implementation’s HASH_PROTOCOL to the hash the canonicalized public key to generate the REVEAL_VALUE, then hash the resulting hash value again using the implementation’s HASH_PROTOCOL to produce the public key commitment.

Implementers MUST NOT re-use public key JWK payloads across different commitment invocations.

§ Network Topology

The figure below illustrates the three primary components of a Sidetree-based DID overlay network:

  1. The underlying ledger system that serves as the global anchoring and linear sequencing system for DID operations.
  2. The Sidetree nodes themselves, which interact with the ledger system to anchor operations, fetch and replicate data from the CAS network, and process operations in accordance with the protocol deterministic ruleset.
  3. An integrated Content-Addressable Storage (CAS) network layer Sidetree nodes use to distribute and replicate DID operation files.

§ File Structures

The protocol defines the following three file structures, which house DID operation data and are designed to support key functionality to enable light node configurations, minimize permanently retained data, and ensure performant resolution of DIDs.

§ Core Index File

Core Index Files contain Create, Recover, and Deactivate operation values, as well as a CAS URI for the related Provisional Index File (detailed below). As the name suggests, Core Index Files are anchored to the target ledger system via embedding a CAS URI in the ledger’s transactional history.

EXAMPLE
{
  "coreProofFileUri": CAS_URI,
  "provisionalIndexFileUri": CAS_URI,
  "writerLockId": OPTIONAL_LOCKING_VALUE,
  "operations": {
    "create": [
      {
        "suffixData": {
          "type": TYPE_STRING,
          "deltaHash": DELTA_HASH,
          "recoveryCommitment": COMMITMENT_HASH
        }
      },
      {...}
    ],
    "recover": [
      {
        "didSuffix": SUFFIX_STRING,
        "revealValue": MULTIHASH_OF_JWK
      },
      {...}
    ],
    "deactivate": [
      {
        "didSuffix": SUFFIX_STRING,
        "revealValue": MULTIHASH_OF_JWK
      },
      {...}
    ]
  }
}

A valid Core Index File is a JSON document that MUST NOT exceed the MAX_CORE_INDEX_FILE_SIZE. Any unknown properties in this file not defined by this specification or specifically permitted by the implementer, MUST result in an invalidation of the entire file.

The Core Index File JSON document is composed as follows:

  1. The Core Index File MUST contain a provisionalIndexFileUri property if the batch of transactions being anchored contains any Create, Recovery, or Update operations, and its value MUST be a CAS URI for the related Provisional Index File. If the batch of transactions being anchored is only comprised of Deactivate operations, the provisionalIndexFileUri property MUST NOT be present.
  2. The Core Index File MUST contain a coreProofFileUri property if the batch of transactions being anchored contains any Recovery or Deactivate operations, and its value MUST be a CAS URI for the related Core Proof File.
  3. The Core Index File MAY contain a writerLockId if the implementation chooses to implement an mechanism that requires embedded anchoring information, and if present, its value MUST comply with the specifications of the implementation.
  4. If the set of operations to be anchored contain any Create, Recover, or Deactivate operations, the Core Index File MUST contain an operations property, and its value MUST be an object, composed as follows:
    • If there are any Create operations to be included in the Core Index File:
      1. The operations object MUST include a create property, and its value MUST be an array.
      2. For each Create operation to be included in the create array, herein referred to as Core Index File Create Entries, use the following process to compose and include a JSON object for each entry:
      3. The Core Index File MUST NOT include multiple Create operations that produce the same DID Suffix.
    • If there are any Recovery operations to be included in the Core Index File:
      1. The operations object MUST include a recover property, and its value MUST be an array.
      2. For each Recovery operation to be included in the recover array, herein referred to as Core Index File Recovery Entries, use the following process to compose and include entries:
        • The object MUST contain a didSuffix property, and its value MUST be the DID Suffix of the DID the operation pertains to. An Core Index File MUST NOT contain more than one operation of any type with the same DID Suffix.
        • The object MUST contain a revealValue property, and its value MUST be the hashed reveal value of the last update commitment.
    • If there are any Deactivate operations to be included in the Core Index File:
      1. The operations object MUST include a deactivate property, and its value MUST be an array.
      2. For each Deactivate operation to be included in the deactivate array, use the following process to compose and include entries:
        • The object MUST contain a didSuffix property, and its value MUST be the DID Suffix of the DID the operation pertains to. An Core Index File MUST NOT contain more than one operation of any type with the same DID Suffix.
        • The object MUST contain a revealValue property, and its value MUST be the hashed reveal value of the last update commitment.

§ Provisional Index File

Provisional Index Files contain Update operation proving data, as well as CAS URI links to Chunk Files.

EXAMPLE
{
  "provisionalProofFileUri": CAS_URI,
  "chunks": [
    { "chunkFileUri": CAS_URI },
    {...}
  ],
  "operations": {
    "update": [
      {
        "didSuffix": SUFFIX_STRING,
        "revealValue": MULTIHASH_OF_JWK
      },
      {...}
    ]
  }
}

A valid Provisional Index File is a JSON document that MUST NOT exceed the MAX_PROVISIONAL_INDEX_FILE_SIZE. Any unknown properties in this file not defined by this specification or specifically permitted by the implementer, MUST result in an invalidation of the entire file.

The Provisional Index File JSON document is composed as follows:

  1. The Provisional Index File MUST contain a provisionalProofFileUri property if the batch of transactions being anchored contains any Update operations, and its value MUST be a CAS URI for the related Provisional Proof File.
  2. The Provisional Index File MUST contain a chunks property, and its value MUST be an array of Chunk Entries for the related delta data for a given chunk of operations in the batch. Future versions of the protocol will specify a process for separating the operations in a batch into multiple Chunk Entries, but for this version of the protocol there MUST be only one Chunk Entry present in the array. Chunk Entry objects are composed as follows:
    1. The Chunk Entry object MUST contain a chunkFileUri property, and its value MUST be a URI representing the corresponding CAS file entry, generated via the CAS_URI_ALGORITHM.
  3. If there are any operation entries to be included in the Provisional Index File (currently only Update operations), the Provisional Index File MUST include an operations property, and its value MUST be an object composed as follows:
    • If there are any Update entries to be included:
      1. The operations object MUST include an update property, and its value MUST be an array.
      2. For each Update operation to be included in the update array, herein referred to as Provisional Index File Update Entries, use the following process to compose and include entries:
        • The object MUST contain an didSuffix property, and its value MUST be the DID Suffix of the DID the operation pertains to, with a maximum length as specified by the MAX_OPERATION_HASH_LENGTH.
        • The object MUST contain a revealValue property, and its value MUST be the hashed reveal value of the last update commitment, with a maximum length as specified by the MAX_OPERATION_HASH_LENGTH.

§ Core Proof File

Core Proof Files are compressed JSON Documents containing the cryptographic proofs (signatures, hashes, etc.) that form the signature-chained backbone for the state lineages of all DIDs in the system. The cryptographic proofs present in Core Proof Files also link a given operation to its verbose state data, which resides in an related Chunk File.

EXAMPLE
{
  "operations": {
    "recover": [
      {
        "signedData": {
          "protected": {...},
          "payload": {
            "recoveryCommitment": COMMITMENT_HASH,
            "recoveryKey": JWK_OBJECT,
            "deltaHash": DELTA_HASH
          },
          "signature": SIGNATURE_STRING
        }
      },
      {...}
    ],
    "deactivate": [
      {
        "signedData": {
          "protected": {...},
          "payload": {
            "didSuffix": SUFFIX_STRING,
            "recoveryKey": JWK_OBJECT
          },
          "signature": SIGNATURE_STRING
        }
      },
      {...}
    ]
  }
}

Any unknown properties in this file not defined by this specification or specifically permitted by the implementer, MUST result in an invalidation of the entire file.

In this version of the protocol, Core Proof Files are constructed as follows:

  1. The Core Proof File MUST include an operations property, and its value MUST be an object containing cryptographic proof entries for any Recovery and Deactivate operations to be included in a batch. Include the Proof Entries as follows:

§ Provisional Proof File

Provisional Proof Files are compressed JSON Documents containing the cryptographic proofs (signatures, hashes, etc.) for all the (eventually) prunable DID operations in the system. The cryptographic proofs present in Provisional Proof Files also link a given operation to its verbose state data, which resides in an related Chunk File.

EXAMPLE
{
  "operations": {
    "update": [
      {
        "signedData": {
          "protected": {...},
          "payload": {
            "updateKey": JWK_OBJECT,
            "deltaHash": DELTA_HASH
          },
          "signature": SIGNATURE_STRING
        }
      },
      {...}
    ]
  }
}

Any unknown properties in this file not defined by this specification or specifically permitted by the implementer, MUST result in an invalidation of the entire file.

In this version of the protocol, Provisional Proof Files are constructed as follows:

  1. The Provisional Proof File MUST include an operations property, and its value MUST be an object containing cryptographic proof entries for any Recovery and Deactivate operations to be included in a batch. Include the Proof Entries as follows:

§ Chunk Files

Chunk Files are JSON Documents, compressed via the COMPRESSION_ALGORITHM, that contain Sidetree Operation source data, which are composed of delta-based CRDT entries that modify the state of a Sidetree identifier’s DID Document.

For this version of the protocol, there will only exist a single Chunk File that contains all the state modifying data for all operations in the included set. Future versions of the protocol will separate the total set of included operations into multiple chunks, each with their own Chunk File.

EXAMPLE
{
  "deltas": [
       
    {
      "patches": PATCH_ARRAY,
      "updateCommitment": COMMITMENT_HASH
    },
    ...
  ]
}

Any unknown properties in this file not defined by this specification or specifically permitted by the implementer, MUST result in an invalidation of the entire file.

In this version of the protocol, Chunk Files are constructed as follows:

  1. The Chunk File MUST include a deltas property, and its value MUST be an array containing Chunk File Delta Entry objects.

  2. Each Chunk File Delta Entry MUST be a JSON object serialized via the JSON_CANONICALIZATION_SCHEME, assembled as follows:

    1. The object MUST contain a patches property, and its value MUST be an array of DID State Patches.
    2. The payload MUST contain an updateCommitment property, and its value MUST be the next Update Commitment generated during the operation process associated with the type of operation being performed.
  3. Each Chunk File Delta Entry MUST be appended to the deltas array as follows, in this order:

    1. If any Create operations were present in the associated Core Index File, append all Create Operation Delta Objects in the same index order as their matching Core Index File Create Entry.
    2. If any Recovery operations were present in the associated Core Index File, append all Recovery Operation Delta Objects in the same index order as their matching Core Index File Recovery Entry.
    3. If any Update operations were present in the associated Provisional Index File, append all Update Operation Delta Objects in the same index order as their matching Provisional Index File Update Entry.

§ DID URI Composition

DID Methods based on the Sidetree protocol all share the same identifier format. The unique identifier segment of a Sidetree-based DID, known as the DID Suffix, is derived based on the initial state of the identifier’s DID Document contents. The DID Suffix is cryptographically bound to the initial PKI state of the DID, which means Sidetree DIDs are self-certifying. As a result, a person or entity who creates a Sidetree-based DID knows their unique identifier at the moment of generation, and it is cryptographic secured for instant use (for more on the instant use capabilities of Sidetree DIDs, see Unpublished DID Resolution).

To generate the Short-Form DID URI of a Sidetree DID, use the Hashing Process to generate a hash of the canonicalized Create Operation Suffix Data Object. The following is an example of a resulting colon (:) separated DID URI composed of the URI scheme (did:), Method identifier (sidetree:), and unique identifier string (EiBJz4...):

Format of Short-form DID URI:

did:METHOD:<did-suffix>

Example of Short-Form DID URI:

did:sidetree:EiDahaOGH-liLLdDtTxEAdc8i-cfCz-WUcQdRJheMVNn3A

§ Long-Form DID URIs

In many DID Methods, there is a period of time (which may be indefinite) between the generation of a DID and the DID operation being anchored, propagated, and processed in the underlying distributed ledger/storage network. In order to account for this, Sidetree introduces an equivalent variant of Sidetree-based DIDs that is self-certifying and self-resolving, known as the Long-Form DID URI. The Long-Form DID URI variant of Sidetree-based DIDs enables DIDs to be immediately resolvable after generation by including the DID’s initial state data within the Long-Form DID URI itself. Sidetree Long-Form DID URIs are the Short-Form DID URI with an additional colon-separated (:) segment appended to the end. The value of this final URI segment is a canonicalized JSON data payload composed of the Create Operation Suffix data and the Create Operation Delta data, encoded via the implementation’s DATA_ENCODING_SCHEME.

Long-form DID JSON data payload:

{
  "delta": {
    "patches": [
      {
        "action": "replace",
        "document": {
          "publicKeys": [
            {
              "id": "anySigningKeyId",
              "publicKeyJwk": {
                "crv": "secp256k1",
                "kty": "EC",
                "x": "H61vqAm_-TC3OrFSqPrEfSfg422NR8QHPqr0mLx64DM",
                "y": "s0WnWY87JriBjbyoY3FdUmifK7JJRLR65GtPthXeyuc"
              },
              "purposes": [
                "auth"
              ],
              "type": "EcdsaSecp256k1VerificationKey2019"
            }
          ],
          "services": [
            {
              "id": "anyServiceEndpointId",
              "type": "anyType",
              "serviceEndpoint": "http://any.endpoint"
            }
          ]
        }
      }
    ],
    "updateCommitment": "EiBMWE2JFaFipPdthcFiQek-SXTMi5IWIFXAN8hKFCyLJw"
  },
  "suffixData": {
    "deltaHash": "EiBP6gAOxx3YOL8PZPZG3medFgdqWSDayVX3u1W2f-IPEQ",
    "recoveryCommitment": "EiBg8oqvU0Zq_H5BoqmWf0IrhetQ91wXc5fDPpIjB9wW5w"
  }
}

Format of Long-Form DID URI:

did:METHOD:<did-suffix>:<long-form-suffix-data>

Example of Long-Form DID URI:

did:sidetree:EiDahaOGH-liLLdDtTxEAdc8i-cfCz-WUcQdRJheMVNn3A:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljX2tleXMiOlt7ImlkIjoiYW55U2lnbmluZ0tleUlkIiwiandrIjp7ImNydiI6InNlY3AyNTZrMSIsImt0eSI6IkVDIiwieCI6Ikg2MXZxQW1fLVRDM09yRlNxUHJFZlNmZzQyMk5SOFFIUHFyMG1MeDY0RE0iLCJ5IjoiczBXbldZODdKcmlCamJ5b1kzRmRVbWlmSzdKSlJMUjY1R3RQdGhYZXl1YyJ9LCJwdXJwb3NlIjpbImF1dGgiXSwidHlwZSI6IkVjZHNhU2VjcDI1NmsxVmVyaWZpY2F0aW9uS2V5MjAxOSJ9XSwic2VydmljZV9lbmRwb2ludHMiOlt7ImVuZHBvaW50IjoiaHR0cDovL2FueS5lbmRwb2ludCIsImlkIjoiYW55U2VydmljZUVuZHBvaW50SWQiLCJ0eXBlIjoiYW55VHlwZSJ9XX19XSwidXBkYXRlX2NvbW1pdG1lbnQiOiJFaUJNV0UySkZhRmlwUGR0aGNGaVFlay1TWFRNaTVJV0lGWEFOOGhLRkN5TEp3In0sInN1ZmZpeF9kYXRhIjp7ImRlbHRhX2hhc2giOiJFaUJQNmdBT3h4M1lPTDhQWlBaRzNtZWRGZ2RxV1NEYXlWWDN1MVcyZi1JUEVRIiwicmVjb3ZlcnlfY29tbWl0bWVudCI6IkVpQmc4b3F2VTBacV9INUJvcW1XZjBJcmhldFE5MXdYYzVmRFBwSWpCOXdXNXcifX0

The Long-Form DID URI variant of Sidetree-based DIDs supports the following features and usage patterns:

§ JSON Web Signatures

Sidetree relies on JSON Web Signatures for authentication and integrity protection of DID Operations, accept for Create, with contains key material and is self certifying.

§ Signing

In addition to RFC7515, the following additional requirements MUST be observed by Sidetree Method implementeers.

  1. kid MAY be present in the protected header.
  2. alg MUST be present in the protected header, its value MUST NOT be none.
  3. No additional members may be present in the protected header.

Here is an example of a decoded JWS header:

{
  "kid": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
  "alg": "EdDSA"
}
WARNING

It is recommended that kid be a DID URL. If it is not, method implementers might need to rely on additional context to uniquely identify the correct verificationMethod.

§ Verifying

Regardless of which verification relationship a verificationMethod is associated with, the process of verifying a JWS linked to a DID is the same.

The JWS header is parsed and a kid is extracted.

  1. Iterate the verificationMethods, until a verificationMethod with id equal to kid is found.
  2. Convert the discovered verificationMethod to JWK if necessary.
  3. Perform JWS Verification using the JWK.

§ Operation Verification

Sidetree operations are considered valid when the JWS can be verified with the correct key pair designated for the type of operation being invoked (i.e. update, recover, deactivate).

An Update Operation MUST be signed by the currently valid Update Key Pair.

A Recover Operation MUST by signed by the currently valid Recovery Key Pair.

A Deactivate Operation MUST by signed by the currently valid Recovery Key Pair.

WARNING

Signatures on operations may be valid, but operations may be deemed invalid for other reasons (e.g. malformed delta payload).

WARNING

It is not recommended to reuse verificationMethods for multiple verification relationships.

§ DID Operations

Sidetree-based DIDs support a variety of DID operations, all of which require the DID owner to generate specific data values and cryptographic material. The sections below describe how to perform each type of operation, and how those operations are represented in the CAS-replicated files that are anchored to the underlying ledger system.

While virtually all DID owners will engage User Agent applications on their local devices to perform these operations, most will not generate the anchoring transactions on the underlying ledger. Instead, most users will likely send the anchoring-related operation values they generate to external nodes for anchoring. This is relatively safe, because operations require signatures that an external node cannot forge. The only attack available to a rogue node operator is to not anchor the operations a DID owner sends them. However, the DID owner can detect this (via a scan of subsequent blocks) and send their operation to a different node or do it themselves, if they so desire.

It is strongly advised that DID owners and User Agents (e.g. wallet apps) retain their DID operations and operation-anchoring files. Doing so is helpful in cases where users, or their User Agent, need to quickly access the operations and operation-anchoring files, or a user wishes to individually persist their operation and operation-anchoring files on the CAS network for even greater independent availability assurance.

NOTE

This specification does not define an API for sending public DID operation values to third-party Sidetree nodes for external anchoring, as that is an elective activity has no bearing on the technical workings of the protocol, its capabilities, or its security guarantees.

WARNING

Operations other than Create contain a compact JWS. Dereferencing of key material used to verify the JWS is a DID Method specific concern. Some methods may rely of the DID Document data model, others may rely on an internal data model. Some methods may rely on kid of the form did:example:123#fingerprint, others may not include a kid in the JWS, or its value may be arbitrary. Support for specific alg fields is also DID Method specific. Implementers are cautioned to choose support for specific alg values carefully.

§ Create

Use the following process to generate a Sidetree-based DID:

  1. Generate a key pair using the defined KEY_ALGORITHM, let this be known as the Update Key Pair.
  2. Generate a public key commitment using the defined public key commitment scheme and public key of the generated Update Key Pair, let this resulting commitment be known as the update commitment.
  3. Generate a canonicalized representation of the following object using the implementation’s JSON_CANONICALIZATION_SCHEME, herein referred to as the Create Operation Delta Object:
    {
      "patches": [ PATCH_1, PATCH_2, ... ],
      "updateCommitment": COMMITMENT_HASH
    }
    
    • The object MUST contain a patches property, and its value MUST be a JSON array of DID State Patches.
    • The object MUST contain an updateCommitment property, and its value MUST be the update commitment as generated in step 2.
  4. Generate a key pair using the defined KEY_ALGORITHM, let this be known as the recovery key pair, where the public key of this pair is used for generating the recovery commitment, and the private key for use in the next recovery operation.
  5. Generate a public key commitment using the defined public key commitment scheme and public key of the generated recovery key pair, let this resulting commitment be known as the recovery commitment.
  6. Generate a canonicalized representation of the following object using the implementation’s JSON_CANONICALIZATION_SCHEME, herein referred to as the Create Operation Suffix Data Object:
    {
      "type": TYPE_STRING,
      "deltaHash": DELTA_HASH,
      "recoveryCommitment": COMMITMENT_HASH
    }
    
    • The object MAY contain a type property, and if present, its value MUST be a type string, of a length and composition defined by the implementation, that signifies the type of entity a DID represents. The value MUST NOT be anything that represents humans, groups of humans, or any human-identifying classification - an implementation SHALL NOT override this directive, and any attempt to do so shall render the implementation non-conformant to this specification.
    • The object MUST contain a deltaHash property, and its value MUST be a hash of the canonicalized Create Operation Delta Object (detailed above), generated via the HASH_PROTOCOL.
    • The object MUST contain a recoveryCommitment property, and its value MUST be the recovery commitment as generated in step 2.
NOTE

Implementations MAY choose to define additional properties for inclusion in the Create Operation Suffix Data Object, but the presence of any properties beyond the standard properties or implementation-defined properties ARE NOT permitted.

§ Update

The following process must be used to update the state a Sidetree-based DID:

  1. Retrieve the Update Reveal Value that matches the previously anchored Update Commitment.
  2. Generate a canonicalized representation of the following object using the implementation’s JSON_CANONICALIZATION_SCHEME, herein referred to as the Update Operation Delta Object, composed as follows:
    {
      "patches": [ PATCH_1, PATCH_2, ... ],
      "updateCommitment": COMMITMENT_HASH
    }
    
    • The object MUST contain a patches property, and its value MUST be an array of DID State Patches.
    • The object MUST contain a updateCommitment property, and its value MUST be a new Update Commitment, the value of which will be revealed for the next Update operation.
  3. Generate an IETF RFC 7515 compliant compact JWS representation of the following object, herein referred to as the Update Operation Signed Data Object, with a signature that validates against a currently active update key, and contains the following payload values:
    {
      "protected": {...},
      "payload": {
        "updateKey": JWK_OBJECT,
        "deltaHash": DELTA_HASH
      },
      "signature": SIGNATURE_STRING
    }
    
    • The JWS payload object MUST include a updateKey property, and its value MUST be the IETF RFC 7517 compliant JWK representation matching the previous Update Commitment.
    • The JWS payload object MUST contain a deltaHash property, and its value MUST be a hash of the canonicalized Update Operation Delta Object, generated via the HASH_PROTOCOL, with a maximum length as specified by the MAX_OPERATION_HASH_LENGTH.

§ Recover

Use the following process to recover a Sidetree-based DID:

  1. Retrieve the Recovery Key that matches the previously anchored Recovery Commitment. This value will be used in constructing an Core Index File Recovery Entry for the DID being recovered.
  2. Generate a new recovery key pair, which MUST NOT be the same key used in any previous operations, via the KEY_ALGORITHM, retaining the Next Recovery Public Key for use in generating the next Recovery Commitment, and the private key for use in the next Recovery operation.
  3. Create a Recovery Commitment using the Hashing Process to generate a hash value from the canonicalized IETF RFC 7517 JWK representation (using the implementation’s JSON_CANONICALIZATION_SCHEME) of the Next Recovery Public Key, and retain the hash value for inclusion in an Core Index File.
  4. Generate a new Update Key Pair, which SHOULD NOT be the same key used in any previous operations, via the KEY_ALGORITHM, retaining the Next Update Public Key for use in generating the next Update Commitment, and the private key for use in the next Update operation.
  5. Create an Update Commitment using the Hashing Process to generate a hash value from the canonicalized IETF RFC 7517 JWK representation (using the implementation’s JSON_CANONICALIZATION_SCHEME) of the Next Update Public Key, and retain the hash value for inclusion in the Recovery Operation Delta Object (as described below).
  6. Generate and retain a COMMITMENT_VALUE, in adherence with the Commitment Schemes directives, for use in the next Update operation, herein referred to as the Update Reveal Value.
  7. Generate an Update Commitment using the Hashing Process, in adherence with the Commitment Schemes directives, to generate a hash of the Update Reveal Value, and retain the resulting hash value for inclusion in an Core Index File.
  8. Generate a canonicalized representation of the following object using the implementation’s JSON_CANONICALIZATION_SCHEME, herein referred to as the Recovery Operation Delta Object, composed as follows:
    {
      "patches": [ PATCH_1, PATCH_2, ... ],
      "updateCommitment": COMMITMENT_HASH
    }
    
    • The object MUST contain a patches property, and its value MUST be an array of DID State Patches.
    • The object MUST contain a updateCommitment property, and its value MUST be the Update Commitment, as described above.
  9. Generate an IETF RFC 7515 compliant compact JWS representation of the following object, herein referred to as the Recovery Operation Signed Data Object, with a signature that validates against a currently active recovery key, and contains the following payload values:
    {
      "protected": {...},
      "payload": {
        "recoveryCommitment": COMMITMENT_HASH,
        "recoveryKey": JWK_OBJECT,
        "deltaHash": DELTA_HASH
      },
      "signature": SIGNATURE_STRING
    }
    

§ Deactivate

The following process must be used to deactivate a Sidetree-based DID:

  1. Retrieve the Recovery Reveal Value that matches the previously anchored Recovery Commitment.
  2. Generate a IETF RFC 7515 compliant compact JWS object, herein referred to as the Deactivate Operation Signed Data Object, with a signature that validates against the currently active recovery key, and contains the following payload values:
    {
      "protected": {...},
      "payload": {
        "didSuffix": SUFFIX_STRING,
        "recoveryKey": JWK_OBJECT
      },
      "signature": SIGNATURE_STRING
    }
    
    • The JWS payload object MUST contain a didSuffix property, and its value MUST be the DID Suffix of the DID the operation pertains to, with a maximum length as specified by the MAX_OPERATION_HASH_LENGTH.
    • The JWS payload object MUST include a recoveryKey property, and its value MUST be the IETF RFC 7517 JWK representation matching the previous Recovery Commitment.

§ DID State Patches

Sidetree defines a general format for patching DID State, called Patch Actions, for describing mutations of a DID’s metadata state. Sidetree further defines a standard set of Patch Actions (below) implementers MAY use to facilitate patching within their implementations. Support of the standard set of Patch Actions defined herein IS NOT required, but implementers MUST use the Patch Action format for defining patch mechanisms within their implementation. The general Patch Action format is defined as follows:

{
  "action": "add-public-keys",
  ...
}

{
  "action": "-custom-action",
  ...
}
  1. Patch Actions MUST be represented as JSON objects.
  2. Patch Action objects MUST include an action property, and its value SHOULD be one of the standard Patch Action types listed in below, or, if the implementer chooses to create a custom Patch Action, a kebab-case string (dash-delimited lowercase words) with a leading dash, to indicate a custom Patch Action, for example: -custom-action.
    • add-public-keys
    • remove-public-keys
    • add-services
    • remove-services
    • ietf-json-patch

§ Standard Patch Actions

The following set of standard Patch Actions are specified to help align on a common set of Patch Actions that provide a predictable usage patter across Sidetree-based DID Method implementations.

§ add-public-keys

EXAMPLE
{
  "action": "add-public-keys",
  "publicKeys": [
    {
      "id": "key1",
      "purposes": ["authentication"],
      "type": "EcdsaSecp256k1VerificationKey2019",
      "publicKeyJwk": {...}
    }
  ]
}

The add-public-keys Patch Action describes the addition of cryptographic keys associated with a given DID. For any part of an add-public-keys Patch Action to be applied to the DID’s state, all specified conditions MUST be met for all properties and values, else the patch MUST be discarded in its entirety. In the case a public key entry already exists for the given id specified within an add-public-keys Patch Action, the implementation MUST overwrite the existing entry entirely with the incoming patch. To construct an add-public-keys patch, compose an object as follows:

  1. The object MUST include an action property, and its value MUST be add-public-keys.
  2. The object MUST include a publicKeys property, and its value MUST be an array.
  3. Each key being added MUST be represented by an entry in the publicKeys array, and each entry must be an object composed as follows:
    1. The object MUST include an id property, and its value MUST be a string with no more than fifty (50) Base64URL encoded characters. If the value is not of the correct type or exceeds the specified length, the entire Patch Action MUST be discarded, without any of it being used to modify the DID’s state.
    2. The object MUST include a type property, and its value SHOULD be the type string of a registered Cryptographic Suite that supports JWK representations - for example:
      • EcdsaSecp256k1VerificationKey2019
      • JsonWebKey2020
    3. The object MUST include a publicKeyJwk property, and its value MUST be a public key expressed as a IETF RFC 7517 compliant JWK representation for a KEY_ALGORITHM supported by the implementation. The key represented by the JWK object MUST be projected into the verificationMethod array of the DID Document upon resolution. If the value is not a compliant JWK representation, the entire Patch Action MUST be discarded, without any of it being used to modify the DID’s state.
    4. The object MAY include a purposes property, and if included, its value MUST be an array of one or more of the strings listed below. If the value is not of the correct type or contains any string not listed below, the entire Patch Action MUST be discarded, without any of it being used to modify the DID’s state.
      • authentication: a reference to the key’s id MUST be included in the authentication array of the resolved DID Document.
      • keyAgreement: a reference to the key’s id MUST be included in the keyAgreement array of the resolved DID Document.
      • assertionMethod: a reference to the key’s id MUST be included in the assertionMethod array of the resolved DID Document.
      • capabilityDelegation: a reference to the key’s id MUST be included in the capabilityDelegation array of the resolved DID Document.
      • capabilityInvocation: a reference to the key’s id MUST be included in the capabilityInvocation array of the resolved DID Document.

§ remove-public-keys

EXAMPLE
{
  "action": "remove-public-keys",
  "ids": ["key1", "key2"]
}

The remove-public-keys Patch Action describes the removal of cryptographic keys associated with a given DID. For any part of an remove-public-keys Patch Action to be applied to the DID’s state, all specified conditions MUST be met for all properties and values, else the patch MUST be discarded in its entirety. In the case there exists no public key entry for an id specified within a remove-public-keys Patch Action, the implementation SHALL perform no action and treat application of the delete operation as a success. To construct a remove-public-keys Patch Action, compose an object as follows:

  1. The object MUST include an action property, and its value MUST be remove-public-keys.
  2. The object MUST include a ids property, and its value MUST be an array of key IDs that correspond with keys presently associated with the DID that are to be removed. If the value is not of the correct type or includes a string value that is not associated with a key in the document, the entire Patch Action MUST be discarded, without any of it being used to modify the DID’s state.

§ add-services

EXAMPLE
{
  "action": "add-services",
  "services": [
    {
      "id": "sds",
      "type": "SecureDataStore",
      "serviceEndpoint": "http://hub.my-personal-server.com"
    },
    {
      "id": "did-config",
      "type": "LinkedDomains",
      "serviceEndpoint": {
        "origins": ["https://foo.com", "https://bar.com"]
      }
    }
  ]
}

The add-services Patch Action describes the addition of Service Endpoints to a DID’s state. For any part of an add-services Patch Action to be applied to the DID’s state, all specified conditions MUST be met for all properties and values, else the patch MUST be discarded in its entirety. In the case a service entry already exists for the given id specified within an add-services Patch Action, the implementation MUST overwrite the existing entry entirely with the incoming patch. To construct an add-services patch, compose an object as follows:

  1. The object MUST include an action property, and its value MUST be add-services.
  2. The object MUST include a services property, and its value MUST be an array. If the value is not of the correct type, the entire Patch Action MUST be discarded, without any of it being used to modify the DID’s state.
  3. Each service being added MUST be represented by an entry in the services array, and each entry must be an object composed as follows:
    1. The object MUST include an id property, and its value MUST be a string with a length of no more than fifty (50) Base64URL encoded characters. If the value is not of the correct type or exceeds the specified length, the entire Patch Action MUST be discarded, without any of it being used to modify the DID’s state.
    2. The object MUST include a type property, and its value MUST be a string with a length of no more than thirty (30) Base64URL encoded characters. If the value is not a string or exceeds the specified length, the entire Patch Action MUST be discarded, without any of it being used to modify the DID’s state.
    3. The object MUST include a serviceEndpoint property, and its value MUST be either a valid URI string (including a scheme segment: i.e. http://, git://) or a JSON object with properties that describe the Service Endpoint further. If the values do not adhere to these constraints, the entire Patch Action MUST be discarded, without any of it being used to modify the DID’s state.

§ remove-services

EXAMPLE
{
  "action": "remove-services",
  "ids": ["sds1", "sds2"]
}

The remove-services Patch Action describes the removal of cryptographic keys associated with a given DID. For any part of an remove-services Patch Action to be applied to the DID’s state, all specified conditions MUST be met for all properties and values, else the patch MUST be discarded in its entirety. In the case there exists no service entry for an id specified within a remove-public-keys Patch Action, the implementation SHALL perform no action and treat application of the delete operation as a success. To construct a remove-services Patch Action, compose an object as follows:

  1. The object MUST include an action property, and its value MUST be remove-services.
  2. The object MUST include a ids property, and its value MUST be an array of Service Endpoint IDs that correspond with Service Endpoints presently associated with the DID that are to be removed.

§ replace

EXAMPLE
{
  "action": "replace",
  "document": {
    "publicKeys": [
      {
        "id": "key2",
        "purposes": ["authentication"],
        "type": "EcdsaSecp256k1VerificationKey2019",
        "publicKeyJwk": {...}
      }
    ],
    "services": [
      {
        "id": "sds3",
        "type": "SecureDataStore",
        "serviceEndpoint": "http://hub.my-personal-server.com"
      }
    ]
  }
}

The replace Patch Action acts as a total state reset that replaces a DID’s current PKI metadata state with the state provided. The replace Patch Action enables the declaration of public keys and service endpoints using the same schema formats as the add-public-keys and add-services Patch Actions. To construct a replace patch, compose an object as follows:

  1. The object MUST include an action property, and its value MUST be replace.
  2. The object MUST include a document property, and its value MUST be an object, which may contain the following properties:
    • The object MAY include a publicKeys property, and if present, its value MUST be an array of public key entries that follow the same schema and requirements as the public key entries from the add-public-keys Patch Action
    • The object MAY include a services property, and if present, its value MUST be an array of service endpoint entries that follow the same schema and requirements as the service endpoint entries from the add-services Patch Action.

§ ietf-json-patch

The ietf-json-patch Patch Action describes a mechanism for modifying a DID’s state using IETF JSON Patch. To construct a ietf-json-patch Patch Action, compose an object as follows:

  1. The object MUST include an action property, and its value MUST be ietf-json-patch.
  2. The object MUST include a patches property, and its value MUST be an array of IETF JSON Patch operation objects.

If ietf-json-patch is used to add or remove from a proof purpose collection, such as operations, recovery or assertionMethod, per the DID Core spec, each collection element MUST have a unique id property, or be a unique string identifier.

See Operation Verification for more details on how operations are verified.

EXAMPLE
{
  "action": "ietf-json-patch",
  "patches": [
    { "op": "add", ... },
    { "op": "remove", ... },
    { "op": "replace", ... },
    { "op": "move", ... },
    { "op": "copy", ... }
  ]
}
EXAMPLE
{
  "action": "ietf-json-patch",
  "patches": [
    {
      "op": "replace",
      "path": "/service",
      "value": [
          {
              "id": "did:example:123#edv",
              "type": "EncryptedDataVault",
              "serviceEndpoint": "https://edv.example.com/",
          }
      ]
    }
  ]
}
WARNING

Without careful validation, use of ietf-json-patch may result in unrecoverable states, similar to “Deactivated”.

WARNING

Use of ietf-json-patch may harm an implmentation’s ability to perform validation on operations at ingestion time, which could impact performance negatively.

§ Transaction & Operation Processing

§ Transaction Anchoring

Once an Core Index File, Provisional Index File, and associated Chunk Files have been assembled for a given set of operations, a reference to the Core Index File must be embedded within the target ledger to enter the set of operations into the Sidetree implementation’s global state. The following process:

  1. Generate a transaction for the underlying ledger
  2. Generate and include the following value, herein referred to as the Anchor String, within the transaction:
    1. Generate a numerical string ('732') that represents the total number of operations present in the Core Index File and Provisional Index File, herein referred to as the Operation Count.
    2. Using the CAS_URI_ALGORITHM, generate a CID for the Core Index File, herein referred to as the Core Index File CAS URI.
    3. Join the Operation Count and Core Index File CAS URI with a . as follows:
      "10000" + "." + "QmWd5PH6vyRH5kMdzZRPBnf952dbR4av3Bd7B2wBqMaAcf"
      
    4. Embed the Anchor String in the transaction such that it can be located and parsed by any party that traverses the history of the target ledger.
  3. If the implementation implements a per-op fee, ensure the transaction includes the fee amount required for the number of operations being anchored.
  4. Encode the transaction with any other data or values required for inclusion by the target ledger, and broadcast it.

§ CAS File Propagation

To ensure other nodes of the implementation can retrieve the operation files required to ingest the included operations and update the states of the DIDs it contains, the implementer must ensure that the files associated with a given set of operations being anchored are available to peers seeking to request and replicate them across the CAS storage layer. Use the following procedure for propagating transaction-anchored CAS files:

  1. If the underlying ledger is subject to an anchoring inclusion delay (e.g. the interval between blocks in a blockchain), implementers SHOULD wait until they receive a confirmation of inclusion (whatever that means for the target ledger) before exposing/propagating the operation files across the CAS network. (more about the reason for this in the note below)
  2. After confirmation is received, implementers SHOULD use the most effective means of proactive propagation that the CAS_PROTOCOL supports.
  3. A Sidetree-based implementation node that anchors operations should not assume other nodes on the CAS network will indefinitely retain and propagate the files for a given set of operations they anchor. A node SHOULD retain and propagate any files related to the operations it anchors.
NOTE

Most ledgers feature some delay between the broadcast of a transaction and the recorded inclusion of the transaction in the ledger’s history. Because operation data included in the CAS files contains revealed commitment values for operations, propagating those files before confirmation of transaction inclusion exposes revealed commitment values to external entities who may download them prior to inclusion in the ledger. This means an attacker who learns of the revealed commitment value can craft invalid transactions that could be included before the legitimate operation the user is attempting to anchor. While this has no affect on proof-of-control security for a DID, an observing node would have to check the signatures of fraudulent transactions before the legitimate transaction is found, which could result in slower resolution processing for the target DID.

§ Transaction Processing

Regardless of the ledger system an implementer chooses, the implementer MUST be able to sequence Sidetree-specific transactions within it in a deterministic order, such that any observer can derive the same order if the same logic is applied. The implementer MUST, either at the native transaction level or by some means of logical evaluation, assign Sidetree-specific transactions a Transaction Number. Transaction Numbers MUST be assigned to all Sidetree-specific transactions present in the underlying ledger after GENESIS_TIME, regardless of whether or not they are valid.

  1. An implementer MUST develop implementation-specific logic that enables deterministic ordering and iteration of all protocol-related transactions in the underlying ledger, such that all operators of the implementation process them in the same order.
  2. Starting at GENESIS_TIME, begin iterating transactions using the implementation-specific logic.
  3. For each transaction found during iteration that is determined to be a protocol-related transaction, process the transaction as follows:
    1. Assign the transaction a Transaction Number.
    2. If the implementation supports enforcement value locking, and the transaction is encoded in accordance with the implementation’s value locking format, skip the remaining steps and process the transaction as described in the Proof of Fee section on Value Locking.
    3. The Anchor String MUST be formatted correctly - if it is not, discard the transaction and continue iteration.
    4. If the implementation DOES NOT support enforcement of a per-operation fee, skip this step. If enforcement of a per-operation fee is supported, ensure the transaction fee meets the per-operation fee requirements for inclusion - if it DOES NOT, discard the transaction and continue iteration.
    5. If the implementation DOES NOT support enforcement of Value Locking, skip this step. If enforcement of Value Locking is supported, ensure the transaction’s fee meets the Value Locking requirements for inclusion - if it does not, discard the transaction and continue iteration.
    6. Parse the Anchor String to derive the Operation Count and Core Index File CAS URI.
    7. Use the CAS_PROTOCOL to fetch the Core Index File using the Core Index File CAS URI. If the file cannot be located, retain a reference that signifies the need to retry fetch of the file. If the file successfully retrieved, proceed to the next section on how to process an Core Index File

§ Core Index File Processing

This sequence of rules and processing steps must be followed to correctly process an Core Index File:

  1. The Core Index File MUST NOT exceed the MAX_CORE_INDEX_FILE_SIZE - if it does, cease processing, discard the file data, and retain a reference that the file is to be ignored.
  2. Decompress the Core Index File in accordance with the implementation’s COMPRESSION_ALGORITHM, within the memory allocation limit specified for decompression in accordance with the implementation-defined MAX_MEMORY_DECOMPRESSION_FACTOR.
  3. The Core Index File MUST validate against the protocol-defined Core Index File schema and construction rules - if it DOES NOT, cease processing, discard the file data, and retain a reference that the whole batch of anchored operations and all its files are to be ignored.
    • While this rule is articulated in the Core Index File section of the specification, it should be emphasized to ensure accurate processing: an Core Index File MUST NOT include multiple operations in the operations section of the Core Index File for the same DID Suffix - if any duplicates are found, cease processing, discard the file data, and retain a reference that the whole batch of anchored operations and all its files are to be ignored.
  4. If processing of rules 1 and 2 above resulted in successful validation of the Core Index File, initiate retrieval of the Provisional Index File via the CAS_PROTOCOL using the provisionalIndexFileUri property’s CAS URI value, if the provisionalIndexFileUri property is present. This is only a SUGGESTED point at which to begin retrieval of the Provisional Index File, not a blocking procedural step, so you may continue with processing before retrieval of the Provisional Index File is complete.
  5. Iterate the Core Index File Create Entries, and for each entry, process as follows:
    1. Derive the DID Suffix from the values present in the entry.
    2. Ensure the DID Suffix of the operation entry has not been included in another valid operation that was previously processed in the scope of this Core Index File.
    3. Create an entry for the operation within the Operation Storage area relative to the DID Suffix.
  6. Iterate the Core Index File Recovery Entries, and for each entry, process as follows:
    1. Ensure the DID Suffix of the operation entry has not been included in another valid operation that was previously processed in the scope of this Core Index File.
    2. Create an entry for the operation within the Operation Storage area relative to the DID Suffix.
  7. Iterate the Core Index File Deactivate Entries, and for each entry, process as follows:
    1. Ensure the DID Suffix of the operation entry has not been included in another valid operation that was previously processed in the scope of this Core Index File.
    2. Create an entry for the operation within the Operation Storage area relative to the DID Suffix.

§ Provisional Index File Processing

This sequence of rules and processing steps must be followed to correctly process a Provisional Index File:

  1. The Provisional Index File MUST NOT exceed the MAX_PROVISIONAL_INDEX_FILE_SIZE - if it does, cease processing, discard the file data, and retain a reference that the file is to be ignored.
  2. Decompress the Provisional Index File in accordance with the implementation’s COMPRESSION_ALGORITHM, within the memory allocation limit specified for decompression in accordance with the implementation-defined MAX_MEMORY_DECOMPRESSION_FACTOR.
  3. The Provisional Index File MUST validate against the protocol-defined Provisional Index File schema and construction rules - if it DOES NOT, cease processing, discard the file data, and retain a reference that all Provisional-type files and their operations are to be ignored.
  4. If processing of rules 1 and 2 above resulted in successful validation of the Provisional Index File, begin retrieval of the Chunk Files by iterating the chunks array and using the CAS_PROTOCOL to fetch each entry’s chunkFileUri (a CAS URI based on the CAS_URI_ALGORITHM). This is only a SUGGESTED point at which to begin retrieval of the Chunk Files, not a blocking procedural step, so you may continue with processing before retrieval of the Chunk Files is complete.
  5. Iterate the Provisional Index File Update Entries, and for each entry, process as follows:
    1. Ensure the DID Suffix of the operation entry has not been included in another valid operation that was previously processed in the scope of the Provisional Index File or its parent Core Index File.
    2. Create an entry for the operation within the Operation Storage area relative to the DID Suffix.
  6. If the node is in a Light Node configuration, retain a reference to the Chunk Files relative to the DIDs in the anchored batch for just-in-time fetch of the Chunk Files during DID resolution.

§ Core Proof File Processing

This sequence of rules and processing steps must be followed to correctly process an Core Proof File:

  1. The Core Proof File MUST NOT exceed the MAX_PROOF_FILE_SIZE - if it does, cease processing, discard the file data, and retain a reference that the whole batch of anchored operations and all its files are to be ignored.
  2. Decompress the Core Proof File in accordance with the implementation’s COMPRESSION_ALGORITHM, within the memory allocation limit specified for decompression in accordance with the implementation-defined MAX_MEMORY_DECOMPRESSION_FACTOR.
  3. The Core Proof File MUST validate against the protocol-defined Core Proof File schema and construction rules - if it DOES NOT, cease processing, discard the file data, and retain a reference that the whole batch of anchored operations and all its files are to be ignored.
  4. Iterate any Core Proof File Recovery Entries and Core Proof File Deactivate Entries that may be present, and for each entry, process as follows:
    1. Ensure an operation for the related DID has not been included in another valid operation that was previously processed in the scope of the Core Proof File or its parent Core Index File.
    2. Create an entry, or associate with an existing entry, the proof payload within the Operation Storage area relative to the DID Suffix.

§ Provisional Proof File Processing

This sequence of rules and processing steps must be followed to correctly process an Provisional Proof File:

  1. The Provisional Proof File MUST NOT exceed the MAX_PROOF_FILE_SIZE - if it does, cease processing, discard the file data, and retain a reference that all Provisional-type files and their operations are to be ignored.
  2. Decompress the Provisional Proof File in accordance with the implementation’s COMPRESSION_ALGORITHM, within the memory allocation limit specified for decompression in accordance with the implementation-defined MAX_MEMORY_DECOMPRESSION_FACTOR.
  3. The Provisional Proof File MUST validate against the protocol-defined Provisional Proof File schema and construction rules - if it DOES NOT, cease processing, discard the file data, and retain a reference that all Provisional-type files and their operations are to be ignored.
  4. Iterate any Provisional Proof File Update Entries that may be present, and for each entry, process as follows:
    1. Ensure an operation for the related DID has not been included in another valid operation that was previously processed in the scope of the Provisional Proof File or its parent Core Index File. If another previous, valid operation was already processed in the scope of the Provisional Proof File or Core Index File for the same DID, do not process the operation and move to the next operation in the array.
    2. Create an entry, or associate with an existing entry, the proof payload within the Operation Storage area relative to the DID Suffix.

§ Chunk File Processing

This sequence of rules and processing steps must be followed to correctly process a Chunk File chunk:

  1. The Chunk File chunk MUST NOT exceed the MAX_CHUNK_FILE_SIZE - if it does, cease processing, discard the file data, and retain a reference that the file is to be ignored.
  2. Decompress the Chunk File in accordance with the implementation’s COMPRESSION_ALGORITHM, within the memory allocation limit specified for decompression in accordance with the implementation-defined MAX_MEMORY_DECOMPRESSION_FACTOR.
  3. The Chunk File MUST validate against the protocol-defined Chunk File schema and construction rules - if it DOES NOT, cease processing, discard the file data, and retain a reference that the file is to be ignored.
  4. The canonicalized buffer of each Chunk File delta entry must not exceed the MAX_DELTA_SIZE. If any deltas entries exceed the maximum size cease processing, discard the file data, and retain a reference that the file is to be ignored.
  5. In order to process Chunk File Delta Entries in relation to the DIDs they are bound to, they must be mapped back to the Create, Recovery, and Update operation entries present in the Core Index File and Provisional Index File. To create this mapping, concatenate the Core Index File Create Entries, Core Index File Recovery Entries, Provisional Index File Update Entries into a single array, in that order, herein referred to as the Operation Delta Mapping Array. Pseudo-code example:
    let mappingArray = [].concat(CREATE_ENTRIES, RECOVERY_ENTRIES, UPDATE_ENTRIES);
    
  6. With the Operation Delta Mapping Array assembled, iterate the Chunk File Delta Entries from 0 index forward, processing each Chunk File Delta Entry as follows:
    1. Identify the operation entry from the Operation Delta Mapping Array at the same index as the current iteration and determine its DID Suffix (for Core Index File Create Entries, you will need to compute the DID Suffix). This is the DID the current iteration element maps to.
    2. Store the current Chunk File Delta Entry relative to its operation entry in the persistent storage area designated for the related DID Suffix.
NOTE

The assembly and processing of Chunk Files will change in a future update to the protocol to accommodate the introduction of multiple chunk files. The current protocol version is designed around one Chunk File, but the scaffolding is present to move to multiple Chunk Files as development progresses.

§ Proof of Fee

Sidetree implementers MAY choose to implement protective mechanisms designed to strengthen a Sidetree network against low-cost spurious operations. These mechanisms are primarily designed for open, permissionless implementations utilizing public blockchains that feature native crypto-economic systems.

§ Base Fee Variable

All of the mechanisms described in this section are based on the same underlying numeric value, known as the Base Fee Variable, that is calculated by processing a collection of native variables from the target ledger with a set of deterministic functions. The Base Fee Variable is used in two primary ways: 1) to set a minimum required native transaction fee that must be paid relative to the number of DID operations a writer seeks to anchor with the transaction, and 2) the fee basis that is used to deterministically set a economic locking amount based on the size of operational batches a writer wants to access.

To calculate the Base Fee Variable, every node MUST run the following pseudorandom transaction selection routine across the transaction history of the target ledger, which will produce the same selected set of transactions across all nodes:

§ Per-Operation Fee

§ Value Locking

§ Resolution

§ Operation Compilation

TODO

Distinguish between Not Found and No DID Doc states, with the former reflected in a 404 response. Clean up API doc.

  1. Upon invocation of resolution, retrieve all observed operations for the DID Unique Suffix of the DID URI being resolved.

  2. If record of the DID being published has been observed, proceed to Step 3. If there is no observed record of the DID being published, skip all remaining Operation Compilation steps and process the DID as follows:

    1. If the DID URI is a Short-Form DID URI, abort resolution and return Unresolvable.
    2. If the DID URI is a Long-Form DID URI, process as follows:
      1. Isolate the last colon-separated (:) segment of the DID URI.
      2. Using the implementation’s DATA_ENCODING_SCHEME, decode the value. If the values fail to properly decode in accordance with the implementation’s DATA_ENCODING_SCHEME, abort resolution and return Unresolvable.
      3. JSON parse the resulting value, apply the canonicalization algorithm, reencode the resulting value and ensure it is the same as the initial value from Step 1. If the values do not match, abort resolution and return Unresolvable.
      4. Use the Hashing Process to generate a hash of the canonicalized Create Operation Suffix Data Object and ensure it matches the DID Unique Suffix, if the values do not match, abort resolution and return Unresolvable.
      5. Validate the resulting object in accordance with the Create Operation Suffix Data Object schema. If the value is found to be a valid Create Operation Suffix Data Object. If the value fails validation, abort resolution and return Unresolvable.
      6. Validate the Create Operation Delta Object (which is present in a Chunk File Delta Entry for published, anchored DIDs). If the value is found to be a valid Create Operation Delta Object. If the value fails validation, abort resolution and return Unresolvable.
      7. If all steps above are successful, internally flag the state of the DID as Unpublished and continue to Create operation processing as if the values decoded and validated in the steps above represent the only operation associated with the DID.
  3. Constructing the Operation Hash Map: generate a Create Operation Pool, which will house references to any Create operations processed in the steps below, and begin iterating through the operations present in the DID’s Operation Storage area as follows:

    1. Type-specific operation evaluation:

    2. Ensure a key exists in the Operation Hash Map corresponding to the Map Hash, and that the corresponding value is an array. If no property exists for the Map Hash, create one and let its value be an array.

    3. Insert the entry into the array of the Map Hash at its proper position in ascending Ledger Time order.

  4. Create operation processing: If no operations are present in the Create Operation Pool, cease resolution of the DID and declare the DID Unresolvable. If the Create Operation Pool contains operation entries, process them as follows:

    1. Store the value of the recoveryCommitment property from the entry’s Create Operation Suffix Data Object as the Next Recovery Commitment for use in processing the next Recovery operation.
    2. Retrieve the Chunk File Delta Entry corresponding to the operation and proceed to Step 3. If the Chunk File Delta Entry is not present because the associated Chunk File has not yet been retrieved and processed (i.e. node is a Light Node implementation, file was previously unavailable, etc.), perform the following steps:
      1. Using the CAS_PROTOCOL, fetch the Chunk File using the associated Chunk File URI. If the file cannot be retrieved, proceed to recovery and deactivate operation processing.
      2. Validate the Chunk File using the Chunk File Processing procedure. If the Chunk File is valid. If the file is invalid, proceed to recovery and deactivate operation processing.
    3. Validate the Chunk File Delta Entry. If the Chunk File Delta Entry is invalid, proceed to Recovery and deactivate operation processing.
    4. Generate a hash of the canonicalized Chunk File Delta Entry via the HASH_PROTOCOL and ensure the hash matches the value of the Create Operation Suffix Data Object deltaHash property. If the values are exactly equal, proceed, if they are not, proceed to recovery and deactivate operation processing.
    5. Store the updateCommitment value of the Chunk File Delta Entry as the Next Update Commitment for use in processing the next Update operation.
    6. Begin iterating the patches array in the Chunk File Delta Entry, and for each DID State Patch entry, perform the following steps:
      1. Validate the entry in accordance any requirements imposed by the Patch Action type indicated by the action value of the entry. If the entry is valid, proceed, if the entry fails validation, reverse all modifications to the DID’s state and proceed to recovery and deactivate operation processing.
      2. Apply the patch as directed by the Patch Action type specified by the action property. If any part of the patch fails or produces an error, reverse all modifications to the DID’s state and proceed to recovery and deactivate operation processing.
  5. Recovery and deactivate operation processing: when Create operations have been processed, process any Recovery and Deactivate operations that may exist in the Operation Hash Map via the iteration procedure below. If no Recovery and Deactivate operations are present, proceed to update operation processing.

    1. If a property is present in the Operation Hash Map that matches the Next Recovery Commitment exactly, process its array of operation entries using the following steps. If no property exists in the Operation Hash Map that matches the Next Recovery Commitment exactly, exit recovery and deactivate operation processing and advance to update operation processing.
    2. Iterate the array of operation entries forward from 0-index using the process enumerated below until all valid entries are found and processed:
    3. Once all Recovery and Deactivate operations have been processed, if the Next Update Commitment value is present, proceed to update operation processing. If the Next Update Commitment value is not present or the DID is in a Deactivated state, proceed to compiled state processing.
  6. Update operation processing: if the DID is marked as Deactivated or the Next Update Commitment value is not present, skip Update processing and proceed to compiled state processing. If the Next Update Commitment value is present and no Deactivate operations were successfully processed during recovery and deactivate operation processing, process any Update operations that may exist in the Operation Hash Map using the following processing loop:

    1. If a property is present in the Operation Hash Map that matches the Next Update Commitment exactly, process its array of operation entries using the following steps. If no property exists in the Operation Hash Map that matches the Next Update Commitment exactly, exit update operation processing and advance to compiled state processing.

    2. Iterate the array of operation entries forward from 0-index using the process enumerated below until all valid entries are found and processed:

      1. Retrieve the operation’s Provisional Proof File Update Entry and Chunk File Delta Entry from the pre-processed Provisional Proof File and Chunk File associated with the operation and proceed to validation of the entries, or, if the Provisional Proof File and Chunk File have yet to be retrieved and processed (e.g. the resolving node is in a Light Node configuration), perform the following steps:
        1. Using the CAS_PROTOCOL, fetch the Provisional Proof File and Chunk File using the associated Provisional Proof File URI and Chunk File URI.
        2. If the Provisional Proof File is unable to be retrieved, skip the entry and advance to the next operation.
        3. Validate the Provisional Proof File. If the file is valid, proceed, if the file is invalid, skip the entry and advance to the next operation.
      2. Using the revealed updateKey JWK value, validate the Update Operation Signed Data Object signature. If the signature is valid, proceed, if the signature is invalid, skip the entry and iterate forward to the next entry.
      3. Validate the Chunk File and Chunk File Delta Entry. If the Chunk File and Chunk File Delta Entry are valid, proceed, if the entry is invalid, skip the entry and iterate forward to the next entry.
      4. Generate a hash of the canonicalized Chunk File Delta Entry via the HASH_PROTOCOL and ensure the hash equals the value of the Update Operation Signed Data Object deltaHash property. If the values are exactly equal, proceed, if they are not, skip the entry and iterate forward to the next entry.
      5. Store the updateCommitment value of the Chunk File Delta Entry as the Next Update Commitment for use in processing the next Update operation.
      6. Begin iterating the patches array in the Chunk File Delta Entry, and for each DID State Patch entry, perform the following steps:
        1. Apply the patch as directed by the Patch Action type specified by the action property. If any of the patches produce an error, reverse all of this operation’s patch modifications to the DID Document state, while retaining the successful rotation to the next Next Update Commitment value, and iterate forward to the next operation.
  7. Compiled state processing: After the DID’s operations have been evaluated in the compilation steps above, the implementation MUST use the DID’s compiled state to generate a valid DID Document in accordance with the W3C Decentralized Identifiers specification.

  8. If the DID Document is being rendered in the JSON-LD representation variant, the implementer SHOULD add an @base entry to the document’s @context, and set the @base value to the id of the resolved DID. This ensures relative path values in the output DID Document are correctly projected into id-related strings by JSON-LD parsers.

  9. Once a valid DID Document state has been generated, proceed to the DID Resolver Output process, if you intend to output the resolved DID Document in accordance with the Decentralized Identifier Resolution specification.

§ DID Resolver Output

The following describes how to construct Decentralized Identifier Resolution-compliant Resolution Result based on a DID resolved via the Operation Compilation process described in the section above.

If the compiled DID was not determined to be Unresolvable, as defined in the Operation Compilation process above, proceed as follows:

  1. Generate a JSON object for the Resolution Result, structured in accordance with the Decentralized Identifier Resolution specification.
  2. Set the didDocument property of the Resolution Result object to the resolved DID Document generated via the Operation Compilation process.
  3. The Resolution Result object MUST include a didDocumentMetadata property, and its value is an object composed of the following values:
    • canonicalId - If canonical representation of the resolved DID exists, the presence of canonical DID representation within the didDocumentMetadata is determined as follows:
      1. Presence and value of the canonicalId property:
        • If the DID being resolved is a Long-Form DID representation and is unpublished, the canonicalId property MUST NOT be included in the didDocumentMetadata object.
        • If the DID being resolved is a Long-Form DID representation and is published, the canonicalId property MUST be included in the didDocumentMetadata object, and its value MUST be the Short-Form DID representation.
        • If the DID being resolved is a Short-Form DID representation and is published, the canonicalId property MUST be included in the didDocumentMetadata object, and its value MUST be the Short-Form DID representation.
      2. Inclusion of the canonical DID representation in the equivalentId array:
        • If under any of the cases above there is a canonical DID representation included for the canonicalId property, the canonical DID representation MUST also be included in the equivalentId array. See below for details on the equivalentId property.
    • equivalentId - If equivalent representations of the resolved DID exist, the presence of equivalent DID representations within the didDocumentMetadata is determined as follows:
      • If the DID being resolved is a Long-Form DID representation, the equivalentId property MUST be included in the didDocumentMetadata object, and its array value MUST include the Short-Form DID representation.
    • method - Its value MUST be an object composed of the following values:
      1. The object MUST include a published property with a boolean value. If the compiled DID state is flagged as Unpublished and/or Unresolvable (per the Operation Compilation process), the published property MUST be set to false, otherwise, set the value to true.
      2. The object MUST include an updateCommitment property, and its value MUST be the updateCommitment hash value expected to be fulfilled in with the next updateKey revealed in the next Update operation.
      3. The object MUST include an recoveryCommitment property, and its value MUST be the recoveryCommitment hash value expected to be fulfilled in with the next recoveryKey revealed in the next Recovery operation.

§ Unresolvable DIDs

If a DID is found to be unresolvable, per the logic defined under the Operation Compilation section, a Sidetree-compliant node SHOULD return the appropriate error code over the transport of the resolution request. For HTTP, you MUST return the responses and status codes defined by the Sidetree API specification section on Resolution.

§ Late Publishing

Sidetree is an eventually strongly consistent, conflict-free state resolution system based on cryptographically signed, delta-based DID operations, which derives its deterministic order of operations from the position of operation entries in a decentralized ledger’s immutable linear chronology. Unlike the native tokens of a strongly immutable blockchain (e.g. Bitcoin), DIDs represent unique identifiers that are generally intended to be non-transferable. As such, the Sidetree protocol provides no technical mechanism for exchanging ownership of DIDs with ‘double-spend’ assurance, the way one might do with a fungible cryptocurrency token.

For Sidetree, non-transferability manifests in a distinct way: a DID owner is ultimately in control of their past, present, and future state changes, and can expose state change operations as they choose across the lineage of their DID’s operational history. DID owners can create forks within their own DID state history, and nothing forces them to expose DID state operations they anchor. A DID operation anchored in the past, at Time X, can be exposed to sometime in the future, at Time Y. This means Sidetree nodes could become aware of past operations that create a change in the lineage of a DID - this is known as Late Publishing of a DID operation. However, due to the non-transferability of DIDs, this condition is isolated to each DID’s own state lineage, and resolved by Sidetree’s deterministic ruleset, which guarantees only one fork of a DID’s state history can ever be valid. To better understand this, consider the following diagram that illustrates a DID owner, Alice, creating forks by creating and anchoring operations in the past that she does not expose to the network:

graph TB 0 --> 1 1 --> 2a 1 --> 2b 2b --> 3

As you can see above, Alice has created a fork by anchoring the divergent operations 2a and 2b. Let us assume Alice refrains from publishing the CAS files that other Sidetree nodes would detect to locate and replicate the date for operation 2a, and further, assume Alice continues creating more operation history stemming from operation 2b. Whenever Alice exposes the DID operation data for 2a, other Sidetree nodes will need to decide which operation between 2a and 2b is the ‘right’ operation. The Sidetree protocol includes a strict rule that resolves this conflict, and any variation of it: the earliest operation in Ledger Time always wins. If operation 2a precedes operation 2b in Ledger Time, whenever she decides to publish operation 2a, all other Sidetree nodes would process the operation and immediately deem operation 2a to be the valid, correct operational fork. This remains true even if Alice continues building operational history stemming from operation 2b any amount of time into the future.

With this example of late publishing in mind, the most important aspect to remember is that DID owners decide what the PKI state of their DIDs should be, and remain in control of that state independent of the shape of their DID operational history. The net takeaway is that regardless of how a DID owner decides to update the state of their DID, the decision over what that state is remains entirely their choice.

§ Method Versioning

It is RECOMMENDED that Sidetree based DID Methods implement the following versioning structures to support development, testing, staging and production network deployments.

We define a network suffix as follows for a given DID Method:

did:<method>:<network>:<didUniqueSuffix>

If no network suffix is provided, it is assumed that the “mainnet” or “production” network is to be used… for example, these DIDs should resolve to the same DID Document:

did:elem:mainnet:EiD0x0JeWXQbVIpBpyeyF5FDdZN1U7enAfHnd13Qk_CYpQ
did:elem:EiD0x0JeWXQbVIpBpyeyF5FDdZN1U7enAfHnd13Qk_CYpQ

An ION DID on the Bitcoin Testnet3 testnet is defined as follows:

did:ion:testnet3:EiD0x0JeWXQbVIpBpyeyF5FDdZN1U7enAfHnd13Qk_CYpQ

An ELEM DID on the Ethereum Ropsten testnet is defined as follows:

did:elem:ropsten:EiD0x0JeWXQbVIpBpyeyF5FDdZN1U7enAfHnd13Qk_CYpQ

WARNING

Implementers should be aware that if the underlying decentralized ledger system were to fork, the identifiers will also be forked. In this case, the a new identifier must be created either through an indication at the network layer or with a completely new method name to identify the decentralized identifiers of the forked network.

§ Context

Per the DID Core Spec an @context MAY be used to represent a DID Document as Linked Data.

If an @context is present, any properties not defined in DID Core, MUST be defined in this context, or in a DID Method specific one.

For example:

{
    "@context": [
        "https://www.w3.org/ns/did/v1", 
        "https://identity.foundation/sidetree/context-v1.jsonld",
        "https://example.com/method/specific.jsonld"
    ]
}

§ recovery

A verificationMethod used to support DID Document Recover Operation verification.

For Example:

{
    "@context": [
        "https://www.w3.org/ns/did/v1", 
        "https://identity.foundation/sidetree/context-v1.jsonld"
    ],
    "recovery": [{
      "id": "did:example:123#JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "publicKeyJwk": {
        "crv": "secp256k1",
        "kid": "JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
        "kty": "EC",
        "x": "dWCvM4fTdeM0KmloF57zxtBPXTOythHPMm1HCLrdd3A",
        "y": "36uMVGM7hnw-N6GnjFcihWE3SkrhMLzzLCdPMXPEXlA"
      }
    }]
}

§ operation

A verificationMethod used to support verification of DID Document Operations: Create, Update, Deactivate.

For Example:

{
    "@context": [
        "https://www.w3.org/ns/did/v1", 
        "https://identity.foundation/sidetree/context-v1.jsonld"
    ],
    "operation": [{
      "id": "did:example:123#JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "publicKeyJwk": {
        "crv": "secp256k1",
        "kid": "JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
        "kty": "EC",
        "x": "dWCvM4fTdeM0KmloF57zxtBPXTOythHPMm1HCLrdd3A",
        "y": "36uMVGM7hnw-N6GnjFcihWE3SkrhMLzzLCdPMXPEXlA"
      }
    }]
}

§ usage

Deprecated. DO NOT USE.

Was introduced to support key ops pre sidetree protocol spec v1.

§ publicKeyJwk

A public key in JWK format. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. Read RFC7517.

Example:

{
  "id": "did:example:123#JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
  "type": "EcdsaSecp256k1VerificationKey2019",
  "publicKeyJwk": {
    "crv": "secp256k1",
    "kid": "JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
    "kty": "EC",
    "x": "dWCvM4fTdeM0KmloF57zxtBPXTOythHPMm1HCLrdd3A",
    "y": "36uMVGM7hnw-N6GnjFcihWE3SkrhMLzzLCdPMXPEXlA"
  }
}

§ publicKeyHex

A hex encoded compressed public key.

Example:

{
  "id": "did:example:123#JUvpllMEYUZ2joO59UNui_XYDqxVqiFLLAJ8klWuPBw",
  "type": "EcdsaSecp256k1VerificationKey2019",
  "publicKeyHex": "027560af3387d375e3342a6968179ef3c6d04f5d33b2b611cf326d4708badd7770"
}
Table of Contents