@aztec-labs/builder 6.0.0-nightly.20260829

package/README.md

@@ -0,0 +1,20 @@
+# Aztec builder
+
+The Aztec builder generates typescript classes for Noir contract, as well as Aztec.nr interfaces for calling external functions.
+It can also be used to update aztec project dependencies.
+
+## Installation
+
+To install the package, run:
+
+```bash
+yarn add @aztec-labs/builder
+```
+
+## Usage
+
+To run the tool, first install the package and then run:
+
+```bash
+yarn aztec-builder --help
+```

package/dest/bin/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvYmluL2NsaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dest/bin/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bin/cli.ts"],"names":[],"mappings":""}

package/dest/bin/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { createConsoleLogger } from '@aztec-labs/foundation/log';
+import { Command } from 'commander';
+import { injectCommands as injectBuilderCommands } from '../index.js';
+const log = createConsoleLogger('aztec:builder');
+const main = async ()=>{
+    const program = new Command('aztec-builder');
+    injectBuilderCommands(program);
+    await program.parseAsync(process.argv);
+    // I force exit here because spawnSync in npm.ts just blocks the process from exiting. Spent a bit of time debugging
+    // it without success and I think it doesn't make sense to invest more time in this.
+    process.exit(0);
+};
+main().catch((err)=>{
+    log(`Error running command`);
+    log(err);
+    process.exit(1);
+});

package/dest/contract-interface-gen/codegen.d.ts

@@ -0,0 +1,9 @@
+/** Generate code options */
+export type GenerateCodeOptions = {
+    force?: boolean;
+};
+/**
+ * Generates Noir interface or Typescript interface for a folder or single file from a Noir compilation artifact.
+ */
+export declare function generateCode(outputPath: string, fileOrDirPath: string, opts?: GenerateCodeOptions): Promise<(string | undefined)[]>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29kZWdlbi5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2NvbnRyYWN0LWludGVyZmFjZS1nZW4vY29kZWdlbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFXQSw0QkFBNEI7QUFDNUIsTUFBTSxNQUFNLG1CQUFtQixHQUFHO0lBQUUsS0FBSyxDQUFDLEVBQUUsT0FBTyxDQUFBO0NBQUUsQ0FBQztBQUV0RDs7R0FFRztBQUNILHdCQUFzQixZQUFZLENBQUMsVUFBVSxFQUFFLE1BQU0sRUFBRSxhQUFhLEVBQUUsTUFBTSxFQUFFLElBQUksR0FBRSxtQkFBd0IsbUNBa0IzRyJ9

package/dest/contract-interface-gen/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/contract-interface-gen/codegen.ts"],"names":[],"mappings":"AAWA,4BAA4B;AAC5B,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtD;;GAEG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,mCAkB3G"}

package/dest/contract-interface-gen/codegen.js

@@ -0,0 +1,92 @@
+/* eslint-disable no-console */ import { loadContractArtifact } from '@aztec-labs/stdlib/abi';
+import crypto from 'crypto';
+import { access, mkdir, readFile, readdir, stat, writeFile } from 'fs/promises';
+import path from 'path';
+import { generateTypescriptContractInterface } from './typescript.js';
+const cacheFilePath = './codegenCache.json';
+let cache = {};
+/**
+ * Generates Noir interface or Typescript interface for a folder or single file from a Noir compilation artifact.
+ */ export async function generateCode(outputPath, fileOrDirPath, opts = {}) {
+    await readCache();
+    const results = [];
+    const stats = await stat(fileOrDirPath);
+    if (stats.isDirectory()) {
+        const files = (await readdir(fileOrDirPath, {
+            recursive: true,
+            encoding: 'utf-8'
+        })).filter((file)=>file.endsWith('.json') && !file.startsWith('debug_'));
+        for (const file of files){
+            const fullPath = path.join(fileOrDirPath, file);
+            results.push(await generateFromNoirAbi(outputPath, fullPath, opts));
+        }
+    } else if (stats.isFile()) {
+        results.push(await generateFromNoirAbi(outputPath, fileOrDirPath, opts));
+    }
+    await writeCache();
+    return results;
+}
+/**
+ * Generates Noir interface or Typescript interface for a single file Noir compilation artifact.
+ */ async function generateFromNoirAbi(outputPath, noirAbiPath, opts = {}) {
+    const fileName = path.basename(noirAbiPath);
+    const currentHash = await generateFileHash(noirAbiPath);
+    const cachedInstance = isCacheValid(fileName, currentHash);
+    if (cachedInstance && !opts.force) {
+        console.log(`${fileName} has not changed. Skipping generation.`);
+        return `${outputPath}/${cachedInstance.contractName}.ts`;
+    }
+    const file = await readFile(noirAbiPath, 'utf8');
+    const contract = JSON.parse(file);
+    if (!Array.isArray(contract.functions)) {
+        console.log(`${fileName} is not a contract artifact. Skipping.`);
+        return;
+    }
+    const aztecAbi = loadContractArtifact(contract);
+    await mkdir(outputPath, {
+        recursive: true
+    });
+    let relativeArtifactPath = path.relative(outputPath, noirAbiPath);
+    if (relativeArtifactPath === path.basename(noirAbiPath)) {
+        // Prepend ./ for local import if the folder is the same
+        relativeArtifactPath = `./${relativeArtifactPath}`;
+    }
+    const tsWrapper = await generateTypescriptContractInterface(aztecAbi, relativeArtifactPath);
+    const outputFilePath = `${outputPath}/${aztecAbi.name}.ts`;
+    await writeFile(outputFilePath, tsWrapper);
+    updateCache(fileName, aztecAbi.name, currentHash);
+    return outputFilePath;
+}
+async function generateFileHash(filePath) {
+    const fileBuffer = await readFile(filePath);
+    const hashSum = crypto.createHash('sha256');
+    hashSum.update(fileBuffer);
+    const hex = hashSum.digest('hex');
+    return hex;
+}
+async function readCache() {
+    if (await exists(cacheFilePath)) {
+        const cacheRaw = await readFile(cacheFilePath, 'utf8');
+        cache = JSON.parse(cacheRaw);
+    }
+}
+async function writeCache() {
+    await writeFile(cacheFilePath, JSON.stringify(cache, null, 2), 'utf8');
+}
+function isCacheValid(contractName, currentHash) {
+    return cache[contractName]?.hash === currentHash && cache[contractName];
+}
+function updateCache(fileName, contractName, hash) {
+    cache[fileName] = {
+        contractName,
+        hash
+    };
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    } catch  {
+        return false;
+    }
+}

package/dest/contract-interface-gen/index.d.ts

@@ -0,0 +1,2 @@
+export { generateTypescriptContractInterface } from './typescript.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jb250cmFjdC1pbnRlcmZhY2UtZ2VuL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxtQ0FBbUMsRUFBRSxNQUFNLGlCQUFpQixDQUFDIn0=

package/dest/contract-interface-gen/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract-interface-gen/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,iBAAiB,CAAC"}

package/dest/contract-interface-gen/index.js

@@ -0,0 +1 @@
+export { generateTypescriptContractInterface } from './typescript.js';

package/dest/contract-interface-gen/typescript.d.ts

@@ -0,0 +1,9 @@
+import { type ContractArtifact } from '@aztec-labs/stdlib/abi';
+/**
+ * Generates the typescript code to represent a contract.
+ * @param input - The compiled Noir artifact.
+ * @param artifactImportPath - Optional path to import the artifact (if not set, will be required in the constructor).
+ * @returns The corresponding ts code.
+ */
+export declare function generateTypescriptContractInterface(input: ContractArtifact, artifactImportPath?: string): Promise<string>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXNjcmlwdC5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2NvbnRyYWN0LWludGVyZmFjZS1nZW4vdHlwZXNjcmlwdC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBR0wsS0FBSyxnQkFBZ0IsRUFhdEIsTUFBTSx3QkFBd0IsQ0FBQztBQXVSaEM7Ozs7O0dBS0c7QUFDSCx3QkFBc0IsbUNBQW1DLENBQUMsS0FBSyxFQUFFLGdCQUFnQixFQUFFLGtCQUFrQixDQUFDLEVBQUUsTUFBTSxtQkFrRDdHIn0=

package/dest/contract-interface-gen/typescript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../src/contract-interface-gen/typescript.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EAatB,MAAM,wBAAwB,CAAC;AAuRhC;;;;;GAKG;AACH,wBAAsB,mCAAmC,CAAC,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM,mBAkD7G"}

package/dest/contract-interface-gen/typescript.js

@@ -0,0 +1,296 @@
+import { EventSelector, decodeFunctionSignature, getAllFunctionAbis, getDefaultInitializer, isAztecAddressStruct, isBoundedVecStruct, isEthAddressStruct, isFunctionSelectorStruct, isOptionStruct, isPublicKeysStruct, isWrappedFieldStruct } from '@aztec-labs/stdlib/abi';
+/**
+ * Returns the corresponding typescript type for a given Noir type.
+ * @param type - The input Noir type.
+ * @returns An equivalent typescript type.
+ */ function abiTypeToTypescript(type) {
+    switch(type.kind){
+        case 'field':
+            return 'FieldLike';
+        case 'boolean':
+            return 'boolean';
+        case 'integer':
+            return '(bigint | number)';
+        case 'string':
+            return 'string';
+        case 'array':
+            return `${abiTypeToTypescript(type.type)}[]`;
+        case 'struct':
+            if (isEthAddressStruct(type)) {
+                return 'EthAddressLike';
+            }
+            if (isAztecAddressStruct(type)) {
+                return 'AztecAddressLike';
+            }
+            if (isFunctionSelectorStruct(type)) {
+                return 'FunctionSelectorLike';
+            }
+            if (isWrappedFieldStruct(type)) {
+                return 'WrappedFieldLike';
+            }
+            if (isPublicKeysStruct(type)) {
+                // PublicKeys are special cased due to them being part of the preimage of contract addresses.
+                // The proper type is expected by the TS code that deals with the ContractInstanceRegistry protocol contract.
+                return 'PublicKeys';
+            }
+            if (isBoundedVecStruct(type)) {
+                // To make BoundedVec easier to work with, we expect a simple array on the input and then we encode it
+                // as a BoundedVec in the ArgumentsEncoder.
+                return `${abiTypeToTypescript(type.fields[0].type)}`;
+            }
+            if (isOptionStruct(type)) {
+                return `OptionLike<${abiTypeToTypescript(type.fields[1].type)}>`;
+            }
+            return `{ ${type.fields.map((f)=>`${f.name}: ${abiTypeToTypescript(f.type)}`).join(', ')} }`;
+        default:
+            throw new Error(`Unknown type ${type.kind}`);
+    }
+}
+/**
+ * Generates the typescript code to represent a Noir parameter.
+ * @param param - A Noir parameter with name and type.
+ * @returns The corresponding ts code.
+ */ function generateParameter(param) {
+    return `${param.name}: ${abiTypeToTypescript(param.type)}`;
+}
+/**
+ * Generates the typescript code to represent a Noir function as a type.
+ * @param param - A Noir function.
+ * @returns The corresponding ts code.
+ */ function generateMethod(entry) {
+    const args = entry.parameters.map(generateParameter).join(', ');
+    return `
+    /** ${entry.name}(${entry.parameters.map((p)=>`${p.name}: ${p.type.kind}`).join(', ')}) */
+    ${entry.name}: ((${args}) => ContractFunctionInteraction) & Pick<ContractMethod, 'selector'>;`;
+}
+/**
+ * Generates a deploy method for this contract.
+ * @param input - Build artifact of the contract.
+ * @returns A type-safe deploy method in ts.
+ */ function generateDeploy(input) {
+    const ctor = getDefaultInitializer(input);
+    const ctorParams = ctor?.parameters ?? [];
+    const args = ctorParams.map(generateParameter).join(', ');
+    const argNames = ctorParams.map((p)=>p.name).join(', ');
+    const argsForwarding = argNames ? `[${argNames}]` : '[]';
+    const contractName = `${input.name}Contract`;
+    const artifactName = `${contractName}Artifact`;
+    return `
+  /**
+   * Creates a tx to deploy a new instance of this contract.
+   * @param instantiation - Optional address-affecting parameters (salt, deployer / universalDeploy, publicKeys).
+   *                       Salt defaults to a random value; the deployer is locked lazily from the first send-time \`from\`.
+   */
+  public static deploy(wallet: Wallet, ${args ? `${args}, ` : ''}instantiation?: DeployInstantiationOptions) {
+    return DeployMethod.create<${contractName}>(
+      wallet,
+      {
+        artifact: ${artifactName},
+        postDeployCtor: (instance, wallet) => ${contractName}.at(instance.address, wallet),
+        args: ${argsForwarding},
+      },
+      instantiation,
+    );
+  }
+
+  /**
+   * Creates a tx to deploy a new instance of this contract using the specified constructor method.
+   */
+  public static deployWithOpts<M extends keyof ${contractName}['methods']>(
+    opts: { method?: M; wallet: Wallet; instantiation?: DeployInstantiationOptions },
+    ...args: Parameters<${contractName}['methods'][M]>
+  ) {
+    return DeployMethod.create<${contractName}>(
+      opts.wallet,
+      {
+        artifact: ${artifactName},
+        postDeployCtor: (instance, wallet) => ${contractName}.at(instance.address, wallet),
+        args,
+        constructorNameOrArtifact: opts.method ?? 'constructor',
+      },
+      opts.instantiation,
+    );
+  }
+  `;
+}
+/**
+ * Generates the constructor by supplying the ABI to the parent class so the user doesn't have to.
+ * @param name - Name of the contract to derive the ABI name from.
+ * @returns A constructor method.
+ * @remarks The constructor is private because we want to force the user to use the at method.
+ */ function generateConstructor(name) {
+    return `
+  private constructor(
+    address: AztecAddress,
+    wallet: Wallet,
+  ) {
+    super(address, ${name}ContractArtifact, wallet);
+  }
+  `;
+}
+/**
+ * Generates the at method for this contract.
+ * @param name - Name of the contract to derive the ABI name from.
+ * @returns An at method.
+ */ function generateAt(name) {
+    return `
+  /**
+   * Creates a contract instance.
+   * @param address - The deployed contract's address.
+   * @param wallet - The wallet to use when interacting with the contract.
+   * @returns A new Contract instance.
+   */
+  public static at(
+    address: AztecAddress,
+    wallet: Wallet,
+  ): ${name}Contract {
+    return Contract.at(address, ${name}Contract.artifact, wallet) as ${name}Contract;
+  }`;
+}
+/**
+ * Generates static getters for the contract's artifact.
+ * @param name - Name of the contract used to derive name of the artifact import.
+ */ function generateArtifactGetters(name) {
+    const artifactName = `${name}ContractArtifact`;
+    return `
+  /**
+   * Returns this contract's artifact.
+   */
+  public static get artifact(): ContractArtifact {
+    return ${artifactName};
+  }
+
+  /**
+   * Returns this contract's artifact with public bytecode.
+   */
+  public static get artifactForPublic(): ContractArtifact {
+    return loadContractArtifactForPublic(${artifactName}Json as NoirCompiledContract);
+  }
+  `;
+}
+/**
+ * Generates statements for importing the artifact from json and re-exporting it.
+ * @param name - Name of the contract.
+ * @param artifactImportPath - Path to load the ABI from.
+ * @returns Code.
+ */ function generateAbiStatement(name, artifactImportPath) {
+    const stmts = [
+        `import ${name}ContractArtifactJson from '${artifactImportPath}' with { type: 'json' };`,
+        `export const ${name}ContractArtifact = loadContractArtifact(${name}ContractArtifactJson as NoirCompiledContract);`
+    ];
+    return stmts.join('\n');
+}
+/**
+ * Generates a getter for the contract's storage layout.
+ * @param input - The contract artifact.
+ */ function generateStorageLayoutGetter(input) {
+    const entries = Object.entries(input.storageLayout);
+    if (entries.length === 0) {
+        return '';
+    }
+    const storageFieldsUnionType = entries.map(([name])=>`'${name}'`).join(' | ');
+    const layout = entries.map(([name, { slot }])=>`${name}: {
+      slot: new Fr(${slot.toBigInt()}n),
+    }`).join(',\n');
+    return `public static get storage(): ContractStorageLayout<${storageFieldsUnionType}> {
+      return {
+        ${layout}
+      } as ContractStorageLayout<${storageFieldsUnionType}>;
+    }
+    `;
+}
+// events is of type AbiType
+async function generateEvents(events) {
+    if (events === undefined) {
+        return {
+            events: '',
+            eventDefs: ''
+        };
+    }
+    const eventsMetadata = await Promise.all(events.map(async (event)=>{
+        const eventName = event.path.split('::').at(-1);
+        const eventDefProps = event.fields.map((field)=>`${field.name}: ${abiTypeToTypescript(field.type)}`);
+        const eventDef = `
+      export type ${eventName} = {
+        ${eventDefProps.join('\n')}
+      }
+    `;
+        const fieldNames = event.fields.map((field)=>`"${field.name}"`);
+        const eventType = `${eventName}: {abiType: AbiType, eventSelector: EventSelector, fieldNames: string[] }`;
+        // Reusing the decodeFunctionSignature
+        const eventSignature = decodeFunctionSignature(eventName, event.fields);
+        const eventSelector = await EventSelector.fromSignature(eventSignature);
+        const eventImpl = `${eventName}: {
+        abiType: ${JSON.stringify(event, null, 4)},
+        eventSelector: EventSelector.fromString("${eventSelector}"),
+        fieldNames: [${fieldNames}],
+      }`;
+        return {
+            eventDef,
+            eventType,
+            eventImpl
+        };
+    }));
+    return {
+        eventDefs: eventsMetadata.map(({ eventDef })=>eventDef).join('\n'),
+        events: `
+    public static get events(): { ${eventsMetadata.map(({ eventType })=>eventType).join(', ')} } {
+    return {
+      ${eventsMetadata.map(({ eventImpl })=>eventImpl).join(',\n')}
+    };
+  }
+  `
+    };
+}
+/**
+ * Generates the typescript code to represent a contract.
+ * @param input - The compiled Noir artifact.
+ * @param artifactImportPath - Optional path to import the artifact (if not set, will be required in the constructor).
+ * @returns The corresponding ts code.
+ */ export async function generateTypescriptContractInterface(input, artifactImportPath) {
+    const methods = getAllFunctionAbis(input).filter((f)=>!f.isOnlySelf).sort((a, b)=>a.name.localeCompare(b.name)).map(generateMethod);
+    const deploy = artifactImportPath && generateDeploy(input);
+    const ctor = artifactImportPath && generateConstructor(input.name);
+    const at = artifactImportPath && generateAt(input.name);
+    const artifactStatement = artifactImportPath && generateAbiStatement(input.name, artifactImportPath);
+    const artifactGetter = artifactImportPath && generateArtifactGetters(input.name);
+    const storageLayoutGetter = artifactImportPath && generateStorageLayoutGetter(input);
+    const { eventDefs, events } = await generateEvents(input.outputs.structs?.events);
+    return `
+/* Autogenerated file, do not edit! */
+
+/* eslint-disable */
+import { AztecAddress, CompleteAddress } from '@aztec-labs/aztec.js/addresses';
+import { type AbiType, type AztecAddressLike, type ContractArtifact, EventSelector, type EthAddressLike, type FieldLike, type FunctionSelectorLike, loadContractArtifact, loadContractArtifactForPublic, type NoirCompiledContract, type OptionLike, type U128Like, type WrappedFieldLike } from '@aztec-labs/aztec.js/abi';
+import { Contract, ContractBase, ContractFunctionInteraction, type ContractMethod, type ContractStorageLayout, type DeployInstantiationOptions, DeployMethod } from '@aztec-labs/aztec.js/contracts';
+import { EthAddress } from '@aztec-labs/aztec.js/addresses';
+import { Fr, Point } from '@aztec-labs/aztec.js/fields';
+import { type PublicKey, PublicKeys } from '@aztec-labs/aztec.js/keys';
+import type { Wallet } from '@aztec-labs/aztec.js/wallet';
+${artifactStatement}
+
+${eventDefs}
+
+/**
+ * Type-safe interface for contract ${input.name};
+ */
+export class ${input.name}Contract extends ContractBase {
+  ${ctor}
+
+  ${at}
+
+  ${deploy}
+
+  ${artifactGetter}
+
+  ${storageLayoutGetter}
+
+  /** Type-safe wrappers for the public methods exposed by the contract. */
+  public declare methods: {
+    ${methods.join('\n')}
+  };
+
+  ${events}
+}
+`;
+}

package/dest/index.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function injectCommands(program: Command): Command;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxPQUFPLEVBQUUsTUFBTSxXQUFXLENBQUM7QUFHekMsd0JBQWdCLGNBQWMsQ0FBQyxPQUFPLEVBQUUsT0FBTyxXQVk5QyJ9

package/dest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,WAY9C"}

package/dest/index.js

@@ -0,0 +1,10 @@
+import { dirname } from 'path';
+export function injectCommands(program) {
+    program.command('codegen').argument('<noir-abi-path>', 'Path to the Noir ABI or project dir.').option('-o, --outdir <path>', 'Output folder for the generated code.').option('-f, --force', 'Force code generation even when the contract has not changed.').description('Validates and generates an Aztec Contract ABI from Noir ABI.').action(async (noirAbiPath, { outdir, force })=>{
+        const { generateCode } = await import('./contract-interface-gen/codegen.js');
+        await generateCode(outdir || dirname(noirAbiPath), noirAbiPath, {
+            force
+        });
+    });
+    return program;
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@aztec-labs/builder",
+  "version": "6.0.0-nightly.20260829",
+  "type": "module",
+  "exports": {
+    ".": "./dest/index.js",
+    "./cli": "./dest/bin/cli.js",
+    "./codegen": "./dest/contract-interface-gen/index.js"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/index.ts"
+    ],
+    "name": "Aztec builder",
+    "tsconfig": "./tsconfig.json"
+  },
+  "scripts": {
+    "build": "yarn clean && ../scripts/tsc.sh",
+    "build:dev": "../scripts/tsc.sh --watch",
+    "generate": "../scripts/tsc.sh",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "moduleFileExtensions": [
+      "js",
+      "ts",
+      "cts"
+    ],
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ],
+    "testEnvironment": "../../foundation/src/jest/env.mjs",
+    "setupFilesAfterEnv": [
+      "../../foundation/src/jest/setupAfterEnv.mjs"
+    ]
+  },
+  "dependencies": {
+    "@aztec-labs/foundation": "6.0.0-nightly.20260829",
+    "@aztec-labs/stdlib": "6.0.0-nightly.20260829",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.15.17",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
+    "jest": "^30.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "types": "./dest/index.d.ts",
+  "engines": {
+    "node": ">=20.10"
+  }
+}

package/src/bin/cli.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { createConsoleLogger } from '@aztec-labs/foundation/log';
+import { Command } from 'commander';
+
+import { injectCommands as injectBuilderCommands } from '../index.js';
+
+const log = createConsoleLogger('aztec:builder');
+
+const main = async () => {
+  const program = new Command('aztec-builder');
+
+  injectBuilderCommands(program);
+  await program.parseAsync(process.argv);
+  // I force exit here because spawnSync in npm.ts just blocks the process from exiting. Spent a bit of time debugging
+  // it without success and I think it doesn't make sense to invest more time in this.
+  process.exit(0);
+};
+
+main().catch(err => {
+  log(`Error running command`);
+  log(err);
+  process.exit(1);
+});

package/src/contract-interface-gen/codegen.ts

@@ -0,0 +1,111 @@
+/* eslint-disable no-console */
+import { loadContractArtifact } from '@aztec-labs/stdlib/abi';
+import crypto from 'crypto';
+import { access, mkdir, readFile, readdir, stat, writeFile } from 'fs/promises';
+import path from 'path';
+
+import { generateTypescriptContractInterface } from './typescript.js';
+
+const cacheFilePath = './codegenCache.json';
+let cache: Record<string, { contractName: string; hash: string }> = {};
+
+/** Generate code options */
+export type GenerateCodeOptions = { force?: boolean };
+
+/**
+ * Generates Noir interface or Typescript interface for a folder or single file from a Noir compilation artifact.
+ */
+export async function generateCode(outputPath: string, fileOrDirPath: string, opts: GenerateCodeOptions = {}) {
+  await readCache();
+  const results = [];
+  const stats = await stat(fileOrDirPath);
+
+  if (stats.isDirectory()) {
+    const files = (await readdir(fileOrDirPath, { recursive: true, encoding: 'utf-8' })).filter(
+      file => file.endsWith('.json') && !file.startsWith('debug_'),
+    );
+    for (const file of files) {
+      const fullPath = path.join(fileOrDirPath, file);
+      results.push(await generateFromNoirAbi(outputPath, fullPath, opts));
+    }
+  } else if (stats.isFile()) {
+    results.push(await generateFromNoirAbi(outputPath, fileOrDirPath, opts));
+  }
+  await writeCache();
+  return results;
+}
+
+/**
+ * Generates Noir interface or Typescript interface for a single file Noir compilation artifact.
+ */
+async function generateFromNoirAbi(outputPath: string, noirAbiPath: string, opts: GenerateCodeOptions = {}) {
+  const fileName = path.basename(noirAbiPath);
+  const currentHash = await generateFileHash(noirAbiPath);
+  const cachedInstance = isCacheValid(fileName, currentHash);
+  if (cachedInstance && !opts.force) {
+    console.log(`${fileName} has not changed. Skipping generation.`);
+    return `${outputPath}/${cachedInstance.contractName}.ts`;
+  }
+
+  const file = await readFile(noirAbiPath, 'utf8');
+  const contract = JSON.parse(file);
+
+  if (!Array.isArray(contract.functions)) {
+    console.log(`${fileName} is not a contract artifact. Skipping.`);
+    return;
+  }
+
+  const aztecAbi = loadContractArtifact(contract);
+
+  await mkdir(outputPath, { recursive: true });
+
+  let relativeArtifactPath = path.relative(outputPath, noirAbiPath);
+  if (relativeArtifactPath === path.basename(noirAbiPath)) {
+    // Prepend ./ for local import if the folder is the same
+    relativeArtifactPath = `./${relativeArtifactPath}`;
+  }
+
+  const tsWrapper = await generateTypescriptContractInterface(aztecAbi, relativeArtifactPath);
+  const outputFilePath = `${outputPath}/${aztecAbi.name}.ts`;
+
+  await writeFile(outputFilePath, tsWrapper);
+
+  updateCache(fileName, aztecAbi.name, currentHash);
+  return outputFilePath;
+}
+
+async function generateFileHash(filePath: string) {
+  const fileBuffer = await readFile(filePath);
+  const hashSum = crypto.createHash('sha256');
+  hashSum.update(fileBuffer);
+  const hex = hashSum.digest('hex');
+  return hex;
+}
+
+async function readCache() {
+  if (await exists(cacheFilePath)) {
+    const cacheRaw = await readFile(cacheFilePath, 'utf8');
+    cache = JSON.parse(cacheRaw);
+  }
+}
+
+async function writeCache() {
+  await writeFile(cacheFilePath, JSON.stringify(cache, null, 2), 'utf8');
+}
+
+function isCacheValid(contractName: string, currentHash: string) {
+  return cache[contractName]?.hash === currentHash && cache[contractName];
+}
+
+function updateCache(fileName: string, contractName: string, hash: string): void {
+  cache[fileName] = { contractName, hash };
+}
+
+async function exists(filePath: string) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/contract-interface-gen/index.ts

@@ -0,0 +1 @@
+export { generateTypescriptContractInterface } from './typescript.js';

package/src/contract-interface-gen/typescript.ts

@@ -0,0 +1,352 @@
+import {
+  type ABIParameter,
+  type ABIVariable,
+  type ContractArtifact,
+  EventSelector,
+  type FunctionAbi,
+  decodeFunctionSignature,
+  getAllFunctionAbis,
+  getDefaultInitializer,
+  isAztecAddressStruct,
+  isBoundedVecStruct,
+  isEthAddressStruct,
+  isFunctionSelectorStruct,
+  isOptionStruct,
+  isPublicKeysStruct,
+  isWrappedFieldStruct,
+} from '@aztec-labs/stdlib/abi';
+
+/**
+ * Returns the corresponding typescript type for a given Noir type.
+ * @param type - The input Noir type.
+ * @returns An equivalent typescript type.
+ */
+function abiTypeToTypescript(type: ABIParameter['type']): string {
+  switch (type.kind) {
+    case 'field':
+      return 'FieldLike';
+    case 'boolean':
+      return 'boolean';
+    case 'integer':
+      return '(bigint | number)';
+    case 'string':
+      return 'string';
+    case 'array':
+      return `${abiTypeToTypescript(type.type)}[]`;
+    case 'struct':
+      if (isEthAddressStruct(type)) {
+        return 'EthAddressLike';
+      }
+      if (isAztecAddressStruct(type)) {
+        return 'AztecAddressLike';
+      }
+      if (isFunctionSelectorStruct(type)) {
+        return 'FunctionSelectorLike';
+      }
+      if (isWrappedFieldStruct(type)) {
+        return 'WrappedFieldLike';
+      }
+      if (isPublicKeysStruct(type)) {
+        // PublicKeys are special cased due to them being part of the preimage of contract addresses.
+        // The proper type is expected by the TS code that deals with the ContractInstanceRegistry protocol contract.
+        return 'PublicKeys';
+      }
+      if (isBoundedVecStruct(type)) {
+        // To make BoundedVec easier to work with, we expect a simple array on the input and then we encode it
+        // as a BoundedVec in the ArgumentsEncoder.
+        return `${abiTypeToTypescript(type.fields[0].type)}`;
+      }
+      if (isOptionStruct(type)) {
+        return `OptionLike<${abiTypeToTypescript(type.fields[1].type)}>`;
+      }
+      return `{ ${type.fields.map(f => `${f.name}: ${abiTypeToTypescript(f.type)}`).join(', ')} }`;
+    default:
+      throw new Error(`Unknown type ${type.kind}`);
+  }
+}
+
+/**
+ * Generates the typescript code to represent a Noir parameter.
+ * @param param - A Noir parameter with name and type.
+ * @returns The corresponding ts code.
+ */
+function generateParameter(param: ABIParameter) {
+  return `${param.name}: ${abiTypeToTypescript(param.type)}`;
+}
+
+/**
+ * Generates the typescript code to represent a Noir function as a type.
+ * @param param - A Noir function.
+ * @returns The corresponding ts code.
+ */
+function generateMethod(entry: FunctionAbi) {
+  const args = entry.parameters.map(generateParameter).join(', ');
+  return `
+    /** ${entry.name}(${entry.parameters.map(p => `${p.name}: ${p.type.kind}`).join(', ')}) */
+    ${entry.name}: ((${args}) => ContractFunctionInteraction) & Pick<ContractMethod, 'selector'>;`;
+}
+
+/**
+ * Generates a deploy method for this contract.
+ * @param input - Build artifact of the contract.
+ * @returns A type-safe deploy method in ts.
+ */
+function generateDeploy(input: ContractArtifact) {
+  const ctor = getDefaultInitializer(input);
+  const ctorParams = ctor?.parameters ?? [];
+  const args = ctorParams.map(generateParameter).join(', ');
+  const argNames = ctorParams.map(p => p.name).join(', ');
+  const argsForwarding = argNames ? `[${argNames}]` : '[]';
+  const contractName = `${input.name}Contract`;
+  const artifactName = `${contractName}Artifact`;
+
+  return `
+  /**
+   * Creates a tx to deploy a new instance of this contract.
+   * @param instantiation - Optional address-affecting parameters (salt, deployer / universalDeploy, publicKeys).
+   *                       Salt defaults to a random value; the deployer is locked lazily from the first send-time \`from\`.
+   */
+  public static deploy(wallet: Wallet, ${args ? `${args}, ` : ''}instantiation?: DeployInstantiationOptions) {
+    return DeployMethod.create<${contractName}>(
+      wallet,
+      {
+        artifact: ${artifactName},
+        postDeployCtor: (instance, wallet) => ${contractName}.at(instance.address, wallet),
+        args: ${argsForwarding},
+      },
+      instantiation,
+    );
+  }
+
+  /**
+   * Creates a tx to deploy a new instance of this contract using the specified constructor method.
+   */
+  public static deployWithOpts<M extends keyof ${contractName}['methods']>(
+    opts: { method?: M; wallet: Wallet; instantiation?: DeployInstantiationOptions },
+    ...args: Parameters<${contractName}['methods'][M]>
+  ) {
+    return DeployMethod.create<${contractName}>(
+      opts.wallet,
+      {
+        artifact: ${artifactName},
+        postDeployCtor: (instance, wallet) => ${contractName}.at(instance.address, wallet),
+        args,
+        constructorNameOrArtifact: opts.method ?? 'constructor',
+      },
+      opts.instantiation,
+    );
+  }
+  `;
+}
+
+/**
+ * Generates the constructor by supplying the ABI to the parent class so the user doesn't have to.
+ * @param name - Name of the contract to derive the ABI name from.
+ * @returns A constructor method.
+ * @remarks The constructor is private because we want to force the user to use the at method.
+ */
+function generateConstructor(name: string) {
+  return `
+  private constructor(
+    address: AztecAddress,
+    wallet: Wallet,
+  ) {
+    super(address, ${name}ContractArtifact, wallet);
+  }
+  `;
+}
+
+/**
+ * Generates the at method for this contract.
+ * @param name - Name of the contract to derive the ABI name from.
+ * @returns An at method.
+ */
+function generateAt(name: string) {
+  return `
+  /**
+   * Creates a contract instance.
+   * @param address - The deployed contract's address.
+   * @param wallet - The wallet to use when interacting with the contract.
+   * @returns A new Contract instance.
+   */
+  public static at(
+    address: AztecAddress,
+    wallet: Wallet,
+  ): ${name}Contract {
+    return Contract.at(address, ${name}Contract.artifact, wallet) as ${name}Contract;
+  }`;
+}
+
+/**
+ * Generates static getters for the contract's artifact.
+ * @param name - Name of the contract used to derive name of the artifact import.
+ */
+function generateArtifactGetters(name: string) {
+  const artifactName = `${name}ContractArtifact`;
+  return `
+  /**
+   * Returns this contract's artifact.
+   */
+  public static get artifact(): ContractArtifact {
+    return ${artifactName};
+  }
+
+  /**
+   * Returns this contract's artifact with public bytecode.
+   */
+  public static get artifactForPublic(): ContractArtifact {
+    return loadContractArtifactForPublic(${artifactName}Json as NoirCompiledContract);
+  }
+  `;
+}
+
+/**
+ * Generates statements for importing the artifact from json and re-exporting it.
+ * @param name - Name of the contract.
+ * @param artifactImportPath - Path to load the ABI from.
+ * @returns Code.
+ */
+function generateAbiStatement(name: string, artifactImportPath: string) {
+  const stmts = [
+    `import ${name}ContractArtifactJson from '${artifactImportPath}' with { type: 'json' };`,
+    `export const ${name}ContractArtifact = loadContractArtifact(${name}ContractArtifactJson as NoirCompiledContract);`,
+  ];
+  return stmts.join('\n');
+}
+
+/**
+ * Generates a getter for the contract's storage layout.
+ * @param input - The contract artifact.
+ */
+function generateStorageLayoutGetter(input: ContractArtifact) {
+  const entries = Object.entries(input.storageLayout);
+
+  if (entries.length === 0) {
+    return '';
+  }
+
+  const storageFieldsUnionType = entries.map(([name]) => `'${name}'`).join(' | ');
+  const layout = entries
+    .map(
+      ([name, { slot }]) =>
+        `${name}: {
+      slot: new Fr(${slot.toBigInt()}n),
+    }`,
+    )
+    .join(',\n');
+
+  return `public static get storage(): ContractStorageLayout<${storageFieldsUnionType}> {
+      return {
+        ${layout}
+      } as ContractStorageLayout<${storageFieldsUnionType}>;
+    }
+    `;
+}
+
+// events is of type AbiType
+async function generateEvents(events: any[] | undefined) {
+  if (events === undefined) {
+    return { events: '', eventDefs: '' };
+  }
+
+  const eventsMetadata = await Promise.all(
+    events.map(async event => {
+      const eventName = event.path.split('::').at(-1);
+
+      const eventDefProps = event.fields.map(
+        (field: ABIVariable) => `${field.name}: ${abiTypeToTypescript(field.type)}`,
+      );
+      const eventDef = `
+      export type ${eventName} = {
+        ${eventDefProps.join('\n')}
+      }
+    `;
+
+      const fieldNames = event.fields.map((field: any) => `"${field.name}"`);
+      const eventType = `${eventName}: {abiType: AbiType, eventSelector: EventSelector, fieldNames: string[] }`;
+      // Reusing the decodeFunctionSignature
+      const eventSignature = decodeFunctionSignature(eventName, event.fields);
+      const eventSelector = await EventSelector.fromSignature(eventSignature);
+      const eventImpl = `${eventName}: {
+        abiType: ${JSON.stringify(event, null, 4)},
+        eventSelector: EventSelector.fromString("${eventSelector}"),
+        fieldNames: [${fieldNames}],
+      }`;
+
+      return {
+        eventDef,
+        eventType,
+        eventImpl,
+      };
+    }),
+  );
+
+  return {
+    eventDefs: eventsMetadata.map(({ eventDef }) => eventDef).join('\n'),
+    events: `
+    public static get events(): { ${eventsMetadata.map(({ eventType }) => eventType).join(', ')} } {
+    return {
+      ${eventsMetadata.map(({ eventImpl }) => eventImpl).join(',\n')}
+    };
+  }
+  `,
+  };
+}
+
+/**
+ * Generates the typescript code to represent a contract.
+ * @param input - The compiled Noir artifact.
+ * @param artifactImportPath - Optional path to import the artifact (if not set, will be required in the constructor).
+ * @returns The corresponding ts code.
+ */
+export async function generateTypescriptContractInterface(input: ContractArtifact, artifactImportPath?: string) {
+  const methods = getAllFunctionAbis(input)
+    .filter(f => !f.isOnlySelf)
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(generateMethod);
+  const deploy = artifactImportPath && generateDeploy(input);
+  const ctor = artifactImportPath && generateConstructor(input.name);
+  const at = artifactImportPath && generateAt(input.name);
+  const artifactStatement = artifactImportPath && generateAbiStatement(input.name, artifactImportPath);
+  const artifactGetter = artifactImportPath && generateArtifactGetters(input.name);
+  const storageLayoutGetter = artifactImportPath && generateStorageLayoutGetter(input);
+  const { eventDefs, events } = await generateEvents(input.outputs.structs?.events);
+
+  return `
+/* Autogenerated file, do not edit! */
+
+/* eslint-disable */
+import { AztecAddress, CompleteAddress } from '@aztec-labs/aztec.js/addresses';
+import { type AbiType, type AztecAddressLike, type ContractArtifact, EventSelector, type EthAddressLike, type FieldLike, type FunctionSelectorLike, loadContractArtifact, loadContractArtifactForPublic, type NoirCompiledContract, type OptionLike, type U128Like, type WrappedFieldLike } from '@aztec-labs/aztec.js/abi';
+import { Contract, ContractBase, ContractFunctionInteraction, type ContractMethod, type ContractStorageLayout, type DeployInstantiationOptions, DeployMethod } from '@aztec-labs/aztec.js/contracts';
+import { EthAddress } from '@aztec-labs/aztec.js/addresses';
+import { Fr, Point } from '@aztec-labs/aztec.js/fields';
+import { type PublicKey, PublicKeys } from '@aztec-labs/aztec.js/keys';
+import type { Wallet } from '@aztec-labs/aztec.js/wallet';
+${artifactStatement}
+
+${eventDefs}
+
+/**
+ * Type-safe interface for contract ${input.name};
+ */
+export class ${input.name}Contract extends ContractBase {
+  ${ctor}
+
+  ${at}
+
+  ${deploy}
+
+  ${artifactGetter}
+
+  ${storageLayoutGetter}
+
+  /** Type-safe wrappers for the public methods exposed by the contract. */
+  public declare methods: {
+    ${methods.join('\n')}
+  };
+
+  ${events}
+}
+`;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import { dirname } from 'path';
+
+export function injectCommands(program: Command) {
+  program
+    .command('codegen')
+    .argument('<noir-abi-path>', 'Path to the Noir ABI or project dir.')
+    .option('-o, --outdir <path>', 'Output folder for the generated code.')
+    .option('-f, --force', 'Force code generation even when the contract has not changed.')
+    .description('Validates and generates an Aztec Contract ABI from Noir ABI.')
+    .action(async (noirAbiPath: string, { outdir, force }) => {
+      const { generateCode } = await import('./contract-interface-gen/codegen.js');
+      await generateCode(outdir || dirname(noirAbiPath), noirAbiPath, { force });
+    });
+  return program;
+}