Xahau Network
Testnet FaucetExplorerHooks API Docs
Xahau Network
Xahau Network
  • 🪝Xahau Documentation
    • XRPL/Xahau: What is Different?
  • 🪝Hooks
  • 🚨Concepts
    • Introduction
      • Example Usage
      • Xahau Testnet
      • Xahau Testnet Explorer
      • Examples (source code)
      • Blogs (concepts)
    • Terminology
    • Loops and Guarding
    • Compiling Hooks
    • Chaining
    • Weak and Strong
    • Collect Call
    • SetHook Transaction
    • Parameters
    • Namespaces
    • Grants
    • HookOn Field
    • Reference Counted Hook Definitions
    • Hook Fees
    • Execution Metadata
    • Debugging Hooks
    • State Management
    • Slots and Keylets
    • Floating Point Numbers (XFL)
    • Emitted Transactions
    • Serialized Objects
  • Features
    • Public Nodes (RPC)
    • Amendments
    • Transaction Signing
      • Transaction Fees
    • Developer Tooling
      • Curated Tooling
      • Client Libraries
      • Developer Tricks
    • HTTP / WebSocket APIs
      • Request Formatting Guide
      • Response Formatting Guide
      • Considerations
      • Public API Methods
      • Admin API Methods
    • Network Features
      • Account Managment
      • Balance Rewards
      • Check
      • Escrow
      • Hooks
      • Offer
      • Payments
      • URIToken
    • Faucet & Explorers
    • Data API's
  • Infrastructure
    • Node Requirements
    • Running a Node
      • Running a Mainnet Node
      • Running a Testnet Node
    • Building Xahau (Dev)
      • Ubuntu - 22.04
      • Mac OS - 15.3.2 (24D81)
  • Technical
    • 📐Hooks Functions
      • Overview
        • Hook API Conventions
        • Return Codes
      • Developer Defined
        • hook
        • cbak / Callback
      • Control
        • accept
        • rollback
      • Utilities
        • util_raddr
        • util_accid
        • util_verify
        • util_sha512h
        • util_keylet
      • Serialization
        • sto_subfield
        • sto_to_json
        • sto_from_json
        • sto_subarray
        • sto_emplace
        • sto_erase
        • sto_validate
      • Emitted Transaction
        • etxn_burden
        • etxn_details
        • etxn_fee_base
        • etxn_nonce
        • etxn_reserve
        • etxn_generation
        • prepare
        • emit
      • Float
        • float_set
        • float_multiply
        • float_mulratio
        • float_negate
        • float_compare
        • float_sum
        • float_sto
        • float_sto_set
        • float_invert
        • float_divide
        • float_one
        • float_exponent
        • float_mantissa
        • float_sign
        • float_int
        • float_root
        • float_log
      • Ledger
        • fee_base
        • ledger_seq
        • ledger_last_hash
        • ledger_last_time
        • ledger_nonce
        • ledger_keylet
      • Hook Context
        • hook_account
        • hook_hash
        • hook_param
        • hook_param_set
        • hook_skip
        • hook_pos
        • hook_again
      • Slot
        • slot
        • slot_clear
        • slot_count
        • slot_set
        • slot_size
        • slot_subarray
        • slot_subfield
        • slot_type
        • xpop_slot
        • slot_float
      • State
        • state
        • state_set
        • state_foreign
        • state_foreign_set
      • Trace (Debug)
        • trace
        • trace_num
        • trace_float
      • Originating Transaction
        • otxn_burden
        • otxn_field
        • otxn_generation
        • otxn_id
        • otxn_type
        • otxn_slot
        • otxn_param
        • otxn_json
        • meta_slot
      • Websocket APIs
        • account_info
        • account_namespace
    • Protocol Reference
      • Transactions
        • Transaction Common Fields
        • Transaction Types
          • AccountDelete
          • AccountSet
          • CheckCancel
          • CheckCash
          • CheckCreate
          • ClaimReward
          • DepositPreauth
          • EscrowCancel
          • EscrowCreate
          • EscrowFinish
          • GenesisMint - (Emitted Txn)
          • Import
          • Invoke
          • OfferCancel
          • OfferCreate
          • Payment
          • PaymentChannelClaim
          • PaymentChannelCreate
          • PaymentChannelFund
          • Remit
          • SetHook
          • SetRegularKey
          • SignerListSet
          • TicketCreate
          • TrustSet
          • URITokenBurn
          • URITokenBuy
          • URITokenCancelSellOffer
          • URITokenCreateSellOffer
          • URITokenMint
        • Pseudo Transaction Types
          • EmitFailure
          • UNLReport
          • UNLModify
          • SetFee
          • EnableAmendment
        • Transaction Results
          • TES Codes
          • TER Codes
          • TEM Codes
          • TEL Codes
          • TEF Codes
          • TEC Codes
        • Transaction Metadata
      • Ledger Data
        • Ledger Objects Types
          • AccountRoot
          • Amendments
          • Check
          • Deposit Pre Auth
          • Directory Node
          • Emitted Txn
          • Escrow
          • Fee Settings
          • Hook
          • Hook Definition
          • Hook State
          • Import VL Sequence
          • Ledger Hashes
          • Negative UNL
          • Offer
          • Pay Channel
          • Ripple State
          • Signers List
          • Ticket
          • UNL Report
          • URIToken
        • Ledger Header
        • Ledger Object IDs
      • Data Types
        • Currency Formats
        • Base 58 Encodings
      • Binary Format
    • Balance Adjustments
    • Governance Game
    • Burn 2 Mint (B2M)
    • Versioning Process
  • Compliance
    • Security Audits
      • Responsible Disclosure
  • Support
    • Help Us
Powered by GitBook
On this page
  • Background
  • What is XFL?
  • Canonical Zero
  • Hook Float API
  • Example

Was this helpful?

Edit on GitHub
Export as PDF
  1. Concepts

Floating Point Numbers (XFL)

High precision calculations are native to Hooks.

Last updated 4 months ago

Was this helpful?

Background

are widely used in computer science to do calculation of finite precision but arbitrary scale numbers.

Most modern CPUs are capable of performing fast floating point operations using the however xahaud does not use this format. Instead Xahau uses a .

This custom format has three basic properties:

  1. The format is inherently decimal, expressed as a decimal mantissa multipled by 10 to the power of an exponent.

  2. All values expressed have 16 significant (decimal) figures.

  3. The range of exponents is -96 to +80

When serialized the mantissa is 54 bits, and the exponent is 8 bits, with a final sign bit bringing the total size of the serialized floating point to 63 bits.

What is XFL?

is an XRPL standards proposal that defines an efficient way to pack and store xrpld floating point numbers (as described above).

XFLs store the bits of the floating point number within an enclosing number. This is always an int64_t. Negative enclosing numbers represent invalid XFLs (for example as a result of division by zero.)

📘 Hint

Use the XFL-tool to compose and decompose XFLs in your browser!

Some example XFLs follow

loating Point Value
Enclosing Number
Representation

-1

1478180677777522688

-1000000000000000 * 10^(-15)

0

0

0 (canonical zero)

1

6089866696204910592

+1000000000000000 * 10^(-15)

PI

6092008288858500385

+3141592653589793 * 10^(-15)

-PI

1480322270431112481

-3141592653589793 * 10^(-15)

This format is very convenient for Hooks, as Hooks can only exchange integer values with xrpld. By enclosing the floating point inside an integer in a well defined way it becomes possible to do complex floating point computations from a Hook. This is useful for computing exchange rates.

Canonical Zero

Floating point regimes typically have a number of different ways to express zero, which can be a problem for testing for zero. For example 0 x 10 ^ 1 is zero and 0 x 10 ^ 2 is also zero. For this reason there is a canonical zero enforced by the standard and the Hook API. The canonical zero is also enclosing number zero (0).

Hook Float API

Once you have an XFL you can use the Float API to do various computations. The Float API appears in the table below. Each API takes one or more XFL enclosing numbers and returns an XFL enclosing number. Negative return values always represent a computational error (such as division by zero). There are no valid negative enclosing numbers.

Hook API
What it does

Create a float from an exponent and mantissa

Multiply two XFL numbers together

Multiply an XFL floating point by a non-XFL numerator and denominator

Negate an XFL floating point number

Perform a comparison on two XFL floating point numbers

Add two XFL numbers together

Output an XFL as a serialized object

Read a serialized amount into an XFL

Divide one by an XFL floating point number

Divide an XFL by another XFL floating point number

Return the number 1 represented in an XFL enclosing number

Get the exponent of an XFL enclosing number

Get the mantissa of an XFL enclosing number

Get the sign of an XFL enclosing number

float_exponent_set

Set the exponent of an XFL enclosing number

float_mantissa_set

Set the mantissa of an XFL enclosing number

float_sign_set

Set the sign of an XFL enclosing number

Convert an XFL floating point into an integer (floor)

Compute the nth root of an XFL

Compute the decimal log of an XFL

❗️ Warning

You should never do any direct math or comparison on the enclosing number. This will almost always result in incorrect computations.

The sole exception is checking for canonical zero.

Example

In the below example an exchange rate conversion is performed, followed by a high precision fraction multiplication.

int64_t max_vault_pusd =
    float_multiply(vault_xrp, exchange_rate);

max_vault_pusd = 
    float_mulratio(max_vault_pusd, 0,
        NEW_COLLATERALIZATION_NUMERATOR, NEW_COLLATERALIZATION_DENOMINATOR);

🚧 Tip

If a float API returns a negative value and you do no check for negatives then feeding that negative value into another float API will also produce a negative value. In this way errors are propagated much as NaN (not a number) is propagated in other languages.

If you ever end up with a negative enclosing number an error occured somewhere in your floating point calculations.

🚨
Floating point numbers
IEEE binary floating point standard
bespoke decimal floating point standard
XLS-17d
here
float_set
float_multiply
float_mulratio
float_negate
float_compare
float_sum
float_sto
float_sto_set
float_invert
float_divide
float_one
float_exponent
float_mantissa
float_sign
float_int
float_root
float_log