Skip to content
Documentation/
/
/
LoanSet
Last updated

LoanSet

[Source]

Creates a new Loan ledger entry, representing a loan agreement between a Loan Broker and Borrower.

The LoanSet transaction is a mutual agreement between the Loan Broker and Borrower, and must be signed by both parties. The following multi-signature flow can be initiated by either party:

  1. The borrower or loan broker creates the transaction with the preagreed terms of the loan. They sign the transaction and set the SigningPubKey, TxnSignature, Signers, Account, Fee, Sequence, and Counterparty fields.
  2. The counterparty verifies the loan terms and signature before signing and submitting the transaction.
Note

Loans created after the LendingProtocolV1_1 amendment is enabled can only be originated against a closed-ended vault during its Investment phase, and only if the loan's final scheduled payment is at least 60 seconds before the vault enters its Redemption phase. This means the maximum term of new loans shrinks as the vault approaches its RedemptionDate.

Requires the LendingProtocol amendment.

Requires the LendingProtocolV1_1 amendment.

Example LoanSet JSON

{
  "TransactionType": "LoanSet",
  "Account": "rEXAMPLE9AbCdEfGhIjKlMnOpQrStUvWxYz",
  "Fee": "12",
  "Flags": 0,
  "LastLedgerSequence": 7108682,
  "Sequence": 8,
  "Data": "546869732069732061726269747261727920646174612061626F757420746865206C6F616E2E",
  "Counterparty": "rCOUNTER9AbCdEfGhIjKlMnOpQrStUvWxYz",
  "LoanOriginationFee": 100,
  "LoanServiceFee": 10,
  "LatePaymentFee": 5,
  "ClosePaymentFee": 20,
  "OverpaymentFee": 5,
  "InterestRate": 500,
  "LateInterestRate": 1000,
  "CloseInterestRate": 200,
  "OverpaymentInterestRate": 5,
  "PrincipalRequested": 10000,
  "PaymentTotal": 12,
  "PaymentInterval": 2592000,
  "GracePeriod": 604800,
  "SigningPubKey": "03C040CAC1E164B0E385D31E41447FE6B8960E0D202811CFDA08B55BA29E08C6B0",
  "TxnSignature": "30440220549D359F792E155D20B5E8B3423F0F844CCF7C86986EB85BE482908A55A7157D02207B464FFE57E75D9693BAC445540CF078E9E0B6452C917DE4D66F27918D32A170",
  "hash": "831EEFF19C980FC348E984625FE41AEB27301B0B072D4239A980E78B86B2515C"
}

LoanSet Fields

In addition to the common fields, LoanSet transactions use the following fields:

Field NameJSON TypeInternal TypeRequired?Description
LoanBrokerIDStringHash256YesThe ID of the LoanBroker ledger entry.
DataStringBlobNoArbitrary metadata in hex format (max 256 bytes).
CounterpartyStringAccountIDNoThe address of the counterparty of the loan.
LoanOriginationFeeStringNumberNoThe amount paid to the LoanBroker owner when the loan is created.
LoanServiceFeeStringNumberNoThe amount paid to the LoanBroker owner with each loan payment.
LatePaymentFeeStringNumberNoThe amount paid to the LoanBroker owner for late payments.
ClosePaymentFeeStringNumberNoThe amount paid to the LoanBroker owner for early full repayment.
OverpaymentFeeNumberUInt32NoA fee charged on overpayments, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%.
InterestRateNumberUInt32NoThe annualized interest rate of the loan, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%.
LateInterestRateNumberUInt32NoA 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%.
CloseInterestRateNumberUInt32NoA fee charged for repaying the loan early, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%.
OverpaymentInterestRateNumberUInt32NoThe interest rate charged on overpayments, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%.
PrincipalRequestedStringNumberYesThe principal loan amount requested by the borrower.
PaymentTotalNumberUInt32NoThe total number of payments to be made against the loan.
PaymentIntervalNumberUInt32NoThe number of seconds between loan payments.
GracePeriodNumberUInt32NoThe number of seconds after the loan's payment due date when it can be defaulted.
SigningPubKeyStringBlobYesThe public key used to verify the validity of the first signer's signature.
TxnSignatureStringBlobYesThe hex encoding of the digital signature for the first signing.
hashStringHash256YesThe unique identifying hash of the partially-signed transaction.

If the borrower already holds the loan's asset, the transaction succeeds regardless of the issuer's DefaultRipple setting since it is only checked when a new trust line needs to be created. If a LoanOriginationFee is specified, the broker owner must also hold the asset for this to apply.

Requires the fixCleanup3_4_0 amendment.

CounterpartySignature Fields

An inner object that contains the signatures of the counterparty of the transaction. The object contains the following fields:

Field NameJSON TypeInternal TypeRequired?Description
SigningPubKeyStringSTBlobNoThe public key used to verify the validity of the signature.
TxnSignatureStringSTBlobNoThe signature over all signing fields. Must be generated using role-specific hash prefixes

Requires the fixCleanup3_4_0 amendment.

. Standard transaction signatures are rejected.
SignersListSTArrayNoAn array of transaction signatures from the counterparty. Each signature must be generated using role-specific hash prefixes

Requires the fixCleanup3_4_0 amendment.

. Standard transaction signatures are rejected.

The final transaction must include either:

  • Both the SigningPubKey and TxnSignature fields.
  • The Signers field.
Note

This field isn't included in the LoanSet JSON the first party signs, instead it's added by the counterparty when they sign.

LoanSet Flags

Transactions of the LoanSet type support additional values in the [flags field], as follows:

Flag NameHex ValueDecimal ValueDescription
tfLoanOverpayment0x0001000065536Indicates that the loan supports overpayments.

Error Cases

Besides errors that can occur for all transactions, LoanSet transactions can result in the following transaction result codes:

Error CodeDescription
tecEXPIREDThe vault is closed-ended and has entered its Redemption phase.

Requires the LendingProtocolV1_1 amendment.

tecINSUFFICIENT_FUNDS
  • The Vault associated with the LoanBroker doesn't have enough assets to fund the loan.
  • The LoanBroker ledger entry doesn't have enough first-loss capital to meet the minimum coverage requirement for the new total debt.
    • tecINSUFFICIENT_RESERVEThe borrower's account doesn't have enough XRP to meet the reserve requirements.
    tecKILLEDThe GracePeriod, PaymentInterval, or PaymentTotal (individually or combined) exceeds the latest time the protocol can represent.
    tecLIMIT_EXCEEDED
  • The requested loan would cause the LoanBroker ledger entry to exceed its maximum allowed debt.
  • The vault's AssetsTotal already meets or exceeds its AssetsMaximum. Doesn't apply to cash-basis vaults.
  • The loan's interest would push the vault's AssetsTotal past its AssetsMaximum. Doesn't apply to cash-basis vaults.
    • tecNO_ENTRYThe LoanBroker doesn't exist.
    tecNO_PERMISSION
  • Neither the transaction sender's Account or the Counterparty field owns the associated LoanBroker ledger entry.
  • The vault is closed-ended and the loan's final scheduled payment is less than 60 seconds before the vault's RedemptionDate.

    Requires the LendingProtocolV1_1 amendment.

    • tecPRECISION_LOSS
  • PrincipalRequested or one of the fee amounts is more precise than the vault's asset can hold.
  • The amount fits the asset, but is more precise than the loan's LoanScale.
    • tecTOO_SOONThe vault is closed-ended and still in its Subscription phase.

    Requires the LendingProtocolV1_1 amendment.

    temBAD_SIGNATUREThe SigningPubKey inside the CounterpartySignature isn't a valid public key.
    temBAD_SIGNER
  • The transaction isn't part of a Batch transaction and is missing a CounterpartySignature.
  • Counterparty is omitted and LoanBrokerID doesn't match an existing LoanBroker entry.
    • temINVALID
  • Data is present but empty, or longer than 256 bytes.
  • A numeric field is outside its valid range. For example, the GracePeriod can't be longer than the PaymentInterval or less than 60 seconds.
  • LoanBrokerID is zero.
    • temINVALID_FLAG
  • Flags contains a value other than tfLoanOverpayment.
  • The transaction requests reserve sponsorship, which LoanSet doesn't support.

    Requires the Sponsor amendment.

    • LoanPay

    MPTokenAuthorize