XRPL Lending Protocol: Key Findings for Developers

Orma exists because a number that should be easy to read turned out not to be readable at all by the obvious method. Getting from there to a working measurement, publication, and enforcement layer meant originating real loans on Devnet, servicing them, impairing them, defaulting them, liquidating first-loss cover, and reading every result back. This page is what that cost — seven findings in the order you meet them as a developer, each verified against the live protocol with a transaction hash.

Environment	Detail
Network	XRPL Devnet, `wss://s.devnet.rippletest.net:51233`, `network_id` 2
Server	rippled 3.4.0-rc5, 89 amendments including `LendingProtocolV1_1` and `fixCleanup3_4_0`
Libraries	`xrpl` 5.2.0 with `ripple-binary-codec` 2.11.0, Node 24.13.0
Re-verification	Every finding below re-verified live on 2026-09-12

This runs on Devnet because it has to. SingleAssetVault, LendingProtocol, and LendingProtocolV1_1 are not on Mainnet. XLS-47 Price Oracle is live on Mainnet, so the publication rail is the one component with a production path today. The measurement and the gate both read or bind a vault object, so neither is deployable until the lending amendments ship.

Severity rubric

Level	Meaning
P0	No supported path exists in the published tooling, or the documented path cannot succeed. The cost is a lost day, and the developer has no way to know the fault is not theirs.
P1	Costs hours and has a non-obvious workaround. Silent wrong-value bugs live here regardless of how small the fix is — the cost is the hours before you know you have a problem.
P2	Friction, or a documentation inaccuracy. You lose minutes, or you are told something untrue and find out cheaply.

Findings

1. LoanBroker requires a closed-ended vault — and no standard states it (P0)

What you expect. LoanBrokerSet requires the submitter to be the vault owner. You create a vault, you own it, you attach a broker.What actually happens. tecNO_PERMISSION, on a vault you own. The missing rule: under LendingProtocolV1_1, a loan broker may only be attached to a closed-ended vault. The proof by exhaustion, holding the owner constant and varying only the vault kind:

Submitter	Vault kind	Result	Hash
Non-owner	Open-ended	`tecNO_PERMISSION`	`A260515D…`
Non-owner	Closed-ended	`tecNO_PERMISSION`	`FCF6DC50…`
Vault owner	Open-ended	`tecNO_PERMISSION`	`86AC8182A100EEDA32495706C06CDAC6D522B0E0772F5F65696064B6F3C0E5ED`
Vault owner	Closed-ended	`tesSUCCESS`	`CFC576DF9DCF7DB12059C559F93BE6F6094011820796859A1E814586C0E4AD5F`

The rule is in the C++ source. LoanBrokerSet.cpp lines 149–161 carry both the check and a comment explaining exactly the confusion it causes, ending in JLOG(ctx.j.warn()) << "LoanBroker requires a closed-ended Vault.". rippled computes that sentence and then discards it.Across the published XLS-0065, XLS-0065/65.1, and XLS-0066 documents on master, the strings VaultKind, SubscriptionDate, RedemptionDate, LEVersion, and “closed-ended” each appear zero times. The closed-ended vault is specified in XRPL-Standards PR #587 (open since 2026-07-21), cash-basis accounting in PR #582 (2026-07-16). Library maintainers can read them; application developers cannot.What it costs you. VaultKind is immutable. VaultSet rejects it at deserialisation with "Field 'VaultKind' found in disallowed location." There is no conversion path. If you follow the published documentation, create an open-ended vault, take deposits into it, and then discover the lending layer is unavailable — you rebuild from scratch.Cheapest fix. Add an eleventh protocol-level failure condition to XLS-66 §3.3.3.2: “Vault(VaultID).VaultKind is not ClosedEnded (tecNO_PERMISSION), requires LendingProtocolV1_1.” The behaviour is already agreed (rippled#8076, merged 2026-08-26) and already documented in the open xrpl-dev-portal#3923, which targets release-3.4.0 and is not on xrpl.org yet.Your fix today. Always set VaultKind: 1, SubscriptionDate, RedemptionDate, and LEVersion: 1 on VaultCreate.

2. The first impairment is invisible to metadata diffs (P1)

What you expect. Vault.LossUnrealized moves from 0 to 10,000,000 drops. Transaction metadata records changes, so an indexer that diffs PreviousFields against FinalFields — the standard indexer pattern — sees it.What actually happens. PreviousFields is an empty object. Verbatim, from LoanManage with tfLoanImpair, transaction 075FE6D2E0F29919AF477A2A8F581A680805A006138BB967D8434611E49229C3 (the Meridian facility, Devnet):

{
  "ModifiedNode": {
    "FinalFields": {
      "LossUnrealized": "10000000",
      "AssetsTotal": "51000000",
      "AssetsAvailable": "41000000"
    },
    "LedgerEntryType": "Vault",
    "LedgerIndex": "...",
    "PreviousFields": {}
  }
}

rippled omits from PreviousFields any field whose previous value equalled the type default. LossUnrealized defaults to 0. Under cash-basis accounting an impairment changes nothing else on the Vault — AssetsTotal and AssetsAvailable are untouched. The result is a ModifiedNode that reads as touched but unchanged.

Reading	Value
`AssetsTotal / OutstandingAmount`	1.000000
`(AssetsTotal - LossUnrealized) / OutstandingAmount`	0.803922
Divergence	1,961 bps

A metadata-diffing indexer reports no change across a 19.61% fall in net asset value.The failure is asymmetric, which is why it survives testing:

Event	Previous value	`PreviousFields`	Visible to a diff
First impairment of a healthy vault	0 (type default)	`{}`	No
`tfLoanUnimpair`	10000000	`{"LossUnrealized":"10000000"}`	Yes
Second impairment while one is outstanding	2000000	`{"LossUnrealized":"2000000"}`	Yes

An indexer author who tests the reversal or a second impairment sees correct metadata and concludes everything works. The only broken case is the transition from healthy to distressed.This was reported before us as rippled#6487, by the operator of the XRPLWin explorer — precisely the metadata-diffing indexer author this trap is built for. He closed it himself the same day: “Not a bug.” No maintainer replied. The behaviour is unchanged on 3.4.0-rc5.Your fix. Never diff. Re-read the full Vault SLE after every LoanManage. Coalesce absent fields to zero in one place:

export function num(v) {
  if (v === undefined || v === null || v === '') return new Decimal(0)
  if (v instanceof Decimal) return v
  return new Decimal(String(v))
}

3. LoanManage carries no LoanBrokerID — every impairment drops from naive filters (P1)

What you expect. To assess a manager, you walk account_tx for the broker owner and keep transactions that concern this broker. A natural filter: keep transactions where tx.LoanBrokerID matches, or where the LoanBroker node appears in AffectedNodes.What actually happens. LoanManage carries LoanID only. It has no LoanBrokerID field on any flag. An impairment does not touch the LoanBroker object at all. The complete AffectedNodes set for an impairment on a funded vault with a broker and cover in place:

Node	Type
`ModifiedNode`	`Loan`
`ModifiedNode`	`AccountRoot`
`ModifiedNode`	`Vault`

A filter on either the transaction field or the broker node returns cover deposits and defaults — and silently drops every impairment. The record comes back complete, in the right order, with correct figures, and missing precisely the events that show a manager behaving well.In Orma’s original conduct assessment this inverted a reputation rule: brokers who impaired before defaulting looked like brokers who never warned anyone. No exception was thrown. No result code was wrong. The assessment returned a plausible, reviewer-acceptable history that quietly penalised disclosure and rewarded concealment.Your fix. The join is free. The Loan node in the same metadata carries FinalFields.LoanBrokerID:

const loanNode = nodes.find((n) => n.LedgerEntryType === 'Loan')
const loanBroker = loanNode?.FinalFields?.LoanBrokerID ?? loanNode?.PreviousFields?.LoanBrokerID

if (!brokerNode && tx.LoanBrokerID !== brokerId && loanBroker !== brokerId) continue

Note also: on a default, the ledger deletes PrincipalOutstanding from the loan, so FinalFields carries nothing and the obvious read returns zero. Fall back to PreviousFields.PrincipalOutstanding, then to the broker’s book movement.

4. Pin xrpl@5.2.0 — VaultCreate fails on earlier versions (P1)

What you expect. npm install xrpl installs a library that can serialise a closed-ended VaultCreate with VaultKind, SubscriptionDate, and RedemptionDate.What actually happens. For 17 days before the event, installing xrpl brought a version whose codec could not serialise those fields. validate() and autofill() both passed the transaction. The failure surfaced as an opaque codec error inside Wallet.sign() — no result code, no field name, no amendment name.ripple-binary-codec@2.11.0 fixed this on 2026-09-11, and xrpl@5.2.0 followed hours later with the SIGNING_ENCODERS table fix that also enabled counterparty signing for LoanSet. Both reached every fresh npm install automatically, because the codec range floats.xrpl-py received neither fix. No published Python version can counterparty-sign a LoanSet, so there is no Python path to originate a loan on this protocol at time of writing.Your fix. Pin "xrpl": "5.2.0" and "ripple-binary-codec": "2.11.0" explicitly in package.json. Floating the range means the floor can move under you mid-session.

5. LoanSet fee must be doubled by hand — autofill doesn't pay for the counterparty signature (P1)

What you expect. autofill() computes the correct fee for LoanSet.What actually happens. LoanSet requires two signatures — the lender’s and the borrower’s. autofill() computes the fee for one. The counterparty signature is a second signing operation that consumes additional fee. autofill warns about this but does not pay for it. The transaction fails at submission with an insufficient-fee error.Your fix. Double the fee before signing:

const prepared = await client.autofill(tx)
prepared.Fee = String(Number(prepared.Fee) * 2)

// Sign by both parties
const signed = wallet.sign(prepared)
const countersigned = counterpartyWallet.sign(signed.tx_blob, true)
await client.submitAndWait(countersigned.tx_blob)

6. OracleSet must bypass validate() — it rejects legal scale values (P1)

What you expect. validate() accepts a well-formed OracleSet transaction.What actually happens. xrpl.js validate() rejects OracleSet transactions carrying valid Scale values for non-price dimensions. The six Orma dimensions use AssetClass: "risk" and Scale values of 6 for NAV and 4 for the other five. validate() refuses them.Pass the transaction directly to the signing layer without calling validate():

// Do not call validate() — it rejects legal Scale values for risk dimensions
const signed = wallet.sign(tx)
await client.submitAndWait(signed.tx_blob)

Three additional OracleSet traps that corrupt data silently instead of erroring:

Not a merge. A (BaseAsset, QuoteAsset) pair already on the object but omitted from the transaction is kept with its AssetPrice stripped. Publishing one dimension blanks the other five. Always send the full six-dimension series.
LastUpdateTime must strictly increase. Equal or lower burns a fee and a sequence number. One update per second per object, maximum.
AssetPrice is hexadecimal. Writing "100" means 256. Use BigInt(n).toString(16).toUpperCase() to encode and BigInt("0x" + hex) to decode.

Reusing an OracleDocumentID for a different set of assets accumulates stale pairs until the series exceeds the ledger ceiling and OracleSet returns tecARRAY_TOO_LARGE. At that point nothing can be published to that document and the only recovery is delete and recreate.

7. DomainID lives on MPTokenIssuance, not on Vault (P2)

What you expect. Reading the Vault ledger entry tells you whether a vault is gated, because DomainID is a vault property.What actually happens. DomainID is not stored on the Vault ledger entry. It lives on the share MPTokenIssuance. Reading the Vault to check whether it is gated returns nothing — which reads exactly like “open to everyone”.

// Wrong: DomainID is not a Vault field
const domain = vaultNode.DomainID  // always undefined

// Right: read the share issuance via Vault.ShareMPTID
const iss = await client.request({
  command: 'ledger_entry',
  mpt_issuance: vaultNode.ShareMPTID,
})
const domain = iss.result.node.DomainID

tfVaultPrivate (0x00010000) is required on VaultCreate alongside DomainID. A DomainID without the flag gates nothing at all. The Orma API reports that case explicitly as "carries a domain but is not flagged private, so nothing is enforced" rather than presenting it as protected.Use GET /api/vaults/:vaultId/gate to verify a gate setup — it reads the issuance, not the Vault.

The full register covers 40 findings, 7 P0, 19 P1, 14 P2, plus three withdrawn after re-verification (listed rather than deleted). Every claim carries a transaction hash, a file and line, a verbatim error string, or a registry timestamp. Every hash resolves at https://devnet.xrpl.org/transactions/<hash>.

What was not tested

Stated so no one builds on claims that were not made.

Non-XRP vault assets. Everything above uses XRP, so Vault.Scale is 0 and all arithmetic is integer drops. With an IOU or MPT asset and a non-zero scale, precision and dust paths become active and several exact numbers will shift.
The min() clamps in the cover formula. In the four defaults tested, the double product was always far below both DefaultAmount and CoverAvailable, so only the first term ever bound.
LoanDelete, LoanBrokerDelete, VaultDelete, LoanBrokerCoverClawback, tfLoanFullPayment, and the fee and rate fields attached to loan closure.
OracleSet under a loaded ledger or a regular-key account. Devnet load_factor was 1 throughout.

Get Started

Core Concepts

Guides

Reference

XRPL Lending Protocol: Key Findings for Developers

Severity rubric

Findings

What was not tested

​Severity rubric

​Findings

​What was not tested

Severity rubric

Findings

What was not tested