Feature Request: Operator-Scoped Incentives Hooks

[HavenCTO]

Feature Request: Operator-Scoped Incentives Hooks

Context
FilecoinPayV1 v1.0.0 is stable on mainnet. Experiments like incentivized uploads need logic inside payment execution to guarantee "no pay → no rewards." Currently requires forks, breaking composability. Example fork - https://github.com/HavenCTO/filecoin-pay/commit/e03f13a31241866f6141023735fe235bc7c7b342

Problem
A global incentives hook creates a bottleneck and protocol-wide risk. Incentives should be operator-controlled and isolated.

Request
Add operator-scoped hooks so each operator can opt-in independently, minting rewards only when payments execute.

Proposed Design

Option A (recommended): Per-rail hook

• Extend createRail with optional incentivesHook address (or add setRailIncentivesHook(railId, hook) callable only by rail.operator)
• Store on Rail struct
• During payment execution: hook.onPayment(railId, token, operator, payee, netPayeeAmount)

Option B: Per-operator registry

• Add mapping operatorIncentivesHook[operator]
• Add setOperatorIncentivesHook(hook) (msg.sender only)
• Look up by rail.operator during payment execution

Hook Semantics

• Called during settleRail (post-fees/pre-credit) and one-time payments
• Pass netPayeeAmount to enforce "no pay → no rewards" deterministically
• Reverts only affect the operator/rail using that hook

Benefits
Operators can independently:

• Mint per-operator reward tokens on bonding curves
• Blacklist users
• Experiment without FilecoinPay deployer coordination

Acceptance Criteria

• No behavior change when hooks unset
• Invoked on settlement and one-time payments
• Operator-scoped isolation
• Tests: unset hook no-op, invocation paths, limited revert propagation

Note: This adds a generic extension point, not a specific incentives scheme.

[rvagg]

@HavenCTO can you explain why either of these two hooks don't serve the purpose?

• RailSettled event - collate and process after the fact at some interval
• IValidator#validatePayment - where the validator gets to be part of the settlement process and even dictate how much of a segments settlement gets resolved, in most cases the validator is going to be the operator, or at least related to it, and where you need to tie incentives and your validator is different to the operator you could do a pass-through validation where the operator is the validator and passes validatePayment through to the real validator but uses the call to account for the payment amount

[HavenCTO]

Great question, both hooks work but have gaps that push complexity onto operators.

IValidator#validatePayment gives atomicity, but one-time payments and emergency settlements bypass it entirely, breaking "no pay → no rewards" for those flows. It also forces rail recreation.

RailSettled events enable retroactive rewards, but an oracle setup adds infrastructure burden and centralization risk.

The third path: user-callable claimRewards(railId) based on RailSettled.

No protocol changes, no oracle, users self-serve when they want. Same deterministic verification on-chain, just shifted gas/UX cost to claim time. Operators opt-in by deploying a reward contract that watches events; users claim permissionlessly.

This keeps core minimal, gives existing rails zero-cost adoption, and lets operators choose:

migrate to validator wrapper for atomicity, or use user-callable mint for retroactivity without infra overhead. Best of both worlds without forcing either.

Thanks for pushing on the tradeoffs. This is likely the most pragmatic balance for v1.0.

[BigLep]

@rvagg : what are the next steps here? Is there any work we'll do for GA?

[rvagg]

Nothing to be done here for GA, Filecoin Pay is immutable and on mainnet as v1, so if there's anything coming out of this that impacts Filecoin Pay directly and not using one of the external mechanisms I mentioned, then it's going to be a Filecoin Pay v2 thing.

tbh though I'm not seeing the product or network requirement to be doing this at the Filecoin Pay level. If the operator is controlling hooks, then they can just do the controlling in their own contract and with the management of rails since the operator is operating the rails so has control over funding flows and knows what activity is happening and therefore can be applying that knowledge to incentives. Unless someone can explain a user or developer story here that can't be solved outside of Filecoin Pay then I'm not seeing the case for doing anything here.