@aztec-labs/stdlib 6.0.0-rc.1 → 6.0.0-rc.3

package/src/gas/gas_fees.ts

@@ -90,6 +90,14 @@ export class GasFees {
     return new GasFees(Math.floor(Math.random() * 1e9), Math.floor(Math.random() * 1e9));
   }
 
+  /** The lower of the two fees on each dimension independently. */
+  static min(a: GasFees, b: GasFees) {
+    return new GasFees(
+      a.feePerDaGas < b.feePerDaGas ? a.feePerDaGas : b.feePerDaGas,
+      a.feePerL2Gas < b.feePerL2Gas ? a.feePerL2Gas : b.feePerL2Gas,
+    );
+  }
+
   static empty() {
     return new GasFees(0, 0);
   }
@@ -138,3 +146,30 @@ export class GasFees {
 export interface BlockMinFeesProvider {
   getCurrentMinFees(): Promise<GasFees>;
 }
+
+/**
+ * Provides the mana min fee the next block this node would build is going to charge.
+ *
+ * Distinct from {@link BlockMinFeesProvider}, which answers the L1-anchored price after the on-chain pending
+ * checkpoint and therefore cannot see the fee a locally proposed in-progress checkpoint already froze.
+ */
+export interface NextBlockMinFeesProvider {
+  /**
+   * The fee the next block will charge, or undefined when the node cannot resolve it right now. For callers that
+   * must not act on a stand-in price, such as evicting transactions the next block could not include.
+   */
+  getNextBlockMinFees(): Promise<GasFees | undefined>;
+}
+
+/** Provides the mana min fees a transaction is held to on its way into this node, over gossip or into the pool. */
+export interface TxAdmissionMinFeesProvider extends NextBlockMinFeesProvider {
+  /**
+   * The fee a transaction must be able to pay to enter this node, over gossip or into the pending pool. The
+   * next-block fee when it resolves, otherwise the L1-forward fee, so admission never runs without a floor: a
+   * zero `maxFeesPerGas` has a zero fee limit, which a fee payer with no balance also covers.
+   */
+  getAdmissionMinFees(): Promise<GasFees>;
+
+  /** The L1-anchored fee projected after the on-chain pending checkpoint, as {@link BlockMinFeesProvider} reports. */
+  getL1ForwardMinFees(): Promise<GasFees>;
+}

package/src/interfaces/aztec-node.ts

@@ -27,7 +27,13 @@ import { z } from 'zod';
 import type { AztecAddress } from '../aztec-address/index.js';
 import { type BlockData, BlockDataSchema } from '../block/block_data.js';
 import { BlockHash } from '../block/block_hash.js';
-import { type BlockParameter, BlockParameterSchema, BlockTagWithoutLatestSchema } from '../block/block_parameter.js';
+import {
+  type ArchiveBlockParameter,
+  ArchiveBlockParameterSchema,
+  type BlockParameter,
+  BlockParameterSchema,
+  BlockTagWithoutLatestSchema,
+} from '../block/block_parameter.js';
 import { type DataInBlock, dataInBlockSchemaFor } from '../block/in_block.js';
 import {
   type CheckpointsQuery,
@@ -169,22 +175,48 @@ export interface AztecNode {
   getPublicDataWitness(referenceBlock: BlockParameter, leafSlot: Fr): Promise<PublicDataWitness | undefined>;
 
   /**
-   * Returns a membership witness for a given block hash in the archive tree.
+   * Returns a membership witness for a given block hash in the archive tree, against the reference block header's
+   * `lastArchive.root`: the archive as it stood before the reference block itself was appended. This is the root a
+   * circuit anchored on that header checks archive membership proofs against.
    *
    * Block hashes are the leaves of the archive tree. Each time a new block is added to the chain,
    * its block hash is appended as a new leaf to the archive tree. This method finds the membership
    * witness (leaf index and sibling path) for a given block hash, which can be used to prove that
    * a specific block exists in the chain's history.
    *
-   * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data
-   * (which contains the root of the archive tree in which we are searching for the block hash).
+   * The reference block must exist. Every `BlockParameter` form selects that reference block, including
+   * `{ archive }`, which identifies the block by its post-block archive root, so the witness is still against the
+   * archive before that block. To prove membership against a supplied archive root itself, use
+   * `getBlockHashMembershipWitnessAtArchive`.
+   *
+   * @param referenceBlock - The block whose header's `lastArchive` the witness is computed against.
    * @param blockHash - The block hash to find in the archive tree.
+   * @returns The witness, or undefined if the block hash is not in that archive.
+   * @throws If the reference block is unknown, or the archive it commits to is not available on this node.
    */
   getBlockHashMembershipWitness(
     referenceBlock: BlockParameter,
     blockHash: BlockHash,
   ): Promise<MembershipWitness<typeof ARCHIVE_HEIGHT> | undefined>;
 
+  /**
+   * Returns a membership witness for a given block hash in the archive tree, against exactly the supplied archive
+   * root. The root is the archive after some block's own hash was appended, so a block is a member of its own archive
+   * and no later block needs to exist.
+   *
+   * Choosing a root does not establish that it is canonical or final: a node that has not yet seen a reorg can serve
+   * a witness against a root that has been reorged away. The caller must pick a root its verifier accepts.
+   *
+   * @param reference - The archive root to prove membership against.
+   * @param blockHash - The block hash to find in the archive tree.
+   * @returns The witness, or undefined if the block hash is not in that archive.
+   * @throws If the node does not know the archive root, or cannot serve the archive state at it.
+   */
+  getBlockHashMembershipWitnessAtArchive(
+    reference: ArchiveBlockParameter,
+    blockHash: BlockHash,
+  ): Promise<MembershipWitness<typeof ARCHIVE_HEIGHT> | undefined>;
+
   /**
    * Returns a membership witness for a given note hash at a given block.
    * @param referenceBlock - The block parameter (block number, block hash, or 'latest') at which to get the data.
@@ -632,6 +664,11 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
     output: MembershipWitness.schemaFor(ARCHIVE_HEIGHT).optional(),
   }),
 
+  getBlockHashMembershipWitnessAtArchive: z.function({
+    input: z.tuple([ArchiveBlockParameterSchema, BlockHash.schema]),
+    output: MembershipWitness.schemaFor(ARCHIVE_HEIGHT).optional(),
+  }),
+
   getNoteHashMembershipWitness: z.function({
     input: z.tuple([BlockParameterSchema, schemas.Fr]),
     output: MembershipWitness.schemaFor(NOTE_HASH_TREE_HEIGHT).optional(),

package/src/interfaces/configs.ts

@@ -137,6 +137,13 @@ export interface SequencerConfig {
    * check. Ignored when p2p is disabled by config.
    */
   minPeersToPropose?: number;
+  /**
+   * Allow starting with fewer block opportunities per checkpoint than `MIN_BLOCKS_FOR_INBOX_CATCHUP`, which on a
+   * real network leaves a proposer that can never clear a mandatory streaming-Inbox backlog and loses all of its
+   * slots. Only sandbox, e2e and benchmark fixtures set this: they run one or two blocks per slot against an Inbox
+   * nobody is filling (for testing only).
+   */
+  allowUnsafeInboxCatchupCapacity?: boolean;
 }
 
 export const SequencerConfigSchema = zodFor<SequencerConfig>()(
@@ -191,6 +198,7 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     skipBroadcastCheckpointProposal: z.boolean().optional(),
     pauseProposingForSlots: z.array(SlotNumberSchema).optional(),
     minPeersToPropose: z.number().nonnegative().optional(),
+    allowUnsafeInboxCatchupCapacity: z.boolean().optional(),
   }),
 );
 

package/src/interfaces/prover-broker.ts

@@ -35,6 +35,8 @@ export interface ProvingJobProducer {
 
 export type ProvingJobFilter = {
   allowList: ProvingRequestType[];
+  /** Whether to acquire new work. Set false to report progress or results while draining. Defaults to true. */
+  allowNewJobs?: boolean;
 };
 
 export type GetProvingJobResponse = {

package/src/interfaces/server_circuit_prover.ts

@@ -182,9 +182,10 @@ export type IVCProofVerificationResult = {
  */
 export interface ClientProtocolCircuitVerifier {
   /**
-   * Verifies the private protocol circuit's proof.
+   * Verifies the private protocol circuit's proof. Rejects, instead of reporting the proof invalid, when the proof
+   * could not be checked (for example, when the proving backend is unavailable).
    * @param tx - The tx to verify the proof of
-   * @returns True if the proof is valid, false otherwise
+   * @returns Whether the proof is valid, with verification timings
    */
   verifyProof(tx: Tx): Promise<IVCProofVerificationResult>;
 

package/src/keys/derivation.ts

@@ -51,12 +51,12 @@ export function deriveMasterFallbackSecretKey(secretKey: Fr): GrumpkinScalar {
 }
 
 export function computePreaddress(publicKeysHash: Fr, partialAddress: Fr) {
-  return poseidon2HashWithSeparator([publicKeysHash, partialAddress], DomainSeparator.CONTRACT_ADDRESS_V2);
+  return poseidon2HashWithSeparator([publicKeysHash, partialAddress], DomainSeparator.CONTRACT_ADDRESS_V3);
 }
 
 export async function computeAddress(publicKeys: PublicKeys, partialAddress: Fr): Promise<AztecAddress> {
   // Given public keys and a partial address, we can compute our address in the following steps.
-  // 1. preaddress = poseidon2([publicKeysHash, partialAddress], DomainSeparator.CONTRACT_ADDRESS_V2);
+  // 1. preaddress = poseidon2([publicKeysHash, partialAddress], DomainSeparator.CONTRACT_ADDRESS_V3);
   // 2. addressPoint = (preaddress * G) + ivpk_m
   // 3. address = addressPoint.x
   const preaddress = await computePreaddress(await publicKeys.hash(), partialAddress);

package/src/messaging/l1_to_l2_message.ts

@@ -95,16 +95,24 @@ export function computeFeeJuiceMessageNullifier(messageHash: Fr, secret: Fr): Pr
   return poseidon2HashWithSeparator([messageHash, secret], DomainSeparator.MESSAGE_NULLIFIER);
 }
 
+/** The outcome of {@link lookUpL1ToL2MessageWitness}. */
+export type L1ToL2MessageWitnessLookup =
+  /** The message is in the tree and, if a nullifier was given, has not been consumed. */
+  | { type: 'found'; witness: [bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>] }
+  /** The message is not in the tree. */
+  | { type: 'missing' }
+  /** A nullifier was given and the message has been consumed. */
+  | { type: 'nullified' };
+
 /**
- * Fetches the membership witness of an L1 to L2 message. When `unsiloedNullifier` is provided, the message is
- * additionally required to be un-nullified.
+ * Looks up the membership witness of an L1 to L2 message in the L1 to L2 message tree at `referenceBlock`.
  */
-export async function getL1ToL2MessageWitness(
+export async function lookUpL1ToL2MessageWitness(
   node: AztecNode,
   messageHash: Fr,
-  unsiloedNullifier?: UnsiloedMessageNullifier,
-  referenceBlock: BlockParameter = 'latest',
-): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>]> {
+  unsiloedNullifier: UnsiloedMessageNullifier | undefined,
+  referenceBlock: BlockParameter,
+): Promise<L1ToL2MessageWitnessLookup> {
   // Both requests are dispatched before awaiting so they run concurrently.
   const l1ToL2ResponsePromise = node.getL1ToL2MessageMembershipWitness(referenceBlock, messageHash);
   const nullifierResponsePromise = unsiloedNullifier
@@ -113,17 +121,37 @@ export async function getL1ToL2MessageWitness(
       )
     : undefined;
 
-  const l1ToL2Response = await l1ToL2ResponsePromise;
+  const [l1ToL2Response, nullifierResponse] = await Promise.all([l1ToL2ResponsePromise, nullifierResponsePromise]);
   if (!l1ToL2Response) {
-    throw new Error(`No L1 to L2 message found for message hash ${messageHash.toString()}`);
+    return { type: 'missing' };
   }
 
-  const nullifierResponse = await nullifierResponsePromise;
   if (nullifierResponse?.[0] !== undefined) {
-    throw new Error(`No non-nullified L1 to L2 message found for message hash ${messageHash.toString()}`);
+    return { type: 'nullified' };
   }
 
-  return l1ToL2Response;
+  return { type: 'found', witness: l1ToL2Response };
+}
+
+/**
+ * Fetches the membership witness of an L1 to L2 message. When `unsiloedNullifier` is provided, the message is
+ * additionally required to be un-nullified.
+ */
+export async function getL1ToL2MessageWitness(
+  node: AztecNode,
+  messageHash: Fr,
+  unsiloedNullifier?: UnsiloedMessageNullifier,
+  referenceBlock: BlockParameter = 'latest',
+): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>]> {
+  const lookup = await lookUpL1ToL2MessageWitness(node, messageHash, unsiloedNullifier, referenceBlock);
+  switch (lookup.type) {
+    case 'missing':
+      throw new Error(`No L1 to L2 message found for message hash ${messageHash.toString()}`);
+    case 'nullified':
+      throw new Error(`No non-nullified L1 to L2 message found for message hash ${messageHash.toString()}`);
+    case 'found':
+      return lookup.witness;
+  }
 }
 
 // This functionality is not on the node because we do not want to pass the node the secret, and give the node the ability to derive a valid nullifer for an L1 to L2 message.

package/src/p2p/block_proposal.ts

@@ -281,6 +281,12 @@ export class BlockProposal extends Gossipable implements Signable {
   static fromBuffer(buf: Buffer | BufferReader): BlockProposal {
     const reader = BufferReader.asReader(buf);
 
+    // Decoding is lenient on purpose, for forward compatibility: trailing bytes are ignored and any non-zero
+    // presence flag reads as present, so a newer version can append fields that older nodes skip over. Rejecting
+    // them would make every wire extension a coordinated upgrade. Lenient decoding does not let one proposal take
+    // several identities, since the P2P message identifier and the signature both cover the signed payload rather
+    // than the raw bytes.
+
     const blockHeader = reader.readObject(BlockHeader);
     const indexWithinCheckpoint = IndexWithinCheckpoint(reader.readNumber());
     const archiveRoot = reader.readObject(Fr);

package/src/p2p/checkpoint_proposal.ts

@@ -308,6 +308,12 @@ export class CheckpointProposal extends Gossipable implements Signable {
   static fromBuffer(buf: Buffer | BufferReader): CheckpointProposal {
     const reader = BufferReader.asReader(buf);
 
+    // Decoding is lenient on purpose, for forward compatibility: trailing bytes are ignored and any non-zero
+    // presence flag reads as present, so a newer version can append fields that older nodes skip over. Rejecting
+    // them would make every wire extension a coordinated upgrade. Lenient decoding does not let one proposal take
+    // several identities, since the P2P message identifier and the signature both cover the signed payload rather
+    // than the raw bytes.
+
     const checkpointHeader = reader.readObject(CheckpointHeader);
     const archive = reader.readObject(Fr);
     const feeAssetPriceModifier = reader.readInt256();

package/src/p2p/gossipable.ts

@@ -26,6 +26,12 @@ export class P2PMessage {
       traceContext = reader.readString();
     }
     const payload = reader.readBuffer();
+    // Reject trailing bytes: padding leaves the same payload but a new message id, so a copy evades
+    // both the seen-message dedup and the duplicate-delivery peer scoring, letting a peer replay one
+    // valid message (e.g. a proposal it cannot forge) as fresh deliveries.
+    if (!reader.isEmpty()) {
+      throw new Error('P2PMessage has trailing bytes after its payload');
+    }
     return new P2PMessage(payload, timestamp, traceContext);
   }