Skip to main content

Notary Overview

This section explains the current Bookcicle Notary model across the web app and Bookcicle Desktop.

The current product spans two main surfaces:

  • the web app
  • the desktop app

Core Model​

At a high level, Notary has four core pieces:

PieceMeaning
Local ProofsProofs created on the user's device first, either in the browser or on desktop
Cloud ProofA proof created directly through Bookcicle's remote notary endpoints
AttestThe server workflow that upgrades a local proof by issuing a signed receipt
AnchorsThe remote workflow that adds a public anchor to a cloud proof or an attested proof

In the current product and API surface, Attest is the server workflow that issues the Bookcicle receipt for an existing local proof.

The current web app labels do not fully use this broader model language yet. The web surface still exposes source labels such as Local browser proof and Local proof attest, even though the product model is broader than browser-only local proofs.

The current UI labels support this model directly:

  • local becomes Local proof
  • attested becomes Attested
  • verified becomes Verified
  • anchor states map to Anchor queued, Anchoring, and Anchored

Main Artifacts​

The current product works with these artifacts:

ArtifactPurpose
Local proofLocal proof record created from bytes or file content
ReceiptBookcicle-signed cloud response tied to the proof
Proof capsulePortable bundle for later verification
Original bytesOptional stored file bytes, depending on storage mode
Anchor artifactExtra output from the anchoring step
CheckpointLocal snapshot of exact bytes used for proofs in desktop workflows

Storage Modes in the Web App​

The web app exposes three remote storage modes:

ModeMeaning
RECEIPT_ONLYReceipt only
STORE_TREEReceipt plus verification data
STORE_BYTESReceipt, verification data, and original file bytes

For local proofs created in the web app, the current storage choice is:

  • no backup bytes
  • backup original bytes into notary storage

Main API Surface​

The main notary endpoints in use today are:

  • POST /notary/attest/init
  • POST /notary/attest/complete
  • POST /notary/attest
  • POST /notary/proofs/{proofId}/anchor
  • GET /notary/proofs/{proofId}
  • GET /notary/proofs/{proofId}/receipt
  • POST /notary/proofs/{proofId}/verify

Attest contract​

The current product uses two Attest patterns:

  1. Two-step upgrade for an existing local proof
    • POST /notary/attest/init
    • POST /notary/attest/complete
    • then GET /notary/proofs/{proofId}/receipt
  2. Direct server-side attest
    • POST /notary/attest

The response can include:

  • proofId
  • merkleRoot
  • attestedProof
  • receipt
  • anchor

So Attest is not just a UI word. It is the server-issued receipt flow.

Anchor contract​

The remote anchor path is exposed through:

  • POST /notary/proofs/{proofId}/anchor

That endpoint is the upgrade step for proofs that already exist in the cloud, including direct cloud proofs and local proofs that were already attested.

Verification Model for Receipts​

Desktop verification currently checks Attest receipts in two important ways:

  • Offline: compare the receipt merkle root to the local proof merkle root
  • Online: verify the server receipt signature publicly, then optionally compare the fetched authoritative cloud receipt to the embedded one when auth is available

Read These Next​