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

Create a document

Load the Legal Entity

Load the keys of the Legal Entity:

Command

==> using user ES256K did1 <PRIVATE_KEY_ES256K> <DID>
==> using user ES256 did1 <PRIVATE_KEY_ES256> <DID>

Now connect the wallet with the pilot environment:

Command

==> env pilot

Request permission to be a creator

Contact with Support Office or the authorised authority in order to list your legal entity in the authorised DIDs to create documents. Once it is done you can check if you are a creator by running:

Command

==> tnt head /accesses?creator= user.did

Request access token

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

Command

==> resAuthTNT: authorisation auth tnt_create_presentation ES256

Now load the access token:

Command

==> using token resAuthTNT.access_token

Create document

Create the document:

Command

==> tnt createDocument 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c my-metadata user.did

To create a document with external metadata define the timestamp and the hash of the external proof at the end:

Command

==> tnt createDocument 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c my-metadata user.did 2024-01-01 0xae3e3d2c20698c1ebf7888b3c965cf1f30834307b7396b966c9abc11996e13ef

Finally, get the document from the blockchain:

Command

==> tnt get /documents/0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c

Output

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

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:

Command

==> resAuthTNT: authorisation auth tnt_write_presentation ES256

Now load the access token:

Command

==> using token resAuthTNT.access_token

Grant access to other account

You can grant access for "write" (to write events) or "delegate" (with this permission the subject can grant write access to other accounts).

Command

==> tnt grantAccess 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c user.did did:ebsi:znbuGDt6tEqpGZNAuGc2uvZ write

Now get the accesses linked to the document:

Command

==> tnt get /documents/0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c/accesses

Output

{
  "self": "https://api-pilot.ebsi.eu/track-and-trace/v1/documents/0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c/accesses?page[after]=1&page[size]=10",
  "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"
    }
  ],
  "total": 2,
  "pageSize": 10,
  "links": {
    "first": "https://api-pilot.ebsi.eu/track-and-trace/v1/documents/0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c/accesses?page[after]=1&page[size]=10",
    "prev": "https://api-pilot.ebsi.eu/track-and-trace/v1/documents/0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c/accesses?page[after]=1&page[size]=10",
    "next": "https://api-pilot.ebsi.eu/track-and-trace/v1/documents/0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c/accesses?page[after]=1&page[size]=10",
    "last": "https://api-pilot.ebsi.eu/track-and-trace/v1/documents/0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c/accesses?page[after]=1&page[size]=10"
  }
}

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:

Command

==> resAuthTNT: authorisation auth tnt_write_presentation ES256

Now load the access token:

Command

==> using token resAuthTNT.access_token

Write event

To write an event define the arguments in this order: documentHash, externalHash, sender, origin, metadata, and optionally timestamp and timestampProof:

Command

==> tnt writeEvent 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c 0x9265031a923088137405ffc270a56bf2d4df87495eada46257352356071b009e user.did my-origin my-metadata

Finally, get the document from the blockchain to see the events:

Command

==> tnt get /documents/0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c

Output

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

Congratulations!

You have submitted an event to a document