chore: Accumulated backports to v4-next (#22205)

BEGIN_COMMIT_OVERRIDE
cherry-pick: feat: move event size check from declaration to private
emission (#22168)
fix: prevent oracle failure on tag computation for invalid recipient
(#22163)
feat: move event size check from declaration to private emission
(#22168) [v4-next backport] (#22182)
fix(cli-wallet): peek claim stack instead of popping for
estimate-gas-only (#22196)
fix: use Fr.fromString for CLI wallet claim params to handle decimal
values (#22197)
fix: indefinite retry for prover node and agent broker communication
(#22202)
END_COMMIT_OVERRIDE

Author: AztecBot

docs/docs-developers/docs/aztec-js/how_to_create_account.md

@@ -46,11 +46,13 @@ See the [guide on fees](./how_to_pay_fees.md#sponsored-fee-payment-contracts) fo
 
 ### Using Fee Juice
 
-If your account already has Fee Juice (for example, [bridged from L1](./how_to_pay_fees.md#bridge-fee-juice-from-l1)):
+If your account has Fee Juice from a [bridge from L1](./how_to_pay_fees.md#bridge-fee-juice-from-l1), you can claim it and deploy in one step using `FeeJuicePaymentMethodWithClaim`:
 
-#include_code deploy_account_fee_juice /docs/examples/ts/aztecjs_connection/index.ts typescript
+#include_code bridge_fee_juice_claim /docs/examples/ts/aztecjs_connection/index.ts typescript
 
-The `from: NO_FROM` signals that this transaction should be executed without account contract mediation. The wallet will directly execute it via a default entrypoint with no authorization
+If the account already has Fee Juice on L2 (for example, from a faucet or a previously claimed bridge), no special payment method is needed — just call `send({ from: NO_FROM })` and Fee Juice is used automatically.
+
+The `from: NO_FROM` signals that this transaction should be executed without account contract mediation. The wallet will directly execute it via a default entrypoint with no authorization.
 
 ## Verify deployment
 

docs/docs-developers/docs/aztec-js/how_to_pay_fees.md

@@ -42,14 +42,7 @@ When using `EmbeddedWallet`, gas is estimated automatically on every `send()` ca
 
 Before sending a transaction, you can estimate the mana it will consume by simulating with `estimateGas: true`:
 
-```typescript
-const { estimatedGas } = await contract.methods
-  .myFunction(arg1, arg2)
-  .simulate({
-    from: sender.address,
-    fee: { estimateGas: true, estimatedGasPadding: 0.1 },
-  });
-```
+#include_code estimate_mana /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 The `estimatedGas` object contains:
 
@@ -62,13 +55,7 @@ The `estimatedGas` object contains:
 
 To calculate the expected fee from estimated gas, use the `computeFee` method with current network fees:
 
-```typescript
-// import { createAztecNodeClient } from '@aztec/aztec.js/node';
-// const aztecNode = createAztecNodeClient('http://localhost:8080');
-const currentFees = await aztecNode.getCurrentMinFees();
-const estimatedFee = estimatedGas.gasLimits.computeFee(currentFees).toBigInt();
-console.log("Estimated fee:", estimatedFee);
-```
+#include_code compute_fee_from_estimate /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 :::tip
 The `estimatedGasPadding` parameter adds a safety margin to the estimate. A value of `0.1` adds 10% padding. Use higher padding for transactions with variable gas costs.
@@ -78,41 +65,19 @@ The `estimatedGasPadding` parameter adds a safety margin to the estimate. A valu
 
 After a transaction is mined, you can retrieve the fee paid from the receipt:
 
-```typescript
-const receipt = await contract.methods
-  .myFunction(arg1, arg2)
-  .send({ from: sender.address })
-  .wait();
-
-console.log("Transaction fee:", receipt.transactionFee);
-```
+#include_code get_fee_from_receipt /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 The `transactionFee` field is a `bigint` representing the total fee paid in the fee token (Fee Juice). You can also check execution status:
 
-```typescript
-if (receipt.hasExecutionSucceeded()) {
-  console.log("Transaction succeeded in block:", receipt.blockNumber);
-  console.log("Fee paid:", receipt.transactionFee);
-} else {
-  console.log("Transaction failed:", receipt.error);
-}
-```
+#include_code check_receipt_status /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 ## Pay with Fee Juice
 
 Fee Juice is the native fee token on Aztec.
 
 If your account has Fee Juice (for example, from a faucet), is [deployed](./how_to_create_account.md), and is registered in your wallet, it will be used automatically to pay for the fee of the transaction:
 
-```typescript
-// contract is a deployed contract instance; aliceAddress is from the connection guide
-const receipt = await contract.methods.myFunction(param1, param2).send({
-  from: aliceAddress,
-  // no fee payment method needed
-});
-
-console.log("Transaction fee:", receipt.transactionFee);
-```
+#include_code pay_with_fee_juice /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 ## Use Fee Payment Contracts
 
@@ -151,51 +116,15 @@ Fee Juice is non-transferable on L2, but you can bridge it from L1, claim it on
 
 `aztec.js` provides helpers to simplify the process:
 
-```typescript
-// essentially returns an extended wallet from Viem
-import { createExtendedL1Client } from "@aztec/ethereum";
-const walletClient = createExtendedL1Client(
-  ["https://your-ethereum-host"], // ex. http://localhost:8545 on the local network (yes it runs Anvil under the hood)
-  privateKey, // the private key for some account, needs funds for gas!
-);
-
-// a helper to interact with the L1 fee juice portal
-import { L1FeeJuicePortalManager } from "@aztec/aztec.js/ethereum";
-const portalManager = await L1FeeJuicePortalManager.new(
-  node, // your Aztec node, ex. https://aztec-testnet-fullnode.zkv.xyz, or http://localhost:8080 for local network
-  walletClient,
-  logger, // a logger, ex. import { createLogger } from "@aztec/aztec.js"
-);
-```
+#include_code bridge_fee_juice_setup /docs/examples/ts/aztecjs_connection/index.ts typescript
 
 Under the hood, `L1FeeJuicePortalManager` gets the L1 addresses from the node `node_getNodeInfo` endpoint. It then exposes an easy method `bridgeTokensPublic` which mints fee juice on L1 and sends it to an L2 address via the L1 portal:
 
-```typescript
-// portalManager is from the L1FeeJuicePortalManager setup above
-// aliceAddress is an Aztec address from the connection guide
-const claim = await portalManager.bridgeTokensPublic(
-  aliceAddress, // the L2 address
-  1000000000000000000000n, // the amount to send to the L1 portal
-  true, // whether to mint or not (set to false if your walletClient account already has fee juice!)
-);
-
-console.log("Claim secret:", claim.claimSecret);
-console.log("Claim amount:", claim.claimAmount);
-```
+#include_code bridge_fee_juice_execute /docs/examples/ts/aztecjs_connection/index.ts typescript
 
 After this transaction is minted on L1 and a few blocks pass, you can claim the message on L2 and use it directly to pay for fees:
 
-```typescript
-import { FeeJuicePaymentMethodWithClaim } from "@aztec/aztec.js/fee";
-
-// aliceAddress and claim are from the bridgeTokensPublic step above
-// contract is a deployed contract instance; gasSettings is from the gas settings section
-// Use the claim from bridgeTokensPublic to pay for a transaction
-const paymentMethod = new FeeJuicePaymentMethodWithClaim(aliceAddress, claim);
-const receipt = await contract.methods
-  .myFunction()
-  .send({ from: aliceAddress, fee: { gasSettings, paymentMethod } });
-```
+#include_code bridge_fee_juice_claim /docs/examples/ts/aztecjs_connection/index.ts typescript
 
 ## Configure gas settings
 
@@ -214,45 +143,21 @@ The fee limit is calculated as `gasLimits × maxFeesPerGas` for each dimension.
 
 Set custom gas limits by importing from `stdlib`:
 
-```typescript
-import { GasSettings } from "@aztec/stdlib/gas";
-
-// contract is a deployed contract instance
-// alice is from the connection guide
-// paymentMethod is from one of the payment method sections above
-const gasSettings = GasSettings.from({
-  gasLimits: { daGas: 100000, l2Gas: 100000 },
-  teardownGasLimits: { daGas: 10000, l2Gas: 10000 },
-  maxFeesPerGas: { daGas: 10, l2Gas: 10 },
-  maxPriorityFeesPerGas: { daGas: 1, l2Gas: 1 },
-});
-
-const receipt = await contract.methods.myFunction().send({
-  from: aliceAddress,
-  fee: {
-    paymentMethod,
-    gasSettings,
-  },
-});
-```
+#include_code custom_gas_settings /docs/examples/ts/aztecjs_advanced/index.ts typescript
+
+Then pass the settings when sending:
+
+#include_code send_with_gas_settings /docs/examples/ts/aztecjs_advanced/index.ts typescript
+
+Note that `gasLimits` and `teardownGasLimits` use `daGas`/`l2Gas` field names, while `maxFeesPerGas` and `maxPriorityFeesPerGas` use `feePerDaGas`/`feePerL2Gas`.
 
 ### Use automatic gas estimation
 
 :::note
 When using `EmbeddedWallet`, gas estimation happens automatically on every `send()` — you don't need to pass `estimateGas`. This option is useful for custom wallet implementations or when you want to estimate gas during a `simulate()` call.
 :::
 
-```typescript
-// contract, aliceAddress, and paymentMethod are from the examples above
-const receipt = await contract.methods.myFunction().send({
-  from: aliceAddress,
-  fee: {
-    paymentMethod,
-    estimateGas: true,
-    estimatedGasPadding: 0.2, // 20% padding
-  },
-});
-```
+#include_code auto_gas_estimation /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 :::tip
 Gas estimation runs a simulation first to determine actual gas usage, then adds padding for safety. This works with all payment methods, including FPCs.

docs/docs-developers/docs/aztec-js/how_to_read_data.md

@@ -20,19 +20,15 @@ The `simulate` method executes a contract function locally and returns its resul
 
 #include_code simulate_function /docs/examples/ts/aztecjs_connection/index.ts typescript
 
-The `from` option specifies which address context to use for the simulation. This is required for all simulations, though it only affects private function execution (public functions ignore this value).
-
-### Basic simulation
-
-#include_code simulate_function docs/examples/ts/aztecjs_connection/index.ts typescript
+The `from` option specifies which account context to use for the simulation. This is required for all simulations. For private functions, it determines which account's private state is accessed. For public functions, it sets the `msg_sender` context.
 
 ### Handling return values
 
 For functions returning multiple values, destructure the result:
 
 ```typescript
 // contract and callerAddress are from the example above
-const [value1, value2] = await contract.methods
+const { result: [value1, value2] } = await contract.methods
   .get_multiple_values()
   .simulate({ from: callerAddress });
 ```
@@ -41,38 +37,17 @@ const [value1, value2] = await contract.methods
 
 Set `includeMetadata: true` to get additional information about the simulation:
 
-```typescript
-// contract and callerAddress are from the examples above
-const result = await contract.methods
-  .balance_of_public(address)
-  .simulate({ from: callerAddress, includeMetadata: true });
-
-// Result includes:
-// - result: the function return value
-// - stats: execution statistics (timing, circuit sizes)
-// - offchainEffects: any offchain effects emitted
-// - estimatedGas: gas limit estimates (gasLimits and teardownGasLimits)
-console.log("Balance:", result.result);
-console.log("L2 gas limit:", result.estimatedGas.gasLimits.l2Gas);
-console.log("DA gas limit:", result.estimatedGas.gasLimits.daGas);
-```
+#include_code simulate_with_metadata /docs/examples/ts/aztecjs_advanced/index.ts typescript
+
+The result includes `result` (the function return value), `stats` (execution statistics), `offchainEffects`, and `estimatedGas` (with `gasLimits` and `teardownGasLimits`).
 
 ### Private function considerations
 
 When simulating private functions, the caller must have access to any private state being read. The PXE only has visibility into notes belonging to registered accounts.
 
-```typescript
-// contract and callerAddress are from the examples above
-// This works if callerAddress owns the notes
-const balance = await contract.methods
-  .balance_of_private(callerAddress)
-  .simulate({ from: callerAddress });
+#include_code simulate_private_access /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
-// This fails if callerAddress doesn't have access to otherAddress's notes
-const otherBalance = await contract.methods
-  .balance_of_private(otherAddress)
-  .simulate({ from: callerAddress }); // Error: cannot access private state
-```
+If the caller doesn't have access to another address's notes, the simulation will fail with an error.
 
 :::warning
 Simulation runs locally without generating proofs. No correctness guarantees are provided on the result. See [Call Types](../foundational-topics/call_types.md#simulate) for more details.
@@ -95,20 +70,11 @@ Contracts emit data in two forms you can read:
 
 Use `aztecNode.getPublicLogs()` to retrieve raw log data:
 
-```typescript
-// aztecNode is from createAztecNodeClient() in the connection guide
-// receipt is from a transaction's send() call
-// Get logs for a specific transaction
-const logs = await aztecNode.getPublicLogs({ txHash: receipt.txHash });
-const rawFields = logs.logs[0].log.getEmittedFields(); // Fr[]
-
-// Get logs for a block range
-const logFilter = {
-  fromBlock: startBlock,
-  toBlock: endBlock,
-};
-const publicLogs = (await aztecNode.getPublicLogs(logFilter)).logs;
-```
+#include_code read_public_logs /docs/examples/ts/aztecjs_advanced/index.ts typescript
+
+You can also filter by transaction hash or block range:
+
+#include_code read_logs_by_filter /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 ## Reading events
 
@@ -118,9 +84,7 @@ Events provide typed access to contract emissions. The event metadata from your
 
 Use the `getPublicEvents` helper to retrieve typed public events:
 
-```typescript
-import { getPublicEvents } from "@aztec/aztec.js/events";
-```
+#include_code import_get_public_events /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 #include_code get_public_events yarn-project/end-to-end/src/e2e_event_logs.test.ts typescript
 
@@ -140,10 +104,7 @@ Each returned event includes both the decoded `event` data and `metadata` (block
 
 Private events are stored in the PXE with privacy scoping. Use `wallet.getPrivateEvents()` to retrieve them:
 
-```typescript
-import type { PrivateEventFilter } from "@aztec/aztec.js/wallet";
-import { BlockNumber } from "@aztec/foundation/branded-types";
-```
+#include_code import_private_event_types /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 The `BlockNumber` type is a branded type that wraps raw numbers for type safety. Use it when setting `fromBlock` and `toBlock` in filters.
 

docs/docs-developers/docs/aztec-js/how_to_send_transaction.md

@@ -23,24 +23,11 @@ import { General } from '@site/src/components/Snippets/general_snippets';
 
 After connecting to a contract:
 
-```typescript
-import { Contract } from "@aztec/aztec.js";
-
-// wallet is from the connection guide; contractAddress and artifact are from your deployed contract
-const contract = await Contract.at(contractAddress, artifact, wallet);
-```
+#include_code connect_to_contract /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 Call a function and wait for it to be mined:
 
-```typescript
-// contract is from the step above; alice is from the connection guide
-const receipt = await contract.methods
-  .transfer(bobAddress, amount)
-  .send({ from: aliceAddress });
-
-console.log(`Transaction mined in block ${receipt.blockNumber}`);
-console.log(`Transaction fee: ${receipt.transactionFee}`);
-```
+#include_code basic_send_transaction /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 The `from` field specifies which account sends the transaction. If that account has Fee Juice, it pays for the transaction automatically. For other fee payment options, see [paying fees](./how_to_pay_fees.md).
 
@@ -53,9 +40,7 @@ When using `EmbeddedWallet`, calling `send()` triggers a **simulation** step bef
 
 This means a simple `.send()` is all most apps need. You can adjust the gas padding if desired:
 
-```typescript
-wallet.setEstimatedGasPadding(0.2); // 20% padding instead of the default 10%
-```
+#include_code set_gas_padding /docs/examples/ts/aztecjs_advanced/index.ts typescript
 
 :::note
 Public authwits still need to be set explicitly before the transaction, as they require a separate onchain transaction. See [Using Authentication Witnesses](./how_to_use_authwit.md) for details.
@@ -85,7 +70,7 @@ After sending a transaction without waiting, you can query its receipt using the
 
 The receipt includes:
 
-- `status` - Transaction status (`success`, `reverted`, `dropped`, or `pending`)
+- `status` - Transaction status (`pending`, `proposed`, `checkpointed`, `proven`, `finalized`, or `dropped`)
 - `blockNumber` - Block where the transaction was included
 - `transactionFee` - Fee paid for the transaction
 - `error` - Error message if the transaction reverted