@typeberry/lib 0.8.4 → 0.9.0-4a9f363

package/packages/jam/database/value-refs.js

@@ -0,0 +1,206 @@
+import { HashDictionary } from "#@typeberry/collections";
+/** `true` if applying the update would not change anything. */
+export function isEmptyUpdate(update) {
+    return (update.finalizedCounts.length === 0 &&
+        update.pendingCounts.length === 0 &&
+        update.setDeltas.length === 0 &&
+        update.removeDeltas.length === 0 &&
+        update.removeValues.length === 0);
+}
+/**
+ * Decides when a content-addressed value can be removed from the values DB.
+ *
+ * A value is needed as long as some surviving state references it. Surviving
+ * states are the finalized tip plus its unfinalized descendants, so we track:
+ * - `finalized`: how many leaves in the current finalized-tip state reference V,
+ *   advanced strictly by replaying finalized blocks' deltas (never on prune);
+ * - `pending`: how many surviving, not-yet-finalized blocks inserted V (an
+ *   over-approximation of unfinalized references).
+ *
+ * A value is removable exactly when both counts reach zero.
+ *
+ * This class only makes decisions: every operation reads the current state
+ * through `ValueRefsReader` and returns a `ValueRefsUpdate` describing what
+ * should change. Nothing is written here - the owning backend applies the
+ * update with whatever consistency guarantees it can provide.
+ */
+export class ValueRefs {
+    reader;
+    constructor(reader) {
+        this.reader = reader;
+    }
+    /** Record values referenced by the genesis / initial finalized state. */
+    onInitial(inserted) {
+        const update = new UpdateBuilder(this.reader);
+        for (const v of inserted) {
+            update.incFinalized(v);
+        }
+        return update.build();
+    }
+    /**
+     * Record a freshly imported, not-yet-finalized block.
+     *
+     * Importing the same header twice is a no-op, otherwise the second import
+     * would double-count `pending` references and pin the values forever.
+     */
+    onImport(header, delta) {
+        const update = new UpdateBuilder(this.reader);
+        if (update.getDelta(header) !== undefined) {
+            return update.build();
+        }
+        update.setDelta(header, delta);
+        for (const v of delta.inserted) {
+            update.incPending(v);
+        }
+        return update.build();
+    }
+    /**
+     * Apply the value deltas of newly finalized blocks, in finalized (ancestor-first) order.
+     *
+     * Moves each inserted value from `pending` to `finalized`, drops `finalized`
+     * references for removed values, and collects anything that becomes unreferenced.
+     */
+    commitFinalized(headers) {
+        const update = new UpdateBuilder(this.reader);
+        for (const header of headers) {
+            const delta = update.getDelta(header);
+            if (delta === undefined) {
+                // already committed, or not tracked (e.g. genesis)
+                continue;
+            }
+            for (const v of delta.inserted) {
+                update.incFinalized(v);
+                update.decPending(v);
+            }
+            for (const v of delta.removed) {
+                update.decFinalized(v);
+            }
+            update.removeDelta(header);
+        }
+        return update.build();
+    }
+    /**
+     * Release the speculative references of a state being discarded.
+     *
+     * For a header that was still unfinalized (a dead fork) the returned update
+     * releases its inserted values, which may become collectable. For an already
+     * finalized state the update is empty (check with `isEmptyUpdate`): its delta
+     * was consumed on finality and its values are accounted for in `finalized`.
+     */
+    releaseUnfinalized(header) {
+        const update = new UpdateBuilder(this.reader);
+        const delta = update.getDelta(header);
+        if (delta === undefined) {
+            return update.build();
+        }
+        for (const v of delta.inserted) {
+            update.decPending(v);
+        }
+        update.removeDelta(header);
+        return update.build();
+    }
+}
+/**
+ * Accumulates mutations of a single operation as an overlay over the reader,
+ * so that later steps observe earlier ones (e.g. several blocks finalized at once).
+ */
+class UpdateBuilder {
+    reader;
+    finalized = HashDictionary.new();
+    pending = HashDictionary.new();
+    setDeltas = HashDictionary.new();
+    removedDeltas = HashDictionary.new();
+    /** Values that lost a reference and may need removal - verified against final counts in `build`. */
+    removalCandidates = HashDictionary.new();
+    constructor(reader) {
+        this.reader = reader;
+    }
+    getDelta(header) {
+        if (this.removedDeltas.has(header)) {
+            return undefined;
+        }
+        return this.setDeltas.get(header) ?? this.reader.getDelta(header);
+    }
+    setDelta(header, delta) {
+        this.setDeltas.set(header, delta);
+    }
+    removeDelta(header) {
+        this.removedDeltas.set(header, header);
+    }
+    incFinalized(v) {
+        this.finalized.set(v, this.getFinalized(v) + 1);
+    }
+    decFinalized(v) {
+        this.finalized.set(v, Math.max(0, this.getFinalized(v) - 1));
+        this.removalCandidates.set(v, v);
+    }
+    incPending(v) {
+        this.pending.set(v, this.getPending(v) + 1);
+    }
+    decPending(v) {
+        this.pending.set(v, Math.max(0, this.getPending(v) - 1));
+        this.removalCandidates.set(v, v);
+    }
+    build() {
+        const removeValues = [];
+        for (const v of this.removalCandidates.values()) {
+            if (this.getFinalized(v) === 0 && this.getPending(v) === 0) {
+                removeValues.push(v);
+            }
+        }
+        return {
+            finalizedCounts: Array.from(this.finalized),
+            pendingCounts: Array.from(this.pending),
+            setDeltas: Array.from(this.setDeltas),
+            removeDeltas: Array.from(this.removedDeltas.keys()),
+            removeValues,
+        };
+    }
+    getFinalized(v) {
+        return this.finalized.get(v) ?? this.reader.getFinalizedCount(v);
+    }
+    getPending(v) {
+        return this.pending.get(v) ?? this.reader.getPendingCount(v);
+    }
+}
+/**
+ * In-memory refcounting store, reusable by the in-memory and hybrid states DBs
+ * (the hybrids cannot resume from disk anyway, so persisting counts buys nothing).
+ *
+ * NOTE: `apply` does not touch the values DB - the caller owns it and must
+ * handle `update.removeValues` itself.
+ */
+export class InMemoryValueRefsStore {
+    finalized = HashDictionary.new();
+    pending = HashDictionary.new();
+    deltas = HashDictionary.new();
+    getFinalizedCount(hash) {
+        return this.finalized.get(hash) ?? 0;
+    }
+    getPendingCount(hash) {
+        return this.pending.get(hash) ?? 0;
+    }
+    getDelta(header) {
+        return this.deltas.get(header);
+    }
+    apply(update) {
+        applyCounts(this.finalized, update.finalizedCounts);
+        applyCounts(this.pending, update.pendingCounts);
+        for (const [header, delta] of update.setDeltas) {
+            this.deltas.set(header, delta);
+        }
+        for (const header of update.removeDeltas) {
+            this.deltas.delete(header);
+        }
+    }
+}
+function applyCounts(store, counts) {
+    for (const [hash, count] of counts) {
+        if (count === 0) {
+            store.delete(hash);
+        }
+        else {
+            store.set(hash, count);
+        }
+    }
+}

package/packages/jam/database/value-refs.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=value-refs.test.d.ts.map

package/packages/jam/database/value-refs.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-refs.test.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database/value-refs.test.ts"],"names":[],"mappings":""}

package/packages/jam/database/value-refs.test.js

@@ -0,0 +1,165 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { Bytes } from "#@typeberry/bytes";
+import { HASH_SIZE } from "#@typeberry/hash";
+import { InMemoryValueRefsStore, isEmptyUpdate, ValueRefs, } from "./value-refs.js";
+function vh(n) {
+    return Bytes.fill(HASH_SIZE, n).asOpaque();
+}
+function hh(n) {
+    return Bytes.fill(HASH_SIZE, n).asOpaque();
+}
+/** Tracks which value hashes are present in the (simulated) values DB. */
+class TrackingValues {
+    present = new Set();
+    write(h) {
+        this.present.add(h.toString());
+    }
+    delete(h) {
+        this.present.delete(h.toString());
+    }
+    has(h) {
+        return this.present.has(h.toString());
+    }
+}
+function setup() {
+    const store = new InMemoryValueRefsStore();
+    const refs = new ValueRefs(store);
+    const values = new TrackingValues();
+    // what every backend is expected to do with an update
+    const apply = (update) => {
+        store.apply(update);
+        for (const v of update.removeValues) {
+            values.delete(v);
+        }
+    };
+    return { refs, store, values, apply };
+}
+/** Simulate importing a block: write inserted values + record the delta. */
+function importBlock({ refs, values, apply }, header, delta) {
+    const full = { inserted: delta.inserted ?? [], removed: delta.removed ?? [] };
+    for (const v of full.inserted) {
+        values.write(v);
+    }
+    apply(refs.onImport(header, full));
+}
+describe("ValueRefs", () => {
+    it("deletes a value once its only finalized reference is removed", () => {
+        const s = setup();
+        const { refs, values, apply } = s;
+        const V = vh(1);
+        importBlock(s, hh(1), { inserted: [V] });
+        apply(refs.commitFinalized([hh(1)]));
+        assert.ok(values.has(V), "kept while referenced by finalized tip");
+        importBlock(s, hh(2), { removed: [V] });
+        apply(refs.commitFinalized([hh(2)]));
+        assert.ok(!values.has(V), "deleted after last finalized reference removed");
+    });
+    it("keeps a value referenced under multiple keys until all references are gone", () => {
+        const s = setup();
+        const { refs, values, apply } = s;
+        const V = vh(1);
+        importBlock(s, hh(1), { inserted: [V] });
+        apply(refs.commitFinalized([hh(1)]));
+        importBlock(s, hh(2), { inserted: [V] });
+        apply(refs.commitFinalized([hh(2)]));
+        importBlock(s, hh(3), { removed: [V] });
+        apply(refs.commitFinalized([hh(3)]));
+        assert.ok(values.has(V), "kept while one reference remains");
+        importBlock(s, hh(4), { removed: [V] });
+        apply(refs.commitFinalized([hh(4)]));
+        assert.ok(!values.has(V), "deleted after the last reference");
+    });
+    it("keeps a value removed on the finalized chain while an unfinalized fork re-adds it", () => {
+        const s = setup();
+        const { refs, values, apply } = s;
+        const V = vh(1);
+        // genesis already references V
+        apply(refs.onInitial([V]));
+        values.write(V);
+        // finalized chain removes V
+        importBlock(s, hh(10), { removed: [V] });
+        // an unfinalized fork re-adds V
+        importBlock(s, hh(20), { inserted: [V] });
+        apply(refs.commitFinalized([hh(10)]));
+        assert.ok(values.has(V), "kept because an unfinalized fork still references V");
+    });
+    it("collects a value that lived only on a discarded fork", () => {
+        const s = setup();
+        const { refs, values, apply } = s;
+        const W = vh(2);
+        importBlock(s, hh(30), { inserted: [W] });
+        assert.ok(values.has(W));
+        const update = refs.releaseUnfinalized(hh(30));
+        apply(update);
+        assert.strictEqual(isEmptyUpdate(update), false);
+        assert.ok(!values.has(W), "dead-fork-only value is collected");
+    });
+    it("does not touch finalized references when releasing an already finalized header", () => {
+        const s = setup();
+        const { refs, values, apply } = s;
+        const V = vh(1);
+        importBlock(s, hh(1), { inserted: [V] });
+        apply(refs.commitFinalized([hh(1)]));
+        const update = refs.releaseUnfinalized(hh(1));
+        apply(update);
+        assert.strictEqual(isEmptyUpdate(update), true, "header was already finalized");
+        assert.ok(values.has(V), "finalized value is untouched");
+    });
+    it("ignores unknown headers in commitFinalized", () => {
+        const { refs } = setup();
+        const update = refs.commitFinalized([hh(99)]);
+        assert.strictEqual(isEmptyUpdate(update), true);
+    });
+    it("ignores a duplicate import of the same header", () => {
+        const s = setup();
+        const { refs, values, apply } = s;
+        const V = vh(1);
+        importBlock(s, hh(1), { inserted: [V] });
+        const second = refs.onImport(hh(1), { inserted: [V], removed: [] });
+        assert.strictEqual(isEmptyUpdate(second), true, "duplicate import is a no-op");
+        // had the duplicate bumped `pending` twice, releasing the fork would leave
+        // a dangling count and the value would never be collected
+        apply(refs.releaseUnfinalized(hh(1)));
+        assert.ok(!values.has(V));
+    });
+    it("counts a header only once within a single commitFinalized call", () => {
+        const s = setup();
+        const { refs, values, apply } = s;
+        const V = vh(1);
+        importBlock(s, hh(1), { inserted: [V] });
+        apply(refs.commitFinalized([hh(1), hh(1)]));
+        importBlock(s, hh(2), { removed: [V] });
+        apply(refs.commitFinalized([hh(2)]));
+        assert.ok(!values.has(V), "a double-counted finalized reference would keep the value alive");
+    });
+    it("does not remove a value re-referenced later within the same batch", () => {
+        const s = setup();
+        const { refs, values, apply } = s;
+        const V = vh(1);
+        apply(refs.onInitial([V]));
+        values.write(V);
+        // one block removes V, its descendant re-adds it; both finalize at once
+        importBlock(s, hh(1), { removed: [V] });
+        importBlock(s, hh(2), { inserted: [V] });
+        const update = refs.commitFinalized([hh(1), hh(2)]);
+        apply(update);
+        assert.strictEqual(update.removeValues.length, 0);
+        assert.ok(values.has(V), "the re-added reference keeps the value alive");
+    });
+    it("emits absolute counts so re-applying an update is harmless", () => {
+        const s = setup();
+        const { refs, store, values, apply } = s;
+        const V = vh(1);
+        importBlock(s, hh(1), { inserted: [V] });
+        const update = refs.commitFinalized([hh(1)]);
+        apply(update);
+        // crash-replay: same batch applied again
+        apply(update);
+        assert.strictEqual(store.getFinalizedCount(V), 1);
+        assert.strictEqual(store.getPendingCount(V), 0);
+        importBlock(s, hh(2), { removed: [V] });
+        apply(refs.commitFinalized([hh(2)]));
+        assert.ok(!values.has(V), "refcounting still exact after replay");
+    });
+});

package/packages/jam/database-fjall/blocks.d.ts

@@ -0,0 +1,25 @@
+import { type BlockView, type ExtrinsicView, type HeaderHash, type HeaderView, type StateRootHash } from "#@typeberry/block";
+import type { ChainSpec } from "#@typeberry/config";
+import type { BlocksDb } from "#@typeberry/database/blocks.js";
+import { type WithHash } from "#@typeberry/hash";
+import { type FjallRoot } from "./root.js";
+/** fjall-backed block storage. */
+export declare class FjallBlocks implements BlocksDb {
+    private readonly chainSpec;
+    private readonly root;
+    private readonly headers;
+    private readonly extrinsics;
+    private readonly postStateRoots;
+    static open(chainSpec: ChainSpec, root: FjallRoot): Promise<FjallBlocks>;
+    private constructor();
+    setPostStateRoot(hash: HeaderHash, postStateRoot: StateRootHash): Promise<void>;
+    getPostStateRoot(hash: HeaderHash): StateRootHash | null;
+    insertBlock(block: WithHash<HeaderHash, BlockView>): Promise<void>;
+    setBestHeaderHash(hash: HeaderHash): Promise<void>;
+    getBestHeaderHash(): HeaderHash;
+    getHeader(hash: HeaderHash): HeaderView | null;
+    getExtrinsic(hash: HeaderHash): ExtrinsicView | null;
+    markUnused(hash: HeaderHash): void;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=blocks.d.ts.map

package/packages/jam/database-fjall/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database-fjall/blocks.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,aAAa,EAElB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EAAuB,KAAK,SAAS,EAAgC,MAAM,WAAW,CAAC;AAK9F,kCAAkC;AAClC,qBAAa,WAAY,YAAW,QAAQ;IAWxC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,cAAc;WAdpB,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IAS9E,OAAO;IAQD,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrF,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,GAAG,IAAI;IAQlD,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlE,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD,iBAAiB,IAAI,UAAU;IAQ/B,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI;IAQ9C,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,GAAG,IAAI;IAQpD,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQ5B,KAAK;CACZ"}

package/packages/jam/database-fjall/blocks.js

@@ -0,0 +1,86 @@
+import { Extrinsic, Header, } from "#@typeberry/block";
+import { Bytes } from "#@typeberry/bytes";
+import { Decoder } from "#@typeberry/codec";
+import { HASH_SIZE } from "#@typeberry/hash";
+import { Logger } from "#@typeberry/logger";
+import { toUint8Array } from "./root.js";
+const BEST_BLOCK = new TextEncoder().encode("best hash and posterior state root");
+const logger = Logger.new(import.meta.filename, "db");
+/** fjall-backed block storage. */
+export class FjallBlocks {
+    chainSpec;
+    root;
+    headers;
+    extrinsics;
+    postStateRoots;
+    static async open(chainSpec, root) {
+        const [headers, extrinsics, postStateRoots] = await Promise.all([
+            root.partition("headers"),
+            root.partition("extrinsics"),
+            root.partition("postStateRoots"),
+        ]);
+        return new FjallBlocks(chainSpec, root, headers, extrinsics, postStateRoots);
+    }
+    constructor(chainSpec, root, headers, extrinsics, postStateRoots) {
+        this.chainSpec = chainSpec;
+        this.root = root;
+        this.headers = headers;
+        this.extrinsics = extrinsics;
+        this.postStateRoots = postStateRoots;
+    }
+    async setPostStateRoot(hash, postStateRoot) {
+        await writable(this.postStateRoots, this.root).insert(hash.raw, postStateRoot.raw);
+    }
+    getPostStateRoot(hash) {
+        const postStateRoot = toUint8Array(this.postStateRoots.get(hash.raw));
+        if (postStateRoot === null) {
+            return null;
+        }
+        return Bytes.fromBlob(postStateRoot, HASH_SIZE).asOpaque();
+    }
+    async insertBlock(block) {
+        await Promise.all([
+            writable(this.headers, this.root).insert(block.hash.raw, block.data.header.view().encoded().raw),
+            writable(this.extrinsics, this.root).insert(block.hash.raw, block.data.extrinsic.view().encoded().raw),
+        ]);
+    }
+    async setBestHeaderHash(hash) {
+        await writable(this.headers, this.root).insert(BEST_BLOCK, hash.raw);
+        await this.root.persist();
+    }
+    getBestHeaderHash() {
+        const bestHeaderHash = toUint8Array(this.headers.get(BEST_BLOCK));
+        if (bestHeaderHash === null) {
+            return Bytes.zero(HASH_SIZE).asOpaque();
+        }
+        return Bytes.fromBlob(bestHeaderHash, HASH_SIZE).asOpaque();
+    }
+    getHeader(hash) {
+        const data = toUint8Array(this.headers.get(hash.raw));
+        if (data === null) {
+            return null;
+        }
+        return Decoder.decodeObject(Header.Codec.View, data, this.chainSpec);
+    }
+    getExtrinsic(hash) {
+        const data = toUint8Array(this.extrinsics.get(hash.raw));
+        if (data === null) {
+            return null;
+        }
+        return Decoder.decodeObject(Extrinsic.Codec.View, data, this.chainSpec);
+    }
+    markUnused(hash) {
+        void Promise.all([
+            writable(this.headers, this.root).remove(hash.raw),
+            writable(this.extrinsics, this.root).remove(hash.raw),
+            writable(this.postStateRoots, this.root).remove(hash.raw),
+        ]).catch((e) => logger.warn `Failed to prune block ${hash}: ${e}`);
+    }
+    async close() { }
+}
+function writable(partition, root) {
+    if (root.readOnly) {
+        throw new Error("Cannot write through a read-only fjall partition.");
+    }
+    return partition;
+}

package/packages/jam/database-fjall/blocks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=blocks.test.d.ts.map

package/packages/jam/database-fjall/blocks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.test.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database-fjall/blocks.test.ts"],"names":[],"mappings":""}

package/packages/jam/database-fjall/blocks.test.js

@@ -0,0 +1,62 @@
+import assert from "node:assert";
+import * as fs from "node:fs";
+import { afterEach, before, beforeEach, describe, it } from "node:test";
+import { testBlockView } from "#@typeberry/block/test-helpers.js";
+import { Bytes } from "#@typeberry/bytes";
+import { tinyChainSpec } from "#@typeberry/config";
+import { Blake2b, HASH_SIZE, WithHash } from "#@typeberry/hash";
+import { FjallBlocks } from "./blocks.js";
+import { FjallRoot } from "./root.js";
+let blake2b;
+before(async () => {
+    blake2b = await Blake2b.createHasher();
+});
+describe("Fjall blocks database", () => {
+    let tmpDir = "";
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync("typeberry-fjall-blocks-");
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("sets and retrieves the best header hash", async () => {
+        const root = await FjallRoot.open(tmpDir, { ephemeral: true });
+        const blocks = await FjallBlocks.open(tinyChainSpec, root);
+        try {
+            await blocks.setBestHeaderHash(Bytes.fill(HASH_SIZE, 5).asOpaque());
+            assert.strictEqual(blocks.getBestHeaderHash().toString(), "0x0505050505050505050505050505050505050505050505050505050505050505");
+        }
+        finally {
+            await blocks.close();
+            await root.close();
+        }
+    });
+    it("sets and retrieves post state roots", async () => {
+        const root = await FjallRoot.open(tmpDir, { ephemeral: true });
+        const blocks = await FjallBlocks.open(tinyChainSpec, root);
+        try {
+            await blocks.setPostStateRoot(Bytes.fill(HASH_SIZE, 5).asOpaque(), Bytes.fill(HASH_SIZE, 10).asOpaque());
+            assert.strictEqual(blocks.getPostStateRoot(Bytes.fill(HASH_SIZE, 1).asOpaque())?.toString(), undefined);
+            assert.strictEqual(blocks.getPostStateRoot(Bytes.fill(HASH_SIZE, 5).asOpaque())?.toString(), "0x0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a");
+        }
+        finally {
+            await blocks.close();
+            await root.close();
+        }
+    });
+    it("stores and retrieves a block", async () => {
+        const root = await FjallRoot.open(tmpDir, { ephemeral: true });
+        const blocks = await FjallBlocks.open(tinyChainSpec, root);
+        try {
+            const block = testBlockView();
+            const headerHash = blake2b.hashBytes(block.header.view().encoded()).asOpaque();
+            await blocks.insertBlock(WithHash.new(headerHash, block));
+            assert.deepStrictEqual(blocks.getHeader(headerHash)?.materialize(), block.header.materialize());
+            assert.deepStrictEqual(blocks.getExtrinsic(headerHash)?.materialize(), block.extrinsic.materialize());
+        }
+        finally {
+            await blocks.close();
+            await root.close();
+        }
+    });
+});

package/packages/jam/database-fjall/hybrid-states.d.ts

@@ -0,0 +1,96 @@
+import type { HeaderHash, StateRootHash } from "#@typeberry/block";
+import type { ChainSpec } from "#@typeberry/config";
+import { type InitStatesDb, LeafDb, type StatesDb, StateUpdateError } from "#@typeberry/database";
+import type { Blake2b } from "#@typeberry/hash";
+import type { ServicesUpdate, State } from "#@typeberry/state";
+import { SerializedState, type StateEntries } from "#@typeberry/state-merkleization";
+import { OK, Result } from "#@typeberry/utils";
+import { type FjallRootOptions, type Partition } from "./root.js";
+/**
+ * One open fjall keyspace together with its content-addressed `values`
+ * partition.
+ *
+ * Opening the keyspace is the slow part, so the fuzz target opens one session
+ * per run and reuses it for every reset (see `HybridSerializedStates.fromSession`).
+ * The values partition is immutable - the key is the hash of the value - so it
+ * is fine that values pile up across resets, the unreferenced ones just sit
+ * there unused.
+ */
+export declare class FjallValuesSession {
+    private readonly root;
+    /** Shared content-addressed values partition, reused across resets. */
+    readonly values: Partition;
+    private constructor();
+    /** Open (or create) the keyspace at `dbPath` and its `values` partition. */
+    static open(dbPath: string, options?: FjallRootOptions): Promise<FjallValuesSession>;
+    /** Flush the journal to disk (a no-op for ephemeral keyspaces). */
+    persist(): Promise<void>;
+    /** Size of the keyspace directory on disk, in bytes. */
+    sizeInBytes(): number | null;
+    /** Release the keyspace handle (skips the sync-all fsync when ephemeral). */
+    close(): Promise<void>;
+}
+/**
+ * Hybrid serialized-states db (fjall variant).
+ *
+ * States (leafs) are kept in memory, only the large values go to fjall on disk.
+ * Reads hit fjall directly, which keeps its own bounded block cache. Meant for
+ * long fuzzing, used together with pruning so the heap stays bounded.
+ *
+ * Construction is async, and value writes are flushed explicitly, because fjall
+ * has no transaction primitive.
+ *
+ * Values that no longer belong to any surviving state are removed from fjall,
+ * decided by in-memory refcounting (`ValueRefs`) driven by the importer's
+ * finality signal. Counts are not persisted: this db cannot resume from disk
+ * anyway (the leaf sets live in memory), so values left over by a previous run
+ * are never collected. An instance backed by a shared session (fuzz reset
+ * reuse) only ever prunes values it inserted itself, since its refcounts start
+ * empty - values left behind by earlier resets stay untouched.
+ */
+export declare class HybridSerializedStates implements StatesDb<SerializedState<LeafDb>>, InitStatesDb<StateEntries> {
+    private readonly spec;
+    private readonly blake2b;
+    private readonly session;
+    /** Whether `close()` should close the underlying session. */
+    private readonly ownsSession;
+    static new({ spec, blake2b, dbPath, ephemeral, cacheSizeBytes, }: {
+        spec: ChainSpec;
+        blake2b: Blake2b;
+        dbPath: string;
+        ephemeral?: boolean;
+        cacheSizeBytes?: number;
+    }): Promise<HybridSerializedStates>;
+    /**
+     * Wrap an already-open `FjallValuesSession` and reuse its keyspace.
+     *
+     * The new instance starts with its own empty in-memory leaf sets but shares
+     * the values partition on disk. Its `close()` does not close the session, the
+     * session owner closes it once. The fuzz target uses this to keep one keyspace
+     * across resets and only rebuild the in-memory state for each vector.
+     */
+    static fromSession(spec: ChainSpec, blake2b: Blake2b, session: FjallValuesSession): HybridSerializedStates;
+    private readonly inMemStates;
+    private readonly valuesDb;
+    /** Shared content-addressed values partition (owned by `session`). */
+    private readonly values;
+    private readonly refsStore;
+    private readonly refs;
+    private pendingCleanup;
+    private constructor();
+    insertInitialState(headerHash: HeaderHash, entries: StateEntries): Promise<Result<OK, StateUpdateError>>;
+    updateAndSetState(header: HeaderHash, state: SerializedState<LeafDb>, update: Partial<State & ServicesUpdate>): Promise<Result<OK, StateUpdateError>>;
+    getStateRoot(state: SerializedState<LeafDb>): Promise<StateRootHash>;
+    getState(header: HeaderHash): SerializedState<LeafDb> | null;
+    commitFinalized(headers: HeaderHash[]): void;
+    markUnused(header: HeaderHash): void;
+    diskSizeInBytes(): number | null;
+    /** Apply a refcounting update and remove values that lost their last reference. */
+    private applyRefs;
+    close(): Promise<void>;
+    /** Write new large values to fjall in a single batch, then flush. */
+    private writeValues;
+    /** Read a value from fjall. */
+    private readValue;
+}
+//# sourceMappingURL=hybrid-states.d.ts.map

package/packages/jam/database-fjall/hybrid-states.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-states.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database-fjall/hybrid-states.ts"],"names":[],"mappings":"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"}