From 766530ce56d78a2134bac5222d243f4c9c0274bc Mon Sep 17 00:00:00 2001 From: Alvaro Rodriguez Date: Mon, 18 Sep 2023 12:00:16 +0200 Subject: [PATCH 1/2] Added documentation for artifact files --- docs/docs/dev_docs/contracts/artifacts.md | 107 ++++++++++++++++++++++ docs/docs/dev_docs/contracts/compiling.md | 2 +- docs/sidebars.js | 1 + 3 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 docs/docs/dev_docs/contracts/artifacts.md diff --git a/docs/docs/dev_docs/contracts/artifacts.md b/docs/docs/dev_docs/contracts/artifacts.md new file mode 100644 index 00000000000..bd6cba20d41 --- /dev/null +++ b/docs/docs/dev_docs/contracts/artifacts.md @@ -0,0 +1,107 @@ +# Contract artifacts + +After compiling a contract you'll get a Contract Artifact file, that contains the data needed to interact with a specific contract, including its name, functions that can be executed, and the interface and code of those functions. Since private functions are not published in the Aztec network, you'll need this artifact file to be able to call private functions of contracts. + +The artifact file can be used with `aztec.js` to instantiate contract objects and interact with them. + +## Contract Artifact Structure + +The structure of a contract artifact is as follows: +```json +{ + "name": "CardGame", + "functions": [ + { + "name": "constructor", + "functionType": "secret", + "isInternal": false, + "parameters": [], + "returnTypes": [], + "bytecode": "...", + "verificationKey": "..." + }, + { + "name": "on_card_played", + "functionType": "open", + "isInternal": true, + "parameters": [ + { + "name": "game", + "type": { + "kind": "integer", + "sign": "unsigned", + "width": 32 + }, + "visibility": "private" + }, + { + "name": "player", + "type": { + "kind": "field" + }, + "visibility": "private" + }, + { + "name": "card_as_field", + "type": { + "kind": "field" + }, + "visibility": "private" + } + ], + "returnTypes": [ + ... + ], + "bytecode": "...", + "verificationKey": "..." + }, + ... + ] +} + +``` + +### Contract Name +It is a simple string that matches the name that the contract developer used for this contract in noir. It's used for logs and errors. + +### Functions +A contract is a collection of several functions that can be called. Each function has the following properties: + +#### Name +A simple string that matches the name that the contract developer used for this function in noir. For logging and debugging purposes. + +#### Function Type +The functionType can have one of the following values: + +- Secret: The function is ran and proved locally by the clients, and its bytecode not published to the network. +- Open: The function is ran and proved by the sequencer, and its bytecode is published to the network. +- Unconstrained: The function is ran locally by the clients to generate digested information useful for the user. It's not meant to be transacted against. + +#### Internal Flag +The isInternal property is a boolean that indicates whether the function is internal to the contract and cannot be called from outside. + +#### Parameters +Each function can have multiple parameters that are arguments to execute the function. Parameters have a name, and type (like integers, strings, or complex types like arrays and structures). + +#### Return Types +The returnTypes property defines the types of values that the function returns after execution. + +#### Bytecode +The bytecode is a string representing the compiled ACIR of the function, ready for execution on the network. + +#### Verification Key (Optional) +The verificationKey is an optional property that contains the verification key of the function. This key is used to verify the proof of the function execution. + +### Debug Metadata (Optional) +Although not significant for non-developer users, it is worth mentioning that there is a debug section in the contract artifact which helps contract developers to debug and test their contracts. This section mainly contains debug symbols and file maps that link back to the original source code. + +## Understanding Parameter and Return Types +To make the most of the functions, it's essential to understand the types of parameters and return values. Here are some common types you might encounter: + + - Field: A basic type representing a field element in the finite field of the curve used in the Aztec protocol. + - Boolean: A simple true/false value. + - Integer: Represents whole numbers. It has attributes defining its sign (positive or negative) and width (the number of bits representing the integer). + - Array: Represents a collection of elements, all of the same type. It has attributes defining its length and the type of elements it holds. + - String: Represents a sequence of characters with a specified length. + - Struct: A complex type representing a structure with various fields, each having a specific type and name. + diff --git a/docs/docs/dev_docs/contracts/compiling.md b/docs/docs/dev_docs/contracts/compiling.md index 845ffdf645e..0ea0be008ea 100644 --- a/docs/docs/dev_docs/contracts/compiling.md +++ b/docs/docs/dev_docs/contracts/compiling.md @@ -31,7 +31,7 @@ Then run the `compile` command with the path to your [contract project folder](. aztec-cli compile ./path/to/my_aztec_contract_project ``` -This will output a JSON artifact for each contract in the project to a `target` folder containing their [ABI](./abi.md), which you can use for deploying or interacting with your contracts. +This will output a JSON [artifact](./artifacts.md) for each contract in the project to a `target` folder containing their [ABI](./abi.md), which you can use for deploying or interacting with your contracts. ### Typescript Interfaces diff --git a/docs/sidebars.js b/docs/sidebars.js index b45e933b025..9ff2f5e8f32 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -104,6 +104,7 @@ const sidebars = { "dev_docs/contracts/constrain", "dev_docs/contracts/compiling", "dev_docs/contracts/deploying", + "dev_docs/contracts/artifacts", "dev_docs/contracts/abi", { label: "Portals", From 2e0939fd5ff81a1f01682b43a132b4b4fa82a326 Mon Sep 17 00:00:00 2001 From: Alvaro Rodriguez Date: Mon, 18 Sep 2023 14:12:27 +0200 Subject: [PATCH 2/2] use literal names of properties --- docs/docs/dev_docs/contracts/artifacts.md | 40 +++++++++++------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/docs/dev_docs/contracts/artifacts.md b/docs/docs/dev_docs/contracts/artifacts.md index bd6cba20d41..975b65e6eb4 100644 --- a/docs/docs/dev_docs/contracts/artifacts.md +++ b/docs/docs/dev_docs/contracts/artifacts.md @@ -61,47 +61,47 @@ The structure of a contract artifact is as follows: ``` -### Contract Name +### `name` It is a simple string that matches the name that the contract developer used for this contract in noir. It's used for logs and errors. -### Functions +### `functions` A contract is a collection of several functions that can be called. Each function has the following properties: -#### Name +#### `function.name` A simple string that matches the name that the contract developer used for this function in noir. For logging and debugging purposes. -#### Function Type -The functionType can have one of the following values: +#### `function.functionType` +The function type can have one of the following values: - Secret: The function is ran and proved locally by the clients, and its bytecode not published to the network. - Open: The function is ran and proved by the sequencer, and its bytecode is published to the network. - Unconstrained: The function is ran locally by the clients to generate digested information useful for the user. It's not meant to be transacted against. -#### Internal Flag -The isInternal property is a boolean that indicates whether the function is internal to the contract and cannot be called from outside. +#### `function.isInternal` +The is internal property is a boolean that indicates whether the function is internal to the contract and cannot be called from outside. -#### Parameters +#### `function.parameters` Each function can have multiple parameters that are arguments to execute the function. Parameters have a name, and type (like integers, strings, or complex types like arrays and structures). -#### Return Types -The returnTypes property defines the types of values that the function returns after execution. +#### `function.returnTypes` +The return types property defines the types of values that the function returns after execution. -#### Bytecode +#### `function.bytecode` The bytecode is a string representing the compiled ACIR of the function, ready for execution on the network. -#### Verification Key (Optional) -The verificationKey is an optional property that contains the verification key of the function. This key is used to verify the proof of the function execution. +#### `function.verificationKey` +The verification key is an optional property that contains the verification key of the function. This key is used to verify the proof of the function execution. -### Debug Metadata (Optional) +### `debug` (Optional) Although not significant for non-developer users, it is worth mentioning that there is a debug section in the contract artifact which helps contract developers to debug and test their contracts. This section mainly contains debug symbols and file maps that link back to the original source code. ## Understanding Parameter and Return Types To make the most of the functions, it's essential to understand the types of parameters and return values. Here are some common types you might encounter: - - Field: A basic type representing a field element in the finite field of the curve used in the Aztec protocol. - - Boolean: A simple true/false value. - - Integer: Represents whole numbers. It has attributes defining its sign (positive or negative) and width (the number of bits representing the integer). - - Array: Represents a collection of elements, all of the same type. It has attributes defining its length and the type of elements it holds. - - String: Represents a sequence of characters with a specified length. - - Struct: A complex type representing a structure with various fields, each having a specific type and name. + - `field`: A basic type representing a field element in the finite field of the curve used in the Aztec protocol. + - `boolean`: A simple true/false value. + - `integer`: Represents whole numbers. It has attributes defining its sign (positive or negative) and width (the number of bits representing the integer). + - `array`: Represents a collection of elements, all of the same type. It has attributes defining its length and the type of elements it holds. + - `string`: Represents a sequence of characters with a specified length. + - `struct`: A complex type representing a structure with various fields, each having a specific type and name.