Conversion Operations | Centrifuge

No network call: Both operations on this page are pure arithmetic — no Substrate RPC, no chain-state dependency. They work identically regardless of network status.

convertUnits

Converts an amount between a currency's base units (the smallest indivisible unit — "Planck", by analogy with Polkadot's terminology) and its display units (whole tokens with a fractional part).

Field	Type	Required	Description
`amount`	text	✓ Yes	The value to convert, as a plain decimal string (e.g. `"2.5"` or `"2500000000000000000"`).
`fromUnit`	select	✓ Yes	`base` / `planck` / `baseunits` (all synonyms) or `display`.
`toUnit`	select	✓ Yes	Same set as `fromUnit`. Must differ in base-vs-display sense from `fromUnit`.
`decimals`	number	✓ Yes	0–38. The currency's decimal precision — never assumed. See Currencies & Units.

Example — convert 2.5 CFG (18 decimals) to base units:

// Request
{ "amount": "2.5", "fromUnit": "display", "toUnit": "base", "decimals": 18 }

// Response
{ "inputAmount": "2.5", "outputAmount": "2500000000000000000", "fromUnit": "display", "toUnit": "base", "decimals": 18 }

Truncates, never rounds. Converting display → base with more fractional digits than decimals allows truncates the excess rather than rounding — silently rounding a money amount upward without being asked is worse than losing an unrepresentable fraction. All arithmetic uses arbitrary-precision BigInteger, since 18-decimal balances routinely exceed what a double can represent exactly.

convertRate

Converts between a human-facing Annual Percentage Rate and the per-second RAY fixed-point rate Centrifuge stores on-chain for loan interest.

Field	Type	Required	Description
`rate`	text	✓ Yes	The rate to convert — an APR percentage (e.g. `"5.25"` for 5.25%) or a RAY per-second integer string, depending on `direction`.
`direction`	select	✓ Yes	`aprToPerSec` or `perSecToApr`.

Example — convert 5% APR to a per-second RAY rate:

// Request
{ "rate": "5", "direction": "aprToPerSec" }

// Response
{ "inputRate": "5", "outputRate": "1000000001547125957", "direction": "aprToPerSec" }

Why RAY, and why per second? Centrifuge stores loan interest as a per-second growth factor in RAY fixed-point (10²⁷) — a value slightly above 1.0 that, compounded every second for a year, yields the configured APR. No workflow author will hand-compute that value, so this operation does the conversion using the same linear approximation Centrifuge's own tooling uses: perSecondRay = RAY + (aprFraction ÷ secondsPerYear) × RAY, with secondsPerYear = 365 × 24 × 60 × 60 (a non-leap year, matching Centrifuge's own convention).

The reverse direction, perSecToApr, recovers the APR from a RAY rate and is rejected (VAL_INVALID_INTEREST_RATE) if the input is below RAY itself — a rate under 1.0 would imply negative interest, which this node doesn't treat as a valid loan configuration.