@optimystic/db-core 0.0.1

package/src/collection/collection.ts

@@ -0,0 +1,200 @@
+import type { IBlock, Action, ActionType, ActionHandler, BlockId, ITransactor, ActionEntry, BlockStore } from "../index.js";
+import { Log, Atomic, Tracker, copyTransforms, CacheSource, isTransformsEmpty, TransactorSource, blockIdsForTransforms, transformsFromTransform } from "../index.js";
+import type { CollectionHeaderBlock, CollectionId, ICollection } from "./index.js";
+import { randomBytes } from '@libp2p/crypto';
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string';
+import { Latches } from "../utility/latches.js";
+
+const PendingRetryDelayMs = 100;
+
+export type CollectionInitOptions<TAction> = {
+	modules: Record<ActionType, ActionHandler<TAction>>;
+	createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => IBlock;
+	/** Called for each local action that is potentially in conflict with a remote action.
+	 * @param action - The local action to check
+	 * @param potential - The remote action that is potentially in conflict
+	 * @returns The original action, a replacement action (return a new instance; will be
+	 * 	applied through act()), or undefined to discard this action
+	 */
+	filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined
+}
+
+export class Collection<TAction> implements ICollection<TAction> {
+	private pending: Action<TAction>[] = [];
+
+	protected constructor(
+		public readonly id: CollectionId,
+		public readonly transactor: ITransactor,
+		private readonly handlers: Record<ActionType, ActionHandler<TAction>>,
+		private readonly source: TransactorSource<IBlock>,
+		/** Cache of unmodified blocks from the source */
+		private readonly sourceCache: CacheSource<IBlock>,
+		/** Tracked Changes */
+		public readonly tracker: Tracker<IBlock>,
+		private readonly filterConflict?: (action: Action<TAction>, potential: Action<TAction>[]) => Action<TAction> | undefined,
+	) {
+	}
+
+	static async createOrOpen<TAction>(transactor: ITransactor, id: CollectionId, init: CollectionInitOptions<TAction>) {
+		// Start with a context that has an infinite revision number to ensure that we always fetch the latest log information
+		const source = new TransactorSource(id, transactor, undefined);
+		const sourceCache = new CacheSource(source);
+		const tracker = new Tracker(sourceCache);
+		const header = await source.tryGet(id) as CollectionHeaderBlock | undefined;
+
+		if (header) {	// Collection already exists
+			const log = (await Log.open<Action<TAction>>(tracker, id))!;
+			source.actionContext = await log.getActionContext();
+		} else {	// Collection does not exist
+			const headerBlock = init.createHeaderBlock(id, tracker);
+			tracker.insert(headerBlock);
+			source.actionContext = undefined;
+			await Log.open<Action<TAction>>(tracker, id);
+		}
+
+		return new Collection(id, transactor, init.modules, source, sourceCache, tracker, init.filterConflict);
+	}
+
+	async act(...actions: Action<TAction>[]) {
+		await this.internalTransact(...actions);
+		this.pending.push(...actions);
+	}
+
+	private async internalTransact(...actions: Action<TAction>[]) {
+		const atomic = new Atomic(this.tracker);
+
+		for (const action of actions) {
+			const handler = this.handlers[action.type];
+			if (!handler) {
+				throw new Error(`No handler for action type ${action.type}`);
+			}
+			await handler(action, atomic);
+		}
+
+		atomic.commit();
+	}
+
+	/** Load external changes and update our context to the latest log revision - resolve any conflicts with our pending actions. */
+	async update() {
+		// Start with a context that can see to the end of the log
+		const source = new TransactorSource(this.id, this.transactor, undefined);
+		const tracker = new Tracker(source);
+
+		// Get the latest entries from the log, starting from where we left off
+		const actionContext = this.source.actionContext;
+		const log = await Log.open<Action<TAction>>(tracker, this.id);
+		const latest = log ? await log.getFrom(actionContext?.rev ?? 0) : undefined;
+
+		// Process the entries and track the blocks they affect
+		let anyConflicts = false;
+		for (const entry of latest?.entries ?? []) {
+			// Filter any pending actions that conflict with the remote actions
+			this.pending = this.pending.map(p => this.doFilterConflict(p, entry.actions) ? p : undefined)
+				.filter(Boolean) as Action<TAction>[];
+			this.sourceCache.clear(entry.blockIds);
+			anyConflicts = anyConflicts || tracker.conflicts(new Set(entry.blockIds)).length > 0;
+		}
+
+		// On conflicts, clear related caching and block-tracking and replay logical operations
+		if (anyConflicts) {
+			await this.replayActions();
+		}
+
+		// Update our context to the latest
+		this.source.actionContext = latest?.context;
+	}
+
+	/** Push our pending actions to the transactor */
+	async sync() {
+		const lockId = `Collection.sync:${this.id}`;
+		const release = await Latches.acquire(lockId);
+		try {
+			const bytes = randomBytes(16);
+			const actionId = uint8ArrayToString(bytes, 'base64url');
+
+			while (this.pending.length || !isTransformsEmpty(this.tracker.transforms)) {
+				// Snapshot the pending actions so that any new actions aren't assumed to be part of this action
+				const pending = [...this.pending];
+
+				// Create a snapshot tracker for the action, so that we can ditch the log changes if we have to retry the action
+				const snapshot = copyTransforms(this.tracker.transforms);
+				const tracker = new Tracker(this.sourceCache, snapshot);
+
+				// Add the action to the log (in local tracking space)
+				const log = await Log.open<Action<TAction>>(tracker, this.id);
+				if (!log) {
+					throw new Error(`Log not found for collection ${this.id}`);
+				}
+				const newRev = (this.source.actionContext?.rev ?? 0) + 1;
+				const addResult = await log.addActions(pending, actionId, newRev, () => tracker.transformedBlockIds());
+
+				// Commit the action to the transactor
+				const staleFailure = await this.source.transact(tracker.transforms, actionId, newRev, this.id, addResult.tailPath.block.header.id);
+				if (staleFailure) {
+					if (staleFailure.pending) {
+						// Wait for short time to allow the pending actions to commit (bounded backoff)
+						await new Promise(resolve => setTimeout(resolve, PendingRetryDelayMs));
+					}
+					await this.update();
+				} else {
+					// Clear the pending actions that were part of this action
+					this.pending = this.pending.slice(pending.length);
+					// Reset cache and replay any actions that were added during the action
+					const transforms = tracker.reset();
+					await this.replayActions();
+					this.sourceCache.transformCache(transforms);
+					this.source.actionContext = this.source.actionContext
+						? { committed: [...this.source.actionContext.committed, { actionId, rev: newRev }], rev: newRev }
+						: { committed: [{ actionId, rev: newRev }], rev: newRev };
+				}
+			}
+		} finally {
+			release();
+		}
+	}
+
+	async updateAndSync() {
+		// TODO: introduce timer and potentially change stats to determine when to sync, rather than always syncing
+		await this.update();
+		await this.sync();
+	}
+
+	async *selectLog(forward = true): AsyncIterableIterator<Action<TAction>> {
+		const log = await Log.open<Action<TAction>>(this.tracker, this.id);
+		if (!log) {
+			throw new Error(`Log not found for collection ${this.id}`);
+		}
+		for await (const entry of log.select(undefined, forward)) {
+			if (entry.action) {
+				yield* forward ? entry.action.actions : entry.action.actions.reverse();
+			}
+		}
+	}
+
+	private async replayActions() {
+		this.tracker.reset();
+		// Because pending could be appended while we're async, we need to snapshot and repeat until empty
+		while (this.pending.length) {
+			const pending = [...this.pending];
+			this.pending = [];
+			await this.internalTransact(...pending);
+		}
+	}
+
+	/** Called for each local action that may be in conflict with a remote action.
+	 * @param action - The local action to check
+	 * @param potential - The remote action that is potentially in conflict
+	 * @returns true if the action should be kept, false to discard it
+	 */
+	protected doFilterConflict(action: Action<TAction>, potential: Action<TAction>[]) {
+		if (this.filterConflict) {
+			const replacement = this.filterConflict(action, potential);
+			if (!replacement) {
+				return false;
+			} else if (replacement !== action) {
+				this.act(replacement);
+			}
+		}
+		return true;
+	}
+}

package/src/collection/index.ts

@@ -0,0 +1,3 @@
+export * from "./collection.js";
+export * from "./struct.js";
+export * from "./action.js";

package/src/collection/struct.ts

@@ -0,0 +1,20 @@
+import type { IBlock, BlockId, Action } from "../index.js";
+
+export type CollectionId = BlockId;
+
+export type CollectionHeaderType = 'CH';
+
+export type CollectionHeaderBlock = IBlock & {
+	header: {
+		type: CollectionHeaderType;
+	};
+};
+
+export interface ICollection<TAction> {
+	update(): Promise<void>;
+	sync(): Promise<void>;
+}
+
+export type CreateCollectionAction = Action<void> & {
+	type: "create";
+};

package/src/collections/diary/diary.ts

@@ -0,0 +1,43 @@
+import { Collection } from "../../index.js";
+import type { ITransactor, Action, BlockId, BlockStore, IBlock, CollectionInitOptions, CollectionId } from "../../index.js";
+import { DiaryHeaderBlockType } from "./index.js";
+
+export class Diary<TEntry> {
+    private constructor(
+			private readonly collection: Collection<TEntry>
+		) {
+    }
+
+    static async create<TEntry>(network: ITransactor, id: CollectionId): Promise<Diary<TEntry>> {
+        const init: CollectionInitOptions<TEntry> = {
+            modules: {
+							"append": async (action, trx) => {
+								// Append-only diary doesn't need to modify any blocks
+								// All entries are stored in the log
+							}
+            },
+            createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => ({
+                header: store.createBlockHeader(DiaryHeaderBlockType, id)
+            })
+        };
+
+        const collection = await Collection.createOrOpen(network, id, init);
+        return new Diary<TEntry>(collection);
+    }
+
+    async append(data: TEntry): Promise<void> {
+        const action: Action<TEntry> = {
+            type: "append",
+            data: data
+        };
+
+        await this.collection.act(action);
+        await this.collection.updateAndSync();
+    }
+
+    async *select(forward = true): AsyncIterableIterator<TEntry> {
+        for await (const entry of this.collection.selectLog(forward)) {
+            yield entry.data;
+        }
+    }
+}

package/src/collections/diary/index.ts

@@ -0,0 +1,2 @@
+export * from "./diary.js";
+export * from "./struct.js";

package/src/collections/diary/struct.ts

@@ -0,0 +1,3 @@
+import { registerBlockType } from "../../index.js";
+
+export const DiaryHeaderBlockType = registerBlockType("DIH", "DiaryHeaderBlock");

package/src/collections/index.ts

@@ -0,0 +1,2 @@
+export * from "./diary/index.js";
+export * from "./tree/index.js";

package/src/collections/tree/collection-trunk.ts

@@ -0,0 +1,25 @@
+import { apply, get } from "../../index.js";
+import type { BlockId, BlockStore, IBlock, ITreeTrunk } from "../../index.js";
+import type { ITreeNode } from "../../btree/nodes.js";
+import { rootId$, type TreeCollectionHeaderBlock } from "./struct.js";
+
+export class CollectionTrunk implements ITreeTrunk {
+    constructor(
+        private readonly store: BlockStore<IBlock>,
+        private readonly collectionId: BlockId,
+    ) {}
+
+    async get(): Promise<ITreeNode> {
+        return await get(this.store, await this.getId());
+    }
+
+    async set(node: ITreeNode): Promise<void> {
+				const header = await get(this.store, this.collectionId) as TreeCollectionHeaderBlock;
+				apply(this.store, header, [rootId$, 0, 1, node.header.id]);
+    }
+
+    async getId(): Promise<BlockId> {
+				const header = await get(this.store, this.collectionId) as TreeCollectionHeaderBlock;
+        return header.rootId;
+    }
+}

package/src/collections/tree/index.ts

@@ -0,0 +1,2 @@
+export * from "./tree.js";
+export * from "./struct.js";

package/src/collections/tree/readme.md

@@ -0,0 +1,19 @@
+# Tree Collection
+
+The Tree Collection combines the logical transaction logging of a collection, with a BTree data structure.
+
+## CollectionTrunk
+
+To avoid having both a collection header and a btree header, we enable the collection header to double as the btree header.  This is accomplished using the "...Trunk" abstraction provided by the BTree.  The trunk interface abstracts accessing or updating the root of the tree, from the btree proper.  For this implementation, we introduce a CollectionTrunk class that implements the trunk interface.  The CollectionTrunk reads the root id from the collection header, and updates the collection header with the new root id when the root changes.
+
+## Replace Action
+
+The replace action is a unit of change to the tree collection.  It is a list of key-value pairs, where the key is the key to replace, and the value is the new value to replace the old value with.  If the value is not provided, the key is deleted.
+
+```ts
+tree.replace([
+	{ key: 5, value: { a: 1, b: 'Value' } },
+	{ key: 10 },
+]);
+```
+Replaces the value at key 5 with { a: 1, b: 'Value' }, and deletes the value at key 10.

package/src/collections/tree/struct.ts

@@ -0,0 +1,18 @@
+import { type BlockId, type CollectionHeaderBlock, nameof, registerBlockType } from "../../index.js";
+
+export const TreeHeaderBlockType = registerBlockType("TRE", "TreeHeaderBlock");
+
+export type TreeCollectionHeaderBlock = CollectionHeaderBlock & {
+	rootId: BlockId;
+};
+
+export const rootId$ = nameof<TreeCollectionHeaderBlock>("rootId");
+
+/** Represents a unit of change to a tree collection. */
+export type TreeReplaceAction<TKey, TEntry> = [
+	// The key to replace
+	key: TKey,
+	// The new entry to replace the old entry with (if not provided, the key is deleted)
+	entry?: TEntry,
+][];
+

package/src/collections/tree/tree.ts

@@ -0,0 +1,124 @@
+import { Collection, type CollectionInitOptions, type CollectionId } from "../../collection/index.js";
+import type { ITransactor, BlockId, BlockStore, IBlock } from "../../index.js";
+import { BTree, type Path, type KeyRange } from "../../btree/index.js";
+import { CollectionTrunk } from "./collection-trunk.js";
+import { TreeHeaderBlockType, type TreeReplaceAction } from "./struct.js";
+
+export class Tree<TKey, TEntry> {
+
+	private constructor(
+		private readonly collection: Collection<TreeReplaceAction<TKey, TEntry>>,
+		private readonly btree: BTree<TKey, TEntry>,
+	) {
+	}
+
+	static async createOrOpen<TKey, TEntry>(
+		network: ITransactor,
+		id: CollectionId,
+		keyFromEntry = (entry: TEntry) => entry as unknown as TKey,
+		compare = (a: TKey, b: TKey) => a < b ? -1 : a > b ? 1 : 0,
+	): Promise<Tree<TKey, TEntry>> {
+		// Tricky bootstrapping here:
+		// We need the root id to initialize the collection header, so we create the btree in the create collection header callback.
+		let btree: BTree<TKey, TEntry> | undefined;
+		const init: CollectionInitOptions<TreeReplaceAction<TKey, TEntry>> = {
+			modules: {
+				"replace": async ({ data: actions }, trx) => {
+					for (const [key, entry] of actions) {
+						if (entry) {
+							await btree!.upsert(entry);
+						} else {
+							await btree!.deleteAt((await btree!.find(key)));
+						}
+					}
+				}
+			},
+			createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => {	// Only called if the collection does not exist
+				let rootId: BlockId;
+				btree = BTree.create<TKey, TEntry>(store, (s, r) => {
+						rootId = r;
+						return new CollectionTrunk(store, id);
+					}, keyFromEntry, compare);
+				return {
+					header: store.createBlockHeader(TreeHeaderBlockType, id),
+					rootId: rootId!,
+				}
+			}
+		};
+
+		const collection = await Collection.createOrOpen<TreeReplaceAction<TKey, TEntry>>(network, id, init);
+		btree = btree ?? new BTree<TKey, TEntry>(collection.tracker, new CollectionTrunk(collection.tracker, collection.id), keyFromEntry, compare);
+		return new Tree<TKey, TEntry>(collection, btree);
+	}
+
+	async replace(data: TreeReplaceAction<TKey, TEntry>): Promise<void> {
+			await this.collection.act({ type: "replace", data });
+			await this.collection.updateAndSync();
+	}
+
+	/**
+	 * Update the local state from the network.
+	 * Call this before reading to ensure you have the latest data.
+	 */
+	async update(): Promise<void> {
+		await this.collection.update();
+	}
+
+	// Read actions
+
+	async first(): Promise<Path<TKey, TEntry>> {
+		return await this.btree.first();
+	}
+
+	async last(): Promise<Path<TKey, TEntry>> {
+		return await this.btree.last();
+	}
+
+	async find(key: TKey): Promise<Path<TKey, TEntry>> {
+		return await this.btree.find(key);
+	}
+
+	async get(key: TKey): Promise<TEntry | undefined> {
+		return await this.btree.get(key);
+	}
+
+	at(path: Path<TKey, TEntry>): TEntry | undefined {
+		return this.btree.at(path);
+	}
+
+	range(range: KeyRange<TKey>): AsyncIterableIterator<Path<TKey, TEntry>> {
+		return this.btree.range(range);
+	}
+
+	ascending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
+		return this.btree.ascending(path);
+	}
+
+	descending(path: Path<TKey, TEntry>): AsyncIterableIterator<Path<TKey, TEntry>> {
+		return this.btree.descending(path);
+	}
+
+	async getCount(from?: { path: Path<TKey, TEntry>, ascending?: boolean }): Promise<number> {
+		return await this.btree.getCount(from);
+	}
+
+	async next(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
+		return await this.btree.next(path);
+	}
+
+	async moveNext(path: Path<TKey, TEntry>): Promise<void> {
+		await this.btree.moveNext(path);
+	}
+
+	async prior(path: Path<TKey, TEntry>): Promise<Path<TKey, TEntry>> {
+		return await this.btree.prior(path);
+	}
+
+	async movePrior(path: Path<TKey, TEntry>): Promise<void> {
+		await this.btree.movePrior(path);
+	}
+
+	isValid(path: Path<TKey, TEntry>): boolean {
+		return this.btree.isValid(path);
+	}
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./blocks/index.js";
+export * from "./btree/index.js";
+export * from "./chain/index.js";
+export * from "./cluster/index.js";
+export * from "./collection/index.js";
+export * from "./collections/index.js";
+export * from "./log/index.js";
+export * from "./network/index.js";
+export * from "./transaction/index.js";
+export * from "./transactor/index.js";
+export * from "./transform/index.js";
+export * from "./utility/groupby.js";
+export * from "./utility/latches.js";
+export * from "./utility/nameof.js";
+export * from "./utility/ensured.js";
+export * from "./utility/pending.js";
+export * from "./utility/block-id-to-bytes.js";

package/src/log/index.ts

@@ -0,0 +1,2 @@
+export * from "./log.js";
+export * from "./struct.js";

package/src/log/log.ts

@@ -0,0 +1,155 @@
+import { sha256 } from 'multiformats/hashes/sha2'
+import { Chain, entryAt, nameof } from "../index.js";
+import type { IBlock, BlockId, ActionId, CollectionId, ChainPath, ActionRev, ActionContext, ChainInitOptions, BlockStore } from "../index.js";
+import type { ChainHeaderBlockType, ChainDataNode } from '../chain/chain-nodes.js';
+import type { LogEntry, ActionEntry } from "./index.js";
+import { LogDataBlockType, LogHeaderBlockType } from "./index.js";
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
+import type { GetFromResult } from './struct.js';
+
+export type LogBlock<TAction> = ChainDataNode<LogEntry<TAction>>
+	& {
+		/** Base64url encoded Sha256 hash of the next block - present on every block except the head */
+		priorHash?: string,
+	};
+
+export const priorHash$ = nameof<LogBlock<any>>("priorHash");
+
+export class Log<TAction> {
+	protected constructor(
+		private readonly chain: Chain<LogEntry<TAction>>,
+	) {
+	}
+
+	get id() {
+		return this.chain.id;
+	}
+
+	/** Opens a presumably existing log. */
+	static async open<TAction>(store: BlockStore<IBlock>, id: BlockId): Promise<Log<TAction> | undefined> {
+		const chain = await Chain.open<LogEntry<TAction>>(store, id, Log.getChainOptions(store));
+		return chain ? new Log<TAction>(chain) : undefined;
+	}
+
+	/** Creates a new log. */
+	static async create<TAction>(store: BlockStore<IBlock>, newId?: BlockId) {
+		return new Log<TAction>(await Chain.create<LogEntry<TAction>>(store, { ...Log.getChainOptions(store), newId }));
+	}
+
+	/** Adds a new entry to the log. */
+	async addActions(actions: TAction[], actionId: ActionId, rev: number, getBlockIds: () => BlockId[], collectionIds: CollectionId[] = [], timestamp: number = Date.now()) {
+		const entry = { timestamp, rev, action: { actionId, actions, blockIds: [], collectionIds } } as LogEntry<TAction>;
+		const tailPath = await this.chain.add(entry);
+		const entryWithBlockIds = { ...entry, action: { ...entry.action!, blockIds: getBlockIds() } };
+		this.chain.updateAt(tailPath, entryWithBlockIds);
+		return { entry: entryWithBlockIds, tailPath };
+	}
+
+	/** Adds a checkpoint to the log. */
+	async addCheckpoint(pendings: ActionRev[], rev: number, timestamp: number = Date.now()) {
+		const entry = { timestamp, rev, checkpoint: { pendings } };
+		const tailPath = await this.chain.add(entry);
+		return { entry, tailPath };
+	}
+
+	/** Gets the action context of the log. */
+	async getActionContext(): Promise<ActionContext | undefined> {
+		const tailPath = await this.chain.getTail();
+		if (!tailPath) {
+			return undefined;
+		}
+		const checkpoint = await this.findCheckpoint(tailPath);
+		return {
+			committed:
+				checkpoint
+
+					? [...checkpoint.pendings, ...await this.pendingFrom(checkpoint.path)]
+					: [],
+			rev: checkpoint?.rev ?? 0,
+		};
+	}
+
+	/** Gets the actions from startRev (exclusive), to latest in the log. */
+	async getFrom(startRev: number | undefined): Promise<GetFromResult<TAction>> {
+		const entries: ActionEntry<TAction>[] = [];
+		const pendings: ActionRev[] = [];
+		let rev: number | undefined;
+		let checkpointPath: ChainPath<LogEntry<TAction>> | undefined;
+		// Step through collecting both pending and entries until a checkpoint is found
+		for await (const path of this.chain.select(undefined, false)) {
+			const entry = entryAt<LogEntry<TAction>>(path)!;
+			rev = rev ?? entry.rev;
+			if (entry.checkpoint) {
+				checkpointPath = path;
+				pendings.unshift(...entry.checkpoint.pendings);
+				break;
+			}
+			pendings.unshift({ actionId: entry.action!.actionId, rev: entry.rev });
+			if (startRev !== undefined && entry.rev > startRev) {
+				entries.unshift(entry.action!);
+			}	// Can't stop at rev, because we need to collect all pending actions for the context
+		}
+		// Continue stepping past the checkpoint until the given rev is reached
+		if (checkpointPath) {
+			for await (const path of this.chain.select(checkpointPath, false)) {
+				const entry = entryAt<LogEntry<TAction>>(path)!;
+				if (startRev !== undefined && entry.rev > startRev) {
+					if (entry.action) {
+						entries.unshift(entry.action!);
+					}
+				} else {
+					break;
+				}
+			}
+		}
+		return { context: rev ? { committed: pendings, rev } : undefined, entries };
+	}
+
+	/** Enumerates log entries from the given starting path or end if undefined, in forward (from tail to head) or reverse (from head to tail) order. */
+	async *select(starting?: ChainPath<LogEntry<TAction>>, forward = true) {
+		for await (const path of this.chain.select(starting, forward)) {
+			yield entryAt<LogEntry<TAction>>(path)!;
+		}
+	}
+
+	/** Returns the set of pending transactions in the most recent checkpoint, at or preceding the given path. */
+	private async findCheckpoint(starting: ChainPath<LogEntry<TAction>>) {
+		let lastPath: ChainPath<LogEntry<TAction>> | undefined;
+		let rev: number | undefined;
+		for await (const path of this.chain.select(starting, false)) {
+			const entry = entryAt<LogEntry<TAction>>(path)!;
+			rev = rev ?? entry.rev;
+			if (entry.checkpoint) {
+				return { path, pendings: entry.checkpoint.pendings, rev };
+			}
+			lastPath = path;
+		}
+		return lastPath ? { path: lastPath, pendings: [], rev } : undefined;
+	}
+
+	/** Returns the set of pending actions following, the given checkpoint path. */
+	private async pendingFrom(starting: ChainPath<LogEntry<TAction>>) {
+		const pendings: ActionRev[] = [];
+		for await (const actionPath of this.chain.select(starting)) {
+			const entry = entryAt<LogEntry<TAction>>(actionPath);
+			if (entry?.action) {
+				pendings.push({ actionId: entry.action.actionId, rev: entry.rev });
+			}
+		}
+		return pendings;
+	}
+
+	private static getChainOptions<TAction>(store: BlockStore<IBlock>) {
+		return {
+			createDataBlock: () => ({ header: store.createBlockHeader(LogDataBlockType) }),
+			createHeaderBlock: (id?: BlockId) => ({ header: store.createBlockHeader(LogHeaderBlockType, id) }),
+			newBlock: async (newTail: LogBlock<TAction>, oldTail: LogBlock<TAction> | undefined) => {
+				if (oldTail) {
+					const hash = await sha256.digest(new TextEncoder().encode(JSON.stringify(oldTail)));
+					newTail.priorHash = uint8ArrayToString(hash.digest, 'base64url');
+				}
+			},
+		} as ChainInitOptions<LogEntry<TAction>>;
+
+	}
+}