Verify DataTrails SCITT Receipts

Proof of Posting Receipts for SCITT

What are receipts?#

Having a receipt for a DataTrails Event allows you to prove that you recorded the Event on the DataTrails Blockchain, independent of DataTrails.

Receipts can be retrieved for Simple Hash Events once they have been confirmed and anchored.

A user may get a receipt for any Event they have recorded on the system. You must be an Administrator for your Tenancy to retrieve receipts for any Event within the Tenancy, including those shared by other organizations.

Receipts for Public Events can be obtained by any authenticated API request.

Note: Receipts are currently an API-only feature. In order to obtain a receipt, you will need an App Registration.

What is in a receipt?#

The Receipts API is provided as an integration with emerging standards driven by Supply Chain Integrity, Transparency, and Trust (SCITT).

Regardless of how the standards evolve, any receipt you obtain today will remain valid proof of posting for the Event.

Warning: The complete contents of the Event are present in the receipt in clear text. If the Event information is sensitive, the receipt should be regarded as sensitive material as well.

The /archivist/v1/notary/claims/events API creates a SCITT claim for a DataTrails event.

In the SCITT model, this claim is then presented to a transparency service to obtain a receipt. When you present a claim to the /archivist/v1/notary/receipts API to obtain your receipt, DataTrails is acting as the transparency service and returns a (draft) standards-compatible receipt proving that you recorded your Event on the DataTrails Blockchain.

How do I retrieve and verify a receipt?#

Once retrieved, receipts are fully verifiable offline and without calls to the DataTrails system using independent OSS tooling.

However, for your convenience DataTrails provides a Python script that can be used to retrieve and verify a receipt. For full details, please visit our Python documentation.

Receipts can also be retrieved offline using curl commands. To get started, make sure you have an Access Token, Event ID, and jq installed.

First, save the identity of an event in EVENT_IDENTITY.

1. Get the transaction_id from the Event.

EVENT_TRANSACTION_ID=$(curl -s \
        -X GET -H "Authorization: Bearer ${TOKEN}" \
        https://app.datatrails.ai/archivist/v2/${EVENT_IDENTITY} \
        | jq -r .transaction_id)

The transaction_id is available once the event has been committed to the blockchain. For assets using the Simple Hash proof_mechanisms it is available once the event is included in an anchor.

1. Get a claim for the Event identity

   CLAIM=$(curl -s -d "{\"transaction_id\":\"${EVENT_TRANSACTION_ID}\"}" \
           -X POST -H "Authorization: Bearer ${TOKEN}" \
           https://app.datatrails.ai/archivist/v1/notary/claims/events \
           | jq -r .claim)
   

2. Next, get the corresponding receipt for the claim

   RECEIPT=$(curl -s -d "{\"claim\":\"${CLAIM}\"}" \
           -X POST -H "Authorization: Bearer ${TOKEN}" \
           https://app.datatrails.ai/archivist/v1/notary/receipts \
           | jq -r .receipt)
   

3. Get the block details Get the block number using:

   echo ${RECEIPT} | base64 -d | less
   

   Look for the first "block":"<HEX-BLOCK-NUMBER>" in the decoded output and set the value in the environment, for example: BLOCK="0x1234".

   Next, get the appropriate state root field from the block details. To verify a Simple Hash receipt get the stateRoot:

   WORLDROOT=$(curl -s -X GET -H "Authorization: Bearer ${TOKEN}" \
               https://app.datatrails.ai/archivist/v1/archivistnode/block?number="${BLOCK}" \
               | jq -r .stateRoot)
   

4. Finally, use the rkvst_receipt_scittv1 command to verify the receipt offline at any time.

   echo ${RECEIPT} | rkvst_receipt_scittv1 verify -d --worldroot ${WORLDROOT}