Title: Decentralized Identity on XRP Ledger Revision: 1 (2023-02-09)
Author: Aanchal Malhotra Affiliation: Ripple
Self-sovereign identity, defined as a lifetime portable digital identity that does not depend on any centralized authority, requires a new class of identifier that fulfills the following four requirements: persistence, global resolvability, cryptographic verifiability, and decentralization. World Wide Web Consortium (W3C) standardized Decentralized Identifiers (DIDs) are a new type of identifier that enable verifiable, self-sovereign digital identity and are designed to be compatible with any distributed ledger or network. In the context of digital identities, W3C's Standards for DIDs and Verifiable Credentials (VCs) are rapidly gaining traction, especially in blockchain-related domains. In this document we propose to implement native support for W3C DIDs on XRP ledger.
To this end, we specify the following on XRPL:
- A new
DID methodthat describes:- the format for XRP ledger DID, and
- defines how XRP ledger generates DIDs
- How to do
CRUD operationson XRP ledger DIDs.
This specification conforms to the requirements specified in the DID v1.0 specification currently recommended by the W3C Credentials Community Group.
This proposal chooses to recommend W3C DID standard to satisfy the following first principles.
-
Decentralized: Requires no central issuing agency and functions effectively in DeFi.
-
Persistent and portable: Inherently persistent and long-lived, not requiring the continued operation of any underlying organization.
-
Cryptographically verifiable: Based on cryptographic proofs rather than out-of-band trust.
-
Resolvable and interoperable: Open to any solution that recognizes the common W3C DID standards and requires no one specific software vendor implementation.
-
This document aims to define DID format for XRPl conformant to W3C DID standards that can be created and owned by any XRPL account holder, and specify definitions for DID methods that can be implemented by any service, wallet, or application.
-
This proposal is NOT intended as a competing decentralized identity standard; it aims to leverage existing (and emerging) decentralized identity standard proposed by W3C.
In this section we specify the implementation details of W3C DID that are specific to XRP Ledger.
We propose a new ledger object called DID. The object will have two required fields: URI and Controller. The owning account of the object will be responsible for additional reserve incurred.
| Field Name | Required? | JSON Type | Internal Type |
|---|---|---|---|
URI |
✔️ | String |
Blob |
URI specifies a Universal Resource Identifier, a.k.a. URI, that points to the corresponding DID document. This field could be an HTTP(S) URL or IPFS URI. The URI field is NOT checked for validity, but the field is limited to a maximum length of 256 bytes.
| Field Name | Required? | JSON Type | Internal Type |
|---|---|---|---|
Controller |
✔️ | Address |
AccountID |
Controller specifies an XRPL account that acts as the authorized editor of the URI and Hash fields. This is NOT required to be an active account with a reserve.
| Field Name | Required? | JSON Type | Internal Type |
|---|---|---|---|
Hash |
String |
Blob |
Hash specifies the SHA-256 hash of the document in the location referenced by the URI field. This is an optional field for additional security.
In this section, we describe the DID method specification that conforms to the requirements specified in the DID specification currently published by the W3C Credentials Community Group. For more information about DIDs and DID method specifications, refer to the DID Primer.
The DID format as defined by W3C is as follows:
"did:" method-name ":" method-specific-idstring
We propose the following format for DIDs on XRPL:
"did:xrpl": network-id: xrpl-specific-idstring
The components specific to the XRP ledger network are the following:
-
method-name: The"xrpl"namestring specifies that this is a DID for XRP Ledger. A DID that uses this method MUST begin with the following prefix:did:xrpl. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is specified below. -
method-specific-idstringis formed bynetwork-idandxrpl-specific-idstringnetwork-id:network-idis a chain ID which is an identifier of XRP ledger networks. It specifies the underlying network instance where the DID related information is stored. The network is identified as 32-bit unsigned integer, formatted as a decimal value without leading zeroes (except for the value 0 which is represented as a single digit 0). The following values are defined at this time:
| Value | Description |
|---|---|
| 0 | The XRPL Mainnet |
| 1 | The XRPL Testnet |
| 2 | The XRPL Devnet |
xrpl-specific-idstring: Specifies the 256-bit hash generated as described in the next section.
XRPL DID MUST be unique within the XRPL network.
NEED TO REWORK WHAT THIS LOOKS LIKE WITH A LEDGER OBJECT INSTEAD OF ACCOUNT ROOT
xrpl-specific-idstring is the ID of the AccountRoot object of an XRPL account, a.k.a., AccountRootID, which is the SHA-512Half of the following values, concatenated in order:
- The Account space key (0x0061)
- The Account ID of the account
Example:
A valid XRPL Testnet DID may be
did:xrpl:1:
XRPL DID is managed by the corresponding XRP ledger account owner. In this section we outline the following four CRUD operations for did:xrpl method using the existing methods supported by XRP ledger client libraries.
CreateResolveUpdateDelete
The XRPL DID creation requires the introduction of a new transaction type: DIDCreate
{
"TransactionType": "DIDCreate",
"Account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"Fee": "10",
"URI": "ipfs://...",
"Controller": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"Hash": "78e48f304dc2257c4358b9a39eee3dd10b5bfe05ddb2746a0522405058d10c22"
}
| Field Name | Required? | JSON Type | Internal Type |
|---|---|---|---|
URI |
✔️ | String |
Blob |
Controller |
✔️ | String |
AccountID |
Hash |
String |
Blob |
The first step in using a DID for any application is to resolve the DID to the underlying DID Document, to further reveal the cryptographic material and service endpoints associated with that DID.
In this case XRP ledger DID, the read operation resolves to the URI. Following steps to retrieve the corresponding URI and hash:
Given the DID, retrieve the contents of the corresponding DID object in its raw format using the the XRPL's ledger_entry method. The index field is used to specify the unique object ID of the AccountRoot object to retrieve its contents.
Sample ledger_entry Method Request to retrieve the contents of DID object:
{
"method": “ledger_entry”,
"params": [
{
“index”: DID,
"ledger_index": "validated"
}
]
}
A sample response to the above query might look like this:
{
"result":
{
“index”: Identifier Object ID,
"ledger_hash": "256-bit hash",
"ledger_index": 58269896,
"node": {
"LedgerEntryType": "DID",
"DID":
{
URI: "256-bit IPFS hash"
}
},
"validated": true
},
"status": "success",
"type": "response"
}
Upon receiving this response, an HTTP(S) or an IPFS address (CAS) can be retrieved from the URI field.
These addresses can then be resolved to retrieve the corresponding DID Document. The DID URL dereferencing dereferences a DID URL into a resource with contents depending on the DID URL's components. The details of how this process is accomplished are outside the scope of this specification. Note that a DID resolver must return the referenced DID document as is.
Note: Applications implementing this method MAY extend it to enable DID document fetching from the retrieved URI.
Update:The owner of the XRP ledger DID may want to modify the storage location of a DID document OR, rotate the cryptographic material, or change the service end-points associated with a DID. This MAY require managing/updating the DID document URL and/or its corresponding hash. This can be done by introducing another new transaction type calledDIDUpdate.
| Field Name | Required? | JSON Type | Internal Type |
|---|---|---|---|
DID |
✔️ | String |
Blob |
URI |
✔️ | String |
Blob |
ControllerSignature |
✔️ | String |
Blob |
Hash |
String |
Blob |
The DIDUpdate transaction can be sent by any account (not necessarily the owner of the DID ledger object) and will succeed so long as the ControllerSignature validates for the current Controller address for the DID.
The DID owner SHOULD also upload the (new) DID document to the corresponding (new) storage network location.
Example DIDUpdate JSON to update DID document reference
{
"Flags": ,
"TransactionType": "DIDUpdate",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "12",
"DID": "The DID to update",
"URI": "New DID doc URI",
"Hash": "New DID doc hash",
"ControllerSignature": "Signature from controller account"
}
Delete:Similarly, XRP ledger DID owner MAY want to delete their DID. Most decentralized systems cannot guarantee actual deletion of a record. Indeed, distributed ledgers are often touted as "immutable". So, instead of deleting a DID, owner should be able to deactivate a DID such that downstream processes for dereferencing are no longer functional. We introduce another new transaction calledDIDDelete. This will remove the ledger object and reduce the reserve requirement. Additionally, a deleted DID will not be allowed to be used again.
Example DIDDelete JSON to delete DID document reference
{
"Flags": ,
"TransactionType": "DIDDelete",
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"DID": "The DID to delete",
"Fee": "12",
}
In order to move ownership (and responsibility for the reserve requirement) we need transactions similar to the NFToken ledger object:
DIDOfferCreateDIDOfferCancelDIDOfferAccept
This does not necessarily transfer control of the DID, just the ownership of it in the reserve requirement sense.
There are several securities and privacy considerations that implementers would want to take into consideration when implementing this specification.
Sending transactions to the XRPL requires control over the private key used to anchor the DID, so any key recovery method which applies to XRPL keys can be applied here. This can involve seed phrases stored in an analogue manner among other methods.
No party can revoke the keys of DID control of another party under the XRPL system.
As mentioned in the Key Recovery section, the entity which controls the private key associated with the DID also effectively controls the DID Document which the DID resolves to. Thus great care should be taken to ensure that the private key is kept private. Methods for ensuring key privacy are outside the scope of this document.
The DID document anchored with the XRPL DID's DIDDoc field can contain any content, though it is recommended that it conforms to the W3C DID Document specification. As anchored DIDs on XRPL can be resolved by anyone, care should be taken to only update to resolve DID Documents which DO NOT expose any sensitive personal information, or information which you may not wish to be public. DID documents should be limited to verification methods and service endpoints, and should not store any personal information.
IPFS allows anyone to store content publicly on the nodes in a distributed network. A common misconception is that anyone can edit content, however the content-addressability of IPFS means that this new edited content will have a different address to the original. While any entity can copy a DID Document anchored with an XRPL account's DIDDoc, they cannot change the document that a DID resolves to via the XRPL ledger_entry resolution unless they control the private key which created the corresponding DIDDoc field on XRPL.
For more, see § 10. Privacy Considerations in did-core.
TBD$$
A DID is associated with a DID document. A DID document contains the necessary information to cryptographically verify the identity of the DID subject. W3C defines the core properties in a DID document, that describe relationships between the DID subject and the value of the property. For example, a DID document could contain cryptographic public keys such that the DID subject can use it to authenticate itself and proves its association with the DID. Usually, a DID document can be serialized to JSON representation or JSON-LD representation (see [DIDs v1.0]).
The DID document associated with the XRPL DID is not directly stored on the XRPL. Instead, XRPL DID method stores a reference on the ledger in the DIDoc field of AccountRoot object to the DID document stored in one or more parts on other decentralized storage networks such as IPFS or STORJ.
A sample XRPL DID Document MAY look like:
{
"@context" : "https://w3id.org/did/v1",
"id" : "did:xrpl:testnet:256-bit hash",
"publicKey" : [
{
"id" : "did:xrpl:testnet:256-bit hash#keys-1",
"type" : ["CryptographicKey", "EcdsaKoblitzPublicKey"],
"curve" : "secp256k1",
"expires" : 15674657,
"publicKeyHex": "04f42987b7faee8b95e2c3a3345224f00e00dfc67ba882…."
} ],
}
W3C defines the core properties in a DID document, that describe relationships between the DID subject and the value of the property.
A Universal Resolver is an identifier resolver that works with any decentralized identifier system, including Decentralized Identifiers (DIDs). Refer here. A driver for XRPL DID mehod resolution will be added to universal resolver configurations to make it publicly accessible.