@aztec/stdlib 0.0.1-commit.e558bd1c → 0.0.1-commit.e588bc7e5

package/src/contract/index.ts

@@ -6,8 +6,6 @@ export * from './contract_deployment_data.js';
 export * from './contract_instance.js';
 export * from './contract_instance_update.js';
 export * from './private_function.js';
-export * from './private_function_membership_proof.js';
-export * from './utility_function_membership_proof.js';
 export * from './interfaces/index.js';
 export * from './contract_function_dao.js';
 export * from './partial_address.js';

package/src/contract/interfaces/contract_class.ts

@@ -42,79 +42,6 @@ const PrivateFunctionSchema = zodFor<PrivateFunction>()(
   }),
 );
 
-/** Private function definition with executable bytecode. */
-export interface ExecutablePrivateFunction extends PrivateFunction {
-  /** ACIR and Brillig bytecode */
-  bytecode: Buffer;
-}
-
-const ExecutablePrivateFunctionSchema = zodFor<ExecutablePrivateFunction>()(
-  PrivateFunctionSchema.and(z.object({ bytecode: schemas.Buffer })),
-);
-
-/** Utility function definition. */
-export interface UtilityFunction {
-  /** Selector of the function. Calculated as the hash of the method name and parameters. The specification of this is not enforced by the protocol. */
-  selector: FunctionSelector;
-  /** Brillig. */
-  bytecode: Buffer;
-}
-
-const UtilityFunctionSchema = zodFor<UtilityFunction>()(
-  z.object({
-    selector: FunctionSelector.schema,
-    bytecode: schemas.Buffer,
-  }),
-);
-
-/** Sibling paths and sibling commitments for proving membership of a private function within a contract class. */
-export type PrivateFunctionMembershipProof = {
-  artifactMetadataHash: Fr;
-  functionMetadataHash: Fr;
-  utilityFunctionsTreeRoot: Fr;
-  privateFunctionTreeSiblingPath: Fr[];
-  privateFunctionTreeLeafIndex: number;
-  artifactTreeSiblingPath: Fr[];
-  artifactTreeLeafIndex: number;
-};
-
-const PrivateFunctionMembershipProofSchema = zodFor<PrivateFunctionMembershipProof>()(
-  z.object({
-    artifactMetadataHash: schemas.Fr,
-    functionMetadataHash: schemas.Fr,
-    utilityFunctionsTreeRoot: schemas.Fr,
-    privateFunctionTreeSiblingPath: z.array(schemas.Fr),
-    privateFunctionTreeLeafIndex: schemas.Integer,
-    artifactTreeSiblingPath: z.array(schemas.Fr),
-    artifactTreeLeafIndex: schemas.Integer,
-  }),
-);
-
-/** A private function with a membership proof. */
-export type ExecutablePrivateFunctionWithMembershipProof = ExecutablePrivateFunction & PrivateFunctionMembershipProof;
-
-/** Sibling paths and commitments for proving membership of a utility  function within a contract class. */
-export type UtilityFunctionMembershipProof = {
-  artifactMetadataHash: Fr;
-  functionMetadataHash: Fr;
-  privateFunctionsArtifactTreeRoot: Fr;
-  artifactTreeSiblingPath: Fr[];
-  artifactTreeLeafIndex: number;
-};
-
-const UtilityFunctionMembershipProofSchema = zodFor<UtilityFunctionMembershipProof>()(
-  z.object({
-    artifactMetadataHash: schemas.Fr,
-    functionMetadataHash: schemas.Fr,
-    privateFunctionsArtifactTreeRoot: schemas.Fr,
-    artifactTreeSiblingPath: z.array(schemas.Fr),
-    artifactTreeLeafIndex: schemas.Integer,
-  }),
-);
-
-/** A utility function with a membership proof. */
-export type UtilityFunctionWithMembershipProof = UtilityFunction & UtilityFunctionMembershipProof;
-
 export const ContractClassSchema = zodFor<ContractClass>()(
   z.object({
     version: z.literal(VERSION),
@@ -143,11 +70,8 @@ export const ContractClassWithIdSchema = zodFor<ContractClassWithId>()(
   }),
 );
 
-/** A contract class with public bytecode information, and optional private and utility functions. */
-export type ContractClassPublic = {
-  privateFunctions: ExecutablePrivateFunctionWithMembershipProof[];
-  utilityFunctions: UtilityFunctionWithMembershipProof[];
-} & Pick<ContractClassCommitments, 'id' | 'privateFunctionsRoot'> &
+/** A contract class with public bytecode information. */
+export type ContractClassPublic = Pick<ContractClassCommitments, 'id' | 'privateFunctionsRoot'> &
   Omit<ContractClass, 'privateFunctions'>;
 
 export type ContractClassPublicWithCommitment = ContractClassPublic &
@@ -158,8 +82,6 @@ export const ContractClassPublicSchema = zodFor<ContractClassPublic>()(
     .object({
       id: schemas.Fr,
       privateFunctionsRoot: schemas.Fr,
-      privateFunctions: z.array(ExecutablePrivateFunctionSchema.and(PrivateFunctionMembershipProofSchema)),
-      utilityFunctions: z.array(UtilityFunctionSchema.and(UtilityFunctionMembershipProofSchema)),
     })
     .and(ContractClassSchema.omit({ privateFunctions: true })),
 );
@@ -179,8 +101,6 @@ export function contractClassPublicFromPlainObject(obj: any): ContractClassPubli
     version: 1,
     artifactHash: Fr.fromPlainObject(obj.artifactHash),
     privateFunctionsRoot: Fr.fromPlainObject(obj.privateFunctionsRoot),
-    privateFunctions: [],
-    utilityFunctions: [],
     packedBytecode: obj.packedBytecode instanceof Buffer ? obj.packedBytecode : Buffer.from(obj.packedBytecode),
   };
 }

package/src/contract/interfaces/node-info.ts

@@ -19,6 +19,8 @@ export interface NodeInfo {
   l1ContractAddresses: L1ContractAddresses;
   /** Protocol contract addresses */
   protocolContractAddresses: ProtocolContractAddresses;
+  /** Whether the node requires real proofs for transaction submission. */
+  realProofs: boolean;
 }
 
 export const NodeInfoSchema: ZodFor<NodeInfo> = z
@@ -29,5 +31,6 @@ export const NodeInfoSchema: ZodFor<NodeInfo> = z
     enr: z.string().optional(),
     l1ContractAddresses: L1ContractAddressesSchema,
     protocolContractAddresses: ProtocolContractAddressesSchema,
+    realProofs: z.boolean(),
   })
   .transform(obj => ({ enr: undefined, ...obj }));

package/src/contract/private_function.ts

@@ -1,4 +1,4 @@
-import { FUNCTION_TREE_HEIGHT, GeneratorIndex } from '@aztec/constants';
+import { DomainSeparator, FUNCTION_TREE_HEIGHT } from '@aztec/constants';
 import { poseidon2Hash, poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { type MerkleTree, MerkleTreeCalculator } from '@aztec/foundation/trees';
@@ -31,7 +31,7 @@ function computePrivateFunctionLeaves(fns: PrivateFunction[]): Promise<Buffer[]>
 
 /** Returns the leaf for a given private function. */
 export async function computePrivateFunctionLeaf(fn: PrivateFunction): Promise<Buffer> {
-  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], GeneratorIndex.PRIVATE_FUNCTION_LEAF)).toBuffer();
+  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], DomainSeparator.PRIVATE_FUNCTION_LEAF)).toBuffer();
 }
 
 async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator> {

package/src/epoch-helpers/index.ts

@@ -11,6 +11,8 @@ export type L1RollupConstants = {
   epochDuration: number;
   ethereumSlotDuration: number;
   proofSubmissionEpochs: number;
+  targetCommitteeSize: number;
+  rollupManaLimit: number;
 };
 
 export const EmptyL1RollupConstants: L1RollupConstants = {
@@ -20,6 +22,8 @@ export const EmptyL1RollupConstants: L1RollupConstants = {
   slotDuration: 1,
   ethereumSlotDuration: 1,
   proofSubmissionEpochs: 1,
+  targetCommitteeSize: 48,
+  rollupManaLimit: Number.MAX_SAFE_INTEGER,
 };
 
 export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
@@ -30,6 +34,8 @@ export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
     epochDuration: z.number(),
     ethereumSlotDuration: z.number(),
     proofSubmissionEpochs: z.number(),
+    targetCommitteeSize: z.number(),
+    rollupManaLimit: z.number(),
   }),
 );
 
@@ -51,6 +57,25 @@ export function getSlotAtTimestamp(
     : SlotNumber.fromBigInt((ts - constants.l1GenesisTime) / BigInt(constants.slotDuration));
 }
 
+/** Returns the timestamp of the next L1 slot boundary after the given wall-clock time. */
+export function getNextL1SlotTimestamp(
+  nowInSeconds: number,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'ethereumSlotDuration'>,
+): bigint {
+  const now = BigInt(nowInSeconds);
+  const elapsed = now - constants.l1GenesisTime;
+  const currentL1Slot = elapsed / BigInt(constants.ethereumSlotDuration);
+  return constants.l1GenesisTime + (currentL1Slot + 1n) * BigInt(constants.ethereumSlotDuration);
+}
+
+/** Returns the timestamp of the last L1 slot within a given L2 slot. */
+export function getLastL1SlotTimestampForL2Slot(
+  slot: SlotNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): bigint {
+  return getTimestampForSlot(slot, constants) + BigInt(constants.slotDuration - constants.ethereumSlotDuration);
+}
+
 /** Returns the L2 slot number at the next L1 block based on the current timestamp. */
 export function getSlotAtNextL1Block(
   currentL1Timestamp: bigint,
@@ -137,6 +162,11 @@ export function getProofSubmissionDeadlineTimestamp(
   return getTimestampForSlot(deadlineSlot, constants);
 }
 
+/** Computes the quorum size required for a committee (⌊2n/3⌋ + 1). */
+export function computeQuorum(committeeSize: number): number {
+  return Math.floor((committeeSize * 2) / 3) + 1;
+}
+
 /** Returns the timestamp to start building a block for a given L2 slot. Computed as the start timestamp of the slot minus one L1 slot duration. */
 export function getSlotStartBuildTimestamp(
   slotNumber: SlotNumber,

package/src/file-store/factory.ts

@@ -1,7 +1,7 @@
 import { type Logger, createLogger } from '@aztec/foundation/log';
 
 import { GoogleCloudFileStore } from './gcs.js';
-import { HttpFileStore } from './http.js';
+import { HttpFileStore, type HttpFileStoreOptions } from './http.js';
 import type { FileStore, ReadOnlyFileStore } from './interface.js';
 import { LocalFileStore } from './local.js';
 import { S3FileStore } from './s3.js';
@@ -59,17 +59,26 @@ export async function createFileStore(
   }
 }
 
-export async function createReadOnlyFileStore(config: string, logger?: Logger): Promise<ReadOnlyFileStore>;
-export async function createReadOnlyFileStore(config: undefined, logger?: Logger): Promise<undefined>;
+export async function createReadOnlyFileStore(
+  config: string,
+  logger?: Logger,
+  options?: HttpFileStoreOptions,
+): Promise<ReadOnlyFileStore>;
+export async function createReadOnlyFileStore(
+  config: undefined,
+  logger?: Logger,
+  options?: HttpFileStoreOptions,
+): Promise<undefined>;
 export async function createReadOnlyFileStore(
   config: string | undefined,
   logger = createLogger('stdlib:file-store'),
+  options?: HttpFileStoreOptions,
 ): Promise<ReadOnlyFileStore | undefined> {
   if (config === undefined) {
     return undefined;
   } else if (config.startsWith('http://') || config.startsWith('https://')) {
     logger.info(`Creating read-only HTTP file store at ${config}`);
-    return new HttpFileStore(config, logger);
+    return new HttpFileStore(config, logger, options);
   } else {
     return await createFileStore(config, logger);
   }

package/src/file-store/http.ts

@@ -10,6 +10,14 @@ import { pipeline } from 'stream/promises';
 
 import type { ReadOnlyFileStore } from './interface.js';
 
+/** Options for configuring HttpFileStore behavior. */
+export interface HttpFileStoreOptions {
+  /** Retry backoff intervals in seconds. Empty array disables retries. Default: [1, 1, 3]. */
+  retryBackoff?: number[];
+  /** Request timeout in milliseconds. Default: no timeout (axios default). */
+  timeoutMs?: number;
+}
+
 export class HttpFileStore implements ReadOnlyFileStore {
   private readonly axiosInstance: AxiosInstance;
   private readonly fetch: <T>(config: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
@@ -17,17 +25,28 @@ export class HttpFileStore implements ReadOnlyFileStore {
   constructor(
     private readonly baseUrl: string,
     private readonly log: Logger = createLogger('stdlib:http-file-store'),
+    options?: HttpFileStoreOptions,
   ) {
-    this.axiosInstance = axios.create();
-    this.fetch = async <T>(config: AxiosRequestConfig) => {
-      return await retry(
-        () => this.axiosInstance.request<T>(config),
-        `Fetching ${config.url}`,
-        makeBackoff([1, 1, 3]),
-        this.log,
-        /*failSilently=*/ true,
-      );
-    };
+    this.axiosInstance = axios.create({
+      ...(options?.timeoutMs !== undefined && { timeout: options.timeoutMs }),
+    });
+
+    const retryBackoff = options?.retryBackoff ?? [1, 1, 3];
+    if (retryBackoff.length > 0) {
+      this.fetch = async <T>(config: AxiosRequestConfig) => {
+        return await retry(
+          () => this.axiosInstance.request<T>(config),
+          `Fetching ${config.url}`,
+          makeBackoff(retryBackoff),
+          this.log,
+          /*failSilently=*/ true,
+        );
+      };
+    } else {
+      this.fetch = async <T>(config: AxiosRequestConfig) => {
+        return await this.axiosInstance.request<T>(config);
+      };
+    }
   }
 
   public async read(pathOrUrl: string): Promise<Buffer> {

package/src/file-store/index.ts

@@ -1,2 +1,3 @@
 export * from './interface.js';
 export * from './factory.js';
+export { type HttpFileStoreOptions } from './http.js';

package/src/file-store/local.ts

@@ -1,15 +1,21 @@
 import { access, mkdir, readFile, writeFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
+import { promisify } from 'util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
 
-import type { FileStore } from './interface.js';
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
 
 export class LocalFileStore implements FileStore {
   constructor(private readonly basePath: string) {}
 
-  public async save(path: string, data: Buffer): Promise<string> {
+  public async save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string> {
     const fullPath = this.getFullPath(path);
     await mkdir(dirname(fullPath), { recursive: true });
-    await writeFile(fullPath, data);
+    const toWrite = opts?.compress ? await gzip(data) : data;
+    await writeFile(fullPath, toWrite);
     return `file://${fullPath}`;
   }
 
@@ -18,9 +24,13 @@ export class LocalFileStore implements FileStore {
     return this.save(destPath, data);
   }
 
-  public read(pathOrUrlStr: string): Promise<Buffer> {
+  public async read(pathOrUrlStr: string): Promise<Buffer> {
     const fullPath = this.getFullPath(pathOrUrlStr);
-    return readFile(fullPath);
+    const data = await readFile(fullPath);
+    if (data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b) {
+      return await gunzip(data);
+    }
+    return data;
   }
 
   public async download(pathOrUrlStr: string, destPath: string): Promise<void> {

package/src/file-store/s3.ts

@@ -13,10 +13,14 @@ import { tmpdir } from 'os';
 import { basename, dirname, join } from 'path';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
-import { createGzip } from 'zlib';
+import { promisify } from 'util';
+import { createGzip, gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
 
 import type { FileStore, FileStoreSaveOptions } from './interface.js';
 
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
 function normalizeBasePath(path: string): string {
   return path?.replace(/^\/+|\/+$/g, '') ?? '';
 }
@@ -52,7 +56,7 @@ export class S3FileStore implements FileStore {
     const key = this.getFullPath(path);
     const shouldCompress = !!opts.compress;
 
-    const body = shouldCompress ? (await import('zlib')).gzipSync(data) : data;
+    const body = shouldCompress ? await gzip(data) : data;
     const contentLength = body.length;
     const contentType = this.detectContentType(key, shouldCompress);
     const put = new PutObjectCommand({
@@ -60,6 +64,7 @@ export class S3FileStore implements FileStore {
       Key: key,
       Body: body,
       ContentType: contentType,
+      ContentEncoding: shouldCompress ? 'gzip' : undefined,
       CacheControl: opts.metadata?.['Cache-control'],
       Metadata: this.extractUserMetadata(opts.metadata),
       ContentLength: contentLength,
@@ -134,7 +139,11 @@ export class S3FileStore implements FileStore {
     for await (const chunk of stream) {
       chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
     }
-    return Buffer.concat(chunks);
+    const buffer = Buffer.concat(chunks);
+    if (out.ContentEncoding === 'gzip') {
+      return await gunzip(buffer);
+    }
+    return buffer;
   }
 
   public async download(pathOrUrlStr: string, destPath: string): Promise<void> {

package/src/gas/README.md

@@ -0,0 +1,123 @@
+# Aztec Gas and Fee Model
+
+The minimum fee per mana and its components are computed on L1 in
+`l1-contracts/src/core/libraries/rollup/FeeLib.sol`. This document describes the
+formulas, the oracle lag/lifetime mechanism, and the TypeScript types in this directory.
+
+## Mana
+
+Aztec uses **mana** as its unit of work (analogous to Ethereum gas). Transactions consume
+mana in two dimensions: **DA** (data availability) and **L2** (execution). The total fee
+is `gasUsed * feePerMana` summed across both dimensions.
+
+## Fee Components
+
+The minimum fee per mana has four components:
+
+### Sequencer Cost
+
+L1 cost to propose a checkpoint (calldata gas + blob data), amortized over `manaTarget`:
+
+```
+sequencerCost = ((L1_GAS_PER_CHECKPOINT_PROPOSED * baseFee)
+              + (BLOBS_PER_CHECKPOINT * BLOB_GAS_PER_BLOB * blobFee))
+              / manaTarget
+```
+
+### Prover Cost
+
+L1 cost to verify an epoch proof, amortized over epoch duration and `manaTarget`, plus a
+governance-set proving cost that compensates for off-chain proof generation:
+
+```
+proverCost = (L1_GAS_PER_EPOCH_VERIFIED * baseFee / epochDuration) / manaTarget
+           + provingCostPerMana
+```
+
+### Congestion Cost
+
+An exponential surcharge when the network is congested (inspired by EIP-1559; the
+implementation uses the `fakeExponential` Taylor series approximation from EIP-4844):
+
+```
+baseCost          = sequencerCost + proverCost
+congestionCost    = baseCost * congestionMultiplier / MINIMUM_CONGESTION_MULTIPLIER - baseCost
+```
+
+When there is no congestion the multiplier equals `MINIMUM_CONGESTION_MULTIPLIER` (1e9)
+and congestion cost is zero.
+
+### Congestion Multiplier
+
+```
+excessMana          = max(0, prevExcessMana + prevManaUsed - manaTarget)
+congestionMultiplier = fakeExponential(MINIMUM_CONGESTION_MULTIPLIER, excessMana, denominator)
+```
+
+Each additional `manaTarget` of excess mana increases the multiplier by ~12.5%.
+
+### Total
+
+```
+minFeePerMana = sequencerCost + proverCost + congestionCost
+```
+
+## L1 Gas Oracle: Lag and Lifetime
+
+The oracle feeds Ethereum's `baseFee` and `blobFee` into the fee model using a two-phase
+(`pre` / `post`) system that smooths out L1 fee volatility.
+
+- **LAG = 2 slots** — when new L1 fees are observed, they activate `LAG` slots later
+  (`slotOfChange = currentSlot + LAG`). This gives mempool transactions time to land
+  before fees change.
+- **LIFETIME = 5 slots** — after an oracle update, the next update is rejected until
+  `slotOfChange + (LIFETIME - LAG)` = 3 more slots have passed. This rate-limits how
+  frequently L1 fee data can change.
+
+Fee resolution at a given timestamp:
+
+```
+if slot < slotOfChange  →  use pre  (old fees)
+else                    →  use post (new fees)
+```
+
+**Net effect**: L1 fee changes reach L2 with a 2-slot delay and can update at most once
+every 5 slots.
+
+## Fee Asset Price
+
+Fees are computed in ETH internally but converted to the fee asset (Fee Juice) via
+`ethPerFeeAsset` (1e12 precision). The price updates at most ±1% (±100 bps) per
+checkpoint:
+
+```
+newPrice = currentPrice * (10000 + modifierBps) / 10000
+```
+
+## Maximum Fee Change Rate
+
+| Component              | Bound                                                   |
+| ---------------------- | ------------------------------------------------------- |
+| L1 base fee / blob fee | At most once every 5 slots (oracle LIFETIME)            |
+| Fee asset price        | ±1% per checkpoint                                      |
+| Congestion multiplier  | Depends on excess mana accumulation/drain per checkpoint |
+| Sequencer/prover costs | Scale linearly with L1 fees                             |
+
+## Key Constants
+
+| Constant                       | Value          |
+| ------------------------------ | -------------- |
+| `L1_GAS_PER_CHECKPOINT_PROPOSED` | 300,000      |
+| `L1_GAS_PER_EPOCH_VERIFIED`     | 3,600,000    |
+| `BLOBS_PER_CHECKPOINT`          | 3            |
+| `BLOB_GAS_PER_BLOB`             | 2^17         |
+| `MINIMUM_CONGESTION_MULTIPLIER` | 1e9          |
+| `LAG`                           | 2 slots      |
+| `LIFETIME`                      | 5 slots      |
+
+## TypeScript Types
+
+- **`Gas`** — mana quantity in two dimensions (`daGas`, `l2Gas`).
+- **`GasFees`** — per-unit price in each dimension (`feePerDaGas`, `feePerL2Gas`).
+- **`GasSettings`** — sender-chosen fee parameters: gas limits, teardown limits, max fees, priority fees.
+- **`GasUsed`** — actual consumption after execution. Note: `billedGas` uses the teardown gas *limit*, not actual usage.

package/src/gas/gas_fees.ts

@@ -56,8 +56,14 @@ export class GasFees {
       return this.clone();
     } else if (typeof scalar === 'bigint') {
       return new GasFees(this.feePerDaGas * scalar, this.feePerL2Gas * scalar);
+    } else if (Number.isInteger(scalar)) {
+      const s = BigInt(scalar);
+      return new GasFees(this.feePerDaGas * s, this.feePerL2Gas * s);
     } else {
-      return new GasFees(Number(this.feePerDaGas) * scalar, Number(this.feePerL2Gas) * scalar);
+      return new GasFees(
+        BigInt(Math.ceil(Number(this.feePerDaGas) * scalar)),
+        BigInt(Math.ceil(Number(this.feePerL2Gas) * scalar)),
+      );
     }
   }