Client-app Identity APIs

Technical Docs for cheqd
Learn about cheqd Product Updates Governance GitHub
Search…
cheqd: Node Documentation
Guides
Setting up a new cheqd node
cheqd Cosmos CLI
Building from source
Client-app Identity APIs
Error messages
Architecture
Architecture Decision Record (ADR) Process
Client-app Identity APIs
Overview
This page describes how identity domain transactions need to be implemented by client-side applications/libraries such as cheqd-sdk (forked from Evernym VDR Tools).
Details on how identity transactions are defined is available in ADR 002: Identity entities and transactions.
Base write flow
1.Build a request Example: build_create_did_request(id, verkey, alias)
2.Sign the request using DID key Example: indy_crypto_sign(did, verkey)
3.Build a transaction with the request from previous step Example: build_tx(pool_alias, pub_key, builded_request, account_number, account_sequence, max_gas, max_coin_amount, denom, timeout_height, memo)
4.Sign the transaction Example: cheqd_keys_sign(wallet_handle, key_alias, tx).
5.Broadcast a signed transaction Example: broadcast_tx_commit(pool_alias, signed).
Response format
1
  Response {
2
   check_tx: TxResult {
3
      code: 0,
4
      data: None,
5
      log: "",
6
      info: "",
7
      gas_wanted: 0,
8
      gas_used: 0,
9
      events: [
10
      ],
11
      codespace: ""
12
   },
13
   deliver_tx: TxResult {
14
      code: 0,
15
      data: Some(Data([...])),
16
      log: "[{\"events\":[{\"type\":\"message\",\"attributes\":[{\"key\":\"action\",\"value\":\"send\"},{\"key\":\"sender\",\"value\":\"cheqd1fknpjldck6n3v2wu86arpz8xjnfc60f99ylcjd\"},{\"key\":\"module\",\"value\":\"bank\"}]},{\"type\":\"transfer\",\"attributes\":[{\"key\":\"recipient\",\"value\":\"cheqds1pvnjjy3vz0ga6hexv32gdxydzxth7f86mekcpg\"},{\"key\":\"sender\",\"value\":\"cheqd1fknpjldck6n3v2wu86arpz8xjnfc60f99ylcjd\"},{\"key\":\"amount\",\"value\":\"1000ncheq\"}]}]}]",
17
      info: "",
18
      gas_wanted: 0,
19
      gas_used: 0,
20
      events: [...], 
21
      codespace: ""
22
   },
23
   hash: "1B3B00849B4D50E8FCCF50193E35FD6CA5FD4686ED6AD8F847AC8C5E466CFD3E",
24
   height: 353
25
}
Copied!
hash : Transaction hash
height: Ledger height
DID transactions
Create DID
cheqd-sdk function
build_create_did_request(id, verkey, alias)
Request format
1
CreateDidRequest 
2
{
3
    "data": {
4
               "id": "GEzcdDLhCpGCYRHW82kjHd",
5
               "verkey": "~HmUWn928bnFT6Ephf65YXv",
6
               "alias": "DID for Alice"
7
             },
8
    "owner": "GEzcdDLhCpGCYRHW82kjHd",
9
    "signature": "49W5WP5jr7x1fZhtpAhHFbuUDqUYZ3AKht88gUjrz8TEJZr5MZUPjskpfBFdboLPZXKjbGjutoVascfKiMD5W7Ba",
10
    "metadata": {}
11
}
Copied!
id (base58-encoded string): Target DID as base58-encoded string for 16 or 32 byte DID value
verkey (base58-encoded string, possibly starting with ""; optional): Target verification key. It can start with "", which means that it is an abbreviated verkey and should be 16 bytes long when decoded. Otherwise, it's a full verkey which should be 32 bytes long when decoded.
alias (string; optional)
Response format
1
CreateDidResponse {
2
    "key": "did:GEzcdDLhCpGCYRHW82kjHd" 
3
}
Copied!
key(string): A unique key is used to store this DID in a state
Response validation
CreateDidRequest must be signed by the DID from id field. It means that this DID must be an owner of this DID transaction.
Update DID
cheqd-sdk function
build_update_did_request(id, verkey, alias)
Request format
1
UpdateDidRequest 
2
{
3
    "data": {
4
               "id": "GEzcdDLhCpGCYRHW82kjHd",
5
               "verkey": "~HmUWn928bnFT6Ephf65YXv",
6
               "alias": "DID for Alice"
7
             },
8
    "owner": "GEzcdDLhCpGCYRHW82kjHd",
9
    "signature": "49W5WP5jr7x1fZhtpAhHFbuUDqUYZ3AKht88gUjrz8TEJZr5MZUPjskpfBFdboLPZXKjbGjutoVascfKiMD5W7Ba",
10
    "metadata": {}
11
}
Copied!
id (base58-encoded string): Target DID as base58-encoded string for 16 or 32 byte DID value.
verkey (base58-encoded string, possibly starting with ""; optional): Target verification key. It can start with "", which means that it is an abbreviated verkey and should be 16 bytes long when decoded. Otherwise, it's a full verkey which should be 32 bytes long when decoded.
alias (string; optional).
Response format
1
UpdateDidResponse {
2
    "key": "did:GEzcdDLhCpGCYRHW82kjHd" 
3
}
Copied!
key(string): A unique key is used to store this DID in a state
Response validation
A transaction with id from UpdateDidRequestmust already be in a ledger created by CreateDidRequest
UpdateDidRequest must be signed by the DID from id field. It means that this DID must be an owner of this DID transaction.
Get DID
cheqd-sdk function
build_query_get_did(id)
id (base58-encoded string): Target DID as base58-encoded string for 16 or 32 byte DID value.
Request format
1
Request 
2
{
3
    "path": "/store/cheqd/key",
4
    "data": <bytes>,
5
    "height": 642,
6
    "prove": true
7
}
Copied!
path: Path for RPC endpoint for cheqd pool
data: Query with an entity key from a state. String did:<id> encoded to bytes
height: Ledger height (size). None for auto calculation
prove: Boolean value. True for getting state proof in a pool response
Response format
1
QueryGetDidResponse{
2
        "did": {
3
               "id": "GEzcdDLhCpGCYRHW82kjHd",
4
               "verkey": "~HmUWn928bnFT6Ephf65YXv",
5
               "alias": "DID for Alice"
6
             },
7
}
Copied!
ATTRIB transactions
Create ATTRIB
cheqd-sdk function
build_create_attrib_request(did, raw)
Request format
1
CreateAttribRequest 
2
{
3
    "data": {
4
               "did": "GEzcdDLhCpGCYRHW82kjHd",
5
               "raw": "{'name': 'Alice'}"
6
             },
7
    "owner": "GEzcdDLhCpGCYRHW82kjHd",
8
    "signature": "49W5WP5jr7x1fZhtpAhHFbuUDqUYZ3AKht88gUjrz8TEJZr5MZUPjskpfBFdboLPZXKjbGjutoVascfKiMD5W7Ba",
9
    "metadata": {}
10
}
Copied!
did (base58-encoded string): Target DID as base58-encoded string for 16 or 32 byte DID value.
raw (JSON; mutually exclusive with hash and enc): Raw data represented as JSON, where the key is attribute name and value is attribute value.
Response format
1
CreateAttribResponse {
2
    "key": "attrib:GEzcdDLhCpGCYRHW82kjHd" 
3
}
Copied!
key(string): A unique key is used to store these attributes in a state
Response validation
A DID transaction with id from UpdateAttribRequestmust already be in a ledger created by CreateDidRequest
CreateAttribRequest must be signed by the DID from did field. It means that this DID must be an owner of this ATTRIB transaction.
Update ATTRIB
cheqd-sdk function
build_update_attrib_request(id, raw)
Request format
1
UpdateAttribRequest 
2
{
3
    "data": {
4
               "did": "GEzcdDLhCpGCYRHW82kjHd",
5
               "raw": "{'name': 'Alice'}"
6
             },
7
    "owner": "GEzcdDLhCpGCYRHW82kjHd",
8
    "signature": "49W5WP5jr7x1fZhtpAhHFbuUDqUYZ3AKht88gUjrz8TEJZr5MZUPjskpfBFdboLPZXKjbGjutoVascfKiMD5W7Ba",
9
    "metadata": {}
10
}
Copied!
did (base58-encoded string): Target DID as base58-encoded string for 16 or 32 byte DID value.
raw (JSON; mutually exclusive with hash and enc): Raw data represented as JSON, where the key is attribute name and value is attribute value.
Response format
1
UpdateAttribResponse {
2
        "key": "attrib:GEzcdDLhCpGCYRHW82kjHd" 
3
}
Copied!
key(string): A unique key is used to store these attributes in a state
Response validation
A DID transaction with id from UpdateAttribRequestmust already be in a ledger created by CreateDidRequest
UpdateAttribRequest must be signed by DID from did field. It means that this DID must be an owner of this ATTRIB transaction.
Get ATTRIB
cheqd-sdk function
build_query_get_attrib(did)
did (base58-encoded string) Target DID as base58-encoded string for 16 or 32 byte DID value.
Request format
1
Request 
2
{
3
    "path": "/store/cheqd/key",
4
    "data": <bytes>,
5
    "height": 642,
6
    "prove": true
7
}
Copied!
path: Path for RPC endpoint for cheqd pool
data: Query with an entity key from a state. String did:<id> encoded to bytes
height: Ledger height (size). None for auto calculation
prove: Boolean value. True for getting state proof in a pool response
Response format
1
QueryGetAttribResponse{
2
        "attrib": {
3
               "did": "GEzcdDLhCpGCYRHW82kjHd",
4
               "raw": "{'name': 'Alice'}"
5
             },
6
}
Copied!
SCHEMA transactions
Create SCHEMA
cheqd-sdk function
build\_create\_schema\_request\(version, name, attr\_names\)
Request format
1
CreateSchemaRequest 
2
{
3
    "data": {
4
            "version": "1.0",
5
            "name": "Degree",
6
            "attr_names": ["undergrad", "last_name", "first_name", "birth_date", "postgrad", "expiry_date"]
7
             },
8
    "owner": "GEzcdDLhCpGCYRHW82kjHd",
9
    "signature": "49W5WP5jr7x1fZhtpAhHFbuUDqUYZ3AKht88gUjrz8TEJZr5MZUPjskpfBFdboLPZXKjbGjutoVascfKiMD5W7Ba",
10
    "metadata": {}
11
}
Copied!
attr_names(array): Array of attribute name strings (125 attributes maximum)
name(string): Schema's name string
version(string): Schema's version string
Response format
1
CreateSchemaResponse {
2
        "key": "schema:GEzcdDLhCpGCYRHW82kjHd:Degree:1.0" 
3
}
Copied!
key(string): A key is used to store this schema in a state
Response validation
A SCHEMA transaction with DID from owner field must already be in a ledger created by CreateDidRequest
CreateSchemaRequest must be signed by DID from owner field.
Get Schema
cheqd-sdk function
build\_query\_get\_schema\(name, version, owner\)
name(string): Schema's name string
version(string): Schema's version string
owner (string): Schema's owner did
Request format
1
Request 
2
{
3
    "path": "/store/cheqd/key",
4
    "data": <bytes>,
5
    "height": 642,
6
    "prove": true
7
}
Copied!
path: Path for RPC Endpoint for cheqd pool
data: Query with an entity key from a state. String schema:<owner>:<name>:<version> encoded to bytes
height: Ledger height (size). None for auto calculation;
prove: Boolean value. True for getting state proof in a pool response.
Response format
1
QueryGetSchemaResponse{
2
        "attrib": {
3
                "version": "1.0",
4
                "name": "Degree",
5
                "attr_names": ["undergrad", "last_name", "first_name", "birth_date", "postgrad", "expiry_date"]
6
             },
7
}
Copied!
CRED_DEF
Create Credential Definition
cheqd-sdk function
build\_create\_cred\_def\_request\(cred\_def, schema\_id, signature\_type, tag\)
Request format
1
CreateCredDefRequest 
2
{
3
    "data": {
4
                "signature_type": "CL",
5
                "schema_id": "schema:GEzcdDLhCpGCYRHW82kjHd:Degree:1.0",
6
                "tag": "some_tag",    
7
                "cred_def": {
8
                    "primary": ....,
9
                    "revocation": ....
10
            },
11
    "owner": "GEzcdDLhCpGCYRHW82kjHd",
12
    "signature": "49W5WP5jr7x1fZhtpAhHFbuUDqUYZ3AKht88gUjrz8TEJZr5MZUPjskpfBFdboLPZXKjbGjutoVascfKiMD5W7Ba",
13
    "metadata": {}
14
}
Copied!
cred_def (dict): Dictionary with Credential Definition's data:
primary (dict): Primary credential public key
revocation (dict): Revocation credential public key
schema_id (string): Schema's key from a state
signature_type (string): Type of the Credential Definition (that is credential signature). CL (Camenisch-Lysyanskaya) is the only supported type now.
tag (string, optional): A unique tag to have multiple public keys for the same Schema and type issued by the same DID. A default tag tag will be used if not specified.
Response format
1
CreateCredDefResponse {
2
        "key": "cred_def:GEzcdDLhCpGCYRHW82kjHd:schema:GEzcdDLhCpGCYRHW82kjHd:Degree:1.0:some_tag:CL" 
3
}
Copied!
key(string): A unique key that is used to store this Credential Definition in a state
Response validation
A CRED_DEF transaction with DID from owner field must already be in a ledger created by CreateDidRequest
CreateCredDefRequest must be signed by DID from owner field.
Get Credential Definition
cheqd-sdk function
build\_query\_get\_cred\_def\(name, version, owner\)
schema_id(string): Schema's key from a state
signature_type(string): Type of the Credential Definition (that is credential signature). CL (Camenisch-Lysyanskaya) is the only supported type now.
owner (string): Credential Definition's owner DID
tag (string, optional): A unique tag to have multiple public keys for the same Schema and type issued by the same DID. A default tag tag will be used if not specified.
Request format
1
Request 
2
{
3
    "path": "/store/cheqd/key",
4
    "data": <bytes>,
5
    "height": 642,
6
    "prove": true
7
}
Copied!
path: Path for RPC endpoint for cheqd pool
data: Query with an entity key from a state. String cred_def:<owner>:<schema_id>:<tag>:<signature_type> encoded to bytes
height: Ledger height (size). None for auto calculation
prove: Boolean value. True for getting state proof in a pool response.
Response format
1
QueryGetCredDefResponse{
2
    "cred_def": {
3
            "signature_type": "CL",
4
            "schema_id": "schema:GEzcdDLhCpGCYRHW82kjHd:Degree:1.0",
5
            "tag": "some_tag",    
6
            "cred_def": {
7
                "primary": "...",// Primary
8
                "revocation": "..." // Revocation registry
9
        },
10
}
Copied!