Skip to content
Documentation/
/
/
Loan
Last updated

Loan

[Source]

A Loan ledger entry defines the state of an on-chain loan agreement between a Loan Broker and a Borrower. It contains all the details of the loan, such as fees and interest rates. You can create a Loan ledger entry with the LoanSet transaction.

The Loan ledger entry is tracked in two Owner Directories:

  1. The owner directory of the Borrower on the loan.
  2. The owner directory of the LoanBroker pseudo-account.

Requires the LendingProtocol amendment.

Example Loan JSON

{
  "LedgerEntryType": "Loan",
  "LedgerIndex": "E123F4567890ABCDE123F4567890ABCDEF1234567890ABCDEF1234567890ABCD",
  "Flags": "0",
  "PreviousTxnID": "9A8765B4321CDE987654321CDE987654321CDE987654321CDE987654321CDE98",
  "PreviousTxnLgrSeq": 12345678,
  "LoanSequence": 1,
  "OwnerNode": 2,
  "LoanBrokerNode": 1,
  "LoanBrokerID": "ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890",
  "Borrower": "rEXAMPLE9AbCdEfGhIjKlMnOpQrStUvWxYz",
  "LoanOriginationFee": "100",
  "LoanServiceFee": "10",
  "LatePaymentFee": "5",
  "ClosePaymentFee": "20",
  "OverpaymentFee": 5,
  "InterestRate": 500,
  "LateInterestRate": 1000,
  "CloseInterestRate": 200,
  "OverpaymentInterestRate": 5,
  "StartDate": 1234567890,
  "PaymentInterval": 2592000,
  "GracePeriod": 604800,
  "PreviousPaymentDueDate": 1234587890,
  "NextPaymentDueDate": 1234597890,
  "PaymentRemaining": 12,
  "PrincipalOutstanding": "10000",
  "TotalValueOutstanding": "12000",
  "ManagementFeeOutstanding": "2000",
  "PeriodicPayment": "1000"
}

Loan Fields

In addition to the common ledger entry fields, Loan entries have the following fields:

NameJSON TypeInternal TypeRequired?Description
PreviousTxnIDStringHash256YesIdentifies the transaction ID that most recently modified this object.
PreviousTxnLgrSeqNumberUInt32YesThe sequence of the ledger that contains the transaction that most recently modified this object.
LoanSequenceNumberUInt32YesThe sequence number of the loan.
OwnerNodeNumberUInt64YesIdentifies the page where this item is referenced in the owner's directory.
LoanBrokerNodeNumberUInt64YesIdentifies the page where this item is referenced in the LoanBroker owner directory.
LoanBrokerIDStringHash256YesThe ID of the Loan Broker associated with this loan.
BorrowerStringAccountIDYesThe account address of the Borrower.
LoanOriginationFeeStringNumberYesThe amount paid to the Loan Broker, taken from the principal loan at creation.
LoanServiceFeeStringNumberYesThe amount paid to the Loan Broker with each loan payment.
LatePaymentFeeStringNumberYesThe amount paid to the Loan Broker for each late payment.
ClosePaymentFeeStringNumberYesThe amount paid to the Loan Broker when a full early payment is made.
OverpaymentFeeNumberUInt32YesThe fee charged on overpayments, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%.
InterestRateNumberUInt32YesThe annualized interest rate of the loan, in 1/10th basis points.
LateInterestRateNumberUInt32YesThe premium added to the interest rate for late payments, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%.
CloseInterestRateNumberUInt32YesThe interest rate charged for repaying the loan early, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%.
OverpaymentInterestRateNumberUInt32YesThe interest rate charged on overpayments, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%.
StartDateNumberUInt32YesThe timestamp of when the loan started, in seconds since the Ripple Epoch.
PaymentIntervalNumberUInt32YesThe number of seconds between loan payments.
GracePeriodNumberUInt32YesThe number of seconds after a loan payment is due before the loan defaults.
PreviousPaymentDueDateNumberUInt32YesThe timestamp of when the previous payment was made, in seconds since the Ripple Epoch.
NextPaymentDueDateNumberUInt32YesThe timestamp of when the next payment is due, in seconds since the Ripple Epoch.
PaymentRemainingNumberUInt32YesThe number of payments remaining on the loan.
PrincipalOutstandingStringNumberYesThe principal amount still owed on the loan.
TotalValueOutstandingStringNumberYesThe total amount owed on the loan, including remaining principal and fees.
ManagementFeeOutstandingStringNumberNoThe remaining management fee owed to the loan broker. Omitted when zero.
PeriodicPaymentStringNumberYesThe amount due for each payment interval, excluding the LoanServiceFee. This value is stored with full precision and can contain more decimal places than the loan's asset supports. To calculate the amount to pay, round decimals up to the next whole number (or to the loan's LoanScale for trust line tokens), then add the LoanServiceFee. The final payment is the remaining TotalValueOutstanding plus the LoanServiceFee instead.
LoanScaleNumberInt32NoThe scale factor that ensures all computed amounts are rounded to the same number of decimal places. It is based on the total loan value at creation time.
Note

When the loan broker discovers that the borrower can't make an upcoming payment, they can impair the loan to register a "paper loss" with the vault. The impairment mechanism moves up the NextPaymentDueDate to the time the loan is impaired, allowing the loan to default quicker. However, if the borrower makes a payment in the subsequent GracePeriod, the impairment status is removed.

Loan Flags

Loan entries can have the following flags:

Field NameHex ValueDecimal ValueDescription
lsfLoanDefault0x0001000065536Indicates the loan is defaulted.
lsfLoanImpaired0x00020000131072Indicates the loan is impaired.
lsfLoanOverpayment0x00040000262144Indicates the loan supports overpayments.

Loan Reserve

Loan entries incur one owner reserve from the borrower.

Loan ID Format

The ID of a Loan ledger entry is the SHA-512Half of the following values, concatenated in order:

  • The Loan space key 0x004C.
  • The LoanBrokerID of the associated LoanBroker ledger entry.
  • The LoanSequence number of the LoanBroker ledger entry.

LedgerHashes

LoanBroker