Syntax and Interpretation

The full Tezos DID scheme is defined by the following ABNF:

tezos-did   = "did:tz:" [ network ":" ] address
network     = 1*(lower-char / digit)
address     = prefix 33*33base58-char
prefix      = "tz1" / "tz2" / "tz3" / "KT1"
base58-char = "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" /
              "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "J" / "K" /
              "L" / "M" / "N" / "P" / "Q" / "R" / "S" / "T" / "U" / "V" /
              "W" / "X" / "Y" / "Z" /
              "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" / "j" /
              "k" / "m" / "n" / "o" / "p" / "q" / "r" / "s" / "t" / "u" /
              "v" / "w" / "x" / "y" / "z"
lower-char  = %x61-7A  ; a-z
digit       = %x30-39  ; 0-9
      

All Tezos DIDs use base58 encoding for the address rule. base58 is an encoding scheme similar to base64, first used by Bitcoin, disallowing characters that may be misinterpreted by the human eye, specifically O (uppercase 'o'), 0 (the digit zero), I (uppercase 'i'), and l (lowercase 'L').

The network rule MAY be used to indicate which Tezos instance the DID references. If it is not present, then the instance is assumed to be mainnet. Other known test networks include dalphanet, carthage, and labnet. The number of test networks is expected to grow.

Background on Tezos Addresses

Tezos addresses can exist as either accounts or smart contracts. Tezos accounts are generated from public keys. The three character prefix, tz1, tz2, or tz3, indicate which signature system and elliptic curve are used. The prefix of KT1 denotes a Tezos smart contract, which do not have an implied public-private key pair. (Note that this specification does not support the prefix btz1 used for blinded accounts.) Tezos supports three public key signature systems for its accounts, each with a different elliptic curve:

Examples

Tiered DID Resolution

DID resolution occurs sequentially across the following ordered layers of data sources, known as resolution layers:

1. Implied DID Document.
2. Corresponding on-chain smart contract known as a DID Manager.
3. Corresponding off-chain DID document signed updates.

DID resolvers must move sequentially through all resolution layers to incrementally build a DID document, and they fail upon the first encountered inconsistency, producing an error result and no DID document. Success can only be achieved after processing all resolution layers.

Implied DID Document

For Tezos account address-based DIDs with addresses starting with tz1, tz2, or tz3, DID document resolution is possible without committing any Tezos blockchain transactions to preserve privacy and save costs. Because all mainnet blockchain transactions are public, immutable, and fee-based, it is recommended to exercise extreme caution and store the absolute minimum amount of information on-chain.

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8",
  "authentication": [{
    "id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8#blockchainAccountId",
    "type": "Ed25519PublicKeyBLAKE2BDigestSize20Base58CheckEncoded2020",
    "controller": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV",
    "blockchainAccountId": "[email protected]:mainnet"
  }]
}
    

DID Manager Smart Contract

DID Managers are smart contracts on the Tezos blockchain that implement TZIP-19, with Michelson annotations satisfying the following abstract function interface:

rotateAuthentication :: (VerificationMethod, RotationSignature) => ()
getAuthentication :: () => VerificationMethod
rotateService :: (Service, RotationSignature) => ()
getService :: () => Service
    

rotateAuthentication updates the verification method used for authentication, such as a public key or public key digest along with its verification method type. It may be called by anyone, but requires a valid RotationSignature. This function is used by the update operation to modify the authentication property in a DID document.

rotateService updates the single service endpoint, which is a URI with a service endpoint type. It may be called by anyone, but requires a valid RotationSignature. This function is used by the update operation to modify the service property in a DID document.

The RotationSignature input parameter contains the signature of the data produced by concatenating the byte representations of the current value's message digest, next value, current chain identifier, and current rotation count. Including the chain identifier prevents impersonating the controller on a different chain. The current rotation count is defined as the sum total of successfully executed calls to both rotateAuthentication and rotateService to date. For example, if each function were successfully executed exactly once, the current rotation count would be two.

getAuthentication returns the verification method for authentication. This result is used to populate the authentication section in the DID document during resolution.

getService returns the single service endpoint. This result is used to populate the service section in the DID document during resolution.

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8",
  "authentication": [{
    "id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8#blockchainAccountId",
    "type": "Ed25519PublicKeyBLAKE2BDigestSize20Base58CheckEncoded2020",
    "controller": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV",
    "blockchainAccountId": "[email protected]:mainnet"
  }],
  "service": [{
    "id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8#discovery",
    "type": "TezosDiscoveryService",
    "serviceEndpoint": "tezos-storage://KT1QDFEu8JijYbsJqzoXq7mKvfaQQamHD1kX/listing"
  }]
}

Off-Chain DID Document Updates

Off-chain updates to the DID document are possible by specifying one or more signed patches in the DID resolution input metadata property named updates containing an array. If updates are present, they must all be of the same type.

The two allowed types for updates are (1) unsigned Tezos transactions with valid RotationSignature parameter values that would correctly update the DID Manager if signed and cleared in a block and (2) signed-ietf-json-patch restricted to changes possible through the DID Manager abstract function interface. These two types of updates have different privacy and security implications.

Create (Register)

Tiered creation across DID resolution layers:

1. DID document is implied
2. Deploy DID manager smart contract
3. Create off-chain DID document updates

Read (Resolve)

Tiered resolution across DID resolution layers:

1. Imply DID document from address
2. Lookup and apply on-chain DID manager
3. Apply any off-chain DID document updates

Update (Replace)

Tiered replace across DID resolution layers:

Delete (Revoke)

Security Considerations

Privacy Considerations

The DID method specification's Privacy Considerations section MUST discuss any subsection of section 5 of [RFC6973] that could apply in a method-specific manner. The subsections to consider are: surveillance, stored data compromise, unsolicited traffic, misattribution, correlation, identification, secondary use, disclosure, exclusion.