ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-29 16:15:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

TicketBatch: more reference docs

Browse Source
This commit is contained in:
mDuo13
2020-11-24 16:30:07 -08:00
parent 422b01a049
commit 9e3c369a8d
11 changed files with 39 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/concepts/payment-system-basics/accounts/tickets.md
View File

@@ -30,7 +30,7 @@ Tickets provide a solution to all of these problems by setting aside sequence nu
A Ticket is a record that a sequence number has been set aside to be used later. An account first sends a [TicketCreate transaction][] to set aside one or more sequence numbers as Tickets; this puts a record in the ledger's state data, in the form of a [Ticket object][], for each sequence number reserved. Later, the account can use a specific Ticket instead of a sequence number; doing so removes the corresponding Ticket from the ledger's state data.
Tickets are numbered using the sequence numbers that were set aside to create them. For example, if your account's current sequence number is 101 and you create 3 Tickets, those Tickets are numbered 101, 102, and 103. Doing so increases your account's sequence number to 104. After this point, you can send a transaction normally using sequence number 104, or you can send a transaction using any of the three Tickets you just created. Suppose you send a transaction using Ticket 102; doing so deletes Ticket 102 from the ledger. Your next transaction after that can use sequence number 104, Ticket 101, or Ticket 103.
Tickets are numbered using the sequence numbers that were set aside to create them. For example, if your account's current sequence number is 101 and you create 3 Tickets, those Tickets have Ticket Sequence numbers 101, 102, and 103. Doing so increases your account's sequence number to 104. After this point, you can send a transaction normally using sequence number 104, or you can send a transaction using any of the three Tickets you just created. Suppose you send a transaction using Ticket 102; doing so deletes Ticket 102 from the ledger. Your next transaction after that can use sequence number 104, Ticket 101, or Ticket 103.
**Tip:** When you create Tickets, your account's sequence number increases by the number of Tickets you created. When you use a Ticket, your account's sequence number does not change, but the ledger deletes the Ticket you used.

1
content/references/rippled-api/ledger-data-formats/ledger-object-types/accountroot.md
View File

@@ -53,6 +53,7 @@ The `AccountRoot` object has the following fields:
| `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/). |
| `MessageKey` | String | Blob | _(Optional)_ A public key that may be used to send encrypted messages to this account. In JSON, uses hexadecimal. No more than 33 bytes. |
| `RegularKey` | String | AccountID | _(Optional)_ The address of a [key pair](cryptographic-keys.html) that can be used to sign transactions for this account instead of the master key. Use a [SetRegularKey transaction][] to change this value. |
| `TicketCount` | Number | UInt32 | _(Optional)_ How many [Tickets](tickets.html) this account owns in the ledger. This is updated automatically to ensure that the account stays within the hard limit of 250 Tickets at a time. _(Added by the [TicketBatch amendment][] :not_enabled)_ |
| `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. _(Added by the [TickSize amendment][].)_ |
| `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. |
| `WalletLocator` | String | Hash256 | _(Optional)_ **DEPRECATED**. Do not use. |

3
content/references/rippled-api/ledger-data-formats/ledger-object-types/check.md
View File

@@ -65,7 +65,8 @@ The ID of a `Check` object is the [SHA-512Half][] of the following values, conca
* The Check 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
* The `Sequence` number of the [CheckCreate transaction][] that created the `Check` object.
If the CheckCreate transaction used a [Ticket](tickets.html), use the `TicketSequence` value instead.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

1
content/references/rippled-api/ledger-data-formats/ledger-object-types/escrow.md
View File

@@ -71,6 +71,7 @@ The ID of an `Escrow` object is the [SHA-512Half][] of the following values, con
* The Escrow space key (`0x0075`)
* The AccountID of the sender of the [EscrowCreate transaction][] that created the `Escrow` object
* The Sequence number of the [EscrowCreate transaction][] that created the `Escrow` object
If the EscrowCreate transaction used a [Ticket](tickets.html), use the `TicketSequence` value instead.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

1
content/references/rippled-api/ledger-data-formats/ledger-object-types/offer.md
View File

@@ -77,6 +77,7 @@ The ID of an `Offer` object is the [SHA-512Half][] of the following values, conc
* The Offer space key (`0x006F`)
* The AccountID of the account placing the offer
* The Sequence number of the [OfferCreate transaction][] that created the offer
If the OfferCreate transaction used a [Ticket](tickets.html), use the `TicketSequence` value instead.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

3
content/references/rippled-api/ledger-data-formats/ledger-object-types/paychannel.md
View File

@@ -103,7 +103,8 @@ The ID of a `PayChannel` object is the [SHA-512Half][] of the following values,
* The PayChannel space key (`0x0078`)
* The AccountID of the source account
* The AccountID of the destination account
* The Sequence number of the transaction that created the channel
* The Sequence number of the [PaymentChannelCreate transaction][] that created the channel
If the PaymentChannelCreate transaction used a [Ticket](tickets.html), use the `TicketSequence` value instead.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}

14
content/references/rippled-api/ledger-data-formats/ledger-object-types/ticket.md
View File

@@ -14,13 +14,21 @@ parent: ledger-object-types.html
_(Requires the [TicketBatch amendment][] :not_enabled:)_
The `Ticket` object type represents a [Ticket](tickets.html), which tracks an account [sequence number][Sequence Number] that has been set aside for future use. You can create new tickets with a [TicketCreate transaction][].
The `Ticket` object type represents a [Ticket](tickets.html), which tracks an account [sequence number][Sequence Number] that has been set aside for future use. You can create new tickets with a [TicketCreate transaction][]. [New in: rippled 1.7.0][]
## Example {{currentpage.name}} JSON
<!-- TODO: this example is synthetic. Replace with a real example when possible -->
```json
{
TODO
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Flags": 0,
"LedgerEntryType": "Ticket",
"OwnerNode": "0000000000000000",
"PreviousTxnID": "F0AB71E777B2DA54B86231E19B82554EF1F8211F92ECA473121C655BFC5329BF",
"PreviousTxnLgrSeq": 14524914,
"TicketSequence": 381
}
```
@@ -32,7 +40,7 @@ A `Ticket` object has the following fields:
|:--------------------|:----------|:--------------|:---------------------------|
| `LedgerEntryType` | String | UInt16 | The value `0x0054`, mapped to the string `Ticket`, indicates that this object is a {{currentpage.name}} object. |
| `Account` | String | AccountID | The [account](accounts.html) that owns this Ticket. |
| `Flags` | Number | UInt32 | A bit-map of Boolean flags enabled for this signer list. For more information, see [SignerList Flags](#signerlist-flags). |
| `Flags` | Number | UInt32 | A bit-map of Boolean flags enabled for this Ticket. Currently, there are no flags defined for Tickets. |
| `OwnerNode` | String | UInt64 | A hint indicating which page of the 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`. |
| `PreviousTxnID` | String | Hash256 | The identifying hash of the [transaction](transaction-basics.html) 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. |

2
content/references/rippled-api/public-rippled-methods/account-methods/account_objects.md
View File

@@ -12,7 +12,7 @@ The types of objects that may appear in the `account_objects` response for an ac
- [PayChannel objects](paychannel.html) for open payment channels.
- [Check objects](check.html) for pending Checks.
- [DepositPreauth objects](depositpreauth-object.html) for deposit preauthorizations. [New in: rippled 1.1.0][]
- [Ticket objects](known-amendments.html#tickets) :not_enabled: for tickets.
- [Ticket objects](known-amendments.html#tickets) :not_enabled: for Tickets.
## Request Format

4
content/references/rippled-api/public-rippled-methods/ledger-methods/ledger_entry.md
View File

@@ -59,6 +59,7 @@ This method can retrieve several different types of data. You can select which t
7. `escrow` - Retrieve an [Escrow object](escrow-object.html), which holds XRP until a specific time or condition is met. [New in: rippled 1.0.0][]
8. `payment_channel` - Retrieve a [PayChannel object](paychannel.html), which holds XRP for asynchronous payments. [New in: rippled 1.0.0][]
9. `deposit_preauth` - Retrieve a [DepositPreauth object](depositpreauth-object.html), which tracks preauthorization for payments to accounts requiring [Deposit Authorization](depositauth.html). [New in: rippled 1.1.0][]
10. `ticket` - Retrieve a [Ticket object](ticket.html), which records a [sequence number][] set aside for future use. _(Requires the [TicketBatch amendment][])_
If you specify more than one of the above items, the server retrieves only one of them; it is undefined which it chooses.
@@ -86,6 +87,9 @@ The full list of parameters recognized by this method is as follows:
| `ripple_state` | Object | _(Optional)_ Object specifying the RippleState (trust line) object to retrieve. The `accounts` and `currency` sub-fields are required to uniquely specify the RippleState entry to retrieve. |
| `ripple_state.accounts` | Array | _(Required if `ripple_state` is specified)_ 2-length array of account [Address][]es, defining the two accounts linked by this [RippleState object](ripplestate.html). |
| `ripple_state.currency` | String | _(Required if `ripple_state` is specified)_ [Currency Code][] of the [RippleState object](ripplestate.html) to retrieve. |
| `ticket` | Object or String | _(Optional)_ Object specifying the [Ticket object](ticket.html) to retrieve. If a string, the must be the [object ID](ledger-object-ids.html) of the Ticket, as hexadecimal. If an object, the `owner` and `ticket_sequence` sub-fields are required to uniquely specify the Ticket entry to retrieve. |
| `ticket.owner` | String - [Address][] | _(Required if `ticket` is specified as an object)_ The owner of the Ticket object. |
| `ticket.ticket_sequence` | Unsigned Integer | _(Required if `ticket` is specified as an object)_ The Ticket Sequence number of the Ticket entry to retrieve. |
| `binary` | Boolean | _(Optional)_ If true, return the requested ledger object's contents as a hex string. Otherwise, return data in JSON format. The default is `false`. [Updated in: rippled 1.2.0][] |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |

9
content/references/rippled-api/transaction-formats/transaction-common-fields.md
View File

@@ -7,7 +7,7 @@ Every transaction has the same set of common fields, plus additional fields base
| `Account` | String | AccountID | _(Required)_ The unique address of the [account](accounts.html) that initiated the transaction. |
| `TransactionType` | String | UInt16 | _(Required)_ The type of transaction. Valid types include: `Payment`, `OfferCreate`, `OfferCancel`, `TrustSet`, `AccountSet`, `AccountDelete`, `SetRegularKey`, `SignerListSet`, `EscrowCreate`, `EscrowFinish`, `EscrowCancel`, `PaymentChannelCreate`, `PaymentChannelFund`, `PaymentChannelClaim`, and `DepositPreauth`. |
| `Fee` | String | Amount | _(Required; [auto-fillable][])_ Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network. Some transaction types have different minimum requirements. See [Transaction Cost][] for details. |
| `Sequence` | Number | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](basic-data-types.html#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. The special case `0` means the transaction is using a [Ticket](tickets.html) instead. _(Requires the [TicketBatch amendment][] :not_enabled:)_ |
| `Sequence` | Number | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](basic-data-types.html#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. The special case `0` means the transaction is using a [Ticket](tickets.html) instead _(Requires the [TicketBatch amendment][] :not_enabled:)_. |
| [`AccountTxnID`](#accounttxnid) | String | Hash256 | _(Optional)_ Hash value identifying another transaction. If provided, this transaction is only valid if the sending account's previously-sent transaction matches the provided hash. |
| [`Flags`](#flags-field) | Number | UInt32 | _(Optional)_ Set of bit-flags for this transaction. |
| `LastLedgerSequence` | Number | UInt32 | _(Optional; strongly recommended)_ Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected. See [Reliable Transaction Submission](reliable-transaction-submission.html) for more details. |
@@ -15,7 +15,7 @@ Every transaction has the same set of common fields, plus additional fields base
| [`Signers`](#signers-field) | Array | Array | _(Optional)_ Array of objects that represent a [multi-signature](multi-signing.html) which authorizes this transaction. |
| `SourceTag` | Number | UInt32 | _(Optional)_ Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's `SourceTag` as the refund payment's `DestinationTag`. |
| `SigningPubKey` | String | Blob | _(Automatically added when signing)_ Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the `Signers` field instead. |
| `TicketSequence` | Number | UInt32 | _(Optional)_ The sequence number of the [ticket](tickets.html) to use in place of a `Sequence` number. If this is provided, `Sequence` must be `0`. |
| `TicketSequence` | Number | UInt32 | _(Optional)_ The sequence number of the [ticket](tickets.html) to use in place of a `Sequence` number. If this is provided, `Sequence` must be `0`. Cannot be used with `AccountTxnID`. |
| `TxnSignature` | String | Blob | _(Automatically added when signing)_ The signature that verifies this transaction as originating from the account it says it is from. |
[auto-fillable]: #auto-fillable-fields
@@ -27,12 +27,13 @@ Every transaction has the same set of common fields, plus additional fields base
<!-- SPELLING_IGNORE: AccountTxnID -->
The `AccountTxnID` field lets you chain your transactions together, so that a current transaction is not valid unless the previous one (by Sequence Number) is also valid and matches the transaction you expected.
The `AccountTxnID` field lets you chain your transactions together, so that a current transaction is not valid unless the previous transaction sent from the same account has a specific [transaction hash][identifying hash].
Unlike the `PreviousTxnID` field, which tracks the last transaction to _modify_ an account (regardless of sender), the `AccountTxnID` tracks the last transaction _sent by_ an account. To use `AccountTxnID`, you must first set the [`asfAccountTxnID`](accountset.html#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. (`PreviousTxnID`, by comparison, is always tracked.)
Unlike the `PreviousTxnID` field, which tracks the last transaction to _modify_ an account (regardless of sender), the `AccountTxnID` tracks the last transaction _sent by_ an account. To use `AccountTxnID`, you must first enable the [`asfAccountTxnID`](accountset.html#accountset-flags) flag, so that the ledger keeps track of the ID for the account's previous transaction. (`PreviousTxnID`, by comparison, is always tracked.)
One situation in which this is useful is if you have a primary system for submitting transactions and a passive backup system. If the passive backup system becomes disconnected from the primary, but the primary is not fully dead, and they both begin operating at the same time, you could potentially have serious problems like some transactions sending twice and others not at all. Chaining your transactions together with `AccountTxnID` ensures that, even if both systems are active, only one of them can submit valid transactions at a time.
The `AccountTxnID` field cannot be used on transactions that use [Tickets](tickets.html) :not_enabled:. Transactions that use `AccountTxnID` cannot be placed in the [transaction queue](transaction-queue.html).

15
content/references/rippled-api/transaction-formats/transaction-types/ticketcreate.md
View File

@@ -21,7 +21,10 @@ A TicketCreate transaction sets aside one or more [sequence numbers][Sequence Nu
```json
{
"TransactionType": "TicketCreate",
TODO
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "10",
"Sequence": 381,
"TicketCount": 10
}
```
@@ -32,16 +35,18 @@ A TicketCreate transaction sets aside one or more [sequence numbers][Sequence Nu
|:-----------------|:-----------------|:------------------|:-------------------|
| `TicketCount` | Number | UInt32 | How many Tickets to create. This must be a positive number, and cannot cause the account to own more than 250 Tickets after executing this transaction. |
**Caution:** Each Ticket counts as a separate item for the [owner reserve](reserves.html), so you must set aside 5 XRP for each Ticket. (The XRP becomes available again after you use the Ticket.) This cost can add up quickly if you create a large number of Tickets at once.
**Tip:** This transaction increases the sending account's [sequence number][Sequence Number] by the number of tickets created (`TicketCount`). This is the only transaction that increases an account's sequence number by more than 1.
## Error Cases
In addition to errors that can occur for all transactions, {{currentpage.name}} transactions can result in the following [transaction result codes](transaction-results.html):
| Error Code | Description |
|:-----------|:------------|
| `temINVALID_COUNT` | The `TicketCount` field is invalid. It must be an integer from 1 to 250. |
| `tecDIR_FULL` | This transaction would cause the account to own more than the limit of 250 Tickets at a time, or more than the maximum number of ledger objects in general. |
| Error Code | Description |
|:--------------------------|:-------------------------------------------------|
| `temINVALID_COUNT` | The `TicketCount` field is invalid. It must be an integer from 1 to 250. |
| `tecDIR_FULL` | This transaction would cause the account to own more than the limit of 250 Tickets at a time, or more than the maximum number of ledger objects in general. |
| `tecINSUFFICIENT_RESERVE` | The sending account does not have enough XRP to meet the [owner reserve](reserves.html) of all the requested Tickets. |
<!--{# common link defs #}-->