feat(fortuna): Add max_fee config option and add AGENTS.md (#3291)

* Add max_fee configuration option and update documentation

- Introduced an optional `max_fee` parameter in the Ethereum configuration to clamp dynamically calculated fees.
- Updated the fee adjustment logic to respect the `max_fee` cap.
- Enhanced README with contributing guidelines for repository workflows and review expectations.

* bump ver

Author: tejasbadadare

Cargo.lock

@@ -0,0 +1,26 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Runtime code sits in `src/`, with `api/`, `chain/`, `keeper/`, and `command/` owning HTTP routes, blockchain adapters, keeper loops, and CLI verbs exposed by `main.rs`. Shared types live in `lib.rs`, configuration templates in `config.sample.yaml`, migrations in `migrations/`, and build helpers (Dockerfile, flake.nix, check-sqlx.sh) at the root.
+
+## Build, Test, and Development Commands
+- `cargo build --workspace`: compile the web service and helper binaries.
+- `cargo test [-- --nocapture]`: run unit/integration suites, optionally showing logs.
+- `RUST_LOG=INFO cargo run -- run`: start the local server using `config.yaml`.
+- `cargo run -- setup-provider`: register the randomness provider specified in the config.
+- `cargo sqlx migrate run` or `database reset`: apply or reset schema using the `.env` `DATABASE_URL`.
+- `./check-sqlx.sh`: ensure SQLx offline metadata is current before DB-affecting commits.
+- `cli start | cli test | cli fix`: Nix-shell shortcuts for watch, verify, and autofix loops.
+
+## Coding Style & Naming Conventions
+Always run `cargo fmt --all` and `cargo clippy --all-targets --all-features -D warnings` so submissions match CI expectations (4-space indent, trailing commas, no lint debt). Modules and files use snake_case, public structs/enums use PascalCase, and constants remain SCREAMING_SNAKE_CASE. Align YAML/TOML samples with `config.sample.yaml`, and reference secrets by env var rather than literals.
+
+## Testing Guidelines
+Keep module-level tests inside the relevant file (`#[cfg(test)]` blocks) and add `tests/` integration suites for CLI flows or keeper orchestration. Run `cargo sqlx migrate run` after editing migrations so `cargo test` interacts with the right schema. Prioritize coverage on chain adapters, keeper scheduling, replica assignment, and API pagination, mocking RPC traits to avoid network flakiness.
+
+## Commit & Pull Request Guidelines
+Git history uses `type(scope): summary` (`fix(lazer)`, `chore(contract-manager): ...`), so keep subjects imperative and ≤72 characters, and isolate unrelated changes. Include regenerated SQLx data or config snapshots in the same commit that needs them. PRs should describe motivation, list the verification commands executed (`cargo test`, `./check-sqlx.sh`, etc.), and attach logs or screenshots whenever behavior changes. 
+**Important**: When changing code, bump the package version in `Cargo.toml` based on semantic versioning. Run `cargo check` to ensure the changes are reflected in the Cargo.lock lockfile.
+
+## Security & Configuration Tips
+Do not commit `config.yaml`, `.env`, or private keys—derive them from `config.sample.yaml` and inject secrets through env vars or secret stores. Each replica must run with unique `keeper.private_key` values, and only the fee-managing instance should hold `keeper.fee_manager_private_key`. Remove sensitive details from logs before sharing and rotate credentials immediately if a leak is suspected.

apps/fortuna/AGENTS.md

@@ -1,6 +1,6 @@
 [package]
 name = "fortuna"
-version = "9.2.2"
+version = "9.3.0"
 edition = "2021"
 
 [lib]

apps/fortuna/Cargo.toml

@@ -144,3 +144,7 @@ automatically.  If you use this configuration you will have a `cli` script in
 your dev shell which provides easy access to some common tasks, such as `cli
 start` to start the server in watch mode, `cli test` to run unit, code format,
 and lint checks, and `cli fix` to run auto-fixes for formatting and lint issues.
+
+## Contributing
+
+See [AGENTS.md](./AGENTS.md) for repository guidelines covering project layout, workflows, and review expectations before opening a pull request.

apps/fortuna/README.md

@@ -32,6 +32,9 @@ chains:
     # How much to charge in fees
     fee: 1500000000000000
 
+    # Optional hard cap on the fee (in wei). If the dynamically calculated fee exceeds this, it will be clamped.
+    # max_fee: 10000000000000000
+
     # Set this temporarily to false if you have changed the fees and want to apply a new baseline fee.
     sync_fee_only_on_register: true
 

apps/fortuna/config.sample.yaml

@@ -609,6 +609,7 @@ mod test {
                 max_profit_pct: 100,
                 min_keeper_balance: 100000000000000000,
                 fee: 1500000000000000,
+                max_fee: None,
                 sync_fee_only_on_register: true,
                 commitments: None,
                 max_num_hashes: None,
@@ -632,6 +633,7 @@ mod test {
                 max_profit_pct: 100,
                 min_keeper_balance: 100000000000000000,
                 fee: 2000000000000000,
+                max_fee: None,
                 sync_fee_only_on_register: true,
                 commitments: None,
                 max_num_hashes: None,

apps/fortuna/src/api.rs

@@ -190,6 +190,11 @@ pub struct EthereumConfig {
     #[serde(default)]
     pub fee: u128,
 
+    /// Optional hard cap on the fee (in wei). If the dynamically calculated fee exceeds this,
+    /// it will be clamped to this value. When None, no cap is applied.
+    #[serde(default)]
+    pub max_fee: Option<u128>,
+
     /// Only set the provider's fee when the provider is registered for the first time. Default is true.
     /// This is useful to avoid resetting the fees on service restarts.
     #[serde(default = "default_sync_fee_only_on_register")]

apps/fortuna/src/config.rs

@@ -169,6 +169,7 @@ pub async fn run_keeper_threads(
                 u64::try_from(100 + chain_eth_config.max_profit_pct)
                     .expect("max_profit_pct must be >= -100"),
                 chain_eth_config.fee,
+                chain_eth_config.max_fee,
                 metrics.clone(),
             )
             .in_current_span(),

apps/fortuna/src/keeper.rs

@@ -230,6 +230,7 @@ pub async fn adjust_fee_wrapper(
     target_profit_pct: u64,
     max_profit_pct: u64,
     min_fee_wei: u128,
+    max_fee_wei: Option<u128>,
     metrics: Arc<KeeperMetrics>,
 ) {
     // The maximum balance of accrued fees + provider wallet balance. None if we haven't observed a value yet.
@@ -246,6 +247,7 @@ pub async fn adjust_fee_wrapper(
             target_profit_pct,
             max_profit_pct,
             min_fee_wei,
+            max_fee_wei,
             &mut high_water_pnl,
             &mut sequence_number_of_last_fee_update,
             metrics.clone(),
@@ -261,7 +263,8 @@ pub async fn adjust_fee_wrapper(
 
 /// Adjust the fee charged by the provider to ensure that it is profitable at the prevailing gas price.
 /// This method targets a fee as a function of the maximum cost of the callback,
-/// c = (gas_limit) * (current gas price), with min_fee_wei as a lower bound on the fee.
+/// c = (gas_limit) * (current gas price), with min_fee_wei as a lower bound and max_fee_wei as an
+/// optional upper bound on the fee.
 ///
 /// The method then updates the on-chain fee if all of the following are satisfied:
 /// - the on-chain fee does not fall into an interval [c*min_profit, c*max_profit]. The tolerance
@@ -282,6 +285,7 @@ pub async fn adjust_fee_if_necessary(
     target_profit_pct: u64,
     max_profit_pct: u64,
     min_fee_wei: u128,
+    max_fee_wei: Option<u128>,
     high_water_pnl: &mut Option<U256>,
     sequence_number_of_last_fee_update: &mut Option<u64>,
     metrics: Arc<KeeperMetrics>,
@@ -313,11 +317,11 @@ pub async fn adjust_fee_if_necessary(
         .get_or_create(&account_label)
         .set((max_callback_cost / gas_limit) as f64 / 1e9);
 
-    let target_fee_min = std::cmp::max(
+    let mut target_fee_min = std::cmp::max(
         (max_callback_cost * u128::from(min_profit_pct)) / 100,
         min_fee_wei,
     );
-    let target_fee = std::cmp::max(
+    let mut target_fee = std::cmp::max(
         (max_callback_cost * u128::from(target_profit_pct)) / 100,
         min_fee_wei,
     );
@@ -326,11 +330,19 @@ pub async fn adjust_fee_if_necessary(
         .get_or_create(&account_label)
         .set(((max_callback_cost * u128::from(target_profit_pct)) / 100) as f64 / 1e18);
 
-    let target_fee_max = std::cmp::max(
+    let mut target_fee_max = std::cmp::max(
         (max_callback_cost * u128::from(max_profit_pct)) / 100,
         min_fee_wei,
     );
 
+    // Apply max fee cap if configured, but ensure it doesn't go below min_fee_wei
+    if let Some(max_fee) = max_fee_wei {
+        let effective_max = std::cmp::max(max_fee, min_fee_wei);
+        target_fee_min = std::cmp::min(target_fee_min, effective_max);
+        target_fee = std::cmp::min(target_fee, effective_max);
+        target_fee_max = std::cmp::min(target_fee_max, effective_max);
+    }
+
     // Calculate current P&L to determine if we can reduce fees.
     let current_keeper_balance = contract
         .provider()