From 175ed822e9206217a1659189050103bd1975aa44 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 24 Nov 2020 17:50:08 -0800 Subject: [PATCH] TicketBatch: diagrams, more references --- content/_img-sources/ticket-creation.uxf | 208 ++++++++++++++++ content/_img-sources/ticket-usage.uxf | 228 ++++++++++++++++++ .../_snippets/data_types/account_sequence.md | 4 +- content/_snippets/tx-type-links.md | 1 + .../payment-system-basics/accounts/tickets.md | 41 +++- .../transaction-types/ticketcreate.md | 2 - img/ticket-creation.svg | 193 +++++++++++++++ img/ticket-usage.svg | 203 ++++++++++++++++ 8 files changed, 871 insertions(+), 9 deletions(-) create mode 100644 content/_img-sources/ticket-creation.uxf create mode 100644 content/_img-sources/ticket-usage.uxf create mode 100644 img/ticket-creation.svg create mode 100644 img/ticket-usage.svg diff --git a/content/_img-sources/ticket-creation.uxf b/content/_img-sources/ticket-creation.uxf new file mode 100644 index 0000000000..bd0a719226 --- /dev/null +++ b/content/_img-sources/ticket-creation.uxf @@ -0,0 +1,208 @@ + + + 10 + + UMLClass + + 420 + 150 + 130 + 100 + + TicketCreate +transaction +-- +Account: rf1Bi... +TicketCount: 3 +Sequence: 101 + + + + UMLClass + + 660 + 80 + 440 + 330 + + Ledger State Data (After) +lt=. + + + + UMLClass + + 690 + 130 + 130 + 110 + + Account +-- +ID: rf1Bi... +*Sequence: 104* + + + + UMLClass + + 690 + 270 + 120 + 70 + + Ticket +-- +Account: rf1Bi... +Sequence: 101 + + + + UMLClass + + 820 + 270 + 120 + 70 + + Ticket +-- +Account: rf1Bi... +Sequence: 102 + + + + UMLClass + + 950 + 270 + 120 + 70 + + Ticket +-- +Account: rf1Bi... +Sequence: 103 + + + + UMLClass + + 80 + 70 + 240 + 340 + + Ledger State Data (Before) +lt=. + + + + UMLClass + + 130 + 130 + 130 + 110 + + Account +-- +ID: rf1Bi... +Sequence: 101 + + + + Relation + + 250 + 170 + 190 + 30 + + lt=<<<- + 170.0;10.0;10.0;10.0 + + + Relation + + 540 + 160 + 170 + 50 + + lt=<<<- + +updates + 150.0;20.0;10.0;20.0 + + + Relation + + 540 + 210 + 190 + 160 + + lt=<<<- + 170.0;130.0;140.0;140.0;10.0;10.0 + + + Relation + + 540 + 210 + 330 + 170 + + lt=<<<- + 310.0;130.0;140.0;150.0;10.0;10.0 + + + Relation + + 540 + 210 + 470 + 190 + + lt=<<<- + 450.0;130.0;150.0;170.0;10.0;10.0 + + + Text + + 540 + 280 + 70 + 30 + + creates + + + + Text + + 80 + 370 + 240 + 40 + + ... +style=wordwrap +halign=center + + + + Text + + 660 + 370 + 440 + 40 + + ... +style=wordwrap +halign=center + + + diff --git a/content/_img-sources/ticket-usage.uxf b/content/_img-sources/ticket-usage.uxf new file mode 100644 index 0000000000..f8cddf59d4 --- /dev/null +++ b/content/_img-sources/ticket-usage.uxf @@ -0,0 +1,228 @@ + + + 10 + + UMLClass + + 750 + 80 + 440 + 330 + + Ledger State Data (After) +lt=. + + + + UMLClass + + 70 + 120 + 130 + 110 + + Account +-- +ID: rf1Bi... +Sequence: 104 + + + + UMLClass + + 70 + 260 + 120 + 70 + + Ticket +-- +Account: rf1Bi... +Sequence: 101 + + + + UMLClass + + 200 + 260 + 120 + 70 + + Ticket +-- +Account: rf1Bi... +Sequence: 102 + + + + UMLClass + + 330 + 260 + 120 + 70 + + Ticket +-- +Account: rf1Bi... +Sequence: 103 + + + + UMLClass + + 530 + 120 + 170 + 120 + + (Any type of +transaction) +-- +Account: rf1Bi... +Sequence: 0 +TicketSequence: 102 +... + + + + UMLClass + + 40 + 80 + 440 + 330 + + Ledger State Data (Before) +lt=. + + + + Relation + + 280 + 200 + 270 + 80 + + lt=<<<- +used + 250.0;10.0;10.0;60.0 + + + UMLClass + + 790 + 130 + 130 + 110 + + Account +-- +ID: rf1Bi... +Sequence: 104 + + + + Text + + 950 + 140 + 130 + 30 + + Doesn't change + + + + Relation + + 890 + 150 + 90 + 50 + + lt=<- + 10.0;30.0;70.0;10.0 + + + UMLClass + + 790 + 270 + 120 + 70 + + Ticket +-- +Account: rf1Bi... +Sequence: 101 + + + + UMLClass + + 1040 + 270 + 120 + 70 + + Ticket +-- +Account: rf1Bi... +Sequence: 103 + + + + Relation + + 690 + 200 + 280 + 100 + + lt=<<<- + + + 260.0;80.0;220.0;60.0;60.0;40.0;10.0;10.0 + + + Text + + 930 + 290 + 90 + 50 + + Ticket 102 deleted +style=wordwrap + + + + Text + + 40 + 370 + 440 + 40 + + ... +style=wordwrap +halign=center + + + + Text + + 750 + 370 + 440 + 40 + + ... +style=wordwrap +halign=center + + + diff --git a/content/_snippets/data_types/account_sequence.md b/content/_snippets/data_types/account_sequence.md index 9f352c1ee6..1aa3091569 100644 --- a/content/_snippets/data_types/account_sequence.md +++ b/content/_snippets/data_types/account_sequence.md @@ -2,9 +2,11 @@ A sequence number is a 32-bit unsigned integer that is used to make sure transac Every [account in the XRP Ledger](accounts.html) has a sequence number in its `Sequence` field, which increases by 1 whenever that account sends a transaction and that transaction gets included in a [validated ledger](ledgers.html). Each [transaction](transaction-basics.html) also has a sequence number in its `Sequence` field, which must match the account's current sequence number when the transaction executes. For each account, each sequence number can only be used once, in numerical order. +[Tickets](tickets.html) :not_enabled: make some exceptions from these rules so that it is possible to send transactions out of the normal order. Tickets represent sequence numbers reserved for later use; a transaction can use a Ticket instead of a normal sequence number. + With the [DeletableAccounts amendment](known-amendments.html#deletableaccounts), the starting `Sequence` number for an account matches the [Ledger Index][] of the ledger version where the account was created. Before DeletableAccounts, every account started with `Sequence` number 1. -Whenever a transaction is included in a ledger, it uses up a sequence number regardless of whether the transaction executed successfully or failed with a [`tec`-class error code](tec-codes.html). Other transaction failures don't get included in ledgers, so they don't change the sender's sequence number (or have any other effects). +Whenever a transaction is included in a ledger, it uses up a sequence number (or Ticket) regardless of whether the transaction executed successfully or failed with a [`tec`-class error code](tec-codes.html). Other transaction failures don't get included in ledgers, so they don't change the sender's sequence number (or have any other effects). Within the ledger, an [Address][] and a sequence number are sometimes used together to identify an object that was created by the validated transaction with that sender and sequence number. [Escrows](escrow.html) and [Offers](offers.html) are examples of objects identified this way. diff --git a/content/_snippets/tx-type-links.md b/content/_snippets/tx-type-links.md index 200fa611b2..24097bf310 100644 --- a/content/_snippets/tx-type-links.md +++ b/content/_snippets/tx-type-links.md @@ -16,6 +16,7 @@ "PaymentChannelFund", "SetRegularKey", "SignerListSet", + "TicketCreate", "TrustSet" ] %} {% set pstxtypes = [ diff --git a/content/concepts/payment-system-basics/accounts/tickets.md b/content/concepts/payment-system-basics/accounts/tickets.md index 4dda3adab1..cff2ca95d2 100644 --- a/content/concepts/payment-system-basics/accounts/tickets.md +++ b/content/concepts/payment-system-basics/accounts/tickets.md @@ -1,5 +1,5 @@ --- -html: reserves.html +html: tickets.html funnel: Build doc_type: Concepts category: Payment System Basics @@ -17,7 +17,7 @@ A Ticket in the XRP Ledger is a way of setting aside a [sequence number][Sequenc [Transactions](transaction-basics.html) have sequence numbers so that any given transaction can execute no more than once. Sequence numbers also make sure any given transaction is unique: if you send the exact same amount of money to the same person multiple times, the Sequence Number is one detail that is guaranteed to be different each time. Finally, Sequence Numbers provide an elegant way to put transactions in a consistent order, even if some of them to arrive out of order when sent throughout the network. -However, there are some situations where sequence numbers are too limiting. Some possible situations include: +However, there are some situations where sequence numbers are too limiting. For example: - Two or more users share access to an account, each with the ability to send transactions independently. If these users try to send transactions around the same time without coordinating first, they may each try to use the same Sequence number for different transactions, and only one can succeed. - You may want to prepare and sign a transaction in advance, then save it in some secure storage so that it can be executed at any future point if certain events occur. However, if you want to continue using your account as normal in the meantime, you don't know what Sequence number the set-aside transaction will need. @@ -28,17 +28,46 @@ Tickets provide a solution to all of these problems by setting aside sequence nu ## Tickets Are Reserved Sequence Numbers -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. +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](ledgers.html), in the form of a [Ticket object][], for each sequence number reserved. -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. +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. -**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. +{{ include_svg("img/ticket-creation.svg", "Diagram: Creating three Tickets") }} + +Later, you can send a transaction using a specific Ticket instead of a sequence number; doing so removes the corresponding Ticket from the ledger's state data and does not change your account's normal sequence number. You can also still send transactions using normal sequence numbers without using Tickets. You can use any of your available Tickets in any order at any time, but each Ticket can only be used once. + +{{ include_svg("img/ticket-usage.svg", "Diagram: Using Ticket 102.") }} + +Continuing the above example, you can send a transaction using sequence number 104 or any of the three Tickets you created. If 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. + +**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. As with sequence numbers, sending a transaction uses up the Ticket _if and only if_ the transaction is confirmed by [consensus](consensus.html). However, transactions that fail to do what they were intended to do can still be confirmed by consensus with [`tec`-class result codes](tec-codes.html). -***TODO: diagram depicting creating and using Tickets*** +To look up what Tickets an account has available, use the [account_objects method][]. +## Limitations +Any account can create and use Tickets on any type of transaction. However, some restrictions apply: + +- Each Ticket can only be used once. It is possible to have multiple different candidate transactions +- Each account cannot have more than 250 Tickets in the ledger at a time. Therefore, you cannot create more than 250 Tickets at a time, either. +- You _can_ use a Ticket to create more Tickets. If you do, the Ticket you used does not count towards the total number of Tickets you can have at once. +- Each Ticket counts toward the [owner reserve](reserves.html), so you must set aside 5 XRP for each Ticket you have not used yet. The XRP becomes available for you to use again after the Ticket is used. +- Within an individual ledger, transactions that use Tickets execute after other transactions from the same sender. If an account has multiple transactions using Tickets in the same ledger version, those Tickets execute in order from lowest Ticket Sequence to highest. (For more information, see the documentation on consensus's [canonical order](consensus.html#calculate-and-share-validations).) +- To "cancel" a Ticket, use the Ticket to [perform a no-op](about-canceling-a-transaction.html) [AccountSet transaction][]. This deletes the Ticket so that you don't have to meet its reserve requirement. + +## See Also + + + +- **Concepts:** + - [Multi-Signing](multi-signing.html) +- **References:** + - [TicketCreate transaction][] + - [Transaction Common Fields](transaction-common-fields.html) + - [Ticket object](ticket.html) + - [account_objects method][] {% include '_snippets/rippled-api-links.md' %} diff --git a/content/references/rippled-api/transaction-formats/transaction-types/ticketcreate.md b/content/references/rippled-api/transaction-formats/transaction-types/ticketcreate.md index 1d80e8643d..5eb74c7bb5 100644 --- a/content/references/rippled-api/transaction-formats/transaction-types/ticketcreate.md +++ b/content/references/rippled-api/transaction-formats/transaction-types/ticketcreate.md @@ -35,8 +35,6 @@ 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 diff --git a/img/ticket-creation.svg b/img/ticket-creation.svg new file mode 100644 index 0000000000..cf65aa6cce --- /dev/null +++ b/img/ticket-creation.svg @@ -0,0 +1,193 @@ + + +......createsAccountID: rf1Bi...Sequence: 101Ledger State Data (Before)TicketAccount: rf1Bi...Sequence: 103TicketAccount: rf1Bi...Sequence: 102TicketAccount: rf1Bi...Sequence: 101AccountID: rf1Bi...Sequence: 104Ledger State Data (After)TicketCreatetransactionAccount: rf1Bi...TicketCount: 3Sequence: 101updates diff --git a/img/ticket-usage.svg b/img/ticket-usage.svg new file mode 100644 index 0000000000..07cd9ba457 --- /dev/null +++ b/img/ticket-usage.svg @@ -0,0 +1,203 @@ + + +......Ticket 102deletedTicketAccount: rf1Bi...Sequence: 103TicketAccount: rf1Bi...Sequence: 101Doesn't changeAccountID: rf1Bi...Sequence: 104Ledger State Data (Before)(Any type oftransaction)Account: rf1Bi...Sequence: 0TicketSequence: 102...TicketAccount: rf1Bi...Sequence: 103TicketAccount: rf1Bi...Sequence: 102TicketAccount: rf1Bi...Sequence: 101AccountID: rf1Bi...Sequence: 104Ledger State Data (After)used