lending.daily-interest Unreviewed

pub fn daily_interest(balances: &[DatedBalance], from_iso: &str, to_iso: &str, annual_rate_basis_points: i64, convention: &str, mode: &str) -> DailyInterest

/// A balance and the day it takes effect; it holds until the next one.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DatedBalance {
    pub date: String,
    /// negative for a debt, e.g. an overdrawn account
    pub balance: Money,
}

/// The posted interest, the exact amount behind it, and the days counted.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DailyInterest {
    /// the exact total rounded once
    pub interest: Money,
    /// the exact total in minor units, before rounding
    pub exact: Rational,
    /// calendar days from fromIso to toIso
    pub days: i64,
}

fune!(lending.daily-interest@^1);  // then call daily_interest(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::dates_day_count_fraction::day_count_fraction;  ← from dates.day-count-fraction ^1.0.0 · built alongside by fune
use super::dates_days_between::days_between;  ← from dates.days-between ^1.0.0 · built alongside by fune
use super::math_rational::{add_rational, multiply_rational, rational, rational_to_integer, rational_to_value};  ← from math.rational ^1.0.0 · built alongside by fune
use super::money_amount::{money, money_from_value, money_to_value};  ← from money.amount ^1.0.0 · built alongside by fune

/// Interest on a balance that changes during the period: each balance earns
/// (or is charged) balance × rate × year fraction for the days it was held,
/// the year fractions come from dates.day-count-fraction, and the pieces are
/// added as exact fractions. Only the total is rounded, once, so splitting a
/// month into more balance changes never moves the answer by a stray penny.
///
/// # Panics
/// Panics on an empty or unordered balance list, mixed currencies, a first
/// balance after fromIso, bad dates, a rate out of range, or an exact total
/// too large for math.rational.
pub fn daily_interest(
    balances: &[DatedBalance],
    from_iso: &str,
    to_iso: &str,
    annual_rate_basis_points: i64,
    convention: &str,
    mode: &str,
) -> DailyInterest {
    let b = annual_rate_basis_points;
    if b < -100000 || b > 100000 {
        panic!("annualRateBasisPoints must be between -100000 and 100000, received {}", b);
    }
    if balances.is_empty() {
        panic!("balances must not be empty");
    }
    let days = days_between(from_iso, to_iso);
    if days < 0 {
        panic!("fromIso {} must not be after toIso {}", from_iso, to_iso);
    }
    let currency = balances[0].balance.currency.clone();
    for i in 0..balances.len() {
        days_between(&balances[i].date, &balances[i].date);
        if balances[i].balance.currency != currency {
            panic!("currency mismatch: {} and {}", currency, balances[i].balance.currency);
        }
        if i > 0 && balances[i].date <= balances[i - 1].date {
            panic!("balances must be in strictly ascending date order");
        }
    }
    if balances[0].date.as_str() > from_iso {
        panic!("the first balance starts on {}, after fromIso {}", balances[0].date, from_iso);
    }
    let rate = rational(b, 10000);
    let mut total = rational(0, 1);
    for i in 0..balances.len() {
        let date = balances[i].date.as_str();
        let start = if date > from_iso { date } else { from_iso };
        let next = if i + 1 < balances.len() { balances[i + 1].date.as_str() } else { to_iso };
        let end = if next < to_iso { next } else { to_iso };
        if start >= end {
            continue;
        }
        let fraction = day_count_fraction(start, end, convention);
        let amount = multiply_rational(&rational(balances[i].balance.minor, 1), &rate);
        total = add_rational(
            &total,
            &multiply_rational(&amount, &rational(fraction.numerator, fraction.denominator)),
        );
    }
    DailyInterest {
        interest: money(rational_to_integer(&total, mode), &currency),
        exact: total,
        days,
    }
}

pub fn dated_balance_from_value(v: &Value) -> DatedBalance {
    DatedBalance {
        date: v.get("date").as_str().to_string(),
        balance: money_from_value(v.get("balance")),
    }
}

pub fn daily_interest_to_value(result: &DailyInterest) -> Value {
    Value::obj(vec![
        ("interest", money_to_value(&result.interest)),
        ("exact", rational_to_value(&result.exact)),
        ("days", Value::Int(result.days)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    let balances: Vec<DatedBalance> = args[0].as_arr().iter().map(dated_balance_from_value).collect();
    daily_interest_to_value(&daily_interest(
        &balances,
        args[1].as_str(),
        args[2].as_str(),
        args[3].as_i64(),
        args[4].as_str(),
        args[5].as_str(),
    ))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 5 dependencies, pins them in fune.lock, downloads only the Rust package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add lending.daily-interest

The manifest, vectors and README with only the Rust implementation. Install it without the registry with fune add ./lending.daily-interest-1.0.1-rust.fune, or fetch it from a terminal with fune pull lending.daily-interest@1.0.1:rust.

The whole function, every language, is one file too: lending.daily-interest-1.0.1.fune, 26,958 bytes, sha256 2c05773e8a51ceee16cb0d3f7b369aaebb047265e4c8eb990b39c4186dae89ed. It installs into a project of any language.

// fune: before lending.daily-interest

// fune: after lending.daily-interest

// fune: replace dates.day-count-fraction in lending.daily-interest
// fune: replace dates.days-between in lending.daily-interest
// fune: replace math.rational in lending.daily-interest
// fune: replace math.round-div in lending.daily-interest
// fune: replace money.amount in lending.daily-interest

// fune: step lending.daily-interest after <n|label>

More from the author

- `balances` is the balance history: each entry holds from its date until the next entry's date. The first entry must start on or before `fromIso` (the opening balance); entries after `toIso` are ignored. - The period is `fromIso` included to `toIso` excluded, the usual accrual convention: 1 January to 31 January is 30 days of interest. - Each piece's year fraction comes from dates.day-count-fraction (ACT/365F, ACT/360, 30/360, 30E/360, ACT/ACT ISDA), as an exact fraction. - The pieces are summed exactly with math.rational, and the total is rounded once, with the mode you pass. `exact` is that unrounded total in minor units, for audit and for carrying fractions of a penny into the next period if your ledger does that.

Rounding once is the point. Rounding each day (or each balance change) and adding the rounded amounts drifts: three days at 0.23p each would post 0p where the true total is 0.68p, and more balance changes would mean more drift. Some ledgers do post whole pence daily; if yours does, call this once per day instead.

## Signs

A negative balance (overdrawn, or a loan held as a debt) accrues negative interest, and a negative rate charges a positive balance. The rounding modes are those of math.round-div, symmetric about zero: `down` is towards zero, `up` away from it.

## Splitting and 30/360

Under ACT/365F, ACT/360 and ACT/ACT the pieces add up to the whole period exactly. Under 30/360 each piece is measured on its own, as a contract that names 30/360 per balance period would, so a piece ending on the 31st can differ by a day from measuring the whole month at once.

## Limits

The exact running total must fit math.rational (numerator and denominator within 2^53 - 1); that holds for balances into the hundreds of millions of pounds at ordinary rates, and a larger one is an error ("rational overflow"), never a wrong answer. The rate is -100000 to 100000 basis points, and the rate is fixed for the period: for a rate change, call once per rate and add.

## Before you rely on this

**Not professional advice.** This capability calculates lending figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a consumer-credit compliance specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified consumer-credit compliance specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files