Architecture
The objective for the Tezos DID Method is to utilize Tezos accounts and smart contract addresses in a coherent manner to manage DID documents while adhering to this document's Design Criteria, including security, privacy, and simplicity. For simplicity, Tezos DIDs only support a single active public key and service endpoint at a time. In this section, we describe major architectural patterns utilized in its DID operations.
Tiered DID Resolution
DID resolution occurs sequentially across the following ordered layers of data sources, known as resolution layers:
- Implied DID Document.
- Corresponding on-chain smart contract known as a DID Manager.
- 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.
The absence of a data source is not considered an inconsistency,
and the resolver simply disregards the absent data source, moving on to
the next data source in the sequence. An example of an inconsistency is
a signed JSON patch that fails an integrity check or uses an unexpected
key.
A Tezos address may represent either an account, beginning with
Smart contracts do not come with implied key pairs, so their implied
DID document is absent. Furthermore, they cannot have off-chain signed
updates without deployment, as currently, smart contract addresses
cannot be known prior to deployment. Therefore, smart contract
address-based DIDs must always be deployed prior to use.
Absence of data sources
Tezos addresses: accounts vs. smart contracts
tz1, tz2, or tz3, or a smart
contract, beginning with KT1. When they populate the
address ABNF rule in DIDs, they are known as account
address-based DIDs and smart contract address-based DIDs, respectively.
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.
Deriving DID Documents
At this resolution layer, DID document is derived by implying
values from a Tezos account address-based DID, such as
did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8,
which matches the account and optional
network rules in the DID Scheme ABNF. This value is then
used within the DID document authentication section as
the blockchainAccountId
as specified in the Security Vocab.
A DID resolver could take the example DID and generate the following
DID document without incorporating any data from blockchain
transactions:
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8",
"authentication": [{
"id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8#blockchainAccountId",
"type": "Ed25519PublicKeyBLAKE2BDigestSize20Base58CheckEncoded2021",
"controller": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8",
"blockchainAccountId": "tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8@tezos:mainnet"
}]
}
However, the DID resolver must then check the live specified Tezos blockchain instance for a DID Manager, which is defined in the next section.
Note: undefined LD-Proof signature suites ("type") for tz1/tz2/tz3
This is related to the example entries found for
blockchainAccountId.
We need to define the type for use with Ed25519-based
tz1 Tezos accounts. We should also consider inclusion of
tezosAddress for the secp256k1/ECDSA-based
tz2 into the
EcdsaSecp256k1RecoverySignature LD-Proof signature suite.
We still need to figure out how the P-256-based tz3 fits
into existing signature suites, if any.
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.
Identifying the DID Manager
The process for reliably identifying the corresponding DID Manager will
differ between account address-based DIDs and smart contract
address-based DIDs. In both cases, the address is first extracted from
the DID using the address ABNF rule.
Account address-based DIDs: In the case of an account address, the DID Manager smart contract is defined as the first smart contract that (1) is deployed by the account and (2) implements TZIP-19. The resolver must exhaustively query for any matching smart contract by either by (recommended) using a Tezos transaction indexer or scanning all Tezos transactions directly.
Smart contract address-based DIDs: In the case of a smart contract address, the smart contract itself is the DID Manager, and must therefore implement TZIP-19. If it does not implement TZIP-19, then resolution will fail.
Deriving DID Documents
The verification method used for authentication is produced by calling
the getAuthentication smart contract function. No input
parameters are required. The single service endpoint and its type is
retrieved by calling the getService smart contract
function. These values are the only smart contract-sourced data used
for Tezos DID resolution, and are substituted into a valid DID
document.
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8",
"authentication": [{
"id": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8#blockchainAccountId",
"type": "Ed25519PublicKeyBLAKE2BDigestSize20Base58CheckEncoded2021",
"controller": "did:tz:mainnet:tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8",
"blockchainAccountId": "tz1TzrmTBSuiVHV2VfMnGRMYvTEPCP42oSM8@tezos: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.