Skip to main content

Track and Trace

This page presents the functional architecture of EBSI's Track and Trace core service.

What it is​

The Track and Trace 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 Track and Trace service answers "what happened to this document, by whom, and in what order?".

The Track and Trace smart contract is deployed on the EBSI ledger, whilst the Track and Trace Service exposes the data through a convenient REST API.

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

Core concepts​

Document​

A Track and Trace 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 Track and Trace 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​

Track and Trace has built-in, DID-based access control:

PermissionWhat it allows
creatorAutomatically held by the document creator; can write events and grant access.
writeWrite events to the document.
delegateWrite 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.

Write operations to the smart contract require an access token from the Authorisation Service:

  • track-and-trace:create scope: to create a new document.
  • track-and-trace:write scope: to write events and manage access.
Creator → Authorisation Service (track-and-trace:create token)
        → Ledger Service (create document in Track and Trace smart contract)
        → EBSI Ledger smart contract (immutable record)

Writer  → Authorisation Service (track-and-trace:write token)
        → Ledger Service (write event in Track and Trace smart contract)
        → EBSI Ledger smart contract (appended event)

Timestamps from the blockchain vs external​

Track and Trace 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​

Last updated on