docs: document EmbeddedWallet automatic gas estimation and private authwits

docs/developer_versioned_docs/version-v4.1.0-rc.2/docs/aztec-js/how_to_pay_fees.md

@@ -34,6 +34,10 @@ Mana is Aztec's unit of computational effort (like gas on Ethereum), and Fee Jui
 
 ## Estimate mana costs
 
+:::tip Automatic estimation with EmbeddedWallet
+When using `EmbeddedWallet`, gas is estimated automatically on every `send()` call. You only need to manually estimate if you want to preview costs before sending, or if you're using a custom wallet implementation.
+:::
+
 Before sending a transaction, you can estimate the mana it will consume by simulating with `estimateGas: true`:
 
 ```typescript
@@ -300,6 +304,10 @@ const receipt = await contract.methods.myFunction().send({
 
 ### 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({

docs/developer_versioned_docs/version-v4.1.0-rc.2/docs/aztec-js/how_to_send_transaction.md

@@ -42,6 +42,23 @@ console.log(`Transaction fee: ${receipt.transactionFee}`);
 
 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).
 
+### What happens behind the scenes
+
+When using `EmbeddedWallet`, calling `send()` triggers a **pre-simulation** step before the transaction is actually sent. This pre-simulation:
+
+1. **Estimates gas limits** based on actual execution, with a configurable padding (default 10%) to avoid reverts. If you provide explicit gas limits via `fee.gasSettings`, they take precedence.
+2. **Generates private authwits automatically**. If the contract you're calling requires a private [authentication witness](./how_to_use_authwit.md) (e.g., a token transfer on behalf of the sender), the wallet detects this during pre-simulation and creates the authwit on the fly — no manual setup needed.
+
+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%
+```
+
+:::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.
+:::
+
 ### Send without waiting
 
 Use the `NO_WAIT` option to get the transaction hash immediately without waiting for inclusion:

docs/developer_versioned_docs/version-v4.1.0-rc.2/docs/aztec-js/how_to_use_authwit.md

@@ -7,6 +7,14 @@ description: Step-by-step guide to implementing authentication witnesses in Azte
 
 This guide shows you how to create and use authentication witnesses (authwits) to authorize other accounts to perform actions on your behalf.
 
+:::tip Automatic private authwits with EmbeddedWallet
+
+When using `EmbeddedWallet`, **private authwits are created automatically**. The wallet pre-simulates your transaction before sending and detects which private authwits are needed, then generates them on the fly. You don't need to create them manually.
+
+Public authwits still need to be set explicitly, as they require a separate onchain transaction before use. The manual approach described below is also relevant if you're building a custom wallet implementation.
+
+:::
+
 :::warning aztec-nr
 
 Using AuthWitnesses is always a two-part process. This guide shows how to generate and use them, but you still need to set up your contract to accept and authenticate them.
@@ -30,6 +38,10 @@ The authwit system supports different intent types depending on your use case:
 
 ## Create private authwits
 
+:::note
+If you're using `EmbeddedWallet`, this section is handled for you automatically — see the tip above. The manual approach below is for custom wallet implementations or advanced use cases.
+:::
+
 Private authwits authorize actions in the private domain. The authorization is included directly in the transaction that uses it.
 
 Let's say Alice wants to allow Bob to transfer tokens from her account. Alice is the **authorizer** (she owns the tokens) and Bob is the **caller** (he will execute the transfer):

docs/developer_versioned_docs/version-v4.1.0-rc.2/docs/foundational-topics/wallets.md

@@ -36,6 +36,8 @@ Private functions use a UTXO model, so their execution trace is determined entir
 Public functions use an account model (like Ethereum), so their execution trace depends on chain state at inclusion time, which may differ from simulation.
 :::
 
+Before sending, the wallet may run a **pre-simulation** — a lightweight simulation using a stub account contract that avoids expensive kernel circuit execution. This pre-simulation estimates gas limits for the transaction and captures any required private authorization data (see [Authorizing actions](#authorizing-actions) below). The `EmbeddedWallet` runs this step automatically on every send.
+
 Finally, the wallet **sends** the resulting _transaction_ object, which includes the proof of execution, to an Aztec Node. The transaction is then broadcasted through the peer-to-peer network, to be eventually picked up by a sequencer and included in a block.
 
 ## Authorizing actions
@@ -44,6 +46,8 @@ Account contracts in Aztec expose an interface for other contracts to validate [
 
 Wallets should manage these authorizations, prompting the user when they are requested by an application. Authorizations in private executions come in the form of _auth witnesses_, which are usually signatures over an identifier for an action. Applications can request the wallet to produce an auth witness via the `createAuthWit` call. In public functions, authorizations are pre-stored in the account contract storage, which is handled by a call to an internal function in the account contract implementation.
 
+Modern wallets can automate private authorization by capturing authorization requests during pre-simulation. The `EmbeddedWallet`, for example, detects which private authwits a transaction needs and generates them automatically, so dapps don't need to explicitly create or manage private authorizations. Public authorizations still require explicit setup, as they involve onchain state changes that must occur before the authorized action.
+
 ## Key management
 
 As in EVM-based chains, wallets are expected to manage user keys, or provide an interface to hardware wallets or alternative key stores. Keep in mind that in Aztec each account requires [multiple key pairs](./accounts/keys.md): protocol keys (nullifier and incoming viewing keys) are mandated by the protocol and used for spending notes and decryption, whereas signing keys are dependent on the account contract implementation rolled out by the wallet. Should the account contract support it, wallets must provide the user with the means to rotate or recover their signing keys.

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

@@ -38,6 +38,10 @@ Mana is Aztec's unit of computational effort (like gas on Ethereum), and Fee Jui
 
 ## Estimate mana costs
 
+:::tip Automatic estimation with EmbeddedWallet
+When using `EmbeddedWallet`, gas is estimated automatically on every `send()` call. You only need to manually estimate if you want to preview costs before sending, or if you're using a custom wallet implementation.
+:::
+
 Before sending a transaction, you can estimate the mana it will consume by simulating with `estimateGas: true`:
 
 ```typescript
@@ -267,6 +271,10 @@ const receipt = await contract.methods.myFunction().send({
 
 ### 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({

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

@@ -44,6 +44,23 @@ console.log(`Transaction fee: ${receipt.transactionFee}`);
 
 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).
 
+### What happens behind the scenes
+
+When using `EmbeddedWallet`, calling `send()` triggers a **pre-simulation** step before the transaction is actually sent. This pre-simulation:
+
+1. **Estimates gas limits** based on actual execution, with a configurable padding (default 10%) to avoid reverts. If you provide explicit gas limits via `fee.gasSettings`, they take precedence.
+2. **Generates private authwits automatically**. If the contract you're calling requires a private [authentication witness](./how_to_use_authwit.md) (e.g., a token transfer on behalf of the sender), the wallet detects this during pre-simulation and creates the authwit on the fly — no manual setup needed.
+
+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%
+```
+
+:::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.
+:::
+
 ### Send without waiting
 
 Use the `NO_WAIT` option to get the transaction hash immediately without waiting for inclusion:

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

@@ -7,6 +7,14 @@ description: Step-by-step guide to implementing authentication witnesses in Azte
 
 This guide shows you how to create and use authentication witnesses (authwits) to authorize other accounts to perform actions on your behalf.
 
+:::tip Automatic private authwits with EmbeddedWallet
+
+When using `EmbeddedWallet`, **private authwits are created automatically**. The wallet pre-simulates your transaction before sending and detects which private authwits are needed, then generates them on the fly. You don't need to create them manually.
+
+Public authwits still need to be set explicitly, as they require a separate onchain transaction before use. The manual approach described below is also relevant if you're building a custom wallet implementation.
+
+:::
+
 :::warning aztec-nr
 
 Using AuthWitnesses is always a two-part process. This guide shows how to generate and use them, but you still need to set up your contract to accept and authenticate them.
@@ -32,6 +40,10 @@ The authwit system supports different intent types depending on your use case:
 
 ## Create private authwits
 
+:::note
+If you're using `EmbeddedWallet`, this section is handled for you automatically. See the tip above.
+:::
+
 Private authwits authorize actions in the private domain. The authorization is included directly in the transaction that uses it.
 
 Let's say Alice wants to allow Bob to transfer tokens from her account. Alice is the **authorizer** (she owns the tokens) and Bob is the **caller** (he will execute the transfer):

docs/docs-developers/docs/foundational-topics/wallets.md

@@ -35,6 +35,8 @@ Private functions use a UTXO model, so their execution trace is determined entir
 Public functions use an account model (like Ethereum), so their execution trace depends on chain state at inclusion time, which may differ from simulation.
 :::
 
+Before sending, the wallet may run a **pre-simulation** — a lightweight simulation using a stub account contract that avoids expensive kernel circuit execution. This pre-simulation estimates gas limits for the transaction and captures any required private authorization data (see [Authorizing actions](#authorizing-actions) below). The `EmbeddedWallet` runs this step automatically on every send.
+
 Finally, the wallet **sends** the resulting _transaction_ object, which includes the proof of execution, to an Aztec Node. The transaction is then broadcasted through the peer-to-peer network, to be eventually picked up by a sequencer and included in a block.
 
 ## Authorizing actions
@@ -43,6 +45,8 @@ Account contracts in Aztec expose an interface for other contracts to validate [
 
 Wallets should manage these authorizations, prompting the user when they are requested by an application. Authorizations in private executions come in the form of _auth witnesses_, which are usually signatures over an identifier for an action. Applications can request the wallet to produce an auth witness via the `createAuthWit` call. In public functions, authorizations are pre-stored in the account contract storage, which is handled by a call to an internal function in the account contract implementation.
 
+Wallets can automate private authorization by capturing authorization requests during pre-simulation. The `EmbeddedWallet`, for example, detects which private authwits a transaction needs and generates them automatically, so dapps don't need to explicitly create or manage private authorizations. Public authorizations still require explicit setup, as they involve onchain state changes that must occur before the authorized action.
+
 ## Key management
 
 As in EVM-based chains, wallets are expected to manage user keys, or provide an interface to hardware wallets or alternative key stores. Keep in mind that in Aztec each account requires [multiple key pairs](./accounts/keys.md): protocol keys (nullifier and incoming viewing keys) are mandated by the protocol and used for spending notes and decryption, whereas signing keys are dependent on the account contract implementation rolled out by the wallet. Should the account contract support it, wallets must provide the user with the means to rotate or recover their signing keys.