The ported API

Every safe API log exposes this API as log.reader and log.appender, so you can start with the safe API and drop down only where you need to.

Conventions

Names follow Go’s, with functions in camelCase: NewAppender is newAppender. Go’s uint64 is bigint, durations are milliseconds, errors are thrown with Go’s message text, and context.Context is an optional trailing AbortSignal. Test for Go’s sentinels with errorIs(err, ErrPushback), never ===, and find an error class anywhere in a cause chain with errorAs(err, ErrInconsistency), both from webtessera. AGENTS.md §3 has the full mapping, so Tessera’s own documentation applies to this API once you translate the names.

Write to a log

Create a signer

The log signs its checkpoints with a signed-note signer, whose name is the log’s origin:

// Generate the key pair once. Keep skey secret; publish vkey so that clients can
// verify the log's checkpoints.
const { skey, vkey } = generateKey(undefined, "example.com/my-log");
const signer = newSigner(skey);

generateKey, newSigner and newVerifier come from webtessera/note.

Start an appender

Import the root package and one storage driver, then start an appender on the driver:

import { newAppender, newAppendOptions, newEntry, newPublicationAwaiter } from "webtessera";

// Choose one!
import { newMemoryDriver } from "webtessera/storage/memory";
// import { newIndexedDBDriver } from "webtessera/storage/indexeddb";
// import { newSqliteDriver, fromSqliteSync } from "webtessera/storage/sqlite";

const driver = newMemoryDriver();
const signer = createSigner();

const { appender, shutdown, reader } = await newAppender(driver, newAppendOptions().withCheckpointSigner(signer));

newAppender takes an optional AbortSignal as its last argument, which its background tasks watch.

Add entries

appender.add returns a future. Call it to get the index that the log durably assigned to the entry:

const index = await appender.add(newEntry(data))();

The entry is then sequenced and integrated into the tree, but clients can verify it only once a published checkpoint commits to it. That happens within the checkpoint interval, ten seconds by default. To wait for it, for example to return an inclusion proof, use a PublicationAwaiter:

// One awaiter per log, shared by every request: it polls the published checkpoint
// only while somebody is waiting.
const awaiter = newPublicationAwaiter((s) => reader.readCheckpoint(s), 100, signal);

const [index, checkpoint] = await awaiter.await(appender.add(newEntry(data)));

Shut down

Call shutdown() before you abort the signal passed to newAppender. It waits until every entry that the appender accepted is integrated and covered by a published checkpoint. After it returns, add fails.

Tune the appender

newAppendOptions() returns an AppendOptions. Its methods mirror Tessera’s With* options; these are the ones most logs set, and each method’s doc comment covers its parameters:

Choose a storage driver

Every driver runs the same storage engine, a port of Tessera’s POSIX driver. To keep the log in a browser, use IndexedDB:

// The log survives reloads, and several tabs may share it: Web Locks serialise
// their writes.
const driver = await newIndexedDBDriver({ name: "my-log" }, signal);
const { appender, shutdown } = await newAppender(driver, newAppendOptions().withCheckpointSigner(signer), signal);

On a server or at the edge, use SQLite through the adapter for your engine:

// node:sqlite here; any other engine changes only this line, through its own adapter.
const database = fromSqliteSync(new DatabaseSync(file));
const driver = await newSqliteDriver({ database }, signal);
const { appender, shutdown } = await newAppender(driver, newAppendOptions().withCheckpointSigner(signer), signal);

For any other backend, implement ObjectStore and pass it to newObjectStoreDriver({ store }) from webtessera/storage/objectstore. Choosing storage covers what each backend guarantees, the SQLite adapters, and how locking keeps a log from forking.

Read and verify a log

webtessera/client reads any tlog-tiles log, whether webtessera, Tessera or another implementation wrote it, and verifies what it reads:

const verifier = newVerifier(verifierKey);
const log = newHTTPFetcher(new URL("https://log.example.com/"));

// Fetch the latest checkpoint and check the log's signature on it.
const { checkpoint } = await fetchCheckpoint((s) => log.readCheckpoint(s), verifier, verifier.name());

// Prove that the entry at `index` is committed to by that checkpoint.
const proofs = await newProofBuilder(checkpoint.size, (l, i, p, s) => log.readTile(l, i, p, s));
const proof = await proofs.inclusionProof(index.index);
verifyInclusion(DefaultHasher, index.index, checkpoint.size, DefaultHasher.hashLeaf(data), proof, checkpoint.hash);

verifyInclusion comes from webtessera/merkle/proof, and DefaultHasher from webtessera/merkle/rfc6962. For a local log, the reader that newAppender returns can stand in for the HTTP fetcher. To follow a log over time and prove that each checkpoint extends the last, use newLogStateTracker; a monitor shows how.

Beyond appending

Packages

The package is split the way Tessera is split into Go packages, plus the additions marked —:

The doc comments in each package’s source are its reference.