Terms

Terms is a value object that captures the complete set of parameters under which a credit facility operates. When a facility is created from a proposal, the proposal's effective terms — the product terms pinned at proposal creation plus any per-deal alterations — become the permanent contract governing the facility's behavior. They cannot be changed after facility creation.

Fields

Interest Rate

annual_rate — The annualized interest rate charged on outstanding principal, expressed as a percentage.

The system uses this rate to calculate daily interest: principal * days * rate / 365, rounded to whole USD cents. This calculation runs on every accrual period (typically daily), and the results accumulate throughout each accrual cycle (typically monthly) before being posted as an interest obligation.

Duration and Maturity

duration — The total lifespan of the credit facility, specified in months.

The maturity date is calculated by adding this many months to the facility's activation date. The duration also determines the accounting classification: facilities with a duration of 12 months or less are classified as "short-term" and facilities longer than 12 months as "long-term." This classification determines which ledger account set (short-term vs. long-term receivables) is used for the facility's accounting entries.

After maturity:

• No new disbursals are permitted.
• No new interest accrual cycles are started.
• Any accrued but not-yet-posted interest is immediately consolidated into a final obligation.
• The facility remains open until all outstanding obligations are fully paid.

Interest Timing

Interest is always calculated daily (end of day) on the outstanding balance — this accrual granularity is fixed and not configurable per product.

accrual_cycle_interval — The cadence at which accumulated interest becomes an obligation. Typically set to EndOfMonth, meaning daily interest calculations are summed and posted as a payable interest obligation at the end of each month.

This creates a two-level timing system: interest accrues at a fixed daily granularity, while the accrual_cycle_interval controls how often the customer receives an interest bill. This separation allows the bank to calculate interest at fine granularity while billing at practical intervals.

Obligation Timing

interest_due_duration_from_accrual — The time between when interest is accrued (end of cycle) and when the resulting obligation becomes due. With a value of Days(0), the interest obligation is due immediately when the cycle ends.

obligation_overdue_duration_from_due — Optional grace period after the due date before an obligation transitions to "overdue" status. When set, obligations move from Due to Overdue after this many days past the due date. When not set, obligations never enter the overdue state.

obligation_liquidation_duration_from_due — Optional period after the due date at which an unpaid obligation enters the "defaulted" state and becomes eligible for the collection/liquidation process. When not set, obligations never enter the defaulted state from aging alone.

These three fields together create the graduated escalation path for unpaid obligations:

Accrual → Due → (grace period) → Overdue → (default period) → Defaulted

Fee

one_time_fee_rate — A structuring/origination fee expressed as a percentage of the facility amount, charged against the facility at activation and repaid at maturity as principal. If zero, no fee is applied.

The fee is calculated as facility_amount * (rate / 100). For single-disbursal facilities, the fee is charged as part of the initial disbursal. For multi-disbursal facilities, an initial disbursal covering just the fee amount is created automatically at activation.

Collateral Thresholds

Three loan-to-value (LTV) percentage thresholds create a graduated safety system for managing Bitcoin collateral volatility. Loan-to-value is outstanding_exposure / collateral_value * 100, so a lower LTV means the facility is safer.

initial_loan_to_value_limit — The maximum LTV permitted to activate a facility and the target level for post-liquidation recovery. A lower value means the bank requires more collateral cushion before extending credit.

margin_call_loan_to_value_limit — The threshold above which the facility enters a margin call state. Also used as the gate for new disbursals: no disbursal is allowed if it would push the LTV above this level.

liquidation_loan_to_value_limit — The highest threshold. When the LTV rises above this level, a partial liquidation is automatically initiated to sell enough collateral to restore the LTV at or below the initial level.

Validation: The three thresholds must be strictly ordered initial_loan_to_value_limit < margin_call_loan_to_value_limit < liquidation_loan_to_value_limit, every value must be finite, strictly greater than 0%, and strictly less than 100%. Equality at any boundary is rejected whenever terms are set: at product creation, product terms update, and proposal creation (after alterations are applied).

The collateral states and their operational implications:

Current LTV	State	Effect
current_ltv == 0 (no exposure)	No Exposure	No outstanding exposure; collateralization price thresholds are not set
Above 0 and at or below margin_call_loan_to_value_limit	Fully Collateralized	Normal operations, but disbursals blocked if they would push LTV above margin call
Above margin_call_loan_to_value_limit and at or below liquidation_loan_to_value_limit	Under Margin Call	Borrower notified to post additional collateral
Above liquidation_loan_to_value_limit	Under Liquidation	Partial liquidation initiated automatically
Infinite LTV (outstanding exposure with no collateral)	No Collateral	No collateralization price thresholds are set; automatic partial liquidation is not initiated from this state

A hysteresis buffer prevents rapid oscillation between states when the LTV hovers near a threshold boundary.

Disbursal Policy

disbursal_policy — Controls whether the facility amount is drawn down all at once or incrementally.

• Single Disbursal: The entire facility amount is disbursed automatically at activation as a pre-approved disbursal. No additional disbursals are possible.
• Multiple Disbursal: At activation, nothing is paid out; the structuring fee (if applicable) is charged against the facility. The customer can request additional disbursals over time, each requiring its own governance approval. This is useful for working capital lines where the borrower's cash needs vary.

Product Terms

Term values are defined on credit facility products. Each CreditFacilityProduct embeds a versioned set of default terms: the version starts at 1 and increments on every value change, so any historical set of terms is identifiable by product and version.

Key characteristics:

• Pinned, not linked: When a proposal is created, the product's current terms (values and version) are copied into the proposal. Updating the product's terms afterward does not change existing proposals or facilities.
• Explicit alterations: A proposal may deviate from the pinned product terms through a list of typed, per-field alterations. The proposal's effective terms are the pinned snapshot with the alterations applied. Each field may be altered at most once, and the resulting terms must pass the same validation as product terms.
• Version guard: Proposal creation carries the product terms version the operator saw; if the product's terms changed in the meantime, creation is rejected rather than silently using different terms.
• Risk controls: Product terms are effectively risk controls, not just configuration. The LTV thresholds, interest rates, and fee rates defined on a product directly determine the safety boundaries and economics of every facility created from it.

Product Lifecycle

Credit facility products are either Enabled or Retired. Enabled products can originate new proposals. Retiring a product removes it from proposal selection and rejects direct attempts to create a proposal from it.

Retirement is not retroactive. Proposals created before retirement can continue through approval, collateralization, activation, disbursal, accrual, and repayment. Active facilities are also unaffected, and retired products remain available in management and historical views for product lineage.

Changing product status does not create a new terms version because availability and commercial terms are independent controls.

Operational Importance

From an operations perspective, product terms are the most impactful configuration in the system:

• annual_rate and duration shape borrowing cost and the obligation timeline.
• initial_loan_to_value_limit, margin_call_loan_to_value_limit, and liquidation_loan_to_value_limit define the LTV safety boundaries that protect the bank against BTC price volatility.
• one_time_fee_rate controls upfront fee revenue.
• accrual_cycle_interval determines billing frequency (monthly billing is standard).
• disbursal_policy controls whether lending is single-shot or incremental.

The quality of a product's terms directly impacts approval behavior, activation requirements, interest accrual patterns, and downstream collateral monitoring. Incorrect thresholds or intervals produce incorrect lifecycle behavior for every facility created from the product — and per-deal alterations should be the exception, not a way to route around product configuration.

In the admin panel, the proposal form pre-fills from the selected product's current terms; fields the operator edits away from those defaults are submitted as alterations.