Quick Start

This guide is intended to get you started with using Witness as quickly as possible. It will walk you through the process of installing the Typescript Witness client and using it to generate and verify proofs 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 Witness 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 (opens in a new tab) development. You should be comfortable with things like installing packages, running Typescript, calling APIs, and reasoning about basic cryptography.

💡

The instructions assume you're starting in a fresh Typescript environment, 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 submit to Witness
  2. Post the hash, and receieve a proof
  3. Verify the proof

Install, import, and instantiate the Witness client

Run the following command to install the Typescript Witness SDK:

bun add @witnessco/client

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

import { WitnessClient } from "@witnessco/client";
 
// Instantiate a new client, default params should suffice for now.
const witness = new WitnessClient();

Hash your data paylaod

 
// Use an existing sample string to quickly get a proof for a pre-existing leaf.
const sampleString = "Check the chain!";
// Or use a unique string, so we get an unseen leafHash.
// Note that this means we'll have to wait for the proof to be ready.
// const sampleString = `Check the chain! @ ${Date.now()}`
// Useful helper method for getting the hash of a string.
const leafHash = witness.hash(sampleString);

Post the leaf to Witness & wait for a checkpoint

// Post the leafHash to the server.
await witness.postLeaf(leafHash);
// Wait for the data to be included in an onchain checkpoint.
await witness.waitForCheckpointedLeafHash(leafHash);

Get the timestamp

// Get the timestamp for the leaf.
const timestamp = await witness.getTimestampForLeafHash(leafHash);
console.log(`Leaf ${leafHash} was timestamped at ${timestamp}`);

Don't trust, verify

// Get the proof for the leaf.
const proof = await witness.getProofForLeafHash(leafHash);
// Verify the proof against the chain.
// You can optionally supply your own chain RPC endpoint for this method.
// Defaults to a public Base RPC node.
const verifiedChain = await witness.verifyProofChain(proof); 
console.log({ verifiedChain });

tldr

Here's the final result:

import { WitnessClient } from "@witnessco/client";
 
// Instantiate a new client, default params should suffice for now.
const witness = new WitnessClient();
 
// Helper method for getting the hash of a string.
const sampleString = `Check the chain! @ ${Date.now()}`;
const leafHash = witness.hash(sampleString);
console.log(`Timestamping leaf ${leafHash}`);
 
// Post the leafHash to the server.
await witness.postLeaf(leafHash);
// Wait for the data to be included in an onchain checkpoint.
await witness.waitForCheckpointedLeafHash(leafHash);
// Get the timestamp for the leaf.
const timestamp = await witness.getTimestampForLeafHash(leafHash);
console.log(`Leaf ${leafHash} was timestamped at ${timestamp}`);
 
// Or shorthand:
// const timestamp = await witness.postLeafAndGetTimestamp(leafHash);
 
// Get the proof for the leaf.
const proof = await witness.getProofForLeafHash(leafHash);
// Verify the proof against the chain.
const verifiedChain = await witness.verifyProofChain(proof); 
console.log({ verifiedChain });

You can also play with the final code sample in this repl (opens in a new tab).

Next Steps

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

IntroductionAPI