ECPIP-2: Standard Hook Fee Estimation Interface

[normanzb]

Abstract

This proposal introduces a standard interface for hook contracts to provide fee estimation capabilities, addressing the current challenge of estimating fees required by hooks in the Ethereum Comments Protocol (ECP). The interface allows hook developers to implement predictable fee estimation methods, improving developer experience and reducing complexity for integrators.

Motivation

Current Challenges

Estimating fees required by hooks in ECP is challenging because there is no standard interface for hooks to provide fee estimates. Developers must implement hook-specific fee calculation logic, leading to:

• Complex integration: Each hook requires custom fee estimation logic
• Maintenance burden: Updates to hook fee structures require corresponding updates in all integrators
• Error-prone process: Manual fee calculations can lead to transaction failures
• Poor developer experience: Integrators must understand each hook's internal fee structure

Existing Workaround

The current approach, as documented in the ECP Protocol Fees documentation, requires developers to:

1. Implement hook-specific logic to calculate required fees
2. Handle different fee structures for different hooks
3. Maintain complex fee calculation code

This approach is not scalable and creates significant overhead for developers integrating with multiple hooks.

Terms

• Hook: A smart contract that implements the IHook interface and provides custom logic for comment processing
• Integrator: A developer or application that integrates hooks in their ECP implementation and invokes fee estimation methods
• Fee estimation: The process of determining the fee required for a specific operation before executing it
• Buffer fee: An additional fee amount added to estimated fees to account for potential variations
• SDK helper function: The ECP team will implement a TypeScript-based helper function to return hook fees. The function makes a best-effort estimation covering the most common and known cases
• Estimator: The method in the IFeeEstimatableHook interface that returns the fee estimation

Specification

A full proposed implementation can be found here

Interface Definition

/// @title Metadata - Type definitions for metadata-related structs and enums
library Metadata {
  /// @notice Struct containing metadata key-value pair
  /// @param key UTF-8 encoded string of format "type key". Must fit in 32 bytes.
  /// @param value The metadata value as bytes
  struct MetadataEntry {
    bytes32 key;
    bytes value;
  }
}

/// @title FeeEstimatable - types used by fee-estimatable hooks
library FeeEstimatable {
  address constant NATIVE_TOKEN_ADDRESS =
    0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE;
  /// @notice Details of a fee estimation
  /// @param amount The fee required for the specific comment action
  /// @param asset The address of the asset, use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for the native token
  /// @param description A description of the hook's behaviour, gating rules and any fee that can be shown by apps to the user
  /// @param metadata Additional app-specific data of the estimation
  struct FeeEstimation {
    uint256 amount;
    address asset;
    string description;
    Metadata.MetadataEntry[] metadata;
  }
}

interface IFeeEstimatableHook is IERC165, IHook {
  /// @notice Should return the fee estimation for adding a comment
  /// @param commentData The comment data that will be processed
  /// @param metadata The metadata entries for the comment
  /// @param msgSender The msg.sender that will initiate the comment action
  /// @return feeEstimation The fee estimation
  function estimateAddCommentFee(
    Comments.Comment calldata commentData,
    Metadata.MetadataEntry[] calldata metadata,
    address msgSender
  ) external view returns (FeeEstimatable.FeeEstimation memory feeEstimation);

  /// @notice Should return the fee estimation for editing a comment
  /// @param commentData The comment data that will be processed
  /// @param metadata The metadata entries for the comment
  /// @param msgSender The msg.sender that will initiate the comment action
  /// @return feeEstimation The fee estimation
  function estimateEditCommentFee(
    Comments.Comment calldata commentData,
    Metadata.MetadataEntry[] calldata metadata,
    address msgSender
  ) external view returns (FeeEstimatable.FeeEstimation memory feeEstimation);
}

Typescript Example (using viem)

The snippet below demonstrates how to call a hook contract directly to estimate the minimum fee required for posting a comment.

⚠️ Notes for integrators:

1. The hook fee is only part of the total cost of posting a comment. Other protocol or gas fees may apply.
2. The asset field may represent either the native token or an ERC-20/ERC-721/ERC-1155 contract. Clients should probe the contract to determine the exact asset type.

import { createPublicClient, http } from "viem";
import { BaseHookABI } from "./abis/BaseHook";

// create a public client for read-only blockchain operations
const publicClient = createPublicClient({
  chain,
  transport: http(rpcUrl),
});

// retrieve the hook contract address from the channel info
const hookAddress = channelInfo.hook;

// call the estimator to get the fee details
const feeEstimation = await publicClient.readContract({
  abi: BaseHookABI,
  address: hookAddress,
  functionName: "estimateAddCommentFee",
  args: [commentData, metadata, msgSender],
});

// handle the response
console.log("Estimated fee:", feeEstimation.amount.toString());

if (
  feeEstimation.asset.toLowerCase() ===
  "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE".toLowerCase()
) {
  console.log("Asset type: native token (wei units)");
} else {
  console.log("Asset type: ERC token at", feeEstimation.asset);
}

// optional: add a buffer fee for timestamp-sensitive hooks
const bufferedAmount = feeEstimation.amount * 110n / 100n; // +10%

Design Rationale

1. Method Signature Alignment

The estimator methods replicate the function signatures of corresponding hook callbacks. This design choice provides:

Advantages:

• Straightforward implementation: Hook developers can reuse existing logic
• Consistent interface: Estimators mirror actual callback parameters
• Accurate estimation: Same parameters ensure estimation accuracy

Trade-offs:

• Integrator complexity: Integrators must provide Comments.Comment struct instead of Comments.CreateComment/Comments.EditComment
• Additional parameters: Integrators must provide authMethod, createdAt, and updatedAt fields

2. Parameter Considerations

authMethod: Integrators are responsible for providing the correct authentication method enum value. This ensures accurate fee estimation based on the intended authentication mechanism.

createdAt/updatedAt: These timestamps are determined on-chain during execution. While integrators cannot provide exact values, they should provide reasonable estimates. For hooks that use these values:

• Best practice: Provide a near-future timestamp as an estimate
• Buffer strategy: Add a small fee buffer to account for timestamp variations (extra fee will be returned)
• Retry mechanism: Implement retry logic for failed transactions due to timestamp-based fee changes

3. Delete Comment Exclusion

The interface does not include a getDeleteCommentFee method because ECP is designed to allow users to call deleteComment() without fees.

4. Estimator returns the minimum amount that gates success

We considered returning a range (min/max) to express optional tipping or upper bounds. We could not find compelling, concrete use cases that require a top limit for gating. Therefore, the estimator returns only the lower bound—the minimum fee (or unit amount) that ensures the action succeeds. If a hook wishes to accept more (e.g., tipping), clients may still pass higher values; the hook’s business logic remains unchanged.

Implications for integrators:

• Treat the returned commentAddFee/commentEditFee as the minimum required
• If your UI permits tipping or buffers for slippage, you may add an extra amount on the client side

5. Identify the fee asset via asset field

Hooks may charge in native currency or in tokens. We add an asset field in the estimator return struct to specify the asset:

• asset == 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE : the fee is the native token to the current chain (on Ethereum mainnet this is ETH).
• Otherwise, it is the contract address of the token (e.g. ERC-20, ERC-721, or ERC-1155).

This keeps the interface concise and avoids separate enum types. It also matches common EVM patterns.

6. Returning a Struct Instead of a Tuple

We chose to return a struct instead of a tuple for the estimator functions. Since these functions are view (read-only), gas consumption is not a concern. Using a struct improves clarity and extensibility, making it easier to add or document new fields in the future without breaking readability or forcing developers to rely on positional return values.

7. No explicit ERC type enum — rely on ERC-165 detection

We do not return a separate “ERC spec” discriminator. Instead:

• If asset == 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE , the asset is the native token to the current chain.
• Otherwise, clients probe interfaces on the contract at the asset address for supported interfaces.

Implementation Guidelines

Estimator Guidelines

1. Set asset to 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for the native token; otherwise use the token contract address.

For Hook Developers

1. Implement the interface: Derive your hook contract from the BaseHook abstract contract, and provide the estimator functions according to IFeeEstimatableFee interface.
2. Reuse existing logic: Leverage existing fee calculation logic in estimation methods
3. Handle edge cases: Consider timestamp variations and provide reasonable defaults
4. Document fee structure: Clearly document how fees are calculated
5. Refund extra fee: If the sender provides more fees than required, the hook should refund the excess amount to maintain fairness and prevent overpayment

For Integrators

1. Check interface support: Verify the hook implements IFeeEstimatableHook
2. Prepare parameters: Create a Comments.Comment struct with appropriate values
3. Handle estimation: Call estimation methods before submitting transactions
4. Add buffer fees: Include small fee buffers for timestamp-sensitive hooks

Backward Compatibility

This proposal is backward compatible. Existing hooks that do not implement IFeeEstimatableHook will continue to function normally.

The ECP team will also implement an SDK helper function that provides a best-effort estimation for cases not covered by IFeeEstimatableHook.

Integrators can:

1. Check interface support: Use supportsInterface() to detect fee estimation capability
2. Fallback gracefully: Use existing fee calculation methods for unsupported hooks
3. Use the SDK helper: Migrate to the SDK helper function once it is ready

Security Considerations

1. Timestamp sensitivity: Hooks using timestamp-based fees should document their sensitivity and provide guidance for integrators

References

• Proposed implementation
• ECP Protocol Fees Documentation
• Comments.Comment Struct
• Comments.EditComment Struct

[davidfurlong]

This is a great start!

A couple of things we should perhaps consider

1. How should a hook return in getAddCommentFee if it supports multiple or a range of values? For example a tipping hook may just pass any message value to the tipped user, allowing the end user to tip however much they want by passing that amount of value in the msg.value? This could be solved by setting the value in some part of the comment data (like the metadata), but it won't necessarily be clear to apps what they can provide.

2. I think a more detailed example integration for an app to estimate the fee would be nice

3. How much latency/slowness does this add to a posting flow? If a hook has a fixed fee of say 0.01eth per interaction, then the app could theoretically simulate once and store/cache the result for this app/hook, rather than get an estimate for each post, which would reduce rpc calls and requests the user is waiting for. It may make sense for the hook to also be able to specify its dependencies somehow, or be able to define whether it is a static fee (no inputs) or not. This is particularly relevant due to privacy considerations - if the user is considering posting something but isn't sure yet, but then a price estimation of the post is sent to a third party RPC and the user doesn't actually post it, it could be leaked. I suppose the content in the estimation request is unsigned and thus untrusted, and so unless the content of the estimated post includes a secret (like a gift card/invite code, or an image link), it's authenticity is not easily verifiable. It is still a problem because the fact that the contents may be shared to third parties isn't necessarily communicated to the user.

4. How should we handle cases whereby the fee is very sensitive to the time, such as when there is a race that can affect the fee, which is very common in token launches/pricing mechanisms (first post costs 0.001, second 0.002, third 0.003, or the reverse)? In token swaps this is often handled via a slippage tolerance, I wonder whether apps may end up supplying excess msg.value with the knowledge that the hook refunds excess fees, in order to increase the likelihood of tx success. At this point it's probably a custom integration for a specific hook.

5. It may be helpful for an app to know whether a hook correctly refunds excess fees sent, although the hook shouldn't be trusted to self report that accurately. This would most likely be an internal tool or provided by an API

6. Will some apps want to communicate where the fee is going (how much to the user/protocol/hook/client)? What about hooks that provide some part of the fee to the client app that creates the transaction? Is there a way to express that here?

7. A similar and adjacent problem is a hook communicating which kinds of calls will even succeed, and communicating a meaningful error message that can be passed to apps/users. For example some hooks may gate access based on a whitelist of users, or an NFT, or a token holding, or only allow comments that contain reddit links. Is this related to this proposal, and should it be included?

[normanzb]

How should a hook return in getAddCommentFee if it supports multiple or a range of values? For example a tipping hook may just pass any message value to the tipped user, allowing the end user to tip however much they want by passing that amount of value in the msg.value? This could be solved by setting the value in some part of the comment data (like the metadata), but it won't necessarily be clear to apps what they can provide.

IMO the apis in this spec should aim to provide the lower end value that gates the corresponding action, what it means is: "a message value equal or more then the returned value should be provided in order to successfully finish the action", hence for tipping hook it should return 0.

In order to provide information that "tips are welcome", perhaps a better place is in the description of the channel or metadata? wdyt?

I think a more detailed example integration for an app to estimate the fee would be nice

How much more detailed do we want to achieve? there is a test function shows example of usage via FlatFeeHook https://github.com/ecp-eth/comments-monorepo/pull/536/files#diff-25413c0a84d830aa4c11893cc37d2ecd62c1fb5290e1f394f92c920e8a93be80R364

I think eventually we will want to have the client side demo implemented in the demo app? will it be enough?

How much latency/slowness does this add to a posting flow? If a hook has a fixed fee of say 0.01eth per interaction, then the app could theoretically simulate once and store/cache the result for this app/hook, rather than get an estimate for each post, which would reduce rpc calls and requests the user is waiting for. It may make sense for the hook to also be able to specify its dependencies somehow, or be able to define whether it is a static fee (no inputs) or not. This is particularly relevant due to privacy considerations - if the user is considering posting something but isn't sure yet, but then a price estimation of the post is sent to a third party RPC and the user doesn't actually post it, it could be leaked. I suppose the content in the estimation request is unsigned and thus untrusted, and so unless the content of the estimated post includes a secret (like a gift card/invite code, or an image link), it's authenticity is not easily verifiable. It is still a problem because the fact that the contents may be shared to third parties isn't necessarily communicated to the user.

I think this is going to be very useful, shall we return a struct that contains a expiry? if the hook provider doesn't provide a expiry date or set it to infinity then it can be cached and used forever

How should we handle cases whereby the fee is very sensitive to the time, such as when there is a race that can affect the fee, which is very common in token launches/pricing mechanisms (first post costs 0.001, second 0.002, third 0.003, or the reverse)? In token swaps this is often handled via a slippage tolerance, I wonder whether apps may end up supplying excess msg.value with the knowledge that the hook refunds excess fees, in order to increase the likelihood of tx success. At this point it's probably a custom integration for a specific hook.

It is a bit late to change postComment signature to add a slippage option, but i guess we could add a method setSlippageTolerance(address author) to the interface, the hook devs can use that to set slippage for the user?
alternative we can use BrokerProxyHook to reinforced it, see below.

It may be helpful for an app to know whether a hook correctly refunds excess fees sent, although the hook shouldn't be trusted to self report that accurately. This would most likely be an internal tool or provided by an API

how about implement/deploy a BrokerProxyHook, where it holds the fund until a the targeting hook's callback function is finished without revert, then it transfer the fund to target hook? only hooks that proxied by the verified BrokerProxyHook will gain a trust badge for refunding the excess. We can also use this idea to re-enforce slippageTolerance is respected by using the hook.

If we turn this hook into a versioned proxy hook, it will also allow us to extend more functionalities to it later. e.g in a later version we can support other assets like NFT

Will some apps want to communicate where the fee is going (how much to the user/protocol/hook/client)? What about hooks that provide some part of the fee to the client app that creates the transaction? Is there a way to express that here?

it feels to me this should either be part of channel description where it is the user's discretion for trusting it or reinforced by BrokerProxyHook.

A similar and adjacent problem is a hook communicating which kinds of calls will even succeed, and communicating a meaningful error message that can be passed to apps/users. For example some hooks may gate access based on a whitelist of users, or an NFT, or a token holding, or only allow comments that contain reddit links. Is this related to this proposal, and should it be included?

Will the user see the result in simulation of the wallet as "likely to fail", if they don't have the required asset?

[davidfurlong]

IMO the apis in this spec should aim to provide the lower end value that gates the corresponding action, what it means is: "a message value equal or more then the returned value should be provided in order to successfully finish the action", hence for tipping hook it should return 0.

Not sure about this, it could also return a range

How much more detailed do we want to achieve? there is a test function shows example of usage via FlatFeeHook https://github.com/ecp-eth/comments-monorepo/pull/536/files#diff-25413c0a84d830aa4c11893cc37d2ecd62c1fb5290e1f394f92c920e8a93be80R364

I suppose I meant in javascript

I think this is going to be very useful, shall we return a struct that contains a expiry? if the hook provider doesn't provide a expiry date or set it to infinity then it can be cached and used forever

Expiry is good - better than any static setting

It is a bit late to change postComment signature to add a slippage option, but i guess we could add a method setSlippageTolerance(address author) to the interface, the hook devs can use that to set slippage for the user?

I don't think this is necessary - a hook could implement this themselves and any client would need to do a custom integration

how about implement/deploy a BrokerProxyHook

I don't think we should, it's unclear what value this adds

Will some apps want to communicate where the fee is going (how much to the user/protocol/hook/client)? What about hooks that provide some part of the fee to the client app that creates the transaction? Is there a way to express that here?

I think this can be split into a different interface at a later date if needed

Will the user see the result in simulation of the wallet as "likely to fail", if they don't have the required asset?

yes, but that's not enough for them to figure out what they need to do. I think this is a case of hooks implementing meaningful revert messages and apps displaying them

[normanzb]

Updated above proposal a bit, currently working on demo in typescript

[normanzb]

I forgot to add in the spec that if the the hook requires transfer anything else other than ERC20. it is not covered in the spec but instead the info should be provided by the simulation of the wallet app.

[davidfurlong]

yeah that makes sense since it doesn't require the app to do anything, although it does if there's an approval needed. How could the spec handle approval requirements?

[normanzb]

good point, will add a extra field for ERC20 in the return value, so client can pre-approve

[davidfurlong]

the x402 standard has a similar problem; https://github.com/coinbase/x402/tree/main/examples/typescript/servers/advanced
https://www.x402.org - although they don't fix a schema, they've thought about some of the problems associated with it.

For example the description seems sensible, as does the asset additional data (potentially in a different format, as onchain JSON is awkward), so that apps can communicate to the user what is going on

      "maxAmountRequired": "1000",
      "maxTimeoutSeconds": 60,
      "asset": "0x...",
      "description": "Access to weather data",
      "extra": {
         "name": "USD Coin",
        "version": "1"
      }

/// @return tokenId The tokenId in case of an NFT, 0x0 for fungible token

I'm not sure there's enough of a use case for this. How would this be used? You need to pay a specific NFT? By definition they're not interchangeable

/// @return expiry The expiry of the comment

A bit unclear atm - is this a cache for all arguments or just the provided ones? what should happen when this expiry has passed? What if there's no price guarantee?

assetAddress == 0x0

I think 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee is better for ETH/native asset as it's not the null address

[normanzb]

Thanks @davidfurlong , will add description and metadata field, also changing returning tuple into a struct

I'm not sure there's enough of a use case for this. How would this be used? You need to pay a specific NFT? By definition they're not interchangeable

Potentially the hook could dynamically calculate a tokenId of a specific NFT for the user to purchase, to gain the permission to post on the channel? so they can set a specific price for each NFT and each user?

is this a cache for all arguments or just the provided ones? what should happen when this expiry has passed

sorry that was a mistake mentioning "comment" (i tabbed it in cursor).
it is explained in the rational section, point 6: " expiry expresses how long an estimate remains valid:"

it is the expiry of the return value of the estimator function, once expired the client should get a new estimation by calling the estimator (will update the doc comment as well if that's ok with you). does that make sense? do you prefer a more fine grained control or what?

What if there's no price guarantee?

You meant estimation is too volatile to be guaranteed? should we add extra field volatile for that?

I think 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee is better for ETH/native asset as it's not the null address

will do

[davidfurlong]

think the NFT example doesn't make sense. The expiry should still clarify whether its argument dependent or not

[normanzb]

1. tokenId removed, added design rational point 5.
2. expiry is also removed according to offline discussion, please see design rational point 6.
3. updated to use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee as native token address.
4. now use struct instead of tuple for return values
5. description added
6. interface updated accordingly
7. example PR updated accordingly

[davidfurlong]

uint256 commentAddFee;

this is used for edit and comment in the code, perhaps amount is a better name

address assetAddress;

can rename this to address asset

/// @param description The description of the estimation

Would change this to A description of the hook's behaviour, gating rules and any fee that can be shown by apps to the user

Metadata.MetadataEntry[]

is missing it's type in this doc

for the adding the specific comment

grammar issue

/// @param commentAddFee The fee or tokenId required for the adding the specific comment, use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee for native token

this is wrong - this comment is relevant for the assetAddress not the fee

/// @param msgSender The original msg.sender that initiated the transaction

the msg.sender that will initiate the transaction

getAddCommentFee

perhaps we should rename to estimateAddCommentFee (same for edit) - as it's not a binding fee

bytes32 commentId

Is there a reason we're adding this argument here? It's unlikely to be used by the estimation, requires an additional read from contract/implementation by frontends, and if it's actually needed, the function can be defined to get it

We should probably also note somewhere that these functions are not reliable to check that a tx will succeed/fail and are meant to solely estimate fees, not necessarily confirm that a transaction will succeed. For example for invalid comment data, these functions may return an estimate but the tx won't succeed.

the fee is native

the fee is the native token to the current chain (on ethereum mainnet this is ETH)

5. Omitting NFT tokenId from the estimator return values

the description still has remnants of old versions that should be excluded

[normanzb]

updated accordingly

[normanzb]

also fixed couple other issues such as dev notice for the methods, and grammars

[normanzb]

revision update removed since it is conflicting with latest version

[normanzb]

updated Estimator guideline to match latest changes

[normanzb]

corresponding PR updated.

[davidfurlong]

this is all unused

/// @notice Enum for metadata operations in hook updates
  enum MetadataOperation {
    SET, // Set or update the metadata value
    DELETE // Delete the metadata key
  }

  /// @notice Struct for hook metadata operations with explicit operation type
  /// @param operation The operation to perform (SET or DELETE)
  /// @param key The metadata key
  /// @param value The metadata value (ignored for DELETE operations)
  struct MetadataEntryOp {
    MetadataOperation operation;
    bytes32 key;
    bytes value;
  }

6. Omitting NFT tokenId field from the estimator return value

After careful consideration, we decided not to include tokenId as a standard property in the return struct, since it is uncommon for > hooks to require users to pay with a specific NFT in order to post/edit a comment. Hook developers may wish to use the metadata > field should the requirement arise.

you're still including this - please remove this and similar

[davidfurlong]

still unclear to me why we need commentId - this function can't and shouldn't actually call the hook directly - would remove. Would rather make it a tiny bit of extra work for the rare hook that needs this than an extra RPC call for every tx on ECP

[normanzb]

updated:

1. commentId removed (and corresponding bytes32 used in the other places removed)
2. unused metadata enum and struct removed,
3. all refs to tokenId removed

[davidfurlong]

underscore versions of contract calls should match non underscore, for example _getAddCommentFee

can you remove the unused stuff like 6. Excluding expiry from estimator return value

and can you update the PR please?

[normanzb]

oops, good catch, will do

[normanzb]

1. code fixed
2. removed point 6, but kept 7. No explicit ERC type enum — rely on **ERC-165 detection**, the probing logic can be used a guidance for for client devs?
3. PR updated: if you are happy with current spec, i will continue with typescript demo and more test changes on the PR

[normanzb]

hi @davidfurlong i think it was a bad move to have abstract contract FeeEstimatableHook, we shouldn't help devs to cover up the missing implementation of the estimator functions, instead we should force them to pay attention to that.

so i will remove abstract contract FeeEstimatableHook and make BaseHook implements IFeeEstimatableHook interface, that means new hooks will be forced to provider estimator functions.

i will do it that way for now to unblock but let me know if any objection.

[normanzb]

Also wondering if there is a mature solution that we can maybe do a symbolic execution of the add comment code then analysis the condition automatically to find out the minimal fee...

[normanzb]

typescript example added

[davidfurlong]

lgtm! would keep it as a draft ECPIP in case any kinks come up, but we can move forward with integrating this