The RippleState object type connects two accounts in a single currency. Conceptually, a RippleState object represents two trust lines between the accounts, one from each side. Each account can change the settings for its side of the RippleState object, but the balance is a single shared value. A trust line that is entirely in its default state is considered the same as a trust line that does not exist, so rippled deletes RippleState objects when their properties are entirely default.
There can only be one RippleState object per currency for any given pair of accounts. Since no account is privileged in Xahau, a RippleState object sorts account addresses numerically, to ensure a canonical form. Whichever address is numerically lower when decoded is deemed the "low account" and the other is the "high account". The net balance of the trust line is stored from the low account's perspective.
The "issuer" for the balance in a trust line depends on whether the balance is positive or negative. If a RippleState object shows a positive balance, the high account is the issuer. If the balance is negative, the low account is the issuer. Often, the issuer has its limit set to 0 and the other account has a positive limit, but this is not reliable because limits can change without affecting an existing balance.
A RippleState object has the following fields:
Balance
Object
Amount
Yes
The balance of the trust line, from the perspective of the low account. A negative balance indicates that the high account holds tokens issued by the low account. The issuer in this is always set to the neutral value ACCOUNT_ONE.
Flags
Number
UInt32
Yes
A bit-map of boolean options enabled for this object.
HighLimit
Object
Amount
Yes
The limit that the high account has set on the trust line. The issuer is the address of the high account that set this limit.
HighNode
String
UInt64
Yes
(Omitted in some historical ledgers) A hint indicating which page of the high account's owner directory links to this object, in case the directory consists of multiple pages.
HighQualityIn
Number
UInt32
No
The inbound quality set by the high account, as an integer in the implied ratio HighQualityIn:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value.
HighQualityOut
Number
UInt32
No
The outbound quality set by the high account, as an integer in the implied ratio HighQualityOut:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value.
LedgerEntryType
String
UInt16
Yes
The value 0x0072, mapped to the string RippleState, indicates that this object is a RippleState object.
LowLimit
Object
Amount
Yes
The limit that the low account has set on the trust line. The issuer is the address of the low account that set this limit.
LowNode
String
UInt64
Yes
(Omitted in some historical ledgers) A hint indicating which page of the low account's owner directory links to this object, in case the directory consists of multiple pages.
LowQualityIn
Number
UInt32
No
The inbound quality set by the low account, as an integer in the implied ratio LowQualityIn:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value.
LowQualityOut
Number
UInt32
No
The outbound quality set by the low account, as an integer in the implied ratio LowQualityOut:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value.
PreviousTxnID
String
Hash256
Yes
The identifying hash of the transaction that most recently modified this object.
PreviousTxnLgrSeq
Number
UInt32
Yes
The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object.
LockCount
Number
UInt32
No
The total number of lock balances on a RippleState ledger object
LockedBalance
Object
Amount
No
The current amount of locked tokens for a specific trustline
There are several options which can be either enabled or disabled for a trust line. These options can be changed with a [TrustSet transaction][]. In the ledger, flags are represented as binary values that can be combined with bitwise-or operations. The bit values for the flags in the ledger are different than the values used to enable or disable those flags in a transaction. Ledger flags have names that begin with lsf.
RippleState objects can have the following flag values:
Flag Name
Hex Value
Decimal Value
Corresponding TrustSet Flag
Description
lsfLowReserve
0x00010000
65536
(None)
This RippleState object contributes to the low account's owner reserve.
lsfHighReserve
0x00020000
131072
(None)
This RippleState object contributes to the high account's owner reserve.
lsfLowAuth
0x00040000
262144
tfSetAuth
The low account has authorized the high account to hold tokens issued by the low account.
lsfHighAuth
0x00080000
524288
tfSetAuth
The high account has authorized the low account to hold tokens issued by the high account.
lsfLowNoRipple
0x00100000
1048576
tfSetNoRipple
The low account has disabled rippling from this trust line.
lsfHighNoRipple
0x00200000
2097152
tfSetNoRipple
The high account has disabled rippling from this trust line.
lsfLowFreeze
0x00400000
4194304
tfSetFreeze
The low account has frozen the trust line, preventing the high account from transferring the asset.
lsfHighFreeze
0x00800000
8388608
tfSetFreeze
The high account has frozen the trust line, preventing the low account from transferring the asset.
If an account modifies a trust line to put it in a non-default state, then that trust line counts towards the account's owner reserve. In a RippleState object, the lsfLowReserve and lsfHighReserve flags indicate which account(s) are responsible for the owner reserve. The rippled server automatically sets these flags when it modifies a trust line.
The values that count towards a trust line's non-default state are as follows:
Balance is negative (the high account holds currency)
Balance is positive (the low account holds currency)
HighLimit is not 0
LowLimit is not 0
LowQualityIn is not 0 and not 1000000000
HighQualityIn is not 0 and not 1000000000
LowQualityOut is not 0 and not 1000000000
HighQualityOut is not 0 and not 1000000000
lsfHighNoRipple flag is not in its default state
lsfLowNoRipple flag is not in its default state
lsfHighFreeze flag is enabled
lsfLowFreeze flag is enabled
The lsfLowAuth and lsfHighAuth flags do not count against the default state, because they cannot be disabled.
The default state of the two No Ripple flags depends on the state of the lsfDefaultRipple flag in their corresponding AccountRoot objects. If Default Ripple is disabled (the default), then the default state of the lsfNoRipple flag is enabled for all of an account's trust lines. If an account enables Default Ripple, then the lsfNoRipple flag is disabled (rippling is enabled) for an account's trust lines by default.
Note: Prior to the introduction of the Default Ripple flag in rippled version 0.27.3 (March 10, 2015), the default state for all trust lines was with both No Ripple flags disabled (rippling enabled).
Fortunately, rippled uses lazy evaluation to calculate the owner reserve. This means that even if an account changes the default state of all its trust lines by changing the Default Ripple flag, that account's reserve stays the same initially. If an account modifies a trust line, rippled re-evaluates whether that individual trust line is in its default state and should contribute to the owner reserve.
The ID of a RippleState object is the [SHA-512Half][] of the following values, concatenated in order:
The RippleState space key (0x0072)
The AccountID of the low account
The AccountID of the high account
The 160-bit currency code of the trust line(s)