Track and Trace Introduction

This page presents the functional architectrue of EBSI's Track & Trace core service.

What it is

The Track and Trace (TnT) service records the full lifecycle of a document on the EBSI ledger. Where the Timestamp service answers "did this data exist at time T?", the TnT service answers "what happened to this document, by whom, and in what order?".

The TnT service consists of two components: the Track & Trace API and the Track & Trace smart contract. The Track & Trace smart contract is deployed on the EBSI ledger, whilst the Track & Trace API enables interaction with the Track & Trace smart contract to:

• Create immutable records of data with unique hashes.
• Manage access permissions.
• Facilitate version control for tracking changes over time.

Every significant event (creation, update, access grant) is recorded as an immutable entry on-chain, linked to the identity of its corresponding TnT document. The result is a Proof of Origin: a verifiable, chronologically ordered chain of events tied to identifiable actors.

Core concepts

Document

A TnT document is an on-chain record identified by a unique document ID (derived from a hash of the document content). It is created by a creator: a legal entity whose DID has been whitelisted in the DID Registry for TnT write access.

The document record holds:

• A reference to the document content (via metadata and hash).
• The creator DID.
• A timestamp, either sourced from the EBSI blockchain or linked to an external source with a cryptographic proof.

Events

After creation, authorised parties write events to the document. Each event records:

• The document hash at the time of the event.
• An optional external hash (for linking to data outside EBSI).
• The sender DID.
• An origin identifier.
• Metadata.
• A timestamp (blockchain or external, with optional proof).

Events are append-only. Once written they cannot be modified or deleted, forming an immutable audit trail.

Access management

TnT has built-in, DID-based access control:

Permission	What it allows
creator	Automatically held by the document creator; can write events and grant access.
write	Write events to the document.
delegate	Write events and grant write access to other accounts.

Access is scoped per document. A legal entity can hold different permissions on different documents.

How it works

The Track and Trace API sits in front of the Ethereum Track and Trace smart contract on the EBSI ledger. The Track and Trace API implements two types of APIs:

• JSON-RPC APIs: Write operations (create document, grant access, write event) are signed JSON-RPC transactions.
• REST APIs: read operations (query documents, events, accesses) use REST.

Access requires a token from the EBSI Authorisation Service:

• tnt_create scope: to create a new document.
• tnt_write scope: to write events and manage access.

Creator → Authorisation API (tnt_create token)
        → TnT API (create document)
        → EBSI Ledger smart contract (immutable record)

Writer  → Authorisation API (tnt_write token)
        → TnT API (write event)
        → EBSI Ledger smart contract (appended event)

Timestamps from the blockchain vs external

TnT supports two timestamp sources:

• Blockchain timestamp: the block timestamp from the EBSI ledger is used. The timestamp is automatically set by the network when the transaction is included in a block.
• External timestamp: the submitter provides a datetime value and a cryptographic proof tying it to an external time authority. This allows anchoring events that occurred outside EBSI to the on-chain record.

Use cases

• Credential lifecycle tracking: record when a VC schema was published, updated, and deprecated, with each change attributed to its author.
• Document provenance: build an auditable history of who processed a document and when, useful for regulatory compliance.
• Supply chain events: anchor production, transfer, and delivery events for physical or digital assets.
• Policy versioning: create a verifiable record of which policy version was in force at each point in time, with the identity of each editor.

Further reading

• Create a TnT Document: step-by-step implementation guide.
• Track and Trace API reference: full endpoint documentation.