@aztec/stdlib 5.0.0-nightly.20260701 → 5.0.0-nightly.20260702

package/dest/logs/app_tagging_secret.js

@@ -5,6 +5,7 @@ import { z } from 'zod';
 import { AztecAddress } from '../aztec-address/index.js';
 import { computeAddressSecret, computePreaddress } from '../keys/derivation.js';
 import { AppTaggingSecretKind } from './app_tagging_secret_kind.js';
+import { appSiloEcdhSharedSecretPoint } from './shared_secret_derivation.js';
 const AppTaggingSecretKindSchema = z.union([
     z.literal(AppTaggingSecretKind.UNCONSTRAINED),
     z.literal(AppTaggingSecretKind.CONSTRAINED)
@@ -27,36 +28,35 @@ const AppTaggingSecretKindSchema = z.union([
     /**
    * Derives an app-siloed, recipient-directional tagging secret from a shared tagging secret point.
    *
+   * App-silos the point via {@link appSiloEcdhSharedSecretPoint}, then directs the result to `recipient`:
+   * `h([s_app, recipient])`. The directional step stops a symmetric shared secret (ECDH against an address, or an
+   * arbitrary registered point) from colliding bidirectionally, so two parties never share a tag sequence.
+   *
    * The point is obtained either via {@link computeSharedTaggingSecret} (an ECDH key exchange against a sender) or
-   * registered directly as a pre-shared secret. Each secret point yields a distinct tagging secret per (app, recipient)
-   * pair.
+   * registered directly as a pre-shared secret.
    *
    * @param taggingSecretPoint - The shared tagging secret point (ECDH output, or a directly registered pre-shared secret)
    * @param app - Contract address to silo the secret to
    * @param recipient - Recipient of the log. Defines the "direction of the secret".
    * @returns The secret that can be used along with an index to compute a tag to be included in a log.
-   */ static async compute(taggingSecretPoint, app, recipient) {
-        const appTaggingSecret = await poseidon2Hash([
-            taggingSecretPoint.x,
-            taggingSecretPoint.y,
-            app
-        ]);
+   */ static async computeDirectional(taggingSecretPoint, app, recipient) {
+        const appSiloedSecret = await appSiloEcdhSharedSecretPoint(taggingSecretPoint, app);
         const directionalAppTaggingSecret = await poseidon2Hash([
-            appTaggingSecret,
+            appSiloedSecret,
             recipient
         ]);
         return new AppTaggingSecret(directionalAppTaggingSecret, app);
     }
     /**
-   * Derives the unconstrained tagging secret for `(externalAddress, recipient, app)` by performing the ECDH key
-   * exchange against `externalAddress` and then siloing and directing the result. Returns undefined if
-   * `externalAddress` is not a valid address.
-   */ static async computeUnconstrained(localAddress, localIvsk, externalAddress, app, recipient) {
+   * Derives the tagging secret for `(externalAddress, recipient, app)` by performing an ECDH key exchange against
+   * `externalAddress` to obtain the shared point, then siloing and directing it via {@link computeDirectional}.
+   * Returns undefined if `externalAddress` is not a valid address.
+   */ static async computeViaEcdh(localAddress, localIvsk, externalAddress, app, recipient) {
         const taggingSecretPoint = await computeSharedTaggingSecret(localAddress, localIvsk, externalAddress);
         if (!taggingSecretPoint) {
             return undefined;
         }
-        return AppTaggingSecret.compute(taggingSecretPoint, app, recipient);
+        return AppTaggingSecret.computeDirectional(taggingSecretPoint, app, recipient);
     }
     toString() {
         // TODO(F-680): Migrate stored tagging keys and remove the legacy unconstrained format.

package/dest/logs/shared_secret_derivation.d.ts

@@ -1,12 +1,10 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
-import type { GrumpkinScalar } from '@aztec/foundation/curves/grumpkin';
+import type { GrumpkinScalar, Point } from '@aztec/foundation/curves/grumpkin';
 import type { AztecAddress } from '../aztec-address/index.js';
 import type { PublicKey } from '../keys/public_key.js';
 /**
- * Derives an app-siloed ECDH shared secret.
- *
- * Computes the raw ECDH shared secret `S = secretKey * publicKey`, then app-silos it:
- * `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, contractAddress)`
+ * Derives an app-siloed ECDH shared secret from keys: ECDHs `S = secretKey * publicKey`, then app-silos it via
+ * {@link appSiloEcdhSharedSecretPoint}.
  *
  * @param secretKey - The secret key used to derive shared secret.
  * @param publicKey - The public key used to derive shared secret.
@@ -14,5 +12,14 @@ import type { PublicKey } from '../keys/public_key.js';
  * @returns The app-siloed shared secret as a Field.
  * @throws If the publicKey is zero.
  */
-export declare function deriveAppSiloedSharedSecret(secretKey: GrumpkinScalar, publicKey: PublicKey, contractAddress: AztecAddress): Promise<Fr>;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2hhcmVkX3NlY3JldF9kZXJpdmF0aW9uLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbG9ncy9zaGFyZWRfc2VjcmV0X2Rlcml2YXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBR0EsT0FBTyxLQUFLLEVBQUUsRUFBRSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDekQsT0FBTyxLQUFLLEVBQUUsY0FBYyxFQUFFLE1BQU0sbUNBQW1DLENBQUM7QUFFeEUsT0FBTyxLQUFLLEVBQUUsWUFBWSxFQUFFLE1BQU0sMkJBQTJCLENBQUM7QUFDOUQsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFFdkQ7Ozs7Ozs7Ozs7O0dBV0c7QUFDSCx3QkFBc0IsMkJBQTJCLENBQy9DLFNBQVMsRUFBRSxjQUFjLEVBQ3pCLFNBQVMsRUFBRSxTQUFTLEVBQ3BCLGVBQWUsRUFBRSxZQUFZLEdBQzVCLE9BQU8sQ0FBQyxFQUFFLENBQUMsQ0FXYiJ9
+export declare function appSiloEcdhSharedSecret(secretKey: GrumpkinScalar, publicKey: PublicKey, contractAddress: AztecAddress): Promise<Fr>;
+/**
+ * App-silos a shared secret point: `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, app)`.
+ *
+ * Mirrors `compute_app_siloed_shared_secret` in aztec-nr.
+ *
+ * @param point - The raw shared secret point `S`.
+ * @param app - The contract address to silo to.
+ */
+export declare function appSiloEcdhSharedSecretPoint(point: Point, app: AztecAddress): Promise<Fr>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2hhcmVkX3NlY3JldF9kZXJpdmF0aW9uLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbG9ncy9zaGFyZWRfc2VjcmV0X2Rlcml2YXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBR0EsT0FBTyxLQUFLLEVBQUUsRUFBRSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDekQsT0FBTyxLQUFLLEVBQUUsY0FBYyxFQUFFLEtBQUssRUFBRSxNQUFNLG1DQUFtQyxDQUFDO0FBRS9FLE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBRSxNQUFNLDJCQUEyQixDQUFDO0FBQzlELE9BQU8sS0FBSyxFQUFFLFNBQVMsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRXZEOzs7Ozs7Ozs7R0FTRztBQUNILHdCQUFzQix1QkFBdUIsQ0FDM0MsU0FBUyxFQUFFLGNBQWMsRUFDekIsU0FBUyxFQUFFLFNBQVMsRUFDcEIsZUFBZSxFQUFFLFlBQVksR0FDNUIsT0FBTyxDQUFDLEVBQUUsQ0FBQyxDQVFiO0FBRUQ7Ozs7Ozs7R0FPRztBQUNILHdCQUFnQiw0QkFBNEIsQ0FBQyxLQUFLLEVBQUUsS0FBSyxFQUFFLEdBQUcsRUFBRSxZQUFZLEdBQUcsT0FBTyxDQUFDLEVBQUUsQ0FBQyxDQUV6RiJ9

package/dest/logs/shared_secret_derivation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared_secret_derivation.d.ts","sourceRoot":"","sources":["../../src/logs/shared_secret_derivation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,SAAS,EACpB,eAAe,EAAE,YAAY,GAC5B,OAAO,CAAC,EAAE,CAAC,CAWb"}
+{"version":3,"file":"shared_secret_derivation.d.ts","sourceRoot":"","sources":["../../src/logs/shared_secret_derivation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAC;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,SAAS,EACpB,eAAe,EAAE,YAAY,GAC5B,OAAO,CAAC,EAAE,CAAC,CAQb;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,EAAE,CAAC,CAEzF"}

package/dest/logs/shared_secret_derivation.js

@@ -2,24 +2,32 @@ import { DomainSeparator } from '@aztec/constants';
 import { Grumpkin } from '@aztec/foundation/crypto/grumpkin';
 import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 /**
- * Derives an app-siloed ECDH shared secret.
- *
- * Computes the raw ECDH shared secret `S = secretKey * publicKey`, then app-silos it:
- * `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, contractAddress)`
+ * Derives an app-siloed ECDH shared secret from keys: ECDHs `S = secretKey * publicKey`, then app-silos it via
+ * {@link appSiloEcdhSharedSecretPoint}.
  *
  * @param secretKey - The secret key used to derive shared secret.
  * @param publicKey - The public key used to derive shared secret.
  * @param contractAddress - The address of the calling contract, used for app-siloing.
  * @returns The app-siloed shared secret as a Field.
  * @throws If the publicKey is zero.
- */ export async function deriveAppSiloedSharedSecret(secretKey, publicKey, contractAddress) {
+ */ export async function appSiloEcdhSharedSecret(secretKey, publicKey, contractAddress) {
     if (publicKey.isZero()) {
         throw new Error(`Attempting to derive a shared secret with a zero public key. You have probably passed a zero public key in your Noir code somewhere thinking that the note won't be broadcast... but it was.`);
     }
     const rawSharedSecret = await Grumpkin.mul(publicKey, secretKey);
+    return appSiloEcdhSharedSecretPoint(rawSharedSecret, contractAddress);
+}
+/**
+ * App-silos a shared secret point: `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, app)`.
+ *
+ * Mirrors `compute_app_siloed_shared_secret` in aztec-nr.
+ *
+ * @param point - The raw shared secret point `S`.
+ * @param app - The contract address to silo to.
+ */ export function appSiloEcdhSharedSecretPoint(point, app) {
     return poseidon2HashWithSeparator([
-        rawSharedSecret.x,
-        rawSharedSecret.y,
-        contractAddress
+        point.x,
+        point.y,
+        app
     ], DomainSeparator.APP_SILOED_ECDH_SHARED_SECRET);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/stdlib",
-  "version": "5.0.0-nightly.20260701",
+  "version": "5.0.0-nightly.20260702",
   "type": "module",
   "inherits": [
     "../package.common.json",
@@ -92,13 +92,13 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.892.0",
-    "@aztec/bb.js": "5.0.0-nightly.20260701",
-    "@aztec/blob-lib": "5.0.0-nightly.20260701",
-    "@aztec/constants": "5.0.0-nightly.20260701",
-    "@aztec/ethereum": "5.0.0-nightly.20260701",
-    "@aztec/foundation": "5.0.0-nightly.20260701",
-    "@aztec/l1-artifacts": "5.0.0-nightly.20260701",
-    "@aztec/noir-noirc_abi": "5.0.0-nightly.20260701",
+    "@aztec/bb.js": "5.0.0-nightly.20260702",
+    "@aztec/blob-lib": "5.0.0-nightly.20260702",
+    "@aztec/constants": "5.0.0-nightly.20260702",
+    "@aztec/ethereum": "5.0.0-nightly.20260702",
+    "@aztec/foundation": "5.0.0-nightly.20260702",
+    "@aztec/l1-artifacts": "5.0.0-nightly.20260702",
+    "@aztec/noir-noirc_abi": "5.0.0-nightly.20260702",
     "@google-cloud/storage": "^7.15.0",
     "axios": "^1.15.1",
     "json-stringify-deterministic": "1.0.12",

package/src/block/l2_block_source.ts

@@ -324,6 +324,7 @@ export type ArchiverEmitter = TypedEventEmitter<{
   [L2BlockSourceEvents.DescendentOfInvalidAttestationsCheckpointDetected]: (
     args: DescendentOfInvalidAttestationsCheckpointEvent,
   ) => void;
+  [L2BlockSourceEvents.L2BlockSourceUpdated]: (args: L2BlockSourceUpdatedEvent) => void;
 }>;
 export interface L2BlockSourceEventEmitter extends L2BlockSource {
   events: ArchiverEmitter;
@@ -376,6 +377,28 @@ export function makeL2CheckpointId(number: CheckpointNumber, hash: string): Chec
   return { number, hash };
 }
 
+function l2BlockIdEquals(a: L2BlockId, b: L2BlockId): boolean {
+  return a.number === b.number && a.hash === b.hash;
+}
+
+function l2TipIdEquals(a: L2TipId, b: L2TipId): boolean {
+  return (
+    l2BlockIdEquals(a.block, b.block) &&
+    a.checkpoint.number === b.checkpoint.number &&
+    a.checkpoint.hash === b.checkpoint.hash
+  );
+}
+
+/** Returns whether two {@link L2Tips} snapshots agree on every tier (proposed, checkpointed, proven, finalized). */
+export function l2TipsEqual(a: L2Tips, b: L2Tips): boolean {
+  return (
+    l2BlockIdEquals(a.proposed, b.proposed) &&
+    l2TipIdEquals(a.checkpointed, b.checkpointed) &&
+    l2TipIdEquals(a.proven, b.proven) &&
+    l2TipIdEquals(a.finalized, b.finalized)
+  );
+}
+
 const L2BlockIdSchema = z.object({
   number: BlockNumberSchema,
   hash: z.string(),
@@ -406,8 +429,26 @@ export enum L2BlockSourceEvents {
   InvalidAttestationsCheckpointDetected = 'invalidCheckpointDetected',
   CheckpointEquivocationDetected = 'checkpointEquivocationDetected',
   DescendentOfInvalidAttestationsCheckpointDetected = 'descendentOfInvalidAttestationsCheckpointDetected',
+  L2BlockSourceUpdated = 'l2BlockSourceUpdated',
 }
 
+/**
+ * Aggregate event emitted once per committed archiver sync pass that mutated local state. Carries the chain tips
+ * before and after the pass, and the blocks added during it. Consumers compare `fromTips` and `toTips` to learn what
+ * moved; there is no separate `changed` section.
+ *
+ * This is an optimization signal that lets a block stream reconcile immediately on an archiver update rather than
+ * waiting for its next poll. Polling remains the correctness fallback, so a missed event only affects latency.
+ * `blocksAdded` are hydrated blocks already in hand from the sync pass, so a triggered sync that is caught up to
+ * `fromTips` can reuse them (and `toTips`) instead of re-reading the store.
+ */
+export type L2BlockSourceUpdatedEvent = {
+  type: 'l2BlockSourceUpdated';
+  fromTips: L2Tips;
+  toTips: L2Tips;
+  blocksAdded: readonly L2Block[];
+};
+
 export type L2BlockProvenEvent = {
   type: 'l2BlockProven';
   blockNumber: BlockNumber;

package/src/block/l2_block_stream/event_driven_l2_block_stream.ts

@@ -0,0 +1,207 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/running-promise';
+
+import type { BlockData } from '../block_data.js';
+import type { L2Block } from '../l2_block.js';
+import {
+  type ArchiverEmitter,
+  type BlockQuery,
+  type BlocksQuery,
+  type L2BlockSource,
+  type L2BlockSourceEventEmitter,
+  L2BlockSourceEvents,
+  type L2BlockSourceUpdatedEvent,
+  type L2Tips,
+} from '../l2_block_source.js';
+import { type L2BlockStreamEventHandler, type L2BlockStreamLocalDataProvider, localTipsMatch } from './interfaces.js';
+import { L2BlockStream, type L2BlockStreamOptions, type L2BlockStreamSource } from './l2_block_stream.js';
+
+/** Derives the metadata-only {@link BlockData} view of a hydrated {@link L2Block}. */
+async function l2BlockToBlockData(block: L2Block): Promise<BlockData> {
+  return {
+    header: block.header,
+    archive: block.archive,
+    blockHash: await block.hash(),
+    checkpointNumber: block.checkpointNumber,
+    indexWithinCheckpoint: block.indexWithinCheckpoint,
+  };
+}
+
+/** Returns the event emitter of a source that exposes one, or undefined for plain (e.g. RPC-backed) sources. */
+function getEmitter(source: L2BlockSource | L2BlockSourceEventEmitter): ArchiverEmitter | undefined {
+  return 'events' in source ? source.events : undefined;
+}
+
+/** Fast-path context for a single sync pass: blocks to serve by number, plus the tips to report as the source's. */
+type ActiveUpdate = { byNumber: Map<number, L2Block>; toTips: L2Tips };
+
+/**
+ * Wraps a block source so a single sync pass can be served from blocks delivered by an aggregate update event,
+ * avoiding round-trips to archiver storage. The fast path is only armed (via {@link activate}) for a pass that is
+ * confirmed caught up to the event's pre-pass tips: in that case the event's `blocksAdded` contiguously cover the
+ * pass's download range and `toTips` is the exact post-pass tip, so `getL2Tips` can report it without querying the
+ * source. When the fast path is not armed, every read delegates to the source, so a stale or partial cache never
+ * changes the sync outcome.
+ */
+class HotBlockSourceAdapter implements L2BlockStreamSource {
+  /** Set for the duration of one fast-path pass; undefined when reads must delegate to the source. */
+  private active: ActiveUpdate | undefined;
+
+  constructor(
+    private readonly source: L2BlockStreamSource,
+    private readonly log: Logger,
+  ) {}
+
+  /** Arms the fast path for the current pass: serve these blocks and report `toTips` as the source tips. */
+  public activate(blocks: readonly L2Block[], toTips: L2Tips): void {
+    const byNumber = new Map<number, L2Block>();
+    for (const block of blocks) {
+      byNumber.set(block.number, block);
+    }
+    this.active = { byNumber, toTips };
+    this.log.trace(`Armed hot-block fast path`, { blocks: byNumber.size, toTips });
+  }
+
+  /** Disarms the fast path so subsequent reads delegate to the source again. */
+  public deactivate(): void {
+    this.active = undefined;
+  }
+
+  public getL2Tips(): Promise<L2Tips> {
+    return this.active ? Promise.resolve(this.active.toTips) : this.source.getL2Tips();
+  }
+
+  public getBlocks(query: BlocksQuery): Promise<L2Block[]> {
+    const served = this.active ? this.tryServeBlocksFromCache(query) : undefined;
+    return served ? Promise.resolve(served) : this.source.getBlocks(query);
+  }
+
+  public getBlockData(query: BlockQuery): Promise<BlockData | undefined> {
+    if (this.active && 'number' in query) {
+      const block = this.active.byNumber.get(query.number);
+      if (block) {
+        return l2BlockToBlockData(block);
+      }
+    }
+    return this.source.getBlockData(query);
+  }
+
+  /** Serves a block range from the cache only when it is fully covered by contiguous cached blocks. */
+  private tryServeBlocksFromCache(query: BlocksQuery): L2Block[] | undefined {
+    // Only the by-range form is cacheable, and only for the full (not checkpointed-only) chain: the cache may hold
+    // uncheckpointed blocks that an onlyCheckpointed query must not receive.
+    if (!this.active || !('from' in query) || query.onlyCheckpointed) {
+      return undefined;
+    }
+    const from = query.from;
+    const to = from + query.limit - 1;
+    const blocks: L2Block[] = [];
+    for (let n = from; n <= to; n++) {
+      const block = this.active.byNumber.get(n);
+      if (!block) {
+        // A gap inside the requested range: bail out and let the source serve the whole range.
+        return undefined;
+      }
+      blocks.push(block);
+    }
+    return blocks;
+  }
+}
+
+/**
+ * Event-driven wrapper around {@link L2BlockStream}. Subscribes to the source's aggregate `l2BlockSourceUpdated`
+ * event (when the source exposes one) to trigger an immediate reconciliation, while keeping the periodic poll as
+ * the correctness fallback. Subsystems keep consuming the same {@link L2BlockStreamEvent}s; the archiver aggregate
+ * event is handled entirely here.
+ *
+ * The event is passed through to the sync pass via {@link RunningPromise.trigger}. If, at the time the pass runs,
+ * the stream's local tips match the event's `fromTips` (it is caught up to where the event began), the event's
+ * hydrated blocks are served back through a hot-block cache and the event's `toTips` is reported as the source tips
+ * — so the triggered sync re-reads neither block bodies nor tips from the archiver. Otherwise the pass delegates
+ * entirely to the source, and the periodic poll guarantees eventual catch-up.
+ */
+export class EventDrivenL2BlockStream {
+  private readonly adapter: HotBlockSourceAdapter;
+  private readonly blockStream: L2BlockStream;
+  private readonly runningPromise: RunningPromise<L2BlockSourceUpdatedEvent>;
+  private readonly emitter: ArchiverEmitter | undefined;
+  private started = false;
+
+  private readonly onSourceUpdated = (event: L2BlockSourceUpdatedEvent) => {
+    // Fire-and-forget: trigger coalesces with any in-flight or periodic pass (see RunningPromise.trigger), so a
+    // burst of events does not run passes concurrently. Errors are swallowed by the inner stream's own handler.
+    void this.runningPromise
+      .trigger(event)
+      .catch(err => this.log.error(`Error in event-triggered block stream sync`, err));
+  };
+
+  constructor(
+    source: L2BlockSource | L2BlockSourceEventEmitter,
+    private readonly localData: L2BlockStreamLocalDataProvider,
+    handler: L2BlockStreamEventHandler,
+    private readonly log = createLogger('types:event_driven_block_stream'),
+    opts: L2BlockStreamOptions = {},
+  ) {
+    this.adapter = new HotBlockSourceAdapter(source, log);
+    // The inner stream's own RunningPromise is never started; this wrapper owns the polling loop and drives the
+    // stream through `sync()` (which runs `work()` directly when the inner loop is stopped).
+    this.blockStream = new L2BlockStream(this.adapter, localData, handler, log, opts);
+    this.runningPromise = new RunningPromise<L2BlockSourceUpdatedEvent>(
+      this.runPass.bind(this),
+      log,
+      opts.pollIntervalMS ?? 1000,
+    );
+    this.emitter = getEmitter(source);
+  }
+
+  public start(): void {
+    if (this.started) {
+      this.log.warn(`Attempted to start an already-started event-driven block stream`);
+      return;
+    }
+    this.started = true;
+    this.emitter?.on(L2BlockSourceEvents.L2BlockSourceUpdated, this.onSourceUpdated);
+    this.runningPromise.start();
+  }
+
+  public async stop(): Promise<void> {
+    this.started = false;
+    this.emitter?.off(L2BlockSourceEvents.L2BlockSourceUpdated, this.onSourceUpdated);
+    await this.runningPromise.stop();
+    await this.blockStream.stop();
+  }
+
+  public isRunning(): boolean {
+    return this.runningPromise.isRunning();
+  }
+
+  /**
+   * Runs a synchronization pass now, bypassing the poll interval, and resolves once that pass completes. Concurrent
+   * callers and periodic ticks coalesce onto a single pass; a caller that coalesces onto an already in-flight pass
+   * can resolve against a pass that began just before it, so this guarantees freshness only up to that coalescing
+   * window. The periodic poll and per-pass reorg handling make the gap a latency effect, never a correctness one.
+   */
+  public sync(): Promise<void> {
+    return this.runningPromise.trigger();
+  }
+
+  /**
+   * Runs a single pass over the underlying block stream. When triggered by an aggregate event and the stream is
+   * caught up to the event's pre-pass tips, the event's blocks and tips serve the pass directly; the fast path is
+   * always disarmed afterwards so a subsequent poll-driven pass reads from the source.
+   */
+  private async runPass(event?: L2BlockSourceUpdatedEvent): Promise<void> {
+    if (event) {
+      const localTips = await this.localData.getL2Tips();
+      if (localTipsMatch(localTips, event.fromTips)) {
+        this.adapter.activate(event.blocksAdded, event.toTips);
+      }
+    }
+
+    try {
+      await this.blockStream.sync();
+    } finally {
+      this.adapter.deactivate();
+    }
+  }
+}

package/src/block/l2_block_stream/index.ts

@@ -1,3 +1,4 @@
+export * from './event_driven_l2_block_stream.js';
 export * from './interfaces.js';
 export * from './l2_block_stream.js';
 export * from './l2_tips_memory_store.js';

package/src/block/l2_block_stream/interfaces.ts

@@ -1,7 +1,7 @@
 import type { BlockNumber } from '@aztec/foundation/branded-types';
 
 import type { L2Block } from '../l2_block.js';
-import type { CheckpointId, L2BlockId, L2TipId, LocalL2Tips } from '../l2_block_source.js';
+import type { CheckpointId, L2BlockId, L2TipId, L2Tips, LocalL2Tips } from '../l2_block_source.js';
 
 /** Provides the current chain tips. Implemented by world-state, l2-tips-store, and AztecNode. */
 export interface L2TipsProvider {
@@ -35,6 +35,40 @@ export interface L2BlockStreamLocalDataProvider {
   getL2BlockHash(number: number): Promise<string | undefined>;
 }
 
+/**
+ * Returns whether a local block id differs from a source block id. Compares block number and, when the local hash is
+ * known, block hash. The hash comparison is skipped when the local hash is undefined: world-state legitimately
+ * reports `undefined` hashes for tips ahead of its synced range, and comparing against an undefined hash would treat
+ * such a tip as different on every poll. An `undefined` local block (no local tip yet) always counts as differing.
+ */
+export function localBlockIdDiffers(localBlock: LocalL2BlockId | undefined, sourceBlock: L2BlockId): boolean {
+  if (localBlock === undefined) {
+    return true;
+  }
+  if (sourceBlock.number !== localBlock.number) {
+    return true;
+  }
+  if (localBlock.hash === undefined) {
+    return false;
+  }
+  return sourceBlock.hash !== localBlock.hash;
+}
+
+/**
+ * Returns whether the local chain tips agree with the given source tips on every tier the local provider exposes.
+ * Each tier is compared at the block level via {@link localBlockIdDiffers} (so an unresolved local hash matches on
+ * number alone); checkpoint ids are not compared, mirroring the stream's own tier reconciliation. The optional
+ * `checkpointed` tier is only compared when present (it is absent when the stream ignores checkpoints).
+ */
+export function localTipsMatch(local: LocalChainTips, source: L2Tips): boolean {
+  return (
+    !localBlockIdDiffers(local.proposed, source.proposed) &&
+    (local.checkpointed === undefined || !localBlockIdDiffers(local.checkpointed.block, source.checkpointed.block)) &&
+    !localBlockIdDiffers(local.proven.block, source.proven.block) &&
+    !localBlockIdDiffers(local.finalized.block, source.finalized.block)
+  );
+}
+
 /** Interface to a handler of events emitted. */
 export interface L2BlockStreamEventHandler {
   handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;

package/src/block/l2_block_stream/l2_block_stream.ts

@@ -4,22 +4,34 @@ import { createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/running-promise';
 
 import type { L2Block } from '../l2_block.js';
+import { type L2BlockId, type L2BlockSource, type LocalL2Tips, makeL2BlockId } from '../l2_block_source.js';
 import {
-  type L2BlockId,
-  type L2BlockSource,
-  type L2TipId,
-  type LocalL2Tips,
-  makeL2BlockId,
-} from '../l2_block_source.js';
-import type {
-  L2BlockStreamEvent,
-  L2BlockStreamEventHandler,
-  L2BlockStreamLocalDataProvider,
-  LocalL2BlockId,
+  type L2BlockStreamEvent,
+  type L2BlockStreamEventHandler,
+  type L2BlockStreamLocalDataProvider,
+  localBlockIdDiffers,
 } from './interfaces.js';
 
 /** Subset of the block source the stream depends on. Checkpoint payloads are no longer fetched here. */
-type L2BlockStreamSource = Pick<L2BlockSource, 'getBlocks' | 'getBlockData' | 'getL2Tips'>;
+export type L2BlockStreamSource = Pick<L2BlockSource, 'getBlocks' | 'getBlockData' | 'getL2Tips'>;
+
+/** Options accepted by {@link L2BlockStream} and {@link EventDrivenL2BlockStream}. */
+export type L2BlockStreamOptions = {
+  pollIntervalMS?: number;
+  batchSize?: number;
+  startingBlock?: number;
+  /** Instead of downloading all blocks, only fetch the smallest subset that results in reliable reorg detection. */
+  skipFinalized?: boolean;
+  /** When true, checkpoint events will not be emitted. Blocks are still fetched but only blocks-added events are emitted. */
+  ignoreCheckpoints?: boolean;
+  /**
+   * When true, the block download loop is skipped entirely: `getBlocks` is never called and `blocks-added` is
+   * never emitted. Only the tip events (`chain-proposed`/`chain-checkpointed`/`chain-proven`/`chain-finalized`)
+   * and `chain-pruned` are emitted, driven by the `getL2Tips` snapshot. For consumers that track tips but never
+   * consume block payloads.
+   */
+  tipsOnly?: boolean;
+};
 
 /** Creates a stream of events for new blocks, chain tips updates, and reorgs, out of polling an archiver or a node. */
 export class L2BlockStream {
@@ -32,22 +44,7 @@ export class L2BlockStream {
     private localData: L2BlockStreamLocalDataProvider,
     private handler: L2BlockStreamEventHandler,
     private readonly log = createLogger('types:block_stream'),
-    private opts: {
-      pollIntervalMS?: number;
-      batchSize?: number;
-      startingBlock?: number;
-      /** Instead of downloading all blocks, only fetch the smallest subset that results in reliable reorg detection. */
-      skipFinalized?: boolean;
-      /** When true, checkpoint events will not be emitted. Blocks are still fetched but only blocks-added events are emitted. */
-      ignoreCheckpoints?: boolean;
-      /**
-       * When true, the block download loop is skipped entirely: `getBlocks` is never called and `blocks-added` is
-       * never emitted. Only the tip events (`chain-proposed`/`chain-checkpointed`/`chain-proven`/`chain-finalized`)
-       * and `chain-pruned` are emitted, driven by the `getL2Tips` snapshot. For consumers that track tips but never
-       * consume block payloads.
-       */
-      tipsOnly?: boolean;
-    } = {},
+    private opts: L2BlockStreamOptions = {},
   ) {
     if (opts.tipsOnly && (opts.startingBlock !== undefined || opts.batchSize !== undefined || opts.skipFinalized)) {
       throw new Error(
@@ -181,19 +178,25 @@ export class L2BlockStream {
       // End-of-pass reconciliation: chain-proposed fires against the pre-pass baseline (a post-prune re-read would
       // equal the source tip and suppress it), then the tiers highest-to-lowest so the finalized <= proven <=
       // checkpointed <= proposed invariant holds mid-pass.
-      if (this.blockTipDiffers(prePassProposed, sourceTips.proposed)) {
+      if (localBlockIdDiffers(prePassProposed, sourceTips.proposed)) {
         await this.emitEvent({ type: 'chain-proposed', block: sourceTips.proposed });
       }
 
       const reconcileTips = pruned ? await this.localData.getL2Tips() : localTips;
-      if (!this.opts.ignoreCheckpoints && this.tipDiffers(reconcileTips.checkpointed?.block, sourceTips.checkpointed)) {
+      if (
+        !this.opts.ignoreCheckpoints &&
+        localBlockIdDiffers(reconcileTips.checkpointed?.block, sourceTips.checkpointed.block)
+      ) {
         await this.emitEvent({
           type: 'chain-checkpointed',
           block: sourceTips.checkpointed.block,
           checkpoint: sourceTips.checkpointed.checkpoint,
         });
       }
-      if (reconcileTips.proven !== undefined && this.tipDiffers(reconcileTips.proven.block, sourceTips.proven)) {
+      if (
+        reconcileTips.proven !== undefined &&
+        localBlockIdDiffers(reconcileTips.proven.block, sourceTips.proven.block)
+      ) {
         await this.emitEvent({
           type: 'chain-proven',
           block: sourceTips.proven.block,
@@ -202,7 +205,7 @@ export class L2BlockStream {
       }
       if (
         reconcileTips.finalized !== undefined &&
-        this.tipDiffers(reconcileTips.finalized.block, sourceTips.finalized)
+        localBlockIdDiffers(reconcileTips.finalized.block, sourceTips.finalized.block)
       ) {
         await this.emitEvent({
           type: 'chain-finalized',
@@ -286,36 +289,6 @@ export class L2BlockStream {
     return true;
   }
 
-  /**
-   * Returns whether the source tip differs from the local one and therefore warrants a tier event. Compares block
-   * number and, when both hashes are known, block hash. The hash comparison is skipped when the local hash is
-   * undefined or missing: world-state legitimately reports `undefined` hashes for tips ahead of its synced range,
-   * and comparing against an undefined hash would re-emit the event on every poll.
-   */
-  private tipDiffers(localBlock: LocalL2BlockId | undefined, sourceTip: L2TipId): boolean {
-    return this.blockTipDiffers(localBlock, sourceTip.block);
-  }
-
-  /**
-   * Block-only variant of {@link tipDiffers} for the proposed tip (an {@link L2BlockId}, with no checkpoint). Compares
-   * block number and, when the local hash is known, block hash. The hash comparison is skipped when the local hash is
-   * undefined: world-state reports `undefined` for its proposed hash, and a strict comparison would re-emit
-   * `chain-proposed` on every poll for it. ({@link L2TipsStoreBase} consumers always carry a hash, so the leniency is
-   * inert for them.)
-   */
-  private blockTipDiffers(localBlock: LocalL2BlockId | undefined, sourceBlock: L2BlockId): boolean {
-    if (localBlock === undefined) {
-      return true;
-    }
-    if (sourceBlock.number !== localBlock.number) {
-      return true;
-    }
-    if (localBlock.hash === undefined) {
-      return false;
-    }
-    return sourceBlock.hash !== localBlock.hash;
-  }
-
   /**
    * Returns whether the source and local agree on the block hash at a given height.
    * @param blockNumber - The block number to test.

package/src/contract/contract_address.ts

@@ -7,6 +7,7 @@ import type { AztecAddress } from '../aztec-address/index.js';
 import { computeVarArgsHash } from '../hash/hash.js';
 import { computeAddress } from '../keys/index.js';
 import type { ContractInstance } from './interfaces/contract_instance.js';
+import type { PartialAddress } from './partial_address.js';
 
 // TODO(@spalladino): Review all generator indices in this file
 
@@ -36,7 +37,7 @@ export async function computePartialAddress(
   instance:
     | Pick<ContractInstance, 'originalContractClassId' | 'initializationHash' | 'salt' | 'deployer' | 'immutablesHash'>
     | { originalContractClassId: Fr; saltedInitializationHash: Fr },
-): Promise<Fr> {
+): Promise<PartialAddress> {
   const saltedInitializationHash =
     'saltedInitializationHash' in instance
       ? instance.saltedInitializationHash