-
-See [this diagram](https://raw.githubusercontent.com/AztecProtocol/aztec-packages/2fa143e4d88b3089ebbe2a9e53645edf66157dc8/docs/static/img/sandbox_sending_a_tx.svg) for a more detailed overview of the transaction execution process. It highlights 3 different types of transaction execution: contract deployments, private transactions and public transactions.
-
-See the page on [contract communication](../smart_contracts/functions/public_private_calls.md) for more context on transaction execution.
-
-### Transaction Requests
-
-Transaction requests are how transactions are constructed and sent to the network.
-
-In Aztec.js:
-
-```javascript title="constructor" showLineNumbers
-constructor(
- /** Sender. */
- public origin: AztecAddress,
- /** Function data representing the function to call. */
- public functionData: FunctionData,
- /** Pedersen hash of function arguments. */
- public argsHash: Fr,
- /** Transaction context. */
- public txContext: TxContext,
-) {}
-```
-
-> Source code: yarn-project/stdlib/src/tx/tx_request.ts#L15-L26
-
-Where:
-
-- `origin` is the account contract where the transaction is initiated from.
-- `functionData` contains the function selector and indicates whether the function is private or public.
-- `argsHash` is the hash of the arguments of all of the calls to be executed. The complete set of arguments is passed to the PXE as part of the [TxExecutionRequest](https://github.com/AztecProtocol/aztec-packages/blob/alpha-testnet/yarn-project/stdlib/src/tx/tx_execution_request.ts) and checked against this hash.
-- `txContext` contains the chain id, version, and gas settings.
-
-The `functionData` includes an `AppPayload`, which includes information about the application functions and arguments, and a `FeePayload`, which includes info about how to pay for the transaction.
-
-An account contract validates that the transaction request has been authorized via its specified authorization mechanism, via the `is_valid_impl` function (e.g. [an ECDSA signature](https://github.com/AztecProtocol/aztec-packages/blob/alpha-testnet/noir-projects/noir-contracts/contracts/account/ecdsa_k_account_contract/src/main.nr#L56-L57), generated [in JS](https://github.com/AztecProtocol/aztec-packages/blob/alpha-testnet/yarn-project/accounts/src/ecdsa/ecdsa_k/account_contract.ts#L30)).
-
-Transaction requests are simulated in the PXE in order to generate the necessary inputs for generating proofs. Once transactions are proven, a [transaction object](https://github.com/AztecProtocol/aztec-packages/blob/alpha-testnet/yarn-project/stdlib/src/tx/tx.ts#L26) is created and can be sent to the network to be included in a block.
-
-#### Contract Interaction Methods
-
-Most transaction requests are created as interactions with specific contracts. The exception is transactions that deploy contracts. Here are the main methods for interacting with contracts related to transactions.
-
-1. [`create`](#create)
-2. [`simulate`](#simulate)
-3. [`prove`](#prove)
-4. [`send`](#send)
-
-And fee utilities:
-
-- [`estimateGas`](#estimategas)
-- [`getFeeOptions`](#getfeeoptions)
-
-##### `create`
-
-```javascript title="create" showLineNumbers
-/**
- * Create a transaction execution request that represents this call, encoded and authenticated by the
- * user's wallet, ready to be simulated.
- * @param options - An optional object containing additional configuration for the transaction.
- * @returns A Promise that resolves to a transaction instance.
- */
-public override async create(options: SendMethodOptions = {}): Promise
-
-2. Storage contract address
-
- - This value is the address of the current context's contract address. This value will be the value of the current contract that is being executed except for when the current call is a delegate call (Warning: This is yet to be implemented). In this case the value will be that of the sending contract.
-
-3. Flags
- - Furthermore there are a series of flags that are stored within the application context:
- - is_delegate_call: Denotes whether the current call is a delegate call. If true, then the storage contract address will be the address of the sender.
- - is_static_call: This will be set if and only if the current call is a static call. In a static call, state changing altering operations are not allowed.
-
-### Block Header
-
-Another structure that is contained within the context is the `BlockHeader` object, which is the header of the block used to generate proofs against.
-
-```rust title="block-header" showLineNumbers
-pub struct BlockHeader {
- pub last_archive: AppendOnlyTreeSnapshot,
- pub content_commitment: ContentCommitment,
- pub state: StateReference,
- pub global_variables: GlobalVariables,
- pub total_fees: Field,
- pub total_mana_used: Field,
-}
-```
-
-> Source code: noir-projects/noir-protocol-circuits/crates/types/src/block_header.nr#L11-L20
-
-### Transaction Context
-
-The private context provides access to the transaction context as well, which are user-defined values for the transaction in general that stay constant throughout its execution.
-
-```rust title="tx-context" showLineNumbers
-pub struct TxContext {
- pub chain_id: Field,
- pub version: Field,
- pub gas_settings: GasSettings,
-}
-```
-
-> Source code: noir-projects/noir-protocol-circuits/crates/types/src/transaction/tx_context.nr#L8-L14
-
-### Args Hash
-
-To allow for flexibility in the number of arguments supported by Aztec functions, all function inputs are reduced to a singular value which can be proven from within the application.
-
-The `args_hash` is the result of pedersen hashing all of a function's inputs.
-
-### Return Values
-
-The return values are a set of values that are returned from an applications execution to be passed to other functions through the kernel. Developers do not need to worry about passing their function return values to the `context` directly as `Aztec.nr` takes care of it for you. See the documentation surrounding `Aztec.nr` [macro expansion](./attributes.md#after-expansion) for more details.
-
-```rust
-return_values : BoundedVec\calling transfer(Alice, Defi, 1000); - activate Alice - Alice-->>Alice: Produces Authentication witness - Alice-->>AC: AuthWit for transfer(Alice, Defi, 1000); - AC->>Token: AuthWit validity - deactivate Alice - Token->>Token: throw if invalid AuthWit - Token->>Token: transfer(Alice, Defi, 1000); - Token->>Defi: success - deactivate Token - Defi->>Defi: deposit(Token, 1000); - deactivate Defi - deactivate AC -``` - -:::info -Note in particular that the request for a witness is done by the token contract, and the user will have to provide it to the contract before it can continue execution. Since the request is made all the way into the contract where it is to be used, we don't need to pass it along as an extra input to the functions before it which gives us a cleaner interface. -::: - -As part of `AuthWit` we are assuming that the `on_behalf_of` implements the private function: - -```rust -#[private] -fn verify_private_authwit(inner_hash: Field) -> Field; -``` - -For public authwit, we have a shared registry that is used, there we are using a `consume` function. - -Both return the value `0xabf64ad4` (`IS_VALID` selector) for a successful authentication, and `0x00000000` for a failed authentication. You might be wondering why we are expecting the return value to be a selector instead of a boolean. This is mainly to account for a case of selector collisions where the same selector is used for different functions, and we don't want an account to mistakenly allow a different function to be called on its behalf - it is hard to return the selector by mistake, but you might have other functions returning a bool. - -## The `AuthWit` library. - -As part of Aztec.nr, we are providing a library that can be used to implement authentication witness for your contracts. - -This library also provides a basis for account implementations such that these can more easily implement authentication witness. - -For our purposes here (not building a wallet), the most important part of the library is the `auth` utility which exposes a couple of helper methods for computing the action hash, retrieving witnesses, validating them and emitting the nullifier. - -### General utilities - -The primary general utility is the `compute_authwit_message_hash_from_call` function which computes the action hash from its components. This is useful for when you need to generate a hash that is not for the current call, such as when you want to update a public approval state value that is later used for [authentication in public](#updating-approval-state-in-noir). You can view the implementation of this function [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/auth.nr). - -#### TypeScript utilities - -To make it convenient to compute the message hashes in TypeScript, the `aztec.js` package includes a `computeAuthWitMessageHash` function that you can use. Implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/utils/authwit.ts). - -### Utilities for private calls - -For private calls where we allow execution on behalf of others, we generally want to check if the current call is authenticated by `on_behalf_of`. To easily do so, we can use the `assert_current_call_valid_authwit` which fetches information from the current context without us needing to provide much beyond the `on_behalf_of`. - -This function will then make a call to `on_behalf_of` to execute the `verify_private_authwit` function which validates that the call is authenticated. -The `on_behalf_of` should assert that we are indeed authenticated and then return the `IS_VALID` selector. If the return value is not as expected, we throw an error. This is to cover the case where the `on_behalf_of` might implemented some function with the same selector as the `verify_private_authwit` that could be used to authenticate unintentionally. - -#### Example - -```rust title="assert_current_call_valid_authwit" showLineNumbers -if (!from.eq(context.msg_sender())) { - assert_current_call_valid_authwit(&mut context, from); -} else { - assert(nonce == 0, "invalid nonce"); -} -``` - -> Source code: noir-projects/noir-contracts/contracts/app/token_contract/src/main.nr#L366-L372 - -### Utilities for public calls - -Very similar to the above, we have variations that work in the public domain (`assert_current_call_valid_authwit_public`). These functions are wrapped to give a similar flow for both cases, but behind the scenes the logic is slightly different since the public goes to the auth registry, while the private flow calls the account contract. - -#### Example - -```rust title="assert_current_call_valid_authwit_public" showLineNumbers -if (!from.eq(context.msg_sender())) { - assert_current_call_valid_authwit_public(&mut context, from); -} else { - assert(nonce == 0, "invalid nonce"); -} -``` - -> Source code: noir-projects/noir-contracts/contracts/app/token_contract/src/main.nr#L226-L232 - -## Usage - -Ok, enough talking, how do we use this? - -### Importing it - -To add it to your project, add the `authwit` library to your `Nargo.toml` file. - -```toml -[dependencies] -aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="alpha-testnet", directory="noir-projects/aztec-nr/aztec" } -authwit = { git="https://github.com/AztecProtocol/aztec-packages/", tag="alpha-testnet", directory="noir-projects/aztec-nr/authwit"} -``` - -Then you will be able to import it into your contracts as follows. - -```rust title="import_authwit" showLineNumbers -use dep::authwit::auth::{ - assert_current_call_valid_authwit, assert_current_call_valid_authwit_public, - compute_authwit_nullifier, -}; -``` - -> Source code: noir-projects/noir-contracts/contracts/app/token_contract/src/main.nr#L40-L45 - -### Private Functions - -#### Checking if the current call is authenticated - -Based on the diagram earlier on this page let's take a look at how we can implement the `transfer` function such that it checks if the tokens are to be transferred `from` the caller or needs to be authenticated with an authentication witness. - -```rust title="transfer_in_private" showLineNumbers -#[private] -fn transfer_in_private(from: AztecAddress, to: AztecAddress, amount: u128, nonce: Field) { - if (!from.eq(context.msg_sender())) { - assert_current_call_valid_authwit(&mut context, from); - } else { - assert(nonce == 0, "invalid nonce"); - } - - storage.balances.at(from).sub(from, amount).emit(encode_and_encrypt_note( - &mut context, - from, - from, - )); - storage.balances.at(to).add(to, amount).emit(encode_and_encrypt_note(&mut context, to, from)); -} -``` - -> Source code: noir-projects/noir-contracts/contracts/app/token_contract/src/main.nr#L363-L383 - -The first thing we see in the snippet above, is that if `from` is not the call we are calling the `assert_current_call_valid_authwit` function from [earlier](#private-functions). If the call is not throwing, we are all good and can continue with the transfer. - -In the snippet we are constraining the `else` case such that only `nonce = 0` is supported. This is not strictly necessary, but because I can't stand dangling useless values. By making it constrained, we can limit what people guess it does, I hope. - -#### Authenticating an action in TypeScript - -Cool, so we have a function that checks if the current call is authenticated, but how do we actually authenticate it? Well, assuming that we use a wallet that is following the spec, we import `computeAuthWitMessageHash` from `aztec.js` to help us compute the hash, and then we simply `addAuthWitness` to the wallet. Behind the scenes this will make the witness available to the oracle. - -```typescript title="authwit_transfer_example" showLineNumbers -const action = asset - .withWallet(wallets[1]) - .methods.transfer_in_private( - accounts[0].address, - accounts[1].address, - amount, - nonce - ); - -const witness = await wallets[0].createAuthWit({ - caller: accounts[1].address, - action, -}); -expect( - await wallets[0].lookupValidity( - wallets[0].getAddress(), - { caller: accounts[1].address, action }, - witness - ) -).toEqual({ - isValidInPrivate: true, - isValidInPublic: false, -}); -``` - -> Source code: yarn-project/end-to-end/src/e2e_token_contract/transfer_in_private.test.ts#L32-L44 - -Learn more about authwits in Aztec.js by [following this guide](../../js_apps/authwit.md). - -### Public Functions - -With private functions covered, how can we use this in a public function? Well, the answer is that we simply change one name of a function and then we are good to go :eyes: (almost). - -#### Checking if the current call is authenticated - -```rust title="transfer_in_public" showLineNumbers -#[public] -fn transfer_in_public(from: AztecAddress, to: AztecAddress, amount: u128, nonce: Field) { - if (!from.eq(context.msg_sender())) { - assert_current_call_valid_authwit_public(&mut context, from); - } else { - assert(nonce == 0, "invalid nonce"); - } - let from_balance = storage.public_balances.at(from).read().sub(amount); - storage.public_balances.at(from).write(from_balance); - let to_balance = storage.public_balances.at(to).read().add(amount); - storage.public_balances.at(to).write(to_balance); -} -``` - -> Source code: noir-projects/noir-contracts/contracts/app/token_contract/src/main.nr#L208-L221 - -#### Authenticating an action in TypeScript - -Authenticating an action in the public domain is slightly different from the private domain, since we are executing a function on the auth registry contract to add the witness flag. As you might recall, this was to ensure that we don't need to call into the account contract from public, which is a potential DOS vector. - -In the snippet below, this is done as a separate contract call, but can also be done as part of a batch as mentioned in the [Accounts concepts](../../../../aztec/concepts/advanced/authwit.md#what-about-public). - -```typescript title="authwit_public_transfer_example" showLineNumbers -const action = asset - .withWallet(wallets[1]) - .methods.transfer_in_public( - accounts[0].address, - accounts[1].address, - amount, - nonce - ); - -const validateActionInteraction = await wallets[0].setPublicAuthWit( - { caller: accounts[1].address, action }, - true -); -await validateActionInteraction.send().wait(); -``` - -> Source code: yarn-project/end-to-end/src/e2e_token_contract/transfer_in_public.test.ts#L69-L76 - -#### Updating approval state in Noir - -We have cases where we need a non-wallet contract to approve an action to be executed by another contract. One of the cases could be when making more complex defi where funds are passed along. When doing so, we need the intermediate contracts to support approving of actions on their behalf. - -This is fairly straight forward to do using the `auth` library which includes logic for updating values in the public auth registry. Namely, you can prepare the `message_hash` using `compute_authwit_message_hash_from_call` and then simply feed it into the `set_authorized` function (both are in `auth` library) to update the value. - -When another contract later is consuming the authwit using `assert_current_call_valid_authwit_public` it will be calling the registry, and spend that authwit. - -An example of this would be our Uniswap example which performs a cross chain swap on L1. In here, we both do private and public auth witnesses, where the public is set by the uniswap L2 contract itself. In the below snippet, you can see that we compute the action hash and update the value in the registry. When we then call the `token_bridge` to execute afterwards, it reads this value, burns the tokens, and consumes the authentication. - -```rust title="authwit_uniswap_set" showLineNumbers -// This helper method approves the bridge to burn this contract's funds and exits the input asset to L1 -// Assumes contract already has funds. -// Assume `token` relates to `token_bridge` (ie token_bridge.token == token) -// Note that private can't read public return values so created an internal public that handles everything -// this method is used for both private and public swaps. -#[public] -#[internal] -fn _approve_bridge_and_exit_input_asset_to_L1( - token: AztecAddress, - token_bridge: AztecAddress, - amount: u128, -) { - // Since we will authorize and instantly spend the funds, all in public, we can use the same nonce - // every interaction. In practice, the authwit should be squashed, so this is also cheap! - let nonce = 0xdeadbeef; - - let selector = FunctionSelector::from_signature("burn_public((Field),u128,Field)"); - let message_hash = compute_authwit_message_hash_from_call( - token_bridge, - token, - context.chain_id(), - context.version(), - selector, - [context.this_address().to_field(), amount as Field, nonce], - ); - - // We need to make a call to update it. - set_authorized(&mut context, message_hash, true); - - let this_portal_address = storage.portal_address.read(); - // Exit to L1 Uniswap Portal ! - TokenBridge::at(token_bridge) - .exit_to_l1_public(this_portal_address, amount, this_portal_address, nonce) - .call(&mut context) -} -``` - -> Source code: noir-projects/noir-contracts/contracts/app/uniswap_contract/src/main.nr#L185-L221 - -Outlining more of the `swap` flow: this simplified diagram shows how it will look for contracts that are not wallets but also need to support authentication witnesses. - -```mermaid -sequenceDiagram - actor A as Alice - participant AC as Alice Account - participant CC as Crosschain Swap - participant TB as Token Bridge - participant T as Token - - A->>AC: Swap 1000 token A to B on Uniswap L1 - activate AC; - AC->>CC: Swap 1000 token A to B - activate CC; - CC->>T: Transfer to public 1000 tokens from Alice Account to CCS - activate T; - T->>AC: Have you approved this?? - AC-->>A: Please give me an AuthWit - A-->>AC: Here is AuthWit - AC-->>AC: Validate AuthWit - AC->>T: Yes - deactivate T; - CC-->>CC: Setting flag to true - CC->>TB: Exit 1000 tokens to CCS - activate TB; - TB->>T: Burn 1000 tokens from CCS - activate T; - T->>CC: Have you approved this? - CC->>T: Yes - T-->>T: Burn - Token->>Defi: success - deactivate T; - TB-->>TB: Emit L2->L1 message - deactivate TB; - CC-->>CC: Emit L2->L1 message - deactivate CC; - deactivate AC; -``` - -:::info **TODO** -Add a link to the blog-posts. -::: diff --git a/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/call_contracts.md b/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/call_contracts.md deleted file mode 100644 index eab00a664df2..000000000000 --- a/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/call_contracts.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Calling Other Contracts -sidebar_position: 4 -tags: [functions, contracts] ---- - -A contract is a collection of persistent state variables and functions which may manipulate these variables. - -Functions and state variables within a contract's scope are said to belong to that contract. A contract can only access and modify its own state. - -If a contract wishes to access or modify another contract's state, it must make a call to an external function of the other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called. - -### Add Contract as a Dependency - -Import the contract that you want to call into your `Nargo.toml` under `dependencies` like this: - -```toml -token = { git="https://github.com/AztecProtocol/aztec-packages/", tag="alpha-testnet", directory="noir-projects/noir-contracts/contracts/app/token_contract" } -``` - -### Import into your contract - -At the top of your contract, import the contract you want to call like this: - -```rust -use token::Token; -``` - -### Call the function - -To call the function, you need to - -- Specify the address of the contract with `Contract::at(contract_address)` -- Call the function name with `.function_name()` -- Pass the parameters into the function call, like `.function_name(param1,param2)` -- Specify the type of call you want to make and pass a mut reference to the context, like `.call(&mut context)` - -#### Private calls - -To call a private function, you can just use `call()` like this: - -```rust title="call_function" showLineNumbers -Token::at(token).transfer(recipient, amount).call(&mut context); -``` - -> Source code: noir-projects/noir-contracts/contracts/app/escrow_contract/src/main.nr#L45-L47 - -#### Public -> Public calls - -To call a public function from a public function, it is the same as above. You can just use `call()` like this: - -```rust title="public_to_public_call" showLineNumbers -let _ = Token::at(collateral_asset) - .transfer_in_public(context.msg_sender(), context.this_address(), amount, nonce) - .call(&mut context); -``` - -> Source code: noir-projects/noir-contracts/contracts/app/lending_contract/src/main.nr#L133-L137 - -#### Private -> Public calls - -To call a public function from private, you will need to enqueue it like this: - -```rust title="enqueue_public" showLineNumbers -Lending::at(context.this_address()) - ._deposit(AztecAddress::from_field(on_behalf_of), amount, collateral_asset) - .enqueue(&mut context); -``` - -> Source code: noir-projects/noir-contracts/contracts/app/lending_contract/src/main.nr#L119-L123 - -Public functions are always executed after private execution. To learn why, read the [concepts overview](../../../../aztec/index.md). - -#### Other call types - -There are other call types, for example to ensure no state changes are made. You can learn more about them in the [call types glossary](../../../../aztec/concepts/call_types.md). diff --git a/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/call_functions.md b/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/call_functions.md deleted file mode 100644 index eab00a664df2..000000000000 --- a/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/call_functions.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Calling Other Contracts -sidebar_position: 4 -tags: [functions, contracts] ---- - -A contract is a collection of persistent state variables and functions which may manipulate these variables. - -Functions and state variables within a contract's scope are said to belong to that contract. A contract can only access and modify its own state. - -If a contract wishes to access or modify another contract's state, it must make a call to an external function of the other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called. - -### Add Contract as a Dependency - -Import the contract that you want to call into your `Nargo.toml` under `dependencies` like this: - -```toml -token = { git="https://github.com/AztecProtocol/aztec-packages/", tag="alpha-testnet", directory="noir-projects/noir-contracts/contracts/app/token_contract" } -``` - -### Import into your contract - -At the top of your contract, import the contract you want to call like this: - -```rust -use token::Token; -``` - -### Call the function - -To call the function, you need to - -- Specify the address of the contract with `Contract::at(contract_address)` -- Call the function name with `.function_name()` -- Pass the parameters into the function call, like `.function_name(param1,param2)` -- Specify the type of call you want to make and pass a mut reference to the context, like `.call(&mut context)` - -#### Private calls - -To call a private function, you can just use `call()` like this: - -```rust title="call_function" showLineNumbers -Token::at(token).transfer(recipient, amount).call(&mut context); -``` - -> Source code: noir-projects/noir-contracts/contracts/app/escrow_contract/src/main.nr#L45-L47 - -#### Public -> Public calls - -To call a public function from a public function, it is the same as above. You can just use `call()` like this: - -```rust title="public_to_public_call" showLineNumbers -let _ = Token::at(collateral_asset) - .transfer_in_public(context.msg_sender(), context.this_address(), amount, nonce) - .call(&mut context); -``` - -> Source code: noir-projects/noir-contracts/contracts/app/lending_contract/src/main.nr#L133-L137 - -#### Private -> Public calls - -To call a public function from private, you will need to enqueue it like this: - -```rust title="enqueue_public" showLineNumbers -Lending::at(context.this_address()) - ._deposit(AztecAddress::from_field(on_behalf_of), amount, collateral_asset) - .enqueue(&mut context); -``` - -> Source code: noir-projects/noir-contracts/contracts/app/lending_contract/src/main.nr#L119-L123 - -Public functions are always executed after private execution. To learn why, read the [concepts overview](../../../../aztec/index.md). - -#### Other call types - -There are other call types, for example to ensure no state changes are made. You can learn more about them in the [call types glossary](../../../../aztec/concepts/call_types.md). diff --git a/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/common_patterns/index.md b/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/common_patterns/index.md deleted file mode 100644 index 184ccfe3fde6..000000000000 --- a/docs/versioned_docs/version-alpha-testnet/developers/guides/smart_contracts/writing_contracts/common_patterns/index.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: Common Patterns -sidebar_position: 7 ---- - -There are many common patterns have been devised by the Aztec core engineering team and the work of the external community as we build Aztec.nr contracts internally (see some of them [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts)). - -This doc aims to summarize some of them! - -Similarly we have discovered some anti-patterns too (like privacy leakage) that we will point out here! - -## Common Patterns - -### Approving another user/contract to execute an action on your behalf - -We call this the "authentication witness" pattern or authwit for short. - -- Approve someone in private domain: - -```typescript title="authwit_to_another_sc" showLineNumbers -// 4. Give approval to bridge to burn owner's funds: -const withdrawAmount = 9n; -const nonce = Fr.random(); -const burnAuthwit = await user1Wallet.createAuthWit({ - caller: l2Bridge.address, - action: l2Token.methods.burn_private(ownerAddress, withdrawAmount, nonce), -}); -``` - -> Source code: yarn-project/end-to-end/src/e2e_cross_chain_messaging/token_bridge_private.test.ts#L70-L78 - -Here you approve a contract to burn funds on your behalf. - -- Approve in public domain: - -```typescript title="authwit_public_transfer_example" showLineNumbers -const action = asset - .withWallet(wallets[1]) - .methods.transfer_in_public( - accounts[0].address, - accounts[1].address, - amount, - nonce - ); - -const validateActionInteraction = await wallets[0].setPublicAuthWit( - { caller: accounts[1].address, action }, - true -); -await validateActionInteraction.send().wait(); -``` - -> Source code: yarn-project/end-to-end/src/e2e_token_contract/transfer_in_public.test.ts#L69-L76 - -Here you approve someone to transfer funds publicly on your behalf - -### Prevent the same user flow from happening twice using nullifiers - -E.g. you don't want a user to subscribe once they have subscribed already. Or you don't want them to vote twice once they have done that. How do you prevent this? - -Emit a nullifier in your function. By adding this nullifier into the tree, you prevent another nullifier from being added again. This is also why in authwit, we emit a nullifier, to prevent someone from reusing their approval. - -```rust title="verify_private_authwit" showLineNumbers -pub fn verify_private_authwit(self, inner_hash: Field) -> Field { - // The `inner_hash` is "siloed" with the `msg_sender` to ensure that only it can - // consume the message. - // This ensures that contracts cannot consume messages that are not intended for them. - let message_hash = compute_authwit_message_hash( - self.context.msg_sender(), - self.context.chain_id(), - self.context.version(), - inner_hash, - ); - let valid_fn = self.is_valid_impl; - assert(valid_fn(self.context, message_hash) == true, "Message not authorized by account"); - IS_VALID_SELECTOR -} -``` - -> Source code: noir-projects/aztec-nr/authwit/src/account.nr#L71-L86 - -Note be careful to ensure that the nullifier is not deterministic and that no one could do a preimage analysis attack. More in [the anti pattern section on deterministic nullifiers](#deterministic-nullifiers) - -Note - you could also create a note and send it to the user. The problem is there is nothing stopping the user from not presenting this note when they next interact with the function. - -### Reading public storage in private - -You can read public storage in private domain by leveraging the private getters of `PublicImmutable` (for values that never change) and `SharedMutable` (for values that change infrequently, see [shared state](../../../../reference/smart_contract_reference/storage/shared_state.md) for details) state variables. -Values that change frequently (`PublicMutable`) cannot be read in private as for those we need access to the tip of the chain and only a sequencer has access to that (and sequencer executes only public functions). - -E.g. when using `PublicImmutable` - -```rust -#[storage] -struct Storage { - config: PublicImmutable
storage_slot: derived_slot, nonce: 0, note_hash_counter } - Utils->>UintNote: note_hiding_point = note.compute_note_hiding_point() - UintNote->>Utils: note_hash = note_hiding_point.x - LifeCycle->>Context: push_note_hash(note_hash) - end - Context->>Kernel: unique_note_hash = H(nonce, note_hash) - Context->>Kernel: siloed_note_hash = H(contract_address, unique_note_hash) -``` - -Notice the `siloed_note_hash` at the very end. It's a hash that will be inserted into the note hashes tree. To clarify what this really is, we "unroll" the values to their simplest components. This gives us a better idea around what is actually inserted into the tree. - -```rust -siloed_note_hash = H(contract_address, unique_note_hash) -siloed_note_hash = H(contract_address, H(nonce, note_hash)) -siloed_note_hash = H(contract_address, H(H(tx_hash, note_index_in_tx), note_hash)) -siloed_note_hash = H(contract_address, H(H(tx_hash, note_index_in_tx), MSM([G_amt, G_to, G_rand, G_slot], [amount, to, randomness, derived_slot]).x)) -``` - -MSM is a multi scalar multiplication on a grumpkin curve and G\_\* values are generators. - -And `to` is the actor who receives the note, `amount` of the note and `randomness` is the randomness used to make the note hiding. Without the `randomness` the note could just as well be plaintext (computational cost of a preimage attack would be trivial in such a case). - -:::info -Beware that this hash computation is what the aztec.nr library is doing, and not strictly required by the network (only the kernel computation is). -::: - -With this note structure, the contract can require that only notes sitting at specific storage slots can be used by specific operations, e.g., if transferring funds from `from` to `to`, the notes to destroy should be linked to `H(map_slot, from)` and the new notes (except the change-note) should be linked to `H(map_slot, to)`. - -That way, we can have logical storage slots, without them really existing. This means that knowing the storage slot for a note is not enough to actually figure out what is in there (whereas it would be for looking up public state). diff --git a/docs/versioned_docs/version-alpha-testnet/developers/index.md b/docs/versioned_docs/version-alpha-testnet/developers/index.md deleted file mode 100644 index aa692db11222..000000000000 --- a/docs/versioned_docs/version-alpha-testnet/developers/index.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -id: index -sidebar_position: 0 -title: Build ---- - -# Build - -## Get Started - -
-
-
-
-
- Get started on Aztec by installing the sandbox and playing with it
-
-
-
-
-## Build applications
-
-Getting Started
-
-
-
-
-
- Go from zero to hero by following these tutorials in order, starting with a counter contract
-
-
-
-
-
-
-
- Learn how everything works together by building an app in JavaScript that connects to a contract
-
-
-
-
-## Clone a repo
-
-Contract Tutorials
-Full stack app on Aztec
-
-
- Full stack app on Aztec
-
-
-
-
-
- Find requests for applications, potential designs, and existing ecosystem projects
-
-
-
diff --git a/docs/versioned_docs/version-alpha-testnet/developers/reference/considerations/limitations.md b/docs/versioned_docs/version-alpha-testnet/developers/reference/considerations/limitations.md
deleted file mode 100644
index 307badfae01b..000000000000
--- a/docs/versioned_docs/version-alpha-testnet/developers/reference/considerations/limitations.md
+++ /dev/null
@@ -1,157 +0,0 @@
----
-title: Limitations
-sidebar_position: 6
----
-
-The Aztec stack is a work in progress. Packages have been released early, to gather feedback on the capabilities of the protocol and user experiences.
-
-## What to expect?
-
-- Regular Breaking Changes;
-- Missing features;
-- Bugs;
-- An 'unpolished' UX;
-- Missing information.
-
-## Why participate?
-
-Front-run the future!
-
-Help shape and define:
-
-- Previously-impossible smart contracts and applications
-- Network tooling;
-- Network standards;
-- Smart contract syntax;
-- Educational content;
-- Core protocol improvements;
-
-## Limitations developers need to know about
-
-- It is a testing environment, it is insecure, and unaudited. It is only for testing purposes.
-- `msg_sender` is currently leaking when doing private -> public calls
- - The `msg_sender` will always be set, if you call a public function from the private world, the `msg_sender` will be set to the private caller's address.
- - There are patterns that can mitigate this.
-- The initial `msg_sender` is `-1`, which can be problematic for some contracts.
-- The number of side-effects attached to a tx (when sending the tx to the mempool) is leaky. At this stage of development, this is _intentional_, so that we can gauge appropriate choices for privacy sets. We have always had clear plans to implement privacy sets so that side effects are much less leaky, and these will be in place come mainnet.
-- A transaction can only emit a limited number of side-effects (notes, nullifiers, logs, l2->l1 messages), see [circuit limitations](#circuit-limitations).
- - We haven't settled on the final constants, since we're still in a testing phase. But users could find that certain compositions of nested private function calls (e.g. call stacks that are dynamic in size, based on runtime data) could accumulate so many side-effects as to exceed tx limits. Such txs would then be unprovable. We would love for you to open an issue if you encounter this, as it will help us decide on adequate sizes for our constants.
-- There are lots of features that we still want to implement. Checkout github and the forum for details. If you would like a feature, please open an issue on github!
-
-## WARNING
-
-Do not use real, meaningful secrets in Aztec's testnets. Some privacy features are still being worked on, including ensuring a secure "zk" property. Since the Aztec stack is still being worked on, there are no guarantees that real secrets will remain secret.
-
-## Limitations
-
-There are plans to resolve all of the below.
-
-### It is not audited
-
-None of the Aztec stack is audited. It's being iterated-on every day. It will not be audited for quite some time.
-
-### Under-constrained
-
-Some of our more-complex circuits are still being worked on, so they will still be be underconstrained.
-
-#### What are the consequences?
-
-Sound proofs are really only needed as a protection against malicious behavior, which we're not testing for at this stage.
-
-### Keys and Addresses are subject to change
-
-The way in which keypairs and addresses are derived is still being iterated on as we receive feedback.
-
-#### What are the consequences?
-
-This will impact the kinds of apps that you can build with the Sandbox, as it is today:
-
-Please open new discussions on [discourse](http://discourse.aztec.network) or open issues on [github](http://github.com/AztecProtocol/aztec-packages), if you have requirements that aren't-yet being met by the Sandbox's current key derivation scheme.
-
-### No privacy-preserving queries to nodes
-
-Ethereum has a notion of a 'full node' which keeps-up with the blockchain and stores the full chain state. Many users don't wish to run full nodes, so rely on 3rd-party 'full-node-as-a-service' infrastructure providers, who service blockchain queries from their users.
-
-This pattern is likely to develop in Aztec as well, except there's a problem: privacy. If a privacy-seeking user makes a query to a 3rd-party 'full node', that user might leak data about who they are, or about their historical network activity, or about their future intentions. One solution to this problem is "always run a full node", but pragmatically, not everyone will. To protect less-advanced users' privacy, research is underway to explore how a privacy-seeking user may request and receive data from a 3rd-party node without revealing what that data is, nor who is making the request.
-
-### No private data authentication
-
-Private data should not be returned to an app, unless the user authorizes such access to the app. An authorization layer is not-yet in place.
-
-#### What are the consequences?
-
-Any app can request and receive any private user data relating to any other private app. Obviously this sounds bad. But the Sandbox is a sandbox, and no meaningful value or credentials should be stored there; only test values and test credentials.
-
-An auth layer will be added in due course.
-
-### No bytecode validation
-
-For safety reasons, bytecode should not be executed unless the PXE/Wallet has validated that the user's intentions (the function signature and contract address) match the bytecode.
-
-#### What are the consequences?
-
-Without such 'bytecode validation', if the incorrect bytecode is executed, and that bytecode is malicious, it could read private data from some other contract and emit that private data to the world. Obviously this would be bad in production. But the Sandbox is a sandbox, and no meaningful value or credentials should be stored there; only test values and test credentials.
-
-There are plans to add bytecode validation soon.
-
-### Insecure hashes
-
-We are planning a full assessment of the protocol's hashes, including rigorous domain separation.
-
-#### What are the consequences?
-
-Collisions and other hash-related attacks might be possible in the Sandbox. Obviously that would be bad in production. But it's unlikely to cause problems at this early stage of testing.
-
-### `msg_sender` is leaked when making a private -> public call
-
-There are ongoing discussions [here](https://forum.aztec.network/t/what-is-msg-sender-when-calling-private-public-plus-a-big-foray-into-stealth-addresses/7527 (and some more recent discussions that need to be documented) around how to address this.
-
-### New Privacy Standards are required
-
-There are many [patterns](../../reference/considerations/privacy_considerations.md) which can leak privacy, even on Aztec. Standards haven't been developed yet, to encourage best practices when designing private smart contracts.
-
-#### What are the consequences?
-
-For example, until community standards are developed to reduce the uniqueness of ['Tx Fingerprints'](../../reference/considerations/privacy_considerations.md#function-fingerprints-and-tx-fingerprints) app developers might accidentally forfeit some function privacy.
-
-## Smart Contract limitations
-
-We will never be done with all the yummy features we want to add to aztec.nr. We have lots of features that we still want to implement. Please check out github, and please open new issues with any feature requests you might have.
-
-## Circuit limitations
-
-### Upper limits on function outputs and tx outputs
-
-Due to the rigidity of zk-SNARK circuits, there are upper bounds on the amount of computation a circuit can perform, and on the amount of data that can be passed into and out of a function.
-
-> Blockchain developers are no stranger to restrictive computational environments. Ethereum has gas limits, local variable stack limits, call stack limits, contract deployment size limits, log size limits, etc.
-
-Here are the current constants:
-
-#include_code constants /noir-projects/noir-protocol-circuits/crates/types/src/constants.nr rust
-
-#### What are the consequences?
-
-When you write an Aztec.nr function, there will be upper bounds on the following:
-
-- The number of public state reads and writes;
-- The number of note reads and nullifications;
-- The number of new notes that may be created;
-- The number of encrypted logs that may be emitted;
-- The number of unencrypted logs that may be emitted;
-- The number of L1->L2 messages that may be consumed;
-- The number of L2->L1 messages that may be submitted to L1;
-- The number of private function calls;
-- The number of public function calls that may be enqueued;
-
-Not only are there limits on a _per function_ basis, there are also limits on a _per transaction_ basis.
-
-**In particular, these _per-transaction_ limits will limit transaction call stack depths**. That means if a function call results in a cascade of nested function calls, and each of those function calls outputs lots of state reads and writes, or logs (etc.), then all of that accumulated output data might exceed the per-transaction limits that we currently have. This would cause such transactions to fail.
-
-There are plans to relax some of this rigidity, by providing many 'sizes' of circuit.
-
-> **In the mean time**, if you encounter a per-transaction limit when testing, please do open an issue to explain what you were trying to do; we'd love to hear about it. And if you're feeling adventurous, you could 'hack' the PXE to increase the limits. **However**, the limits cannot be increased indefinitely. So although we do anticipate that we'll be able to increase them a little bit, don't go mad and provide yourself with 1 million state transitions per transaction. That would be as unrealistic as artificially increasing Ethereum gas limits to 1 trillion.
-
-## There's more
-
-See the [GitHub issues (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues) for all known bugs fixes and features currently being worked on.
diff --git a/docs/versioned_docs/version-alpha-testnet/developers/reference/debugging/aztecnr-errors.md b/docs/versioned_docs/version-alpha-testnet/developers/reference/debugging/aztecnr-errors.md
deleted file mode 100644
index 62004b8dc9e4..000000000000
--- a/docs/versioned_docs/version-alpha-testnet/developers/reference/debugging/aztecnr-errors.md
+++ /dev/null
@@ -1,75 +0,0 @@
----
-title: Aztec.nr Errors
-tags: [contracts]
----
-
-This section contains some errors that you may encounter when writing and compiling contracts in Aztec.nr. If you run into an error that is not listed here, please [create an issue (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues/new).
-
-#### `Aztec dependency not found. Please add aztec as a dependency in your Nargo.toml`
-
-All smart contracts written in Aztec.nr need the `aztec` dependency. In your `Nargo.toml` under `[dependencies]`, add this:
-
-```toml
-aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="alpha-testnet", directory="noir-projects/aztec-nr/aztec" }
-```
-
-You can learn more about dependencies and their paths [here](../smart_contract_reference/dependencies.md).
-
-#### `backend has encountered an error`
-
-This is likely due to a version mismatch or bad install of barretenberg. Try [reinstalling nargo](../../guides/local_env/versions-updating.md) or uninstalling barretenberg:
-
-```bash
-nargo backend uninstall acvm-backend-barretenberg
-```
-
-It will then reinstall when you compile.
-
-#### `Oracle callback {} not found` & `Oracle callback pedersenHash not found`
-
-This can occasionally happen when there are breaking releases. Make sure that your dependencies in `Nargo.toml` are [updated to the latest release](../../guides/local_env/versions-updating.md#dependency-versions).
-
-#### `error: Failed constraint: 'Public state writes only supported in public functions`
-
-Reading and writing to public state from private functions is currently not supported.
-This is because public values may change before the private function execution is posted on-chain.
-
-This may change in future versions.
-
-#### `Simulation error: Assertion failed:...`
-
-This is an assertion error that is thrown when a condition is not met.
-
-To address the error. find the line in the contract that is throwing the error and investigate why the condition is not met.
-
-#### `Unknown contract 0x0: add it to PXE by calling server.addContracts(...)`
-
-This error occurs when you are trying to interact with a smart contract via an Private Execution Environment (PXE) that does not have the necessary information to execute a transaction.
-
-To execute a transaction, the PXE needs to know the complete address of a contract and contract artifacts.
-
-To address the error, add the contract to the PXE by calling [`pxe.addContracts(...)`](../../../aztec/concepts/pxe/index.md).
-
-#### `Simulation error: No public key registered for address 0x0. Register it by calling pxe.registerRecipient(...) or pxe.registerAccount(...)`
-
-This error occurs when your contract is trying to get a public key via the `get_public_key` oracle call, but the PXE does not have the Complete Address (Complete Address contains the public key).
-
-Your contract typically needs a note recipient's public key when it wants to send a note to because the public key is used to encrypt notes.
-
-:::info
-Manually adding the recipient to the PXE should not be required in case the recipient contract has already been deployed and the PXE is fully synced.
-This is because this information is submitted on-chain when the recipient contract is deployed.
-:::
-
-#### `Could not process note because of "Error: Unknown account.". Skipping note...`
-
-This error occurs when your contract is trying to get a secret via the `get_secret` oracle call, but the PXE does not have the secret for the public key.
-
-This error might occur when you register an account only as a recipient and not as an account.
-To address the error, register the account by calling `server.registerAccount(...)`.
-
-#### `Failed to solve brillig function 'self._is_some`
-
-You may encounter this error when trying to send a transaction that is using an invalid contract. The contract may compile without errors and you only encounter this when sending the transaction.
-
-This error may arise when function parameters are not properly formatted, when trying to "double-spend" a note, or it may indicate that there is a bug deeper in the stack (e.g. a bug in the Aztec.nr library or deeper). If you hit this error, double-check your contract implementation, but also consider [opening an issue (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues/new).
diff --git a/docs/versioned_docs/version-alpha-testnet/developers/reference/environment_reference/cheat_codes.md b/docs/versioned_docs/version-alpha-testnet/developers/reference/environment_reference/cheat_codes.md
deleted file mode 100644
index acfaaa0c8b8e..000000000000
--- a/docs/versioned_docs/version-alpha-testnet/developers/reference/environment_reference/cheat_codes.md
+++ /dev/null
@@ -1,565 +0,0 @@
----
-title: Cheat Codes
-tags: [sandbox]
-sidebar_position: 4
----
-
-import Disclaimer from "@site/src/components/Disclaimers/\_wip_disclaimer.mdx";
-
-## Introduction
-
-To help with testing, the sandbox is shipped with a set of cheatcodes.
-
-Cheatcodes allow you to change the time of the Aztec block, load certain state or more easily manipulate Ethereum instead of having to write dedicated RPC calls to anvil or hardhat.
-
-:::info Prerequisites
-If you aren't familiar with [Anvil (Foundry)](https://book.getfoundry.sh/anvil/), we recommend reading up on that since Aztec Sandbox uses Anvil as the local Ethereum instance.
-:::
-
-### Aims
-
-The guide will cover how to manipulate the state of the:
-
-- Ethereum blockchain;
-- Aztec network.
-
-### Dependencies
-
-For this guide, the following Aztec packages are used:
-
-- @aztec/aztec.js
-
-### Initialization
-
-```ts
-import { createPXEClient, CheatCodes } from "@aztec/aztec.js";
-const pxeRpcUrl = "http://localhost:8080";
-const ethRpcUrl = "http://localhost:8545";
-const pxe = createPXEClient(pxeRpcUrl);
-const cc = await CheatCodes.create(ethRpcUrl, pxe);
-```
-
-There are two properties of the CheatCodes class - `eth` and `aztec` for cheatcodes relating to the Ethereum blockchain (L1) and the Aztec network (L2) respectively.
-
-## Ethereum related cheatcodes
-
-These are cheatcodes exposed from anvil/hardhat conveniently wrapped for ease of use in the Sandbox.
-
-### Interface
-
-```ts
-// Fetch current block number of Ethereum
-public async blockNumber(): Promise