@witnessco/client / Exports / WitnessClient

Class: WitnessClient

Represents a client for interacting with the Witness server and contract.

Example

import { WitnessClient } from "@witnessco/client";
 
// Instantiate a new client, default params should suffice for now.
const witness = new WitnessClient();
 
// Unique string, so we get an unseen leaf hash.
const sampleString = `Check the chain! @ ${Date.now()}`;
// Helper method for getting the hash of a string.
const leafHash = witness.hash(sampleString);
console.log(`Timestamping leaf ${leafHash}`);
 
// Post the leafHash to the server.
await witness.postLeaf(leafHash);
// Use an old leafHash if you don't want to wait for this step.
await witness.waitForCheckpointedLeafHash(leafHash);
const timestamp = await witness.getTimestampForLeafHash(leafHash);
console.log(`Leaf ${leafHash} was timestamped at ${timestamp}`);
 
// Or shorthand for the above:
// const timestamp = await witness.postLeafAndGetTimestamp(leafHash);

Table of contents

Constructors

• constructor

Methods

• getCheckpointByTxHash
• getCurrentTreeState
• getEarliestCheckpointCoveringLeafIndex
• getLatestCheckpointForAllChains
• getLatestOnchainCheckpoint
• getLeafIndexForHash
• getProofForLeafHash
• getTimestampForLeafHash
• hash
• postLeaf
• postLeafAndGetProof
• postLeafAndGetTimestamp
• verifyProofChain
• verifyProofServer
• waitForCheckpointedLeafHash

Constructors

constructor

• new WitnessClient(config?): WitnessClient

Constructs an instance of WitnessClient.

An optional authToken can be provided as either the sole argument or as part of a config object:

const authToken = "my-auth-token";
new WitnessClient(authToken);

Full client config customization options are as follows:

 // ChainConfig lets you configure how proofs are verified against a blockchain.
 type ChainConfig = { ethRpc: string };
 // ServerConfig lets you configure how the client interacts with the Witness server.
 type ServerConfig = { authToken: string; chainId: number; endpoint: string; fetchFn: typeof fetch };
 // All values are optional and can be comfortably omitted.
 type Config = { chain?: ChainConfig; server?: ServerConfig };
 // WitnessClient can be instantiated with an optional config object.
 // Example usage (populate with your config values).
 const chain = { ethRpc: "my-rpc-url.com/" };
 const server = { authToken: "my-auth-token", chainId: 1 }
 const myConfig: Config = { chain: chainConfig, server: serverConfig };
 new WitnessClient(myConfig);

Parameters

Returns

WitnessClient

Defined in

src/WitnessClient.ts:87 (opens in a new tab)

Methods

getCheckpointByTxHash

▸ getCheckpointByTxHash(txHash): Promise<{ blockHash: Hash ; blockNumber: bigint ; chainId: number ; rootHash: Hash ; status: "pending" | "included" | "finalized" ; timestamp: Date ; treeSize: bigint ; txHash: string }>

Gets a checkpoint by its transaction hash.

Parameters

Returns

Promise<{ blockHash: Hash ; blockNumber: bigint ; chainId: number ; rootHash: Hash ; status: "pending" | "included" | "finalized" ; timestamp: Date ; treeSize: bigint ; txHash: string }>

The checkpoint with the specified transaction hash.

Defined in

src/WitnessClient.ts:411 (opens in a new tab)

getCurrentTreeState

▸ getCurrentTreeState(): Promise<{ checkpointedLeafCount: bigint ; checkpointedRoot: Hash ; leafCount: bigint ; merklizedLeafCount: bigint ; merklizedRoot: Hash ; unmerklizedLeafCount: bigint }>

Gets the current tree state.

Returns

Promise<{ checkpointedLeafCount: bigint ; checkpointedRoot: Hash ; leafCount: bigint ; merklizedLeafCount: bigint ; merklizedRoot: Hash ; unmerklizedLeafCount: bigint }>

The current tree state.

Defined in

src/WitnessClient.ts:117 (opens in a new tab)

getEarliestCheckpointCoveringLeafIndex

▸ getEarliestCheckpointCoveringLeafIndex(leafIndex, chainId?): Promise<{ blockHash: Hash ; blockNumber: bigint ; chainId: number ; rootHash: Hash ; status: "pending" | "included" | "finalized" ; timestamp: Date ; treeSize: bigint ; txHash: Hash }>

Gets the earliest checkpoint that covers the specified leaf index.

Parameters

Returns

Promise<{ blockHash: Hash ; blockNumber: bigint ; chainId: number ; rootHash: Hash ; status: "pending" | "included" | "finalized" ; timestamp: Date ; treeSize: bigint ; txHash: Hash }>

The earliest checkpoint that covers the specified leaf.

Defined in

src/WitnessClient.ts:291 (opens in a new tab)

getLatestCheckpointForAllChains

▸ getLatestCheckpointForAllChains(): Promise<Record<string, { [key: string]: string | bigint | Date | number; }>>

Gets the latest onchain checkpoints for all chains.

Returns

Promise<Record<string, { [key: string]: string | bigint | Date | number; }>>

The latest onchain checkpoint for all chains.

Defined in

src/WitnessClient.ts:367 (opens in a new tab)

getLatestOnchainCheckpoint

▸ getLatestOnchainCheckpoint(chainId?): Promise<{ blockHash: Hash ; blockNumber: bigint ; chainId: number ; rootHash: Hash ; status: "pending" | "included" | "finalized" ; timestamp: Date ; treeSize: bigint ; txHash: Hash }>

Gets the latest onchain checkpoint.

Parameters

Returns

Promise<{ blockHash: Hash ; blockNumber: bigint ; chainId: number ; rootHash: Hash ; status: "pending" | "included" | "finalized" ; timestamp: Date ; treeSize: bigint ; txHash: Hash }>

The latest onchain checkpoint.

Defined in

src/WitnessClient.ts:334 (opens in a new tab)

getLeafIndexForHash

▸ getLeafIndexForHash(leafHash): Promise<bigint>

Gets the index of a leaf with the specified hash.

Parameters

Returns

Promise<bigint>

The index of the leaf with the specified hash.

Defined in

src/WitnessClient.ts:272 (opens in a new tab)

getProofForLeafHash

▸ getProofForLeafHash(leafHash, options?): Promise<{ leafHash: Hash ; leafIndex: bigint ; leftHashes: Hash[] ; rightHashes: Hash[] ; targetRootHash: Hash }>

Gets the Merkle proof for a particular leafHash.

Parameters

Returns

Promise<{ leafHash: Hash ; leafIndex: bigint ; leftHashes: Hash[] ; rightHashes: Hash[] ; targetRootHash: Hash }>

The Merkle proof for the specified leaf.

Defined in

src/WitnessClient.ts:442 (opens in a new tab)

getTimestampForLeafHash

▸ getTimestampForLeafHash(leafHash, chainId?): Promise<Date>

Gets the index of a leaf with the specified hash.

Parameters

Returns

Promise<Date>

The index of the leaf with the specified hash.

Defined in

src/WitnessClient.ts:251 (opens in a new tab)

hash

▸ hash(str): Hash

Hashes a string using the keccak256 algorithm.

Parameters

Returns

Hash

• The resulting hash.

Defined in

src/WitnessClient.ts:545 (opens in a new tab)

postLeaf

▸ postLeaf(leafHash): Promise<{ leafHash: Hash ; leafIndex: bigint }>

Posts a leafHash to the server.

Parameters

Returns

Promise<{ leafHash: Hash ; leafIndex: bigint }>

The index of the posted leafHash.

Defined in

src/WitnessClient.ts:183 (opens in a new tab)

postLeafAndGetProof

▸ postLeafAndGetProof(leafHash, chainId?): Promise<{ leafHash: Hash ; leafIndex: bigint ; leftHashes: Hash[] ; rightHashes: Hash[] ; targetRootHash: Hash }>

Posts a leaf and waits until it can return with a checkpointed proof.

Parameters

Returns

Promise<{ leafHash: Hash ; leafIndex: bigint ; leftHashes: Hash[] ; rightHashes: Hash[] ; targetRootHash: Hash }>

The proof for the specified leaf.

Remarks

This is a convenience method that combines postLeaf and waitForCheckpointedLeaf. Because it waits for a checkpointed leaf, it may take up to a few minutes to return.

Defined in

src/WitnessClient.ts:209 (opens in a new tab)

postLeafAndGetTimestamp

▸ postLeafAndGetTimestamp(leafHash, chainId?): Promise<Date>

Posts a leaf and waits until it can return with a checkpointed timestamp.

Parameters

Returns

Promise<Date>

The timestamp for the specified leaf.

Remarks

This is a convenience method that combines postLeaf, waitForCheckpointedLeaf, and getTimestampForLeafHash. Because it waits for a checkpointed leaf, it may take up to a few minutes to return.

Defined in

src/WitnessClient.ts:235 (opens in a new tab)

verifyProofChain

▸ verifyProofChain(proof, config?): Promise<boolean>

Verifies a Merkle proof for a given leaf against the chain.

Parameters

Returns

Promise<boolean>

A boolean indicating whether the proof is valid.

Remarks

This method calls out to the provided RPC node to verify the proof provided corresponds to a legitimate checkpoint. While a default public RPC node is provided for convenience, it's recommended to bring your own to avoid any potential issues such as rate limits.

Defined in

src/WitnessClient.ts:512 (opens in a new tab)

verifyProofServer

▸ verifyProofServer(proof): Promise<boolean>

Verifies a Merkle proof for a given leaf.

Parameters

Returns

Promise<boolean>

A boolean indicating whether the proof is valid.

Remarks

This method calls out to the Witness server, to verify the proof provided corresponds to an actual checkpoint. It's recommended to cross-check the proof and checkpoint against the corresponding Witness contract on-chain.

Defined in

src/WitnessClient.ts:482 (opens in a new tab)

waitForCheckpointedLeafHash

▸ waitForCheckpointedLeafHash(leafHash, chainId?): Promise<{ blockHash: Hash ; blockNumber: bigint ; chainId: number ; rootHash: Hash ; status: "pending" | "included" | "finalized" ; timestamp: Date ; treeSize: bigint ; txHash: Hash }>

Waits for a checkpoint covering the given leaf hash. This method will wait up to 15 minutes for a checkpoint to be created covering the given leaf, polling at a 5s interval.

Parameters

Returns

Promise<{ blockHash: Hash ; blockNumber: bigint ; chainId: number ; rootHash: Hash ; status: "pending" | "included" | "finalized" ; timestamp: Date ; treeSize: bigint ; txHash: Hash }>

The earliest checkpoint that covers the specified leaf.

Defined in

src/WitnessClient.ts:150 (opens in a new tab)