XRPL Data Architecture What's Actually on the Ledger

The XRP Ledger isn't a single document—it's a sequence of versioned states, each called a "ledger" or "ledger version."

The Ledger Chain:

Ledger 1 → Ledger 2 → Ledger 3 → ... → Ledger N (current)
     ↓           ↓           ↓                  ↓
   State       State       State             State
   at t₁       at t₂       at t₃             at tₙ

Key fields in the ledger header:

LEDGER HEADER (Analytically Relevant):

ledger_index: Sequential number (e.g., 85,000,000)
  - Use: Reference point for historical queries
  - Note: Ledger index increases continuously

close_time: Unix timestamp of ledger close
  - Use: Timing analysis, correlating with external events
  - Note: ~3-5 seconds between ledgers

total_coins: Total XRP in existence (drops)
  - Use: Tracking XRP burned as fees
  - Note: Started at 100B XRP, decreases slowly

transaction_hash: Hash of transaction set
  - Use: Verification, not direct analysis

account_hash: Hash of state tree
  - Use: Verification, not direct analysis

Analytical implication:

The ledger chain provides a complete history with precise timestamps. You can query any historical state—"What was address X's balance at ledger 80,000,000?" This enables time-series analysis that would be impossible in traditional finance without special data access.

Understanding when data becomes "final" matters for analysis:

1. Validators propose transactions
2. Multiple rounds of voting occur
3. 80%+ agreement finalizes the ledger
4. Ledger "closes" and becomes immutable

• Ledgers close every 3-5 seconds
• Data is near-real-time (not truly instant)
• Once closed, data is permanent

Analytical implication:

On-chain analysis typically works with closed ledgers (finalized data). For real-time monitoring, you might watch pending transactions, but most analysis uses confirmed, closed-ledger data.

Not all XRPL nodes store all data:

• Store every ledger version back to genesis

• Required for deep historical analysis

• Resource-intensive to operate

• Limited number exist

• Store recent ledgers only (rolling window)

• Sufficient for current state queries

• More common

Analytical implication:

• Access to full history node/API
• Archived data from analytics providers
• Pre-downloaded historical datasets

Most public APIs provide substantial history, but verify coverage for your analytical needs.

---

Every address on XRPL has an associated AccountRoot object containing core data:

ACCOUNT ROOT OBJECT:

Account: The address (e.g., "rN7n3473SaZBCG4dFL83w7...")
  - Analysis: Unique identifier for tracking

Balance: XRP holdings in drops (1 XRP = 1,000,000 drops)
  - Analysis: Core for wealth distribution, whale tracking

Sequence: Next valid transaction sequence number
  - Analysis: Transaction count from this account

OwnerCount: Number of objects owned (trust lines, offers, etc.)
  - Analysis: Account activity complexity

Flags: Account settings (e.g., DefaultRipple, RequireDest)
  - Analysis: Account behavior configuration

Domain: Optional domain verification
  - Analysis: Sometimes reveals identity

EmailHash: Optional email hash (deprecated, rarely used)
  - Analysis: Limited use

MessageKey: Optional public key for encrypted messaging
  - Analysis: Limited use

TransferRate: Fee charged on transfers (for issuers)
  - Analysis: IOU/token issuer identification

Deep dive on analytically critical fields:

• Divide by 1,000,000 for XRP amounts

• Track balance changes over time for flow analysis

• Aggregate by size tiers for distribution analysis

• Transaction counter (lifetime transactions sent)

• Rough activity measure (higher = more active historically)

• Note: Doesn't count received transactions

• Trust lines

• Offers on DEX

• Escrow objects

• Payment channels

• etc.

Higher owner count = more complex account activity. Can indicate traders (many offers), token users (many trust lines), or institutional operations.

XRPL requires accounts to maintain minimum XRP balances:

Base reserve: 10 XRP to create/maintain account
Owner reserve: 2 XRP per owned object

RESERVE CALCULATION:

Required Balance = Base Reserve + (OwnerCount × Owner Reserve)
                = 10 XRP + (OwnerCount × 2 XRP)

Example:
Account with 5 trust lines + 3 open offers:
OwnerCount = 8
Required = 10 + (8 × 2) = 26 XRP minimum

Analytical implications:

• Minimum to activate: 10 XRP (~$X at current prices)
• Cost to participate affects user growth
• Reserve is "locked" not "spent"—still shows in balance
• Very small balances (10-15 XRP) often indicate minimally-active or abandoned accounts

Understanding this distinction clarifies XRPL analytical approaches:

Bitcoin UTXO Model:

Transactions consume "coins" (UTXOs) and create new ones.

Input UTXOs → Transaction → Output UTXOs

To find balance, sum all unspent outputs for an address.
Tracing requires following UTXO chains.

XRPL Account Model:

Accounts have balances that increase and decrease.

Account.Balance += received
Account.Balance -= sent

Balance is directly queryable—no aggregation needed.

Analytical differences:

Aspect	UTXO (Bitcoin)	Account (XRPL)
Balance query	Aggregate UTXOs	Direct lookup
History	Trace UTXO lineage	Query transactions
Address clustering	Common input heuristic	Transaction patterns
Privacy	Change addresses complicate	Clearer address identity
Analysis complexity	Higher	Lower

• Balance tracking is straightforward
• Address clustering requires different techniques
• Transaction history is directly associated with accounts
• Simpler data model = more accessible analysis

---

Every XRPL transaction shares common elements:

COMMON TRANSACTION FIELDS:

Account: Source account sending the transaction
  - Analysis: Sender identification

TransactionType: What kind of transaction
  - Analysis: Activity categorization (see Section 3.2)

Fee: XRP paid as transaction fee (in drops)
  - Analysis: Demand indicator, but tiny on XRPL

Sequence: Transaction sequence number
  - Analysis: Ordering, gap detection

Flags: Transaction-specific options
  - Analysis: Behavioral modifiers

Memos: Optional arbitrary data
  - Analysis: Sometimes contains useful metadata

Signers/SigningPubKey: Authorization data
  - Analysis: Multi-sig detection

hash: Unique transaction identifier
  - Analysis: Reference for lookup

date: Ledger close time when processed
  - Analysis: Timing analysis

ledger_index: Which ledger contains this
  - Analysis: Historical reference

meta: Outcome and state changes
  - Analysis: Critical for understanding effects

XRPL has ~30 transaction types. Here are the most analytically relevant:

Tier 1: Core Economic Activity

• Description: Transfer XRP or issued assets

• Analytical use: Core economic activity tracking

• Key fields: Destination, Amount, SendMax (for cross-currency)

• Volume: ~70-80% of transactions

• Description: Place order on native DEX

• Analytical use: Trading activity, liquidity provision

• Key fields: TakerPays, TakerGets (defines the trade)

• Volume: ~10-15% of transactions

• Description: Remove order from DEX

• Analytical use: Trading activity, order management

• Key fields: OfferSequence (which offer to cancel)

Tier 2: Account Management

• Description: Modify account settings

• Analytical use: Configuration changes, rarely useful alone

• Key fields: Various flags being set

• Description: Create/modify trust line (for tokens)

• Analytical use: Token ecosystem growth, IOU adoption

• Key fields: LimitAmount (currency/issuer/limit)

• Description: Set signing key (security feature)

• Analytical use: Sophisticated account management

Tier 3: Advanced Features

• Description: Time-locked or condition-locked XRP

• Analytical use: Ripple's escrow tracking, conditional payments

• Key fields: Amount, Destination, FinishAfter, Condition

• Description: Off-chain payment channels

• Analytical use: Streaming payments, micropayments

• Key fields: Amount, Destination, PublicKey

• Description: Automated Market Maker operations

• Analytical use: DeFi activity on XRPL

• Key fields: Asset, Asset2, Amount (pool details)

• Description: NFT operations

• Analytical use: NFT ecosystem tracking

• Key fields: NFTokenID, Amount

Analytical categorization framework:

TRANSACTION CATEGORIZATION FOR ANALYSIS:

- Payment (XRP)
- Payment (issued assets)

- OfferCreate
- OfferCancel
- AMMDeposit/Withdraw
- NFTokenCreateOffer/AcceptOffer

- AccountSet
- TrustSet
- SetRegularKey
- SignerListSet

- EscrowCreate/Finish/Cancel
- PaymentChannelCreate/Fund/Claim

- AMMCreate
- NFTokenMint/Burn
- Clawback (if enabled)

The meta field contains the actual effects of a transaction—essential for analysis:

TRANSACTION METADATA:

TransactionResult: Success/failure code
  - "tesSUCCESS" = succeeded
  - Other codes = failed (but still recorded)
  - Analysis: Filter to successful transactions

AffectedNodes: Array of state changes
  - ModifiedNode: Changed existing object
  - CreatedNode: New object created
  - DeletedNode: Object removed
  - Analysis: See exactly what changed

delivered_amount: Actual amount received (for payments)
  - May differ from Amount field (partial payments)
  - Analysis: True economic value transferred

Why metadata matters:

The transaction fields show intent; metadata shows outcome. A Payment transaction might have Amount: 1000 XRP but only deliver 950 XRP (partial payment). Only metadata reveals the true delivered amount.

For flow analysis, always use delivered_amount (or calculate from AffectedNodes), not the stated Amount.

---

Beyond accounts, the XRPL stores various objects representing ongoing states:

LEDGER OBJECT TYPES:

AccountRoot - Account balances and settings (covered above)

Offer - Open order on the DEX
  - Fields: TakerPays, TakerGets, Account, Sequence
  - Analysis: Order book analysis, trading activity

RippleState - Trust line between two accounts
  - Fields: Balance, HighLimit, LowLimit, issuer info
  - Analysis: Token distribution, IOU tracking

Escrow - Time/condition-locked XRP
  - Fields: Amount, Destination, FinishAfter, Condition
  - Analysis: Ripple escrow monitoring, smart escrows

PayChannel - Payment channel
  - Fields: Amount, Balance, SourceTag, etc.
  - Analysis: Off-chain payment patterns

AMM - Automated Market Maker pool
  - Fields: Asset, Asset2, LPTokenBalance, TradingFee
  - Analysis: DeFi liquidity, pool health

NFTokenPage - Collection of NFTs
  - Contains NFToken objects
  - Analysis: NFT ecosystem metrics

DirectoryNode - Index structures (internal)
  - Analysis: Usually not directly relevant

Others: Check, DepositPreauth, Ticket, etc.

Escrow Objects (Critical for Ripple Monitoring):

ESCROW OBJECT:

Account: Creator of the escrow
Destination: Recipient when finished
Amount: XRP locked (in drops)
FinishAfter: Unix time when releasable (optional)
CancelAfter: Unix time when cancellable (optional)
Condition: Crypto-condition for release (optional)

- Created in 2017 with ~55B XRP
- Monthly releases of 1B XRP
- Known escrow addresses
- Track: releases, re-escrowing, actual sales

Offer Objects (DEX Analysis):

OFFER OBJECT:

Account: Who placed the offer
TakerPays: What they want to receive
TakerGets: What they're selling
Sequence: Unique identifier with Account
Expiration: When offer expires (optional)
Flags: Passive, ImmediateOrCancel, etc.

- Order book depth and shape
- Spread analysis
- Liquidity assessment
- Trading pair activity

RippleState Objects (Trust Lines / Tokens):

RIPPLE STATE OBJECT:

Balance: Current balance of the token
  - Positive: One party holds tokens
  - Negative: Other party holds tokens
LowLimit: Trust limit set by low account
HighLimit: Trust limit set by high account
LowNode/HighNode: Directory pointers

- Token distribution
- Issuer health (total outstanding)
- Token ecosystem growth

Objects are queried via rippled API methods:

USEFUL QUERIES:

account_info: Get AccountRoot for an address
account_lines: Get all trust lines for an account
account_offers: Get all open offers for an account
account_objects: Get all objects owned by account
account_tx: Get transaction history for account

book_offers: Get order book for a currency pair
ledger_entry: Get specific ledger object by ID

gateway_balances: Aggregate issued assets (for issuers)

---

Let's map common analytical questions to the required data:

QUESTION: "How is XRP distributed across holders?"

- All AccountRoot objects with Balance > 0
- Aggregated by balance tier

- Full ledger state snapshot
- Rich list data from explorers

- One entity may have multiple addresses
- Exchange addresses skew distribution
- Need to exclude/identify known entities

QUESTION: "Are whales accumulating or distributing?"

• Whale address list (see Lesson 5)

• Balance changes over time

• Transaction history for each whale

• account_info queries at different times

• account_tx for transaction details

• Defining "whale" threshold

• Identifying all whale addresses

• Distinguishing whale-to-whale transfers

QUESTION: "How much XRP is flowing to/from exchanges?"

- Exchange address list (see Lesson 5)
- Payments TO exchange addresses (inflows)
- Payments FROM exchange addresses (outflows)

- Payment transactions with exchange addresses
- Filter by destination for inflows, account for outflows

- Exchange address identification completeness
- Internal exchange transfers (hot↔cold)
- Defining time periods

QUESTION: "What's the daily active user count?"

• All transactions in time period

• Unique accounts involved

• Transaction stream for ledger range

• Deduplicate Account fields

• Counting "unique"—one entity, multiple addresses?

• Bots and automated accounts inflate count

• Time zone/period definition

Data Type	Availability	Access Method
Current balances	Universal	account_info
Balance history	Full history nodes	Snapshots or derivation
Transaction history	Usually extensive	account_tx
Full ledger state	Point-in-time	ledger_data (large)
Object details	Universal	ledger_entry
Aggregate metrics	Derived	Custom calculation

What's NOT on the ledger:

• Off-chain transactions: OTC trades, exchange internal transfers
• Identity information: Who owns an address (except Domain field, rarely used)
• Motivations: Why transactions occurred
• Price data: XRPL records amounts, not USD values (must join external price data)
• Derivative positions: No futures/options on XRPL native
• Fiat conversions: When XRP becomes USD/EUR/etc. off-chain

What requires interpretation:

• Entity clustering: Which addresses belong to same entity?
• Activity classification: Is this payment ODL or retail?
• Intent inference: Is exchange deposit for selling?

---

The primary interface for XRPL data is the JSON-RPC API:

// Example: Get account information
{
  "method": "account_info",
  "params": [{
    "account": "rN7n3473SaZBCG4dFL83w7...",
    "ledger_index": "validated"
  }]
}

// Example: Get recent transactions
{
  "method": "account_tx",
  "params": [{
    "account": "rN7n3473SaZBCG4dFL83w7...",
    "limit": 100,
    "forward": false
  }]
}

• wss://xrplcluster.com

• wss://s1.ripple.com

• wss://s2.ripple.com

• Running your own node

• Using commercial data providers

• Downloading bulk datasets

For systematic analysis, you'll want to:

• Export full account list with balances at specific dates

• Compare snapshots to derive changes

• Good for: Distribution analysis, periodic reporting

• Subscribe to transactions in real-time or query ranges

• Build your own database of relevant transactions

• Good for: Flow analysis, alert systems

• Use analytics platforms that have already processed data

• Trade control for convenience

• Good for: Quick analysis, standard metrics

We'll explore tools in detail in Lesson 3.

---

The XRPL provides rich, accessible data far exceeding traditional market transparency. Understanding the data architecture enables meaningful analysis, but that analysis operates within boundaries: you can only analyze what's recorded, and what's recorded doesn't include off-chain activity or human motivations. Master the data model, but remember its limits.

---

Assignment: Create a comprehensive reference document mapping XRPL data elements to analytical applications.

Requirements:

• Field name and data type

• What it represents

• Analytical application (what questions can it answer?)

• Any limitations or caveats

• Example use case

• All key fields

• What each field represents

• How to extract analytical value

• Common analysis patterns

• Note any metadata requirements

• What API methods are needed

• Key parameters to specify

• Expected response structure

• Sample query (JSON format)

• What analytical questions CANNOT be answered with on-chain data alone

• What supplemental data sources would be needed

• Any workarounds or approximations

• Completeness of coverage (25%)

• Accuracy of technical details (25%)

• Quality of analytical mapping (25%)

• Practical usefulness as reference (15%)

• Clarity and organization (10%)

Time Investment: 3-4 hours
Value: Creates a personal reference document you'll use throughout this course and beyond.

---

1. Data Model Question:

What is the primary advantage of XRPL's account model over Bitcoin's UTXO model for on-chain analysis?

A) Account model provides better privacy protection
B) Account balances are directly queryable without aggregation
C) Account model prevents double-spending more effectively
D) Account model supports more transaction types

Correct Answer: B
Explanation: The key analytical advantage is that XRPL balances are stored directly in the AccountRoot object and can be queried instantly. Bitcoin requires aggregating all unspent transaction outputs (UTXOs) to calculate a balance, which is more computationally intensive. Answer A is incorrect—account models generally have less privacy than UTXO. Answers C and D relate to features, not analytical advantages.

---

2. Transaction Metadata Question:

An analyst wants to track XRP payment volumes. Which data field should they use for the most accurate measurement?

A) The Amount field in the Payment transaction
B) The delivered_amount field in transaction metadata
C) The Fee field summed across all Payment transactions
D) The Balance field difference in the destination AccountRoot

Correct Answer: B
Explanation: The delivered_amount field in metadata shows what was actually received. The Amount field shows intended/maximum amount but partial payments may deliver less. Using Amount would overstate actual transfers. Answer C measures fees, not payment volumes. Answer D could work but is more complex and indirect than using delivered_amount directly.

---

3. Escrow Analysis Question:

To monitor Ripple's monthly escrow releases, an analyst should track:

A) Payment transactions from Ripple's main corporate address
B) EscrowFinish transactions on known Ripple escrow addresses
C) TrustSet transactions creating new escrow relationships
D) AccountSet transactions modifying escrow parameters

Correct Answer: B
Explanation: Ripple's escrow releases occur when EscrowFinish transactions execute on the escrow addresses created in 2017. These transactions release XRP from time-locked escrow. Answer A would track sales/transfers, not escrow releases. Answer C is incorrect—TrustSet is for trust lines, not escrows. Answer D is incorrect—AccountSet doesn't modify escrows.

---

4. Data Availability Question:

Which of the following is NOT directly available from XRPL on-chain data?

A) Historical balance of any address at any past ledger
B) All transactions ever sent from a specific address
C) The USD value of an XRP payment at the time it occurred
D) The total number of trust lines an account has

Correct Answer: C
Explanation: XRPL records XRP amounts in drops but does not record fiat exchange rates. To determine USD value, you must join on-chain data with external price data from exchanges. All other options are directly available: historical balances (from snapshots or derivation), transaction history (account_tx), and trust line count (from OwnerCount or account_lines query).

---

5. Transaction Type Question:

An analyst observes a large increase in OfferCreate transactions for the XRP/USD pair. This most directly indicates:

A) Increased XRP payment activity for remittances
B) Increased trading activity on the XRPL native DEX
C) New accounts being created on the network
D) Ripple releasing XRP from escrow

Correct Answer: B
Explanation: OfferCreate transactions place orders on the native DEX order book. An increase in these transactions for a specific pair (XRP/USD) directly indicates more trading activity on that pair. Answer A describes Payment activity, not DEX. Answer C would be indicated by new AccountRoot objects. Answer D involves EscrowFinish transactions.

---

For Next Lesson:
Begin exploring XRPSCAN.com and Bithomp.com to familiarize yourself with the data we discussed. We'll cover these and other tools in depth in Lesson 3: Tools of the Trade.

---

End of Lesson 2

Total words: ~6,400
Estimated completion time: 60 minutes reading + 3-4 hours for deliverable