Anchors

Anchoring allows users to store a digest of one or more credentials (or any document) on our blockchain, tying them to immutable timestamps and proving that they were generated at a certain moment in time. By enabling this feature, users will have more options for auditing credentials given and timestamping any documents.

The Dock Blockchain includes a module explicitly intended for proof of existence. You post the hash of a document on-chain at a specific block. Later you can use that hash to prove the document existed at or before that block.

The API allows you to create, get, and retrieve anchors as well as a list of all anchors created by the user.

For a detailed example of the anchor workflow. Please refer here.

Endpoints

POST /anchors GET /anchors GET /anchors/{anchor}

Create Anchor

Creating an anchor will state on the blockchain that one or more document hashes were created at a specific time. In the context of verifiable credentials, anchors are used to attest that the credential document was not altered and was created at a specific time. Batching multiple documents/credentials into a single anchor is done through a Merkle tree and can save on cost/time as only the Merkle root has to be anchored.

The API will store the blake2b256 hash of a document or string that you provide. Dock provides a fully functioning reference client and SDK example for anchoring.

Parameters

Name	In	Type	Required	Description
body	body	array of strings or JSON	true	Supply an array of strings or JSON documents to be hashed and anchored to the blockchain. For credentials, send the Verifiable Credential document(s) or anchor when issuing.

Responses

200	OK	The request was successful and will try to create an anchor on the blockchain.	JobId
400	Bad Request	The request was unsuccessful, because of invalid params.	Error
402	Payment required	Transaction limit reached or upgrade required to proceed	Error

POST /anchors REQUEST PAYLOAD

[
  "can be a string",
  {
    "or": "a JSON document"
  }
]

POST /anchors REQUEST CURL

curl --location --request POST https://api.dock.io/anchors \

  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '[
  "can be a string",
  {
    "or": "a JSON document"
  }
]'

200 Response

{
  "id": "829",
  "data": {
    "root": "0xdfc3cd9ff7836143746c292d4099e62277fac4c2b6a1c004d784adcbc0319634",
    "proofs": []
  }
}

List Anchors

Return a list of all anchors created by the authenticated user, regardless of whether they have contributed to the batching or not.

Parameters

Name	In	Type	Required	Description
offset	query	integer	false	How many items to offset by for pagination
limit	query	integer	false	How many items to return at one time (max 64)

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful and will return all anchors created by the user.	Inline
402	Payment required	Transaction limit reached or upgrade required to proceed	Error

GET /anchors REQUEST CURL

curl --location --request GET https://api.dock.io/anchors \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

200 Response

[
  {
    "anchor":"54bdd55207c4d41d2b8a7780e967bb5a06bdfb793fc4055baf244e60cd0d839c",
    "type": "single",
    "data": {
      "proofs": [],
      "root":"0x54bdd55207c4d41d2b8a7780e967bb5a06bdfb793fc4055baf244e60cd0d839c",
      "documentIds": [
        "https://creds.dock.io/credential/b1ed680d3d2d8167dc31bc4913e9c511"
      ]
     },
     "created_at": "2021-11-12T13:53:51.640Z",
     "job_id": "827"
  }
]

Get Anchor

Get a specific anchor with the given ID.

Parameters

Name	In	Type	Required	Description
anchor	path	Hex32	true	An anchor id.

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful and returns the anchor's details, e.g., blockHash and root.	Anchor
404	Not Found	The request was unsuccessful, because the anchor was not found.	Error
402	Payment required	Transaction limit reached or upgrade required to proceed	Error

GET /anchors/{anchor} REQUEST CURL

curl --location --request GET https://api.dock.io/anchors/{anchor} \
  --header 'DOCK-API-TOKEN: API_KEY'
  --data-raw ''

200 Response

{
  "type": "single",
  "proofs": [],
  "root": "0x00",
  "created_at": "2021-11-30T15:47:24.667Z"
}

Verify Anchor

Verify an anchor's merkle root and proof by supplying the source documents (array of strings of JSON objects, same as in anchor creation).

Parameters

Name	In	Type	Required	Description
documents	body	array of strings or JSON	true	An array of strings or JSON objects to represent documents to be hashed
proofs	body	JSON object array	true	An array of proofs given on anchor creation
root	body	Hex32	true	The anchor merkle root/ID.

Responses

Status	Meaning	Description	Schema
200	OK	The request was successful and returns the anchor's details, e.g., blockHash and root.	Anchor
402	Payment required	Transaction limit reached or upgrade required to proceed	Error

POST /verify REQUEST PAYLOAD

{
  "documents": [],
  "proofs": [],
  "root": "0x00"
}

POST /verify REQUEST CURL

curl --location --request POST https://api.dock.io/anchors \

  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '[
  "can be a string",
  {
    "or": "a JSON document"
  }
]'

200 Response

{
  "verified": true,
  "results": [
    {}
  ]
}