---
fip: "XXXX"
title: Miner actor fee application events
author: "Rod Vagg (@rvagg)"
discussions-to: https://github.com/filecoin-project/FIPs/discussions/XXX
status: Draft
type: Technical (Core)
category: Core
created: 2025-05-20
spec-sections: 
requires:
  - FIP-XXXX: Implicit Messages in Block Receipts (TODO)
replaces: N/A
---

# FIP-XXXX: Miner actor fee application events

## Simple Summary

This FIP introduces events that are emitted when fees (penalties) are applied to miner actors, providing transparency about when and why fees are charged. This will help Storage Provider and other network participants track and audit all fee applications by making them observable and queryable through the event system.

## Abstract

The Filecoin network applies various fees and penalties to miner actors, including daily proof fees (introduced in [FIP-0100](./fip-0100.md)), penalties for faulty sectors, consensus faults, and early terminations. Currently, when these fees are applied, there is limited visibility into what fees were charged and why, particularly for those applied during cron operations.

This FIP introduces a standardised event that is emitted whenever a fee is applied to a miner actor via the `apply_penalty` method. This event provides detailed information about the fee type, amount, and relevant context. By leveraging the "Implicit Messages in Block Receipts" FIP *(link TODO once numbered and merged)*, these events can be captured and indexed even when they originate from cron operations.

The events will make the fee application process transparent and auditable, allowing Storage Providers to better understand their costs, and enabling the development of improved monitoring and management tools. Importantly, these events indicate when fee debt is accrued, not necessarily when funds are actually burned, as fee payment occurs separately and depends on available funds.

## Change Motivation

Currently, when fees are applied to a miner actor, Storage Providers and other network participants have limited visibility into:
- When specific fees were applied
- Why fees were applied
- How much was charged for each fee type
- Which deadlines or sectors triggered fee applications

This lack of transparency creates several challenges:

1. **Billing uncertainty**: Storage Providers cannot easily reconcile their expected costs with actual fees applied
2. **Debugging difficulties**: When investigating unexpected fee debt, it's challenging to identify the specific sources
3. **Operational blindness**: Missing visibility into fee applications makes operational planning more difficult
4. **Accountability gaps**: The network cannot easily demonstrate that fees are being applied correctly and fairly

The introduction of the daily proof fee in [FIP-0100](./fip-0100.md) increases the importance of fee application visibility, as these fees are applied regularly during cron operations. Additionally, FIP-0100 comes with a commitment to montior the application of that fee for a period of time in order to determine whether the FIP and its parameters are appropriate to the network. Due to the ambiguity involved in fee application, insight into fee payment is more complex than it needs to be.

Without these events, observers must resort to complex message execution techniques or manual calculation to understand their fee applications, which is error-prone and lacks authoritative confirmation from the protocol itself.

## Specification

This FIP introduces an event that is emitted whenever a fee is applied to a miner actor through the `apply_penalty` method. The event follows the Filecoin actor event schema defined in [FIP-0049](./fip-0049.md).

### Fee Applied Event

The `fee-applied` event provides details about a specific fee application:

| flags | key | value |
|--------------------|---------------------|-----------------------------------------------------|
| Index Key + Value | "$type" | "fee-applied" (string) |
| Index Key + Value | "fee-type" | <FEE_TYPE> (string, see table below) |
| Index Value | "amount" | <FEE_AMOUNT> (bigint) |
| Index Value | "deadline" | <DEADLINE_INDEX> (int, optional, where relevant) |
| Index Value | "sectors" | <SECTOR_COUNT> (int, optional, where relevant) |
| Index Value | "limit-applied" | <BOOLEAN> (optional, for daily-proof events) |

Valid fee types include:

| Fee Type | Description |
|-------------------------|------------------------------------------------------------|
| "daily-proof" | Daily proof fee (FIP-0100) |
| "continued-fault" | Penalty for sectors that remain in a faulty state |
| "consensus-fault" | Penalty for proven consensus fault |
| "termination" | Penalty for early termination of sectors |
| "precommit-expired" | Forfeited deposit for expired precommits |
| "window-post-dispute" | Penalty from successful window post dispute |
| "window-post-invalid" | Penalty for invalid window post submission |
| "sector-prove-deadline" | Penalty for sectors that didn't prove before deadline |

### Implementation Notes

1. Events are emitted whenever the miner actor's `apply_penalty` method is called
2. The event will be emitted from all entry points that apply fees, including:
- The `handle_proving_deadline` function during cron operations
- The `report_consensus_fault` method
- The `terminate_sectors` method
- The `dispute_windowed_post` method
- The `cleanup_expired_pre_commits` method
- Any other function that calls `apply_penalty`

3. Optional fields are only included when relevant:
- `deadline` is included when the fee is related to a specific deadline
- `sectors` is included when the fee applies to a specific number of sectors
- `limit-applied` is included when a fee cap was applied (e.g., daily proof fees capped at 50% of expected rewards)

4. The event indicates fee debt accrual, not actual payment. The actual burning of tokens to pay fee debt happens separately and depends on available funds in the miner's account.

### Code Changes

The primary code change will be in the miner actor's `apply_penalty` method to emit the fee-applied event. Additional changes may be needed in specific fee application locations to provide relevant context (deadline index, sector count, etc.) to the event.

pub fn fee_applied(
    rt: &impl Runtime, 
    fee_type: &str, 
    amount: &TokenAmount, 
    deadline: Option<u64>, 
    sectors: Option<u64>,
    limit_applied: Option<bool>
) -> Result<(), ActorError>

## Design Rationale

Several considerations informed this design:

1. **Single comprehensive event**: Rather than creating multiple event types for different fee scenarios, we use a single event type with a fee-type field. This simplifies event processing while still providing all necessary information.

2. **Optional fields**: Only including context-specific fields when relevant keeps the events compact while providing necessary information. The deadline and sector count fields are only meaningful for certain fee types.

3. **Clear distinction between accrual and payment**: The events make it clear that they represent fee debt accrual, not actual payment, addressing the fact that fee payment depends on available funds.

4. **Dependency on implicit messages**: For fees applied during cron operations, these events rely on the ability to capture events from cron operations, which will be enabled by the "Implicit Messages in Block Receipts" FIP.

## Backwards Compatibility

This change is backwards compatible as it only adds events without modifying existing behaviour. The actor code changes are minimal and contained within the fee application functions.

Event emission follows the standard Filecoin event mechanism defined in [FIP-0049](./fip-0049.md) and does not require protocol changes beyond those already included in the "Implicit Messages in Block Receipts" FIP.

Existing systems that process miner actor state changes will continue to function without modification, while systems that wish to consume the new events can be updated to do so.

## Test Cases

The following test cases should be implemented to verify correct event emission:

1. **Daily Proof Fee Test**:
- Set up a miner with sectors subject to daily proof fees
- Trigger a cron deadline where fees are applied
- Verify that a `fee-applied` event is emitted with type "daily-proof"
- Verify that the fee amount matches expected calculation
- Verify that the deadline index and sector count are included when applicable

2. **Continued Fault Penalty Test**:
- Set up a miner with faulty sectors
- Trigger a cron deadline where penalties are applied
- Verify that a `fee-applied` event is emitted with type "continued-fault"
- Verify that the fee amount matches expected calculation

3. **Fee Cap Test**:
- Set up a miner with daily proof fees exceeding the 50% cap
- Trigger a cron deadline where fees are applied
- Verify that the `fee-applied` event has `limit-applied` field set to true
- Verify that the fee amount matches the capped amount

4. **Consensus Fault Test**:
- Simulate a consensus fault report
- Verify that a `fee-applied` event is emitted with type "consensus-fault"
- Verify that the fee amount matches expected calculation

5. **Termination Fee Test**:
- Terminate sectors early
- Verify that a `fee-applied` event is emitted with type "termination"
- Verify that the fee amount matches expected calculation

6. **Expired PreCommit Test**:
- Allow precommitted sectors to expire
- Verify that a `fee-applied` event is emitted with type "precommit-expired"
- Verify that the fee amount matches expected calculation

7. **Window PoSt Dispute Test**:
- Successfully dispute a window PoSt
- Verify that a `fee-applied` event is emitted with type "window-post-dispute"
- Verify that the fee amount matches expected calculation

8. **Invalid Window PoSt Test**:
- Submit an invalid window PoSt
- Verify that a `fee-applied` event is emitted with type "window-post-invalid"
- Verify that the fee amount matches expected calculation

9. **Implicit Message Capture Test**:
- Verify that events emitted during cron are correctly captured in receipts
- Verify that events can be retrieved using standard event retrieval methods

## Security Considerations

This FIP has minimal security implications as it only adds observability without modifying behaviour. The primary security consideration is the impact on the additional **Gas Costs** of emitting events. However, as demonstrated in [FIP-0083](./fip-0083.md), these costs are relatively minimal and also don't have per-message multipliers (as is the case of some multi-sector events in FIP-0083).

## Incentive Considerations

This FIP aligns incentives by increasing transparency around fee applications:

1. **Storage Provider Benefits**:
- Better understanding of fees enables more accurate cost models
- Increased transparency builds trust in the fee application process
- Easier auditing reduces operational overhead

2. **Network Benefits**:
- Transparent fee application demonstrates fairness
- Ability to track fee applications helps identify potential issues
- Improved tooling enabled by events can lead to better network participation

3. **Ecosystem Benefits**:
- Service providers can build better monitoring and management tools
- Data analysts can derive insights from fee application patterns
- Improved visibility supports education about network economics

There are no negative incentive implications as this change only adds observability without modifying fee calculation or application.

## Product Considerations

This FIP enhances the Filecoin product in several ways:

1. **Improved User Experience**:
- Storage Providers gain visibility into fee applications
- Monitoring tools can display fee breakdowns and histories
- Alerts can be created for unexpected fee patterns

2. **Operational Transparency**:
- The "black box" of fee application becomes transparent
- Fee application can be correlated with other operations
- Historical fee data becomes available for analysis

3. **Tooling Enablement**:
- Dashboards can show fee breakdowns by type
- Accounting systems can reconcile fee applications
- Forecasting tools can predict future fee applications based on patterns

4. **Documentation Benefits**:
- Fee application becomes documentable with concrete examples
- Educational content can reference actual fee events
- Debugging guides can include fee event analysis

The primary product improvement is turning an opaque system process into an observable, auditable operation that Storage Providers can understand and incorporate into their workflows and other network participants can use to inspect network operations.

This FIP specifically addresses fee accrual visibility. A separate future proposal may address the gap between fee accrual and actual payment by providing visibility into the fee payment process.

## Implementation

The implementation requires changes to the miner actor code to emit events during fee application. The main change will be around the use of the `apply_penalty` method where an additional event emit operation will need to be added for each one.

The implementation will depend on the "Implicit Messages in Block Receipts" FIP to ensure that events emitted during cron operations are captured in receipts and available through standard event retrieval methods.

A reference implementation will be provided in the `builtin-actors` repository.

The implementation should include:

1. A utility function for emitting the standardised fee-applied event
2. Integration of event emission in the `apply_penalty` method
3. Context gathering in fee application entry points to provide relevant information to the event
4. Tests confirming correct event emission patterns for all fee types

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).