chore(docs): Update docs on fees and various other updates

docs/docs/aztec/concepts/fees.md

@@ -9,6 +9,7 @@ import { Why_Fees } from '/components/snippets';
 <Why_Fees />
 
 In a nutshell, the pricing of transactions transparently accounts for:
+
 - L1 costs, including L1 execution of a block, and data availability via blobs,
 - L2 node operating costs, including proving
 
@@ -18,17 +19,16 @@ This is done via multiple variables and calculations explained in detail in the
 
 Familiar terms from Ethereum mainnet as referred to on the Aztec network:
 
-| Ethereum Mainnet | Aztec              | Description |
-| ----------- | ------------------ | - |
-| gas         | mana               | indication of effort in transaction operations |
-| fee per gas | fee-juice per mana | cost per unit of effort |
-| fee (wei)   | fee-juice          | amount to be paid |
+| Ethereum Mainnet | Aztec              | Description                                    |
+| ---------------- | ------------------ | ---------------------------------------------- |
+| gas              | mana               | indication of effort in transaction operations |
+| fee per gas      | fee-juice per mana | cost per unit of effort                        |
+| fee (wei)        | fee-juice          | amount to be paid                              |
 
 An oracle informs the price of fee-juice per wei, which can be used to calculate a transaction's fee-juice in the units of wei.
 
 Also Aztec borrows ideas from EIP-1559 including: congestion multipliers, and the ability to specify base and priority fee per mana.
 
-
 ### Aztec-specific fields
 
 There are many other fields used in mana and fee calculations, and below shows the ways these fields are determined:
@@ -58,14 +58,15 @@ These are:
 
 ## Fee payment
 
-A fee payer will have bridged fee-juice from L1. On Aztec this fee asset is non-transferrable, and only deducted by the protocol to pay for fees.
+A fee payer will have bridged fee-juice from L1. On Aztec this fee asset is non-transferrable, and only deducted by the protocol to pay for fees. A user can claim bridged fee juice and use it to pay for transaction fees in the same transaction.
 
 The mechanisms for bridging is the same as any other token. For more on this concept see the start of the [Token Bridge Tutorial](../../developers/tutorials/codealong/contract_tutorials/token_bridge) where it describes the components and how bridging works (under the hood this makes use of [portals](https://docs.aztec.network/aztec/concepts/communication/portals)).
 
 ### Payment methods
 
-An account with fee-juice can pay for its transactions, including deployment of a new account.
-An account making a transaction can also refer to "fee-paying contracts" (FPCs) to pay for its transactions.
+An account with fee-juice can pay for its transactions, including deployment of a new account, if fee juice has been bridged the that address at which the account will be deployed.
+
+An account making a transaction can also refer to "fee-paying contracts" (FPCs) to pay for its transactions. FPCs are contracts that accept a token and pay for transactions in fee juice. This means a user doesn't need to hold fee juice, they only need the token that the FPC accepts. FPCs can contain arbitrary logic to determine how they want to authorize transaction fee payments. They can be used for paying transaction fees privately or publicly.
 
 ### Teardown phase
 

docs/docs/developers/getting_started.md

@@ -4,9 +4,18 @@ sidebar_position: 0
 tags: [sandbox]
 ---
 
-This guide will teach you how to install the Aztec sandbox, run it using the Aztec CLI, and interact with contracts using the wallet CLI.
+The Sandbox is an local development Aztec network running fully on your machine, and interacting with a development Ethereum node. You can develop and deploy on it just like on a testnet or mainnet (when the time comes). The sandbox makes it faster and easier to develop and test your Aztec applications.
+
+What's included in the sandbox:
+
+- Local Ethereum network (Anvil)
+- Deployed Aztec protocol contracts (for L1 and L2)
+- A set of test accounts with some test tokens to pay fees
+- Development tools to compile contracts and interact with the network (`aztec-nargo` and `aztec-wallet`)
 
-The Sandbox is an Aztec network running fully on your machine, and interacting with a development Ethereum node. You can develop and deploy on it just like on a testnet or mainnet.
+All of this comes packages in a Docker container to make it easy to install and run.
+
+This guide will teach you how to install the Aztec sandbox, run it using the Aztec CLI, and interact with contracts using the wallet CLI.
 
 ## Prerequisites
 
@@ -75,7 +84,6 @@ import { CLI_Add_Test_Accounts } from '/components/snippets';
 
 <CLI_Add_Test_Accounts />
 
-
 To add the test accounts:
 
 ```bash

docs/docs/developers/guides/js_apps/pay_fees.md

@@ -10,27 +10,32 @@ This guide shows the various ways this can be done. For more of a background see
 
 ## Methods to pay a tx fee
 
-### Natively via an existing balance of fee juice
+1. Natively via an existing balance of fee juice
 
 Either your own account or someone else's address has a balance of fee juice, and the transaction is paid for from this balance.
 
-### Natively via a balance of fee juice to be claimed
+2. Natively via a balance of fee juice bridged from L1 to be claimed on L2
 
 Processing this transaction first claims bridged fee juice then is paid for from the balance, all in the same public/private tx.
 
-### Privately or publicly via a Fee Paying Contract
+3. Privately or publicly via a Fee Paying Contract
 
-A fee paying contract (FPC) is created and nominates a token that it accepts to then pay for txs in fee juice. So a user doesn't need to hold fee juice, they only need the token that the FPC accepts.
+A fee paying contract (FPC) is created and nominates a token that it accepts to then pay for transactions in fee juice. So a user doesn't need to hold fee juice, they only need the token that the FPC accepts.
 
-### Sponsored Fee Paying Contract (SponsoredFPC)
+The FPC can also decide to refund users in cases of overpayment. For private FPCs, this incurrs a substantial gate count (proving time) and DA costs so in some cases it might be cheaper to not get the refund. The sample FPCs we show here refund the users but a FPC deployer or user should think carefully if asking for refunds is a smart option.
 
-The most straightforward way to pay for a transaction is via the sponsored fee payment method, bootstrapping some transactions by skipping the need to bridge fee juice to the account. This method uses a type of fee paying contract configured to pay for a number of transactions without requiring payment.
+The most straightforward way to pay for a transaction is via the sponsored fee payment method, bootstrapping some transactions by skipping the need to bridge fee juice to the account. This method uses a type of fee paying contract configured to pay for a number of transactions without requiring payment, but also requires that there is a sponsor to pay for the transactions. **This only exists on the sandbox as a convenience to get started quickly, though you could deploy it on testnet too for your own use case**
 
-## Bridging fee-juice
+The most straightforward way to pay for a transaction is via the sponsored fee payment method, bootstrapping some transactions by skipping the need to bridge fee juice to the account. This method uses a type of fee paying contract configured to pay for a number of transactions without requiring payment, but also requires that there is a sponsor to pay for the transactions.
+
+## Bridging Fee Juice
+
+### Sandbox
 
 To first get fee juice into an account it needs to be bridged from L1. You can skip this section if you want to first make a transaction via the SponsoredFPC.
 
 :::note
+
 See here to [Bridge Fee Juice](../../../developers/reference/environment_reference/cli_wallet_reference#bridge-fee-juice) via the CLI wallet.
 
 :::
@@ -51,50 +56,96 @@ Create a new fee juice portal manager and bridge fee juice publicly to Aztec:
 
 #include_code bridge_fee_juice yarn-project/end-to-end/src/spartan/setup_test_wallets.ts javascript
 
-Bridging can also be done privately with the corresponding function:
+For the mechanisms to complete bridging between L1 and Aztec, we have to wait for 2 Aztec blocks to progress. This can be triggered manually by sending 2 transactions in the sandbox, or by waiting for 2 blocks on a public network. After this, an account should have its fee juice ready to use in transactions.
 
-#include_code bridge_tokens_private yarn-project/aztec.js/src/ethereum/portal_manager.ts javascript
+Alternatively, the resulting claim object can be used to create a payment method to claim and pay for a transaction in one, where the transaction is the contract's deployment.
 
-For the mechanisms to complete bridging between L1 and Aztec, any two other transactions on the sandbox are made. After this, an already deployed account should have its fee juice ready to use in transactions.
+### Testnet
 
-Alternatively, the resulting claim object can be used to create a payment method to claim and pay for a transaction in one, where the transaction is the contract's deployment.
+The `L1FeeJuicePortalManager` will not be able to mint assets for you on testnet. You will need to call the fee asset's `mint` function on L1 to mint fee juice, e.g.:
 
+```bash
+cast call $FEE_ASSET_HANDLER_CONTRACT "mint(address)" $MY_L1_ADDRESS --rpc-url <RPC_URL>
+```
 
-## Fee Options
+Then bridge it to L2, using the the `L1FeeJuicePortalManager` as described above.
 
-Functions pertaining to sending a transaction, such as `deploy` and `send`, each include a `fee` variable defined with the following (optional) parameters:
+## Examples
 
-#include_code user_fee_options yarn-project/entrypoints/src/interfaces.ts javascript
+### Pay with FeeJuice
 
+To send a transaction from an already deployed account already holding fee juice. A user's fee juice balance is public, so paying for a transaction with fee juice will reveal information about which account is paying for the transaction and how much they paid.
 
-### Fee Payment Method
+Note: this example is a public token transfer call, but can equally be a private function call
 
-The `paymentMethod` is an object for the type of payment. Each of the implementations can be found [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec.js/src/fee). For example:
+```ts
+import { FeeJuicePaymentMethod } from "@aztec/aztec.js";
+```
 
-#include_code fee_juice_method yarn-project/aztec.js/src/fee/fee_juice_payment_method.ts javascript
+#include_code pay_fee_juice_send yarn-project/end-to-end/src/e2e_fees/fee_juice_payments.test.ts javascript
 
-### Gas Settings
+**The equivalent to specify fees via CLI...**
 
-#include_code gas_settings_vars yarn-project/stdlib/src/gas/gas_settings.ts javascript
+import { CLI_Fees } from '/components/snippets';
 
-import { Gas_Settings_Components, Gas_Settings } from '/components/snippets';
+<CLI_Fees />
 
-<Gas_Settings />
+### Claim and deploy
 
-<Gas_Settings_Components />
+Here we will use the `claim` object previously from the bridging section, and the corresponding `wallet`, to create the fee payment method. The payment method is then used to claim fee juice and pay for account contract deployment. Note the function used to bridge fee juice (private/public) should correspond to how the fee juice is claimed.
 
+```ts
+import { FeeJuicePaymentMethodWithClaim } from "@aztec/aztec.js";
+```
 
-### Other params
+#include_code claim_and_deploy yarn-project/bot/src/factory.ts javascript
 
-Fee and gas padding params can be left to their default values, and the estimateGas boolean can be used when simulating a tx to calculate gas.
+**The equivalent to specify fees via CLI...**
 
-With the fee options explained, lets do a paid transaction.
+The CLI tool `aztec-wallet` takes the fee payment method via the param: `--payment method=fee_juice,claim`
 
-## Examples
+#### Claim and Pay
+
+Claiming bridged fee juice and using it to pay for transaction fees results in fees being paid publicly.
+
+Calling a function, in this case checking the balance of the fee juice contract:
+
+#include_code claim_and_pay yarn-project/end-to-end/src/e2e_fees/fee_juice_payments.test.ts javascript
+
+### Fee Paying Contract
+
+Users can pay fees privately or publicly via FPCs. A FPC must be deployed and funded with fee juice before it can be used to pay for transactions. Users must have the token that the FPC accepts to pay for transactions. They must have a private balance of the token if they want to pay for fees privately, and a public balance if they want to pay for fees publicly.
+
+Import the appropriate method from aztec.js.
+
+```ts
+import {
+  PrivateFeePaymentMethod,
+  PublicFeePaymentMethod,
+} from "@aztec/aztec.js";
+```
+
+The fee payment method is created and used as follows, with similar syntax for private or public fee payments:
+
+#include_code fpc yarn-project/end-to-end/src/e2e_fees/public_payments.test.ts javascript
+
+In this example, thanks to the FPC's `accepted_asset` being banana tokens, Alice only needs to hold this token and not fee juice. The asset that a FPC accepts for paying fees is determined when the FPC is deployed. The function being called happens to also be a transfer of banana tokens to Bob.
+
+More on FPCs [here](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/fpc_contract/src/main.nr)
+
+See this [section](../../reference/environment_reference/cli_wallet_reference.md#fee-paying-contract) for paying fees via an FPC using the CLI wallet.
 
 ### Sponsored Fee Paying Contract
 
-Creating the SponsoredFPC is as simple as passing it the PXE:
+This method of fee payment will only work for environments where a sponsored fee paying contract is deployed.
+The sandbox comes with a sponsored fee paying contract deployed, so this can be used to pay for transactions without needing to bridge fee juice.
+To use sponsored FPCs in other environments, they will need to be deployed and funded with fee juice.
+Creating the SponsoredFPC is as simple as importing it and passing it the PXE:
+
+```ts
+import { SponsoredFeePaymentMethod } from "@aztec/aztec.js";
+```
+
 ```ts
 const paymentMethod = await SponsoredFeePaymentMethod.new(pxe);
 ```
@@ -107,37 +158,28 @@ const paymentMethod = await SponsoredFeePaymentMethod.new(pxe);
 myAccountManager.deploy({ fee: { paymentMethod } });
 ```
 
-### Pay with FeeJuice
-
-To send a transaction from an already deployed account already holding fee juice:
-(Note: this example is a public token transfer call, but can equally be a private function call)
-
-#include_code pay_fee_juice_send yarn-project/end-to-end/src/e2e_fees/fee_juice_payments.test.ts javascript
-
-**The equivalent to specify fees via CLI...**
-
-import { CLI_Fees } from '/components/snippets';
+## Fee Options
 
-<CLI_Fees />
+Functions pertaining to sending a transaction, such as `deploy` and `send`, each include a `fee` variable defined with the following (optional) parameters:
 
-### Claim and deploy
+#include_code user_fee_options yarn-project/entrypoints/src/interfaces.ts javascript
 
-Here we will use the `claim` object previously from the bridging section, and the corresponding `wallet`, to create the payment method. The payment method is then used to claim fee juice and pay for account contract deployment. Note the function used to bridge fee juice (private/public) should correspond to how the fee juice is claimed.
+### Fee Payment Method
 
-#include_code claim_and_deploy yarn-project/bot/src/factory.ts javascript
+The `paymentMethod` is an object for the type of payment. Each of the implementations can be found [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec.js/src/fee). For example:
 
-#### Claim and Pay
+#include_code fee_juice_method yarn-project/aztec.js/src/fee/fee_juice_payment_method.ts javascript
 
-Calling a function, in this case checking the balance of the fee juice contract:
+### Gas Settings
 
-#include_code claim_and_pay yarn-project/end-to-end/src/e2e_fees/fee_juice_payments.test.ts javascript
+#include_code gas_settings_vars yarn-project/stdlib/src/gas/gas_settings.ts javascript
 
-### Fee Paying Contract
+import { Gas_Settings_Components, Gas_Settings } from '/components/snippets';
 
-Similarly with a fee paying contract, the fee payment method is created and used as follows:
+<Gas_Settings />
 
-#include_code fpc yarn-project/end-to-end/src/e2e_fees/public_payments.test.ts javascript
+<Gas_Settings_Components />
 
-In this example, thanks to the FPC's `accepted_asset` being banana tokens, Alice only needs to hold this token and not fee juice. The function being called happens to also be a transfer of banana tokens to Bob.
+### Other params
 
-More on FPCs [here](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/fpc_contract/src/main.nr)
+Fee and gas padding params can be left to their default values, and the estimateGas boolean can be used when simulating a tx to calculate gas.

docs/docs/developers/tutorials/codealong/contract_tutorials/counter_contract.md

@@ -5,7 +5,7 @@ sidebar_position: 0
 
 import Image from "@theme/IdealImage";
 
-In this guide, we will create our first Aztec.nr smart contract. We will build a simple private counter. This contract will get you started with the basic setup and syntax of Aztec.nr, but doesn't showcase the awesome stuff Aztec is capable of.
+In this guide, we will create our first Aztec.nr smart contract. We will build a simple private counter, where you can keep your own private counter - so no one knows what ID you are at or when you increment! This contract will get you started with the basic setup and syntax of Aztec.nr, but doesn't showcase all of the awesome stuff Aztec is capable of.
 
 ## Prerequisites
 
@@ -83,7 +83,7 @@ Write this within your contract at the top:
 
 `value_note`
 
-Notes are fundamental to how Aztec manages privacy. A note is a privacy-preserving representation of an amount of tokens associated with a nullifier key (that can be owned by an owner), while encrypting the amount. In this contract, we are using the `value_note` library. This is a type of note interface for storing a single Field, eg a balance - or, in our case, a counter.
+Notes are fundamental to how Aztec manages privacy. A note is a privacy-preserving representation of some arbitrary information. A commitment to a note is stored on-chain, it is associated with a nullifier key (that can be owned by an owner) so it can be spent, and encrypted note information is often emitted on-chain for later retrieval. In this contract, we are using the `value_note` library. This is a type of note interface for storing a single Field, e.g. a balance - or, in our case, a counter.
 
 We are also using `balance_utils` from this import, a useful library that allows us to utilize value notes as if they are simple balances.
 
@@ -101,7 +101,7 @@ Add this below the imports. It declares the storage variables for our contract.
 
 Now we’ve got a mechanism for storing our private state, we can start using it to ensure the privacy of balances.
 
-Let’s create a constructor method to run on deployment that assigns an initial supply of tokens to a specified owner. This function is called `initialize`, but behaves like a constructor. It is the `#[initializer]` decorator that specifies that this function behaves like a constructor. Write this:
+Let’s create a constructor method to run on deployment that assigns an initial count to a specified owner. This function is called `initialize`, but behaves like a constructor. It is the `#[initializer]` decorator that specifies that this function behaves like a constructor. Write this:
 
 #include_code constructor /noir-projects/noir-contracts/contracts/counter_contract/src/main.nr rust