Orma Method Reference: Formulas and Oracle Encoding

This page is the complete method reference — every formula Orma uses, the ledger fields it reads, and the source file that implements it. Use it to verify results or build your own implementation. Nothing here requires privileged access: every input is a public ledger field, and every figure the API serves names the ledger state it was computed from so you can recompute it yourself.

Symbols

Symbol	Meaning	Ledger field
$A$	Total assets held by the vault	`Vault.AssetsTotal`
$A_v$	Assets not currently lent out	`Vault.AssetsAvailable`
$L$	Loss recognised but not yet deducted	`Vault.LossUnrealized`
$S$	Units outstanding	`MPTokenIssuance.OutstandingAmount`
$D$	Broker’s total drawn debt	`LoanBroker.DebtTotal`
$C$	First-loss capital posted	`LoanBroker.CoverAvailable`
$c_{\min}$	Minimum cover rate	`LoanBroker.CoverRateMinimum`
$c_{\text{liq}}$	Liquidation cover rate	`LoanBroker.CoverRateLiquidation`
$p_i$	Principal of exposure $i$	`Loan.PrincipalOutstanding`

Units

All monetary fields are integer drops (1 XRP =

10^6

drops), carried as decimal strings of up to 19 significant digits. All arithmetic uses decimal.js at precision 40. Number() and parseFloat are never applied to a monetary value: 19 significant digits do not survive an IEEE-754 double, and BigInt("1e17") throws on the scientific notation rippled sometimes emits. The helper num() in src/num.mjs is the single place where “field absent” is coalesced to zero, because rippled omits any field equal to its type default.

Rate scale

c_{\min}

and

c_{\text{liq}}

are expressed in units of

10^{-5}

. A stated value of 10000 is therefore

0.10

— not

10000

and not

100

// src/num.mjs
export const RATE_SCALE = 100000
export const rateToDec = (r) => num(r).div(RATE_SCALE)

1. Net Asset Value, Two Ways

Orma computes and reports NAV two ways on every call — not to be thorough, but because the two numbers differ and one of them is silently wrong for any vault carrying an unrealised loss. The naive reading, which is what a metadata-diffing indexer computes:

\text{NAV}_{\text{naive}} = \frac{A}{S}

The correct reading, net of the loss the manager has already recognised:

\text{NAV}_{\text{held}} = \frac{A - L}{S}

Both are defined as zero when

S = 0

. Divergence is reported in basis points:

\delta = \operatorname{round}\!\left(10^{4} \cdot \frac{\text{NAV}_{\text{naive}} - \text{NAV}_{\text{held}}}{\text{NAV}_{\text{naive}}}\right)

\delta

is computed from the full-precision Decimal values, not from the rounded six-decimal strings. The integer conversion is a round, not a truncation: bps() in src/num.mjs calls toFixed(0), and Decimal.prototype.toFixed rounds half-up. On Calder Structured Credit III the exact value is

1960.78\ldots

bp, so the API reports 1961. A floor would report 1960. If you reimplement this and get 1960, that is the reason.

The whole computation is four lines of Reader.nav() in src/poll.mjs:

static nav(vault) {
  const { assetsTotal, lossUnrealized, sharesOutstanding: s } = vault
  const naive = s.isZero() ? new Decimal(0) : assetsTotal.div(s)
  const correct = s.isZero() ? new Decimal(0) : assetsTotal.minus(lossUnrealized).div(s)
  return {
    navNaive: naive.toFixed(6),
    navCorrect: correct.toFixed(6),
    navDivergenceBps: bps(naive, correct),
  }
}

Measured on Devnet. Calder Structured Credit III,

A = 51{,}000{,}000

drops,

L = 10{,}000{,}000

S = 51{,}000{,}000

\text{NAV}_{\text{naive}} = 1.000000

\text{NAV}_{\text{held}} = 0.803922

\delta = 1961

bp.

Why the naive figure is not merely lazy

rippled omits from PreviousFields any field whose previous value was the type default. On the first impairment of a healthy vault,

L

moves from

0

, so PreviousFields is emitted empty. Under cash-basis accounting (LEVersion = 1) an impairment changes nothing else on the Vault object. An indexer that diffs transaction metadata therefore observes no change at all on the vault it is watching. Captured from transaction 075FE6D2E0F29919AF477A2A8F581A680805A006138BB967D8434611E49229C3 (tesSUCCESS, Meridian Trade Finance I):

"vaultNode": {
  "previousFields": {},
  "finalFields": {
    "AssetsTotal": "51000000",
    "AssetsAvailable": "41000000",
    "LossUnrealized": "10000000"
  }
}

This is why Orma polls full object state every 4 seconds and never diffs PreviousFields. A diffing reader is not slightly late here — it is silent, until some later transaction happens to touch the same field for another reason. Reporting both NAV readings, with the gap named, lets a consumer see what a naive computation would have told them and decide for themselves.

2. First-Loss Cover

Cover required and cover shortfall

\text{cover\_required} = \lceil D \cdot c_{\min} \rceil

\text{cover\_shortfall} = \max\!\left(0,\; \text{cover\_required} - C\right)

Max liquidatable now

The amount of first-loss capital that can actually be liquidated in a single default event:

\text{max\_liquidatable} = \lceil D \cdot c_{\min} \cdot c_{\text{liq}} \rceil

Both rates are

10^{-5}

units, so both must be divided by

10^5

. At

c_{\min} = c_{\text{liq}} = 10000

the coefficient is

0.10 \times 0.10 = 0.01

. Dividing only once makes the answer 100 times too large.

Stranded cover fraction

Cover that has been posted but cannot currently be liquidated — it is frozen above the liquidation ceiling:

\text{stranded\_cover\_fraction} = \frac{\max\!\left(0,\; C - \text{max\_liquidatable}\right)}{C}

Defined as

0

when

C = 0

. The derivation in src/score.mjs:

// src/score.mjs  (inside deriveScoreInputs)
const cmin = D(o.broker.coverRateMinimum).div(100000)
const cliq = D(o.broker.coverRateLiquidation).div(100000)
// The DOUBLE PRODUCT. Both rates are 1e-5 units so BOTH are divided by 1e5.
const maxLiquidatableNow = debtTotal.times(cmin).times(cliq).ceil()
const coverRequired = debtTotal.times(cmin).ceil()
const coverShortfall = Decimal.max(0, coverRequired.minus(coverAvailable))
const strandedCoverFraction = coverAvailable.isZero()
  ? D(0)
  : Decimal.max(0, coverAvailable.minus(maxLiquidatableNow)).div(coverAvailable)

3. Cover Consumed on a Default

When a broker calls LoanManage with the DEFAULT flag, the ledger liquidates:

T(p) = \min\!\Big(\big\lceil D \cdot c_{\min} \cdot c_{\text{liq}} \big\rceil,\; p,\; C\Big)

Three properties of this formula, each of which matters:

The double product. Both rates are $10^{-5}$ units, so both are divided by $10^5$ (see above).
The result is ceilinged, not floored and not rounded.
The base is the broker’s total book $D$ , not the principal $p$ of the exposure that defaulted. The same loan defaulting inside a larger book liquidates more cover. $D$ is decremented as each default lands, so each successive default consumes less.

Implemented in coverForOrder() in src/history.mjs, which mirrors the ledger step by step:

// src/history.mjs
export function coverForOrder(principals, startingDebt, cmin, cliq, coverAvailable) {
  const c = num(cmin).div(100000).times(num(cliq).div(100000))
  let debt = num(startingDebt)
  let cover = num(coverAvailable)
  let total = new Decimal(0)
  for (const p of principals) {
    const want = debt.times(c).ceil()
    const paid = Decimal.min(want, num(p), cover)
    total = total.plus(paid)
    cover = cover.minus(paid)
    debt = Decimal.max(0, debt.minus(num(p)))
  }
  return total
}

Verified against LoanManage.cpp:146–169, with

D

decremented at line 248.

4. The Ordering Result

Because

D

is decremented as each default lands, each default shrinks the base for the next one. The total cover paid across a fixed set of losses therefore depends on the order they are declared in. Write

c = c_{\min} \cdot c_{\text{liq}}

and let

D_0

be the book at the moment of the first default. Declaring

k

defaults in the order

\sigma

consumes, while cover remains available and each

p_i

is large enough that the

\min

never binds:

T(\sigma, k) = c \left[ k D_0 - \sum_{i=1}^{k} (k - i)\, p_{\sigma(i)} \right]

Only the sum depends on

\sigma

. The coefficient

(k - i)

is decreasing in

i

, so by the rearrangement inequality the sum is maximised, and therefore

T

minimised, when

p_{\sigma(i)}

is decreasing. Hence:

Total first-loss capital consumed is minimised by declaring the largest exposure first, and maximised by declaring the smallest first.

The party who chooses

\sigma

is the LoanBroker owner, who is necessarily the vault owner (LoanBrokerSet.cpp:109), and is the party whose capital

C

is consumed. The difference lands on the unit holders.

The closed form drops the ceiling and the

\min

clamps, which is why it is stated with a proviso. Use the closed form to understand the result; use the simulation in coverForOrder() to compute it.

Measured on Devnet

Kestrel Bridge Financing II:

p = \{30\ \text{XRP},\ 10\ \text{XRP}\}

D_0 = 40\ \text{XRP}

c_{\min} = c_{\text{liq}} = 10000

Order	Step 1	Step 2	Total
Largest first (30 XRP, then 10 XRP)	$\lceil 40 \cdot 0.01 \rceil = 0.40\ \text{XRP}$	$\lceil 10 \cdot 0.01 \rceil = 0.10\ \text{XRP}$	0.50 XRP (500,000 drops)
Smallest first (10 XRP, then 30 XRP)	$\lceil 40 \cdot 0.01 \rceil = 0.40\ \text{XRP}$	$\lceil 30 \cdot 0.01 \rceil = 0.30\ \text{XRP}$	0.70 XRP (700,000 drops)

A 40% difference in what the first-loss capital absorbed, on identical losses. Three independent agreements: the iterative simulation in coverForOrder(), the closed form above, and the ledger itself.

Fairness score

Observed consumption placed between the two extremes:

\phi = \frac{T_{\text{observed}} - T_{\min}}{T_{\max} - T_{\min}}, \qquad \phi \in [0, 1]

\phi = 0.0000

is investor-worst (the sequence that minimised cover consumed, leaving the maximum loss for depositors).

\phi = 1.0000

is investor-best (the sequence that maximised cover consumed on the broker’s behalf).

\phi

is defined as

1

when

T_{\max} = T_{\min}

, meaning the ordering could not have changed anything.

// src/history.mjs  (inside analyseOrdering)
fairness: span.isZero() ? '1.0000' : actual.minus(worst).div(span).toFixed(4),

Read the JSON field names carefully before comparing. In GET /api/vaults/{id}/broker-history the score is the field fairness. worstPossible is the smallest cover number (largest-first order, worst for investors), and bestPossible is the largest. The names are from the investors’ point of view, not the arithmetic’s.

Reconstructed from ledger history alone for the Kestrel broker, which declared the 30 XRP loan first:

"ordering": {
  "applicable": true,
  "defaultCount": 2,
  "actualCoverPaid": "500000",
  "bestPossible": "700000",
  "worstPossible": "500000",
  "costToDepositors": "200000",
  "spread": "200000",
  "fairness": "0.0000",
  "fairOrder": ["10000000", "30000000"]
}

The 0.20 XRP of costToDepositors is depositor money. Reconstructing it required no privileged access.

5. Capital Destruction

Every other factor measures current exposure — and a realised loss leaves none behind. When a write-off settles, the asset is removed from AssetsTotal, the provision is released, and the book reads clean. Without an explicit memory term, a vault that just wrote off four-fifths of its portfolio would score identically to one that never lost a penny.

\rho = \max\!\left(0,\; \frac{S - A}{S}\right)

\rho

is measured against

A

(total assets), not against

A - L

(assets net of provision). An unrealised loss is a provision against an asset the vault still holds and may recover. Counting it against

\rho

would punish a manager for disclosing early — precisely the behaviour the rest of the system exists to reward. Only a write-off, which removes the asset from AssetsTotal outright, is permanent destruction.

Par is

1.0

for a closed-ended vault: subscription closes before any lending, so

S

is capital subscribed measured in asset units, and later subscribers join at the same unit value with no profit or loss yet accrued. This identity does not hold for an open-ended vault and

\rho

would need rethinking in that case.

// src/score.mjs  (inside deriveScoreInputs)
const realisedLossPct = shares.isZero() || assetsTotal.gte(shares)
  ? D(0)
  : shares.minus(assetsTotal).div(shares).times(100)

Measured. A vault that took 50 XRP, defaulted on 40, and holds 10.5:

\rho = 79\%

\Delta = -14

from AAA, composite B. Without this term the same vault scored AAA, identical to one that never lost a penny — and because the book sorts worst-first, the most damaged facility sorted last. That was observed on Devnet, not hypothesised.

6. Composite Grade by Ordinal Notching

Orma grades are ordinal and rule-based, never a weighted sum. A weighted average lets a strong factor compensate for a broken one — and that is not the question an investor is asking.

The ladder

Let

\mathcal{L} = [\text{AAA}, \text{AA+}, \ldots, \text{D}]

|\mathcal{L}| = 20

, ordered best to worst, and

\text{idx}(g)

the position of grade

g

\text{notch}(g, \Delta) = \mathcal{L}\big[\operatorname{clamp}(\text{idx}(g) - \Delta,\; 0,\; 19)\big]

// src/score.mjs
export const LADDER = ['AAA', 'AA+', 'AA', 'AA-', 'A+', 'A', 'A-', 'BBB+', 'BBB', 'BBB-',
                       'BB+', 'BB', 'BB-', 'B+', 'B', 'B-', 'CCC', 'CC', 'C', 'D']

export const notch = (grade, delta) =>
  LADDER[Math.min(LADDER.length - 1, Math.max(0, LADDER.indexOf(grade) - delta))]

export const gradeNumeric = (g) =>
  Math.round((1 - LADDER.indexOf(g) / (LADDER.length - 1)) * 100)

A negative

\Delta

is a downgrade. The ladder runs best to worst, so a worse grade is a higher index — hence the minus sign.

Dimension bands

Each dimension maps its raw value to an initial band grade before any notching. Bands are evaluated top to bottom; the first threshold the value reaches wins, and D if none does.

LIQUIDITY — AssetsAvailable / AssetsTotal

Threshold	Grade
$\ge 0.95$	AAA
$\ge 0.85$	A
$\ge 0.70$	BBB
$\ge 0.50$	BB
$\ge 0.25$	B
$\ge 0.05$	CCC
otherwise	D

Defined as

1

when

A = 0

COVER — first-loss adequacy

\text{adequacy} = \frac{\min\!\big(\lceil D \cdot c_{\min} \cdot c_{\text{liq}} \rceil,\; C\big)}{\max\!\big(L,\; P_{\text{distressed}}\big)}

The denominator takes the larger of the recognised loss and the distressed principal. Dividing by

L

alone would grade a vault concealing a large overdue exposure as perfectly covered. Concealment must never improve a score.

Threshold	Grade
$\ge 1$	AA
$\ge 0.5$	A-
$\ge 0.2$	BBB-
$\ge 0.05$	BB-
$\ge 0.01$	B-
otherwise	D

Defined as

1

when the denominator is zero (no exposure to absorb).

CONCENT — concentration

Graded on

1 - \text{concentration}

, where

\text{concentration} = \max_i(p_i) / D

Threshold (on $1 -$ concentration)	Grade
$\ge 0.8$	AA
$\ge 0.6$	A-
$\ge 0.4$	BBB-
$\ge 0.2$	BB-
otherwise	D

Note: the API reports concentration raw (higher is worse) with worseIsHigher: true. The grading is done internally on the complement.

RECOG — recognition lag

A direct cut on seconds, not a ratio:

Threshold	Grade
$\le 0$	AAA
$< 60$ s	A
$< 300$ s	BBB
$< 900$ s	BB
otherwise	CCC

recogLagSeconds is the maximum seconds any loan with status overdue or defaultable has been overdue without being declared, floored at zero.

DEADLINE — redemption cliff

\text{shortfall} = \max\!\Big(0,\; (A - L) - \big(A_v + R_{\text{performing}} + [P_{\text{distressed}} > 0] \cdot C_{\text{rec}}\big)\Big)

where

R_{\text{performing}}

is the total contractual repayment of performing loans (status current or due_soon) and

C_{\text{rec}} = \min\!\big(\lceil D \cdot c_{\min} \cdot c_{\text{liq}} \rceil,\ C\big)

.Graded on

1 - \text{shortfall\%}/100

Threshold	Grade
$= 1$ (0% shortfall)	AAA
$\ge 0.98$	AA
$\ge 0.90$	A
$\ge 0.75$	BBB
$\ge 0.50$	BB
$\ge 0.25$	B
$\ge 0.10$	CCC
otherwise	D

rippled refuses any LoanSet whose maturity overruns the vault’s RedemptionDate, so every performing loan is contractually repaid before redemption. A projected shortfall is therefore exactly the non-performing book net of recoverable cover. Being fully lent is not a distress signal.

Notch rules

The composite anchors on DEADLINE — for a fixed-term facility the headline question is whether claims can be met at redemption — then notches from there:

Condition	$\Delta$
Realised capital destruction $\ge 75\%$	$-14$
Realised capital destruction $\ge 50\%$	$-12$
Realised capital destruction $\ge 25\%$	$-8$
Realised capital destruction $\ge 10\%$	$-5$
Realised capital destruction $\ge 2\%$	$-3$
Realised capital destruction $> 0\%$	$-1$
Recognition lag $> 300$ s	$-2$
Recognition lag $> 0$ s	$-1$
Largest exposure $\ge 75\%$ of the book	$-1$
Liquidatable cover $< 5\%$ of recognised loss	$-1$
In Redemption phase with liquidity exhausted	$-2$

The two recognition-lag rules are exclusive (the larger wins). The realised-destruction bands are also exclusive. Every notch applied is emitted in notchTrace on the API response, with from, rule, delta, and to. That trace is the answer to “how did you choose your weights” — there are no weights, there are notches, and each one is named.

Worked example — Calder Structured Credit III

A = 51{,}000{,}000

A_v = 41{,}000{,}000

L = 10{,}000{,}000

S = 51{,}000{,}000

D = 10{,}000{,}000

C = 5{,}000{,}000

c_{\min} = c_{\text{liq}} = 10000

, one impaired loan of

p = 10{,}000{,}000

, phase: Investment.

Step	Value	Grade
Liquidity	$41/51 = 0.8039$	BBB
Liquidatable cover	$\lceil 10{,}000{,}000 \times 0.01 \rceil = 100{,}000$	—
Cover adequacy	$100{,}000 / \max(10{,}000{,}000,\ 10{,}000{,}000) = 0.0100$	B-
Concentration	$10{,}000{,}000 / 10{,}000{,}000 = 1.0000$	D
Recognition lag	0 s (loan already declared impaired)	AAA
Claims	$51{,}000{,}000 - 10{,}000{,}000 = 41{,}000{,}000$	—
Liquidity at redemption	$41{,}000{,}000 + 0 + 100{,}000 = 41{,}100{,}000$	—
Shortfall	$\max(0,\ 41{,}000{,}000 - 41{,}100{,}000) = 0,\ \text{so}\ 0.00\%$	AAA

Notching: anchor AAA.

\rho = 0

because

A \ge S

, no capital-destruction notch. Concentration

1.0 \ge 0.75

-1

→ AA+. Adequacy

0.0100 < 0.05

-1

→ AA. Numeric:

\operatorname{round}(100 \cdot (1 - 2/19)) = 89

7. Conduct Score

The conduct score is a separate ordinal assessment of the manager, not of the book. It starts at 100 and is clamped to

[0, 100]

Observation	Penalty
$\phi < 0.25$ — sequence close to investor-worst order	$-35$
$0.25 \le \phi < 0.75$ — mixed ordering	$-15$
A loss written off with no prior impairment	$-20$ each
A withdrawal of first-loss capital	$-10$ each

Mapped to letter grades:

A \ge 90

B \ge 75

C \ge 55

D \ge 35

E

below.

// src/history.mjs  (inside reputation)
score = Math.max(0, Math.min(100, score))
const grade = score >= 90 ? 'A' : score >= 75 ? 'B' : score >= 55 ? 'C' : score >= 35 ? 'D' : 'E'

Measured on Devnet. The Kestrel broker scores

100 - 35 - (2 \times 20) = 25

, grade E: it declared the largest loan first (fairness

0.0000

), and neither loan was impaired before it was written off.

Finding codes

ORDERING_SELF_SERVING

Declared losses in an order close to the one that minimises the broker’s own first-loss contribution (fairness score

< 0.25

). The choice cost investors the difference between actualCoverPaid and bestPossible.

DEFAULT_WITHOUT_IMPAIRMENT

An exposure was written off with no prior impairment — the loss went straight from invisible to realised, with no window for anyone to react. Penalty

-20

per occurrence.

COVER_WITHDRAWN

A withdrawal of first-loss capital is on record. Cover taken out ahead of a deteriorating book is the pattern that preceded losses at Maple Finance in 2022. Penalty

-10

per withdrawal.

Reconstructing this history requires a join that is not obvious. LoanManage carries no LoanBrokerID, only LoanID, and an impairment does not touch the LoanBroker object at all. Matching on the broker node or a transaction field alone silently drops every impairment. Loan.FinalFields.LoanBrokerID in the same metadata closes the join at no extra request. Without that join, every default looks unsignalled — and a rule written to reward disclosure ends up penalising it.

Devnet prunes account history to roughly 29 days, so the conduct score covers a window, not a lifetime. The API says so in a caveat field on the reputation block of GET /api/vaults/{id}/broker-history.

8. Pledge Valuation

For

u

units pledged as collateral, Orma reports both readings so a lender can see what a naive computation would have told them:

V_{\text{reported}} = u \cdot \text{NAV}_{\text{naive}}

V_{\text{held}} = u \cdot \text{NAV}_{\text{held}}

\text{overstatement} = V_{\text{reported}} - V_{\text{held}}

A lender’s own haircut

h

applies to the honest value, not the reported one:

V_{\text{lendable}} = V_{\text{held}} \cdot (1 - h)

A haircut absorbs volatility. It does not absorb a misstatement. A 20% haircut applied to a value that is 19.61% overstated leaves the lender roughly where they thought they were starting.

Measured.

u = 1{,}000{,}000

units against

\text{NAV}_{\text{held}} = 0.803922

: reported

1.000000\ \text{XRP}

, held

0.803922\ \text{XRP}

, overstatement

0.196078\ \text{XRP}

. Two functions compute this, with deliberately different field names because they answer different questions:

valuePledge (nav.mjs)
valuePledge (collateral.mjs)

Behind GET /api/mpt/{issuanceId}/nav?units=N. Takes a NAV document and a unit count; returns units, valueHeld, valueReported, overstatement. Returns an unpriced string rather than throwing when the document carries no unitValue, because a lender’s collateral tool must be able to say “I could not value this” rather than crash.

// src/nav.mjs
export function valuePledge(nav, units) {
  const uv = nav?.unitValue
  if (!uv || uv.held === undefined || uv.reported === undefined) {
    return {
      units: num(units).toFixed(0),
      valueHeld: null,
      valueReported: null,
      overstatement: null,
      unpriced: 'the document at the pointer carries no unitValue, so this pledge cannot be valued',
    }
  }
  const u = num(units)
  const held = u.times(num(uv.held))
  const reported = u.times(num(uv.reported))
  return {
    units: u.toFixed(0),
    valueHeld: held.toFixed(0),
    valueReported: reported.toFixed(0),
    overstatement: reported.minus(held).toFixed(0),
  }
}

Behind GET /api/vaults/{id}/collateral. Takes vault collateral state; returns shares, valueNaive, valueCorrect, overstatement, overstatementPct, plus maxLendable after the caller’s haircut query parameter.Both functions multiply the published six-decimal NAV strings, so a pledge value is reproducible to the drop from the API document alone.

9. Oracle Encoding (XLS-47)

Orma publishes six PriceData entries per vault as a native XLS-47 Price Oracle — one per dimension. The base asset is derived from the vault ID; the quote asset is the dimension code.

Code	Dimension	Scale
`NAV`	Loss-adjusted assets per unit	6
`HDL`	Composite grade, numeric, divided by 100	4
`LIQ`	Liquidity ratio	4
`COV`	First-loss adequacy	4
`CNC`	Concentration (raw — higher is worse)	4
`DDL`	Redemption cliff, percent divided by 100	4

Everything except NAV is clamped to

[0, 1]

. NAV is a price and may exceed 1. A stored value

v

at scale

s

decodes to

v \cdot 10^{-s}

. AssetPrice is a UInt64 serialised as hexadecimal, so writing "100" means 256, not one hundred:

// src/oracle.mjs
export const encodePrice = (n) => BigInt(n).toString(16).toUpperCase()
export const decodePrice = (hex) => BigInt(`0x${hex}`)

The base asset uses the first 40 hex characters of the vault ID, with the leading byte forced non-zero:

// src/oracle.mjs
export function vaultToBaseAsset(vaultId) {
  let hex = vaultId.replace(/^0x/i, '').toUpperCase().slice(0, 40).padEnd(40, '0')
  if (/^0{2}/.test(hex)) hex = 'A' + hex.slice(1)
  return hex
}

Two traps motivate that last line: an all-zero currency code means XRP, and a code whose bytes 12–14 spell ASCII is rendered back by rippled as a three-character ticker symbol rather than a hex string.

Decoded from a live oracle object

Oracle object 03C7B0E151129510F11FF92CCE8FBB3E7AD3C55B25EDA6EB414324E3E995078A, document id 3, for Calder Structured Credit III:

Code	Raw hex	Scale	Decoded	Check
`NAV`	`c4452`	6	0.803922	$\text{0xC4452} = 803922$
`HDL`	`22c4`	4	0.8900	$\text{0x22C4} = 8900$ ; grade 89 over 100
`LIQ`	`1f67`	4	0.8039	$\text{0x1F67} = 8039$
`COV`	`64`	4	0.0100	$\text{0x64} = 100$
`CNC`	`2710`	4	1.0000	$\text{0x2710} = 10000$
`DDL`	`0`	4	0.0000	Shortfall is zero

Four publication invariants

Each of these corrupts data silently rather than erroring:

OracleSet is not a merge

A pair already on the object but omitted from the transaction is kept with its AssetPrice and Scale stripped. Publishing one dimension blanks the other five. The publisher always resends all six. There is also no way to remove a pair, so reusing a document ID for a different set of assets accumulates stale pairs until OracleSet returns tecARRAY_TOO_LARGE. The only recovery path is OracleDelete then recreate. Document IDs come from an explicit table, never from a hash of the vault ID, because the ID is a UInt32 scoped to (account, ID) and a collision would silently overwrite another vault’s scores.

LastUpdateTime must strictly increase

Equal or lower gives tecINVALID_UPDATE_TIME, burning a fee and a sequence number. The publisher uses ledger close time clamped to Date.now() and skips a tick rather than post ahead of the clock.

LastUpdateTime in the future bricks the object

A LastUpdateTime in the future bricks the object until wall clock catches up. Never add a safety margin.

AssetPrice is hex, not decimal

AssetPrice is a UInt64 serialised as hexadecimal. Writing the decimal string "803922" would be interpreted as hex

803922_{16} = 8,404,258

, giving a NAV nine orders of magnitude too large. Always encode with BigInt(n).toString(16).toUpperCase().

LastUpdateTime is UNIX epoch, not Ripple epoch.

XLS-47 is live on Mainnet today, unlike the lending amendments. get_aggregate_price computes a median and standard deviation across independent publishers inside the ledger — that is the point of publishing here rather than serving a number over HTTP. A second publisher who disagrees changes the aggregate without asking Orma’s permission. Orma reports aggregate: null honestly while it is the only publisher.

Checking This Yourself

Start from the valuation document, which names the ledger state it was computed from precisely so you do not have to trust it:

curl -s http://localhost:8787/api/vaults/5763707D11EA19D1B5FF04E4EBA4F9336057955CDE65B725D1FF3EF2A96CB0E5/nav

{
  "unitValue": {
    "held": "0.803922",
    "reported": "1.000000",
    "divergenceBps": 1961,
    "basis": "assets net of recognised loss, divided by units outstanding"
  },
  "provenance": {
    "network": "devnet",
    "source": "devnet",
    "assetsTotal": "51000000",
    "lossUnrealized": "10000000",
    "unitsOutstanding": "51000000",
    "recompute": "(assetsTotal - lossUnrealized) / unitsOutstanding",
    "buildVersion": "3.4.0-rc5"
  }
}

Recompute both readings and the divergence from those three strings in decimal arithmetic, not in floats:

import Decimal from 'decimal.js'
Decimal.set({ precision: 40 })

const p = {
  assetsTotal:    '51000000',
  lossUnrealized: '10000000',
  unitsOutstanding: '51000000',
}
const A = new Decimal(p.assetsTotal)
const L = new Decimal(p.lossUnrealized)
const S = new Decimal(p.unitsOutstanding)

const naive = A.div(S)               // 1
const held  = A.minus(L).div(S)      // 0.80392156862745098039...
const bps   = naive.minus(held).div(naive).times(10000)

console.log(naive.toFixed(6), held.toFixed(6), Number(bps.toFixed(0)))
// 1.000000  0.803922  1961

Then verify the provenance against the ledger directly — the step that makes the exercise non-circular:

import { Client } from 'xrpl'

const client = new Client('wss://s.devnet.rippletest.net:51233')
await client.connect()
// Note: the parameter is vault_id, not vault (see XLS-65 section 3.9.1)
const r = await client.request({
  command: 'vault_info',
  vault_id: '5763707D11EA19D1B5FF04E4EBA4F9336057955CDE65B725D1FF3EF2A96CB0E5',
})
console.log(r.result.vault.AssetsTotal, r.result.vault.LossUnrealized)
await client.disconnect()

AssetsTotal and LossUnrealized should equal provenance.assetsTotal and provenance.lossUnrealized as of the ledgerIndex on the response envelope. If LossUnrealized is absent, that means zero — rippled omits any field equal to its type default, which is the same rule that makes the first impairment invisible to a diffing indexer.

Verify the grade

Every notch is in notchTrace on GET /api/vaults/{id}, with the grade before and after. Walk it against the band tables in Section 6 and the notch rules table.

Verify the cover arithmetic

GET /api/vaults/{id}/broker-history lists every default with debtBefore and coverConsumed. Check each against

\lceil D \cdot c_{\min} \cdot c_{\text{liq}} \rceil

using the rates on the broker, then check the total against coverForOrder() run over the same principals in both extreme orders.

Verify the oracle

Fetch the object by its index on the Devnet explorer and decode AssetPrice yourself with BigInt('0x' + raw) divided by

10^{\text{Scale}}

. It should agree with the API to the last digit, because both come from the same snapshot.

Everything on this page runs on Devnet at wss://s.devnet.rippletest.net:51233 (network ID 2), because XLS-65 vaults and XLS-66 lending are not yet on Mainnet. The oracle publication via XLS-47 is the one component with a production path today.

Get Started

Core Concepts

Guides

Reference

Orma Method Reference: Formulas and Oracle Encoding

Symbols

Units

Rate scale

1. Net Asset Value, Two Ways

Why the naive figure is not merely lazy

2. First-Loss Cover

Cover required and cover shortfall

Max liquidatable now

Stranded cover fraction

3. Cover Consumed on a Default

4. The Ordering Result

Measured on Devnet

Fairness score

5. Capital Destruction

6. Composite Grade by Ordinal Notching

The ladder

Dimension bands

Notch rules

Worked example — Calder Structured Credit III

7. Conduct Score

Finding codes

8. Pledge Valuation

9. Oracle Encoding (XLS-47)

Decoded from a live oracle object

Four publication invariants

Checking This Yourself

​Symbols

​Units

​Rate scale

​1. Net Asset Value, Two Ways

​Why the naive figure is not merely lazy

​2. First-Loss Cover

​Cover required and cover shortfall

​Max liquidatable now

​Stranded cover fraction

​3. Cover Consumed on a Default

​4. The Ordering Result

​Measured on Devnet

​Fairness score

​5. Capital Destruction

​6. Composite Grade by Ordinal Notching

​The ladder

​Dimension bands

​Notch rules

​Worked example — Calder Structured Credit III

​7. Conduct Score

​Finding codes

​8. Pledge Valuation

​9. Oracle Encoding (XLS-47)

​Decoded from a live oracle object

​Four publication invariants

​Checking This Yourself

Symbols

Units

Rate scale

1. Net Asset Value, Two Ways

Why the naive figure is not merely lazy

2. First-Loss Cover

Cover required and cover shortfall

Max liquidatable now

Stranded cover fraction

3. Cover Consumed on a Default

4. The Ordering Result

Measured on Devnet

Fairness score

5. Capital Destruction

6. Composite Grade by Ordinal Notching

The ladder

Dimension bands

Notch rules

Worked example — Calder Structured Credit III

7. Conduct Score

Finding codes

8. Pledge Valuation

9. Oracle Encoding (XLS-47)

Decoded from a live oracle object

Four publication invariants

Checking This Yourself