@aztec/prover-node 0.0.1-commit.9ef841308 → 0.0.1-commit.a4600f49

package/dest/job/epoch-session.d.ts

@@ -0,0 +1,146 @@
+import { BlockNumber, type EpochNumber, type SlotNumber } from '@aztec/foundation/branded-types';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type LoggerBindings } from '@aztec/foundation/log';
+import { type DateProvider } from '@aztec/foundation/timer';
+import type { EpochProverFactory } from '@aztec/prover-client';
+import { type EpochProvingJobState } from '@aztec/stdlib/interfaces/server';
+import { type Traceable, type Tracer } from '@aztec/telemetry-client';
+import type { ProverNodeJobMetrics } from '../metrics.js';
+import type { ProofPublishingService } from '../proof-publishing-service.js';
+import { CheckpointProver } from './checkpoint-prover.js';
+import { type TopTreeProof } from './top-tree-job.js';
+export type { EpochProvingJobState };
+/** Full vs partial — the only behavioural difference is at the L1 submission step. */
+export type SessionKind = 'full' | 'partial';
+/**
+ * Identifies what a session proves: a contiguous slot range within an epoch. The
+ * concrete prover set the session holds is the *implementation* of the spec — frozen
+ * at construction time, derived from the canonical content for `[fromSlot, toSlot]`.
+ *
+ * Reconciliation in `ProverNode` is uniform across kinds: whenever the canonical
+ * content for the slot range changes, the session is cancelled and replaced with a
+ * fresh session that **preserves the slot range** but adopts the new checkpoints.
+ *
+ * Kind affects only the publishing decision (see `EpochSession`).
+ */
+export interface SessionSpec {
+    kind: SessionKind;
+    epochNumber: EpochNumber;
+    fromSlot: SlotNumber;
+    toSlot: SlotNumber;
+}
+/** Stable string key for use in maps. */
+export declare function specKey(spec: SessionSpec): string;
+/** Hooks tests use to interpose around the top-tree prove without monkey-patching. */
+export type EpochSessionHooks = {
+    beforeTopTreeProve?: () => Promise<void> | void;
+    afterTopTreeProve?: () => Promise<void> | void;
+    topTreeProveOverride?: (defaultProve: () => Promise<TopTreeProof>) => Promise<TopTreeProof>;
+};
+export type EpochSessionOptions = {
+    /**
+     * If set, the session sleeps this many ms after `start()` (before the TopTreeJob is
+     * constructed). Lets late-arriving events (e.g. a prune) be processed before
+     * top-tree proving begins.
+     */
+    finalizationDelayMs?: number;
+};
+/** Dependencies an `EpochSession` needs at construction. */
+export type EpochSessionDeps = {
+    proverFactory: EpochProverFactory;
+    proverId: EthAddress;
+    publishingService: Pick<ProofPublishingService, 'submit' | 'withdraw'>;
+    metrics: ProverNodeJobMetrics;
+    dateProvider: DateProvider;
+    /** Optional proving deadline. The session enters `timed-out` if exceeded. */
+    deadline: Date | undefined;
+    config: EpochSessionOptions;
+    bindings?: LoggerBindings;
+    hooks?: EpochSessionHooks;
+};
+/**
+ * One attempt at proving and publishing a contiguous slot range. The `SessionSpec` and
+ * the prover set are both frozen at construction time; the session does not adapt to
+ * reorgs or extensions of canonical content. Instead, `SessionManager` owns the
+ * reconciliation loop and replaces invalidated sessions wholesale (cancel + construct
+ * a fresh session with the new prover set).
+ *
+ * Each session does three things in sequence:
+ *
+ *   1. Run a `TopTreeJob` over its frozen prover subset to produce the epoch proof.
+ *   2. Hand the proof to the shared `ProofPublishingService` as a `PublishCandidate`.
+ *   3. Translate the service's outcome into a terminal session state.
+ *
+ * Everything to do with submission — predecessor gating, same-epoch dedup, deadline
+ * enforcement, and the L1 transaction itself — is the publishing service's concern.
+ * The session is just the producer of one candidate and the observer of its outcome.
+ *
+ * Lifecycle (happy path):
+ *
+ *   initialized → awaiting-checkpoints → awaiting-root → publishing-proof → completed
+ *
+ * Terminal states map the publishing outcome: `published` → `completed`, `superseded` →
+ * `superseded`, `failed` → `failed`, `expired` → `timed-out`, `withdrawn` → `cancelled`.
+ * Additionally, the session-level deadline fires `cancel('deadline')` and transitions
+ * to `timed-out` for the pre-submit window (top-tree proving) — the publishing service
+ * handles the post-submit window via the candidate's `deadline`.
+ *
+ * `cancel()` is idempotent. It marks the session terminal, calls
+ * `publishingService.withdraw(uuid)` to drop any queued candidate (an in-flight publish
+ * runs to natural completion; the session has already settled), and tears down the
+ * top-tree job if proving is still in progress.
+ */
+export declare class EpochSession implements Traceable {
+    private readonly spec;
+    private readonly deps;
+    readonly tracer: Tracer;
+    private readonly uuid;
+    private readonly log;
+    private state;
+    private deadlineTimeoutHandler;
+    private topTreeJob;
+    /** Cancelled top-tree jobs whose teardown is still in flight. Awaited at session stop. */
+    private readonly pendingTopTreeCleanups;
+    private readonly completionPromise;
+    private resolveCompletion;
+    /** Stable reference; never mutated after construction. */
+    private readonly checkpoints;
+    constructor(spec: SessionSpec, checkpoints: readonly CheckpointProver[], deps: EpochSessionDeps);
+    getId(): string;
+    getSpec(): SessionSpec;
+    getState(): EpochProvingJobState;
+    getEpochNumber(): EpochNumber;
+    getKind(): SessionKind;
+    getDeadline(): Date | undefined;
+    getCheckpoints(): readonly CheckpointProver[];
+    /** Resolves when the session reaches a terminal state. */
+    whenDone(): Promise<EpochProvingJobState>;
+    /** True if the session is in a terminal state. */
+    isTerminal(): boolean;
+    /** First block this session proves. */
+    getStartBlockNumber(): BlockNumber;
+    /** Last block this session proves. */
+    getEndBlockNumber(): BlockNumber;
+    /**
+     * Kicks off proving + submission. Fires and forgets — callers should await `whenDone()`.
+     * Returns a promise that resolves to the final state for callers that want to wait inline.
+     */
+    start(): Promise<EpochProvingJobState>;
+    /**
+     * Cancels the session. Idempotent. Withdraws any submitted candidate from the
+     * publishing service so the in-flight publisher (if any) is interrupted.
+     */
+    cancel(reason?: string): Promise<void>;
+    private run;
+    private submitProof;
+    private teardownTopTreeIfNeeded;
+    private scheduleDeadlineStop;
+    /**
+     * Returns a promise that resolves once cancellation has propagated and the state has
+     * been flipped from 'cancelled' to 'timed-out'. Protected so unit tests can drive the
+     * deadline path without waiting on the real `setTimeout` to fire.
+     */
+    protected handleDeadline(): Promise<void>;
+    private toTopTreeHooks;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXBvY2gtc2Vzc2lvbi5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2pvYi9lcG9jaC1zZXNzaW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxXQUFXLEVBQXlCLEtBQUssV0FBVyxFQUFFLEtBQUssVUFBVSxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFDeEgsT0FBTyxLQUFLLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDaEUsT0FBTyxFQUFlLEtBQUssY0FBYyxFQUFnQixNQUFNLHVCQUF1QixDQUFDO0FBRXZGLE9BQU8sRUFBRSxLQUFLLFlBQVksRUFBUyxNQUFNLHlCQUF5QixDQUFDO0FBQ25FLE9BQU8sS0FBSyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFL0QsT0FBTyxFQUFFLEtBQUssb0JBQW9CLEVBQWdDLE1BQU0saUNBQWlDLENBQUM7QUFDMUcsT0FBTyxFQUFjLEtBQUssU0FBUyxFQUFFLEtBQUssTUFBTSxFQUFhLE1BQU0seUJBQXlCLENBQUM7QUFJN0YsT0FBTyxLQUFLLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxlQUFlLENBQUM7QUFDMUQsT0FBTyxLQUFLLEVBQUUsc0JBQXNCLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUM3RSxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUMxRCxPQUFPLEVBQW9DLEtBQUssWUFBWSxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFFeEYsWUFBWSxFQUFFLG9CQUFvQixFQUFFLENBQUM7QUFFckMsd0ZBQXNGO0FBQ3RGLE1BQU0sTUFBTSxXQUFXLEdBQUcsTUFBTSxHQUFHLFNBQVMsQ0FBQztBQUU3Qzs7Ozs7Ozs7OztHQVVHO0FBQ0gsTUFBTSxXQUFXLFdBQVc7SUFDMUIsSUFBSSxFQUFFLFdBQVcsQ0FBQztJQUNsQixXQUFXLEVBQUUsV0FBVyxDQUFDO0lBQ3pCLFFBQVEsRUFBRSxV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

package/dest/job/epoch-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch-session.d.ts","sourceRoot":"","sources":["../../src/job/epoch-session.ts"],"names":[],"mappings":"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"}