Skip to main content

FeePool

Manages the fee normalization pool for GhostTracking. Absorbs the difference between actual network fees and the flat fee displayed to users.

Source​

packages/contracts/FeePool.compact

Ledgers​

LedgerTypeDescription
user_depositsMap<Bytes, Counter>Deposits per user
pool_balanceCounterCurrent pool balance
total_normalizedCounterTotal normalization events
total_depositedCounterTotal deposits received
configMap<Bytes, Counter>Configuration (key 0x01 = flat fee)

Circuits​

initialize(flat_fee: Counter)​

Sets the flat fee amount. All normalized transactions will display this fee.

deposit(user_id: Bytes, amount: Counter)​

Adds funds to the normalization pool. Updates both the user's deposit balance and the global pool balance.

normalizeFee(user_id: Bytes, actual_fee: Counter)​

Records a fee normalization event. The pool absorbs the difference between the actual fee and the flat fee:

  • If actual_fee < flat_fee: pool receives flat_fee - actual_fee
  • If actual_fee > flat_fee: pool pays actual_fee - flat_fee

getUserDeposit(): Counter​

Returns the calling user's total deposits.

getPoolBalance(): Counter​

Returns the current pool balance.

getTotalNormalized(): Counter​

Returns the total number of normalization events.

How Fee Normalization Works​

Without GhostTracking:
  User A pays fee: 847,293  ← unique fingerprint
  User B pays fee: 1,203,847 ← unique fingerprint

With GhostTracking:
  User A pays fee: 1,000,000 ← flat fee
  User B pays fee: 1,000,000 ← flat fee
  Pool absorbs: (1,000,000 - 847,293) + (1,203,847 - 1,000,000) = 356,554

The pool must be funded to cover periods where actual fees exceed the flat fee. The FeeReserve contract can subsidize the pool during bootstrapping.