ADR-001 - HackMD

--- title: ADR-001 id: adr-001 displayed_sidebar: resourcesSidebar --- - **Author(s):** [Prad Nukala](https://github.com/prnk28) - **Last Updated:** June 21, 2022 - **Status:** Integrated - **Deployment:** `integrate/adr-001` # ADR-001: DID Method Specification [![hackmd-github-sync-badge](https://hackmd.io/iomfscGXR1ycI_67NrLvMw/badge)](https://hackmd.io/iomfscGXR1ycI_67NrLvMw) ## Abstract Sonr is a privacy focused blockchain built to reinvent how we handle identity and data transmission. Sonr also supports DID operations. DIDs are created and stored in the Sonr Node, and they are used with verifiable credentials. This specification describes how DIDs are managed on the Sonr. ## DID Method Name The name-string is `snr`. A DID must begin with the prefix: `did:snr` in lowercase. ## DID Method Specific Identifier ``` sonr-did = "did:snr:" idstring idstring = 32*44(base58) base58 = "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" ``` The `idstring` is a base58-encoded SHA-256 hash of a Secp256k1 public key, otherwise known as the Sonr Blockchain Wallet address. This means that DIDs are case-sensitive, even though the prefix is always lower-case. The Sonr Highway CLI provides a tool for generating the Secp256k1 key-pair either randomly or from a BIP44 mnemonic provided by the user. **Example**: ``` did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm ``` ### Relationship between DIDs and Sonr wallet accounts Sonr Blockchain Wallets are integrated within every Motor powered application. The Sonr Motor is a light peer-to-peer node embedded within every decentralized application built with the Highway SDK. From here on, a Sonr Blockchain Wallet Account will be referenced as a motor. ## DID Document Format (JSON-LD) ```json { "@context": "https://www.w3.org/ns/did/v1", // All connected Motor Nodes for a Sonr User "controller":[ "did:snr:123", ], // Address to Multisig wallet for all user motor nodes "id": "did:snr:abc", // Registered alias (.snr) names "alsoKnownAs": [ "test.snr", "example.snr" ], // User authenticated application credentials get stored as assertionMethod "assertionMethod": [...], // Connected Motors webauthn credentials get stored as verificationMethod "verificationMethod": [ { // Set to Motor Nodes Wallet Address "controller": "did:snr:123", // Id of Key set to unique value and operating system/architecture "id": "did:snr:123#ios-arm64-1", // JWK generated from WebAuthN Credential "publicKeyJwk": { "crv": "P-256", "kty": "EC", "x": "UANQ8pgvJT33JbrnwMiu1L1JCGQFOEm1ThaNAJcFrWA=", "y": "UWm6q5n1iXyeCJLMGDInN40bkkKr8KkoTWDqJBZQXRo=" }, "type": "JsonWebKey2020" } ], // User public facing services "service": [{ // Inbound/Outbound Mailbox - Sonr Core Service "id":"snr:123#mailbox", "type": "EncryptedDataVault", // MultiAddr of hosted IPFS node "serviceEndpoint": "/ip4/159.313.1.45/tcp/57665/peer/123/snr/test" }] } ``` `controller` : Currently, the controller represents the set of DIDs associated with the top-level document for a User. In order for the controller to be valid an accompanying entry must be present in the `verificationMethod` and must conform to the ****[FIDO2 WebAuthn](https://fidoalliance.org/fido2/fido2-web-authentication-webauthn/)**** specification. `id` : The ID of the DIDDocument is created from the `multisignature` key address returned from the set of all `PublicKey` ’s present with matching controllers. The `id` is regenerated on every instance a controller is added or removed from the DIDDocument. `alsoKnownAs` : This property is utilized to provide resolvable aliases to the associated DIDDocument. Users purchase a name alias which is suffixed by, .snr, a resolvable TLD on the [Handshake Network](https://handshake.org/). Motor nodes are packaged with the lightweight [HNS Resolver](https://github.com/handshake-org/hnsd). `assertionMethod` : This property is currently being used to store authenticated application credentials. When Users first access an application, they utilize the account DID in order to authenticate their session. `verificationMethod` : This property is utilized for storing the individual Motor `WebAuthn` credentials. This mechanism is put into place to associate users by individual devices opposed to strictly an account based structure. # CRUD Operations ## Create ``` (POST): /v1/registry/create/whois - Owner:string - DidDocument:[]byte - WhoisType:Enum{ WhoisType_APP | WhoisType_USER } ``` This method takes a DIDDocument as an input along with the did of the account calling the TX, and verifies the signature. If successful, and there is no existing WhoIs created for the user or application. Parameters include: Signature, DIDDocument, address, and WhoIsType. The resulting response is a `WhoIs` object containing the following payload body: ``` json { "document": { "@context": "<https://www.w3.org/ns/did/v1>", "id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "verificationMethod": [ { "id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1", "type": "Secp256k1VerificationKey2018", "controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "publicKeyBase58": "dBuN4i7dqwCLzSX7GHBLsfUoXw5RmWQ3DwQ9Ee4bfh5Y" } ], "authentication": [ "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1" ] }, "sequence": "0" } ``` # CRUD Operations *All transactions TX will incur a gas fee whenever read and writes are made to the store. `fees = gas * gas-prices`* ## Create ``` (POST): /v1/registry/create/whois - Owner:string - DidDocument:[]byte - WhoisType:Enum{ WhoisType_APP | WhoisType_USER } ``` This method takes a DIDDocument as an input along with the DID of the account calling the TX and verifies the signature. If successful, and there is no existing WhoIs created for the user or application. Parameters include: Signature, DIDDocument, address, and WhoIsType. ## Read A Sonr DID Document can be looked up with three possible queries. ``` // Find a DIDDocument by ID (GET): /v1/registry/query/whois/:did - DID:string // Find a DIDDocument with the matching controller (GET): /v1/registry/query/whois/controller/:did - DID:string // Find a DIDDocument with the matching alias (GET): /v1/registry/query/whois/alias/:name - Name:string ``` If the DID exists (not deactivated yet), the result is a `WhoIs` object: ```json { "document": { "@context": "<https://www.w3.org/ns/did/v1>", "id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "verificationMethod": [ { "id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1", "type": "Secp256k1VerificationKey2018", "controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "publicKeyBase58": "dBuN4i7dqwCLzSX7GHBLsfUoXw5RmWQ3DwQ9Ee4bfh5Y" } ], "authentication": [ "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1" ] }, "alias": ["a.snr", "b.snr"], "controllers": [snr7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm], } ``` The `alias` list and `controller` list for wallet addresses is returned along with the `document`. It must be included in the subsequent transaction (update/deactivate) for preventing transaction replay attacks. --- ## Update Only the DID owner can replace the DID Document using the following transaction. ``` (POST): /v1/registry/update/whois - Owner:string - DidDocument:[]byte - Did:string ``` This example is for adding a new public key to the `verificationMethod` and adding a dedicated public key to the `authentication`. ```json { "type": "did/MsgUpdateDID", "value": { "did": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "document": { "@context": "<https://www.w3.org/ns/did/v1>", "id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "verificationMethod": [ { "id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1", "type": "Secp256k1VerificationKey2018", "controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "publicKeyBase58": "dBuN4i7dqwCLzSX7GHBLsfUoXw5RmWQ3DwQ9Ee4bfh5Y" }, { "id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key2", "type": "Secp256k1VerificationKey2018", "controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "publicKeyBase58": "2BjcxuwijyE1om4991ANiFrwZJ3Ev5YYX9KiPKgaHmGsi" } ], "authentication": [ "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1", { "id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key3", "type": "Secp256k1VerificationKey2018", "controller": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "publicKeyBase58": "yE1om4991ANiFrwZJ3Ev5YYX9KiPKgaHmGsi2Bjcxuwij" } ] }, "signature": "xtsQH3D5naHe9IXmhCnohlChwHiD0dx9PI4aPkaJPGoEznYMHmg0aBerg85ai7T2WNxxlc39uFzAxKbI4sbJCA==", "verification_method_id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1", "from_address": "sonr1d58s72gu0mjkw0lkgyvr0eqzz3mv74awfsjslz" } } ``` Like creating DIDs, the `signature` must be generated from the `document` and the `sequence` returned from the Read DID operation. It must be signed with a private key which corresponds to the public key referred by the `verification_method_id`. The `verification_method_id` must be one of the key IDs specified in the `authentication` of the `document`. Whenever submitting this transaction the user must query the current `sequence` by the Read DID operation. (The user can also increment the `sequence` manually, but the transaction can be rejected if there are the concurrent transactions with the same `sequence`.) The source of the `signature` should look like (encoded with Amino): ```json { "data": { "@context": ..., "id": "did:snr:...", ... }, "sequence": "50" } ``` The transaction fails if the DID has been already deactivated. --- ## Deactivate To deactivate the DID document, the DID owner should send the following transaction. ``` (POST): /v1/registry/deactivate/whois - Owner:string - Did:string ``` Sonr doesn't delete the DID document. The document is just deactivated. This strategy guarantees that malicious users cannot recreate the DID, because the DID deactivation may be appropriate when a person dies or a business is terminated. ```json { "type": "did/MsgDeactivateDID", "value": { "did": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm", "signature": "xtsQH3D5naHe9IXmhCnohlChwHiD0dx9PI4aPkaJPGoEznYMHmg0aBerg85ai7T2WNxxlc39uFzAxKbI4sbJCA==", "verification_method_id": "did:snr:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm#key1", "from_address": "sonr1d58s72gu0mjkw0lkgyvr0eqzz3mv74awfsjslz" } } ``` This method sets the state of a particular WhoIs to be deactivated. In order to successfully perform this request, the TX creator and signature must be the same as the WhoIs owner. The `signature` must be generated from the `did` and the `sequence` returned from the Read DID operation. It must be signed with a private key which corresponds to the public key referred by the `verification_method_id`. The `verification_method_id` must be one of the key IDs specified in the `authentication` of the `document`. The source of the `signature` should look like (encoded with Amino): ```json { "data": "did:snr:...", "sequence": "50" } ``` The transaction fails if the DID doesn't exist or if it has been already deactivated.  # Resolution of Aliases User’s can purchase alias identifiers with the `.snr` domain namespace in order to have applications resolve their DIDDocument. This is how to purchase a new alias on behalf of a user. ### Buying an Alias ``` (POST): /v1/registry/buy/alias/name - Creator:string - Did:string - Amount:int32 - Name:string ``` This method purchases a user alias .snr domain i.e. `{example}.snr`, and inserts it into the `alsoKnownAs` field of the app's DIDDocument. Request fails when the DIDDoc type doesn’t match, wallet balance is too low, the alias has already been purchased, creator is not listed as controller of DIDDoc, or WhoIs is deactivated. The purchase of a user alias .snr domain will have a cost associated. ### Selling an Alias ``` (POST): /v1/registry/sell/alias/name - Creator:string - Did:string - Amount:int32 - Name:string ``` This method purchases a user alias .snr domain i.e. `{example}.snr`, and inserts it into the `alsoKnownAs` field of the app's DIDDocument. Request fails when the DIDDoc type doesn’t match, wallet balance is too low, the alias has already been purchased, creator is not listed as controller of DIDDoc, or WhoIs is deactivated. The selling of a user alias .snr domain will have a cost assocaited by the Alias Owner and will incur a fee upon sale. ### Transferring Alias In the situation that a user wants to transfer an owned alias from their DIDDocument to another peer on the network, the following method is called: ``` (POST): /v1/registry/transfer/alias/name - Creator:string - Did:string - Alias:string - Recipient:string ``` This method transfers an existing User .snr name Alias to the specified peer. The alias is removed from the current App's `alsoKnownAs` list and inserted into the new App's `alsoKnownAs` list. The transfer of an alias .snr domain will have incur a fee upon trasnfer to the specified peer. # Sequence Diagrams ``` erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains CUSTOMER }|..|{ DELIVERY-ADDRESS : uses ``` # Privacy Considerations *This section is non-normative.* ### Keep Personally Identifiable Information (PII) Private A DID Document should not include Personally Identifiable Information (PII), even if it is encrypted. All personal data should be kept behind service endpoints under the control of the DID subject. For example, if a DID Document contains a URL which contains any human-meaningful information, such as a username, some personal data can be unintentionally revealed without the DID subject's consent. For more details, please see the [Decentralized Identifier Specification](https://www.w3.org/TR/did-core/#keep-personally-identifiable-information-pii-private). ### DID Correlation Risks and Pseudonymous DIDs If DID Controllers want to mitigate the risk of correlation, they should use unique DIDs for every interaction and the corresponding DID Documents should contain a unique public key. For more details, please see the [Decentralized Identifier Specification](https://www.w3.org/TR/did-core/#did-correlation-risks-and-pseudonymous-dids). # Reference Implementations - [Sonr Blockchain](https://github.com/sonr-io/blockchain) - [Sonr core/did](https://github.com/sonr-io/core) # References - [https://w3c-ccg.github.io/did-spec/](https://w3c-ccg.github.io/did-spec/)

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.