Tutorials

Create a DID

In order to create a Ziden DID, you need to generate a random 32-byte PrivateKey.

Random 32-byte PrivateKey

import { auth } from '@zidendev/zidenjs';
import { randomBytes } from 'crypto';

const privateKey = randomBytes(32);
const auth = await auth.newAuthFromPrivateKey(privateKey);

Then, use our TS Package to generate your own Authentication Tree, and then you can extract your Genesis ID. This Genesis ID will be your unique DID in our ecosystem.

import { auth, db, state } from '@zidendev/zidenjs';
import { randomBytes } from 'crypto';

const privateKey = randomBytes(32);
const auth = await auth.newAuthFromPrivateKey(privateKey);

// setup level DB to store trees
const authDb = smt.SMTLevelDb('/path/to/your/authDb');
const claimDb = smt.SMTLevelDb('/path/to/your/claimDb');
const claimRevDb = smt.SMTLevelDb('/path/to/your/claimRevDb');

const identity = await state.State.generateState([auth], authDb, claimDb, claimRevDb);

Use can also use BIP39 and BIP32 libs to create your own HD wallets, for example:

GitHub - paulmillr/scure-bip32: Secure, audited & minimal implementation of BIP32 hierarchical deterministic (HD) wallets.GitHub

GitHub - paulmillr/scure-bip39: Secure, audited & minimal implementation of BIP39 mnemonic phrasesGitHub

Request for a new Claim

Claims are issued based on the specification of registered schemas, so to request a for a new claim, the Holder need to query information of registered Issuers to find the suitable schema registry.

Find all Issuer

Get all registered Issuers

GET/api/v1/issuers

Query parameters

Response

200

A JSON array of Issuer

Body

application/json

issuersarray of all of

Request

JavaScriptCurl

const response = await fetch('/api/v1/issuers', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "issuers": [
    {
      "issuerId": "82701632f563e84bcb34de9542d0457ff5cfb17bf9703f743afb93ba605cc6",
      "name": "Issuer's Name",
      "description": "Issuer's Description",
      "contact": "[e-mail]",
      "isVerified": false,
      "website": "https://ziden.io",
      "logoUrl": "https://logo.image.url",
      "endpointUrl": "https://issuer.endpoint.url/api/v1/registration"
    }
  ]
}

Find one Issuer

Query an registered Issuer by DID

GET/api/v1/issuers/{issuerId}

Path parameters

issuerId*string

DID of Issuer

Response

200

A JSON object of Issuer

Body

application/json

issuerIssuer (object)

Request

JavaScriptCurl

const response = await fetch('/api/v1/issuers/{issuerId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "issuer": {
    "issuerId": "82701632f563e84bcb34de9542d0457ff5cfb17bf9703f743afb93ba605cc6",
    "name": "Issuer's Name",
    "description": "Issuer's Description",
    "contact": "[e-mail]",
    "isVerified": false,
    "website": "https://ziden.io",
    "logoUrl": "https://logo.image.url",
    "endpointUrl": "https://issuer.endpoint.url/api/v1/registration"
  }
}

Each Issuer has their own list of registered Schema.

Find one Schema Registry

Query an registered Schema Registry by unique ID

GET/api/v1/registries/{registryId}

Path parameters

registryId*string

Unique ID of Schema Registry

Response

200

A JSON object of Schema Registry

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('/api/v1/registries/{registryId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

After they found the correct Schema Registry, the Holder need to provide information for the Issuer for the issuance of the Identity Claim.

Request create claim

Request create claim

POST/api/v1/claims/request/{issuerId}

Path parameters

issuerIdstring

issuerId

Body

application/json

holderIdstring

registryIdstring

publicKeystring

dataobject

Response

400default

Error

Body

application/json

errorstring

messagestring

Request

JavaScriptCurl

const response = await fetch('/api/v1/claims/request/{issuerId}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "error": "text",
  "message": "text"
}

The Holder will receive a unique ID for their newly created claim. They can use this to track the status of the claim, which can be one of the followings:

• Reviewing

• Pending

• Active

• Rejected

• Waiting

Get claim status

Get claim status

GET/api/v1/claims/{claimId}/status

Path parameters

claimIdstring

claimId

Response

400default

Error

Body

application/json

errorstring

messagestring

Request

JavaScriptCurl

const response = await fetch('/api/v1/claims/{claimId}/status', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "error": "text",
  "message": "text"
}

Accept a Claim

Besides directly request for issuance of new claims, the Holder can also accept pre-issued claims from Issuers. This approach fits for use cases where the Issuer wants to perform batch issuance for multiple Holders.

Query claims

Fetch claim's data

GET/api/v1/claims

Query parameters

Response

200

A JSON object

Body

application/json

claimsarray of object

Request

JavaScriptCurl

const response = await fetch('/api/v1/claims', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "claims": [
    {
      "claimId": "text",
      "status": "text",
      "schema": {
        "schemaHash": "text",
        "name": "text"
      },
      "issuer": {
        "issuerId": "text",
        "name": "text",
        "endpointUrl": "text"
      }
    }
  ]
}

The Holder can query all claims attached to their DID and check if there is any claim with the "Waiting" status. Then, they can use the unique ID of the claim to accept it.

Retrive claims data from claimId

Retrive claims data from claimId

GET/api/v1/claims/{claimId}/retrieve

Path parameters

claimIdstring

claimId

Response

400default

Error

Body

application/json

errorstring

messagestring

Request

JavaScriptCurl

const response = await fetch('/api/v1/claims/{claimId}/retrieve', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "error": "text",
  "message": "text"
}

Backup/Recover Claims

In order to backup user data, the Holder need encrypt their claims with a SecretKey before upload to the Backup Service to protect their data.

API for post data encrypt

API for post data encrypt

POST/api/v1/backup

Query parameters

Body

application/jsonapplication/xmlapplication/x-www-form-urlencoded

Your holderId, issuerId, claimId, data and nonce

holderIdstring

Holder

issuerIdstring

iusser

claimIdstring

claim

datastring

Your data encrypted by your DEK

noncestring

nonce

Response

default

API response

Body

application/jsonapplication/xmlapplication/x-www-form-urlencoded

statusinteger (int64)

messagestring

dataobject

Request

JavaScriptCurl

const response = await fetch('/api/v1/backup', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "message": "text"
}

After finishing backup, the Holder can fetch their data from the Backup Service and decrypt to use on other devices.

API for get data encrypt by holderId, issuerId or

API for post data encrypt

GET/api/v1/backup

Query parameters

Response

default

API response

Body

application/jsonapplication/xmlapplication/x-www-form-urlencoded

statusinteger (int64)

messagestring

dataobject

Request

JavaScriptCurl

const response = await fetch('/api/v1/backup', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "message": "text"
}

Therefore, we recommend using a separated backup password or a derived key from the Holder's auth to enable seamless experience across devices.

Generate ZKP for Attestations

Services are managed by Verifiers, so to utilize their claims, the Holder need to query information of registered Verifiers to find available services.

Find all Verifier

Get all registered Verifier

GET/api/v1/verifiers

Response

200

A JSON array of Verifier

Body

application/json

verifiersarray of Verifier (object)

Request

JavaScriptCurl

const response = await fetch('/api/v1/verifiers', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "verifiers": [
    {
      "_id": "82701632f563e84bcb34de9542d0457ff5cfb17bf9703f743afb93ba605cc6",
      "name": "Verifier's Name",
      "description": "Verifier's Description",
      "contact": "[e-mail]",
      "isVerified": false,
      "website": "https://ziden.io",
      "logoUrl": "https://logo.image.url"
    }
  ]
}

Find one Verifier

Query an registered Verifier by DID

GET/api/v1/verifiers/{verifierId}

Path parameters

verifierId*string

DID of Verifier

Response

200

A JSON object of Verifier

Body

application/json

verifierVerifier (object)

Request

JavaScriptCurl

const response = await fetch('/api/v1/verifiers/{verifierId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "verifier": {
    "_id": "82701632f563e84bcb34de9542d0457ff5cfb17bf9703f743afb93ba605cc6",
    "name": "Verifier's Name",
    "description": "Verifier's Description",
    "contact": "[e-mail]",
    "isVerified": false,
    "website": "https://ziden.io",
    "logoUrl": "https://logo.image.url"
  }
}

Each Verifier has their own list of registered Service.

Find one Service

Query an registered Service by unique ID

GET/api/v1/services/{serviceId}

Path parameters

serviceId*string

Unique ID of Service

Response

200

A JSON object of Service

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('/api/v1/services/{serviceId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

After they found Service they want, the Holder check if they meet the service's requirements. If yes, they should fetch all the necessary inputs for the proof generation process.

Query proof input

Query proof input

GET/api/v1/claims/{claimId}/proof

Path parameters

claimId*string

id of claim

Query parameters

Response

400default

Error

Body

application/json

errorstring

messagestring

Request

JavaScriptCurl

const response = await fetch('/api/v1/claims/{claimId}/proof', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "error": "text",
  "message": "text"
}

Generate ZK proof request

Generate request for ZK proof generation

POST/api/v1/proofs/request

Body

application/json

Data for generating proof generation request

serviceIdstring

Response

200

Unique ID of Request

Body

application/json

requestProofRequest (object)

Request

JavaScriptCurl

const response = await fetch('/api/v1/proofs/request', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "request": {
    "requestId": "text",
    "serviceId": "text",
    "message": "text",
    "validUntil": "2024-04-28T22:09:24.362Z",
    "zkProofs": [
      {
        "publicData": []
      }
    ]
  }
}

In order to generate a ZKP proof for attestation, they need to use the TS Package.

import { queryMTP, claim, auth } from '@zidendev/zidenjs';
const { newClaim, schemaHashFromBigInt, withSlotData, withIndexID } = claim;

const holderPrivateKey = // mock here
const holderAuth = await auth.newAuthFromPrivateKey(holderPrivateKey);
const query1 = {
  slotIndex: 2,
  operator: OPERATOR.LESS_THAN,
  values: [BigInt(20040101)],
  valueTreeDepth: 6,
  from: 10,
  to: 100,
  timestamp: Date.now(),
  claimSchema: BigInt(12394),
};

const slot1 = setBits(BigInt(0), query1.from, BigInt(20010101));

const claim1 = newClaim(
  schemaHashFromBigInt(query1.claimSchema),
  withSlotData(query1.slotIndex, numToBits(slot1, 32)),
  withIndexID(holderState.userID)
);

// issuer side: grant kycGenerateQueryMTPInput for holder once issued
const kycQueryMTPInput = await kycGenerateQueryMTPInput(claim1.hiRaw(), issuerState);

// issuer side: grant kycGenerateNonRevQueryMTPInput for holder when asked
const kycNonRevQueryMTPInput = await kycGenerateNonRevQueryMTPInput(claim1.getRevocationNonce(), issuerState);
// holder side: generate queryMTP proof on their claim
const witness = await holderGenerateQueryMTPWitnessWithPrivateKey(
  claim1,
  holderPrivateKey,
  holderAuth,
  BigInt(1),
  holderState,
  kycQueryMTPInput,
  kycNonRevQueryMTPInput,
  query1
);

After successfully generated a valid attestation proof, the Holder need to upload it to the Portal Service for the Verifier.

Verify ZK Proof

Verify ZK proofs

POST/api/v1/proofs/verify

Body

application/json

A JSON array of Proof

networkIdstring

proofsarray of Proof (object)

Response

200

An array of verification result

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('/api/v1/proofs/verify', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Submit ZK Proof

Submit ZK proofs for verification

POST/api/v1/proofs/submit

Body

application/json

A JSON array of Proof

requestIdstring

proofsarray of Proof (object)

Response

200

An array of verification result

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('/api/v1/proofs/submit', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Share attestation verification results

Moreover, the Holder can also directly share the verification result of the attestation proof to others.

Fetch ZK proof

Fetch ZK proof for a request

GET/api/v1/proofs/{requestId}

Path parameters

requestId*string

Unique ID of a request

Response

200

A JSON of proof request

Body

application/json

requestProofRequest (object)

Request

JavaScriptCurl

const response = await fetch('/api/v1/proofs/{requestId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "request": {
    "requestId": "text",
    "serviceId": "text",
    "message": "text",
    "validUntil": "2024-04-28T22:09:24.362Z",
    "zkProofs": [
      {
        "publicData": []
      }
    ]
  }
}

Resources

pageIdentity SDK

pageServices' API Specification

ziden-devGitHub