feat(intent_settlement): optional on-chain referral fee-share (#281)

[henrypeters]

Summary

Implements an optional on-chain referral fee-share mechanism for the Vortex protocol, closing #281.

• submit_intent now accepts an optional referrer: Option<Address>.
• ProtocolConfig gains a referral_share_bps field (default 0 = disabled, backward-compatible).
• When referral_share_bps > 0 and a referrer is set, the configured slice of each fill's protocol fee is routed to the referrer at fill_intent time; the remainder still goes to FeeRecipient.
• Referral split accrues proportionally on every partial fill (dust rounds to FeeRecipient, so no fee units are silently dropped).
• Self-referral (referrer == user) is rejected with the new Error::SelfReferral variant, preventing users from gaming the programme against their own volume.
• batch_submit_intent tuple type extended to carry the referrer through.
• All new public items carry rustdoc per CONTRIBUTING.md.
• Error enum is append-only — SelfReferral = 35 is appended after SrcChainNotSupported = 34, no renumbering.

Motivation

Issue #281 requested a way to credit referrers with a share of protocol fees so that integrators (front-ends, wallets, market makers) can be rewarded for routing volume through Vortex. Until now, the entire protocol fee went to FeeRecipient. This PR makes the split opt-in by an admin via set_config (which now takes a referral_share_bps argument) and a referrer per intent via submit_intent.

Changes

File	Change
intent_settlement/src/lib.rs	Added MAX_REFERRAL_SHARE_BPS / DEFAULT_REFERRAL_SHARE_BPS constants, referral_share_bps on ProtocolConfig/ProtocolParams/IntentRecord, Error::SelfReferral, referrer param on submit_intent + self-referral guard, referral split in fill_intent with CEI ordering preserved, batch_submit_intent tuple extension, validation in set_config.
intent_settlement/src/test.rs	Updated Ctx::submit() helper to pass &None for referrer; added assertion for params.referral_share_bps; appended 5 tests (self-referral rejection, 20% split, multi-partial-fill accrual, zero-share passthrough, no-referrer regression).
CHANGELOG.md	Entry under [Unreleased] > Added describing the feature.

Tests

Five new tests in intent_settlement/src/test.rs:

1. submit_intent_self_referral_rejected — Error::SelfReferral returned.
2. fill_intent_referrer_receives_configured_split — 20% share: referrer gets fee * 2000 / 10_000, FeeRecipient gets the remainder.
3. partial_fills_accrue_referral_share_across_fills — 100% share, two partial fills: referrer accumulates fee1 + fee2.
4. zero_referral_share_sends_all_fee_to_fee_recipient — explicit 0 share, referrer named, full fee still goes to FeeRecipient.
5. fill_intent_no_referrer_unchanged_behavior — non-zero share, no referrer named, full fee still goes to FeeRecipient (regression guard).

Note on cargo: this environment does not have cargo / rustup installed, so the suite could not be run locally. Please run cargo test -p intent_settlement and cargo fmt --check in CI before merge.

Compatibility

• All new params have defaults (None for the referrer, 0 for the share), so existing integrators calling submit_intent or set_config need to be updated to the new arity but their semantics are unchanged.
• The config_updated event payload gains a fifth field (referral_share_bps) — strictly additive.
• Error::SelfReferral is appended at index 35; no renumbering of existing variants.

Closes #281.

[drips-wave]

@henrypeters Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits