fix(fees): treat zero-budget chain allocations as absent 🐛

[kp2pml30]

Problem and outcome

Consensus resolves only allocation keys with a nonzero stored budget:

• internal resolveAllocationKey takes the exact key if budget > 0, else the callKey wildcard if budget > 0, else reverts MessageNoMatchingAllocation
• external _tryReserveOnKey skips budget == 0 keys, and falls back to the legacy unallocated path when both keys are zero

The v0.3 executor matched zero-budget entries and failed their budget check instead, so it rejected messages the chain would fund from the wildcard or accept as unallocated. Now an entry with a concrete recipient and a zero budget is absent. Synthetic recipient wildcards (recipient: None, executor-only) keep matching at any budget. A key used up by the execution's own emissions still never spills

Non-goal: v0.2.x keeps the old matching

Implementation and validation

• allocation_match_priority drops zero-budget chain entries, so the internal resolver and external candidate list both see them as absent
• Impl-spec 04-fees.rst, manager-api.yaml and the MessageAllocationNode::budget doc describe stored chain budgets; the old "optionally reduced by prior consumption" allowance is gone, since a host lowering a budget to 0 would now turn exhausted into absent. genlayer-node already passes stored budgets
• Tests: resolver and end-to-end emission for internal call, deploy and external. Covers fallthrough to the wildcard, the no-allocation error, the unallocated external path, the phase interplay, the synthetic wildcard and the unchanged local-exhaustion behaviour. cargo test --lib genlayer_sdk: 87 passed

Summary by CodeRabbit

• Documentation
  • Clarified how fee allocation matching handles chain entries with concrete recipients and synthetic recipient wildcards.
  • Explained that zero-budget chain entries are omitted, while zero-budget wildcards remain eligible for matching but are exhausted.
  • Updated guidance on what happens when no matching allocation exists, including the different paths for internal and external messages.
  • Clarified that null budgets are uncapped and that allocations absent on-chain should be omitted.

[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#47 (v0.3)

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

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: 81e76168-4789-47fa-b559-7bdd79f9707c

📥 Commits

Reviewing files that changed from the base of the PR and between 5519ae6 and 619dfad.

📒 Files selected for processing (4)

• 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

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

Walkthrough

Fee allocation documentation now distinguishes concrete chain entries from synthetic recipient wildcards and describes how zero budgets affect matching. The budget field descriptions were updated, and the v0.3.x executor submodule reference changed.

Changes

Fee allocation matching

Layer / File(s)	Summary
Budget and allocation matching contract 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	The budget descriptions distinguish stored chain budgets from synthetic wildcard allowances. The specification describes matching and fallback behavior for zero-budget entries, exhausted candidates, and unallocated external messages. The executor submodule reference changed.

Priority: ➖ Normal

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

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 619df

No actionable merge-blocking issue is established. The updated contract consistently describes zero-budget fallback while preserving local-exhaustion precedence; merge after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 619df

The change narrowly aligns zero-budget allocation matching with chain behavior. The documented rules preserve recipient restrictions, local-exhaustion checks, and receipt charging. No new security bypass was established, but the changed execution code and its failure-recovery behavior could not be fully verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The identified exposure concerns funding selection for outbound messages processed by the changed v0.3 executor, including which wildcard allocation or receipt-only path funds a message. The available evidence does not establish maximum deployment, tenant, or asset exposure.

Trust Boundaries and Controls

• observed — The interface predicates check allocation kind, optional recipient, optional call key, and internal phase, but do not inspect budget. Zero-budget filtering and post-match spending controls must therefore be enforced by consumers. The host supplies proof-bearing subtree bytes; the available contract describes transport, not verified producer authentication or proof enforcement.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: zero-budget chain allocations are treated as absent for fee matching.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

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

Autopilot is currently an internal CodeRabbit preview.

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.}

[kp2pml30]

/genvm-run-tests

[github-actions]

👀 Full tests are running for 619dfad4bae5: open run #36737691901

[kp2pml30]

/run-e2e all

[ci-core-e2e-runner]

E2E status was updated. Follow the current E2E and merge checks on this PR. Detailed diagnostics are available internally.

[kp2pml30]

/merge

[ci-core-e2e-runner]

The request is recorded and waiting for processing. Follow the E2E and merge checks for progress. Do not post a duplicate command.