Add m013 Value-Based Fee Routing mechanism spec#23
Add m013 Value-Based Fee Routing mechanism spec#23CShear wants to merge 2 commits intoregen-network:mainfrom
Conversation
Adds full mechanism spec for m013 following the established pattern: - SPEC.md with 13 sections covering value-proportional fees on credit transactions, 4-pool distribution (burn/validator/community/agent), and FLAT_GAS → TRANSITION → VALUE_BASED state machine - JSON schemas for fee events, fee config, and KPI metrics - Reference implementation (m013_fee.js, m013_kpi.js) with deterministic self-test covering min_fee floor clamping and fee conservation - Fee schedule: Issuance 2%, Transfer 0.1%, Retirement 0.5%, Marketplace 1% - Distribution (Model A): Burn 30%, Validator 40%, Community 25%, Agent 5% - Updates verify.mjs with m013 validation checks - Updates MECHANISM_CONSUMERS.md with m013 consumer mappings Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Summary of ChangesHello @CShear, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request integrates the m013 Value-Based Fee Routing mechanism, fundamentally altering how fees are calculated and distributed for ecological credit transactions. It shifts from a flat gas model to a value-proportional system, ensuring protocol revenue scales with the value facilitated. The change establishes a structured approach to funding critical network operations and incentives through a multi-pool distribution model, supported by detailed specifications, schemas, and a reference implementation for validation. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the comprehensive specification and reference implementation for M013 Value-Based Fee Routing. The documentation, schemas, and test data are well-structured and thorough. My review found a critical issue in the fee distribution logic of the reference implementation that could lead to a loss of funds due to rounding errors, violating the 'Fee Conservation' security invariant. I have provided a code suggestion to fix this. I also suggest updating the specification to clarify the rounding logic to prevent ambiguity in other implementations, aligning with repository guidelines for explicit transition logic.
| const distribution = { | ||
| burn: Math.floor(feeAmount * shares.burn), | ||
| validator: Math.floor(feeAmount * shares.validator), | ||
| community: Math.floor(feeAmount * shares.community), | ||
| agent: Math.floor(feeAmount * shares.agent) | ||
| }; |
There was a problem hiding this comment.
The current fee distribution logic uses Math.floor() for each pool's share independently. This can lead to rounding errors where the sum of the distributed amounts is less than the total feeAmount, causing a loss of funds (dust). This violates the Fee Conservation security invariant defined in SPEC.md (section 9), which states fee_collected = sum(pool_distributions). To fix this, the remainder from rounding should be deterministically allocated to one of the pools. The suggested implementation calculates three of the pool amounts using Math.floor() and allocates the entire remaining amount to the fourth pool (validator), ensuring that the total distributed amount exactly equals feeAmount.
const d_burn = Math.floor(feeAmount * shares.burn);
const d_community = Math.floor(feeAmount * shares.community);
const d_agent = Math.floor(feeAmount * shares.agent);
const d_validator = feeAmount - d_burn - d_community - d_agent;
const distribution = {
burn: d_burn,
validator: d_validator,
community: d_community,
agent: d_agent
};| burn_pool += fee_amount * burn_share | ||
| validator_fund += fee_amount * validator_share | ||
| community_pool += fee_amount * community_share | ||
| agent_infra += fee_amount * agent_share |
There was a problem hiding this comment.
The pseudo-code for fee distribution is ambiguous about how to handle rounding with integer-based amounts. This can lead to implementations that violate the Fee Conservation invariant (fee_collected = sum(pool_distributions)), as flooring each share's calculation can result in lost "dust".
The specification should be explicit about a deterministic rounding strategy to ensure no funds are lost. For example, you could specify that N-1 shares are calculated with flooring, and the remainder is assigned to the last (or largest) share to ensure the sum is always correct.
References
- When specifying transition logic between different mechanisms (e.g., multipliers), explicitly define the function (e.g.,
max()) and the state-based conditions (phase-gating) that govern the transition to prevent implementation ambiguity.
Floor 3 pools (burn, community, agent) and derive validator as remainder so fee_collected = sum(pool_distributions) always holds. Clarify rounding strategy in SPEC.md pseudo-code. Fixes Gemini review on PR regen-network#23. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 participant
Summary
Test plan
node mechanisms/m013-value-based-fee-routing/reference-impl/m013_fee.js— self-test PASS (5 vectors, fee conservation verified)npm run verify— PASS🤖 Generated with Claude Code