Custom Contract Fees Mechanism

[cschuchardt88]

NEP: Custom Contract Fees Mechanism

NEP: TBD
Title: Custom Contract Fees with ABI Declaration and Runtime Enforcement
Author: Chris Schuchardt [email protected]
Type: Standard
Status: Draft
Created: 2025-10-27

---

Abstract

This NEP introduces a standardized mechanism for smart contracts to declare custom execution fees in addition to standard network gas. These fees are paid by the caller to the contract owner (or designated beneficiary) upon successful invocation. The fee structure is declared in the contract's ABI using a new "fee" metadata field, supported by updated DevPack tooling and enforced by the Neo VM at runtime.

---

Motivation

Many dApps require micro-transactions, subscription models, or usage-based billing directly within smart contracts. While GAS covers network costs, there is no native way to charge contract-level fees in NEO or NEP-17 tokens. This NEP enables:

• Pay-per-use contracts
• Premium feature access
• Decentralized SaaS models
• Fair compensation for contract maintainers

---

Specification

1. ABI Extension: Fee Declaration

A new optional "fee" object is added to method definitions in the ABI.

{
  "methods": [
    {
      "name": "queryData",
      "parameters": [],
      "returnType": "String",
      "offset": 123,
      "safe": true,
      "fee": {
        "asset": "NEO" | "GAS" | "0x..." (NEP-17 hash),
        "amount": 100000000,  // 8 decimals (1.0 fixed-point)
        "beneficiary": "NM7g6DAeN3Nx8iK53GqY7fpeyqX5bUq5fJ",  // optional, defaults to contract owner
        "mode": "fixed" | "dynamic",  // fixed = static, dynamic = computed at runtime
        "dynamicScriptHash": "0x..."   // required if mode=dynamic
      }
    }
  ]
}

Field Details:

Field	Type	Required	Description
asset	string	Yes	"NEO", "GAS", or NEP-17 contract hash
amount	integer	Yes (if mode=fixed)	Amount in smallest unit (8 decimals)
beneficiary	string	No	Address to receive fee. Defaults to contract owner
mode	string	Yes	"fixed" or "dynamic"
dynamicScriptHash	string	Yes (if mode=dynamic)	Contract that computes fee via calculateFee(...)

Note: Dynamic fees allow complex logic (e.g., tiered pricing, time-based rates).

---

2. Dynamic Fee Computation Interface

Contracts declaring mode: "dynamic" must reference a fee calculator contract implementing:

public interface IFeeCalculator
{
    BigInteger CalculateFee(ByteString method, object[] args);
}

• Called by VM before execution
• Must be Safe (no state changes)
• Returns fee in smallest unit

---

3. Decorators

C# Attributes

[Fee(Asset = "GAS", Amount = 50000000, Mode = FeeMode.Fixed)] // 0.5 GAS
[Fee(Asset = "0xd2a4cff31913016155e38e474a2c06d08be276cf", Amount = 100, Mode = FeeMode.Fixed)]
public static string QueryData(string key) { ... }

[Fee(
    Asset = "GAS",
    Mode = FeeMode.Dynamic,
    Calculator = "0xb2a4cff31913016155e38e474a2c06d08be296cf"
)]
public static UInt160 GetReport(uint userId) { ... }

DevPack Export Logic

• [Fee] attribute is parsed during ABI generation
• Populates fee field in method ABI
• Validates:
  • Asset is valid (NEO, GAS, or deployed NEP-17)
  • Calculator implements IFeeCalculator if mode=dynamic
• Emits warning if fee > 10 GAS (configurable)

---

4. Runtime Enforcement (Neo VM)

Invocation Flow

1. Caller invokes contract.method(args)
2. VM loads ABI
3. If method has .fee:
   a. If fixed → deduct exact amount from caller
   b. If dynamic → invoke calculator.CalculateFee(method, args)
        → deduct returned amount
4. Transfer fee to beneficiary (or contract owner)
5. Proceed with execution
6. On failure → refund fee (but not network GAS)

Safety Guarantees

• Atomicity: Fee deduction and transfer are atomic with execution
• Reentrancy-safe: Uses ExecutionEngine snapshot
• No double-spend: Fee checked before execution
• Refund on revert: Fee returned if contract throws

Syscall Additions

// Pseudo-syscalls (internal)
bool ChargeFee(UInt160 asset, BigInteger amount, UInt160 beneficiary);
BigInteger QueryDynamicFee(UInt160 calculator, string method, object[] args);

---

5. Contract Owner & Beneficiary

• Contract owner = deployer address (stored in manifest)
• beneficiary overrides owner per method
• If omitted → owner

---

Security Considerations

• DoS via high dynamic fees: Mitigated by gas cap on calculator
• Calculator griefing: Limit execution to 100k gas
• Fee spoofing: ABI is signed in manifest
• Replay attacks: Nonce not needed (fee per call)

---

Backwards Compatibility

• Existing contracts without [Fee] → no fee charged
• Old DevPack versions → ignore attribute
• VM ignores unknown ABI fields

---

Appendix

Example Contract

public class MyContract : SmartContract
{
    [Fee(Asset = "GAS", Amount = 100000000, Beneficiary = "NM7...")] // 1 GAS
    public static string GetPrice(string symbol) { ... }

    [Fee(Asset = "0xabc...", Mode = FeeMode.Dynamic, Calculator = "0xb2a4cff31913016155e38e474a2c06d08be296cf")]
    public static UInt160 GetReport(uint tier) { ... }
}

[shargon]

In my opinion only gas should be used (at least now) it's easier to compute and attach the gas into the transaction in calculateFeeMethod, and it's good for the strength of the network, it make the gas more useful. Also, neo is not divisible, so I think there is no reason to pay one neo for one smart contract call.

Also I think we don't need to add any extra syscall, it will be transparent to the user who make the transaction.

[erikzhang]

In my opinion only gas should be used

Some projects may have their own tokens that need to be taken into account.

[ixje]

I'd like to see a dynamic mode where calculateFee is in the same contract instead of being forced to call an "external" contract. That way it can also be based on internal storage instead of being forced to add public methods to get the data to calculate the fee from the "calculator contract".

[shargon]

In my opinion only gas should be used

Some projects may have their own tokens that need to be taken into account.

This will add the requirement of do a transfer before (or after) the execution, so it's not transparent to the transaction script. Maybe if we use gas we can do it transparent.

[erikzhang]

I thought about it and realized that if the contract uses its own token, then it doesn’t really need this API, so I agreed to support only GAS.

[shargon]

I'd like to see a dynamic mode where calculateFee is in the same contract instead of being forced to call an "external" contract. That way it can also be based on internal storage instead of being forced to add public methods to get the data to calculate the fee from the "calculator contract".

As @ixje said, if we use the same contract we reduce the configuration, the contract can implement the required method and call to another contract if they want.

[vncoelho]

I thought about it and realized that if the contract uses its own token, then it doesn’t really need this API, so I agreed to support only GAS.

I think that the design should be draw to support that in the future.

If we really move in a way to have a "native DEX", this can become a possible scenario much easier.

Also, it would be interesting if Contracts create a Liquidity Pool only accessible for such cases, maybe the contract owner could provide liquidity himself. So, the pool is just used for such cases.

[roman-khimov]

1. GAS-only fees can be implemented much easier with #204 (comment)
2. Generic token fees are just a specific kind of transfer to me. Contracts can call transfer(someone, me, amount) and this is guarded with witness scopes, but the mechanism of scopes currently gives permissions for arbitrary changes and that's the thing that can be improved. If we could express a permission to transfer X amount from A to B in scopes I think this all would be solved immediately, contracts would just use regular transfer calls for their needs and it'd not require any ABI changes. Related to #137.

[roman-khimov]

Methods are defined using NEP-25 JSON, not using C#, see any other NEP defining methods for example.

[roman-khimov]

Implementation detail not relevant to the VM/runtime spec.

[roman-khimov]

Same here.