feat(docs): nethermind fpc docs (backport to v4-next) (#22532)

critesjosh · web-flow · commit adcfdb81c14f · 2026-04-14T13:52:22.000-04:00
## Summary Backport of #22496 to v4-next. Cherry-pick applied cleanly — no conflicts. ### Original PR Adds documentation for third-party Fee Payment Contracts (FPCs) on testnet and mainnet, using Nethermind's Private Multi Asset FPC as a reference integration example. ClaudeBox log: https://claudebox.work/s/b06a98c8d4c9aeda?run=1
diff --git a/docs/docs-developers/docs/aztec-js/how_to_create_account.md b/docs/docs-developers/docs/aztec-js/how_to_create_account.md
@@ -36,12 +36,12 @@ New accounts must be deployed before they can send transactions. Deployment requ
 
 ### Using the Sponsored FPC
 
-If your account doesn't have Fee Juice, use the [Sponsored Fee Payment Contract](./how_to_pay_fees.md#sponsored-fee-payment-contracts):
+If your account doesn't have Fee Juice, use the [Sponsored FPC](./how_to_pay_fees.md#sponsored-fpc-devnet-and-local-only):
 
 #include_code deploy_account_sponsored_fpc /docs/examples/ts/aztecjs_connection/index.ts typescript
 
 :::info
-See the [guide on fees](./how_to_pay_fees.md#sponsored-fee-payment-contracts) for setting up the Sponsored FPC.
+See the [guide on fees](./how_to_pay_fees.md#sponsored-fpc-devnet-and-local-only) for setting up the Sponsored FPC.
 :::
 
 ### Using Fee Juice
diff --git a/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md b/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md
@@ -20,15 +20,16 @@ This guide walks you through paying transaction fees on Aztec using various paym
 
 ## Payment methods overview
 
-| Method              | Use Case                      | Privacy | Requirements               |
-| ------------------- | ----------------------------- | ------- | -------------------------- |
-| Fee Juice (default) | Account already has Fee Juice | Public  | Funded account             |
+| Method              | Use Case                                       | Privacy         | Requirements                 |
+| ------------------- | ---------------------------------------------- | --------------- | ---------------------------- |
+| Fee Juice (default) | Account already has Fee Juice                  | Public          | Funded account               |
 #if(devnet)
-| Sponsored FPC       | Testing, free transactions    | Public  | None                       |
+| Sponsored FPC       | Testing, free transactions                     | Public          | None                         |
 #else
-| Sponsored FPC       | Testing, free transactions    | Public  | None (devnet and local only) |
+| Sponsored FPC       | Testing, free transactions                     | Public          | None (devnet and local only) |
 #endif
-| Bridge + Claim      | Bootstrap from L1             | Public  | L1 ETH for gas             |
+| 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               |
 
 ## Mana and Fee Juice
 
@@ -81,9 +82,13 @@ If your account has Fee Juice (for example, from a faucet), is [deployed](./how_
 
 ## Use Fee Payment Contracts
 
-Fee Payment Contracts (FPCs) pay Fee Juice on your behalf. FPCs must use Fee Juice exclusively on L2 during the setup phase; custom token contract functions cannot be called during setup on public networks. An FPC that accepts other tokens on L1 and bridges Fee Juice works on any network.
+Fee Payment Contracts (FPCs) pay Fee Juice on your behalf. An FPC holds its own Fee Juice balance to pay the protocol and can accept other tokens from users in exchange. Some FPCs operate privately by design, routing fee payments through private notes rather than public function calls.
 
-### Sponsored Fee Payment Contracts
+:::note
+The SDK includes `PrivateFeePaymentMethod` and `PublicFeePaymentMethod` classes for the built-in reference FPC, but these are **deprecated** and do not work on mainnet alpha. For custom-token fee payment, use a third-party FPC with its own SDK (see [below](#third-party-fpcs-on-testnet-and-mainnet)).
+:::
+
+### Sponsored FPC (devnet and local only)
 
 #if(testnet)
 :::note
@@ -105,6 +110,53 @@ 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
 
+### 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).
+
+#### Example: Nethermind Private Multi Asset FPC
+
+To illustrate how a third-party FPC integration works, the following walkthrough uses Nethermind's [Private Multi Asset FPC](https://github.com/NethermindEth/aztec-fpc) as a reference. This is one implementation — other FPCs may differ in design and API.
+
+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.
+
+:::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.
+:::
+
+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):
+
+```ts
+import { FpcClient } from "@nethermindeth/aztec-fpc-sdk";
+
+// Point the client at the FPC's attestation service
+const fpcClient = new FpcClient({
+  fpcAddress,       // the deployed FPC contract address
+  operator,         // operator's Aztec address
+  node,             // PXE or node connection
+  attestationBaseUrl: "https://...",  // attestation service URL from the FPC provider
+});
+
+// Estimate gas, fetch a signed quote, and build the payment method
+const payment = await fpcClient.createPaymentMethod({
+  wallet,
+  user: wallet.getAddress(),
+  tokenAddress,     // the token you want to pay in
+  estimatedGas,     // from a prior estimateGas call
+});
+
+// Use it like any other payment method
+const tx = await myContract.methods.myMethod(args).send({ fee: payment.fee });
+await tx.wait();
+```
+
+For the cold-start flow, deployment addresses, and the full API, see the [`aztec-fpc` repository](https://github.com/NethermindEth/aztec-fpc).
+
 ## Bridge Fee Juice from L1
 
 Fee Juice is non-transferable on L2, but you can bridge it from L1, claim it on L2, and use it. This involves a few components that are part of a running network's infrastructure:
diff --git a/docs/docs-developers/docs/foundational-topics/fees.md b/docs/docs-developers/docs/foundational-topics/fees.md
@@ -83,20 +83,37 @@ Fee Juice uses an enshrined `FeeJuicePortal` contract on Ethereum for bridging,
 
 An account with Fee Juice can pay for its transactions directly. A new account can even pay for its own deployment transaction, provided Fee Juice was bridged to its address before deployment.
 
-Alternatively, accounts can use [fee-paying contracts (FPCs)](../aztec-js/how_to_pay_fees.md#use-fee-payment-contracts) to pay for transactions. FPCs must use Fee Juice exclusively on L2 during the setup phase, but can accept other tokens on L1 and bridge Fee Juice.
+Alternatively, accounts can use [fee-paying contracts (FPCs)](../aztec-js/how_to_pay_fees.md#use-fee-payment-contracts) to pay for transactions. An FPC holds its own Fee Juice balance to pay the protocol, and can accept other tokens from users in exchange.
 
-The **Sponsored FPC** pays fees unconditionally, enabling free transactions. It is only available on devnet and local network.
+The **Sponsored FPC** pays fees unconditionally, enabling free transactions. It is only available on devnet and local network. For testnet and mainnet, ecosystem-deployed FPCs are the practical option — the built-in reference FPC contract does not work on mainnet alpha because custom token class IDs are not included in the default public setup allowlist. As an example, Nethermind's [Private Multi Asset FPC](https://github.com/NethermindEth/aztec-fpc) demonstrates one such design — it accepts multiple tokens and routes fee payments as private notes.
+
+### How FPCs work
+
+An FPC acts as a fee payer on the user's behalf. Simpler FPCs (like the Sponsored FPC) just call `set_as_fee_payer()` with no user payment at all. More sophisticated FPCs accept user tokens in exchange for paying Fee Juice. A common pattern for quote-based FPCs works as follows:
+
+1. **Quote.** The user requests a fee quote from the FPC operator, specifying the token they want to pay with and the estimated gas cost. The operator signs the quote, binding it to the user, asset, amounts, and an expiry.
+2. **Authorization.** The user creates an [authentication witness](./advanced/authwit.md) authorizing the FPC to transfer tokens from their balance. This is the same authwit mechanism used for any delegated token transfer.
+3. **Setup phase (non-revertible).** The FPC's entrypoint runs during the transaction's setup phase. It verifies the quote, collects the user's payment, declares itself as the fee payer via `set_as_fee_payer()`, and calls `end_setup()` to mark the boundary between non-revertible and revertible execution. Because this runs in the non-revertible phase, the payment is **irrevocably committed** before application logic executes — the user pays regardless of whether the app-logic phase reverts.
+4. **App phase (revertible).** The user's actual transaction logic runs here. In the common fee-entrypoint flow the FPC is not involved in this phase, though some FPC designs (such as cold-start flows) perform additional app-phase work like claiming bridged tokens.
+
+Key properties for developers integrating with an FPC:
+
+- **Authwit scope.** The authwit authorizes a specific action hash (typically covering the transfer amount). A nonce can be included when otherwise-identical actions need to be distinguishable. The authwit is single-use — consumed by a nullifier onchain.
+- **Token interface.** The FPC calls the token contract's transfer function (private or public, depending on the FPC design). Any token that implements the standard Aztec token interface with authwit verification is compatible.
+- **Gas estimation first.** The Fee Juice amount in the quote is typically derived from the transaction's gas estimate. Simulate and estimate gas *before* requesting a quote, then pass the estimated cost to the FPC operator.
+- **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.
 
 ### Teardown phase
 
 <Tx_Teardown_Phase />
 
-This enables FPCs to calculate the actual transaction cost and refund any overpayment to the user.
+This enables FPCs to calculate the actual transaction cost and refund any overpayment to the user. Not all FPC designs use the teardown phase — some charge a fixed quoted amount with no refund, keeping unused Fee Juice in the FPC's balance for future transactions.
 
 ### Operator rewards
 
 The calculated fee of a transaction is deducted from the fee payer (nominated account or fee-paying contract), then pooled together across transactions, blocks, and epochs. Once an epoch is proven, the total collected fees (minus any burnt congestion amount) are distributed to the provers and block proposers that contributed to the epoch.
 
 ## Next steps
 
-For a guide on paying fees programmatically, see [How to Pay Fees](../aztec-js/how_to_pay_fees).
+For a guide on paying fees programmatically, see [How to Pay Fees](../aztec-js/how_to_pay_fees.md).
diff --git a/docs/docs-participate/basics/fees.md b/docs/docs-participate/basics/fees.md
@@ -61,8 +61,12 @@ Aztec offers flexible fee payment:
 ### Pay Directly
 If you have $AZTEC, pay for your own transactions directly from your account.
 
-### Sponsored Transactions
-Fee-paying contracts can pay fees on your behalf. For example, on devnet and local network, a sponsored fee-paying contract covers transaction costs for free. FPCs can also accept other tokens on L1 and bridge $AZTEC to pay fees.
+### Fee-Paying Contracts
+
+A fee-paying contract (FPC) pays $AZTEC (referred to as "Fee Juice" in the developer docs) on your behalf, typically in exchange for another token. This lets applications accept fees in tokens their users already hold and lets brand-new accounts transact without first acquiring $AZTEC.
+
+- **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.
 
 ## Understanding Your Fee
 
