Topaz API

  • Version: 0.2.1
  • Host: api.topaz.io/v1
  • Protocols: https
More Info

Topaz API Spec

To get up and running with Topaz API as quickly as possible, read through these docs.

Prerequisites

Create an account at https://topaz.io, log in, and generate an API Token.

You’ll need an API Token to create a new app, create objects, create hashes, and view proofs.

All API requests should be prefixed with /v1, indicating that you’re targeting version 1 of our API.

Guarantee

Topaz API follows Semantic Versioning (https://semver.org), so expect that any breaking changes will be versioned under a new route prefix.

Getting Started

This short tutorial is the best way to learn how to use Topaz to create truth-first applications.

Create your first app

Apps are the way that Topaz organizes collections of critical data. You’re more than welcome to make many apps with a single account so you can keep you data organized.

Apps take two arguments, name, and interval.

interval refers to the frequency, in seconds, at which your app’s data will be timestamped on a blockchain.

*Free tier minimum interval is 60 seconds.

CREATE NEW APP

We’re going to make an app called backup with an interval of 60.

$ curl -X POST \
  http://localhost:8090/v1/apps \
  -H 'Authorization: Bearer 2FRv2pWdXSCqjuo4mNnNkKLJXpxuLsGfCUc6TbS9RNj8' \
  -H 'Content-Type: application/json' \
  -d '{ 
      "name": "backup", 
      "interval": 60 
  }'

RESPONSE BODY

If your app was created successfully, the API response should look like this.

{
  "id": "195dfefa-190d-49df-bebe-0d4e24be242b",
  "interval": 60,
  "name": "backup",
  "userId": "a0ec2f24-6529-410d-a9df-a6a5612b3e7b"
}

Create a file to secure

For the sake of this tutorial, we are going to secure a document called backup.txt using Topaz. You can use any file you’d like.

CREATE A NEW FILE

$ touch backup.txt
$ echo "bank account snapshot" > backup.txt
$ cat backup.txt
> bank account snapshot

Create an object for backup.txt

Objects are the way Topaz records new things. An object could be a document, transaction, physical asset, or just an entry in a database. The important concept to understand is that an object refers to a specific, real thing.

Every piece of data you wish to secure using Topaz should start as an object.

CREATE NEW OBJECT

We’re going to make an object to represent backup.txt.

$ curl -X POST \
  http://localhost:8090/v1/apps/{appId}/objects \
  -H 'Authorization: Bearer 2FRv2pWdXSCqjuo4mNnNkKLJXpxuLsGfCUc6TbS9RNj8'

RESPONSE BODY

If your object was created successfully, the API response should look like this.

{
  "id": "dd4177b2-310c-4b24-affc-5ff9cd20ae65",
  "appId": "195dfefa-190d-49df-bebe-0d4e24be242b"
}

Create a hash for the backup.txt object

Hashes are the recorded state of an object at a specific point in time. The hash literally is the SHA-256 hash of an object.

Topaz uses the Multihash format, which means that you may choose to use a different hashing algorithm if you choose, and Topaz will be compatible.

Learn more about Multihash here. To start using Multihash to create hashes yourself, first make sure Golang is installed on your machine.

INSTALL THE MULTIHASH TOOL

We’re using the Golang package manager to install multihash.

$ go get github.com/multiformats/go-multihash/multihash

CREATE NEW SHA-256 HASH

Let’s do a SHA-256 hash of backup.txt, and get its Base58 representation. multihash defaults to the SHA-256 algorithm, and Base58 encoding. Learn about more options with multihash --help.

$ cat backup.txt | multihash
> QmbBGyMmBtKFTTSbewEkNrr73rEKLdHetsaM8JmEHAuDac

CREATE HASH IN TOPAZ

Next, let’s create a corresponding hash in Topaz.

$ curl -X POST \
  http://localhost:8090/v1/apps/{appId}/objects/{objectId}/hashes \
  -H 'Authorization: Bearer 2FRv2pWdXSCqjuo4mNnNkKLJXpxuLsGfCUc6TbS9RNj8' \
  -H 'Content-Type: application/json' \
  -d '{ 
      "hash": "QmbBGyMmBtKFTTSbewEkNrr73rEKLdHetsaM8JmEHAuDac"
  }'

RESPONSE BODY

If your hash was created successfully, the API response should look like this

{
  "id": "90b228e4-8578-4511-9b7f-5709dd1d8ce5",
  "unixTimestamp": 1551886825,
  "objectId": "dd4177b2-310c-4b24-affc-5ff9cd20ae65",
  "proofId": null,
  "hash": "QmbBGyMmBtKFTTSbewEkNrr73rEKLdHetsaM8JmEHAuDac"
}

Check that the hash has been added to the backup.txt object

Let’s see how the hash and object are related. Go ahead and check out what our object looks like now.

GET OBJECT

The API response should look like this

$ curl -X GET \
  http://localhost:8090/v1/apps/{appId}/objects/{objectId} \
  -H 'Authorization: Bearer 2FRv2pWdXSCqjuo4mNnNkKLJXpxuLsGfCUc6TbS9RNj8'

RESPONSE BODY

As you can see, the hash is now associated with the object, and is the first entry in the hashes history of the object we created.

{
  "id": "dd4177b2-310c-4b24-affc-5ff9cd20ae65",
  "appId": "195dfefa-190d-49df-bebe-0d4e24be242b",
  "hashes": [
    {
      "id": "90b228e4-8578-4511-9b7f-5709dd1d8ce5",
      "hash": "QmbBGyMmBtKFTTSbewEkNrr73rEKLdHetsaM8JmEHAuDac"
    }
  ]
}

Check that the hash has made it to the Ethereum network

Remember when you declared an interval for your app earlier?

Topaz uses intervals to secure data on blockchains while avoiding expensive transaction fees and scaling issues.

Every time an interval completes, we generate a cryptographic proof for all of the hashes that occurred during that interval and send it to a blockchain.

GET HASH

Let’s inspect the hash we uploaded.

$ curl -X GET \
  http://localhost:8090/v1/apps/{appId}/objects/{objectId}/hashes/{hashId} \
  -H 'Authorization: Bearer 2FRv2pWdXSCqjuo4mNnNkKLJXpxuLsGfCUc6TbS9RNj8'

RESPONSE BODY

If your hash.proofId is populated, the response should look something like this

*If your hash.proofId is null, your app hasn’t completed an interval cycle yet.

{
  "id": "90b228e4-8578-4511-9b7f-5709dd1d8ce5",
  "unixTimestamp": 1551886825,
  "objectId": "dd4177b2-310c-4b24-affc-5ff9cd20ae65",
  "proofId": "64c91b09-7941-4924-b8e8-b7599f790d08",
  "hash": "QmbBGyMmBtKFTTSbewEkNrr73rEKLdHetsaM8JmEHAuDac"
}

Retrieve the proof information for a hash

Now that the hash has been timestamped on a blockchain, we can retrieve information about it at any time for data verification purposes.

GET PROOF

First, get the proof for the hash

$ curl -X GET \
  http://localhost:8090/v1/apps/{appId}/proofs/{proofId} \
  -H 'Authorization: Bearer 2FRv2pWdXSCqjuo4mNnNkKLJXpxuLsGfCUc6TbS9RNj8'

RESPONSE BODY

The blockchainTransactions array contains information that is used to define the moment in time at which your hash was stored on a blockchain. Check out one of the linked explorers to verify that the hex-encoded hash on the blockchain matches the Base58 encoded hash from the proof.

*While Topaz is a blockchain-agnostic platform, our free tier runs on the Ethereum Görli testnet.

{
  "id": "64c91b09-7941-4924-b8e8-b7599f790d08",
  "unixTimestamp": 1551886855,
  "appId": "195dfefa-190d-49df-bebe-0d4e24be242b",
  "hashes": [
    {
      "id": "90b228e4-8578-4511-9b7f-5709dd1d8ce5",
      "hash": "QmbBGyMmBtKFTTSbewEkNrr73rEKLdHetsaM8JmEHAuDac"
    }
  ],
  "blockchainTransactions": [
    {
      "blockchainNetwork": "ethereum goerli",
      "transactionHash": "0x8cfdf5172198034db70fc326e23b92dae9c23f4c3a542ecbbe5391f67dd277ba",
      "explorers": [
        "https://goerli.etherscan.io/tx/0x8cfdf5172198034db70fc326e23b92dae9c23f4c3a542ecbbe5391f67dd277ba",
        "https://blockscout.com/eth/goerli/tx/0x8cfdf5172198034db70fc326e23b92dae9c23f4c3a542ecbbe5391f67dd277ba/internal_transactions"
      ]
    }
  ],
  "merkleRoot": "0x1220635f3f90f43599e7c461928729357b932ebf3c5cce29b1e59737debc698b6993",
}

Verify data against the hash

Now that the hash is secured, we can cross reference it with backup.txt.

VERIFY SHA-256 HASH

As long as the file hash remains identical to the hash of its corresponding object, we can verify the data has not been corrupted since the time the proof was created.

$ cat backup.txt | multihash
> QmbBGyMmBtKFTTSbewEkNrr73rEKLdHetsaM8JmEHAuDac

Alter your data

Let’s go ahead and edit our file, and see what the new hash is.

As you can see, the hash no longer matches the hash first added to the backup.txt object.

Of course, in real life, almost no data is static. Amendments and changes happen all the time, so we enable amending data in a secure way by recording it.

EDIT FILE

Since we’re making a change, we’re going to amend the object with our new file hash.

$ echo "bank account snapshot, next month" > backup.txt
$ cat backup.txt | multihash
> QmY8bvrcK86jEXKPZ27RKMs5qE2U3yASx8TTUL54X4M6uG

NEW HASH

$ curl -X POST \
  http://localhost:8090/v1/apps/{appId}/objects/{objectId}/hashes \
  -H 'Authorization: Bearer 2FRv2pWdXSCqjuo4mNnNkKLJXpxuLsGfCUc6TbS9RNj8' \
  -H 'Content-Type: application/json' \
  -d '{ 
      "hash": "QmY8bvrcK86jEXKPZ27RKMs5qE2U3yASx8TTUL54X4M6uG"
  }'

RESPONSE BODY

If your hash was created successfully, the response should look something like this.

*In your own programs, you’d probably want to keep a copy of your original file, instead of amending it directly, so you can track and verify its changes over time.

{
  "id": "6628dea3-5675-4f50-9b6c-afa82947da97",
  "unixTimestamp": 1551886935,
  "objectId": "dd4177b2-310c-4b24-affc-5ff9cd20ae65",
  "proofId": null,
  "hash": "QmY8bvrcK86jEXKPZ27RKMs5qE2U3yASx8TTUL54X4M6uG"
}

Verify data against the hash

FILE HASH

Here’s the new hash of backup.txt again.

$ cat backup.txt | multihash
> QmY8bvrcK86jEXKPZ27RKMs5qE2U3yASx8TTUL54X4M6uG

GET OBJECT

And here’s the amended object

$ curl -X GET \
  http://localhost:8090/v1/apps/{appId}/objects/{objectId} \
  -H 'Authorization: Bearer 2FRv2pWdXSCqjuo4mNnNkKLJXpxuLsGfCUc6TbS9RNj8' \

RESPONSE BODY

Hooray! As you can see, the file hash of backup.txt is now identical to the object’s last hash. This process can be used to verify the integrity of backup.txt to the timestamp of the latest hash.

{
  "id": "dd4177b2-310c-4b24-affc-5ff9cd20ae65",
  "appId": "195dfefa-190d-49df-bebe-0d4e24be242b",
  "hashes": [
    {
      "id": "90b228e4-8578-4511-9b7f-5709dd1d8ce5",
      "hash": "QmbBGyMmBtKFTTSbewEkNrr73rEKLdHetsaM8JmEHAuDac"
    },
    {
      "id": "6628dea3-5675-4f50-9b6c-afa82947da97",
      "hash": "QmY8bvrcK86jEXKPZ27RKMs5qE2U3yASx8TTUL54X4M6uG"
    }
  ]
}

Conclusion

  • Created a new app
  • Created a file to secure
  • Created an object to represent the file
  • Created an initial hash for the object
  • Verified our data
  • Amended the file
  • Amended the object that represents the file, with a new hash
  • Verified our amended data

This workflow can be used to secure data in any app or business process. By integrating Topaz directly with software, we can create verifiable proofs of data over time and allow authorized users to amend them. This allows data to be secured by a blockchain without the complex technical requirements or cost of directly sending data to a blockchain.

We hope you enjoyed experimenting with Topaz!