@typeberry/lib 0.5.1-aff8b4f → 0.5.1-eb84786

package/packages/jam/state-merkleization/in-memory-state-codec.js

@@ -0,0 +1,155 @@
+import { codecPerValidator } from "#@typeberry/block";
+import { codecHashDictionary } from "#@typeberry/block/codec-utils.js";
+import { Ticket } from "#@typeberry/block/tickets.js";
+import { codec, Descriptor } from "#@typeberry/codec";
+import { asKnownSize, HashDictionary } from "#@typeberry/collections";
+import { BANDERSNATCH_RING_ROOT_BYTES } from "#@typeberry/crypto/bandersnatch.js";
+import { HASH_SIZE } from "#@typeberry/hash";
+import { tryAsU32 } from "#@typeberry/numbers";
+import { Ordering } from "#@typeberry/ordering";
+import { InMemoryService, InMemoryState, LookupHistoryItem, PreimageItem, ServiceAccountInfo, StorageItem, tryAsLookupHistorySlots, ValidatorData, } from "#@typeberry/state";
+import { SafroleSealingKeysData } from "#@typeberry/state/safrole-data.js";
+import { seeThrough } from "#@typeberry/utils";
+import { serialize } from "./serialize.js";
+/** Codec for a map with string keys. */
+export const codecMap = (value, extractKey, { typicalLength = codec.TYPICAL_DICTIONARY_LENGTH, compare = (a, b) => {
+    const keyA = extractKey(a);
+    const keyB = extractKey(b);
+    if (keyA < keyB) {
+        return Ordering.Less;
+    }
+    if (keyA > keyB) {
+        return Ordering.Greater;
+    }
+    return Ordering.Equal;
+}, } = {}) => {
+    return Descriptor.new(`Map<${value.name}>[?]`, {
+        bytes: typicalLength * value.sizeHint.bytes,
+        isExact: false,
+    }, (e, v) => {
+        const data = Array.from(v.values());
+        data.sort((a, b) => compare(a, b).value);
+        e.varU32(tryAsU32(data.length));
+        for (const v of data) {
+            value.encode(e, v);
+        }
+    }, (d) => {
+        const map = new Map();
+        const len = d.varU32();
+        let prevValue = null;
+        for (let i = 0; i < len; i += 1) {
+            const v = value.decode(d);
+            const k = extractKey(v);
+            if (map.has(k)) {
+                throw new Error(`Duplicate item in the dictionary encoding: "${k}"!`);
+            }
+            if (prevValue !== null && compare(prevValue, v).isGreaterOrEqual()) {
+                throw new Error(`The keys in dictionary encoding are not sorted "${extractKey(prevValue)}" >= "${extractKey(v)}"!`);
+            }
+            map.set(k, v);
+            prevValue = v;
+        }
+        return map;
+    }, (s) => {
+        const len = s.decoder.varU32();
+        s.sequenceFixLen(value, len);
+    });
+};
+const lookupHistoryItemCodec = codec.object({
+    hash: codec.bytes(HASH_SIZE).asOpaque(),
+    length: codec.u32,
+    slots: codec
+        .readonlyArray(codec.sequenceVarLen(codec.u32.asOpaque()))
+        .convert(seeThrough, tryAsLookupHistorySlots),
+}, "LookupHistoryItem", ({ hash, length, slots }) => new LookupHistoryItem(hash, length, slots));
+const lookupHistoryEntryCodec = codec.object({
+    key: codec.bytes(HASH_SIZE).asOpaque(),
+    data: codec.sequenceVarLen(lookupHistoryItemCodec),
+});
+const lookupHistoryCodec = codec
+    .sequenceVarLen(lookupHistoryEntryCodec)
+    .convert((dict) => {
+    const entries = [];
+    for (const [key, data] of dict) {
+        entries.push({
+            key,
+            data,
+        });
+    }
+    return entries;
+}, (items) => {
+    const dict = HashDictionary.new();
+    for (const { key, data } of items) {
+        const items = dict.get(key) ?? [];
+        items.push(...data);
+        dict.set(key, items);
+    }
+    return dict;
+});
+class ServiceWithCodec extends InMemoryService {
+    static Codec = codec.Class(ServiceWithCodec, {
+        serviceId: codec.u32.asOpaque(),
+        data: codec.object({
+            info: ServiceAccountInfo.Codec,
+            preimages: codecHashDictionary(PreimageItem.Codec, (x) => x.hash),
+            lookupHistory: lookupHistoryCodec,
+            storage: codecMap(StorageItem.Codec, (x) => x.key.toString()),
+        }),
+    });
+    constructor(id, data) {
+        super(id, data);
+    }
+    static create({ serviceId, data }) {
+        return new ServiceWithCodec(serviceId, data);
+    }
+}
+export const inMemoryStateCodec = (spec) => codec.Class(class State extends InMemoryState {
+    static create(data) {
+        return InMemoryState.new(spec, data);
+    }
+}, {
+    // alpha
+    authPools: serialize.authPools.Codec,
+    // phi
+    authQueues: serialize.authQueues.Codec,
+    // beta
+    recentBlocks: serialize.recentBlocks.Codec,
+    // gamma_k
+    nextValidatorData: codecPerValidator(ValidatorData.Codec),
+    // gamma_z
+    epochRoot: codec.bytes(BANDERSNATCH_RING_ROOT_BYTES).asOpaque(),
+    // gamma_s
+    sealingKeySeries: SafroleSealingKeysData.Codec,
+    // gamma_a
+    ticketsAccumulator: codec
+        .readonlyArray(codec.sequenceVarLen(Ticket.Codec))
+        .convert((x) => x, asKnownSize),
+    // psi
+    disputesRecords: serialize.disputesRecords.Codec,
+    // eta
+    entropy: serialize.entropy.Codec,
+    // iota
+    designatedValidatorData: serialize.designatedValidators.Codec,
+    // kappa
+    currentValidatorData: serialize.currentValidators.Codec,
+    // lambda
+    previousValidatorData: serialize.previousValidators.Codec,
+    // rho
+    availabilityAssignment: serialize.availabilityAssignment.Codec,
+    // tau
+    timeslot: serialize.timeslot.Codec,
+    // chi
+    privilegedServices: serialize.privilegedServices.Codec,
+    // pi
+    statistics: serialize.statistics.Codec,
+    // omega
+    accumulationQueue: serialize.accumulationQueue.Codec,
+    // xi
+    recentlyAccumulated: serialize.recentlyAccumulated.Codec,
+    // theta
+    accumulationOutputLog: serialize.accumulationOutputLog.Codec,
+    // delta
+    services: codec.dictionary(codec.u32.asOpaque(), ServiceWithCodec.Codec, {
+        sortKeys: (a, b) => a - b,
+    }),
+});

package/packages/jam/state-merkleization/in-memory-state-codec.test.d.ts

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

package/packages/jam/state-merkleization/in-memory-state-codec.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-state-codec.test.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/state-merkleization/in-memory-state-codec.test.ts"],"names":[],"mappings":""}

package/packages/jam/state-merkleization/in-memory-state-codec.test.js

@@ -0,0 +1,55 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { BytesBlob } from "#@typeberry/bytes";
+import { codec, Decoder, Encoder } from "#@typeberry/codec";
+import { asOpaqueType } from "#@typeberry/utils";
+import { codecMap } from "./in-memory-state-codec.js";
+describe("JAM types codec / Map", () => {
+    class StorageItem {
+        key;
+        value;
+        static Codec = codec.Class(StorageItem, {
+            key: codec.blob.convert((i) => i, (o) => asOpaqueType(o)),
+            value: codec.blob,
+        });
+        static create({ key, value }) {
+            return new StorageItem(key, value);
+        }
+        constructor(key, value) {
+            this.key = key;
+            this.value = value;
+        }
+    }
+    const dictionaryCodec = codecMap(StorageItem.Codec, (x) => x.key.toString(), { typicalLength: 10 });
+    const arrayCodec = codec.sequenceVarLen(StorageItem.Codec);
+    it("should be compatible with a list", () => {
+        const list = ["0x00", "0x01", "0x02"]
+            .map(BytesBlob.parseBlob)
+            .map((x) => StorageItem.create({ key: asOpaqueType(x), value: x }));
+        const encoded = Encoder.encodeObject(arrayCodec, list);
+        const decoded = Decoder.decodeObject(dictionaryCodec, encoded);
+        const reencoded = Encoder.encodeObject(dictionaryCodec, decoded);
+        const decodedlist = Decoder.decodeObject(arrayCodec, reencoded);
+        assert.deepStrictEqual(list, decodedlist);
+        assert.deepStrictEqual(encoded.toString(), reencoded.toString());
+        assert.deepStrictEqual(list, Array.from(decoded.values()));
+    });
+    it("should throw an error if order is incorrect", () => {
+        const list = ["0x00", "0x02", "0x01"]
+            .map(BytesBlob.parseBlob)
+            .map((x) => StorageItem.create({ key: asOpaqueType(x), value: x }));
+        const encoded = Encoder.encodeObject(arrayCodec, list);
+        assert.throws(() => {
+            Decoder.decodeObject(dictionaryCodec, encoded);
+        }, new Error('The keys in dictionary encoding are not sorted "0x02" >= "0x01"!'));
+    });
+    it("should throw an error if there are duplicates", () => {
+        const list = ["0x00", "0x01", "0x01"]
+            .map(BytesBlob.parseBlob)
+            .map((x) => StorageItem.create({ key: asOpaqueType(x), value: x }));
+        const encoded = Encoder.encodeObject(arrayCodec, list);
+        assert.throws(() => {
+            Decoder.decodeObject(dictionaryCodec, encoded);
+        }, new Error('Duplicate item in the dictionary encoding: "0x01"!'));
+    });
+});

package/packages/jam/state-merkleization/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * JAM State Serialization & Merkleization.
+ *
+ * https://graypaper.fluffylabs.dev/#/5f542d7/389f00389f00
+ *
+ * State representations:
+ *
+ * We maintain two "views" of our chain state:
+ *
+ * - **InMemoryState**
+ *   - Full, canonical state held entirely in memory.
+ *   - Complete info on every field, plus lists of services, modules, etc.
+ *
+ * - **SerializedState<T>**
+ *   - Generic wrapper around a serialized snapshot of the state.
+ *   - Only the bytes (and minimal metadata) are held up front.
+ *   - Three instantiations:
+ *     - `SerializedState<Persistence>`: Pure "black-box" serialized blob
+ *        (incomplete in-memory view).
+ *     - `SerializedState<LeafDb>`: Disk-backed trie storage-leaf nodes live on
+ *        disk and load on demand; cheap to update (no data duplication) and re-compute
+ *        the `stateRoot`. Used in LMDB.
+ *     - `SerializedState<StateEntries>`: serialized state represented as a simple in-memory
+ *        hashmap of `key -> value` entries.
+ */
+export * from "./binary-merkleization.js";
+export * from "./keys.js";
+export * from "./loader.js";
+export * from "./serialize.js";
+export * from "./serialize-state-update.js";
+export * from "./serialized-state.js";
+export * from "./serialized-state-view.js";
+export * from "./state-entries.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/jam/state-merkleization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/state-merkleization/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC"}

package/packages/jam/state-merkleization/index.js

@@ -0,0 +1,33 @@
+/**
+ * JAM State Serialization & Merkleization.
+ *
+ * https://graypaper.fluffylabs.dev/#/5f542d7/389f00389f00
+ *
+ * State representations:
+ *
+ * We maintain two "views" of our chain state:
+ *
+ * - **InMemoryState**
+ *   - Full, canonical state held entirely in memory.
+ *   - Complete info on every field, plus lists of services, modules, etc.
+ *
+ * - **SerializedState<T>**
+ *   - Generic wrapper around a serialized snapshot of the state.
+ *   - Only the bytes (and minimal metadata) are held up front.
+ *   - Three instantiations:
+ *     - `SerializedState<Persistence>`: Pure "black-box" serialized blob
+ *        (incomplete in-memory view).
+ *     - `SerializedState<LeafDb>`: Disk-backed trie storage-leaf nodes live on
+ *        disk and load on demand; cheap to update (no data duplication) and re-compute
+ *        the `stateRoot`. Used in LMDB.
+ *     - `SerializedState<StateEntries>`: serialized state represented as a simple in-memory
+ *        hashmap of `key -> value` entries.
+ */
+export * from "./binary-merkleization.js";
+export * from "./keys.js";
+export * from "./loader.js";
+export * from "./serialize.js";
+export * from "./serialize-state-update.js";
+export * from "./serialized-state.js";
+export * from "./serialized-state-view.js";
+export * from "./state-entries.js";

package/packages/jam/state-merkleization/keys.d.ts

@@ -0,0 +1,63 @@
+import type { ServiceId } from "#@typeberry/block";
+import type { PreimageHash } from "#@typeberry/block/preimage.js";
+import { BytesBlob } from "#@typeberry/bytes";
+import { type Blake2b, type OpaqueHash } from "#@typeberry/hash";
+import { type U32 } from "#@typeberry/numbers";
+import type { StorageKey } from "#@typeberry/state";
+import type { Opaque } from "#@typeberry/utils";
+export type StateKey = Opaque<OpaqueHash, "stateKey">;
+/** Numeric mapping for state entries. */
+export declare enum StateKeyIdx {
+    Unused = 0,
+    /**Authorizer Pool */
+    Alpha = 1,
+    /** Authorizer Queue */
+    Phi = 2,
+    /** Recent History */
+    Beta = 3,
+    /** Safrole */
+    Gamma = 4,
+    /** Disputes Records (Judgements) */
+    Psi = 5,
+    /** Entropy */
+    Eta = 6,
+    /** Next Validators */
+    Iota = 7,
+    /** Current Validators */
+    Kappa = 8,
+    /** Previous Validators */
+    Lambda = 9,
+    /** Availability Assignment */
+    Rho = 10,
+    /** Current time slot */
+    Tau = 11,
+    /** Privileged Services */
+    Chi = 12,
+    /** Statistics */
+    Pi = 13,
+    /** Work Packages ready to be accumulated. NOTE: Pre 0.7.0 was called `Theta` */
+    Omega = 14,
+    /** Work Packages recently accumulated */
+    Xi = 15,
+    /** Recent Merkle mountain belts */
+    Theta = 16,
+    /** Services data */
+    Delta = 255
+}
+export declare namespace stateKeys {
+    /** https://graypaper.fluffylabs.dev/#/85129da/38e50038e500?v=0.6.3 */
+    function index(index: StateKeyIdx): StateKey;
+    /** https://graypaper.fluffylabs.dev/#/85129da/382b03382b03?v=0.6.3 */
+    function serviceInfo(serviceId: ServiceId): StateKey;
+    /** https://graypaper.fluffylabs.dev/#/1c979cb/3bba033bba03?v=0.7.1 */
+    function serviceStorage(blake2b: Blake2b, serviceId: ServiceId, key: StorageKey): StateKey;
+    /** https://graypaper.fluffylabs.dev/#/1c979cb/3bd7033bd703?v=0.7.1 */
+    function servicePreimage(blake2b: Blake2b, serviceId: ServiceId, hash: PreimageHash): StateKey;
+    /** https://graypaper.fluffylabs.dev/#/1c979cb/3b0a043b0a04?v=0.7.1 */
+    function serviceLookupHistory(blake2b: Blake2b, serviceId: ServiceId, hash: PreimageHash, preimageLength: U32): StateKey;
+    /** https://graypaper.fluffylabs.dev/#/1c979cb/3b88003b8800?v=0.7.1 */
+    function serviceNested(blake2b: Blake2b, serviceId: ServiceId, numberPrefix: U32, hash: BytesBlob): StateKey;
+}
+/** https://graypaper.fluffylabs.dev/#/85129da/380101380101?v=0.6.3 */
+export declare function legacyServiceNested(serviceId: ServiceId, hash: OpaqueHash): StateKey;
+//# sourceMappingURL=keys.d.ts.map

package/packages/jam/state-merkleization/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/state-merkleization/keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAS,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAY,KAAK,GAAG,EAAgB,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;AAEtD,yCAAyC;AACzC,oBAAY,WAAW;IACrB,MAAM,IAAI;IACV,qBAAqB;IACrB,KAAK,IAAI;IACT,uBAAuB;IACvB,GAAG,IAAI;IACP,qBAAqB;IACrB,IAAI,IAAI;IACR,cAAc;IACd,KAAK,IAAI;IACT,oCAAoC;IACpC,GAAG,IAAI;IACP,cAAc;IACd,GAAG,IAAI;IACP,sBAAsB;IACtB,IAAI,IAAI;IACR,yBAAyB;IACzB,KAAK,IAAI;IACT,0BAA0B;IAC1B,MAAM,IAAI;IACV,8BAA8B;IAC9B,GAAG,KAAK;IACR,wBAAwB;IACxB,GAAG,KAAK;IACR,0BAA0B;IAC1B,GAAG,KAAK;IACR,iBAAiB;IACjB,EAAE,KAAK;IACP,gFAAgF;IAChF,KAAK,KAAK;IACV,yCAAyC;IACzC,EAAE,KAAK;IACP,mCAAmC;IACnC,KAAK,KAAK;IACV,oBAAoB;IACpB,KAAK,MAAM;CACZ;AAED,yBAAiB,SAAS,CAAC;IACzB,sEAAsE;IACtE,SAAgB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ,CAIlD;IAED,sEAAsE;IACtE,SAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAS1D;IAED,sEAAsE;IACtE,SAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,QAAQ,CAEhG;IAED,sEAAsE;IACtE,SAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,GAAG,QAAQ,CAEpG;IAED,sEAAsE;IACtE,SAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,YAAY,EAClB,cAAc,EAAE,GAAG,GAClB,QAAQ,CAEV;IAED,sEAAsE;IACtE,SAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAclH;CACF;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,CAYpF"}

package/packages/jam/state-merkleization/keys.js

@@ -0,0 +1,110 @@
+import { Bytes, BytesBlob } from "#@typeberry/bytes";
+import { HASH_SIZE } from "#@typeberry/hash";
+import { tryAsU32, u32AsLeBytes } from "#@typeberry/numbers";
+/** Numeric mapping for state entries. */
+export var StateKeyIdx;
+(function (StateKeyIdx) {
+    StateKeyIdx[StateKeyIdx["Unused"] = 0] = "Unused";
+    /**Authorizer Pool */
+    StateKeyIdx[StateKeyIdx["Alpha"] = 1] = "Alpha";
+    /** Authorizer Queue */
+    StateKeyIdx[StateKeyIdx["Phi"] = 2] = "Phi";
+    /** Recent History */
+    StateKeyIdx[StateKeyIdx["Beta"] = 3] = "Beta";
+    /** Safrole */
+    StateKeyIdx[StateKeyIdx["Gamma"] = 4] = "Gamma";
+    /** Disputes Records (Judgements) */
+    StateKeyIdx[StateKeyIdx["Psi"] = 5] = "Psi";
+    /** Entropy */
+    StateKeyIdx[StateKeyIdx["Eta"] = 6] = "Eta";
+    /** Next Validators */
+    StateKeyIdx[StateKeyIdx["Iota"] = 7] = "Iota";
+    /** Current Validators */
+    StateKeyIdx[StateKeyIdx["Kappa"] = 8] = "Kappa";
+    /** Previous Validators */
+    StateKeyIdx[StateKeyIdx["Lambda"] = 9] = "Lambda";
+    /** Availability Assignment */
+    StateKeyIdx[StateKeyIdx["Rho"] = 10] = "Rho";
+    /** Current time slot */
+    StateKeyIdx[StateKeyIdx["Tau"] = 11] = "Tau";
+    /** Privileged Services */
+    StateKeyIdx[StateKeyIdx["Chi"] = 12] = "Chi";
+    /** Statistics */
+    StateKeyIdx[StateKeyIdx["Pi"] = 13] = "Pi";
+    /** Work Packages ready to be accumulated. NOTE: Pre 0.7.0 was called `Theta` */
+    StateKeyIdx[StateKeyIdx["Omega"] = 14] = "Omega";
+    /** Work Packages recently accumulated */
+    StateKeyIdx[StateKeyIdx["Xi"] = 15] = "Xi";
+    /** Recent Merkle mountain belts */
+    StateKeyIdx[StateKeyIdx["Theta"] = 16] = "Theta";
+    /** Services data */
+    StateKeyIdx[StateKeyIdx["Delta"] = 255] = "Delta";
+})(StateKeyIdx || (StateKeyIdx = {}));
+export var stateKeys;
+(function (stateKeys) {
+    /** https://graypaper.fluffylabs.dev/#/85129da/38e50038e500?v=0.6.3 */
+    function index(index) {
+        const key = Bytes.zero(HASH_SIZE);
+        key.raw[0] = index;
+        return key.asOpaque();
+    }
+    stateKeys.index = index;
+    /** https://graypaper.fluffylabs.dev/#/85129da/382b03382b03?v=0.6.3 */
+    function serviceInfo(serviceId) {
+        const key = Bytes.zero(HASH_SIZE);
+        key.raw[0] = StateKeyIdx.Delta;
+        let i = 1;
+        for (const byte of u32AsLeBytes(serviceId)) {
+            key.raw[i] = byte;
+            i += 2;
+        }
+        return key.asOpaque();
+    }
+    stateKeys.serviceInfo = serviceInfo;
+    /** https://graypaper.fluffylabs.dev/#/1c979cb/3bba033bba03?v=0.7.1 */
+    function serviceStorage(blake2b, serviceId, key) {
+        return serviceNested(blake2b, serviceId, tryAsU32(2 ** 32 - 1), key);
+    }
+    stateKeys.serviceStorage = serviceStorage;
+    /** https://graypaper.fluffylabs.dev/#/1c979cb/3bd7033bd703?v=0.7.1 */
+    function servicePreimage(blake2b, serviceId, hash) {
+        return serviceNested(blake2b, serviceId, tryAsU32(2 ** 32 - 2), hash);
+    }
+    stateKeys.servicePreimage = servicePreimage;
+    /** https://graypaper.fluffylabs.dev/#/1c979cb/3b0a043b0a04?v=0.7.1 */
+    function serviceLookupHistory(blake2b, serviceId, hash, preimageLength) {
+        return serviceNested(blake2b, serviceId, preimageLength, hash);
+    }
+    stateKeys.serviceLookupHistory = serviceLookupHistory;
+    /** https://graypaper.fluffylabs.dev/#/1c979cb/3b88003b8800?v=0.7.1 */
+    function serviceNested(blake2b, serviceId, numberPrefix, hash) {
+        const inputToHash = BytesBlob.blobFromParts(u32AsLeBytes(numberPrefix), hash.raw);
+        const newHash = blake2b.hashBytes(inputToHash).raw.subarray(0, 28);
+        const key = Bytes.zero(HASH_SIZE);
+        let i = 0;
+        for (const byte of u32AsLeBytes(serviceId)) {
+            key.raw[i] = byte;
+            key.raw[i + 1] = newHash[i / 2];
+            i += 2;
+        }
+        // no need to floor, since we know it's divisible (adding +2 every iteration).
+        const middle = i / 2;
+        key.raw.set(newHash.subarray(middle), i);
+        return key.asOpaque();
+    }
+    stateKeys.serviceNested = serviceNested;
+})(stateKeys || (stateKeys = {}));
+/** https://graypaper.fluffylabs.dev/#/85129da/380101380101?v=0.6.3 */
+export function legacyServiceNested(serviceId, hash) {
+    const key = Bytes.zero(HASH_SIZE);
+    let i = 0;
+    for (const byte of u32AsLeBytes(serviceId)) {
+        key.raw[i] = byte;
+        key.raw[i + 1] = hash.raw[i / 2];
+        i += 2;
+    }
+    // no need to floor, since we know it's divisible (adding +2 every iteration).
+    const middle = i / 2;
+    key.raw.set(hash.raw.subarray(middle, HASH_SIZE - middle), i);
+    return key.asOpaque();
+}

package/packages/jam/state-merkleization/keys.test.d.ts

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

package/packages/jam/state-merkleization/keys.test.d.ts.map

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

package/packages/jam/state-merkleization/keys.test.js

@@ -0,0 +1,47 @@
+import assert from "node:assert";
+import { before, describe, it } from "node:test";
+import { tryAsServiceId } from "#@typeberry/block";
+import { Bytes } from "#@typeberry/bytes";
+import { Blake2b, HASH_SIZE } from "#@typeberry/hash";
+import { tryAsU32 } from "#@typeberry/numbers";
+import { StateKeyIdx, stateKeys } from "./keys.js";
+let blake2b;
+before(async () => {
+    blake2b = await Blake2b.createHasher();
+});
+describe("State Serialization / keys", () => {
+    it("should construct index key", () => {
+        const alpha = stateKeys.index(StateKeyIdx.Alpha);
+        const delta = stateKeys.index(StateKeyIdx.Delta);
+        const xi = stateKeys.index(StateKeyIdx.Xi);
+        assert.strictEqual(`${alpha}`, "0x0100000000000000000000000000000000000000000000000000000000000000");
+        assert.strictEqual(`${delta}`, "0xff00000000000000000000000000000000000000000000000000000000000000");
+        assert.strictEqual(`${xi}`, "0x0f00000000000000000000000000000000000000000000000000000000000000");
+    });
+    it("should construct key for service info", () => {
+        const a = stateKeys.serviceInfo(tryAsServiceId(2 ** 32 - 1));
+        const b = stateKeys.serviceInfo(tryAsServiceId(2));
+        const c = stateKeys.serviceInfo(tryAsServiceId(2 ** 16));
+        const d = stateKeys.serviceInfo(tryAsServiceId(2 ** 16 - 1));
+        assert.strictEqual(`${a}`, "0xffff00ff00ff00ff000000000000000000000000000000000000000000000000");
+        assert.strictEqual(`${b}`, "0xff02000000000000000000000000000000000000000000000000000000000000");
+        assert.strictEqual(`${c}`, "0xff00000000010000000000000000000000000000000000000000000000000000");
+        assert.strictEqual(`${d}`, "0xffff00ff00000000000000000000000000000000000000000000000000000000");
+    });
+    it("should construct a key for service state", () => {
+        const a = stateKeys.serviceStorage(blake2b, tryAsServiceId(0xbbbb_bbbb), EXAMPLE_HASH.asOpaque());
+        const expectedKey = "0xbb98bb4bbb5bbbf04624e8575cf0ddc40ad4d73ae8dcbd527b3143b76e6689f6";
+        assert.strictEqual(`${a}`, expectedKey);
+    });
+    it("should construct a key for service preimage", () => {
+        const a = stateKeys.servicePreimage(blake2b, tryAsServiceId(0xbbbb_bbbb), EXAMPLE_HASH.asOpaque());
+        const expectedKey = "0xbb9ebbb1bb8dbb02b980a74e4be74b55435d6030e74652c9cc6fe523b4c866f5";
+        assert.strictEqual(`${a}`, expectedKey);
+    });
+    it("should construct a key for service lookup history", () => {
+        const a = stateKeys.serviceLookupHistory(blake2b, tryAsServiceId(0xbbbb_bbbb), EXAMPLE_HASH.asOpaque(), tryAsU32(0xdeadbeef));
+        const expectedKey = "0xbb48bb92bbc3bb5ff7692d2e8e65b37d5df58917217dbb72b1d2c0cdf75079e9";
+        assert.strictEqual(`${a}`, expectedKey);
+    });
+});
+const EXAMPLE_HASH = Bytes.parseBytes("0x00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff", HASH_SIZE);

package/packages/jam/state-merkleization/loader.d.ts

@@ -0,0 +1,8 @@
+import type { BytesBlob } from "#@typeberry/bytes";
+import type { ChainSpec } from "#@typeberry/config";
+import type { Blake2b, TruncatedHash } from "#@typeberry/hash";
+import type { StateKey } from "./keys.js";
+import { SerializedState } from "./serialized-state.js";
+import { StateEntries } from "./state-entries.js";
+export declare function loadState(spec: ChainSpec, blake2b: Blake2b, entries: Iterable<[StateKey | TruncatedHash, BytesBlob]>): SerializedState<StateEntries>;
+//# sourceMappingURL=loader.d.ts.map

package/packages/jam/state-merkleization/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/state-merkleization/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,GAAG,aAAa,EAAE,SAAS,CAAC,CAAC,iCAGpH"}

package/packages/jam/state-merkleization/loader.js

@@ -0,0 +1,6 @@
+import { SerializedState } from "./serialized-state.js";
+import { StateEntries } from "./state-entries.js";
+export function loadState(spec, blake2b, entries) {
+    const stateEntries = StateEntries.fromEntriesUnsafe(entries);
+    return SerializedState.fromStateEntries(spec, blake2b, stateEntries);
+}

package/packages/jam/state-merkleization/serialize-state-update.d.ts

@@ -0,0 +1,16 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import type { ChainSpec } from "#@typeberry/config";
+import type { Blake2b } from "#@typeberry/hash";
+import { type ServicesUpdate, type State } from "#@typeberry/state";
+import type { StateKey } from "./keys.js";
+/** What should be done with that key? */
+export declare enum StateEntryUpdateAction {
+    /** Insert an entry. */
+    Insert = 0,
+    /** Remove an entry. */
+    Remove = 1
+}
+export type StateEntryUpdate = [StateEntryUpdateAction, StateKey, BytesBlob];
+/** Serialize given state update into a series of key-value pairs. */
+export declare function serializeStateUpdate(spec: ChainSpec, blake2b: Blake2b, update: Partial<State & ServicesUpdate>): Generator<StateEntryUpdate>;
+//# sourceMappingURL=serialize-state-update.d.ts.map

package/packages/jam/state-merkleization/serialize-state-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-state-update.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/state-merkleization/serialize-state-update.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,KAAK,EAQX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,yCAAyC;AACzC,oBAAY,sBAAsB;IAChC,uBAAuB;IACvB,MAAM,IAAI;IACV,uBAAuB;IACvB,MAAM,IAAI;CACX;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,sBAAsB,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAI7E,qEAAqE;AACrE,wBAAiB,oBAAoB,CACnC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,cAAc,CAAC,GACtC,SAAS,CAAC,gBAAgB,CAAC,CAW7B"}