Quick Start

This guide is intended to get you started with using Chronicle as quickly as possible. It will walk you through the process of installing the Typescript Chronicle client and using it to generate and verify provenance for a simple data payload. It should take no more than 5 minutes to complete, and will leave you with a basic understanding of how to integrate with Chronicle for your own application.

Feel free to skip to the tldr if you want to go really fast.

Prerequisites

This document assumes an intermediate understanding of blockchain-based applications and Typescript development. You should be comfortable with things like installing packages, running Typescript, calling APIs, and reasoning about basic cryptography.

note

The instructions assume you're starting in a fresh Typescript environment, such as this repl which uses bun, but the basic steps should be transferrable to any environment with Javascript or Typescript support.

Speedrun

We're going to write some Typescript to:

1. hash a simple data payload we want to post to Chronicle
2. post the hash, and receieve a Chronicle checkpoint and proof for it
3. verify the checkpoint and proof

Let's get started!

Install, import, and instantiate the Chronicle client

Run the following command to install the Typescript Chronicle SDK:

bun add @chroniclewtf/client

Then import it into an empty index.ts file and initialize your instance:

import { ChronicleClient } from "@chroniclewtf/client";

const chronicle = new ChronicleClient();

Hash your data paylaod

// In this example we'll use a simple string as our data payload.
// Helper method for getting the hash of a string.
const leafHash = client.hash("check the chain");

Post the leaf to Chronicle & wait for a checkpoint

// Post the leafHash to the server.
const { leafIndex } = await client.postLeaf(leafHash);
console.log(`Posted leaf ${leafHash} at index ${leafIndex}`);

// Wait for the data to be included in an onchain checkpoint.
const { rootHash, treeSize } = await client.waitForCheckpointedLeafIndex(
    leafIndex,
);
console.log(
    `Leaf ${leafHash} was included in checkpoint ${rootHash} at tree size ${treeSize}`,
);

Get and verify the proof

// Get the proof for the leaf:
const proof = await client.getProofForLeafHash(
    leafHash,
    // Optional param to target your proof to a particular tree size.
    treeSize,
);
console.log(
    `Got proof for leaf ${leafHash} with target root ${proof.targetRootHash}`,
);

// Or shorthand for the above:
// const proof = await client.postLeafAndGetProof(leafHash);

// Verify proof against the server. Note that it's typically recommended to use
// the Chronicle contract onchain for verification.
const { success } = await client.verifyProofServer(proof);
console.log(`Proof is valid: ${success}`);

tldr

Here's the final result:

import { ChronicleClient } from "@chroniclewtf/client";

// Instantiate a new client, default params should suffice for now.
const client = new ChronicleClient();

// Helper method for getting the hash of a string.
const leafHash = client.hash("check the chain");

// Post the leafHash to the server.
const { leafIndex } = await client.postLeaf(leafHash);
console.log(`Posted leaf ${leafHash} at index ${leafIndex}`);

// Wait for the data to be included in an onchain checkpoint.
const { rootHash, treeSize } = await client.waitForCheckpointedLeafIndex(
    leafIndex,
);
console.log(
    `Leaf ${leafHash} was included in checkpoint ${rootHash} at tree size ${treeSize}`,
);

const proof = await client.getProofForLeafHash(
    leafHash,
    // Optional param to target your proof to a particular tree size.
    treeSize,
);
console.log(
    `Got proof for leaf ${leafHash} with target root ${proof.targetRootHash}`,
);

// Or shorthand for the above:
// const proof = await client.postLeafAndGetProof(leafHash);

// Verify proof against the server. Note that it's typically recommended to use
// the Chronicle contract onchain for verification.
const { success } = await client.verifyProofServer(proof);
console.log(`Proof is valid: ${success}`);

You can also play with the final code sample in this repl.

Next Steps

Now that you have a basic understanding of Chronicle, it's time to delve deeper. You can further explore the API section for a better idea of integrating Chronicle into your application. Alternatively, you can check out the Concepts section to to learn more about the theory behind Chronicle.