From 6a44cf364559a4a431798aa86396025513e87e21 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Mon, 17 Feb 2025 13:18:56 +0100 Subject: [PATCH 1/8] initial --- docs/docs/aztec/concepts/accounts/keys.md | 2 ++ .../aztec/smart_contracts/contract_classes.md | 7 ++++ .../smart_contracts/injecting_data/index.md | 8 +++++ .../smart_contracts/injecting_data/oracles.md | 34 +++++++++++++++++++ 4 files changed, 51 insertions(+) create mode 100644 docs/docs/aztec/smart_contracts/contract_classes.md create mode 100644 docs/docs/aztec/smart_contracts/injecting_data/index.md create mode 100644 docs/docs/aztec/smart_contracts/injecting_data/oracles.md diff --git a/docs/docs/aztec/concepts/accounts/keys.md b/docs/docs/aztec/concepts/accounts/keys.md index 89b1687ddce4..35424e666d62 100644 --- a/docs/docs/aztec/concepts/accounts/keys.md +++ b/docs/docs/aztec/concepts/accounts/keys.md @@ -132,3 +132,5 @@ App-siloed incoming viewing key also allows per-application auditability. A user Key rotation is the process of creating new signing keys to replace existing keys. By rotating encryption keys on a regular schedule or after specific events, you can reduce the potential consequences of the key being compromised. On Aztec, key rotation is impossible for nullifier keys, incoming viewing keys and address keys as all of them are embedded into the address and address is unchangeable. In the meanwhile, signing keys can be rotated. + +## Shared secrets \ No newline at end of file diff --git a/docs/docs/aztec/smart_contracts/contract_classes.md b/docs/docs/aztec/smart_contracts/contract_classes.md new file mode 100644 index 000000000000..b7d760244a39 --- /dev/null +++ b/docs/docs/aztec/smart_contracts/contract_classes.md @@ -0,0 +1,7 @@ +--- +title: Contract Classes +tags: [contracts, protocol] +sidebar_position: 0 +--- + +class vs instance \ No newline at end of file diff --git a/docs/docs/aztec/smart_contracts/injecting_data/index.md b/docs/docs/aztec/smart_contracts/injecting_data/index.md new file mode 100644 index 000000000000..49d68cc33f4c --- /dev/null +++ b/docs/docs/aztec/smart_contracts/injecting_data/index.md @@ -0,0 +1,8 @@ +--- +title: Injectinhg Data +tags: [functions, oracles, capsules] +--- + +There are multiple ways to inject data into smart contracts. + +capsules vs authwits vs args packing. Mention databus \ No newline at end of file diff --git a/docs/docs/aztec/smart_contracts/injecting_data/oracles.md b/docs/docs/aztec/smart_contracts/injecting_data/oracles.md new file mode 100644 index 000000000000..a564bf94b216 --- /dev/null +++ b/docs/docs/aztec/smart_contracts/injecting_data/oracles.md @@ -0,0 +1,34 @@ +--- +title: Oracles +tags: [functions, oracles] +--- + +This page goes over what oracles are in Aztec and how they work. + +Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../developers/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md). + +An oracle is something that allows us to get data from the outside world into our contracts. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account. + +While this is one type of oracle, the more general oracle, allows us to get any data into the contract. In the context of oracle functions or oracle calls in Aztec, it can essentially be seen as user-provided arguments, that can be fetched at any point in the circuit, and don't need to be an input parameter. + +**Why is this useful? Why don't just pass them as input parameters?** +In the world of EVM, you would just read the values directly from storage and call it a day. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you actually allowed to modify them. + +If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. A similar idea, applied to the authentication mechanism is used for the Authentication Witnesses that allow us to have a single function signature for any wallet implementation, see [AuthWit](../../concepts/advanced/authwit.md) for more information on this. + +Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure! + +`Aztec.nr` has a module dedicated to its oracles. If you are interested, you can view them by following the link below: +#include_code oracles-module /noir-projects/aztec-nr/aztec/src/oracle/mod.nr rust + +## Inbuilt oracles + +- [`debug_log`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/debug_log.nr) - Provides a couple of debug functions that can be used to log information to the console. Read more about debugging [here](../../../developers/reference/debugging/index.md). +- [`auth_witness`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/auth_witness.nr) - Provides a way to fetch the authentication witness for a given address. This is useful when building account contracts to support approve-like functionality. +- [`get_l1_to_l2_message`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/get_l1_to_l2_message.nr) - Useful for application that receive messages from L1 to be consumed on L2, such as token bridges or other cross-chain applications. +- [`notes`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/notes.nr) - Provides a lot of functions related to notes, such as fetches notes from storage etc, used behind the scenes for value notes and other pre-build note implementations. +- [`logs`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/logs.nr) - Provides the to log encrypted and unencrypted data. + +Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle). + +Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [popCapsule](../../../developers/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md). From 37eb2361aaa26717a7560fd0763e1fe6cf459d6e Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 18 Feb 2025 11:31:42 +0100 Subject: [PATCH 2/8] shared secrets and contract classes --- docs/docs/aztec/concepts/accounts/keys.md | 6 +++++- docs/docs/aztec/smart_contracts/contract_classes.md | 10 +++++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/docs/aztec/concepts/accounts/keys.md b/docs/docs/aztec/concepts/accounts/keys.md index 35424e666d62..251588b3884f 100644 --- a/docs/docs/aztec/concepts/accounts/keys.md +++ b/docs/docs/aztec/concepts/accounts/keys.md @@ -133,4 +133,8 @@ Key rotation is the process of creating new signing keys to replace existing key On Aztec, key rotation is impossible for nullifier keys, incoming viewing keys and address keys as all of them are embedded into the address and address is unchangeable. In the meanwhile, signing keys can be rotated. -## Shared secrets \ No newline at end of file +## Shared secrets + +Aztec uses the Elliptic Curve Diffie-Hellman (ECDH) method to allow two parties to securely create a shared secret without directly exchanging it. This shared secret encrypts private data to be shared with another party over the network, which enables private transactions without communicating with the other party outside of the network. + + diff --git a/docs/docs/aztec/smart_contracts/contract_classes.md b/docs/docs/aztec/smart_contracts/contract_classes.md index b7d760244a39..d6ac2f86bcd6 100644 --- a/docs/docs/aztec/smart_contracts/contract_classes.md +++ b/docs/docs/aztec/smart_contracts/contract_classes.md @@ -4,4 +4,12 @@ tags: [contracts, protocol] sidebar_position: 0 --- -class vs instance \ No newline at end of file +Aztec defines a difference between contract *classes* and contract *instances*. This can be compared to object oriented programming and is different from Ethereum, where every contract's bytecode is deployed to the network and has a unique address. + +## Contract classes + +A contract class defines the contract's bytecode and is uniquely identified by a hash. A contract class doesn't have its own storage or state, but is more of a template that outlines the contract's code. + +## Contract instances + +A contract instance is a deployed version of a contract class with its own storage and state. Each instance operates independently. This separation allows for multiple deployments of the same contract logic without interference between instances. From d269645d06a306f9fd75a104130414b1a7348e07 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 11 Mar 2025 12:47:22 -0300 Subject: [PATCH 3/8] injeting data --- .../smart_contracts/injecting_data/index.md | 26 +++++++++++++++++-- .../smart_contracts/injecting_data/oracles.md | 9 ++----- 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/docs/docs/aztec/smart_contracts/injecting_data/index.md b/docs/docs/aztec/smart_contracts/injecting_data/index.md index 49d68cc33f4c..ec479ac05346 100644 --- a/docs/docs/aztec/smart_contracts/injecting_data/index.md +++ b/docs/docs/aztec/smart_contracts/injecting_data/index.md @@ -1,8 +1,30 @@ --- -title: Injectinhg Data +title: Injecting Data tags: [functions, oracles, capsules] --- There are multiple ways to inject data into smart contracts. -capsules vs authwits vs args packing. Mention databus \ No newline at end of file +1. **Oracles** - fetching data from the outside world +2. **AuthWits (Authentication Witnesses)** - authorizing an arbitrary action (or piece of data) +3. **Capsules** - local data storage in the PXE + +## Oracles + +In the world of EVM, you can read data directly from storage. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you actually allowed to modify them. + +If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. See [oracles](./oracles.md) for more information. + +## Authentication Witnesses (authwit) + +The same mechanism used in oracles is also used for the Authentication Witnesses that allow us to have a single function signature for any wallet implementation. See [AuthWit](../../concepts/advanced/authwit.md) for more information on this. + +## Capsules + +Capsules are used to store data in the PXE and inject this data into smart contracts. They can be useful for arbitrary data that does not have a dedicated oracle. + +You can learn more about using capsules in contracts in the [reference docs](../../../developers/reference/smart_contract_reference/aztec-nr/aztec/oracle/capsules.md) + + + + diff --git a/docs/docs/aztec/smart_contracts/injecting_data/oracles.md b/docs/docs/aztec/smart_contracts/injecting_data/oracles.md index a564bf94b216..d84272761018 100644 --- a/docs/docs/aztec/smart_contracts/injecting_data/oracles.md +++ b/docs/docs/aztec/smart_contracts/injecting_data/oracles.md @@ -5,17 +5,12 @@ tags: [functions, oracles] This page goes over what oracles are in Aztec and how they work. -Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../developers/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md). +Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md). An oracle is something that allows us to get data from the outside world into our contracts. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account. While this is one type of oracle, the more general oracle, allows us to get any data into the contract. In the context of oracle functions or oracle calls in Aztec, it can essentially be seen as user-provided arguments, that can be fetched at any point in the circuit, and don't need to be an input parameter. -**Why is this useful? Why don't just pass them as input parameters?** -In the world of EVM, you would just read the values directly from storage and call it a day. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you actually allowed to modify them. - -If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. A similar idea, applied to the authentication mechanism is used for the Authentication Witnesses that allow us to have a single function signature for any wallet implementation, see [AuthWit](../../concepts/advanced/authwit.md) for more information on this. - Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure! `Aztec.nr` has a module dedicated to its oracles. If you are interested, you can view them by following the link below: @@ -31,4 +26,4 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle). -Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [popCapsule](../../../developers/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md). +Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [popCapsule](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md). From 7f14cad10a65318320674bd615f2300112eea95e Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 12 Mar 2025 11:06:00 -0300 Subject: [PATCH 4/8] nits --- .../aztec/smart_contracts/contract_classes.md | 2 +- .../smart_contracts/injecting_data/index.md | 2 +- .../aztec/smart_contracts/oracles/index.md | 34 ------------------- 3 files changed, 2 insertions(+), 36 deletions(-) delete mode 100644 docs/docs/aztec/smart_contracts/oracles/index.md diff --git a/docs/docs/aztec/smart_contracts/contract_classes.md b/docs/docs/aztec/smart_contracts/contract_classes.md index d6ac2f86bcd6..3762fbc87c5a 100644 --- a/docs/docs/aztec/smart_contracts/contract_classes.md +++ b/docs/docs/aztec/smart_contracts/contract_classes.md @@ -4,7 +4,7 @@ tags: [contracts, protocol] sidebar_position: 0 --- -Aztec defines a difference between contract *classes* and contract *instances*. This can be compared to object oriented programming and is different from Ethereum, where every contract's bytecode is deployed to the network and has a unique address. +Aztec defines a difference between contract *classes* and contract *instances*. This is different from Ethereum, where every contract's bytecode is deployed to the network and has a unique address. ## Contract classes diff --git a/docs/docs/aztec/smart_contracts/injecting_data/index.md b/docs/docs/aztec/smart_contracts/injecting_data/index.md index ec479ac05346..63035d0ab96a 100644 --- a/docs/docs/aztec/smart_contracts/injecting_data/index.md +++ b/docs/docs/aztec/smart_contracts/injecting_data/index.md @@ -6,7 +6,7 @@ tags: [functions, oracles, capsules] There are multiple ways to inject data into smart contracts. 1. **Oracles** - fetching data from the outside world -2. **AuthWits (Authentication Witnesses)** - authorizing an arbitrary action (or piece of data) +2. **Authwits (Authentication Witnesses)** - authorizing an arbitrary action (or piece of data) 3. **Capsules** - local data storage in the PXE ## Oracles diff --git a/docs/docs/aztec/smart_contracts/oracles/index.md b/docs/docs/aztec/smart_contracts/oracles/index.md deleted file mode 100644 index 60ef28b66101..000000000000 --- a/docs/docs/aztec/smart_contracts/oracles/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Oracle Functions -tags: [functions, oracles] ---- - -This page goes over what oracles are in Aztec and how they work. - -Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md). - -An oracle is something that allows us to get data from the outside world into our contracts. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account. - -While this is one type of oracle, the more general oracle, allows us to get any data into the contract. In the context of oracle functions or oracle calls in Aztec, it can essentially be seen as user-provided arguments, that can be fetched at any point in the circuit, and don't need to be an input parameter. - -**Why is this useful? Why don't just pass them as input parameters?** -In the world of EVM, you would just read the values directly from storage and call it a day. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you actually allowed to modify them. - -If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. A similar idea, applied to the authentication mechanism is used for the Authentication Witnesses that allow us to have a single function signature for any wallet implementation, see [AuthWit](../../concepts/advanced/authwit.md) for more information on this. - -Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure! - -`Aztec.nr` has a module dedicated to its oracles. If you are interested, you can view them by following the link below: -#include_code oracles-module /noir-projects/aztec-nr/aztec/src/oracle/mod.nr rust - -## Inbuilt oracles - -- [`debug_log`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/debug_log.nr) - Provides a couple of debug functions that can be used to log information to the console. Read more about debugging [here](../../../developers/reference/debugging/index.md). -- [`auth_witness`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/auth_witness.nr) - Provides a way to fetch the authentication witness for a given address. This is useful when building account contracts to support approve-like functionality. -- [`get_l1_to_l2_message`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/get_l1_to_l2_message.nr) - Useful for application that receive messages from L1 to be consumed on L2, such as token bridges or other cross-chain applications. -- [`notes`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/notes.nr) - Provides a lot of functions related to notes, such as fetches notes from storage etc, used behind the scenes for value notes and other pre-build note implementations. -- [`logs`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/logs.nr) - Provides the to log encrypted and unencrypted data. - -Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle). - -Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [capsules](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md). From e34a65dd893eaa23f8b2fd9dc757dff052d85fca Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 12 Mar 2025 11:07:04 -0300 Subject: [PATCH 5/8] nits --- docs/docs/aztec/concepts/accounts/keys.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/docs/aztec/concepts/accounts/keys.md b/docs/docs/aztec/concepts/accounts/keys.md index 120a1cfe9f7c..da479f13b0c8 100644 --- a/docs/docs/aztec/concepts/accounts/keys.md +++ b/docs/docs/aztec/concepts/accounts/keys.md @@ -155,6 +155,14 @@ On Aztec, key rotation is impossible for nullifier keys, incoming viewing keys a ## Shared secrets -Aztec uses the Elliptic Curve Diffie-Hellman (ECDH) method to allow two parties to securely create a shared secret without directly exchanging it. This shared secret encrypts private data to be shared with another party over the network, which enables private transactions without communicating with the other party outside of the network. +Aztec uses the Elliptic Curve Diffie-Hellman (ECDH) method to allow two parties to securely create a shared secret without directly exchanging it. + +ECDH works by each party generating a public-private key pair and exchanging public keys, then using their own private key and the other party’s public key to derive the same shared secret. Mathematically, if Alice has a private key `a` and public key `A = aG`, and Bob has a private key `b` and public key `B = bG` (where `G` is a generator point on the elliptic curve), they can both compute the shared secret as: + +``` +S = aB = a(bG) = b(aG) = bA +``` + +This shared secret encrypts private data to be shared with another party over the network, which enables private transactions without communicating with the other party outside of the network. From df18b0038613218af3e49e1935aa8d9fa76e1927 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 12 Mar 2025 11:08:38 -0300 Subject: [PATCH 6/8] nits --- docs/docs/aztec/smart_contracts/injecting_data/index.md | 4 ---- docs/docs/aztec/smart_contracts/injecting_data/oracles.md | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/docs/aztec/smart_contracts/injecting_data/index.md b/docs/docs/aztec/smart_contracts/injecting_data/index.md index 63035d0ab96a..52a8e6ab24a8 100644 --- a/docs/docs/aztec/smart_contracts/injecting_data/index.md +++ b/docs/docs/aztec/smart_contracts/injecting_data/index.md @@ -24,7 +24,3 @@ The same mechanism used in oracles is also used for the Authentication Witnesses Capsules are used to store data in the PXE and inject this data into smart contracts. They can be useful for arbitrary data that does not have a dedicated oracle. You can learn more about using capsules in contracts in the [reference docs](../../../developers/reference/smart_contract_reference/aztec-nr/aztec/oracle/capsules.md) - - - - diff --git a/docs/docs/aztec/smart_contracts/injecting_data/oracles.md b/docs/docs/aztec/smart_contracts/injecting_data/oracles.md index d84272761018..e8bfcb5c4174 100644 --- a/docs/docs/aztec/smart_contracts/injecting_data/oracles.md +++ b/docs/docs/aztec/smart_contracts/injecting_data/oracles.md @@ -26,4 +26,4 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle). -Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [popCapsule](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md). +Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [capsules](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md). From 8eb2f12452a90bd6b9ed7c23a63af39d2f3b1744 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Thu, 13 Mar 2025 03:49:53 +0900 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: josh crites --- docs/docs/aztec/smart_contracts/injecting_data/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/aztec/smart_contracts/injecting_data/index.md b/docs/docs/aztec/smart_contracts/injecting_data/index.md index 52a8e6ab24a8..db7c372413f6 100644 --- a/docs/docs/aztec/smart_contracts/injecting_data/index.md +++ b/docs/docs/aztec/smart_contracts/injecting_data/index.md @@ -11,7 +11,7 @@ There are multiple ways to inject data into smart contracts. ## Oracles -In the world of EVM, you can read data directly from storage. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you actually allowed to modify them. +In the world of EVM, you can read data directly from storage. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you know value that the commitments represent and that you are actually allowed to modify them. If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. See [oracles](./oracles.md) for more information. @@ -21,6 +21,6 @@ The same mechanism used in oracles is also used for the Authentication Witnesses ## Capsules -Capsules are used to store data in the PXE and inject this data into smart contracts. They can be useful for arbitrary data that does not have a dedicated oracle. +Capsules are used to store contract-scoped data in the PXE and inject this data into smart contracts. They can be useful for arbitrary data that does not have a dedicated oracle. You can learn more about using capsules in contracts in the [reference docs](../../../developers/reference/smart_contract_reference/aztec-nr/aztec/oracle/capsules.md) From 6721d2bc72ab2e6337013edfcc678ceabf20d992 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 12 Mar 2025 18:04:07 -0300 Subject: [PATCH 8/8] suugesstoins --- docs/docs/aztec/smart_contracts/injecting_data/index.md | 4 +--- docs/docs/aztec/smart_contracts/injecting_data/oracles.md | 8 +++++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/aztec/smart_contracts/injecting_data/index.md b/docs/docs/aztec/smart_contracts/injecting_data/index.md index db7c372413f6..6ea09a47683e 100644 --- a/docs/docs/aztec/smart_contracts/injecting_data/index.md +++ b/docs/docs/aztec/smart_contracts/injecting_data/index.md @@ -11,9 +11,7 @@ There are multiple ways to inject data into smart contracts. ## Oracles -In the world of EVM, you can read data directly from storage. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you know value that the commitments represent and that you are actually allowed to modify them. - -If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. See [oracles](./oracles.md) for more information. +An oracle is something that allows us to get data from the outside world into our contracts. Aztec has some inbuilt oracles that allow developers to access cross-chain messages, private logs, data about notes, and others. You can learn more about them [here](./oracles.md). ## Authentication Witnesses (authwit) diff --git a/docs/docs/aztec/smart_contracts/injecting_data/oracles.md b/docs/docs/aztec/smart_contracts/injecting_data/oracles.md index e8bfcb5c4174..c9b24ad92e36 100644 --- a/docs/docs/aztec/smart_contracts/injecting_data/oracles.md +++ b/docs/docs/aztec/smart_contracts/injecting_data/oracles.md @@ -7,11 +7,13 @@ This page goes over what oracles are in Aztec and how they work. Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md). -An oracle is something that allows us to get data from the outside world into our contracts. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account. +Oracles are used to fetch data from the outside world. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account. While this is one type of oracle, the more general oracle, allows us to get any data into the contract. In the context of oracle functions or oracle calls in Aztec, it can essentially be seen as user-provided arguments, that can be fetched at any point in the circuit, and don't need to be an input parameter. -Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure! +In the world of EVM, you can read data directly from storage. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you know value that the commitments represent and that you are actually allowed to modify them. We can instead fetch the notes with an oracle all. + +Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure. `Aztec.nr` has a module dedicated to its oracles. If you are interested, you can view them by following the link below: #include_code oracles-module /noir-projects/aztec-nr/aztec/src/oracle/mod.nr rust @@ -22,7 +24,7 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine - [`auth_witness`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/auth_witness.nr) - Provides a way to fetch the authentication witness for a given address. This is useful when building account contracts to support approve-like functionality. - [`get_l1_to_l2_message`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/get_l1_to_l2_message.nr) - Useful for application that receive messages from L1 to be consumed on L2, such as token bridges or other cross-chain applications. - [`notes`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/notes.nr) - Provides a lot of functions related to notes, such as fetches notes from storage etc, used behind the scenes for value notes and other pre-build note implementations. -- [`logs`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/logs.nr) - Provides the to log encrypted and unencrypted data. +- [`logs`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/logs.nr) - Provides the ability to log encrypted and unencrypted data. Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle).