Create a TnT Doc

The Track and Trace API is used to timestamp documents and write events on top of them. The timestamp can be taken from the blockchain or can be linked to external sources with their corresponding proof. With this guide, you will be able to create a document, grant access to other accounts, and write events.

The general process will be as follows:

info

Consult the Track and Trace API page for API instructions on how to register a Track and Trace document or event onto the EBSI ledger.

Request permission to be a creator

Contact the Support Office or the authorised authority to list your legal entity in the DID Registry to create documents. Once this is done, you can check if you are a creator by running the following.

API CALL

Check whether your DID is allow-listed as a creator with Check access (HEAD /track-and-trace/v1/accesses?creator={did}). A 204 response confirms you can create documents; 404 means your DID is not yet listed.

Request access token

Request an access token to the authorisation API with the scope tnt_create.

API CALL

Request an access token with the scope openid tnt_create by following the Access Control flow:

• GET Presentation definition: fetch the presentation definition for the scope.
• POST Token endpoint: submit a presentation matching the definition to obtain the token.

Create document

1. Create the document.
2. To create a document with external metadata define the timestamp and the hash of the external proof at the end.
3. Get the document from the blockchain.

API CALL

Build the document-creation transaction with the createDocument method of the Track and Trace JSON-RPC API, then sign and submit it with the sendSignedTransaction method (see Signing and submitting transactions). To anchor an external timestamp instead of the block time, include the timestamp (its datetime and source: external) together with the timestampProof.

Read the document back with Get a document (GET /track-and-trace/v1/documents/{documentId}).

Output

{
  "metadata": "my-metadata",
  "timestamp": {
    "datetime": "0x65920080",
    "source": "external",
    "proof": "0xae3e3d2c20698c1ebf7888b3c965cf1f30834307b7396b966c9abc11996e13ef"
  },
  "creator": "did:ebsi:zkrLJ5WyqiHbiXjur3TqzfA"
}

success

Congratulations! You have registered a document in Track and Trace.

Grant access

Now let's grant access to other account to write events in the document.

Request access token

Request an access token to the authorisation API with the scope tnt_write.

API CALL

Request an access token with the scope openid tnt_write by following the Access Control flow:

• GET Presentation definition: fetch the presentation definition for the scope.
• POST Token endpoint: submit a presentation matching the definition to obtain the token.

Grant access to other account

1. Grant access for "write" (to write events) or "delegate" (with this permission the subject can grant write access to other accounts).
2. Get the accesses linked to the document.

API CALL

Build the grant transaction with the grantAccess method of the Track and Trace JSON-RPC API, then sign and submit it with the sendSignedTransaction method. Grant write to let an account add events, or delegate to also let it grant write access to others. Only the creator can grant delegate; the creator or a delegate can grant write.

List the document's accesses with List accesses (GET /track-and-trace/v1/documents/{documentId}/accesses).

Output

{
  "items": [
    {
      "subject": "did:ebsi:zkrLJ5WyqiHbiXjur3TqzfA",
      "grantedBy": "did:ebsi:zkrLJ5WyqiHbiXjur3TqzfA",
      "permission": "creator",
      "documentId": "0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c"
    },
    {
      "subject": "did:ebsi:znbuGDt6tEqpGZNAuGc2uvZ",
      "grantedBy": "did:ebsi:zkrLJ5WyqiHbiXjur3TqzfA",
      "permission": "write",
      "documentId": "0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c"
    }
  ]
}

success

Congratulations! You have granted access to other account to write events.

Write an event

Request access token

Request an access token to the authorisation API with the scope tnt_write.

API CALL

Request an access token with the scope openid tnt_write by following the Access Control flow:

• GET Presentation definition: fetch the presentation definition for the scope.
• POST Token endpoint: submit a presentation matching the definition to obtain the token.

Write event

1. To write an event, define the arguments in the following order: documentHash, externalHash, sender, origin, metadata, and optionally timestamp and timestampProof.
2. Get the document from the blockchain to see the events.

API CALL

Build the event transaction with the writeEvent method of the Track and Trace JSON-RPC API, then sign and submit it with the sendSignedTransaction method. The event takes documentHash, externalHash, sender, origin, and metadata, plus an optional external timestamp and timestampProof.

List the document's events with List events (GET /track-and-trace/v1/documents/{documentId}/events).

Output

{
  "metadata": "my-metadata",
  "timestamp": {
    "datetime": "0x65920080",
    "source": "external",
    "proof": "0xae3e3d2c20698c1ebf7888b3c965cf1f30834307b7396b966c9abc11996e13ef"
  },
  "creator": "did:ebsi:zkrLJ5WyqiHbiXjur3TqzfA"
}

success

Congratulations! You have submitted an event to a document.