Use Tickets tutorial improvements and additions

This commit is contained in:
rachelflynn
2026-05-21 11:16:59 -04:00
parent 2fd46e197b
commit 994286cfb2
14 changed files with 422 additions and 729 deletions

View File

@@ -1,274 +1,188 @@
---
html: use-tickets.html
parent: manage-account-settings.html
seo:
description: Use Tickets to send a transaction outside of normal Sequence order.
embed_xrpl_js: true
filters:
- interactive_steps
description: Use Tickets to send a transaction outside the normal Sequence order.
labels:
- Accounts
steps: ['Generate', 'Connect', 'Check Sequence', 'Prepare & Sign', 'Submit', 'Wait', 'Intermission', 'Check Tickets', 'Prepare Ticketed Tx', 'Submit Ticketed Tx', 'Wait Again']
- Transactions
---
# Use Tickets
[Tickets](../../../concepts/accounts/tickets.md) provide a way to send transactions out of the normal order. This tutorial walks through the steps of creating a Ticket, then using it to send another transaction.
[Tickets](../../../concepts/accounts/tickets.md) let you reserve Sequence numbers in advance so you can send transactions out of order. This is useful when collecting signatures on multi-signed transactions while normal account activity continues, or queuing transactions for later submission.
This tutorial walks through creating a batch of Tickets, using one in a transaction, and applying the same pattern to multi-signed workflows.
## Goals
By the end of this tutorial, you will be able to:
- Create Tickets to reserve Sequence numbers for future use.
- Use a Ticket to send a transaction outside the normal Sequence order.
## Prerequisites
<!-- Source for this specific tutorial's interactive bits: -->
<script type="application/javascript" src="/js/interactive-tutorial.js"></script>
<script type="application/javascript" src="/js/tutorials/use-tickets.js"></script>
To complete this tutorial, you need:
This page provides JavaScript examples that use the [xrpl.js](https://js.xrpl.org/) library. See [Get Started Using JavaScript](../../get-started/get-started-javascript.md) for setup instructions.
Since JavaScript works in the web browser, you can read along and use the interactive steps without any setup.
- A basic understanding of the XRP Ledger.
- A basic understanding of how [Sequence numbers](../../../references/protocol/data-types/basic-data-types.md#account-sequence) work in transactions.
- An XRP Ledger [client library](../../../references/client-libraries.md) set up.
- (Optional) A basic understanding of [multi-signing](../../../concepts/accounts/multi-signing.md), if you plan to combine it with Tickets.
- {% amendment-disclaimer name="TicketBatch" /%}
## Source Code
You can find the complete source code for this tutorial's examples in the [code samples section of this website's repository](https://github.com/XRPLF/xrpl-dev-portal/tree/master/_code-samples/use-tickets/).
## Steps
This tutorial is divided into a few phases:
- (Steps 1-2) **Setup:** You need an XRP Ledger address and secret. For production, you can use the same address and secret consistently. For this tutorial, you can generate new test credentials as needed. You also need to be connected to the network.
- (Steps 3-6) **Create Tickets:** Send a transaction to set aside some Tickets.
- (Optional) **Intermission:** After creating Tickets, you can send various other transactions at any time before, during, and after the following steps.
- (Steps 7-10) **Use Ticket:** Use one of your set-aside Tickets to send a transaction. You can repeat these steps while skipping the previous parts as long as you have at least one Ticket remaining to use.
### 1. Get Credentials
To transact on the XRP Ledger, you need an address and secret key, and some XRP. For development purposes, you can get these on the [Testnet](../../../concepts/networks-and-servers/parallel-networks.md) using the following interface:
{% partial file="/docs/_snippets/interactive-tutorials/generate-step.md" /%}
When you're building production-ready software, you should use an existing account, and manage your keys using a [secure signing configuration](../../../concepts/transactions/secure-signing.md).
### 2. Connect to Network
You must be connected to the network to submit transactions to it. Since Tickets are only available on Devnet so far, you should connect to a Devnet server. For example:
### 1. Install dependencies
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Connect to" before="// Get credentials" language="js" /%}
{% /tab %}
From the `_code-samples/use-tickets/js/` folder, use `npm` to install dependencies:
```sh
npm install
```
{% /tab %}
{% tab label="Python" %}
From the `_code-samples/use-tickets/py/` folder, set up a virtual environment and use `pip` to install dependencies:
```sh
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
{% /tab %}
{% tab label="Go" %}
From the `_code-samples/use-tickets/go/` folder, install dependencies with Go modules:
```sh
go mod download
```
{% /tab %}
{% /tabs %}
{% admonition type="info" name="Note" %}The code samples in this tutorial use JavaScript's [`async`/`await` pattern](https://javascript.info/async-await). Since `await` needs to be used from within an `async` function, the remaining code samples are written to continue inside the `main()` function started here. You can also use Promise methods `.then()` and `.catch()` instead of `async`/`await` if you prefer.{% /admonition %}
### 2. Set up client and account
For this tutorial, click the following button to connect:
{% partial file="/docs/_snippets/interactive-tutorials/connect-step.md" /%}
### 3. Check Sequence Number
Before you create any Tickets, you should check what [Sequence Number][] your account is at. You want the current Sequence number for the next step, and the Ticket Sequence numbers it sets aside start from this number.
Import the XRPL client library, connect to the network, and generate a test account funded by the [Testnet](../../../concepts/networks-and-servers/parallel-networks.md) faucet. Using a live test network lets you submit transactions without risking real XRP.
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Check Sequence" before="// Prepare and Sign TicketCreate" language="js" /%}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" before="// Create Tickets" language="js" /%}
{% /tab %}
{% tab label="Python" %}
{% code-snippet file="/_code-samples/use-tickets/py/use-tickets.py" before="# Create Tickets" language="py" /%}
{% /tab %}
{% tab label="Go" %}
{% code-snippet file="/_code-samples/use-tickets/go/main.go" before="// Create Tickets" language="go" /%}
{% /tab %}
{% /tabs %}
{% interactive-block label="Check Sequence" steps=$frontmatter.steps %}
<button id="check-sequence" class="btn btn-primary previous-steps-required">Check Sequence Number</button>
{% loading-icon message="Querying..." /%}
<div class="output-area"></div>
{% /interactive-block %}
### 4. Prepare and Sign TicketCreate
Construct a [TicketCreate transaction][] using the sequence number you determined in the previous step. Use the `TicketCount` field to specify how many Tickets to create. For example, to prepare a transaction that would make 10 Tickets:
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Prepare and Sign TicketCreate" before="// Submit TicketCreate" language="js" /%}
{% /tab %}
{% /tabs %}
Record the transaction's hash and `LastLedgerSequence` value so you can [be sure whether or not it got validated](../../../concepts/transactions/reliable-transaction-submission.md) later.
{% interactive-block label="Prepare & Sign" steps=$frontmatter.steps %}
<button id="prepare-and-sign" class="btn btn-primary previous-steps-required">Prepare & Sign</button>
<div class="output-area"></div>
{% /interactive-block %}
### 5. Submit TicketCreate
Submit the signed transaction blob that you created in the previous step. For example:
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Submit TicketCreate" before="// Wait for Validation" language="js" /%}
{% /tab %}
{% /tabs %}
{% interactive-block label="Submit" steps=$frontmatter.steps %}
<button id="ticketcreate-submit" class="btn btn-primary previous-steps-required" data-tx-blob-from="#tx_blob" data-wait-step-name="Wait">Submit</button>
{% loading-icon message="Sending..." /%}
<div class="output-area"></div>
{% /interactive-block %}
### 6. Wait for Validation
Most transactions are accepted into the next ledger version after they're submitted, which means it may take 4-7 seconds for a transaction's outcome to be final. If the XRP Ledger is busy or poor network connectivity delays a transaction from being relayed throughout the network, a transaction may take longer to be confirmed. (For information on how to set an expiration for transactions, see [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md).)
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Wait for Validation" before="// Check Available" language="js" /%}
{% /tab %}
{% /tabs %}
{% partial file="/docs/_snippets/interactive-tutorials/wait-step.md" /%}
### (Optional) Intermission
The power of Tickets is that you can carry on with your account's business as usual while you are getting Ticketed transactions ready. When you want to send a transaction using a Ticket, you can do that in parallel with other sending transactions, including ones using different Tickets, and submit a Ticketed transaction at any time. The only constraint is that each Ticket can only be used once.
{% admonition type="success" name="Tip" %}You can come back here to send Sequenced transactions between or during any of the following steps, without interfering with the success of your Ticketed transaction.{% /admonition %}
{% interactive-block label="Intermission" steps=$frontmatter.steps %}
<button id="intermission-payment" class="btn btn-primary previous-steps-required">Payment</button>
<button id="intermission-escrowcreate" class="btn btn-primary previous-steps-required">EscrowCreate</button>
<button id="intermission-accountset" class="btn btn-primary previous-steps-required">AccountSet</button>
<div class="output-area"></div>
{% /interactive-block %}
### 7. Check Available Tickets
When you want to send a Ticketed transaction, you need to know what Ticket Sequence number to use for it. If you've been keeping careful track of your account, you already know which Tickets you have, but if you're not sure, you can use the [account_objects method][] to look up your available tickets. For example:
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Check Available Tickets" before="// Prepare and Sign Ticketed" language="js" /%}
{% /tab %}
{% /tabs %}
{% interactive-block label="Check Tickets" steps=$frontmatter.steps %}
<button id="check-tickets" class="btn btn-primary previous-steps-required">Check Tickets</button>
<div class="output-area"></div>
{% /interactive-block %}
{% admonition type="success" name="Tip" %}You can repeat the steps from here through the end as long as you have Tickets left to be used!{% /admonition %}
### 8. Prepare Ticketed Transaction
Now that you have a Ticket available, you can prepare a transaction that uses it.
This can be any [type of transaction](../../../references/protocol/transactions/types/index.md) you like. The following example uses a no-op [AccountSet transaction][] since that doesn't require any other setup in the ledger. Set the `Sequence` field to `0` and include a `TicketSequence` field with the Ticket Sequence number of one of your available Tickets.
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Prepare and Sign Ticketed" before="// Submit Ticketed Transaction" language="js" /%}
{% /tab %}
{% /tabs %}
{% admonition type="success" name="Tip" %}
If you don't plan to submit the TicketCreate transaction right away, you should be sure not to set the `LastLedgerSequence` so that the transaction does not expire. The way you do this varies by library:
- **xrpl.js:** Specify `"LastLedgerSequence": null` when auto-filling the transaction.
- **`rippled`:** Omit `LastLedgerSequence` from the prepared instructions. The server does not provide a value by default.
{% admonition type="info" name="Note" %}
When you're building production-ready software, use an existing account and manage your keys using a [secure signing configuration](../../../concepts/transactions/secure-signing.md).
{% /admonition %}
{% interactive-block label="Prepare Ticketed Tx" steps=$frontmatter.steps %}
### 3. Create Tickets
<div id="ticket-selector">
<h4>Select a Ticket:</h4>
<div class="form-area"></div>
</div>
<button id="prepare-ticketed-tx" class="btn btn-primary previous-steps-required">Prepare Ticketed Transaction</button>
<div class="output-area"></div>
Send a [TicketCreate transaction][] and set the `TicketCount` field to the number of Tickets you want to create (up to 250 per account). Each new Ticket reserves a future [Sequence Number][] you can use later. Each Ticket also counts toward your account's [owner reserve](../../../concepts/accounts/reserves.md), which is released when the Ticket is used. Tickets stay reserved on the ledger until you consume them, regardless of any other transactions your account sends.
{% /interactive-block %}
### 9. Submit Ticketed Transaction
Submit the signed transaction blob that you created in the previous step. For example:
Submit the transaction and wait for validation. For example, to create 10 Tickets:
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Submit Ticketed Transaction" before="// Wait for Validation (again)" language="js" /%}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Create Tickets" before="// Check Available Tickets" language="js" /%}
{% /tab %}
{% tab label="Python" %}
{% code-snippet file="/_code-samples/use-tickets/py/use-tickets.py" from="# Create Tickets" before="# Check Available Tickets" language="py" /%}
{% /tab %}
{% tab label="Go" %}
{% code-snippet file="/_code-samples/use-tickets/go/main.go" from="// Create Tickets" before="// Check Available Tickets" language="go" /%}
{% /tab %}
{% /tabs %}
{% interactive-block label="Submit Ticketed Tx" steps=$frontmatter.steps %}
{% admonition type="info" name="Note" %}
A transaction is not final until it is validated by [consensus](../../../concepts/consensus-protocol/index.md), which typically occurs 4-7 seconds after submission. The submit-and-wait call above (`submitAndWait` in xrpl.js, `submit_and_wait` in xrpl-py, `SubmitTxAndWait` in xrpl-go) blocks until validation completes, so the validated result is already available.
<button id="ticketedtx-submit" class="btn btn-primary previous-steps-required" data-tx-blob-from="#tx_blob_t" data-wait-step-name="Wait Again">Submit</button>
<div class="output-area"></div>
For production code that needs to handle longer waits or transaction expiration, see [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md).
{% /admonition %}
{% /interactive-block %}
### 4. Check available Tickets
To send a Ticketed transaction, you need a Ticket Sequence number. Use the [account_objects method][] to list your Tickets. See the method's [Response Format](../../../references/http-websocket-apis/public-api-methods/account-methods/account_objects.md#response-format) for the response shape.
### 10. Wait for Validation
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Check Available Tickets" before="// Use a Ticket" language="js" /%}
{% /tab %}
{% tab label="Python" %}
{% code-snippet file="/_code-samples/use-tickets/py/use-tickets.py" from="# Check Available Tickets" before="# Use a Ticket" language="py" /%}
{% /tab %}
{% tab label="Go" %}
{% code-snippet file="/_code-samples/use-tickets/go/main.go" from="// Check Available Tickets" before="// Use a Ticket" language="go" /%}
{% /tab %}
{% /tabs %}
Ticketed transactions go through the consensus process the same way that Sequenced transactions do.
You can repeat the next step as long as you have unused Tickets.
{% partial file="/docs/_snippets/interactive-tutorials/wait-step.md" variables={label: "Wait Again"} /%}
### 5. Use a Ticket
Now that you have a Ticket available, you can use it in a transaction. This can be any [type of transaction](../../../references/protocol/transactions/types/index.md). You can use Tickets in any order, but each can only be used once. For the multi-signing variant, see [With Multi-Signing](#with-multi-signing) below.
{% admonition type="info" name="The Ticket pattern" %}
For any transaction that uses a Ticket, set the `Sequence` field to `0` and include a `TicketSequence` field with one of your available Ticket Sequence numbers.
{% /admonition %}
The following example uses an [AccountSet transaction][] with no fields set, making it a no-op that requires no setup. Ticketed transactions go through the same [consensus](../../../concepts/consensus-protocol/index.md) process as Sequenced transactions.
{% tabs %}
{% tab label="JavaScript" %}
{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Use a Ticket" language="js" /%}
{% /tab %}
{% tab label="Python" %}
{% code-snippet file="/_code-samples/use-tickets/py/use-tickets.py" from="# Use a Ticket" language="py" /%}
{% /tab %}
{% tab label="Go" %}
{% code-snippet file="/_code-samples/use-tickets/go/main.go" from="// Use a Ticket" language="go" /%}
{% /tab %}
{% /tabs %}
After the transaction is validated, the Ticket is consumed and removed from the ledger. To verify, re-run step 4, and the Ticket you used should no longer appear in the result.
{% admonition type="success" name="Tip" %}
You can use this same pattern to cancel an unused Ticket — just send a no-op AccountSet using the Ticket you no longer need.
{% /admonition %}
## With Multi-Signing
One of the main use cases for Tickets is to be able to collect signatures for several [multi-signed transactions](../../../concepts/accounts/multi-signing.md) in parallel. By using a Ticket, you can send a multi-signed transaction as soon as it is fully signed and ready to go, without worrying about which one will be ready first. <!-- STYLE_OVERRIDE: will -->
Reserve a Ticket for each [multi-signed transaction](../../../concepts/accounts/multi-signing.md) to hold its slot while you collect signatures. Then submit each transaction as soon as its signatures are complete, in any order.
In this scenario, [step 8, "Prepare Ticketed Transaction"](#8-prepare-ticketed-transaction) is slightly different. Instead of preparing and signing all at once, you would follow the steps for [sending any multi-signed transaction](../../best-practices/key-management/send-a-multi-signed-transaction.md): first prepare the transaction, then circulate it among trusted signers to collect their signatures, and finally combine the signatures into the final multi-signed transaction.
In this scenario, [step 5: Use a Ticket](#5-use-a-ticket) becomes a multi-step process: prepare the transaction, circulate it among signers, and combine their signatures. See [Send a Multi-Signed Transaction](../../best-practices/key-management/send-a-multi-signed-transaction.md) for more details.
You could do this in parallel for several different potential transactions as long as each one uses a different Ticket.
For complete working examples that combine Tickets and multi-signing, see `use-tickets-multisig.js` (JavaScript) or `use-tickets-to-multisign.py` (Python) in the [code samples directory](https://github.com/XRPLF/xrpl-dev-portal/tree/master/_code-samples/use-tickets/). A Go variant isn't currently available.
You can prepare multiple multi-signed transactions simultaneously, each using a different Ticket.
{% admonition type="success" name="Tip" %}
For this scenario, omit the `LastLedgerSequence` field so that the transaction does not expire while you collect signatures. How you do this varies by library:
- **xrpl.js:** Specify `"LastLedgerSequence": null` when auto-filling the transaction.
- **xrpl-py:** Set `last_ledger_sequence=None` on the transaction.
- **xrpl-go:** Leave the field unset before signing.
- **`rippled` directly:** Omit the field from the prepared instructions. The server doesn't provide a default.
{% /admonition %}
## See Also
- **Concepts:**
- [Tickets](../../../concepts/accounts/tickets.md)
- [Multi-Signing](../../../concepts/accounts/multi-signing.md)
- [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md)
- **Tutorials:**
- [Set Up Multi-Signing](../../best-practices/key-management/set-up-multi-signing.md)
- [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md)
- [Send a Multi-Signed Transaction](../../best-practices/key-management/send-a-multi-signed-transaction.md)
- **References:**
- [account_objects method][]
- [sign_for method][]
- [submit_multisigned method][]
- [TicketCreate transaction][]
- [Transaction Common Fields](../../../references/protocol/transactions/common-fields.md)
- [Transaction Common Fields][common fields]
{% raw-partial file="/docs/_snippets/common-links.md" /%}