ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2026-04-29 15:37:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3487 from XRPLF/lending-use-case

Browse Source 
Lending Protocol doc updates
This commit is contained in:
oeggert
2026-02-10 10:19:59 -08:00
committed by GitHub
parent eecdaccd55 66caa79289
commit 5ad87dee4b
10 changed files with 84 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/references/protocol/ledger-data/ledger-entry-types/loan.md
View File

@@ -68,10 +68,10 @@ In addition to the [common ledger entry fields][], {% code-page-name /%} entries
| `LoanBrokerNode` | Number | UInt64 | Yes | Identifies the page where this item is referenced in the `LoanBroker` owner directory. |
| `LoanBrokerID` | String | Hash256 | Yes | The ID of the _Loan Broker_ associated with this loan. |
| `Borrower` | String | AccountID | Yes | The account address of the _Borrower_. |
| `LoanOriginationFee` | Number | Number | Yes | The amount paid to the _Loan Broker_, taken from the principal loan at creation. |
| `LoanServiceFee` | Number | Number | Yes | The amount paid to the _Loan Broker_ with each loan payment. |
| `LatePaymentFee` | Number | Number | Yes | The amount paid to the _Loan Broker_ for each late payment. |
| `ClosePaymentFee` | Number | Number | Yes | The amount paid to the _Loan Broker_ when a full early payment is made. |
| `LoanOriginationFee` | String | Number | Yes | The amount paid to the _Loan Broker_, taken from the principal loan at creation. |
| `LoanServiceFee` | String | Number | Yes | The amount paid to the _Loan Broker_ with each loan payment. |
| `LatePaymentFee` | String | Number | Yes | The amount paid to the _Loan Broker_ for each late payment. |
| `ClosePaymentFee` | String | Number | Yes | The amount paid to the _Loan Broker_ when a full early payment is made. |
| `OverpaymentFee` | Number | UInt32 | Yes | The fee charged on overpayments, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%. |
| `InterestRate` | Number | UInt32 | Yes | The annualized interest rate of the loan, in 1/10th basis points. |
| `LateInterestRate` | Number | UInt32 | Yes | The 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%. |
@@ -83,10 +83,10 @@ In addition to the [common ledger entry fields][], {% code-page-name /%} entries
| `PreviousPaymentDueDate` | Number | UInt32 | Yes | The timestamp of when the previous payment was made, in [seconds since the Ripple Epoch][]. |
| `NextPaymentDueDate` | Number | UInt32 | Yes | The timestamp of when the next payment is due, in [seconds since the Ripple Epoch][]. |
| `PaymentRemaining` | Number | UInt32 | Yes | The number of payments remaining on the loan. |
| `PrincipalOutstanding` | Number | Number | Yes | The principal amount still owed on the loan. |
| `TotalValueOutstanding` | Number | Number | Yes | The total amount owed on the loan, including remaining principal and fees. |
| `ManagementFeeOutstanding` | Number | Number | Yes | The remaining management fee owed to the loan broker. |
| `PeriodicPayment` | Number | Number | Yes | The amount due for each payment interval. |
| `PrincipalOutstanding` | String | Number | Yes | The principal amount still owed on the loan. |
| `TotalValueOutstanding` | String | Number | Yes | The total amount owed on the loan, including remaining principal and fees. |
| `ManagementFeeOutstanding` | String | Number | Yes | The remaining management fee owed to the loan broker. |
| `PeriodicPayment` | String | Number | Yes | The amount due for each payment interval. |
| `LoanScale` | Number | Int32 | No | The 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. |
{% admonition type="info" name="Note" %}
@@ -115,7 +115,6 @@ When the loan broker discovers that the borrower can't make an upcoming payment,
The ID of a `Loan` ledger entry is the [SHA-512Half][] of the following values, concatenated in order:
- The `Loan` space key `0x004C`.
- The [AccountID][] of the Borrower account.
- The `LoanBrokerID` of the associated `LoanBroker` ledger entry.
- The `LoanSequence` number of the `LoanBroker` ledger entry.

6
docs/references/protocol/ledger-data/ledger-entry-types/loanbroker.md
View File

@@ -65,9 +65,9 @@ In addition to the [common ledger entry fields][], {% code-page-name /%} entries
| `Data` | String | Blob | No | Arbitrary metadata about the vault. Limited to 256 bytes. |
| `ManagementFeeRate` | Number | UInt16 | No | The fee charged by the lending protocol, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%. |
| `OwnerCount` | Number | UInt32 | Yes | The number of active loans issued by the LoanBroker. |
| `DebtTotal` | Number | Number | Yes | The total asset amount the protocol owes the vault, including interest. |
| `DebtMaximum` | Number | Number | Yes | The maximum amount the protocol can owe the vault. The default value of `0` means there is no limit to the debt. |
| `CoverAvailable` | Number | Number | Yes | The total amount of first-loss capital deposited into the lending protocol. |
| `DebtTotal` | String | Number | Yes | The total asset amount the protocol owes the vault, including interest. |
| `DebtMaximum` | String | Number | Yes | The maximum amount the protocol can owe the vault. The default value of `0` means there is no limit to the debt. |
| `CoverAvailable` | String | Number | Yes | The total amount of first-loss capital deposited into the lending protocol. |
| `CoverRateMinimum` | Number | UInt32 | Yes | The 1/10th basis point of the `DebtTotal` that the first-loss capital must cover. Valid values are 0 to 100000 (inclusive), representing 0% to 100%. |
| `CoverRateLiquidation`| Number | UInt12 | Yes | The 1/10th basis point of minimum required first-loss capital that is moved to an asset vault to cover a loan default. Valid values are 0 to 100000 (inclusive), representing 0% to 100%. |

8
docs/references/protocol/transactions/types/loanbrokercoverclawback.md
View File

@@ -38,10 +38,10 @@ The `LoanBrokerCoverClawback` transaction claws back first-loss capital from a `
In addition to the [common fields][], {% code-page-name /%} transactions use the following fields:
| Field Name | JSON Type | Internal Type | Required? | Description |
|:-------------- |:----------|:--------------|:----------|:------------|
| `LoanBrokerID` | String | Hash256 | No | The ID of the `LoanBroker` ledger entry to clawback first-loss capital. Must be provided if `Amount` is an MPT, or `Amount` is an IOU and the specified `issuer` matches the `Account` submitting the transaction. |
| `Amount` | Object | Amount | No | The amount of first-loss capital to claw back. If the value is `0` or empty, claw back all assets down to the minimum cover (`DebtTotal * CoverRateMinimum`). |
| Field Name | JSON Type | Internal Type | Required? | Description |
|:-------------- |:--------------------|:--------------|:----------|:------------|
| `LoanBrokerID` | String | Hash256 | No | The ID of the `LoanBroker` ledger entry to clawback first-loss capital. Must be provided if `Amount` is an MPT, or `Amount` is an IOU and the specified `issuer` matches the `Account` submitting the transaction. |
| `Amount` | [Currency Amount][] | Amount | No | The amount of first-loss capital to claw back. If the value is `0` or empty, claw back all assets down to the minimum cover (`DebtTotal * CoverRateMinimum`). |
## Error Cases

8
docs/references/protocol/transactions/types/loanbrokercoverdeposit.md
View File

@@ -40,10 +40,10 @@ Only the owner of the associated `LoanBroker` entry can initiate this transactio
In addition to the [common fields][], {% code-page-name /%} transactions use the following fields:
| Field Name | JSON Type | Internal Type | Required? | Description |
|:-------------- |:----------|:--------------|:----------|:------------|
| `LoanBrokerID` | String | Hash256 | Yes | The ID of the `LoanBroker` ledger entry to deposit the first-loss capital. |
| `Amount` | Object | Amount | Yes | The amount of first-loss capital to deposit. |
| Field Name | JSON Type | Internal Type | Required? | Description |
|:-------------- |:--------------------|:--------------|:----------|:------------|
| `LoanBrokerID` | String | Hash256 | Yes | The ID of the `LoanBroker` ledger entry to deposit the first-loss capital. |
| `Amount` | [Currency Amount][] | Amount | Yes | The amount of first-loss capital to deposit. |
## Error Cases

10
docs/references/protocol/transactions/types/loanbrokercoverwithdraw.md
View File

@@ -40,11 +40,11 @@ Only the owner of the associated `LoanBroker` entry can initiate this transactio
In addition to the [common fields][], {% code-page-name /%} transactions use the following fields:
| Field Name | JSON Type | Internal Type | Required? | Description |
|:-------------- |:----------|:-------------|:----------|:------------|
| `LoanBrokerID` | String | Hash256 | Yes | The ID of the `LoanBroker` ledger entry to withdraw from. |
| `Amount` | Object | Amount | Yes | The amount of first-loss capital to withdraw. |
| `Destination` | String | AccountID | No | An account to receive the assets. |
| Field Name | JSON Type | Internal Type | Required? | Description |
|:-------------- |:--------------------|:--------------|:----------|:------------|
| `LoanBrokerID` | String | Hash256 | Yes | The ID of the `LoanBroker` ledger entry to withdraw from. |
| `Amount` | [Currency Amount][] | Amount | Yes | The amount of first-loss capital to withdraw. |
| `Destination` | String | AccountID | No | An account to receive the assets. |
## Error Cases

2
docs/references/protocol/transactions/types/loanbrokerset.md
View File

@@ -45,7 +45,7 @@ In addition to the [common fields][], {% code-page-name /%} transactions use the
| `LoanBrokerID` | String | Hash256 | No | The loan broker ID that the transaction is modifying. |
| `Data` | String | Blob | No | Arbitrary metadata in hex format--limited to 256 bytes. |
| `ManagementFeeRate` | Number | UInt16 | No | The 1/10th basis point fee charged by the lending protocol owner. Valid values range from `0` to `10000` (inclusive), representing 0% to 10%. |
| `DebtMaximum` | Number | Number | No | The maximum amount the protocol can owe the vault. The default value of `0` means there is no limit to the debt. Must be a positive value. |
| `DebtMaximum` | String | Number | No | The maximum amount the protocol can owe the vault. The default value of `0` means there is no limit to the debt. Must be a positive value. |
| `CoverRateMinimum` | Number | UInt32 | No | The 1/10th basis point `DebtTotal` that the first-loss capital must cover. Valid values range from `0` to `100000` (inclusive), representing 0% to 100%. |
| `CoverRateLiquidation` | Number | UInt32 | No | The 1/10th basis point of minimum required first-loss capital that is moved to an asset vault to cover a loan default. Valid values range from `0` to `100000` (inclusive), representing 0% to 100%. |

1
docs/references/protocol/transactions/types/loanmanage.md
View File

@@ -38,7 +38,6 @@ In addition to the [common fields][], {% code-page-name /%} transactions use the
| Field Name | JSON Type | Internal Type | Required? | Description |
|:-------------- |:----------|:-------------|:----------|:------------|
| `LoanID` | String | Hash256 | Yes | The ID of the `Loan` ledger entry to manage. |
| `Flags` | String | UInt32 | No | The flag to modify the loan. |
## {% $frontmatter.seo.title %} Flags

17
docs/references/protocol/transactions/types/loanpay.md
View File

@@ -43,20 +43,21 @@ To see how loan payment transactions are calculated, see [transaction pseudo-cod
In addition to the [common fields][], {% code-page-name /%} transactions use the following fields:
| Field Name | JSON Type | Internal Type | Required? | Description |
|:--------------- |:----------|:-------------|:----------|:------------|
| `LoanID` | String | Hash256 | Yes | The ID of the `Loan` ledger entry to repay. |
| `Amount` | Number | Amount | Yes | The amount to pay toward the loan. |
| Field Name | JSON Type | Internal Type | Required? | Description |
|:--------------- |:--------------------|:--------------|:----------|:------------|
| `LoanID` | String | Hash256 | Yes | The ID of the `Loan` ledger entry to repay. |
| `Amount` | [Currency Amount][] | Amount | Yes | The amount to pay toward the loan. |
## {% $frontmatter.seo.title %} Flags
Transactions of the {% code-page-name /%} type support additional values in the [flags field], as follows:
| Flag Name | Hex Value | Decimal Value | Description |
|:----------|:----------|:--------------|:------------|
| `tfLoanOverpayment` | `0x00010000` | 65536 | Indicates that the remaining payment amount should be treated as an overpayment. |
| `tfLoanFullPayment` | `0x00020000` | 131072 | Indicates that the borrower is making a full early repayment. |
| Flag Name | Hex Value | Decimal Value | Description |
|:--------------------|:-------------|:--------------|:------------|
| `tfLoanOverpayment` | `0x00010000` | 65536 | Indicates that the remaining payment amount should be treated as an overpayment. |
| `tfLoanFullPayment` | `0x00020000` | 131072 | Indicates that the borrower is making a full early repayment. |
| `tfLoanLatePayment` | `0x00040000` | 262144 | Indicates that the borrower is making a late loan payment. |
## Error Cases

13
docs/references/protocol/transactions/types/loanset.md
View File

@@ -58,19 +58,18 @@ In addition to the [common fields][], {% code-page-name /%} transactions use the
| Field Name | JSON Type | Internal Type | Required? | Description |
|:--------------------------|:----------|:--------------|:----------|:------------|
| `LoanBrokerID` | String | Hash256 | Yes | The ID of the `LoanBroker` ledger entry. |
| `Flags` | String | UInt32 | No | Flags for the loan. |
| `Data` | String | Blob | No | Arbitrary metadata in hex format (max 256 bytes). |
| `Counterparty` | String | AccountID | No | The address of the counterparty of the loan. |
| `LoanOriginationFee` | Number | Number | No | The amount paid to the `LoanBroker` owner when the loan is created. |
| `LoanServiceFee` | Number | Number | No | The amount paid to the `LoanBroker` owner with each loan payment. |
| `LatePaymentFee` | Number | Number | No | The amount paid to the `LoanBroker` owner for late payments. |
| `ClosePaymentFee` | Number | Number | No | The amount paid to the `LoanBroker` owner for early full repayment. |
| `LoanOriginationFee` | String | Number | No | The amount paid to the `LoanBroker` owner when the loan is created. |
| `LoanServiceFee` | String | Number | No | The amount paid to the `LoanBroker` owner with each loan payment. |
| `LatePaymentFee` | String | Number | No | The amount paid to the `LoanBroker` owner for late payments. |
| `ClosePaymentFee` | String | Number | No | The amount paid to the `LoanBroker` owner for early full repayment. |
| `OverpaymentFee` | Number | UInt32 | No | A fee charged on overpayments, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%. |
| `InterestRate` | Number | UInt32 | No | The annualized interest rate of the loan, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%. |
| `LateInterestRate` | Number | UInt32 | No | A 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%. |
| `CloseInterestRate` | Number | UInt32 | No | A 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%. |
| `OverpaymentInterestRate` | Number | UInt32 | No | The interest rate charged on overpayments, in units of 1/10th basis points. Valid values are 0 to 100000 (inclusive), representing 0% to 100%. |
| `PrincipalRequested` | Number | Number | Yes | The principal loan amount requested by the borrower. |
| `PrincipalRequested` | String | Number | Yes | The principal loan amount requested by the borrower. |
| `PaymentTotal` | Number | UInt32 | No | The total number of payments to be made against the loan. |
| `PaymentInterval` | Number | UInt32 | No | The number of seconds between loan payments. |
| `GracePeriod` | Number | UInt32 | No | The number of seconds after the loan's payment due date when it can be defaulted. |
@@ -113,7 +112,7 @@ Besides errors that can occur for all transactions, {% code-page-name /%} transa
| Error Code | Description |
|:--------------------------|:-----------------------------------|
| `temBAD_SIGNER` | - The transaction is missing a `CounterpartySignature` field.<br>- This transaction is part of a `Batch` transaction, but didn't specify a `Counterparty`. |
| `temINVALID` | One or more of the numeric fields are outside their valid ranges. For example, the `GracePeriod` can't be longer than the `PaymentInterval`. |
| `temINVALID` | One or more of the numeric fields are outside their valid ranges. For example, the `GracePeriod` can't be longer than the `PaymentInterval` or less than `60` seconds. |
| `tecNO_ENTRY` | The `LoanBroker` doesn't exist. |
| `tecNO_PERMISSION` | Neither the transaction sender's `Account` or the `Counterparty` field owns the associated `LoanBroker` ledger entry. |
| `tecINSUFFICIENT_FUNDS` | - The `Vault` associated with the `LoanBroker` doesn't have enough assets to fund the loan.<br>- The `LoanBroker` ledger entry doesn't have enough first-loss capital to meet the minimum coverage requirement for the new total debt. |

60
docs/use-cases/defi/institutional-credit-facilities.md
View File

@@ -44,8 +44,8 @@ The XRPL lending protocol addresses these challenges through:
### Regulatory Compliance
- Accounts on the XRPL can be vetted by a trusted credential issuer. Credentials can be issued and revoked, based around relevant criteria, such as credit score.
- Permissioned Domains act as a gateway, limiting who can access the credit facilities, based on accepted credentials you define.
- Accounts on the XRPL can be vetted by a trusted credential issuer. Credentials can be issued and revoked based on relevant criteria, such as credit score.
- Permissioned Domains act as a gateway, limiting who can access the credit facilities based on accepted credentials you define.
- All credential and loan info is transparent on the XRPL, which makes compliance reporting and monitoring simpler and tamper-proof.
@@ -56,18 +56,46 @@ The XRPL lending protocol addresses these challenges through:
- Built-in first-loss capital features automatically protect against asset losses from defaults.
## Implementation Steps
## User Journeys
1. Set Up Credential System
- Select or become a credential issuer.
- Define required credentials for borrowers.
- Set up Permissioned Domains to protect your lending protocol and stay compliant with regulations.
2. Set Up Asset Vaults
- Set up vaults for different lending assets.
- Define public/private access parameters.
- Establish vault management policies.
3. Deploy Lending Protocol
- Create a LoanBroker and configure lending parameters.
- Create and manage loans, including fees, impairment and default settings.
- Set up monitoring and reporting systems.
- Withdraw and repay loans.
There are three users that enable institutional credit facilities on the XRP Ledger: Loan Brokers, Lenders, and Borrowers. The tabs below outline which features and transactions each user typically uses in the lending process.
{% tabs %}
{% tab label="Loan Broker" %}
As a **Loan Broker**, I need to:
- Create a [LoanBroker entry][] to define the configuration of a Lending Protocol.
- Maintain the required [first-loss capital](../../concepts/tokens/lending-protocol.md#first-loss-capital) to protect deposits in my Single Asset Vault.
| Step | Description | Technical Implementation |
|:-------------------------------|:------------|:-------------------------|
| Vault Setup | The Loan Broker creates a Single Asset Vault to aggregate one type of asset to lend out. They define a [permissioned domain][] to ensure only accounts that meet KYB (Know Your Business) compliance requirements can deposit into the vault. | - [Create Permissioned Domains](../../tutorials/javascript/compliance/create-permissioned-domains.md)<br>- [Create a Single Asset Vault](../../tutorials/how-tos/set-up-lending/use-single-asset-vaults/create-a-single-asset-vault.md) |
| Lending Protocol Setup | The Loan Broker sets up the Lending Protocol instance, linking it to the Single Asset Vault they created, and defining parameters such as payment fees. | [Create a Loan Broker](../../tutorials/how-tos/set-up-lending/use-the-lending-protocol/create-a-loan-broker.md) |
| First-loss Capital Maintenance | The Loan Broker deposits first-loss capital into the Lending Protocol to meet the minimum cover required. When there is excess cover, they withdraw first-loss capital. | [Deposit and Withdraw First-Loss Capital](../../tutorials/how-tos/set-up-lending/use-the-lending-protocol/deposit-and-withdraw-cover.md) |
{% /tab %}
{% tab label="Lender" %}
As a **Lender**, I need to:
- Authorize my account to deposit assets into a Single Asset Vault, so that I can deploy idle liquidity to generate yield.
- Redeem vault shares to realize my earnings and return assets to my account.
| Step | Description | Technical Implementation |
|:----------------|:------------|:-------------------------|
| Onboarding | The Lender triggers a verification workflow with the Loan Broker managing the Lending Protocol. The Loan Broker can issue their own credentials or utilize a credential issuer. Upon successful KYB, a credential is issued and the Lender accepts the credential. | [Build a Credential Issuing Service](../../tutorials/javascript/build-apps/credential-issuing-service.md) |
| Deposit Asset | The Lender deposits assets into a Single Asset Vault to lend out. Vault shares are minted and sent back to the Lender, representing their stake in the vault. | [Deposit into a Vault](../../tutorials/how-tos/set-up-lending/use-single-asset-vaults/deposit-into-a-vault.md) |
| Withdraw Asset | Vault shares are yield-bearing assets; the vault collects interest and fees on loans, which increases the underlying value of each vault share. The Lender collects their deposit (plus yield) by redeeming vault shares. | [Withdraw from a Vault](../../tutorials/how-tos/set-up-lending/use-single-asset-vaults/withdraw-from-a-vault.md) |
{% /tab %}
{% tab label="Borrower" %}
As a **Borrower**, I need to:
- Authorize my account to request loans from a Loan Broker.
- Repay my loan.
| Step | Description | Technical Implementation |
|:-----------------|:------------|:-------------------------|
| Onboarding | The Borrower triggers a verification workflow with the Loan Broker managing the Lending Protocol. The Loan Broker can issue their own credentials or utilize a credential issuer. Upon successful KYB, a credential is issued and the Borrower accepts the credential. | [Build a Credential Issuing Service](../../tutorials/javascript/build-apps/credential-issuing-service.md) |
| Loan Application | The Borrower applies for a loan with the Loan Broker. Both parties agree on the terms and co-sign the loan. | [Create a Loan](../../tutorials/how-tos/set-up-lending/use-the-lending-protocol/create-a-loan.md) |
| Repayment | The Borrower makes payments on principal, interest, and fees according to the loan agreement. | [Pay Off a Loan](../../tutorials/how-tos/set-up-lending/use-the-lending-protocol/pay-off-a-loan.md) |
{% /tab %}
{% /tabs %}
{% raw-partial file="/docs/_snippets/common-links.md" /%}