docs: clarify FeeVault is optional, document when to use it vs plain baseFeeSink

Author: randygrok

contracts/README.md

@@ -8,14 +8,17 @@ The AdminProxy contract solves the bootstrap problem for admin addresses at gene
 
 See [AdminProxy documentation](../docs/contracts/admin_proxy.md) for detailed setup and usage instructions.
 
-## FeeVault
+## FeeVault (optional)
 
-The FeeVault contract collects base fees and distributes them between a bridge recipient and an optional secondary recipient. It supports:
+The FeeVault is an **optional** contract for chains that need on-chain fee splitting logic. The base fee redirect (`baseFeeSink`) works with any address — an EOA or multisig is sufficient if you just need fees sent to a single destination.
 
-- Configurable fee splitting between bridge and another recipient
-- Minimum amount thresholds before distributing
-- Call fee for incentivizing distribution calls
-- Owner-controlled configuration
+FeeVault is useful when you need:
+
+- **Automatic splitting** of accumulated fees between two recipients (e.g., 80% to a bridge contract, 20% to a treasury)
+- **Minimum threshold** to avoid distributing uneconomically small amounts
+- **Keeper incentive** (`callFee`) so anyone can trigger distribution and get compensated
+
+If your chain only needs fees routed to a single address, skip FeeVault and point `baseFeeSink` directly at that address.
 
 ## Prerequisites
 

docs/contracts/fee_vault.md

@@ -2,11 +2,21 @@
 
 ## Overview
 
-The `FeeVault` is a specialized smart contract designed to accumulate native tokens (gas tokens) and automatically split them between a bridge recipient and a secondary recipient.
+The `FeeVault` is an **optional** smart contract for chains that need on-chain fee splitting logic. It accumulates native tokens (gas tokens) and automatically splits them between two configurable recipients.
+
+## When to Use FeeVault
+
+The base fee redirect (`baseFeeSink`) works with any address. You **do not need** FeeVault if fees should go to a single destination — just point `baseFeeSink` at an EOA or multisig.
+
+FeeVault adds value when you need:
+
+- **Splitting**: Automatically divide fees between two recipients (e.g., 80% to a bridge, 20% to treasury).
+- **Minimum threshold**: Only distribute when enough has accumulated to be economically worthwhile.
+- **Keeper incentive**: A `callFee` rewards anyone who triggers the distribution, removing the need for a centralized operator.
 
 ## Use Case
 
-This contract serves as a **fee sink** and **distribution mechanism** for a rollup or chain that wants to redirect collected fees (e.g., EIP-1559 base fees) to configured recipients while retaining a portion for other purposes (e.g., developer rewards, treasury).
+This contract serves as a **fee sink** and **distribution mechanism** for a rollup or chain that wants to redirect collected fees (e.g., EIP-1559 base fees) to multiple recipients.
 
 1. **Fee Accumulation**: The contract receives funds from:
     - **Base Fee Redirect**: The chain's execution layer (e.g., `ev-revm`) can be configured to direct burned base fees directly to this contract's address.

docs/guide/fee-systems.md

@@ -31,18 +31,18 @@ These components are independent but commonly deployed together. The base fee re
 
 See `docs/adr/ADR-0001-base-fee-redirect.md` for implementation details.
 
-## FeeVault (contract level)
+## FeeVault (contract level, optional)
 
-**Purpose**: Accumulate native tokens and split them between a bridge recipient and a secondary recipient.
+**Purpose**: Accumulate native tokens and split them between two configurable recipients.
+
+FeeVault is **optional**. The base fee redirect works with any address — if fees should go to a single destination, point `baseFeeSink` at an EOA or multisig and skip FeeVault entirely. Use FeeVault when you need automatic on-chain splitting, minimum thresholds, or keeper incentives.
 
 **Mechanics**:
 
 - Receives base fees when `baseFeeSink` is set to the FeeVault address.
 - Anyone can trigger `distribute()` once the minimum threshold is met.
 - Splits balance by `bridgeShareBps`, sends the bridge share to `bridgeRecipient`, and transfers the remainder to `otherRecipient`.
 
-**Why it pairs with base fee redirect**: the redirect funnels base fees into the FeeVault automatically, turning burned fees into recoverable value for treasury or bridging.
-
 See `docs/contracts/fee_vault.md` for parameters and deployment details.
 
 ## Native Token Minting Precompile
@@ -69,17 +69,19 @@ See `docs/adr/ADR-0002-native-minting-precompile.md` for the full interface and
 
 ## How They Fit Together
 
-1. **Base fee redirect** credits base fees to a sink address instead of burning them.
-2. **FeeVault** can be that sink, so base fees accumulate in a contract with deterministic split logic.
+1. **Base fee redirect** credits base fees to a sink address instead of burning them. The sink can be any address (EOA, multisig, or contract).
+2. **FeeVault** is one option for that sink when you need automatic splitting between two recipients. If fees go to a single destination, skip it.
 3. **Native minting** is separate and optional; it is used for controlled supply changes (bootstrapping liquidity, treasury operations), not for redirecting fees.
 
 In other words, base fee redirect and FeeVault are about re-routing existing value, while native minting explicitly changes total supply. Keep those responsibilities separate and limit minting access to minimize systemic risk.
 
-## Suggested Deployment Pattern
+## Suggested Deployment Patterns
+
+**Simple (no FeeVault):** Set `baseFeeSink` to an EOA or multisig. Fees accumulate there directly.
+
+**With splitting (FeeVault):** Set `baseFeeSink` to the FeeVault address. Configure the split between `bridgeRecipient` and `otherRecipient`. Use `AdminProxy` as the FeeVault owner if you need a safe, upgradeable admin.
 
-- Set `baseFeeSink` to the FeeVault address.
-- Use `AdminProxy` as the `mintAdmin` and FeeVault owner if you need a safe, upgradeable admin.
-- Activate both features at a planned height for existing networks.
+Both patterns can be combined with native minting if needed. Activate features at a planned height for existing networks.
 
 References: