feat(fees): move the open-bucket cascade carve into GenVM ✨

[kp2pml30]

What

GenVM applies the open-bucket cascade carve that the node used to apply after execution: each sender-pool internal message of an open-bucket transaction is raised to the chain floor, then the children share half of the spare pool equally

Delivery Context

Hub: https://github.com/genlayerlabs/genlayer-node/pull/2218
Base: v0.6-dev, which includes the descendant grants of #59

Changes

• Manager API: optional message_fee_cascade {min_primary_fee, budget_total} on the run request, null by default, cleared for nested runs
• Executor v0.3 (pr/v0.3/feat/open-bucket-carve): rt::cascade::apply rewrites the final emissions before the execution hash. v0.2 is untouched: it serves Studio backward compatibility only
  • fee = max(fee, min_primary_fee) for every sender-pool internal and deploy message (use_balance ones are skipped)
  • spare = budget_total - Σ fee; if positive, each gets spare / (2 * N) more
  • Buckets are not charged for the addition; data_fees_remaining is unchanged
• Impl-spec (04-fees.rst) and manager-api.yaml document the input
• Integration runner forwards message_fee_cascade from a case; new case message/open_bucket_cascade

Equivalence With the Node

Same arithmetic as the node's removed clampInternalMessageFees carve, including the funded total (messageFeesBudgetTotal, not the remaining pool), integer division order and the set of counted messages. A single floor suffices because the node gives every synthesized open-bucket internal node the same params; the node PR has a test for that invariant

Validation

• rt::cascade unit tests: 5/5
• Integration open_bucket_cascade: leader, validator and sync all agree; 2 sender-pool messages floored to 100000 then +200000 each, the use_balance one keeps its metered fee
• Neighbouring cases use_balance_no_alloc, send_message_on on both lines: 33/33
• ninja all/bin cargo/clippy cargo/fmt: clean

Risks

• Execution hash now covers the raised fees: node and GenVM must be upgraded together; mixed old/new validators disagree on open-bucket receipts with sender-pool children
• A new node with an old manager fails, because calldata decoding rejects the unknown field
• Studio does not send the field and keeps its current behaviour

Summary by CodeRabbit

• New Features
  • Open-pool executions can now optionally configure a message-fee cascade, specifying a minimum primary fee and a total message-fee budget.
  • Eligible messages receive at least the configured minimum; any remaining budget may be distributed among them. Balance-funded and external messages are unchanged.
  • The cascade setting applies only to top-level executions and is optional.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: genlayerlabs/genvm-manager/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7931843d-695f-47cc-b3b4-aea306dcd054

📥 Commits

Reviewing files that changed from the base of the PR and between 42e6693 and 6f4ff08.

⛔ Files ignored due to path filters: 2

• implementation/src/manager/run_test.rs is excluded by !**/*_test.rs
• tests/runner/genvm_tool_plugins/integration.py is excluded by !**/tests/**

📒 Files selected for processing: 6

• crates/modules-interfaces/src/domain.rs
• crates/modules-interfaces/src/domain/fees/mod.rs
• docs/website/src/impl-spec/04-fees.rst
• docs/website/src/impl-spec/appendix/manager-api.yaml
• executors/v0.3.x
• implementation/src/manager/run.rs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The manager request and ExecutionData now carry an optional MessageFeeCascade. The manager passes it to top-level execution data and clears it for nested runs. The API schema and fee specification describe the parameter and fee rewrite. The executors/v0.3.x reference points to a new commit.

Changes: Message fee cascade

Layer / File(s)	Summary
Define the cascade contract crates/modules-interfaces/src/domain/fees/mod.rs, crates/modules-interfaces/src/domain.rs, implementation/src/manager/run.rs, docs/website/src/impl-spec/appendix/manager-api.yaml	Adds the serializable MessageFeeCascade type and optional cascade fields to execution data and manager requests. The API schema defines the nullable parameter and its required uint256 values.
Propagate cascade to top-level execution implementation/src/manager/run.rs, docs/website/src/impl-spec/04-fees.rst, executors/v0.3.x	The manager passes the request value to top-level execution data and sets it to None for nested runs. The fee specification documents the fee rewrite, and the executor reference changes to a new commit.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to 6f4ff

No confirmed issue in the supplied changes blocks merging. Validate v0.2 compatibility as part of the coordinated upgrade.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files. (3 skipped: 3 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the main change: moving the open-bucket cascade fee adjustment into GenVM.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 2

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.98.1)

Clippy execution failed

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

GenVM PR actions

Tick a box to run it (the box unticks itself when handled). Actions only run while the PR has the ci-safe label.

• Force run full tests
• Provision executor PRs

Commands

• /genvm-run-tests — run full tests once for the current manager snapshot
• /merge — queue the exact manager snapshot through the App-owned E2E merge train

[github-actions]

Linked executor PR(s)

executor: genlayerlabs/genvm-executor#53 (v0.2)
executor: genlayerlabs/genvm-executor#54 (v0.3)

[kp2pml30]

/genvm-run-tests

[github-actions]

👀 Full tests are running for 5788b2b0de82: open run #38586859505

[kp2pml30]

/genvm-run-tests

[github-actions]

👀 Full tests are running for 6f4ff0860d9a: open run #38597607558

[kp2pml30]

/genvm-run-tests

[github-actions]

👀 Full tests are running for 6f4ff0860d9a: open run #38661065161