From 008a987919904875d159e00f58249f5df32668f7 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 22 Nov 2023 22:40:57 +0600 Subject: [PATCH 1/9] core concepts page --- .../dev_docs/getting_started/core-concepts.md | 86 +++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/docs/dev_docs/getting_started/core-concepts.md diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md new file mode 100644 index 00000000000..3a379bfcc4c --- /dev/null +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -0,0 +1,86 @@ +--- +title: Core Concepts +--- + +This page outlines Aztec concepts that are essential for developers to understand. Reading and understanding these concepts will help you massively when you start to dive deeper into smart contracts. + +A little bit of time here can save a lot down the road. + +# Aztec Overview + +TODO diagram + +To sum this up: +1. A user interacts with Aztec through Aztec.js (like web3js or ethersjs) or Aztec CLI +2. Private functions are executed in the PXE, which is client-side +3. They are rolled up and sent to the Public VM +4. Public functions are executed in the Public VM +5. The Public VM rolls up the private & public transaction rollups +6. These rollups are submitted to Ethereum + +## Composability between private and public state + +The PXE is unaware of the Public VM. And the Public VM is unaware of the PXE. They are completely separate execution environments. This means: + +* The PXE and the Public VM cannot directly communicate with each other +* Private transactions in the PXE are executed first, followed by public transactions + +You can call a public transaction from a private transaction by using this: + +TODO include code + +You cannot call a private transaction from a public transaction, but you can use an append-only merkle tree to save messages from a public function call. These can later be executed by a private function. + +TODO include code if we have anything + +### Data types + +Private state works with UTXOs, or what we call notes. To keep things private, everything is stored in an append-only UTXO tree, and a nullifier is created when notes are spent. + +TODO diagram maybe + +Public state works similarly to other chains like Ethereum, behaving more like a public ledger. + +Working with private state is like creating commitments and nullifiers, whereas working with public state is like directly updating state. + +We have abstractions for working with private state so you don't have to worry about these commitments and nullifiers. However, it is important to understand that the types and libraries you use will be different when working with private state and public state. + +For example, let's say you're trying to work with an integer. We have a library called `EasyPrivateUint` that acts like an int but in the background is actually updating notes in private state. For the public side, we instead have something called `SafeU120`. You cannot use EasyPrivateUint in a public environment, and you cannot use SafeU120 in a private environment. + +# Storage + +Currently, when writing Aztec.nr smart contracts, you will need to define two things when initiating storage: + +1. The storage struct, ie what you are storing and their types +2. A storage `impl` block with `init` function that will be called when you use the storage in a function + +The storage struct looks like this: + +TODO include code + +The storage impl block looks like this: + +TODO include code + +The `init` function must declare the storage struct with an instantiation defining how variables are accessed and manipulated. Each variable must be given a storage slot, which can be anything except 0. + +The impl block is likely to be abstracted away at a later date. + +# Portals + +Aztec allows you to interact with Ethereum privately - ie no-one knows where the transaction is coming from, just that it is coming from somewhere on Aztec. + +This is achieved through portals - these are smart contracts written in Solidity that are related to the Ethereum smart contract you want to interact with. + +A portal can be associated with multiple Aztec contracts, but an Aztec contract can only be associated with one portal. + +# Account Abstraction + +Every account in Aztec is a smart contract. This allows implementing different schemes for transaction signing, nonce management, and fee payments. + +You can write your own account contract to define the rules by which user transactions are authorized and paid for, as well as how user keys are managed. + +# Noir Language +Aztec smart contracts are written in a framework on top of Noir, the zero-knowledge domain-specific language developed specifically for Aztec. It is similar to Rust. Outside of Aztec, Noir is used for writing circuits that can be verified in Solidity. + +You do not need to understand Noir to write Aztec contracts. However, it may be useful to reference the [Noir docs](https://noir-lang.org) when you start writing more advanced contracts. \ No newline at end of file From 58fc8a7c14b90f7d3ee87fb03788bcb3724ec964 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Mon, 27 Nov 2023 13:25:36 +0600 Subject: [PATCH 2/9] sidebar and include_code --- .../dev_docs/getting_started/core-concepts.md | 26 +++++++++++-------- docs/sidebars.js | 1 + .../contracts/card_game_contract/src/main.nr | 2 ++ 3 files changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md index 3a379bfcc4c..dbc19cdde26 100644 --- a/docs/docs/dev_docs/getting_started/core-concepts.md +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -2,13 +2,15 @@ title: Core Concepts --- +import Image from '@theme/IdealImage'; + This page outlines Aztec concepts that are essential for developers to understand. Reading and understanding these concepts will help you massively when you start to dive deeper into smart contracts. A little bit of time here can save a lot down the road. # Aztec Overview -TODO diagram + To sum this up: 1. A user interacts with Aztec through Aztec.js (like web3js or ethersjs) or Aztec CLI @@ -25,20 +27,17 @@ The PXE is unaware of the Public VM. And the Public VM is unaware of the PXE. Th * The PXE and the Public VM cannot directly communicate with each other * Private transactions in the PXE are executed first, followed by public transactions -You can call a public transaction from a private transaction by using this: - -TODO include code +You can call a public function from a private function by using this: -You cannot call a private transaction from a public transaction, but you can use an append-only merkle tree to save messages from a public function call. These can later be executed by a private function. +#include_code call_public_function yarn-project/noir-contracts/src/contracts/card_game_contract/src/main.nr rust -TODO include code if we have anything +You cannot call a private function from a public function, but you can use a +slow updates tree to read and write to public state from a private function. ### Data types Private state works with UTXOs, or what we call notes. To keep things private, everything is stored in an append-only UTXO tree, and a nullifier is created when notes are spent. -TODO diagram maybe - Public state works similarly to other chains like Ethereum, behaving more like a public ledger. Working with private state is like creating commitments and nullifiers, whereas working with public state is like directly updating state. @@ -56,11 +55,11 @@ Currently, when writing Aztec.nr smart contracts, you will need to define two th The storage struct looks like this: -TODO include code +#include_code storage_struct yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust The storage impl block looks like this: -TODO include code +#include_code storage_init yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust The `init` function must declare the storage struct with an instantiation defining how variables are accessed and manipulated. Each variable must be given a storage slot, which can be anything except 0. @@ -83,4 +82,9 @@ You can write your own account contract to define the rules by which user transa # Noir Language Aztec smart contracts are written in a framework on top of Noir, the zero-knowledge domain-specific language developed specifically for Aztec. It is similar to Rust. Outside of Aztec, Noir is used for writing circuits that can be verified in Solidity. -You do not need to understand Noir to write Aztec contracts. However, it may be useful to reference the [Noir docs](https://noir-lang.org) when you start writing more advanced contracts. \ No newline at end of file +You do not need to understand Noir to write Aztec contracts. However, it may be useful to reference the [Noir docs](https://noir-lang.org) when you start writing more advanced contracts. + +Now you're ready to dive into coding: + +1. [Learn how to interact with a smart contract in Aztec.js](./aztecjs-getting-started.md) +2. [Write your first Aztec smart contract](./aztecnr-getting-started.md) \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index 5dcccb9c8d1..cf0523153b1 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -208,6 +208,7 @@ const sidebars = { }, items: [ "dev_docs/getting_started/quickstart", + "dev_docs/getting_started/core-concepts", "dev_docs/getting_started/aztecjs-getting-started", "dev_docs/getting_started/aztecnr-getting-started", ], diff --git a/yarn-project/noir-contracts/src/contracts/card_game_contract/src/main.nr b/yarn-project/noir-contracts/src/contracts/card_game_contract/src/main.nr index aa01e597e91..9136189202b 100644 --- a/yarn-project/noir-contracts/src/contracts/card_game_contract/src/main.nr +++ b/yarn-project/noir-contracts/src/contracts/card_game_contract/src/main.nr @@ -159,9 +159,11 @@ contract CardGame { game_deck.remove_cards([card], player); let selector = compute_selector("on_card_played(u32,Field,Field)"); + // docs:start:call_public_function context.call_public_function(context.this_address(), selector, [game as Field, player, card.to_field()]); + // docs:end:call_public_function } #[aztec(public)] From 35885cbda0a6e9b101f77cff16707bd99a83cc85 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 28 Nov 2023 07:15:00 +0000 Subject: [PATCH 3/9] Update docs/docs/dev_docs/getting_started/core-concepts.md Co-authored-by: josh crites --- docs/docs/dev_docs/getting_started/core-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md index dbc19cdde26..a8ee3a353d2 100644 --- a/docs/docs/dev_docs/getting_started/core-concepts.md +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -27,7 +27,7 @@ The PXE is unaware of the Public VM. And the Public VM is unaware of the PXE. Th * The PXE and the Public VM cannot directly communicate with each other * Private transactions in the PXE are executed first, followed by public transactions -You can call a public function from a private function by using this: +You can call a public function from a private function by using `context.call_public_function`, like this: #include_code call_public_function yarn-project/noir-contracts/src/contracts/card_game_contract/src/main.nr rust From 061f37220ae3113e5f9d4ab4e86e32c188cd5489 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 28 Nov 2023 07:15:09 +0000 Subject: [PATCH 4/9] Update docs/docs/dev_docs/getting_started/core-concepts.md Co-authored-by: josh crites --- docs/docs/dev_docs/getting_started/core-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md index a8ee3a353d2..fb4aa7287b1 100644 --- a/docs/docs/dev_docs/getting_started/core-concepts.md +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -32,7 +32,7 @@ You can call a public function from a private function by using `context.call_pu #include_code call_public_function yarn-project/noir-contracts/src/contracts/card_game_contract/src/main.nr rust You cannot call a private function from a public function, but you can use a -slow updates tree to read and write to public state from a private function. +slow updates tree to read historic public state and stage writes to public state from a private function. ### Data types From 1d57ce091409e4320632b62e56d2e621ae13a7e2 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 28 Nov 2023 07:15:14 +0000 Subject: [PATCH 5/9] Update docs/docs/dev_docs/getting_started/core-concepts.md Co-authored-by: josh crites --- docs/docs/dev_docs/getting_started/core-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md index fb4aa7287b1..af00bcea765 100644 --- a/docs/docs/dev_docs/getting_started/core-concepts.md +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -40,7 +40,7 @@ Private state works with UTXOs, or what we call notes. To keep things private, e Public state works similarly to other chains like Ethereum, behaving more like a public ledger. -Working with private state is like creating commitments and nullifiers, whereas working with public state is like directly updating state. +Working with private state is creates commitments and nullifiers to state, whereas working with public state is like directly updating state. We have abstractions for working with private state so you don't have to worry about these commitments and nullifiers. However, it is important to understand that the types and libraries you use will be different when working with private state and public state. From 30320ea8babd8e62275ef730e475256e898596e2 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 28 Nov 2023 07:15:20 +0000 Subject: [PATCH 6/9] Update docs/docs/dev_docs/getting_started/core-concepts.md Co-authored-by: josh crites --- docs/docs/dev_docs/getting_started/core-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md index af00bcea765..e4c0b2b67f2 100644 --- a/docs/docs/dev_docs/getting_started/core-concepts.md +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -82,7 +82,7 @@ You can write your own account contract to define the rules by which user transa # Noir Language Aztec smart contracts are written in a framework on top of Noir, the zero-knowledge domain-specific language developed specifically for Aztec. It is similar to Rust. Outside of Aztec, Noir is used for writing circuits that can be verified in Solidity. -You do not need to understand Noir to write Aztec contracts. However, it may be useful to reference the [Noir docs](https://noir-lang.org) when you start writing more advanced contracts. +A cursory understanding of Noir is sufficient for writing Aztec contracts. The [Noir docs](https://noir-lang.org) will be a helpful reference when you start writing more advanced contracts. Now you're ready to dive into coding: From 5e0d29e636779c04e5e49ad109f155a192efea98 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 28 Nov 2023 07:15:36 +0000 Subject: [PATCH 7/9] Update docs/docs/dev_docs/getting_started/core-concepts.md Co-authored-by: josh crites --- docs/docs/dev_docs/getting_started/core-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md index e4c0b2b67f2..8c932a324f9 100644 --- a/docs/docs/dev_docs/getting_started/core-concepts.md +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -44,7 +44,7 @@ Working with private state is creates commitments and nullifiers to state, where We have abstractions for working with private state so you don't have to worry about these commitments and nullifiers. However, it is important to understand that the types and libraries you use will be different when working with private state and public state. -For example, let's say you're trying to work with an integer. We have a library called `EasyPrivateUint` that acts like an int but in the background is actually updating notes in private state. For the public side, we instead have something called `SafeU120`. You cannot use EasyPrivateUint in a public environment, and you cannot use SafeU120 in a private environment. +For example, let's say you're trying to work with an integer. We have a library called `EasyPrivateUint` that acts like an integer but in the background is actually updating notes in private state. For the public side, we instead have something called `SafeU120`. You cannot use EasyPrivateUint in a public environment, and you cannot use SafeU120 in a private environment. # Storage From 53a84105529a07f40253b34fcd867dc5a368b530 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 28 Nov 2023 13:19:23 +0600 Subject: [PATCH 8/9] addressed josh's comments --- docs/docs/dev_docs/getting_started/core-concepts.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md index 8c932a324f9..91b2997a24b 100644 --- a/docs/docs/dev_docs/getting_started/core-concepts.md +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -65,6 +65,8 @@ The `init` function must declare the storage struct with an instantiation defini The impl block is likely to be abstracted away at a later date. +Learn more about how to use storage [here](../contracts/syntax/storage/main.md). + # Portals Aztec allows you to interact with Ethereum privately - ie no-one knows where the transaction is coming from, just that it is coming from somewhere on Aztec. @@ -73,14 +75,18 @@ This is achieved through portals - these are smart contracts written in Solidity A portal can be associated with multiple Aztec contracts, but an Aztec contract can only be associated with one portal. +Learn more about how to work with portals [here](../contracts/portals/main.md). + # Account Abstraction Every account in Aztec is a smart contract. This allows implementing different schemes for transaction signing, nonce management, and fee payments. You can write your own account contract to define the rules by which user transactions are authorized and paid for, as well as how user keys are managed. +Learn more about account contracts [here](../../concepts/foundation/accounts/main.md). + # Noir Language -Aztec smart contracts are written in a framework on top of Noir, the zero-knowledge domain-specific language developed specifically for Aztec. It is similar to Rust. Outside of Aztec, Noir is used for writing circuits that can be verified in Solidity. +Aztec smart contracts are written in a framework on top of Noir, the zero-knowledge domain-specific language developed specifically for Aztec. Its syntax is similar to Rust. Outside of Aztec, Noir is used for writing circuits that can be verified in Solidity. A cursory understanding of Noir is sufficient for writing Aztec contracts. The [Noir docs](https://noir-lang.org) will be a helpful reference when you start writing more advanced contracts. From 251afa2fe0dbe1a191659de10710d85fec7eb933 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 28 Nov 2023 18:52:38 +0600 Subject: [PATCH 9/9] small typo fixes --- docs/docs/dev_docs/getting_started/core-concepts.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/dev_docs/getting_started/core-concepts.md b/docs/docs/dev_docs/getting_started/core-concepts.md index 91b2997a24b..e22e1d3a04d 100644 --- a/docs/docs/dev_docs/getting_started/core-concepts.md +++ b/docs/docs/dev_docs/getting_started/core-concepts.md @@ -31,8 +31,7 @@ You can call a public function from a private function by using `context.call_pu #include_code call_public_function yarn-project/noir-contracts/src/contracts/card_game_contract/src/main.nr rust -You cannot call a private function from a public function, but you can use a -slow updates tree to read historic public state and stage writes to public state from a private function. +You cannot call a private function from a public function, but you can use a slow updates tree to read historic public state and stage writes to public state from a private function. ### Data types @@ -40,7 +39,7 @@ Private state works with UTXOs, or what we call notes. To keep things private, e Public state works similarly to other chains like Ethereum, behaving more like a public ledger. -Working with private state is creates commitments and nullifiers to state, whereas working with public state is like directly updating state. +Working with private state is like creating commitments and nullifiers to state, whereas working with public state is like directly updating state. We have abstractions for working with private state so you don't have to worry about these commitments and nullifiers. However, it is important to understand that the types and libraries you use will be different when working with private state and public state. @@ -86,6 +85,7 @@ You can write your own account contract to define the rules by which user transa Learn more about account contracts [here](../../concepts/foundation/accounts/main.md). # Noir Language + Aztec smart contracts are written in a framework on top of Noir, the zero-knowledge domain-specific language developed specifically for Aztec. Its syntax is similar to Rust. Outside of Aztec, Noir is used for writing circuits that can be verified in Solidity. A cursory understanding of Noir is sufficient for writing Aztec contracts. The [Noir docs](https://noir-lang.org) will be a helpful reference when you start writing more advanced contracts.