@aztec-labs/protocol-contracts 6.0.0-nightly.20260829

package/src/class-registry/lazy.ts

@@ -0,0 +1,31 @@
+import { type ContractArtifact, loadContractArtifact } from '@aztec-labs/stdlib/abi';
+
+import { makeProtocolContract } from '../make_protocol_contract.js';
+import type { ProtocolContract } from '../protocol_contract.js';
+
+export * from './contract_class_published_event.js';
+
+let protocolContract: ProtocolContract;
+let protocolContractArtifact: ContractArtifact;
+
+export async function getContractClassRegistryArtifact(): Promise<ContractArtifact> {
+  if (!protocolContractArtifact) {
+    // Cannot assert this import as it's incompatible with bundlers like vite
+    // https://github.com/vitejs/vite/issues/19095#issuecomment-2566074352
+    // Even if now supported by all major browsers, the MIME type is replaced with
+    // "text/javascript"
+    // In the meantime, this lazy import is INCOMPATIBLE WITH NODEJS
+    const { default: contractClassRegistryJson } = await import('../../artifacts/ContractClassRegistry.json');
+    protocolContractArtifact = loadContractArtifact(contractClassRegistryJson);
+  }
+  return protocolContractArtifact;
+}
+
+/** Returns the canonical deployment of the auth registry. */
+export async function getCanonicalClassRegistry(): Promise<ProtocolContract> {
+  if (!protocolContract) {
+    const contractClassRegistryArtifact = await getContractClassRegistryArtifact();
+    protocolContract = makeProtocolContract('ContractClassRegistry', contractClassRegistryArtifact);
+  }
+  return protocolContract;
+}

package/src/fee-juice/index.ts

@@ -0,0 +1,37 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { loadContractArtifact } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { computePublicDataTreeLeafSlot, deriveStorageSlotInMap } from '@aztec-labs/stdlib/hash';
+import type { NoirCompiledContract } from '@aztec-labs/stdlib/noir';
+
+import FeeJuiceJson from '../../artifacts/FeeJuice.json' with { type: 'json' };
+import { makeProtocolContract } from '../make_protocol_contract.js';
+import type { ProtocolContract } from '../protocol_contract.js';
+import { ProtocolContractAddress } from '../protocol_contract_data.js';
+
+export const FeeJuiceArtifact = loadContractArtifact(FeeJuiceJson as NoirCompiledContract);
+
+let protocolContract: ProtocolContract;
+
+/** Returns the canonical deployment of the contract. */
+export function getCanonicalFeeJuice(): Promise<ProtocolContract> {
+  if (!protocolContract) {
+    protocolContract = makeProtocolContract('FeeJuice', FeeJuiceArtifact);
+  }
+  return Promise.resolve(protocolContract);
+}
+
+/**
+ * Computes the storage slot within the Fee Juice contract for the balance of the fee payer.
+ */
+export function computeFeePayerBalanceStorageSlot(feePayer: AztecAddress): Promise<Fr> {
+  return deriveStorageSlotInMap(FeeJuiceArtifact.storageLayout.balances.slot, feePayer);
+}
+
+/**
+ * Computes the leaf slot in the public data tree for the balance of the fee payer in the Fee Juice.
+ */
+export async function computeFeePayerBalanceLeafSlot(feePayer: AztecAddress): Promise<Fr> {
+  const balanceSlot = await computeFeePayerBalanceStorageSlot(feePayer);
+  return computePublicDataTreeLeafSlot(ProtocolContractAddress.FeeJuice, balanceSlot);
+}

package/src/fee-juice/lazy.ts

@@ -0,0 +1,29 @@
+import { type ContractArtifact, loadContractArtifact } from '@aztec-labs/stdlib/abi';
+
+import { makeProtocolContract } from '../make_protocol_contract.js';
+import type { ProtocolContract } from '../protocol_contract.js';
+
+let protocolContract: ProtocolContract;
+let protocolContractArtifact: ContractArtifact;
+
+export async function getFeeJuiceArtifact(): Promise<ContractArtifact> {
+  if (!protocolContractArtifact) {
+    // Cannot assert this import as it's incompatible with bundlers like vite
+    // https://github.com/vitejs/vite/issues/19095#issuecomment-2566074352
+    // Even if now supported by all major browsers, the MIME type is replaced with
+    // "text/javascript"
+    // In the meantime, this lazy import is INCOMPATIBLE WITH NODEJS
+    const { default: feeJuiceJson } = await import('../../artifacts/FeeJuice.json');
+    protocolContractArtifact = loadContractArtifact(feeJuiceJson);
+  }
+  return protocolContractArtifact;
+}
+
+/** Returns the canonical deployment of the auth registry. */
+export async function getCanonicalFeeJuice(): Promise<ProtocolContract> {
+  if (!protocolContract) {
+    const feeJuiceArtifact = await getFeeJuiceArtifact();
+    protocolContract = makeProtocolContract('FeeJuice', feeJuiceArtifact);
+  }
+  return protocolContract;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './protocol_contract.js';
+export * from './protocol_contract_data.js';

package/src/instance-registry/__snapshots__/README.md

@@ -0,0 +1,9 @@
+# How to update these snapshots
+
+(You probably need to have done a `./bootstrap.sh` at some point)
+
+From the root:
+
+`cd yarn-project/protocol-contracts`
+
+`yarn test -u`

package/src/instance-registry/contract_instance_published_event.ts

@@ -0,0 +1,74 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader } from '@aztec-labs/foundation/serialize';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ContractInstanceWithAddress } from '@aztec-labs/stdlib/contract';
+import { PublicKeys } from '@aztec-labs/stdlib/keys';
+import type { PrivateLog } from '@aztec-labs/stdlib/logs';
+
+import { CONTRACT_INSTANCE_PUBLISHED_EVENT_TAG } from '../protocol_contract_data.js';
+
+/** Event emitted from the ContractInstanceRegistry. */
+export class ContractInstancePublishedEvent {
+  constructor(
+    public readonly address: AztecAddress,
+    public readonly version: number,
+    public readonly salt: Fr,
+    public readonly contractClassId: Fr,
+    public readonly initializationHash: Fr,
+    public readonly immutablesHash: Fr,
+    public readonly publicKeys: PublicKeys,
+    public readonly deployer: AztecAddress,
+  ) {}
+
+  static isContractInstancePublishedEvent(log: PrivateLog) {
+    return log.fields[0].equals(CONTRACT_INSTANCE_PUBLISHED_EVENT_TAG);
+  }
+
+  static fromLog(log: PrivateLog) {
+    const bufferWithoutTag = log.toBuffer().subarray(32);
+    const reader = new BufferReader(bufferWithoutTag);
+    const address = reader.readObject(AztecAddress);
+    const version = reader.readObject(Fr).toNumber();
+    const salt = reader.readObject(Fr);
+    const contractClassId = reader.readObject(Fr);
+    const initializationHash = reader.readObject(Fr);
+    const immutablesHash = reader.readObject(Fr);
+    const publicKeys = reader.readObject(PublicKeys);
+    const deployer = reader.readObject(AztecAddress);
+
+    return new ContractInstancePublishedEvent(
+      address,
+      version,
+      salt,
+      contractClassId,
+      initializationHash,
+      immutablesHash,
+      publicKeys,
+      deployer,
+    );
+  }
+
+  toContractInstance(): ContractInstanceWithAddress {
+    if (this.version !== 2) {
+      throw new Error(`Unexpected contract instance version ${this.version}`);
+    }
+
+    return {
+      address: this.address,
+      version: this.version,
+      currentContractClassId: this.contractClassId,
+      originalContractClassId: this.contractClassId,
+      initializationHash: this.initializationHash,
+      immutablesHash: this.immutablesHash,
+      publicKeys: this.publicKeys,
+      salt: this.salt,
+      deployer: this.deployer,
+    };
+  }
+
+  public static extractContractInstanceEvents(logs: PrivateLog[]): ContractInstancePublishedEvent[] {
+    return logs
+      .filter(log => ContractInstancePublishedEvent.isContractInstancePublishedEvent(log))
+      .map(log => ContractInstancePublishedEvent.fromLog(log));
+  }
+}

package/src/instance-registry/contract_instance_updated_event.ts

@@ -0,0 +1,44 @@
+import { CONTRACT_INSTANCE_UPDATED_MAGIC_VALUE } from '@aztec-labs/constants';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { FieldReader } from '@aztec-labs/foundation/serialize';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type { ContractInstanceUpdateWithAddress } from '@aztec-labs/stdlib/contract';
+import type { PublicLog } from '@aztec-labs/stdlib/logs';
+import type { UInt64 } from '@aztec-labs/stdlib/types';
+
+import { ProtocolContractAddress } from '../protocol_contract_data.js';
+
+/** Event emitted from the ContractInstanceRegistry. */
+export class ContractInstanceUpdatedEvent {
+  constructor(
+    public readonly address: AztecAddress,
+    public readonly prevContractClassId: Fr,
+    public readonly newContractClassId: Fr,
+    public readonly timestampOfChange: UInt64,
+  ) {}
+
+  static isContractInstanceUpdatedEvent(log: PublicLog) {
+    return (
+      log.contractAddress.equals(ProtocolContractAddress.ContractInstanceRegistry) &&
+      log.fields[0].toBigInt() === CONTRACT_INSTANCE_UPDATED_MAGIC_VALUE
+    );
+  }
+
+  static fromLog(log: PublicLog) {
+    const reader = new FieldReader(log.fields.slice(1) /* remove tag */);
+    const address = reader.readObject(AztecAddress);
+    const prevContractClassId = reader.readField();
+    const newContractClassId = reader.readField();
+    const timestampOfChange = reader.readField().toBigInt();
+    return new ContractInstanceUpdatedEvent(address, prevContractClassId, newContractClassId, timestampOfChange);
+  }
+
+  toContractInstanceUpdate(): ContractInstanceUpdateWithAddress {
+    return {
+      address: this.address,
+      prevContractClassId: this.prevContractClassId,
+      newContractClassId: this.newContractClassId,
+      timestampOfChange: this.timestampOfChange,
+    };
+  }
+}

package/src/instance-registry/index.ts

@@ -0,0 +1,23 @@
+import { loadContractArtifact } from '@aztec-labs/stdlib/abi';
+import type { NoirCompiledContract } from '@aztec-labs/stdlib/noir';
+
+import ContractInstanceRegistryJson from '../../artifacts/ContractInstanceRegistry.json' with { type: 'json' };
+import { makeProtocolContract } from '../make_protocol_contract.js';
+import type { ProtocolContract } from '../protocol_contract.js';
+
+export * from './contract_instance_published_event.js';
+export * from './contract_instance_updated_event.js';
+
+export const ContractInstanceRegistryArtifact = loadContractArtifact(
+  ContractInstanceRegistryJson as NoirCompiledContract,
+);
+
+let protocolContract: ProtocolContract;
+
+/** Returns the canonical deployment of the contract. */
+export function getCanonicalInstanceRegistry(): Promise<ProtocolContract> {
+  if (!protocolContract) {
+    protocolContract = makeProtocolContract('ContractInstanceRegistry', ContractInstanceRegistryArtifact);
+  }
+  return Promise.resolve(protocolContract);
+}

package/src/instance-registry/lazy.ts

@@ -0,0 +1,32 @@
+import { type ContractArtifact, loadContractArtifact } from '@aztec-labs/stdlib/abi';
+
+import { makeProtocolContract } from '../make_protocol_contract.js';
+import type { ProtocolContract } from '../protocol_contract.js';
+
+export * from './contract_instance_published_event.js';
+export * from './contract_instance_updated_event.js';
+
+let protocolContract: ProtocolContract;
+let protocolContractArtifact: ContractArtifact;
+
+export async function getContractInstanceRegistryArtifact(): Promise<ContractArtifact> {
+  if (!protocolContractArtifact) {
+    // Cannot assert this import as it's incompatible with bundlers like vite
+    // https://github.com/vitejs/vite/issues/19095#issuecomment-2566074352
+    // Even if now supported by all major browsers, the MIME type is replaced with
+    // "text/javascript"
+    // In the meantime, this lazy import is INCOMPATIBLE WITH NODEJS
+    const { default: contractInstanceRegistryJson } = await import('../../artifacts/ContractInstanceRegistry.json');
+    protocolContractArtifact = loadContractArtifact(contractInstanceRegistryJson);
+  }
+  return protocolContractArtifact;
+}
+
+/** Returns the canonical deployment of the auth registry. */
+export async function getCanonicalInstanceRegistry(): Promise<ProtocolContract> {
+  if (!protocolContract) {
+    const contractInstanceRegistryArtifact = await getContractInstanceRegistryArtifact();
+    protocolContract = makeProtocolContract('ContractInstanceRegistry', contractInstanceRegistryArtifact);
+  }
+  return protocolContract;
+}

package/src/make_protocol_contract.ts

@@ -0,0 +1,50 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { ContractArtifact } from '@aztec-labs/stdlib/abi';
+import { PublicKeys } from '@aztec-labs/stdlib/keys';
+
+import type { ProtocolContract } from './protocol_contract.js';
+import {
+  ProtocolContractAddress,
+  ProtocolContractClassId,
+  ProtocolContractClassIdPreimage,
+  ProtocolContractInitializationHash,
+  type ProtocolContractName,
+  ProtocolContractPrivateFunctions,
+  ProtocolContractSalt,
+} from './protocol_contract_data.js';
+
+/**
+ * Reconstructs a ProtocolContract from precomputed data without performing any hash computations.
+ * Internal to the protocol-contracts package — not part of the public API.
+ */
+export function makeProtocolContract(name: ProtocolContractName, artifact: ContractArtifact): ProtocolContract {
+  const address = ProtocolContractAddress[name];
+  const salt = ProtocolContractSalt[name];
+  const classId = ProtocolContractClassId[name];
+  const { artifactHash, privateFunctionsRoot, publicBytecodeCommitment } = ProtocolContractClassIdPreimage[name];
+  const initializationHash = ProtocolContractInitializationHash[name];
+
+  const contractClass = {
+    id: classId,
+    version: 1 as const,
+    artifactHash,
+    privateFunctionsRoot,
+    publicBytecodeCommitment,
+    packedBytecode: artifact.functions.find(f => f.name === 'public_dispatch')?.bytecode ?? Buffer.alloc(0),
+    privateFunctions: ProtocolContractPrivateFunctions[name],
+  };
+
+  const instance = {
+    version: 2 as const,
+    currentContractClassId: classId,
+    originalContractClassId: classId,
+    initializationHash,
+    immutablesHash: Fr.ZERO, // Protocol Contracts Have No Immutables
+    publicKeys: PublicKeys.default(),
+    salt,
+    deployer: address,
+    address,
+  };
+
+  return { instance, contractClass, artifact, address };
+}

package/src/protocol_contract.ts

@@ -0,0 +1,35 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { ContractArtifact } from '@aztec-labs/stdlib/abi';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import type {
+  ContractClassIdPreimage,
+  ContractClassWithId,
+  ContractInstanceWithAddress,
+} from '@aztec-labs/stdlib/contract';
+
+import { ProtocolContractAddress, ProtocolContractClassId } from './protocol_contract_data.js';
+
+/** Represents a canonical contract in the protocol. */
+export interface ProtocolContract {
+  /** Canonical deployed instance. */
+  instance: ContractInstanceWithAddress;
+  /** Contract class of this contract. */
+  contractClass: ContractClassWithId & ContractClassIdPreimage;
+  /** Complete contract artifact. */
+  artifact: ContractArtifact;
+  /** Deployment address for the canonical instance.  */
+  address: AztecAddress;
+}
+
+export function isProtocolContract(address: AztecAddress) {
+  return Object.values(ProtocolContractAddress).some(a => a.equals(address));
+}
+
+const protocolContractClassIds = new Set(Object.values(ProtocolContractClassId).map(id => id.toString()));
+
+/** Returns whether the given contract class id belongs to a bundled protocol contract. */
+export function isProtocolContractClass(classId: Fr): boolean {
+  return protocolContractClassIds.has(classId.toString());
+}
+
+export { type ProtocolContractsProvider } from './provider/protocol_contracts_provider.js';

package/src/protocol_contract_data.ts

@@ -0,0 +1,101 @@
+
+    // GENERATED FILE - DO NOT EDIT. RUN `yarn generate` or `yarn generate:data`
+    import { Fr } from '@aztec-labs/foundation/curves/bn254';
+    import { FunctionSelector } from '@aztec-labs/stdlib/abi';
+    import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+    import { ProtocolContracts } from '@aztec-labs/stdlib/tx';
+
+    
+    export const protocolContractNames = [
+      'ContractInstanceRegistry',
+'ContractClassRegistry',
+'FeeJuice'
+    ] as const;
+
+    export type ProtocolContractName = typeof protocolContractNames[number];
+  
+
+    
+    export const ProtocolContractSalt: Record<ProtocolContractName, Fr> = {
+      ContractInstanceRegistry: new Fr(1),
+ContractClassRegistry: new Fr(1),
+FeeJuice: new Fr(1)
+    };
+  
+
+    
+    export const ProtocolContractAddress: Record<ProtocolContractName, AztecAddress> = {
+      ContractInstanceRegistry: AztecAddress.fromBigIntUnsafe(2n),
+ContractClassRegistry: AztecAddress.fromBigIntUnsafe(1n),
+FeeJuice: AztecAddress.fromBigIntUnsafe(3n)
+    };
+  
+
+    
+    export const ProtocolContractDerivedAddress = {
+      ContractInstanceRegistry: AztecAddress.fromStringUnsafe('0x2d822c19c286cf1b249431a6c5ffb1864f627b469a6386574da83f44800d6c17'),
+ContractClassRegistry: AztecAddress.fromStringUnsafe('0x1bbb52d2b4ac8c634f4b5026f2228580627c918895c369495f71caae13d996fe'),
+FeeJuice: AztecAddress.fromStringUnsafe('0x1df1b0934b368c073f61d3cdb2de064766cd44ea4429f7920959f4a7758ef208')
+    };
+  
+
+    
+    export const ProtocolContractClassId: Record<ProtocolContractName, Fr> = {
+      ContractInstanceRegistry: Fr.fromString('0x28d8b9fff43315ce084cbd127532c8a1bb562fe1f147aee518c2c8ca822dcd4a'),
+ContractClassRegistry: Fr.fromString('0x0026d0944a8b8204b840c37cf238b145bdd6b1af9daf59eeb5e689022a708e5e'),
+FeeJuice: Fr.fromString('0x013e4ae6015db998dabfe78684c8b9e2fe413d316b36395091f53b9ea40f15ed')
+    };
+
+    export const ProtocolContractClassIdPreimage: Record<ProtocolContractName, { artifactHash: Fr; privateFunctionsRoot: Fr; publicBytecodeCommitment: Fr }> = {
+      ContractInstanceRegistry: {
+        artifactHash: Fr.fromString('0x19835337f0aee2e9042f3a0ae0d334bdb39ecb22794b40d2670d26b2ca72b98f'),
+        privateFunctionsRoot: Fr.fromString('0x05bb912d9d2871492d76c610472544d8219df70aa874768f9667e99861d7971f'),
+        publicBytecodeCommitment: Fr.fromString('0x1fd8380bb220e7d13db681da7e62c93b03add6754895a84c51d13fcde03e8d25'),
+      },
+ContractClassRegistry: {
+        artifactHash: Fr.fromString('0x0d0ef0a61d9c829c306eee702aa7914299d58e7d3fc9f11d5aebd38c838fa1d0'),
+        privateFunctionsRoot: Fr.fromString('0x119c77be6d76c221642b63a337d94bf7b6ed8f872927ef3645c7e6b5002baa34'),
+        publicBytecodeCommitment: Fr.fromString('0x0ce4c618c3ed7f3a20410e618c06bb701e150af7fe28a3e92f68e7733809f33e'),
+      },
+FeeJuice: {
+        artifactHash: Fr.fromString('0x100f61126a468cb2c4b5bad99a769256f7944830ea7b396225975a8628bd37a6'),
+        privateFunctionsRoot: Fr.fromString('0x1c4bf54a4a33e3b9eae6f816dfc81e128d76d2646807a5443598c8adbd47f81f'),
+        publicBytecodeCommitment: Fr.fromString('0x2968eb109f722c701d59d171c32d32b79199841f0044d6bbd77dc43bd513a770'),
+      }
+    };
+
+    export const ProtocolContractInitializationHash: Record<ProtocolContractName, Fr> = {
+      ContractInstanceRegistry: Fr.fromString('0x0000000000000000000000000000000000000000000000000000000000000000'),
+ContractClassRegistry: Fr.fromString('0x0000000000000000000000000000000000000000000000000000000000000000'),
+FeeJuice: Fr.fromString('0x0000000000000000000000000000000000000000000000000000000000000000')
+    };
+
+    export const ProtocolContractPrivateFunctions: Record<ProtocolContractName, { selector: FunctionSelector; vkHash: Fr }[]> = {
+      ContractInstanceRegistry: [{ selector: FunctionSelector.fromField(Fr.fromString('0x0000000000000000000000000000000000000000000000000000000077cff62f')), vkHash: Fr.fromString('0x19172c0acecd517dd8995c2e36178ca2aa16cbe001c3606d8cd848776ab80d23') }],
+ContractClassRegistry: [{ selector: FunctionSelector.fromField(Fr.fromString('0x000000000000000000000000000000000000000000000000000000006934ed0d')), vkHash: Fr.fromString('0x1241fdbf61631c59b977bb6a520cafe3169604036705b8680dea59f05fb71251') }],
+FeeJuice: [{ selector: FunctionSelector.fromField(Fr.fromString('0x00000000000000000000000000000000000000000000000000000000cbe67243')), vkHash: Fr.fromString('0x0bdf2e5c4467f295f8defb436546a7f2e642e7fe75786d0d54aef497b76527a1') }, { selector: FunctionSelector.fromField(Fr.fromString('0x00000000000000000000000000000000000000000000000000000000e8d374b6')), vkHash: Fr.fromString('0x2616a94d2d2981737c31ed7d74b9fd32ddc8376bf436dd60fb2507662b47c6dd') }]
+    };
+  
+
+    
+    export const ProtocolContractsList = new ProtocolContracts([
+      AztecAddress.fromStringUnsafe('0x1bbb52d2b4ac8c634f4b5026f2228580627c918895c369495f71caae13d996fe'),
+AztecAddress.fromStringUnsafe('0x2d822c19c286cf1b249431a6c5ffb1864f627b469a6386574da83f44800d6c17'),
+AztecAddress.fromStringUnsafe('0x1df1b0934b368c073f61d3cdb2de064766cd44ea4429f7920959f4a7758ef208'),
+AztecAddress.fromStringUnsafe('0x0000000000000000000000000000000000000000000000000000000000000000'),
+AztecAddress.fromStringUnsafe('0x0000000000000000000000000000000000000000000000000000000000000000'),
+AztecAddress.fromStringUnsafe('0x0000000000000000000000000000000000000000000000000000000000000000'),
+AztecAddress.fromStringUnsafe('0x0000000000000000000000000000000000000000000000000000000000000000'),
+AztecAddress.fromStringUnsafe('0x0000000000000000000000000000000000000000000000000000000000000000'),
+AztecAddress.fromStringUnsafe('0x0000000000000000000000000000000000000000000000000000000000000000'),
+AztecAddress.fromStringUnsafe('0x0000000000000000000000000000000000000000000000000000000000000000'),
+AztecAddress.fromStringUnsafe('0x0000000000000000000000000000000000000000000000000000000000000000')
+    ]);
+
+    export const protocolContractsHash = Fr.fromString('0x14cec0ae6f31e913c3be04691c6d49c3ec07b3f2d024c9558693ea62fc530bbf');
+  
+
+    
+  export const CONTRACT_INSTANCE_PUBLISHED_EVENT_TAG = Fr.fromHexString('0x1a7e1badb79abdd38c684b3c8306ffe7ecb33c69e3380d9855730aaaa83a21a8');
+  
+  

package/src/provider/bundle.ts

@@ -0,0 +1,21 @@
+import type { ContractArtifact } from '@aztec-labs/stdlib/abi';
+
+import { ContractClassRegistryArtifact } from '../class-registry/index.js';
+import { FeeJuiceArtifact } from '../fee-juice/index.js';
+import { ContractInstanceRegistryArtifact } from '../instance-registry/index.js';
+import { makeProtocolContract } from '../make_protocol_contract.js';
+import type { ProtocolContract } from '../protocol_contract.js';
+import type { ProtocolContractName } from '../protocol_contract_data.js';
+import type { ProtocolContractsProvider } from './protocol_contracts_provider.js';
+
+export const ProtocolContractArtifact: Record<ProtocolContractName, ContractArtifact> = {
+  ContractInstanceRegistry: ContractInstanceRegistryArtifact,
+  ContractClassRegistry: ContractClassRegistryArtifact,
+  FeeJuice: FeeJuiceArtifact,
+};
+
+export class BundledProtocolContractsProvider implements ProtocolContractsProvider {
+  getProtocolContractArtifact(name: ProtocolContractName): Promise<ProtocolContract> {
+    return Promise.resolve(makeProtocolContract(name, ProtocolContractArtifact[name]));
+  }
+}

package/src/provider/lazy.ts

@@ -0,0 +1,21 @@
+import { getCanonicalClassRegistry } from '../class-registry/lazy.js';
+import { getCanonicalFeeJuice } from '../fee-juice/lazy.js';
+import { getCanonicalInstanceRegistry } from '../instance-registry/lazy.js';
+import type { ProtocolContract } from '../protocol_contract.js';
+import type { ProtocolContractName } from '../protocol_contract_data.js';
+import type { ProtocolContractsProvider } from './protocol_contracts_provider.js';
+
+export class LazyProtocolContractsProvider implements ProtocolContractsProvider {
+  getProtocolContractArtifact(name: ProtocolContractName): Promise<ProtocolContract> {
+    switch (name) {
+      case 'ContractInstanceRegistry':
+        return getCanonicalInstanceRegistry();
+      case 'ContractClassRegistry':
+        return getCanonicalClassRegistry();
+      case 'FeeJuice':
+        return getCanonicalFeeJuice();
+      default:
+        throw new Error(`Unknown protocol contract name: ${name}`);
+    }
+  }
+}

package/src/provider/protocol_contracts_provider.ts

@@ -0,0 +1,7 @@
+import type { ProtocolContract } from '../protocol_contract.js';
+import type { ProtocolContractName } from '../protocol_contract_data.js';
+
+/** Returns the canonical deployment of a given artifact. */
+export interface ProtocolContractsProvider {
+  getProtocolContractArtifact(name: ProtocolContractName): Promise<ProtocolContract>;
+}

package/src/tests/fixtures.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+// Generated from end-to-end/src/automine/contracts/deploy/contract_class_registration.test.ts with AZTEC_GENERATE_TEST_DATA=1
+export function getSampleContractClassPublishedEventPayload(): Buffer {
+  const path = getPathToFixture('ContractClassPublishedEventData.hex');
+  return Buffer.from(readFileSync(path).toString(), 'hex');
+}
+
+// Generated from end-to-end/src/automine/contracts/deploy/contract_class_registration.test.ts with AZTEC_GENERATE_TEST_DATA=1
+export function getSampleContractInstancePublishedEventPayload(): Buffer {
+  const path = getPathToFixture('ContractInstancePublishedEventData.hex');
+  return Buffer.from(readFileSync(path).toString(), 'hex');
+}
+
+export function getPathToFixture(name: string) {
+  return resolve(dirname(fileURLToPath(import.meta.url)), `../../fixtures/${name}`);
+}