Skip to main content

Merkle Tree

After obtaining a Document instance, you can utilize these methods to examine and verify the current state of the merkle tree.

Get the merkle proof status for a document​

After performing a document-related operation (create, update, or drop), the document must be queued for the next merkle tree update. You can verify the document's status in the merkle tree by calling the merkleProofStatus method on a Document object.

Definition​

await document.merkleProofStatus(): Promise<EQueueTaskStatus>;

Parameters​

  • None

Returns​

The operation returns a Promise that resolves to the status of the document in the merkle tree. The status can be one of the following:

  • EQueueTaskStatus.Queued: The document has been queued for the next merkle tree update.
  • EQueueTaskStatus.Processing: The document is currently being processed for the next merkle tree update.
  • EQueueTaskStatus.Success: The document has been successfully processed and incorporated into the merkle tree.
  • EQueueTaskStatus.Failed: The document processing has failed and is not included in the merkle tree. This status also indicates that subsequent operations on the document will be blocked until corrective action is taken. Refer to Detect and retry failed operations for more information on how to handle failure.
  • EQueueTaskStatus.Unknown: The document's status cannot be determined. This should only occur if there is an underlying issue with the zkDatabase.

Example​

import { CircuitString, UInt64 } from 'o1js';
import { Schema, ZkDatabase, Permission } from './index';
import { EQueueTaskStatus } from '@zkdb/common'

const zkdb = await ZkDatabase.connect({
  userName: "chiro-user",
  privateKey: "EKFTciRxyxshZjimay9sktsn7v5PvmC5zPq7q4JnitHUytxUVnFP",
  environment: "node",
  // This URL is for test environment
  url: "https://api.zkdatabase.org/graphql",
});

await zkdb.auth.signIn();

class Shirt extends Schema.create({
  name: CircuitString,
  price: UInt64,
}) {}

type TShirt = typeof Shirt;

const collection = await zkdb
  .db('zkdb_test')
  .collection<TShirt>('test_collection');

await collection.insert({
  name: 'Test Shirt',
  price: 10n,
});

await collection.insert(
  {
    name: 'Orochi',
    price: 10n ** 9n,
  },
  Permission.policyStrict()
);

const status = await document.merkleProofStatus();
console.assert([
  EQueueTaskStatus.Queued,
  EQueueTaskStatus.Processing,
  EQueueTaskStatus.Success,
  EQueueTaskStatus.Failed,
  EQueueTaskStatus.Unknown,
].includes(status))

await zkdb.auth.signOut();

Get the merkle proof for a document​

Once you've confirmed that the document's merkle tree proof status is Success, you can retrieve its merkle proof using the merkleProof method on the Document object. If the status is not Success, the merkle proof may correspond to an empty node.

Definition​

await document.merkleProof(): Promise<TMerkleProof>;

Parameters​

  • None

Returns​

The operation returns a Promise that resolves to the merkle proof for the document. The merkle proof is a list of hashes that can be used to verify the document's inclusion in the merkle tree.

type TMerkleProof = Array<{
    sibling: string;
    isLeft: boolean;
}>;

Example​

import { CircuitString, UInt64 } from 'o1js';
import { Schema, ZkDatabase, Permission } from './index';
import { EQueueTaskStatus } from '@zkdb/common'

const zkdb = await ZkDatabase.connect({
  userName: "chiro-user",
  privateKey: "EKFTciRxyxshZjimay9sktsn7v5PvmC5zPq7q4JnitHUytxUVnFP",
  environment: "node",
  // This URL is for test environment
  url: "https://api.zkdatabase.org/graphql",
});

await zkdb.auth.signIn();

class Shirt extends Schema.create({
  name: CircuitString,
  price: UInt64,
}) {}

type TShirt = typeof Shirt;

const collection = await zkdb
  .db('zkdb_test')
  .collection<TShirt>('test_collection');

await collection.insert({
  name: 'Test Shirt',
  price: 10n,
});

await collection.insert(
  {
    name: 'Orochi',
    price: 10n ** 9n,
  },
  Permission.policyStrict()
);

let status;
while ((status = await document.merkleProofStatus()) !== EQueueTaskStatus.Success) {
  if (status === EQueueTaskStatus.Failed) {
      throw new Error('Document processing failed');
  }
  await new Promise(resolve => setTimeout(resolve, 1000));
}

const proof = await document.merkleProof();
console.assert(proof.length > 0)

await zkdb.auth.signOut();