-
Notifications
You must be signed in to change notification settings - Fork 1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Checks (Reference changes) #296
Changes from 12 commits
6c5e1c3
1da18fb
2eda6e8
8bc7b48
93c9811
102b30a
99e46df
cde60d8
87f9930
be99b8a
cbc0495
c30bd85
25d687a
5291eb4
2484893
d8b034b
f0dcc2c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,69 @@ | ||
## AccountRoot | ||
[[Source]<br>](https://github.com/ripple/rippled/blob/5d2d88209f1732a0f8d592012094e345cbe3e675/src/ripple/protocol/impl/LedgerFormats.cpp#L27 "Source") | ||
|
||
The `AccountRoot` object type describes a single _account_ object. Example `AccountRoot` object: | ||
|
||
```json | ||
{ | ||
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", | ||
"AccountTxnID": "0D5FB50FA65C9FE1538FD7E398FFFE9D1908DFA4576D8D7A020040686F93C77D", | ||
"Balance": "148446663", | ||
"Domain": "6D64756F31332E636F6D", | ||
"EmailHash": "98B4375E1D753E5B91627516F6D70977", | ||
"Flags": 8388608, | ||
"LedgerEntryType": "AccountRoot", | ||
"MessageKey": "0000000000000000000000070000000300", | ||
"OwnerCount": 3, | ||
"PreviousTxnID": "0D5FB50FA65C9FE1538FD7E398FFFE9D1908DFA4576D8D7A020040686F93C77D", | ||
"PreviousTxnLgrSeq": 14091160, | ||
"Sequence": 336, | ||
"TransferRate": 1004999999, | ||
"index": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8" | ||
} | ||
``` | ||
|
||
The `AccountRoot` object has the following fields: | ||
|
||
| Field | JSON Type | [Internal Type][] | Description | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. How are these sorted? Should it be alphabetical? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. They're not really in order. (They sort of approximate the order in the source code, but not quite.) I'll change that to be like the ledger object types: LedgerEntryType first, then required fields in alphabetical order, then optional fields in alphabetical order. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Are all these different sorting orders explained somewhere? Seems like different tables use different sorting methods, which doesn't seem ideal for readers. |
||
|-----------------|-----------|---------------|-------------| | ||
| `LedgerEntryType` | String | UInt16 | The value `0x0061`, mapped to the string `AccountRoot`, indicates that this object is an AccountRoot object. | | ||
| `Account` | String | AccountID | The identifying address of this account, such as rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn. | | ||
| [`Flags`](#accountroot-flags) | Number | UInt32 | A bit-map of boolean flags enabled for this account. | | ||
| `Sequence` | Number | UInt32 | The sequence number of the next valid transaction for this account. (Each account starts with Sequence = 1 and increases each time a transaction is made.) | | ||
| `Balance` | String | Amount | The account's current [XRP balance in drops][XRP, in drops], represented as a string. | | ||
| `OwnerCount` | Number | UInt32 | The number of objects this account owns in the ledger, which contributes to its owner reserve. | | ||
| `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | | ||
| `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger](#ledger-index) that contains the transaction that most recently modified this object. | | ||
| `AccountTxnID` | String | Hash256 | (Optional) The identifying hash of the transaction most recently submitted by this account. | | ||
| `RegularKey` | String | AccountID | (Optional) The address of a keypair that can be used to sign transactions for this account instead of the master key. Use a [SetRegularKey transaction][] to change this value. | | ||
| `EmailHash` | String | Hash128 | (Optional) The md5 hash of an email address. Clients can use this to look up an avatar through services such as [Gravatar](https://en.gravatar.com/). | | ||
| `WalletLocator` | String | Hash256 | (Optional) **DEPRECATED**. Do not use. | | ||
| `WalletSize` | Number | UInt32 | (Optional) **DEPRECATED**. Do not use. | | ||
| `MessageKey` | String | VariableLength | (Optional) A public key that may be used to send encrypted messages to this account. In JSON, uses hexadecimal. No more than 33 bytes. | | ||
| `TickSize` | Number | UInt8 | (Optional) How many significant digits to use for exchange rates of Offers involving currencies issued by this address. Valid values are `3` to `15`, inclusive. _(Requires the [TickSize amendment](reference-amendments.html#ticksize).)_ | | ||
| `TransferRate` | Number | UInt32 | (Optional) A [transfer fee](https://ripple.com/knowledge_center/transfer-fees/) to charge other users for sending currency issued by this account to each other. | | ||
| `Domain` | String | VariableLength | (Optional) A domain associated with this account. In JSON, this is the hexadecimal for the ASCII representation of the domain. | | ||
|
||
### AccountRoot Flags | ||
|
||
There are several options which can be either enabled or disabled for an account. These options can be changed with an [AccountSet 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_. | ||
|
||
AccountRoot objects can have the following flag values: | ||
|
||
| Flag Name | Hex Value | Decimal Value | Description | Corresponding [AccountSet Flag](reference-transaction-format.html#accountset-flags) | | ||
|-----------|-----------|---------------|-------------|-------------------------------| | ||
| lsfPasswordSpent | 0x00010000 | 65536 | Indicates that the account has used its free SetRegularKey transaction. | (None) | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. possible nit: How are these fields sorted? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. In order of ascending numerical value. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If some tables are sorted that way and others alphabetically, we should probably explain that somewhere? |
||
| lsfRequireDestTag | 0x00020000 | 131072 | Requires incoming payments to specify a Destination Tag. | asfRequireDest | | ||
| lsfRequireAuth | 0x00040000 | 262144 | This account must individually approve other users for those users to hold this account's issuances. | asfRequireAuth | | ||
| lsfDisallowXRP | 0x00080000 | 524288 | Client applications should not send XRP to this account. Not enforced by `rippled`. | asfDisallowXRP | | ||
| lsfDisableMaster | 0x00100000 | 1048576 | Disallows use of the master key to sign transactions for this account. | asfDisableMaster | | ||
| lsfNoFreeze | 0x00200000 | 2097152 | This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled. | asfNoFreeze | | ||
| lsfGlobalFreeze | 0x00400000 | 4194304 | All assets issued by this address are frozen. | asfGlobalFreeze | | ||
| lsfDefaultRipple | 0x00800000 | 8388608 | Enable [rippling](concept-noripple.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | asfDefaultRipple | | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm assuming that the Checks documentation comes first and the DepositAuth changes will come later. Which means the |
||
### AccountRoot ID Format | ||
|
||
The ID of an AccountRoot object is the [SHA-512Half](#sha512half) of the following values put together: | ||
|
||
* The Account space key (`0x0061`) | ||
* The AccountID of the account |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,56 @@ | ||
## Amendments | ||
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/LedgerFormats.cpp#L110-L113 "Source") | ||
|
||
The `Amendments` object type contains a list of [Amendments](concept-amendments.html) that are currently active. Each ledger version contains **at most one** `Amendments` object. | ||
|
||
Example `Amendments` object: | ||
|
||
```json | ||
{ | ||
"Majorities": [ | ||
{ | ||
"Majority": { | ||
"Amendment": "1562511F573A19AE9BD103B5D6B9E01B3B46805AEC5D3C4805C902B514399146", | ||
"CloseTime": 535589001 | ||
} | ||
} | ||
], | ||
"Amendments": [ | ||
"42426C4D4F1009EE67080A9B7965B44656D7714D104A72F9B4369F97ABF044EE", | ||
"4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373", | ||
"6781F8368C4771B83E8B821D88F580202BCB4228075297B19E4FDC5233F1EFDC", | ||
"740352F2412A9909880C23A559FCECEDA3BE2126FED62FC7660D628A06927F11" | ||
], | ||
"Flags": 0, | ||
"LedgerEntryType": "Amendments", | ||
"index": "7DB0788C020F02780A673DC74757F23823FA3014C1866E72CC4CD8B226CD6EF4" | ||
} | ||
``` | ||
|
||
| Name | JSON Type | [Internal Type][] | Description | | ||
|-------------------|-----------|-------------------|-------------| | ||
| `Amendments` | Array | STI_VECTOR256 | _(Optional)_ Array of 256-bit [amendment IDs](concept-amendments.html#about-amendments) for all currently-enabled amendments. If omitted, there are no enabled amendments. | | ||
| `Majorities` | Array | STI_ARRAY | _(Optional)_ Array of objects describing the status of amendments that have majority support but are not yet enabled. If omitted, there are no pending amendments with majority support. | | ||
| `Flags` | Number | UInt32 | Not used. | | ||
| `LedgerEntryType` | String | UInt16 | The value `0x0066`, mapped to the string `Amendments`, indicates that this is object describes status of amendments to the XRP Ledger. | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. tiny: change "this is object" to
tiny: change "describes status of amendments" to:
|
||
|
||
Each member of the `Majorities` field, if it is present, is an object with a one field, `Majority`, whose contents are a nested object with the following fields: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. tiny: change "object with a one field" to:
|
||
|
||
| Name | JSON Type | [Internal Type][] | Description | | ||
|-------------------|-----------|-------------------|-------------| | ||
| `Amendment` | String | Hash256 | The Amendment ID of the pending amendment. | | ||
| `CloseTime` | Number | UInt32 | The [`close_time` field](#header-format) of the ledger version where this amendment most recently gained a majority. | | ||
|
||
In the [amendment process](concept-amendments.html#amendment-process), a consensus of validators adds a new amendment to the `Majorities` field using an [EnableAmendment][] pseudo-transaction with the `tfGotMajority` flag when 80% or more of validators support it. If support for a pending amendment goes below 80%, an [EnableAmendment][] pseudo-transaction with the `tfLostMajority` flag removes the amendment from the `Majorities` array. If an amendment remains in the `Majorities` field for at least 2 weeks, an [EnableAmendment][] pseudo-transaction with no flags removes it from `Majorities` and permanently adds it to the `Amendments` field. | ||
|
||
**Note:** Technically, all transactions in a ledger are processed based on which amendments are enabled in the ledger version immediately before it. While applying transactions to a ledger version where an amendment becomes enabled, the rules don't change mid-ledger. After the ledger is closed, the next ledger uses the new rules as defined by any new amendments that applied. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I like this note! Useful distinction. |
||
|
||
### Amendments ID Format | ||
|
||
The `Amendments` object ID is the hash of the `Amendments` space key (`0x0066`) only. This means that the ID of the `Amendments` object in a ledger is always: | ||
|
||
``` | ||
7DB0788C020F02780A673DC74757F23823FA3014C1866E72CC4CD8B226CD6EF4 | ||
``` | ||
|
||
(Don't mix up the ID of the `Amendments` ledger object type with the Amendment ID of an individual amendment.) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
## Check | ||
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/LedgerFormats.cpp#L158 "Source") | ||
|
||
_Requires the [Checks Amendment](reference-amendments.html#checks)._ | ||
|
||
A `Check` object describes a check, a potential pull payment, waiting to be cashed. (The potential payment has already been approved by its sender.) Example `Check` object: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Describing a check as a potential pull payment confuses me. Who's pulling the payment. How about comparing it to a traditional bank check, that promises payment when cashed or redeemed? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "Pull payment" confused me, too, but this article helped me understand it a little more: https://www.getcontrol.co/blog/push-or-pull-payments-strategy/ (assuming that the article is correct) Though it's interesting that the article uses checks as an example of a push payment. |
||
|
||
```json | ||
{ | ||
"Account": "rUn84CUYbNjRoTQ6mSW7BVJPSVJNLb1QLo", | ||
"Destination": "rfkE1aSy9G8Upk4JssnwBxhEv5p4mn2KTy", | ||
"DestinationNode": "0000000000000000", | ||
"DestinationTag": 1, | ||
"Expiration": 570113521, | ||
"Flags": 0, | ||
"InvoiceID": "46060241FABCF692D4D934BA2A6C4427CD4279083E38C77CBE642243E43BE291", | ||
"LedgerEntryType": "Check", | ||
"OwnerNode": "0000000000000000", | ||
"PreviousTxnID": "5463C6E08862A1FAE5EDAC12D70ADB16546A1F674930521295BC082494B62924", | ||
"PreviousTxnLgrSeq": 6, | ||
"SendMax": "100000000", | ||
"Sequence": 2, | ||
"index": "49647F0D748DC3FE26BDACBC57F251AADEFFF391403EC9BF87C97F67E9977FB0" | ||
} | ||
``` | ||
|
||
A `Check` object has the following fields: | ||
|
||
| Field | JSON Type | [Internal Type][] | Description | | ||
|:--------------------|:-----------------|:------------------|:----------------| | ||
| `LedgerEntryType` | String | UInt16 | The value `0x0043`, mapped to the string `Check`, indicates that this object is a Check object. | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. One last time: maybe order these alphabetically, unless there's another, better sorting scheme already. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah, as with the others, I'll fix the ordering. It was originally basically in the order the fields appeared in the source. I'll change it to be LedgerEntryType first, then required fields in alphabetical, then optional fields in alphabetical order. |
||
| `Account` | String | Account | The sender of the Check. Cashing the Check debits this address's balance. | | ||
| `Destination` | String | Account | The intended recipient of the Check. Only this address can cash the Check, using a [CheckCash transaction][]. | | ||
| `Flags` | Number | UInt32 | No flags are defined for Checks, so this value is always `0`. | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I like this descr of |
||
| `SendMax` | String or Object | Amount | The maximum amount of currency this Check can debit the sender. If the Check is successfully cashed, the destination is credited in the same currency for up to this amount. | | ||
| `Sequence` | Number | UInt32 | The sequence number of the [CheckCreate transaction][] that created this check. | | ||
| `OwnerNode` | String | UInt64 | A hint indicating which page of the sender's owner directory links to this object, in case the directory consists of multiple pages. **Note:** The object does not contain a direct link to the owner directory containing it, since that value can be derived from the `Account`. | | ||
| `DestinationNode` | String | UInt64 | _(Optional)_ A hint indicating which page of the destination's owner directory links to this object, in case the directory consists of multiple pages. | | ||
| `Expiration` | Number | UInt32 | (Optional) Indicates the time after which this Check is considered expired. See [Specifying Time](reference-rippled.html#specifying-time) for details. | | ||
| `InvoiceID` | String | Hash256 | _(Optional)_ Arbitrary 256-bit hash provided by the sender as a specific reason or identifier for this Check. | | ||
| `SourceTag` | Number | UInt32 | _(Optional)_ An arbitrary tag to further specify the source for this Check, such as a hosted recipient at the sender's address. | | ||
| `DestinationTag` | Number | UInt32 | _(Optional)_ An arbitrary tag to further specify the destination for this Check, such as a hosted recipient at the destination address. | | ||
| `PreviousTxnID` | String | Hash256 | The identifying hash of the transaction that most recently modified this object. | | ||
| `PreviousTxnLgrSeq` | Number | UInt32 | The [index of the ledger](#ledger-index) that contains the transaction that most recently modified this object. | | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Looks like the object contains the fields in alphabetical order, except for the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The fields in the table are presented in the following order, which I think is more useful (but please let me know if this seems wrong to you):
|
||
|
||
### Check ID Format | ||
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/Indexes.cpp#L193-L200 "Source") | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This looks like the features listing, which I expected to be the link for Checks when it was introduced, further above. Conversely, the source link in the Checks introduction contains what appears to be to me (and I don't read C++ very well) the formatting restraints, which would make sense here. Maybe you switched them or maybe I'm missing something? The concern is a bit compounded by the fact that some of the format sections on the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is it common for the online docs to reference rippled sources? There might be some maintenance issues with that. You're referring to the file at the tip of develop. As new lines are added or removed from that file then the lines you're linking to (L193-L200) may move out from under you. I think that maintenance concern is worth thinking about seriously. |
||
|
||
The ID of a `Check` object is the [SHA-512Half](#sha512half) of the following values put together: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There are 10 uses of 'put together' on the To disambiguate, I do understand that the SHA-512 algorithm acts on the elements to create the ID for that object, which also serves as the object's index (presumably for lookup in the hash map or tree). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes, concatenated in the order of the bullet points is correct? Of course, it's their C++ formats, not the JSON representation, so for example the AccountID is the actual number the address is derived from, not the base-58 encoded version with a checksum that we usually write. I've changed the wording to reflect that. I'm not adding any diagrams just yet. |
||
|
||
* The Escrow space key (`0x0043`) | ||
* The AccountID of the sender of the [CheckCreate transaction][] that created the `Check` object | ||
* The Sequence number of the [CheckCreate transaction][] that created the `Check` object |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should that be
6578616d706c652e636f6d
? 😉There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe. It's probably fine because this isn't a transaction, so other people aren't going to (can't) set their domains using this example.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any strong reason not to change all such examples to a standard?