@typeberry/lib 0.8.4 → 0.9.0-3f2c45b

package/packages/workers/block-authorship/epoch-authoring-slots.js

@@ -0,0 +1,86 @@
+import { BytesBlob } from "#@typeberry/bytes";
+import { HashDictionary } from "#@typeberry/collections";
+import { deriveBandersnatchPublicKey, deriveEd25519PublicKey } from "#@typeberry/crypto/key-derivation.js";
+import bandersnatchVrf from "#@typeberry/safrole/bandersnatch-vrf.js";
+import { JAM_FALLBACK_SEAL, JAM_TICKET_SEAL } from "#@typeberry/safrole/constants.js";
+import { SafroleSealingKeysKind } from "#@typeberry/state";
+import { asOpaqueType } from "#@typeberry/utils";
+/** A helper class to figure out in which slots in the next epoch we are authoring blocks. */
+export class EpochAuthoringSlots {
+    ticketsPerValidator;
+    bandersnatch;
+    keys;
+    static async new(chainSpec, bandersnatch, ownedSecrets) {
+        const keys = await derivePublicKeys(ownedSecrets);
+        const keysDictionary = new HashDictionary();
+        for (const key of keys) {
+            keysDictionary.set(key.bandersnatchPublic, key);
+        }
+        return new EpochAuthoringSlots(chainSpec.ticketsPerValidator, bandersnatch, keysDictionary);
+    }
+    constructor(ticketsPerValidator, bandersnatch, keys) {
+        this.ticketsPerValidator = ticketsPerValidator;
+        this.bandersnatch = bandersnatch;
+        this.keys = keys;
+    }
+    getValidatorKeys() {
+        return Array.from(this.keys.values());
+    }
+    getBandersnatchPublicKeys() {
+        return Array.from(this.keys.keys());
+    }
+    async getOurSlotsInKeySeries(sealingKeySeries, entropy) {
+        // Fallback (keys) mode. Just find keys that match ours.
+        if (sealingKeySeries.kind === SafroleSealingKeysKind.Keys) {
+            const sealPayload = getFallbackSealPayload(entropy);
+            return sealingKeySeries.keys.map((author) => {
+                const key = this.keys.get(author);
+                if (key === undefined) {
+                    return null;
+                }
+                return {
+                    key,
+                    sealPayload,
+                    logId: `key ${key.bandersnatchPublic.toStringTruncated()}`,
+                };
+            });
+        }
+        // Tickets mode. Generate own VrfOutputHash for our tickets (cheap) and check if it matches.
+        const ownTickets = await this.getOwnTicketIds(entropy);
+        const slots = sealingKeySeries.tickets.map((ticket) => ownTickets.get(ticket.id.asOpaque()) ?? null);
+        return slots;
+    }
+    async getOwnTicketIds(entropy) {
+        // generate our own tickets first
+        const ownTickets = new HashDictionary();
+        for (let attempt = 0; attempt < this.ticketsPerValidator; attempt++) {
+            const sealPayload = getTicketSealPayload(entropy, attempt);
+            for (const key of this.keys.values()) {
+                const result = await bandersnatchVrf.getVrfOutputHash(this.bandersnatch, key.bandersnatchSecret, sealPayload);
+                if (result.isOk) {
+                    const ticketId = result.ok.asOpaque();
+                    ownTickets.set(ticketId, {
+                        key,
+                        sealPayload,
+                        logId: `ticket ${ticketId} (attempt ${attempt})`,
+                    });
+                }
+            }
+        }
+        return ownTickets;
+    }
+}
+function derivePublicKeys(keys) {
+    return Promise.all(keys.map(async (secrets) => ({
+        bandersnatchSecret: secrets.bandersnatch,
+        bandersnatchPublic: deriveBandersnatchPublicKey(secrets.bandersnatch),
+        ed25519Secret: secrets.ed25519,
+        ed25519Public: await deriveEd25519PublicKey(secrets.ed25519),
+    })));
+}
+function getTicketSealPayload(entropy, attempt) {
+    return asOpaqueType(BytesBlob.blobFromParts(JAM_TICKET_SEAL, entropy.raw, new Uint8Array([attempt])));
+}
+function getFallbackSealPayload(entropy) {
+    return asOpaqueType(BytesBlob.blobFromParts(JAM_FALLBACK_SEAL, entropy.raw));
+}

package/packages/workers/block-authorship/epoch-tracker.d.ts

@@ -0,0 +1,29 @@
+import { type EntropyHash, type Epoch, type TimeSlot } from "#@typeberry/block";
+import type { ChainSpec } from "#@typeberry/config";
+import type { Blake2b } from "#@typeberry/hash";
+import type { Logger } from "#@typeberry/logger";
+import type { BandernsatchWasm } from "#@typeberry/safrole/bandersnatch-wasm.js";
+import { type SafroleSealingKeys, type State } from "#@typeberry/state";
+import { Result } from "#@typeberry/utils";
+import { EpochAuthoringSlots, type SlotSealData } from "./epoch-authoring-slots.js";
+import type { ValidatorSecrets } from "./protocol.js";
+/** Per-epoch data computed once when entering (or resuming into) an epoch. */
+export type EpochData = {
+    epoch: Epoch;
+    epochLength: number;
+    sealingKeySeries: SafroleSealingKeys;
+    entropy: EntropyHash;
+    slots: Array<SlotSealData | null>;
+};
+export declare class EpochTracker {
+    private readonly chainSpec;
+    private readonly blake2bHasher;
+    readonly authoring: EpochAuthoringSlots;
+    static new(chainSpec: ChainSpec, bandersnatch: BandernsatchWasm, blake2bHasher: Blake2b, keys: readonly ValidatorSecrets[]): Promise<EpochTracker>;
+    private constructor();
+    isEpochChanged(stateTimeSlot: TimeSlot, newTimeSlot: TimeSlot): boolean;
+    getEpochData(logger: Logger, state: State, newTimeSlot: TimeSlot): Promise<Result<EpochData, string>>;
+    private getSealingKeySeries;
+    private logEpochAuthorshipInfo;
+}
+//# sourceMappingURL=epoch-tracker.d.ts.map

package/packages/workers/block-authorship/epoch-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch-tracker.d.ts","sourceRoot":"","sources":["../../../../../packages/workers/block-authorship/epoch-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAc,MAAM,kBAAkB,CAAC;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChF,OAAO,EAAE,KAAK,kBAAkB,EAA0B,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,kBAAkB,CAAC;IACrC,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACnC,CAAC;AAEF,qBAAa,YAAY;IAYrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;aACd,SAAS,EAAE,mBAAmB;WAbnC,GAAG,CACd,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,gBAAgB,EAC9B,aAAa,EAAE,OAAO,EACtB,IAAI,EAAE,SAAS,gBAAgB,EAAE;IAMnC,OAAO;IAMP,cAAc,CAAC,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO;IAOjE,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YA+B7F,mBAAmB;IAejC,OAAO,CAAC,sBAAsB;CAe/B"}

package/packages/workers/block-authorship/epoch-tracker.js

@@ -0,0 +1,80 @@
+import { tryAsEpoch } from "#@typeberry/block";
+import { Safrole } from "#@typeberry/safrole";
+import { SafroleSealingKeysKind } from "#@typeberry/state";
+import { Result } from "#@typeberry/utils";
+import { EpochAuthoringSlots } from "./epoch-authoring-slots.js";
+export class EpochTracker {
+    chainSpec;
+    blake2bHasher;
+    authoring;
+    static async new(chainSpec, bandersnatch, blake2bHasher, keys) {
+        const epochSlots = await EpochAuthoringSlots.new(chainSpec, bandersnatch, keys);
+        return new EpochTracker(chainSpec, blake2bHasher, epochSlots);
+    }
+    constructor(chainSpec, blake2bHasher, authoring) {
+        this.chainSpec = chainSpec;
+        this.blake2bHasher = blake2bHasher;
+        this.authoring = authoring;
+    }
+    isEpochChanged(stateTimeSlot, newTimeSlot) {
+        const epochLength = this.chainSpec.epochLength;
+        const stateEpoch = Math.floor(stateTimeSlot / epochLength);
+        const newEpoch = Math.floor(newTimeSlot / epochLength);
+        return newEpoch > stateEpoch;
+    }
+    async getEpochData(logger, state, newTimeSlot) {
+        const sealingKeySeriesResult = await this.getSealingKeySeries(state, newTimeSlot);
+        // Propagate the typed failure instead of crashing — `main` decides whether to
+        // retry, skip or terminate, and keeps the real error details.
+        if (sealingKeySeriesResult.isError) {
+            return Result.error(`${sealingKeySeriesResult.error}`, sealingKeySeriesResult.details);
+        }
+        const epochLength = this.chainSpec.epochLength;
+        const sealingKeySeries = sealingKeySeriesResult.ok;
+        // On a new epoch, `state.entropy[2]` is the epoch-E entropy (pre-transition);
+        // mid-epoch, it has already shifted to `entropy[3]`. Use the same predicate
+        // as `getSealingKeySeries` so the entropy and the key series stay consistent
+        // even when the first authored block of an epoch isn't exactly at slot E·L.
+        const isNewEpoch = this.isEpochChanged(state.timeslot, newTimeSlot);
+        const entropy = isNewEpoch ? state.entropy[2] : state.entropy[3];
+        const epoch = tryAsEpoch(Math.floor(newTimeSlot / epochLength));
+        logger.log `[E${epoch}] is using ${SafroleSealingKeysKind[sealingKeySeries.kind]}`;
+        logger.trace `[E${epoch}] ${sealingKeySeries}`;
+        const slots = await this.authoring.getOurSlotsInKeySeries(sealingKeySeries, entropy);
+        this.logEpochAuthorshipInfo(logger, epoch, slots);
+        return Result.ok({
+            epoch,
+            epochLength,
+            sealingKeySeries,
+            entropy,
+            slots,
+        });
+    }
+    async getSealingKeySeries(state, newTimeSlot) {
+        // in case we are not changing epoch, just use the state data
+        if (!this.isEpochChanged(state.timeslot, newTimeSlot)) {
+            return Result.ok(state.sealingKeySeries);
+        }
+        // otherwise, pick the new sealing key series already
+        const safrole = new Safrole(this.chainSpec, this.blake2bHasher, state);
+        return await safrole.getSealingKeySeries({
+            entropy: state.entropy[1],
+            slot: newTimeSlot,
+            punishSet: state.disputesRecords.punishSet,
+        });
+    }
+    logEpochAuthorshipInfo(logger, epoch, slots) {
+        let isCreating = false;
+        let slot = epoch * this.chainSpec.epochLength;
+        for (const sealData of slots) {
+            if (sealData !== null) {
+                isCreating = true;
+                logger.info `[E${epoch}#${slot}] Validator ${sealData.key.bandersnatchPublic.toStringTruncated()} will author using ${sealData.logId}`;
+            }
+            slot += 1;
+        }
+        if (isCreating === false) {
+            logger.info `[E${epoch}] No blocks to author for this epoch.`;
+        }
+    }
+}

package/packages/workers/block-authorship/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/workers/block-authorship/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,eAAO,MAAM,MAAM,mBAAwD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/workers/block-authorship/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,eAAO,MAAM,MAAM,mBAAyD,CAAC"}

package/packages/workers/block-authorship/index.js

@@ -1,4 +1,4 @@
 export * from "./main.js";
 export * from "./metrics.js";
 export * from "./protocol.js";
-export const WORKER = new URL("./bootstrap-generator.mjs", import.meta.url);
+export const WORKER = new URL("./bootstrap-authorship.mjs", import.meta.url);

package/packages/workers/block-authorship/main.d.ts

@@ -2,6 +2,9 @@ import type { NetworkingComms } from "#@typeberry/comms-authorship-network";
 import type { WorkerConfig } from "#@typeberry/workers-api";
 import type { BlockAuthorshipConfig, GeneratorInternal } from "./protocol.js";
 type Config = WorkerConfig<BlockAuthorshipConfig>;
+/**
+ * The `BlockAuthorship` should create new blocks and send them as signals to the main thread.
+ */
 export declare function main(config: Config, comms: GeneratorInternal, networkingComms: NetworkingComms): Promise<void>;
 export {};
 //# sourceMappingURL=main.d.ts.map

package/packages/workers/block-authorship/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../packages/workers/block-authorship/main.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAiB3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAK9E,KAAK,MAAM,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAC;AAwBlD,wBAAsB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,iBAiapG"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../packages/workers/block-authorship/main.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAS3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAM9E,KAAK,MAAM,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAC;AAElD;;GAEG;AAEH,wBAAsB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,iBAkKpG"}