From 6842277977cd55207abc89a9e142a55f14b00b85 Mon Sep 17 00:00:00 2001
From: Scott Schurr <scott@ripple.com>
Date: Mon, 7 Jul 2014 12:52:33 -0700
Subject: [PATCH] Add documentation for ledger entries (RIPD-361)

---
 src/ripple/module/app/ledger/README.md | 151 ++++++++++++++++++++++++-
 1 file changed, 149 insertions(+), 2 deletions(-)

diff --git a/src/ripple/module/app/ledger/README.md b/src/ripple/module/app/ledger/README.md
index 6a635bec3..57368edda 100644
--- a/src/ripple/module/app/ledger/README.md
+++ b/src/ripple/module/app/ledger/README.md
@@ -75,7 +75,7 @@ of the permanent, public history.
 
 The most recent ledger that the server believes the network reached consensus
 on. Different servers can arrive at a different conclusion about the last
-closed ledger. This is a consequence of Byztanine failure. The purpose of
+closed ledger. This is a consequence of Byzantanine failure. The purpose of
 validations is to resolve the differences between servers and come to a common
 conclusion about which last closed ledger is authoritative.
 
@@ -110,5 +110,152 @@ such as the root node of the state tree.
 
 ---
 
-# References
+# Ledger Structures #
+
+## Account Root ##
+
+**Account:** A 160-bit account ID.
+
+**Balance:** Balance in the account.
+
+**Flags:** ???
+
+**LedgerEntryType:** "AccountRoot"
+
+**OwnerCount:** The number of items the account owns that are charged to the
+account.  Offers are charged to the account.  Trust lines may be charged to
+the account (but not necessarily).  The OwnerCount determines the reserve on
+the account.
+
+**PreviousTxnID:** 256-bit index of the previous transaction on this account.
+
+**PreviousTxnLgrSeq:** Ledger number sequence number of the previous
+transaction on this account.
+
+**Sequence:** Must be a value of 1 for the account to process a valid
+transaction.  The value initially matches the sequence number of the state
+tree of the account that signed the transaction.  The process of executing
+the transaction increments the sequence number.  This is how ripple prevents
+a transaction from executing more than once.
+
+**index:** 256-bit hash of this AccountRoot.
+
+
+## Trust Line ##
+
+The trust line acts as an edge connecting two accounts: the accounts
+represented by the HighNode and the LowNode.  Which account is "high" and
+"low" is determined by the values of the two 160-bit account IDs.  The
+account with the smaller 160-bit ID is always the low account.  This
+ordering makes the hash of a trust line between accounts A and B have the
+same value as a trust line between accounts B and A.
+
+**Balance:**
+ - **currency:** String identifying a valid currency, e.g., "BTC".
+ - **issuer:** There is no issuer, really, this entry is "NoAccount".
+ - **value:** 
+
+**Flags:** ???
+
+**HighLimit:**
+ - **currency:** Same as for Balance.
+ - **issuer:** A 160-bit account ID.
+ - **value:** The largest amount this issuer will accept of the currency.
+
+**HighNode:** A deletion hint.
+
+**LedgerEntryType:** "RippleState".
+
+**LowLimit:**
+ - **currency:** Same as for Balance.
+ - **issuer:** A 160-bit account ID.
+ - **value:** The largest amount of the currency this issuer will accept.
+
+**LowNode:** A deletion hint
+
+**PreviousTxnID:** 256-bit hash of the previous transaction on this account.
+
+**PreviousTxnLgrSeq:** Ledger number sequence number of the previous
+transaction on this account.
+
+**index:** 256-bit hash of this RippleState.
+
+
+## Ledger Hashes ##
+
+**Flags:** ???
+
+**Hashes:** A list of the hashes of the previous 256 ledgers.
+
+**LastLedgerSequence:**
+
+**LedgerEntryType:** "LedgerHashes".
+
+**index:** 256-bit hash of this LedgerHashes.
+
+
+## Owner Directory ##
+
+Lists all of the offers and trust lines that are associated with an account.
+
+**Flags:** ???
+
+**Indexes:** A list of hashes of items owned by the account.
+
+**LedgerEntryType:** "DirectoryNode".
+
+**Owner:** 160-bit ID of the owner account.
+
+**RootIndex:**
+
+**index:** A hash of the owner account.
+
+
+## Book Directory ##
+
+Lists one or more offers that have the same quality.
+
+If a pair of Currency and Issuer fields are all zeros, then that pair is
+dealing in XRP.
+
+The code, at the moment, does not recognize that the Currency and Issuer
+fields are currencies and issuers.  So those values are presented in hex,
+rather than as accounts and currencies.  That's a bug and should be fixed
+at some point.
+
+**ExchangeRate:** A 64-bit value.  The first 8-bits is the exponent and the
+remaining bits are the mantissa.  The format is such that a bigger 64-bit
+value always represents a higher exchange rate.
+
+Each type can compute its own hash.  The hash of a book directory contains,
+as its lowest 64 bits, the exchange rate.  This means that if there are
+multiple *almost* identical book directories, but with different exchange
+rates, then these book directories will sit together in the ledger.  The best
+exchange rate will be the first in the sequence of Book Directories.
+
+**Flags:** ???
+
+**Indexes:** 256-bit hashes of offers that match the exchange rate and
+currencies described by this BookDirectory.
+
+**LedgerEntryType:** "DirectoryNode".
+
+**RootIndex:** Always identical to the index.
+
+**TakerGetsCurrency:** Type of currency taker receives.
+
+**TakerGetsIssuer:** Issuer of the GetsCurrency.
+
+**TakerPaysCurrency:** Type of currency taker pays.
+
+**TakerPaysIssuer:** Issuer of the PaysCurrency.
+
+**index:** A 256-bit hash computed using the TakerGetsCurrency, TakerGetsIssuer,
+TakerPaysCurrency, and TakerPaysIssuer in the top 192 bits.  The lower 64-bits
+are occupied by the exchange rate.
+
+
+---
+
+# References #