Custom EID RPC Interfaces
EID inherits all RPC interfaces of ESC, so please refer to the Github Wiki for the full reference. This section describes the two RPC interfaces (did_resolveDID and did_resolveCredential) that are unique to the EID chain.
Contentsβ
This document is the Elastos DID Resolver specification, which is published and maintained by the Elastos Foundation. It mainly explains the definition of the Elastos DID Resolver, as well as the definition of related requests and response data. In the future, we will continue to upgrade this document so that it reflects the latest state of development of the Elastos DID technology.
Abstractβ
This specification defines the method and interface for resolving or querying DID on the Elastos ID side chain.
Elastos uses the JSON-RPC interface to provide the DID resolve method. For more details about JSON-RPC, please see specifications on the official website.
DID Resolveβ
DID Resolve is the method used to resolve specific DID documents.
Resolve Requestβ
methodβ
The string value contains the name of the method to be invoked. For the DID Resolve request, the value is "resolvedid".
paramsβ
The object value, which is the parameter to be included in the call of resolvedid
method. The parameters are defined as follows:
did
DID string. Can be a complete DID string, such as did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4, or just a method specific string, such as: iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4.
all
Whether or not all operation history of this DID are obtained. Boolean, true or false.
idβ
The request identifier set by the client must include a string, numerical or null value (if contained). The value usually should not be null, and the numerals should not include decimals.
Resolve Responseβ
jsonrpcβ
The JSON-RPC default response property, a string value, indicates the JSON-RPC protocol version. Must be "2.0."
resultβ
If Resolve is executed successfully, then this member is included, and the value is the result object of resolve. If an error occurs when resolve is invoked, then this member does not exist or is null. See Resolve Result Object for the definition of the DID Resolverβs resolve result object.
errorβ
If Resolve executes normally, then this member does not exist or is null. If there is an error in the execution of Resolve, this member is included, the value is an error object. See Error Object for the definition of error objects.
idβ
This member is necessary. It must be identical to the value of the id member in the request object. If an error occurs at the time of ID inspection in the request object (for example resolve error/invalid request), then this value must be null.
Resolve Result Objectβ
When the DID Resolve executes successfully, the response must contain a result member whose value is an object containing the following members:
didβ
The request's target DID.
statusβ
The numerical value type status code indicates the result status of resolving target DID. This value is an integer. The value is defined as the following:
status | meaning |
---|---|
0 | DID document is valid. Transaction member contains an array which is the result of requesting DID transaction. |
1 | DID document is expired. Transaction member contains an array which is the result of requesting DID transaction. |
2 | DID document is deactivated. Transaction member contains an array which is the result of requesting DID transaction. |
3 | DID does not exist. The result object does not contain the transaction member. |
When resolving a DID, regardless of the DID status, it should return this object, and should not return the error object, as long as the resolve is executed normally. Different resolve results are expressed though different status values. For example, statuses such as DID does not exists, is expired, or is deactivated, are all normal, and should return this object. It will only return the error object when the Resolver service cannot execute resolve actions, and in general is a JSON-RPC error or a Resolver error itself.
transactionβ
An array object, and the elements are the ID transaction and operation information of the target DID being requested. The element is an object containing the following members:
txid
The string member which is the current ID transaction's transaction id.
timestamp
For the transaction time, whose value must be a valid string value conforming to RFC3339 combining the date and time, and must also be normalized to UTC time, followed in "Z."
operation
The object member, which is the payload of the current ID transaction, that is, the JSON object of the DID operation.
Whenall
in the parameters of Resolve DID request is false, the transaction array object only contains information from the target ID's last transaction. When all
is true, the transaction array object contains all transaction information of the target DID, and the array elements are stored in descending order according to IDβs transaction time, meaning that no. #0 is the newest ID transaction.
Examplesβ
Resolve the DID document, and the document is validβ
Requestβ
{
method: "resolvedid",
params: {
did: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
all: false,
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
id: "8555cbd1afbf3b8fd8748464ee949574",
jsonrpc: "2.0",
result: {
did: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
status: 0,
transaction: [
{
txid: "467491e6be79fbc6...ce9192d6f15ca81e",
timestamp: "2019-08-10T17:30:00Z",
operation: {
header: {
specification: "elastos/did/1.0",
operation: "update",
previousTxid: "3641de55f368583c...8917756a872093d2",
},
payload: "eyJpZCI6ImRpZDplbGFzdG9zOmlWUGFk...UMDI6MDA6MDBaIn0",
proof: {
type: "ECDSAsecp256r1",
verificationMethod: "#primary",
signature: "IdcfNkS7yA_GHL6g...6lWq7eI9OJGaNPbg",
},
},
},
],
},
}
Resolve the DID document, the document is expiredβ
Requestβ
{
method: "resolvedid",
params: {
did: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
all: false,
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
id: "8555cbd1afbf3b8fd8748464ee949574",
jsonrpc: "2.0",
result: {
did: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
status: 1,
transaction: [
{
txid: "467491e6be79fbc6...ce9192d6f15ca81e",
timestamp: "2019-08-10T17:30:00Z",
operation: {
header: {
specification: "elastos/did/1.0",
operation: "update",
previousTxid: "3641de55f368583c...8917756a872093d2",
},
payload: "eyJpZCI6ImRpZDplbGFzdG9zOmlWUGFk...UMDI6MDA6MDBaIn0",
proof: {
type: "ECDSAsecp256r1",
verificationMethod: "#primary",
signature: "IdcfNkS7yA_GHL6g...6lWq7eI9OJGaNPbg",
},
},
},
],
},
}
Resolve the DID document, the DID has been deactivatedβ
Requestβ
{
method: "resolvedid",
params: {
did: "iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
all: false,
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
id: "8555cbd1afbf3b8fd8748464ee949574",
jsonrpc: "2.0",
result: {
did: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
status: 2,
transaction: [
{
txid: "467491e6be79fbc6...ce9192d6f15ca81e",
timestamp: "2019-11-10T21:30:00Z",
operation: {
header: {
specification: "elastos/did/1.0",
operation: "deactivate",
},
payload: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
proof: {
verificationMethod: "#recovery",
signature: "IdcfNkS7yA_GHL6g...6lWq7eI9OJGaNPbg",
},
},
},
],
},
}
Resolve the DID document, the DID does not existβ
Requestβ
{
method: "resolvedid",
params: {
did: "iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
all: false,
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
id: "8555cbd1afbf3b8fd8748464ee949574",
jsonrpc: "2.0",
result: {
did: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
status: 3,
},
}
Resolve all DID operation recordsβ
Requestβ
{
method: "resolvedid",
params: {
did: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
all: true,
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
id: "8555cbd1afbf3b8fd8748464ee949574",
jsonrpc: "2.0",
result: {
did: "did:elastos:iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
status: 0, // Maybe 0, 1, 2
transaction: [
{
txid: "467491e6be79fbc6...ce9192d6f15ca81e",
timestamp: "2019-12-1T17:30:00Z",
operation: {
header: {
specification: "elastos/did/1.0",
operation: "update",
previousTxid: "3641de55f368583c...8917756a872093d2",
},
payload: "eyJpZCI6ImRpZDplbGFzdG9zOmlWUGFk...UMDI6MDA6MDBaIn0",
proof: {
type: "ECDSAsecp256r1",
verificationMethod: "#primary",
signature: "IdcfNkS7yA_GHL6g...6lWq7eI9OJGaNPbg",
},
},
},
{
txid: "3641de55f368583c...8917756a872093d2",
timestamp: "2019-10-18T10:30:00Z",
operation: {
header: {
specification: "elastos/did/1.0",
operation: "update",
previousTxid: "3a2936c4777f02a9...3f683c82a1aa378c",
},
payload: "E1NndTUkR2dEQ1SEt2Q1BOcnlITszcV...ZTVTQiLCJwdWJsaW",
proof: {
type: "ECDSAsecp256r1",
verificationMethod: "#primary",
signature: "xOanVzekR2aGk5aW...l2NlJxQ0RHc1Rjc0",
},
},
},
{
txid: "3a2936c4777f02a9...3f683c82a1aa378c",
timestamp: "2019-08-10T17:30:00Z",
operation: {
header: {
specification: "elastos/did/1.0",
operation: "create",
},
payload: "NLZXkiOlt7ImlkIjoiI3ByaW1hcnkiLC...JwdWJsaWNLZXlCYX",
proof: {
type: "ECDSAsecp256r1",
verificationMethod: "#primary",
signature: "NlNTgiOiJwdmZBUU...68dTRnTm1hdDZHTE",
},
},
},
],
},
}
Resolve the DID errorβ
Requestβ
{
method: "resolvedid",
params: {
did: "iVPadJq56wSRDvtD5HKvCPNryHMk3qVSU4",
all: false,
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
id: "8555cbd1afbf3b8fd8748464ee949574",
jsonrpc: "2.0",
error: {
code: -32001,
message: "Resolver internal error.",
},
}
DID Queryβ
DID Query is a method for querying DID documents on the ID side chain. The query scope is all latest DID documents in non-deactivated state, the expired documents are in the scope.
Query Requestβ
methodβ
The string value contains the name of the method to be invoked. For the DID query request, the value is "query".
paramsβ
The object value, which is the parameter to be included in the call of query
method. The parameters are defined as follows:
service
Optional, a string representing the service type. For service type, see the definition of service in the Elastos DID method specification. Only supports single values. For complex queries, use "query".
credential
Optional, a string representing the credential type. For credential type, see the definition of credential in the Elastos Verifiable Claims Specification. Only supports single values. For complex queries, use "query".
query
Optional, query conditions in MongoDB query syntax, only supports the conditional syntax of MongoDB's find method.
skip
Optional, the number of documents to skip in the results set. The default value is 0.
limit
Optional, the number of documents returned in the result set.
If no limit is specified, the size of the results returned is determined by the server. If the result set is large, the server may return a subset of the results to avoid excessive server resource consumption.
Although all the above three parameters service
, credential
and query
are optional, they can only support one and must have one.
The skip
and limit
parameters are used to provide pagination support, which controls the subset of the query results that should be returned.
idβ
The request identifier set by the client must include a string, numerical or null value (if contained). The value usually should not be null, and the numerals should not include decimals.
Query Responseβ
jsonrpcβ
The JSON-RPC default response property, a string value, indicates the JSON-RPC protocol version. Must be "2.0."
resultβ
If query is executed successfully, then this member is included, and the value is the result object of query. If an error occurs when query is invoked, then this member does not exist or is null. See Query Result Object for the definition of the DID query result object.
errorβ
If query executes normally, then this member does not exist or is null. If there is an error in the execution of query, this member is included, the value is an error object. See Error Object for the definition of error objects.
idβ
This member is necessary. It must be identical to the value of the id member in the request object. If an error occurs at the time of ID inspection in the request object (for example query error/invalid request), then this value must be null.
Query Result Objectβ
When the DID Query executes successfully, the response must contain a result member whose value is an object containing the following members:
totalβ
The total number of document that meet the query conditions.
startβ
The start document position of the current results set.
countβ
The number of documents returned in the current result set.
documentβ
An array object, and the elements are the DID document that meet the query conditions. If there are no matching DIDs, an empty array is returned.
Examplesβ
Querying DIDs containing specific service, return the 3rd page, 10 documents per pageβ
Requestβ
{
method: "query",
params: {
service: "CredentialRepositoryService",
skip: 20,
limit: 10,
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
"id": "8555cbd1afbf3b8fd8748464ee949574",
"jsonrpc": "2.0",
"result": {
"total": 1234,
"start": 20,
"count": 10,
"document": [{
"id":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz",
"publicKey":[
{
"id":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz",
"publicKeyBase58":"29sd8BAPMWcTvDxT2igvQ86rbd8WYboYbmt3szo1zszdB"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz#primary",
"signatureValue":"DNBIrcX9...Dz0j5q1g"
}
}, {
"id":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m",
"publicKey":[
{
"id":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m",
"publicKeyBase58":"22z1jcrBqX75yRBUNgDHkWmPs1SGe57gkHYA7UCij6Nge"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m#primary",
"signatureValue":"vJH4s1KH...LWSU-8MA"
}
},
......
{
"id":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT",
"publicKey":[
{
"id":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT",
"publicKeyBase58":"26aiYAHBGGKvHWneoaLfgJNKihfGjhHsva1YLBT89WvFB"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT#primary",
"signatureValue":"4yoSU799...zv5euakA"
}
}]
}
}
Querying DIDs containing specific credentialβ
Requestβ
{
method: "query",
params: {
credential: "TrinityCredential",
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
"id": "8555cbd1afbf3b8fd8748464ee949574",
"jsonrpc": "2.0",
"result": {
"total": 1234,
"start": 0,
"count": 20,
"document": [{
"id":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz",
"publicKey":[
{
"id":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz",
"publicKeyBase58":"29sd8BAPMWcTvDxT2igvQ86rbd8WYboYbmt3szo1zszdB"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz#primary",
"signatureValue":"DNBIrcX9...Dz0j5q1g"
}
}, {
"id":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m",
"publicKey":[
{
"id":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m",
"publicKeyBase58":"22z1jcrBqX75yRBUNgDHkWmPs1SGe57gkHYA7UCij6Nge"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m#primary",
"signatureValue":"vJH4s1KH...LWSU-8MA"
}
},
......
{
"id":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT",
"publicKey":[
{
"id":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT",
"publicKeyBase58":"26aiYAHBGGKvHWneoaLfgJNKihfGjhHsva1YLBT89WvFB"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT#primary",
"signatureValue":"4yoSU799...zv5euakA"
}
}]
}
}
Customized queryβ
MongoDB's find conditionβ
{
credential: {
type: ["SelfProclaimedCredential"],
subject: {
email: { $exists: true },
},
},
}
Requestβ
{
method: "query",
params: {
query: '{"credential":{"type":["SelfProclaimedCredential"],"subject":{"email":{$exists:true}}}}',
skip: 10,
limit: 10,
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
"id": "8555cbd1afbf3b8fd8748464ee949574",
"jsonrpc": "2.0",
"result": {
"total": 1234,
"start": 10,
"count": 10,
"document": [{
"id":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz",
"publicKey":[
{
"id":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz",
"publicKeyBase58":"29sd8BAPMWcTvDxT2igvQ86rbd8WYboYbmt3szo1zszdB"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ir3YWGtyHNe9FoX9JXELgxCd8VkrGDaGcz#primary",
"signatureValue":"DNBIrcX9...Dz0j5q1g"
}
}, {
"id":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m",
"publicKey":[
{
"id":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m",
"publicKeyBase58":"22z1jcrBqX75yRBUNgDHkWmPs1SGe57gkHYA7UCij6Nge"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ieMT72pyCe6NtHC9wbeKoVR1vjkWVTaG3m#primary",
"signatureValue":"vJH4s1KH...LWSU-8MA"
}
},
......
{
"id":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT",
"publicKey":[
{
"id":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT#primary",
"type":"ECDSAsecp256r1",
"controller":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT",
"publicKeyBase58":"26aiYAHBGGKvHWneoaLfgJNKihfGjhHsva1YLBT89WvFB"
}
],
......
"expires":"2025-03-24T02:25:41Z",
"proof":{
"type":"ECDSAsecp256r1",
"created":"2020-03-24T02:25:41Z",
"creator":"did:elastos:ioz9sPWmCdATbpbhSmrYGJ5V9hYkqT1kGT#primary",
"signatureValue":"4yoSU799...zv5euakA"
}
}]
}
}
Empty query resultβ
Requestβ
{
method: "query",
params: {
query: '{"credential":{"type":["InternetCredential"],"subject":{"email":{$exists:true}}}}',
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
id: "8555cbd1afbf3b8fd8748464ee949574",
jsonrpc: "2.0",
result: {
total: 0,
start: 0,
count: 0,
document: [],
},
}
Query errorβ
Requestβ
{
method: "query",
params: {
service: "carrier",
query: '{"credential":{"type":["SelfProclaimedCredential"],"subject":{"email":{$exists:true}}}}',
},
id: "8555cbd1afbf3b8fd8748464ee949574",
}
Responseβ
{
id: "8555cbd1afbf3b8fd8748464ee949574",
jsonrpc: "2.0",
error: {
code: -32602,
message: "Query parameters invalid.",
},
}
Error objectβ
When the Resolve or Query encounters an error, an error member must be contained in the response, whose value is an object containing the following members:
codeβ
The numerical type error code indicating the error type occurred. This value is an integer.
According to the definition in specification, error codes from -32768 to -32000 (including -32768 to -32000) are reserved for predefined errors. Any code within this scope that has not been specifically defined below is reserved for future use.
code | message | meaning |
---|---|---|
-32700 | Parse error | Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. |
-32600 | Invalid Request | The JSON sent is not a valid Request object. |
-32601 | Method not found | The method does not exist / is not available. |
-32602 | Invalid params | Invalid method parameter(s). |
-32603 | Internal error | Internal JSON-RPC error. |
-32000 to -32099 | Server error | Reserved for implementation-defined server-errors. |
messageβ
A string briefly describing the error. Generally, a concise sentence.
dataβ
Member optional, contains other information related to the error. The value is defined by the Resolver server (for example, detailed error information, nested errors, etc.).