@aztec-labs/stdlib 6.0.0-nightly.20260829

package/dest/abi/contract_artifact.js

@@ -0,0 +1,278 @@
+import { jsonParseWithSchema, jsonStringify } from '@aztec-labs/foundation/json-rpc';
+import { AZTEC_INITIALIZER_ATTRIBUTE, AZTEC_ONLY_SELF_ATTRIBUTE, AZTEC_PRIVATE_ATTRIBUTE, AZTEC_PUBLIC_ATTRIBUTE, AZTEC_UTILITY_ATTRIBUTE, AZTEC_VIEW_ATTRIBUTE } from '../noir/index.js';
+import { ARTIFACT_VERSION_BEFORE_INJECTION, ContractArtifactSchema, FunctionType } from './abi.js';
+/**
+ * Serializes a contract artifact to a buffer for storage.
+ * @param artifact - Artifact to serialize.
+ * @returns A buffer.
+ */ export function contractArtifactToBuffer(artifact) {
+    return Buffer.from(jsonStringify(artifact), 'utf-8');
+}
+/**
+ * Deserializes a contract artifact from storage.
+ * @param buffer - Buffer to deserialize.
+ * @returns Deserialized artifact.
+ */ export function contractArtifactFromBuffer(buffer) {
+    return jsonParseWithSchema(buffer.toString('utf-8'), ContractArtifactSchema);
+}
+/**
+ * Gets nargo build output and returns a valid contract artifact instance.
+ * Does not include public bytecode, apart from the public_dispatch function.
+ * @param input - Input object as generated by nargo compile.
+ * @returns A valid contract artifact instance.
+ */ export function loadContractArtifact(input) {
+    if (isContractArtifact(input)) {
+        // TODO(F-557): Remove this fallback once pre-version artifacts are no longer tested.
+        if (!input.aztecVersion) {
+            return {
+                ...input,
+                aztecVersion: ARTIFACT_VERSION_BEFORE_INJECTION
+            };
+        }
+        return input;
+    }
+    return generateContractArtifact(input);
+}
+/**
+ * Gets nargo build output and returns a valid contract artifact instance.
+ * Differs from loadContractArtifact() by retaining all bytecode.
+ * @param input - Input object as generated by nargo compile.
+ * @returns A valid contract artifact instance.
+ */ export function loadContractArtifactForPublic(input) {
+    return generateContractArtifactForPublic(input);
+}
+/**
+ * Checks if the given input looks like a valid ContractArtifact. The check is not exhaustive,
+ * and it's just meant to differentiate between nargo raw build artifacts and the ones
+ * produced by this compiler.
+ * @param input - Input object.
+ * @returns True if it looks like a ContractArtifact.
+ */ function isContractArtifact(input) {
+    if (typeof input !== 'object') {
+        return false;
+    }
+    const maybeContractArtifact = input;
+    if (typeof maybeContractArtifact.name !== 'string') {
+        return false;
+    }
+    if (!Array.isArray(maybeContractArtifact.functions)) {
+        return false;
+    }
+    for (const fn of maybeContractArtifact.functions){
+        if (typeof fn.name !== 'string') {
+            return false;
+        }
+        if (typeof fn.functionType !== 'string') {
+            return false;
+        }
+        if (!retainBytecode(fn) && fn.bytecode.length) {
+            // We want to remove the bytecode of public fns (apart from the dispatch fn) to save space
+            // If the input is private-only, we don't need to use generateContractArtifact() below
+            return false;
+        }
+    }
+    if (!Array.isArray(maybeContractArtifact.nonDispatchPublicFunctions)) {
+        return false;
+    }
+    for (const fn of maybeContractArtifact.nonDispatchPublicFunctions){
+        if (typeof fn.name !== 'string') {
+            return false;
+        }
+        if (typeof fn.functionType !== 'string') {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Generates a function parameter out of one generated by a nargo build.
+ * @param param - Noir parameter.
+ * @returns A function parameter.
+ */ function generateFunctionParameter(param) {
+    const { visibility } = param;
+    if (visibility === 'databus') {
+        throw new Error(`Unsupported visibility ${param.visibility} for noir contract function parameter ${param.name}.`);
+    }
+    return {
+        ...param,
+        visibility: visibility
+    };
+}
+/**
+ * Returns true if we should retain bytecode
+ */ export function retainBytecode(input) {
+    const functionType = input.functionType ?? getFunctionType(input);
+    return functionType !== FunctionType.PUBLIC || input.name == 'public_dispatch';
+}
+/**
+ * Generates a function abi.
+ * @param fn - Noir function entry.
+ * @param contract - Parent contract.
+ * @returns Function abi.
+ */ function generateFunctionAbi(fn, contract) {
+    if (fn.custom_attributes === undefined) {
+        throw new Error(`No custom attributes found for contract function ${fn.name}. Try rebuilding the contract with the latest nargo version.`);
+    }
+    const functionType = getFunctionType(fn);
+    const isOnlySelf = fn.custom_attributes.includes(AZTEC_ONLY_SELF_ATTRIBUTE);
+    const isStatic = fn.custom_attributes.includes(AZTEC_VIEW_ATTRIBUTE);
+    // If the function is not a utility function, the first item is inputs or CallContext which we should omit
+    let parameters = fn.abi.parameters.map(generateFunctionParameter);
+    if (hasKernelFunctionInputs(parameters)) {
+        parameters = parameters.slice(1);
+    }
+    let returnType;
+    if (functionType === FunctionType.UTILITY) {
+        returnType = fn.abi.return_type?.abi_type;
+    } else {
+        const pathToFind = `${contract.name}::${fn.name}_abi`;
+        const abiStructs = contract.outputs.structs['functions'];
+        const returnStruct = abiStructs.find((a)=>a.kind === 'struct' && a.path === pathToFind);
+        if (returnStruct) {
+            if (returnStruct.kind !== 'struct') {
+                throw new Error('Could not generate contract function artifact');
+            }
+            returnType = returnStruct.fields.find((field)=>field.name === 'return_type')?.type;
+        }
+    }
+    return {
+        name: fn.name,
+        functionType,
+        isOnlySelf,
+        isStatic,
+        isInitializer: fn.custom_attributes.includes(AZTEC_INITIALIZER_ATTRIBUTE),
+        parameters,
+        returnType,
+        // Old consumers expect `returnTypes` property, not `returnType`. So we write both down for now, until we can
+        // safely remove the old version.
+        returnTypes: returnType ? [
+            returnType
+        ] : [],
+        errorTypes: fn.abi.error_types,
+        ...fn.assert_messages ? {
+            assertMessages: fn.assert_messages
+        } : undefined
+    };
+}
+/**
+ * Generates a function build artifact.
+ * @param fn - Noir function entry.
+ * @param contract - Parent contract.
+ * @returns Function artifact.
+ */ function generateFunctionArtifact(fn, contract) {
+    const abi = generateFunctionAbi(fn, contract);
+    return {
+        ...abi,
+        bytecode: fn.bytecode,
+        debugSymbols: fn.debug_symbols,
+        ...fn.verification_key ? {
+            verificationKey: fn.verification_key
+        } : undefined
+    };
+}
+function getFunctionType(fn) {
+    if (fn.custom_attributes.includes(AZTEC_PRIVATE_ATTRIBUTE)) {
+        return FunctionType.PRIVATE;
+    } else if (fn.custom_attributes.includes(AZTEC_PUBLIC_ATTRIBUTE)) {
+        return FunctionType.PUBLIC;
+    } else if (fn.custom_attributes.includes(AZTEC_UTILITY_ATTRIBUTE)) {
+        return FunctionType.UTILITY;
+    } else {
+        throw new Error(`Invalid function type for a noir contract function ${fn.name}`);
+    }
+}
+/**
+ * Returns true if the first parameter is kernel function inputs.
+ *
+ * Noir macros #[aztec(private|public)] inject the following code
+ * fn <name>(inputs: <Public|Private>ContextInputs, ...otherparams) {}
+ *
+ * Return true if this injected parameter is found
+ */ function hasKernelFunctionInputs(params) {
+    const firstParam = params[0];
+    return firstParam?.type.kind === 'struct' && firstParam.type.path.includes('ContextInputs');
+}
+/**
+ * Generates a storage layout for the contract artifact.
+ * @param contractName - The name of the compiled Noir contract.
+ * @param globals - The globals exported by the contract.
+ * @returns A storage layout for the contract.
+ */ function getStorageLayout(contractName, globals) {
+    // If another contract is imported by the main contract, its storage layout its going to also show up here.
+    // The layout export includes the contract name, so here we can find the one that belongs to the current one and
+    // ignore the rest.
+    const storageExports = globals.storage?.map((entry)=>entry.value) ?? [];
+    const storageForContract = storageExports.find((storageExport)=>{
+        if (storageExport.kind !== 'struct') {
+            return false;
+        }
+        const contractNameField = storageExport.fields.find((field)=>field.name === 'contract_name')?.value;
+        return contractNameField.value === contractName;
+    });
+    const storageFields = storageForContract ? storageForContract.fields.find((field)=>field.name == 'fields').value.fields : [];
+    if (storageFields.length === 0) {
+        return {};
+    }
+    return storageFields.reduce((acc, field)=>{
+        const name = field.name;
+        const slot = field.value.fields[0].value;
+        acc[name] = {
+            slot: `0x${slot.value}`
+        };
+        return acc;
+    }, {});
+}
+/**
+ * Returns the globals exported by the contract under an `#[abi(tag)]` attribute, keyed by global name.
+ * An unknown tag yields an empty record. Throws if two globals under the same tag share a name.
+ */ export function getGlobalsByTag(artifact, tag) {
+    const globals = new Map();
+    for (const entry of artifact.outputs.globals[tag] ?? []){
+        if (globals.has(entry.name)) {
+            throw new Error(`Duplicate global '${entry.name}' exported under #[abi(${tag})] in contract ${artifact.name}`);
+        }
+        globals.set(entry.name, entry.value);
+    }
+    return Object.fromEntries(globals);
+}
+/**
+ * Given a post-processed Nargo output defined as `contract` generates an Aztec-compatible contract artifact.
+ *
+ * Does not include public bytecode, apart from the public_dispatch function.
+ */ function generateContractArtifact(contract) {
+    try {
+        if (!contract.transpiled) {
+            throw new Error("Contract's public bytecode has not been transpiled");
+        }
+        return ContractArtifactSchema.parse({
+            name: contract.name,
+            aztecVersion: contract.aztec_version,
+            functions: contract.functions.filter((f)=>retainBytecode(f)).map((f)=>generateFunctionArtifact(f, contract)),
+            nonDispatchPublicFunctions: contract.functions.filter((f)=>!retainBytecode(f)).map((f)=>generateFunctionAbi(f, contract)),
+            outputs: contract.outputs,
+            storageLayout: getStorageLayout(contract.name, contract.outputs.globals),
+            fileMap: contract.file_map
+        });
+    } catch (err) {
+        throw new Error(`Could not generate contract artifact for ${contract.name}: ${err}`);
+    }
+}
+/**
+ * Given a post-processed Nargo output defined as `contract` generates an Aztec-compatible contract artifact.
+ *
+ * Retains all public bytecode.
+ */ function generateContractArtifactForPublic(contract) {
+    try {
+        return ContractArtifactSchema.parse({
+            name: contract.name,
+            aztecVersion: contract.aztec_version,
+            functions: contract.functions.map((f)=>generateFunctionArtifact(f, contract)),
+            nonDispatchPublicFunctions: contract.functions.filter((f)=>!retainBytecode(f)).map((f)=>generateFunctionAbi(f, contract)),
+            outputs: contract.outputs,
+            storageLayout: getStorageLayout(contract.name, contract.outputs.globals),
+            fileMap: contract.file_map
+        });
+    } catch (err) {
+        throw new Error(`Could not generate contract artifact for ${contract.name}: ${err}`);
+    }
+}

package/dest/abi/decoder.d.ts

@@ -0,0 +1,26 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { AztecAddress } from '../aztec-address/index.js';
+import type { AbiType } from './abi.js';
+import { FunctionSelector } from './function_selector.js';
+/**
+ * The type of our decoded ABI.
+ */
+export type AbiDecoded = bigint | boolean | string | AztecAddress | EthAddress | FunctionSelector | Fr | AbiDecoded[] | {
+    [key: string]: AbiDecoded;
+} | undefined;
+/**
+ * Decodes the single value a function returns, or undefined if it returns nothing. Multiple return values are expressed
+ * as one `tuple` type, so they decode through here too.
+ * @param type - The type the function returns.
+ * @param buffer - The flattened Field array to decode.
+ */
+export declare function decodeFromAbi(type: AbiType | undefined, buffer: Fr[]): AbiDecoded;
+/**
+ * Decodes one value per given type, consumed from the buffer in order. Always returns one decoded value per type, so
+ * callers can index the result positionally. A function's arguments are encoded this way.
+ * @param types - The type of each value, in order.
+ * @param buffer - The flattened Field array to decode.
+ */
+export declare function decodeEachFromAbi(types: AbiType[], buffer: Fr[]): AbiDecoded[];
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVjb2Rlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FiaS9kZWNvZGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSxxQ0FBcUMsQ0FBQztBQUN6RCxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sb0NBQW9DLENBQUM7QUFFaEUsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLDJCQUEyQixDQUFDO0FBQ3pELE9BQU8sS0FBSyxFQUFFLE9BQU8sRUFBRSxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQVUxRDs7R0FFRztBQUNILE1BQU0sTUFBTSxVQUFVLEdBQ2xCLE1BQU0sR0FDTixPQUFPLEdBQ1AsTUFBTSxHQUNOLFlBQVksR0FDWixVQUFVLEdBQ1YsZ0JBQWdCLEdBQ2hCLEVBQUUsR0FDRixVQUFVLEVBQUUsR0FDWjtJQUFFLENBQUMsR0FBRyxFQUFFLE1BQU0sR0FBRyxVQUFVLENBQUE7Q0FBRSxHQUM3QixTQUFTLENBQUM7QUE4RmQ7Ozs7O0dBS0c7QUFDSCx3QkFBZ0IsYUFBYSxDQUFDLElBQUksRUFBRSxPQUFPLEdBQUcsU0FBUyxFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsR0FBRyxVQUFVLENBRWpGO0FBRUQ7Ozs7O0dBS0c7QUFDSCx3QkFBZ0IsaUJBQWlCLENBQUMsS0FBSyxFQUFFLE9BQU8sRUFBRSxFQUFFLE1BQU0sRUFBRSxFQUFFLEVBQUUsR0FBRyxVQUFVLEVBQUUsQ0FHOUUifQ==

package/dest/abi/decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../../src/abi/decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,qCAAqC,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAU1D;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,OAAO,GACP,MAAM,GACN,YAAY,GACZ,UAAU,GACV,gBAAgB,GAChB,EAAE,GACF,UAAU,EAAE,GACZ;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,GAC7B,SAAS,CAAC;AA8Fd;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,UAAU,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,UAAU,EAAE,CAG9E"}

package/dest/abi/decoder.js

@@ -0,0 +1,112 @@
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { AztecAddress } from '../aztec-address/index.js';
+import { FunctionSelector } from './function_selector.js';
+import { isAztecAddressStruct, isEthAddressStruct, isFunctionSelectorStruct, isOptionStruct, isWrappedFieldStruct, parseSignedInt } from './utils.js';
+/**
+ * Decodes values using a provided ABI.
+ */ class AbiDecoder {
+    flattened;
+    constructor(flattened){
+        this.flattened = flattened;
+    }
+    /**
+   * Decodes a single value from field to the given type.
+   * @param abiType - The type of the value.
+   * @returns The decoded value.
+   */ decodeNext(abiType) {
+        switch(abiType.kind){
+            case 'field':
+                return this.getNextField().toBigInt();
+            case 'integer':
+                {
+                    const nextField = this.getNextField();
+                    if (abiType.sign === 'signed') {
+                        // We parse the buffer using 2's complement
+                        return parseSignedInt(nextField.toBuffer(), abiType.width);
+                    }
+                    return nextField.toBigInt();
+                }
+            case 'boolean':
+                return !this.getNextField().isZero();
+            case 'array':
+                {
+                    const array = [];
+                    for(let i = 0; i < abiType.length; i += 1){
+                        array.push(this.decodeNext(abiType.type));
+                    }
+                    return array;
+                }
+            case 'struct':
+                {
+                    const struct = {};
+                    if (isAztecAddressStruct(abiType)) {
+                        return new AztecAddress(this.getNextField().toBuffer());
+                    }
+                    if (isEthAddressStruct(abiType)) {
+                        return EthAddress.fromField(this.getNextField());
+                    }
+                    if (isFunctionSelectorStruct(abiType)) {
+                        return FunctionSelector.fromField(this.getNextField());
+                    }
+                    if (isWrappedFieldStruct(abiType)) {
+                        return this.getNextField();
+                    }
+                    if (isOptionStruct(abiType)) {
+                        const isSome = this.decodeNext(abiType.fields[0].type);
+                        const value = this.decodeNext(abiType.fields[1].type);
+                        return isSome ? value : undefined;
+                    }
+                    for (const field of abiType.fields){
+                        struct[field.name] = this.decodeNext(field.type);
+                    }
+                    return struct;
+                }
+            case 'string':
+                {
+                    let str = '';
+                    for(let i = 0; i < abiType.length; i += 1){
+                        const charCode = Number(this.getNextField().toBigInt());
+                        str += String.fromCharCode(charCode);
+                    }
+                    return str;
+                }
+            case 'tuple':
+                {
+                    const array = [];
+                    for (const tupleAbiType of abiType.fields){
+                        array.push(this.decodeNext(tupleAbiType));
+                    }
+                    return array;
+                }
+            default:
+                throw new Error(`Unsupported type: ${abiType}`);
+        }
+    }
+    /**
+   * Gets the next field in the flattened buffer.
+   * @returns The next field in the flattened buffer.
+   */ getNextField() {
+        const field = this.flattened.shift();
+        if (!field) {
+            throw new Error('Not enough return values');
+        }
+        return field;
+    }
+}
+/**
+ * Decodes the single value a function returns, or undefined if it returns nothing. Multiple return values are expressed
+ * as one `tuple` type, so they decode through here too.
+ * @param type - The type the function returns.
+ * @param buffer - The flattened Field array to decode.
+ */ export function decodeFromAbi(type, buffer) {
+    return type === undefined ? undefined : new AbiDecoder(buffer.slice()).decodeNext(type);
+}
+/**
+ * Decodes one value per given type, consumed from the buffer in order. Always returns one decoded value per type, so
+ * callers can index the result positionally. A function's arguments are encoded this way.
+ * @param types - The type of each value, in order.
+ * @param buffer - The flattened Field array to decode.
+ */ export function decodeEachFromAbi(types, buffer) {
+    const decoder = new AbiDecoder(buffer.slice());
+    return types.map((type)=>decoder.decodeNext(type));
+}

package/dest/abi/encoder.d.ts

@@ -0,0 +1,16 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { FunctionAbi } from './abi.js';
+/**
+ * Encodes all the arguments for a function call.
+ * @param abi - The function ABI entry.
+ * @param args - The arguments to encode.
+ * @returns The encoded arguments.
+ */
+export declare function encodeArguments(abi: FunctionAbi, args: any[]): Fr[];
+/**
+ * Returns the size of the arguments for a function ABI.
+ * @param abi - The function ABI entry.
+ * @returns The size of the arguments.
+ */
+export declare function countArgumentsSize(abi: FunctionAbi): number;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW5jb2Rlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FiaS9lbmNvZGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSxxQ0FBcUMsQ0FBQztBQUV6RCxPQUFPLEtBQUssRUFBVyxXQUFXLEVBQUUsTUFBTSxVQUFVLENBQUM7QUFpVHJEOzs7OztHQUtHO0FBQ0gsd0JBQWdCLGVBQWUsQ0FBQyxHQUFHLEVBQUUsV0FBVyxFQUFFLElBQUksRUFBRSxHQUFHLEVBQUUsUUFFNUQ7QUFFRDs7OztHQUlHO0FBQ0gsd0JBQWdCLGtCQUFrQixDQUFDLEdBQUcsRUFBRSxXQUFXLFVBRWxEIn0=

package/dest/abi/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/abi/encoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,qCAAqC,CAAC;AAEzD,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,UAAU,CAAC;AAiTrD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,QAE5D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,UAElD"}