credit-facility-rs

A Rust library for modeling and managing various types of credit facilities including term loans, revolving credit, open-term loans, and overdraft facilities. Provides deterministic time control for testing and financial calculations.

Features

Multiple facility types
- Term loans (personal, mortgage, auto)
- Revolving credit (credit cards, HELOC)
- Open-term loans with collateral
- Overdraft facilities
Time control system
- Deterministic time manipulation for testing
- Real-time and controlled time modes
- Built on hourglass-rs SafeTimeProvider
Financial calculations
- Interest accrual with multiple conventions
- Payment processing and amortization
- Penalty calculations and grace periods
- Collateral monitoring and liquidation
API design
- Unified primitives: approve, deny, disburse, make_payment, json
- Builder pattern with .set_time(&time).build()
- JSON serialization for state inspection

Quick start

use credit_facility_rs::{Money, Rate};
use credit_facility_rs::facilities::TermLoanBuilder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // create a $10,000 personal loan
    let mut loan = TermLoanBuilder::new()
        .amount(Money::from_major(10_000))
        .rate(Rate::from_percentage(8))
        .term_months(12)
        .build()?;
    
    // approve and disburse
    loan.approve()?;
    loan.disburse(Money::from_major(10_000))?;
    
    // make a payment
    loan.make_payment(Money::from_major(500))?;
    
    // print current state
    println!("{}", loan.json());
    
    Ok(())
}

Time control for testing

use credit_facility_rs::{Money, Rate, SafeTimeProvider, TimeSource};
use credit_facility_rs::facilities::TermLoanBuilder;
use chrono::{Duration, TimeZone, Utc};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // create controlled time for testing
    let time = SafeTimeProvider::new(TimeSource::Test(
        Utc.with_ymd_and_hms(2024, 1, 1, 0, 0, 0).unwrap()
    ));
    let controller = time.test_control().unwrap();
    
    // create loan with controlled time
    let mut loan = TermLoanBuilder::new()
        .amount(Money::from_major(100_000))
        .rate(Rate::from_percentage(5))
        .term_months(36)
        .set_time(&time)  // set time controller
        .build()?;
    
    // originate at t=0
    loan.approve()?;
    loan.disburse(Money::from_major(100_000))?;
    
    // advance 30 days
    controller.advance(Duration::days(30));
    
    // accrue interest and make payment
    loan.accrue_interest()?;
    loan.process_scheduled_payment()?;
    
    Ok(())
}

API patterns

All facility types follow consistent patterns:

Core operations

approve() - approve the facility for use
deny() - deny/cancel the facility
disburse(amount) - disburse funds
make_payment(amount) - process a payment
json() - get JSON representation of current state

Time management

.set_time(&time) - set time provider during construction
.build() - build facility with stored or system time
accrue_interest() - accrue interest using stored time
update_daily_status() - update status using stored time

State inspection

.facility() - access underlying facility data
.json() - pretty-printed JSON state
Status lifecycle: Originated → Active → Settled/GracePeriod/Delinquent

Examples

The examples/ directory contains 11 examples:

00_quick_start - minimal usage example
01_basic_usage - basic facility operations
02_time_control - deterministic time manipulation
03_facility_types - different facility types
04_shared_time - shared time across facilities
05_json_state - JSON serialization
06_lifecycle - facility status lifecycle
07_bitcoin_loan - collateralized bitcoin loan
08_revolving_credit - revolving credit facility
09_overdraft - overdraft facility
10_status_test - status transition testing

Run examples with:

cargo run --example 00_quick_start
cargo run --example 02_time_control

Installation

Add to your Cargo.toml:

[dependencies]
credit-facility-rs = "0.1.0"

Dependencies:

rust_decimal - precise decimal arithmetic
chrono - date/time handling
hourglass-rs - time control for testing
uuid - unique identifiers
serde - JSON serialization

Testing

Run all tests:

cargo test

Runs 88 unit tests covering facility types, interest calculations, payment processing, collateral management, and time manipulation.

Architecture

The library is organized into modules:

facilities/ - facility implementations (term_loan, revolving, open_term, overdraft)
interest/ - interest calculation engines
payments/ - payment processing and amortization
collateral/ - collateral management and liquidation
decimal/ - precise decimal types (Money, Rate)
config/ - facility configuration
state/ - facility state management
events/ - event system for auditing

Known limitations

Denied loans use Settled status (no Cancelled status yet)
Scheduled payments may leave small residual balances due to rounding
Some edge cases in payment timing and status transitions

credit-facility-rs 0.1.0