feat(docs): private fpc guide (backport #22497) (#22538)

## Summary

Backport of #22497
to v4-next.

Cherry-pick had a minor conflict in `docs/docs-words.txt` (the
`indistinguishability` word addition conflicted with unrelated changes
in the spelling dictionary). Resolved by accepting the incoming word.

### Changes
- Adds `how_to_use_private_fee_juice.md` guide explaining fully private
fee payment using DeFi Wonderland's PrivateFPC
- Updates fee payment overview with Private FPC row in comparison table
- Adds private FPC paragraphs to foundational fees concept page and
participant fees page
- Adds `indistinguishability` to spellcheck dictionary

### Commits
1. Cherry-pick with conflict markers preserved
2. Conflict resolution in docs-words.txt

ClaudeBox log: https://claudebox.work/s/422d20244c5c0f73?run=1

Author: critesjosh

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

@@ -28,6 +28,7 @@ This guide walks you through paying transaction fees on Aztec using various paym
 #else
 | Sponsored FPC       | Testing, free transactions                     | Public          | None (devnet and local only) |
 #endif
+| Private FPC         | Privacy-preserving fees                        | Private         | Bridged Fee Juice via FPC    |
 | Third-party FPC     | Pay in other tokens on testnet/mainnet         | Varies by FPC   | FPC provider's SDK           |
 | Bridge + Claim      | Bootstrap from L1                              | Public          | L1 ETH for gas               |
 
@@ -110,6 +111,14 @@ Here's a simpler example from the test suite:
 
 #include_code sponsored_fpc_simple yarn-project/end-to-end/src/e2e_fees/sponsored_payments.test.ts typescript
 
+### Private Fee Payment
+
+For transactions where the fee payment itself should be private, you can use a fully private FPC — one that holds Fee Juice claimed from L1 as an internal private balance, works on every network, and never needs an onchain deployment. See [Pay Fees Privately](./how_to_use_private_fee_juice.md) for how this pattern works and a walkthrough using a community-built example.
+
+:::tip Shared salt for privacy
+When multiple apps derive the same private FPC address (using the same artifact and salt), every private fee payment joins a single, larger privacy set. See [Recommended salt](./how_to_use_private_fee_juice.md#recommended-salt-0) for details.
+:::
+
 ### Third-party FPCs on testnet and mainnet
 
 On networks where the Sponsored FPC is unavailable, third-party FPCs deployed by ecosystem teams let you pay fees in tokens other than Fee Juice. Each FPC provider typically offers an SDK or API that handles payment method construction on the client side — this may include quote fetching and authwit creation, though the exact flow depends on the FPC design. For background on how FPCs work at the protocol level, see [How FPCs work](../foundational-topics/fees.md#how-fpcs-work).
@@ -123,10 +132,10 @@ This FPC is quote-based and operates privately:
 - A single deployment accepts many tokens — the asset is selected per quote rather than hard-coded at deploy time.
 - Fee payments are transferred as private notes, so fee activity is not visible onchain.
 - An operator-run attestation service signs per-user quotes binding the FPC address, accepted asset, amounts, expiry, and user.
-- A cold-start entrypoint allows a brand-new account to bridge tokens from L1, claim on L2, and pay the fee in a single transaction.
+- A cold-start entrypoint allows a brand-new account to bridge tokens from L1, claim on L2, and pay the fee in a single transaction. Note that the cold-start path calls `Token::mint_to_private`, which enqueues a public call to update the token's total supply — so the minted amount is visible onchain even though the user's identity and balances remain private.
 
 :::warning Third-party software
-This FPC is developed and maintained by Nethermind, not by Aztec Labs. The SDK (`@nethermindeth/aztec-fpc-sdk`) is not yet published to npm — install from source per the [repository README](https://github.com/NethermindEth/aztec-fpc/blob/main/sdk/README.md). Review the [protocol spec](https://github.com/NethermindEth/aztec-fpc/blob/main/docs/spec/protocol-spec.md) and evaluate independently before integrating.
+This FPC is developed and maintained by Nethermind, not by Aztec Labs. The SDK (`@nethermindeth/aztec-fpc-sdk`) may not yet be published to npm — check the [repository README](https://github.com/NethermindEth/aztec-fpc/blob/main/sdk/README.md) for current install instructions. Review the [protocol spec](https://github.com/NethermindEth/aztec-fpc/blob/main/docs/spec/protocol-spec.md) and evaluate independently before integrating.
 :::
 
 The SDK wraps the quote-and-pay flow into a single call. The snippet below shows the general shape of the integration (illustrative — verify against the current SDK API before using):

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

@@ -0,0 +1,91 @@
+---
+title: Pay Fees Privately
+tags: [fees, privacy, fpc]
+sidebar_position: 8
+description: Learn how private fee payment works on Aztec and walk through an example using a community-built fully private Fee Payment Contract.
+---
+
+import { General, Fees } from '@site/src/components/Snippets/general_snippets';
+
+This guide explains how private fee payment works on Aztec and walks through a concrete example. A fully private FPC can pay transaction fees without revealing the payer — it has no public functions, no owner, and no offchain agent. Because the contract is fully private, **no onchain deployment transaction is required**. Every app just derives the address deterministically from the class hash and a shared salt, and users interact with it privately.
+
+To illustrate the pattern, this guide uses [`PrivateFPC`](https://github.com/defi-wonderland/aztec-fee-payment) — a community-built implementation by [DeFi Wonderland](https://github.com/defi-wonderland). You could write your own private FPC following the same design principles.
+
+## Prerequisites
+
+- <General.AztecJSPrerequisites />
+- Familiarity with [fee concepts](../foundational-topics/fees.md) and [Paying Fees](./how_to_pay_fees.md)
+
+:::info
+<Fees.FeeAsset_NonTransferrable />
+:::
+
+## Why a fully private FPC?
+
+The `PrivateFeePaymentMethod` shipped in `@aztec/aztec.js/fee` (now deprecated) targets the reference [`FPC` contract](https://github.com/AztecProtocol/aztec-packages/blob/next/noir-projects/noir-contracts/contracts/fees/fpc_contract/src/main.nr), which accepts an arbitrary asset and calls custom token functions (like `transfer_to_public`) during the setup phase of a transaction. Since Aztec v4.2.0, token functions are no longer in the default public setup allowlist, so that flow is rejected on public networks. See the [migration note](../resources/migration_notes.md#custom-token-fpcs-removed-from-default-public-setup-allowlist) for details.
+
+A fully private FPC avoids the problem entirely by holding Fee Juice claimed from L1 as an internal private balance and never making cross-contract calls during setup — it only verifies a Fee Juice nullifier exists and deducts from its own private balance, so it passes the allowlist on every network.
+
+## How a private FPC works
+
+This section describes the design pattern using Wonderland's `PrivateFPC` as an example. The contract stores an internal, note-based `BalanceSet` of Fee Juice per user. There is no constructor, no admin, and no public surface.
+
+Two flows are supported:
+
+1. **Bridge + mint + pay** (recommended steady state):
+    1. On L1, deposit Fee Juice to the `FeeJuicePortal`, targeting the FPC's Aztec address as the recipient and using a claimer-bound secret hash.
+    2. On L2, call `FeeJuice.claim(...)` to emit the Fee Juice nullifier.
+    3. Call `PrivateFPC.mint(amount, salt, leaf_index)` to convert the bridge claim into private Fee Juice balance inside the FPC, credited to the claimer.
+    4. From that point on, every transaction can call `PrivateFPC.pay_fee()` to deduct `max_gas_cost` from the internal balance and have the FPC set itself as the transaction's fee payer.
+2. **Cold-start:** First call `FeeJuice.claim(...)` so the Fee Juice nullifier lands onchain, then in a follow-up transaction call `PrivateFPC.mint_and_pay_fee(amount, salt, leaf_index)`. The contract verifies the nullifier exists, credits `amount - max_gas_cost` to the claimer, and pays the fee — useful when the user has no prior balance with the FPC.
+
+Because `pay_fee` never makes cross-contract calls — it only deducts from the FPC's internal private balance and calls `set_as_fee_payer` — no custom token calls ever happen during the setup phase.
+
+:::note No refund
+`PrivateFPC.pay_fee()` deducts the full `max_gas_cost` and does not refund unused gas. Use `estimateGas` (see [Estimate mana costs](./how_to_pay_fees.md#estimate-mana-costs)) to right-size your limits.
+:::
+
+## Share one FPC address across the ecosystem
+
+Privacy on Aztec comes from indistinguishability. When two transactions call the *same* contract with the *same* function selector and argument shape, they are indistinguishable to an outside observer. If your app derives its own copy of a private FPC with a unique salt, that copy has its own (tiny) anonymity set. If every app derives the *same* FPC address and routes fees through it, every private fee payment in the ecosystem looks the same, and they all share a single, much larger privacy set.
+
+This is the whole point of a fully private FPC: because you don't have to deploy it on L2, there is no race to "be the deployer" — the only thing that matters is that everyone agrees on the address.
+
+## Recommended salt: `0`
+
+Two parties derive the same contract address if and only if they use the same compiled artifact and the same deployment salt. For any fully private FPC, using a common salt maximizes the shared privacy set. The community convention for Wonderland's `PrivateFPC` is `Fr.ZERO`.
+
+This is a convention, not a protocol-enforced default. It is up to each developer to pass the salt when registering the contract with their PXE, just as they choose any other deployment parameter. Following the convention means your users' private fee payments join the same privacy set as every other app that follows it.
+
+:::danger Version-specific addresses
+The `PrivateFPC` address depends on the compiled contract bytecode. A different Aztec version produces different bytecode and therefore a **different address**. Sending Fee Juice to the wrong address means **unrecoverable loss**. Before using a derived address on a given network, verify the network runs the same Aztec version as the Wonderland SDK version you have installed.
+:::
+
+## Example: pay fees with Wonderland's `PrivateFPC`
+
+The SDK exports two payment methods (`FPCFeePaymentMethod` for users who already have a private balance, and `PrivateMintAndPayFeePaymentMethod` for cold-start) plus a `registerPrivateContract` helper that registers the FPC with your PXE using the shared salt — no deployment transaction needed.
+
+For installation, the complete bridge-claim-mint-pay flow, required `send()` options (including `additionalScopes` and `gasSettings`), and a runnable end-to-end example, see the [SDK README](https://github.com/defi-wonderland/aztec-fee-payment/blob/dev/src/ts/README.md) and the [integration test](https://github.com/defi-wonderland/aztec-fee-payment/blob/dev/src/ts/test/private.test.ts).
+
+:::note Transaction behavior
+| Scenario | Status | Execution result | Fee paid? |
+| --- | --- | --- | --- |
+| Private revert | `DROPPED` (not included in block) | — | No |
+| Public revert | `PROPOSED` | `REVERTED` | Yes (FPC pays) |
+| Success | `PROPOSED` | `SUCCESS` | Yes (FPC pays) |
+:::
+
+## Reference implementation
+
+Wonderland's repository ships detailed documentation for this design and its security properties:
+
+- [Private FPC Product Requirements](https://github.com/defi-wonderland/aztec-fee-payment/blob/dev/docs/private-product-requirements.md) — problem statement, requirements matrix, cryptographic design (secret derivation, nullifier reconstruction, double-spend prevention), and security properties
+- [`PrivateFPC` Noir source](https://github.com/defi-wonderland/aztec-fee-payment/blob/dev/src/nr/private_contract/src/main.nr) — the contract itself, annotated with the full bridge-to-mint-to-pay flow
+- [`src/ts/README.md`](https://github.com/defi-wonderland/aztec-fee-payment/blob/dev/src/ts/README.md) — SDK reference with every exported class and utility
+- [Integration test `private.test.ts`](https://github.com/defi-wonderland/aztec-fee-payment/blob/dev/src/ts/test/private.test.ts) — canonical end-to-end example of the bridge → claim → mint → sponsor flow
+
+## Next steps
+
+- Learn about [fee concepts](../foundational-topics/fees.md) in detail
+- Review the other [fee payment methods](./how_to_pay_fees.md) available in `aztec.js`
+- Browse Wonderland's [`aztec-fee-payment`](https://github.com/defi-wonderland/aztec-fee-payment) repository for the Noir source, TypeScript SDK, and integration examples

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

@@ -104,6 +104,8 @@ Key properties for developers integrating with an FPC:
 - **Quote expiry.** Quotes are time-bound and single-use. Fetch a fresh quote per transaction.
 - **Cold-start variant.** Some FPCs offer a cold-start entrypoint where a brand-new account can bridge tokens from L1, claim them on L2, and pay the fee in one transaction — no prior L2 balance or authwit needed, because the FPC itself claims and distributes the bridged tokens. The user still needs L1 tokens and ETH for the initial bridge transaction.
 
+Fee payments themselves can also be made private via a fully private FPC that holds Fee Juice internally and nominates itself as the fee payer during the setup phase — without revealing who initiated the transaction. See [Pay Fees Privately](../aztec-js/how_to_use_private_fee_juice.md) for how this pattern works and an example implementation.
+
 ### Teardown phase
 
 <Tx_Teardown_Phase />

docs/docs-participate/basics/fees.md

@@ -68,6 +68,11 @@ A fee-paying contract (FPC) pays $AZTEC (referred to as "Fee Juice" in the devel
 - **Sponsored FPC** — available on testnet and local network, covers transaction costs for free. Useful for development and onboarding examples.
 - **Third-party FPCs** — deployed by ecosystem teams for use on testnet and mainnet. These accept various tokens and handle $AZTEC fee payment behind the scenes. As one example, Nethermind offers a [Private Multi Asset FPC](https://github.com/NethermindEth/aztec-fpc) that supports multiple tokens with private fee transfers.
 
+### Private Fee Payment
+Some apps pay fees through a fully private fee-paying contract, so the fee payment itself leaks no information about who you are. The more apps that route private fee payments through the *same* contract address, the stronger your privacy — every payment shares one large anonymity set instead of many small ones.
+
+If you care about fee privacy, look for apps that use a shared private FPC. For example, [DeFi Wonderland](https://github.com/defi-wonderland/aztec-fee-payment) has built a community implementation where every app can derive the same contract address from a common deployment salt. Note that the derived address depends on the compiled contract bytecode, which changes between Aztec versions — always verify the address matches the network you are using.
+
 ## Understanding Your Fee
 
 Transaction fees have several components:

docs/docs-words.txt

@@ -409,3 +409,4 @@ interoperate
 reentrancy
 variadic
 Wonderland
+indistinguishability