@typeberry/lib 0.8.4-7a69737 → 0.8.4-7d1719f

package/packages/jam/jamnp-s/tasks/ticket-distribution.js

@@ -1,4 +1,5 @@
 import { Logger } from "#@typeberry/logger";
+import { DenyTicketsValidator, PendingTicketPool } from "#@typeberry/ticket-pool";
 import { OK } from "#@typeberry/utils";
 import { ce131 } from "../protocol/index.js";
 const logger = Logger.new(import.meta.filename, "net:tickets");
@@ -12,6 +13,11 @@ const TICKET_AUX = {
  * Uses CE-132 (proxy-to-all) for direct broadcast to all peers.
  * Implements a maintain pattern similar to SyncTask: tickets are collected
  * and periodically distributed to peers that haven't received them yet.
+ *
+ * Incoming tickets from peers are first run through a {@link TicketValidator};
+ * only validated tickets are added to the redistribution pool. The default
+ * validator denies everything, so callers must wire a real one via
+ * {@link setTicketValidator} before any networked ticket can be redistributed.
  */
 export class TicketDistributionTask {
     streamManager;
@@ -26,10 +32,8 @@ export class TicketDistributionTask {
         streamManager.registerOutgoingHandlers(ce131.ClientHandler.new(chainSpec, ce131.STREAM_KIND_PROXY_TO_ALL));
         return task;
     }
-    /** Pending tickets waiting to be distributed to peers */
-    pendingTickets = [];
-    /** Current epoch being tracked (cleared when epoch changes) */
-    currentEpoch = null;
+    pool = new PendingTicketPool();
+    validator = new DenyTicketsValidator();
     constructor(streamManager, connections) {
         this.streamManager = streamManager;
         this.connections = connections;
@@ -38,14 +42,13 @@ export class TicketDistributionTask {
      * Should be called periodically to distribute pending tickets to connected peers.
      */
     maintainDistribution() {
-        if (this.currentEpoch === null) {
-            return; // No tickets to distribute yet
+        const currentEpoch = this.pool.currentEpoch;
+        if (currentEpoch === null) {
+            return;
         }
-        /** `this` is mutable and TS can't narrow this.currentEpoch inside the callback closure */
-        const currentEpoch = this.currentEpoch;
-        // Iterate through all pending tickets
-        for (let ticketIdx = 0; ticketIdx < this.pendingTickets.length; ticketIdx++) {
-            const { epochIndex, ticket } = this.pendingTickets[ticketIdx];
+        const tickets = this.pool.getTickets();
+        for (let ticketIdx = 0; ticketIdx < tickets.length; ticketIdx++) {
+            const { epochIndex, ticket } = tickets[ticketIdx];
             // Try to send to each connected peer
             for (const peerInfo of this.connections.getConnectedPeers()) {
                 this.connections.withAuxData(peerInfo.peerId, TICKET_AUX, (maybeAux) => {
@@ -77,72 +80,45 @@ export class TicketDistributionTask {
         }
     }
     /**
-     * Add a ticket to the pending queue for distribution.
+     * Add a ticket to the redistribution pool.
      * Clears pending tickets when epoch changes.
      * Deduplicates tickets based on signature.
      */
     addTicket(epochIndex, ticket) {
-        // Drop tickets for older epochs (can happen when a delayed validation callback completes
-        // after the epoch has already advanced — accepting it would roll back currentEpoch).
-        if (this.currentEpoch !== null && epochIndex < this.currentEpoch) {
-            return;
-        }
-        // Epoch advanced — clear old tickets
-        if (this.currentEpoch !== null && epochIndex > this.currentEpoch) {
-            logger.log `[addTicket] Epoch changed from ${this.currentEpoch} to ${epochIndex}, clearing ${this.pendingTickets.length} old tickets`;
-            this.pendingTickets = [];
-            // Note: We don't need to clear aux data for all peers here.
-            // The aux data contains the epoch, so maintainDistribution will lazily
-            // reset it when it detects an epoch mismatch. This handles both connected
-            // and disconnected peers correctly.
-        }
-        this.currentEpoch = epochIndex;
-        /**
-         * Deduplicate: check if a ticket with the same signature already exists
-         *
-         * Here we are risking "poisoning" the local pendingTickets - i.e:
-         *  1. The adversary sees a signature and swaps the ticket attempt to something different.
-         *  2. This creates an invalid ticket, but prevents a valid ticket with the same signature from being included and distributed.
-         *
-         * TODO [MaSi]: The poisoning risk should be fixed during implementation of ticket validation.
-         */
-        const isDuplicate = this.pendingTickets.some((pending) => pending.epochIndex === epochIndex && pending.ticket.signature.isEqualTo(ticket.signature));
-        if (!isDuplicate) {
-            this.pendingTickets.push({ epochIndex, ticket });
-            logger.info `[addTicket] Added ticket for epoch ${epochIndex}, total: ${this.pendingTickets.length}`;
-        }
+        this.pool.addTicket(epochIndex, ticket);
     }
-    onTicketReceivedCallback = null;
     /**
-     * Register a callback that validates a received ticket.
-     * The ticket is only added to the redistribution pool if the callback returns `true`.
-     * This prevents redistribution of invalid tickets (e.g. those with a tampered `attempt` field).
+     * Replace the redistribution pool for the given epoch with the supplied tickets.
+     * Used when the authorship worker dumps the authoritative pool on an epoch boundary.
      */
-    setOnTicketReceived(cb) {
-        this.onTicketReceivedCallback = cb;
+    replacePool(epochIndex, tickets) {
+        this.pool.replace(epochIndex, tickets);
+    }
+    /**
+     * Register the validator that decides whether tickets received from peers should be
+     * accepted (and therefore redistributed). The default is {@link DenyTicketsValidator},
+     * so the caller must install a real validator for any peer ticket to make it through.
+     */
+    setTicketValidator(validator) {
+        this.validator = validator;
     }
     onTicketReceived(epochIndex, ticket) {
         logger.trace `Received ticket for epoch ${epochIndex}, attempt ${ticket.attempt}`;
-        if (this.onTicketReceivedCallback !== null) {
-            // Validate first; only redistribute if valid to avoid spreading tampered tickets.
-            // Wrap with Promise.resolve().then() to catch both sync throws and async rejections.
-            const cb = this.onTicketReceivedCallback;
-            Promise.resolve()
-                .then(() => cb(epochIndex, ticket))
-                .then((isValid) => {
-                if (isValid) {
-                    this.addTicket(epochIndex, ticket);
-                }
-                else {
-                    logger.warn `Dropping invalid ticket for epoch ${epochIndex} (validation failed)`;
-                }
-            })
-                .catch((error) => {
-                logger.error `Error validating ticket for epoch ${epochIndex}, attempt ${ticket.attempt}: ${error}`;
-            });
-        }
-        else {
-            this.addTicket(epochIndex, ticket);
-        }
+        const validator = this.validator;
+        // Wrap with Promise.resolve().then() so a synchronous throw inside the validator
+        // funnels into the same .catch() as an async rejection.
+        Promise.resolve()
+            .then(() => validator.validate(epochIndex, ticket))
+            .then((result) => {
+            if (result.isOk) {
+                this.addTicket(epochIndex, ticket);
+            }
+            else {
+                logger.trace `Dropping ticket for epoch ${epochIndex}: ${result.error}`;
+            }
+        })
+            .catch((error) => {
+            logger.error `Error validating ticket for epoch ${epochIndex}, attempt ${ticket.attempt}: ${error}`;
+        });
     }
 }

package/packages/jam/jamnp-s/tasks/ticket-distribution.test.js

@@ -8,7 +8,8 @@ import { tinyChainSpec } from "#@typeberry/config";
 import { BANDERSNATCH_PROOF_BYTES } from "#@typeberry/crypto";
 import { Logger } from "#@typeberry/logger";
 import { createTestPeerPair, MockNetwork } from "#@typeberry/networking/testing.js";
-import { OK } from "#@typeberry/utils";
+import { AcceptTicketsValidator, ValidationError } from "#@typeberry/ticket-pool";
+import { OK, Result } from "#@typeberry/utils";
 import { Connections } from "../peers.js";
 import { StreamManager } from "../stream-manager.js";
 import { TicketDistributionTask } from "./ticket-distribution.js";
@@ -34,6 +35,9 @@ describe("TicketDistributionTask", () => {
         const receivedTickets = [];
         // Use real TicketDistributionTask
         const ticketTask = TicketDistributionTask.start(streamManager, connections, tinyChainSpec);
+        // Default validator accepts every ticket so the test asserts purely on distribution
+        // behaviour. Tests that exercise the rejection path overwrite this.
+        ticketTask.setTicketValidator(new AcceptTicketsValidator());
         // Intercept received tickets by wrapping onTicketReceived behavior
         // The task already adds received tickets to pending queue via addTicket,
         // so we can track them by checking the pending queue growth or by
@@ -217,7 +221,7 @@ describe("TicketDistributionTask", () => {
         assert.strictEqual(peer2.receivedTickets.length, 1);
         assert.deepStrictEqual(peer2.receivedTickets[0].ticket, ticket);
     });
-    it("should NOT redistribute ticket if validation callback returns false", async () => {
+    it("should NOT redistribute ticket if validator rejects", async () => {
         const self = await init("self");
         const peer1 = await init("peer1");
         const peer2 = await init("peer2");
@@ -225,35 +229,53 @@ describe("TicketDistributionTask", () => {
         self.openConnection(peer2);
         await tick();
         // Validation always rejects
-        self.ticketTask.setOnTicketReceived(async () => false);
+        self.ticketTask.setTicketValidator({
+            validate: async () => Result.error(ValidationError.InvalidProof, () => "rejected"),
+        });
         const ticket = createTestTicket(0);
         peer1.ticketTask.addTicket(TEST_EPOCH, ticket);
         peer1.ticketTask.maintainDistribution();
         await tick();
-        // self.addTicket was NOT called (callback returned false), so nothing to redistribute
+        // self.addTicket was NOT called (validator rejected), so nothing to redistribute
         assert.strictEqual(self.receivedTickets.length, 0);
         self.ticketTask.maintainDistribution();
         await tick();
         assert.strictEqual(peer2.receivedTickets.length, 0);
     });
-    it("should redistribute ticket if validation callback returns true", async () => {
+    it("should redistribute ticket if validator accepts", async () => {
         const self = await init("self");
         const peer1 = await init("peer1");
         const peer2 = await init("peer2");
         self.openConnection(peer1);
         self.openConnection(peer2);
         await tick();
-        // Validation always accepts
-        self.ticketTask.setOnTicketReceived(async () => true);
+        // Default init() already wires an AcceptTicketsValidator
         const ticket = createTestTicket(0);
         peer1.ticketTask.addTicket(TEST_EPOCH, ticket);
         peer1.ticketTask.maintainDistribution();
         await tick();
-        // self.addTicket WAS called (callback returned true)
+        // self.addTicket WAS called
         assert.strictEqual(self.receivedTickets.length, 1);
         self.ticketTask.maintainDistribution();
         await tick();
         assert.strictEqual(peer2.receivedTickets.length, 1);
         assert.deepStrictEqual(peer2.receivedTickets[0].ticket, ticket);
     });
+    it("replacePool overwrites the redistribution pool", async () => {
+        const self = await init("self");
+        const peer1 = await init("peer1");
+        self.openConnection(peer1);
+        await tick();
+        // Locally added tickets first
+        self.ticketTask.addTicket(TEST_EPOCH, createTestTicket(0));
+        self.ticketTask.addTicket(TEST_EPOCH, createTestTicket(1));
+        // Pool dump replaces with a different set
+        const dump = [createTestTicket(2), createTestTicket(3)];
+        self.ticketTask.replacePool(TEST_EPOCH, dump);
+        self.ticketTask.maintainDistribution();
+        await tick();
+        assert.strictEqual(peer1.receivedTickets.length, 2);
+        assert.deepStrictEqual(peer1.receivedTickets[0].ticket, dump[0]);
+        assert.deepStrictEqual(peer1.receivedTickets[1].ticket, dump[1]);
+    });
 });

package/packages/jam/node/main-fuzz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main-fuzz.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/node/main-fuzz.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAOrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,aAAa,EAAE,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uBAAuB,EAAE,OAAO,CAAC;CAClC,CAAC;AAOF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASpF;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAED,wBAAgB,cAAc;;;;EAM7B;AAED,wBAAsB,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,uBA2GxF"}
+{"version":3,"file":"main-fuzz.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/node/main-fuzz.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAOrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,aAAa,EAAE,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uBAAuB,EAAE,OAAO,CAAC;CAClC,CAAC;AAWF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASpF;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAED,wBAAgB,cAAc;;;;EAM7B;AAED,wBAAsB,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,uBAqHxF"}

package/packages/jam/node/main-fuzz.js

@@ -14,6 +14,9 @@ import { mainImporter } from "./main-importer.js";
 const logger = Logger.new(import.meta.filename, "fuzztarget");
 /** Dedicated subdirectory under the configured base path that the fuzzer owns and wipes. */
 const FUZZ_DB_SUBDIR = "typeberry-fuzz-db";
+const FUZZ_DB_FJALL = "fjall-hybrid";
+const FUZZ_DB_LMDB = "lmdb-hybrid";
+const FUZZ_DB_OPTIONS = [FUZZ_DB_FJALL, FUZZ_DB_LMDB];
 /**
  * Resolve the directory the fuzzer should use for its on-disk database, or
  * `undefined` for an in-memory database. The dedicated `FUZZ_DB_SUBDIR` is
@@ -50,6 +53,15 @@ export async function mainFuzz(fuzzConfig, withRelPath) {
     logHostEnvironment(logger);
     const { jamNodeConfig: config } = fuzzConfig;
     const fuzzDbBase = resolveFuzzDbBase(config.node.databaseBasePath);
+    const rawFuzzDb = process.env.JAM_FUZZ_DB?.trim() ?? "";
+    // Using experimental fjall-hybrid by default, with an option to test lmdb as well.
+    const hybridStateBackend = rawFuzzDb === "" ? FUZZ_DB_FJALL : rawFuzzDb;
+    if (!isValidStateBackend(hybridStateBackend)) {
+        throw new Error(`JAM_FUZZ_DB must be one of: ${FUZZ_DB_OPTIONS} (got: "${rawFuzzDb}").`);
+    }
+    if (fuzzDbBase !== undefined) {
+        logger.info `🗄️ Fuzz persistent backend: ${hybridStateBackend}.`;
+    }
     let runningNode = null;
     const chainSpec = getChainSpec(config.node.flavor);
     const closeFuzzTarget = startFuzzTarget(fuzzConfig.version, fuzzConfig.socket, {
@@ -106,7 +118,7 @@ export async function mainFuzz(fuzzConfig, withRelPath) {
                     // spec only, where values are big) bounds its on-disk/page-cache size.
                     // Tiny stays uncompressed since its db is small and speed matters more.
                     ephemeral: isPersistent,
-                    stateBackend: isPersistent ? "hybrid" : "lmdb",
+                    stateBackend: isPersistent ? hybridStateBackend : "lmdb",
                 });
             };
             if (fuzzDbBase !== undefined) {
@@ -136,3 +148,6 @@ export async function mainFuzz(fuzzConfig, withRelPath) {
         }
     };
 }
+function isValidStateBackend(val) {
+    return FUZZ_DB_OPTIONS.indexOf(val) !== -1;
+}

package/packages/jam/node/main-importer.d.ts

@@ -1,13 +1,16 @@
 import type { JamConfig } from "./jam-config.js";
 import type { NodeApi } from "./main.js";
+export type StateBackend = "lmdb" | "lmdb-hybrid" | "fjall-hybrid";
 export type ImporterOptions = {
     initGenesisFromAncestry?: boolean;
     dummyFinalityDepth?: number;
     pruneBlocks?: boolean;
-    /** Open the LMDB database without fsync/compression. Only safe for throwaway dbs (e.g. fuzzing). */
+    /** Open the database without fsync/compression. Only safe for throwaway dbs (e.g. fuzzing). */
     ephemeral?: boolean;
-    /** Persistent backend to use when `databaseBasePath` is set. Defaults to full LMDB. */
-    stateBackend?: "lmdb" | "hybrid";
+    /**
+     * Persistent backend to use when `databaseBasePath` is set. Defaults to full LMDB.
+     */
+    stateBackend?: StateBackend;
 };
 export declare function mainImporter(config: JamConfig, withRelPath: (v: string) => string, options?: ImporterOptions): Promise<NodeApi>;
 //# sourceMappingURL=main-importer.d.ts.map

package/packages/jam/node/main-importer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main-importer.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/node/main-importer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,MAAM,MAAM,eAAe,GAAG;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oGAAoG;IACpG,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAClC,CAAC;AAEF,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAClC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAoGlB"}
+{"version":3,"file":"main-importer.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/node/main-importer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,aAAa,GAAG,cAAc,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,+FAA+F;IAC/F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;OAEG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAClC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAqGlB"}

package/packages/jam/node/main-importer.js

@@ -39,8 +39,8 @@ export async function mainImporter(config, withRelPath, options = {}) {
             blake2b,
             workerParams,
         })
-        : dbBackend === "hybrid"
-            ? HybridWorkerConfig.new({
+        : dbBackend === "lmdb-hybrid" || dbBackend === "fjall-hybrid"
+            ? await HybridWorkerConfig.new({
                 nodeName,
                 chainSpec,
                 blake2b,
@@ -48,6 +48,7 @@ export async function mainImporter(config, withRelPath, options = {}) {
                 workerParams,
                 ephemeral,
                 compression,
+                backend: dbBackend === "lmdb-hybrid" ? "lmdb" : "fjall",
             })
             : LmdbWorkerConfig.new({
                 nodeName,

package/packages/jam/ticket-pool/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./pending-ticket-pool.js";
+export * from "./ticket-validator.js";
+export * from "./verified-ticket-pool.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/jam/ticket-pool/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/ticket-pool/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC"}

package/packages/jam/ticket-pool/index.js

@@ -0,0 +1,3 @@
+export * from "./pending-ticket-pool.js";
+export * from "./ticket-validator.js";
+export * from "./verified-ticket-pool.js";

package/packages/jam/ticket-pool/pending-ticket-pool.d.ts

@@ -0,0 +1,30 @@
+import type { Epoch } from "#@typeberry/block";
+import type { SignedTicket } from "#@typeberry/block/tickets.js";
+/**
+ * An ordered, signature-deduplicated pool of tickets waiting to be redistributed to peers.
+ *
+ * Used on the networking side. Indices are stable within an epoch so callers can track
+ * per-peer "sent" sets by index. The pool is cleared whenever a new epoch is observed,
+ * and tickets for older epochs are dropped (can happen when an async validation completes
+ * after the epoch already advanced).
+ */
+export declare class PendingTicketPool {
+    private tickets;
+    private currentEpochValue;
+    /** Epoch the pool is currently holding tickets for, or `null` if empty. */
+    get currentEpoch(): Epoch | null;
+    /** Returns the ordered tickets currently in the pool. Caller must not mutate the array. */
+    getTickets(): readonly {
+        epochIndex: Epoch;
+        ticket: SignedTicket;
+    }[];
+    /** Returns true if the ticket was added, false if it was a duplicate or dropped (old epoch). */
+    addTicket(epochIndex: Epoch, ticket: SignedTicket): boolean;
+    /**
+     * Replace the pool contents for the given epoch with the supplied tickets. Used when the
+     * authorship worker pushes an authoritative pool dump on an epoch boundary; any tickets
+     * that aren't in the dump are dropped, and dedup runs over the new set.
+     */
+    replace(epochIndex: Epoch, tickets: readonly SignedTicket[]): void;
+}
+//# sourceMappingURL=pending-ticket-pool.d.ts.map

package/packages/jam/ticket-pool/pending-ticket-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-ticket-pool.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/ticket-pool/pending-ticket-pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAKhE;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAA0D;IACzE,OAAO,CAAC,iBAAiB,CAAsB;IAE/C,2EAA2E;IAC3E,IAAI,YAAY,IAAI,KAAK,GAAG,IAAI,CAE/B;IAED,2FAA2F;IAC3F,UAAU,IAAI,SAAS;QAAE,UAAU,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE;IAIpE,gGAAgG;IAChG,SAAS,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO;IAyB3D;;;;OAIG;IACH,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI;CAWnE"}

package/packages/jam/ticket-pool/pending-ticket-pool.js

@@ -0,0 +1,56 @@
+import { Logger } from "#@typeberry/logger";
+const logger = Logger.new(import.meta.filename, "pending-pool");
+/**
+ * An ordered, signature-deduplicated pool of tickets waiting to be redistributed to peers.
+ *
+ * Used on the networking side. Indices are stable within an epoch so callers can track
+ * per-peer "sent" sets by index. The pool is cleared whenever a new epoch is observed,
+ * and tickets for older epochs are dropped (can happen when an async validation completes
+ * after the epoch already advanced).
+ */
+export class PendingTicketPool {
+    tickets = [];
+    currentEpochValue = null;
+    /** Epoch the pool is currently holding tickets for, or `null` if empty. */
+    get currentEpoch() {
+        return this.currentEpochValue;
+    }
+    /** Returns the ordered tickets currently in the pool. Caller must not mutate the array. */
+    getTickets() {
+        return this.tickets;
+    }
+    /** Returns true if the ticket was added, false if it was a duplicate or dropped (old epoch). */
+    addTicket(epochIndex, ticket) {
+        if (this.currentEpochValue !== null && epochIndex < this.currentEpochValue) {
+            return false;
+        }
+        if (this.currentEpochValue !== null && epochIndex > this.currentEpochValue) {
+            logger.log `Epoch changed from ${this.currentEpochValue} to ${epochIndex}, clearing ${this.tickets.length} old tickets`;
+            this.tickets = [];
+        }
+        this.currentEpochValue = epochIndex;
+        const isDuplicate = this.tickets.some((pending) => pending.epochIndex === epochIndex && pending.ticket.signature.isEqualTo(ticket.signature));
+        if (isDuplicate) {
+            return false;
+        }
+        this.tickets.push({ epochIndex, ticket });
+        logger.info `[addTicket] Added ticket for epoch ${epochIndex}, total: ${this.tickets.length}`;
+        return true;
+    }
+    /**
+     * Replace the pool contents for the given epoch with the supplied tickets. Used when the
+     * authorship worker pushes an authoritative pool dump on an epoch boundary; any tickets
+     * that aren't in the dump are dropped, and dedup runs over the new set.
+     */
+    replace(epochIndex, tickets) {
+        this.tickets = [];
+        this.currentEpochValue = epochIndex;
+        for (const ticket of tickets) {
+            const isDuplicate = this.tickets.some((pending) => pending.ticket.signature.isEqualTo(ticket.signature));
+            if (!isDuplicate) {
+                this.tickets.push({ epochIndex, ticket });
+            }
+        }
+        logger.log `Pool replaced for epoch ${epochIndex} with ${this.tickets.length} tickets`;
+    }
+}

package/packages/jam/ticket-pool/pending-ticket-pool.test.d.ts

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

package/packages/jam/ticket-pool/pending-ticket-pool.test.d.ts.map

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

package/packages/jam/ticket-pool/pending-ticket-pool.test.js

@@ -0,0 +1,67 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { tryAsEpoch } from "#@typeberry/block";
+import { SignedTicket, tryAsTicketAttempt } from "#@typeberry/block/tickets.js";
+import { Bytes } from "#@typeberry/bytes";
+import { BANDERSNATCH_PROOF_BYTES } from "#@typeberry/crypto";
+import { PendingTicketPool } from "./pending-ticket-pool.js";
+const E1 = tryAsEpoch(1);
+const E2 = tryAsEpoch(2);
+function makeTicket(seed, attempt = 0) {
+    const sig = Bytes.zero(BANDERSNATCH_PROOF_BYTES);
+    sig.raw[0] = seed;
+    return SignedTicket.create({
+        attempt: tryAsTicketAttempt(attempt),
+        signature: sig.asOpaque(),
+    });
+}
+describe("PendingTicketPool", () => {
+    it("starts empty with no current epoch", () => {
+        const pool = new PendingTicketPool();
+        assert.strictEqual(pool.currentEpoch, null);
+        assert.deepStrictEqual(pool.getTickets(), []);
+    });
+    it("adds a ticket and tracks the epoch", () => {
+        const pool = new PendingTicketPool();
+        const t = makeTicket(1);
+        assert.strictEqual(pool.addTicket(E1, t), true);
+        assert.strictEqual(pool.currentEpoch, E1);
+        assert.strictEqual(pool.getTickets().length, 1);
+    });
+    it("dedups by signature within an epoch", () => {
+        const pool = new PendingTicketPool();
+        const t = makeTicket(1);
+        pool.addTicket(E1, t);
+        assert.strictEqual(pool.addTicket(E1, t), false);
+        assert.strictEqual(pool.getTickets().length, 1);
+    });
+    it("clears tickets when a newer epoch arrives", () => {
+        const pool = new PendingTicketPool();
+        pool.addTicket(E1, makeTicket(1));
+        pool.addTicket(E1, makeTicket(2));
+        pool.addTicket(E2, makeTicket(3));
+        const tickets = pool.getTickets();
+        assert.strictEqual(tickets.length, 1);
+        assert.strictEqual(tickets[0].epochIndex, E2);
+        assert.strictEqual(pool.currentEpoch, E2);
+    });
+    it("drops late tickets for older epochs", () => {
+        const pool = new PendingTicketPool();
+        pool.addTicket(E2, makeTicket(1));
+        assert.strictEqual(pool.addTicket(E1, makeTicket(2)), false);
+        assert.strictEqual(pool.getTickets().length, 1);
+        assert.strictEqual(pool.currentEpoch, E2);
+    });
+    it("replace clears existing tickets and dedups the new set", () => {
+        const pool = new PendingTicketPool();
+        pool.addTicket(E1, makeTicket(1));
+        pool.addTicket(E1, makeTicket(2));
+        const dump = [makeTicket(3), makeTicket(4), makeTicket(3)];
+        pool.replace(E2, dump);
+        const tickets = pool.getTickets();
+        assert.strictEqual(tickets.length, 2);
+        assert.strictEqual(pool.currentEpoch, E2);
+        assert.strictEqual(tickets[0].ticket.signature.raw[0], 3);
+        assert.strictEqual(tickets[1].ticket.signature.raw[0], 4);
+    });
+});

package/packages/jam/ticket-pool/ticket-validator.d.ts

@@ -0,0 +1,46 @@
+import type { EntropyHash, Epoch } from "#@typeberry/block";
+import type { SignedTicket } from "#@typeberry/block/tickets.js";
+import { Result } from "#@typeberry/utils";
+/**
+ * Outcome of a successful validation.
+ *
+ * `id` is the entropy hash the validator computed for this ticket. It is `null` when the
+ * concrete validator doesn't actually verify (e.g. {@link AcceptTicketsValidator}) or when
+ * it delegates to another process that doesn't bother to send the id back over the wire.
+ */
+export type ValidatedTicket = {
+    id: EntropyHash | null;
+};
+/** Reasons a ticket may fail validation. */
+export declare enum ValidationError {
+    /** Verifier rejected the signature / proof. */
+    InvalidProof = "invalid_proof",
+    /** Validator could not run (e.g. state unavailable, transient internal failure). */
+    ValidatorUnavailable = "validator_unavailable",
+    /** Ticket is for an epoch outside the validator's window of interest. */
+    WrongEpoch = "wrong_epoch"
+}
+/**
+ * Strategy for verifying tickets arriving from peers.
+ *
+ * The concrete implementation may call into the bandersnatch verifier, defer to another
+ * worker via IPC, or short-circuit (Accept/Deny defaults for tests).
+ */
+export interface TicketValidator {
+    validate(epochIndex: Epoch, ticket: SignedTicket): Promise<Result<ValidatedTicket, ValidationError>>;
+}
+/**
+ * Accepts every ticket without inspection. Useful for unit tests where the validator
+ * isn't the subject under test. Must never be used in production.
+ */
+export declare class AcceptTicketsValidator implements TicketValidator {
+    validate(_epochIndex: Epoch, _ticket: SignedTicket): Promise<Result<ValidatedTicket, ValidationError>>;
+}
+/**
+ * Rejects every ticket. Used as the default for any task that needs an explicit, real
+ * validator wired in before it will accept anything from the network.
+ */
+export declare class DenyTicketsValidator implements TicketValidator {
+    validate(_epochIndex: Epoch, _ticket: SignedTicket): Promise<Result<ValidatedTicket, ValidationError>>;
+}
+//# sourceMappingURL=ticket-validator.d.ts.map

package/packages/jam/ticket-pool/ticket-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket-validator.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/ticket-pool/ticket-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,WAAW,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,4CAA4C;AAC5C,oBAAY,eAAe;IACzB,+CAA+C;IAC/C,YAAY,kBAAkB;IAC9B,oFAAoF;IACpF,oBAAoB,0BAA0B;IAC9C,yEAAyE;IACzE,UAAU,gBAAgB;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,CAAC;CACtG;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IACtD,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;CAG7G;AAED;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IACpD,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;CAG7G"}

package/packages/jam/ticket-pool/ticket-validator.js

@@ -0,0 +1,29 @@
+import { Result } from "#@typeberry/utils";
+/** Reasons a ticket may fail validation. */
+export var ValidationError;
+(function (ValidationError) {
+    /** Verifier rejected the signature / proof. */
+    ValidationError["InvalidProof"] = "invalid_proof";
+    /** Validator could not run (e.g. state unavailable, transient internal failure). */
+    ValidationError["ValidatorUnavailable"] = "validator_unavailable";
+    /** Ticket is for an epoch outside the validator's window of interest. */
+    ValidationError["WrongEpoch"] = "wrong_epoch";
+})(ValidationError || (ValidationError = {}));
+/**
+ * Accepts every ticket without inspection. Useful for unit tests where the validator
+ * isn't the subject under test. Must never be used in production.
+ */
+export class AcceptTicketsValidator {
+    async validate(_epochIndex, _ticket) {
+        return Result.ok({ id: null });
+    }
+}
+/**
+ * Rejects every ticket. Used as the default for any task that needs an explicit, real
+ * validator wired in before it will accept anything from the network.
+ */
+export class DenyTicketsValidator {
+    async validate(_epochIndex, _ticket) {
+        return Result.error(ValidationError.ValidatorUnavailable, () => "no ticket validator wired");
+    }
+}

package/packages/jam/ticket-pool/ticket-validator.test.d.ts

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

package/packages/jam/ticket-pool/ticket-validator.test.d.ts.map

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