Skip to main content

Fee Arithmetic in Program Escrow

Last updated: 16 August 2026

Archived — describes a contract that does not exist

This page is in the archive: it documents a Soroban contract surface with no implementation in any Grainlify repository, verified 16 August 2026. Kept as a design record, not as a description of working software.

Overview​

The Program Escrow contract uses precise fee arithmetic to manage prize pools and fee collection. Ensuring no value is lost or created out of thin air is critical for security and financial integrity.

Rounding Policy​

The contract employs floor (round-down) rounding for all fee calculations. This ensures that the protocol never overcharges the user.

Any remainder from basis-point division (dust) remains with the payer as part of the net amount, adhering to the fundamental invariant:

fee + net_amount == gross_amount

Implementation​

Fee calculation is performed in contracts/program-escrow/src/token_math.rs:

pub fn calculate_fee(amount: i128, fee_rate: i128) -> i128 {
    amount
        .checked_mul(fee_rate)
        .and_then(|x| x.checked_div(BASIS_POINTS))
        .unwrap_or(0)
}

Security Invariants​

  1. Conservation of Value: The sum of fee and net_amount must always equal the gross_amount input.
  2. No Over-charge: The fee must never exceed the calculated share based on basis points.
  3. No Overflow: Calculations must be safe against integer overflow, panicking if they occur.
  4. Dust Control: For equal splits, any rounding remainder (dust) is accounted for in the net_amount, ensuring no token loss.