ICRC-107: standard for fee collector

[bogwar]

Fee collection in ICRC-based ledgers (e.g., ckBTC) is inconsistently implemented. While transfer transactions often incur fees, approve transactions typically do not. However, there is no standardized way to:

• Define fee collection rules—who receives fees, which operations are charged, and whether fees are burned.
• Record fee collection settings directly on-chain in ledger blocks.
• Provide consistent semantics for wallets, explorers, and other integrations to interpret fee structures.

ICRC-107 extends ICRC-3, adding semantics for fee collection while ensuring full compatibility with the existing block format. This proposal eliminates reliance on off-chain metadata, simplifies integration with wallets and explorers, and ensures full transparency in fee handling.

[mbjorkqvist]

Thanks for writing this up, @bogwar! I left a few clarifying questions/comments.

[mbjorkqvist]

The fee may be set to 0, in which case no party is paying a fee. Also, what if the fee collector is set to the minting account? Should that explicitly be forbidden, or should the standard say that setting the fee collector to the minting account is effectively a way to go back from collecting fees, to burning them, i.e., a way to unset the fee collector (which is otherwise currently not possible)?

[skilesare]

I think the minting account section of icrc1 would assume that the minting account would be burned: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md#minting-account-

There probably is no harm in mentioning it here as that would be expected behavior from icrc1

[bogwar]

Yes, good suggestion (to allow setting the fee collector to the minting account). I was thinking how to deal with going back to burning and this is the best idea.

[tmu0]

Why do we need 3 fields? Couldn't we just say if fee_col is set, it receives the fee, otherwise fee is burned?

[bogwar]

For backwards compatibility: we have to deal with the case where fee_col is set but we only collect for transfers.

[tmu0]

How about announcing the block number ranges which follow the standard in the icrc10_supported_standards URL? Something like https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-107.md#blockRange=[[123,)] would mean that all blocks >= 123 would follow the standard. I think this would simplify implementation for clients because all you need to determine if a fee was burned or collected for a given block are the block ranges. You don't have to lookup fee collector settings from previous blocks.

[bogwar]

This would not allow to accurately calculate the balance of fee collectors (if they were set prior to the standard)

[marc0olo]

@bogwar can you elaborate again on this a little bit? I kind of understand where we are coming from, but this seems super weird for somebody who is not aware of the history.

are there already past blocks that define the fee collector? does this apply for transfers and approvals?

is the full col_ops list expected to be provided for each block type (transfer, approval, ...)? if so, it seems a little bit weird to provide this information in each block.

we should keep in mind that fee collection was not clearly specified in a standard before and that the behavior could generally differ among different implementations.

I would prefer the this standard to not rely on implementation specifics of the reference implementation. wouldn't it be better to just use the field fee_col as @tmu0 initially proposed (ignoring the history), but document the historical behavior for the rust reference implementation?

[marc0olo]

and document the semantics for legacy fields per Thomas' suggestion.

the semantics for the legacy fields would be documented in the ledger implementation, right? or also in this standard? 🤔

[bogwar]

I'll keep it part of the standard, otherwise it's going to be folklore that will get lost at some point. Do you see an issue with doing so?

[marc0olo]

I definitely think it is important to be documented. I am not sure if this standard is the best place for that, but I also do not have a strong opinion on it. it just kind of feels wrong here.

maybe we should at least highlight that the legacy fee handling is specifically referring to the Rust implementation of DFINITY before ICRC-107 was introduced.

[tmu0]

@bogwar I read through it again and looks like I misunderstood you.

My preferred solution would be adding a new field icrc107_fee_col to the block and not an entirely new block type for setting the fee collector. The idea is that if the ledger supports ICRC-107 he has to specify the field in each block that has a non-zero fee (even if the new field is empty) and in this case the legacy field fee_col is ignored.

Why is this better IMO?

• self contained: Clients can determine the fee collector of every block without having to look at other blocks
• allows implementing flexible policies that scale: Ledgers can implement arbitrary complex fee collection logic, e.g., different fee collector for each trx type, round robin fee collection, etc, without having to worry about scalability (current approach would reuqire adding a 107feecol block every time the FC changes)

[bogwar]

There are indeed advantages to have a field per block, but... in practice this would add a lot of redundant data per block for the benefit of very few clients of the ledger. Even in the previous incarnation, we used a field to point to the block where the fee collector was set. The saving was 8bytes vs 61bytes.

[mbjorkqvist]

Could this be extended to be something like "An icrc107_fee_col block configures the fee collection for all subsequent blocks, until superseded by another icrc107_fee_col block"?

[mbjorkqvist]

This currently doesn't seem to cover the case where some legacy fee collection has been configured, and later an icrc107_fee_col block is created - in particular, the fees for blocks before the icrc107_fee_col block may have been collected according to the legacy logic.

[marc0olo]

@mbjorkqvist do you mean that we should explicitly provide the information that there MIGHT be ledger (custom, non DFINITY) implementations out there where the legacy fee_col logic in section 5 does not apply?

if so, I think we should say the ledger most likely burns all block fees ... and elaborate more on that in section 5

[mbjorkqvist]

I was thinking about a ledger with the DFINITY legacy fee collector implementation, and then later implements ICRC-107 and adds an icrc107_fee_col block. For this case, I feel this bullet point does not apply (since an icrc107_fee_col block HAS been set), and therefore it's unclear whether section 5 applies to the pre-icrc107_fee_col blocks or not.

[bogwar]

Yes, the wording is not good; let me rewrite it.

[mbjorkqvist]

"The updated settings are recorded in the next block added to the ledger."

Since we are now proposing a new block type, it should be added to the ledger immediately as a result of a call to icrc107_set_fee_collection, rather than having the new configuration added to the next (unrelated) block added to the ledger.

[bogwar]

Good point; i'll rewrite to state that it is recorded in a new block type

[marc0olo]

I second that, but I assume this was just a wording/phrasing/interpretation issue.

[bogwar]

rewrote

[mbjorkqvist]

Should we explicitly say that if fee_col is not set, all fees are burned?

[marc0olo]

I think that applies more to the next line (187) and should be added there

[bogwar]

I've reorganised the points to be more explicit. PTAL

[mbjorkqvist]

Suggested change

	New implementations SHOULD avoid using fee_col and instead use `icrc107_fee_col` for all fee collection settings. Legacy behavior is provided for backward compatibility only and MAY be deprecated in future versions of this standard.
	New implementations SHOULD avoid using `fee_col` and instead use `icrc107_fee_col` for all fee collection settings. Legacy behavior is provided for backward compatibility only and MAY be deprecated in future versions of this standard.

[marc0olo]

@bogwar provided some additional comments

@mbjorkqvist thanks for the in-depth review 🙏

[marc0olo]

@mbjorkqvist do you mean that we should explicitly provide the information that there MIGHT be ledger (custom, non DFINITY) implementations out there where the legacy fee_col logic in section 5 does not apply?

if so, I think we should say the ledger most likely burns all block fees ... and elaborate more on that in section 5

[marc0olo]

I second that, but I assume this was just a wording/phrasing/interpretation issue.

[marc0olo]

Unauthorized calls SHOULD result in an error.

SHOULD or MUST? 🤔

do we need to define the expected error, too?

[marc0olo]

I think that applies more to the next line (187) and should be added there

[bogwar]

Addressed most of the comments

[bogwar]

Good point; i'll rewrite to state that it is recorded in a new block type

[bogwar]

Yes, the wording is not good; let me rewrite it.

[bogwar]

rewrote

[bogwar]

I've reorganised the points to be more explicit. PTAL