Skip to content

Add send trust line token tutorial + remove old modular version - #3732

Open
maria-robobug wants to merge 1 commit into
masterfrom
new-send-trust-line-token-payment
Open

Add send trust line token tutorial + remove old modular version#3732
maria-robobug wants to merge 1 commit into
masterfrom
new-send-trust-line-token-payment

Conversation

@maria-robobug

@maria-robobug maria-robobug commented Jun 26, 2026

Copy link
Copy Markdown
Contributor
  • Adds new Send a Trust Line Token tutorial to replace the old modular version.

  • Fixes minor error in send mpt tutorial (transfer fee should be set to 0 for Python set up).

@maria-robobug maria-robobug changed the title Update sending trust line token tutorial Update send trust line token tutorial Jun 26, 2026
@maria-robobug maria-robobug changed the title Update send trust line token tutorial Add send trust line token tutorial + remove old modular version Jun 26, 2026
@maria-robobug
maria-robobug force-pushed the new-send-trust-line-token-payment branch 5 times, most recently from 8bc881f to 119ac62 Compare June 26, 2026 17:36
@maria-robobug
maria-robobug force-pushed the new-send-trust-line-token-payment branch from 119ac62 to ea6eb18 Compare June 26, 2026 17:44

@mDuo13 mDuo13 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The flow you walk through in this tutorial does not seem representative of real-world usage. Outside of testing, you're not likely to have the keys to all three accounts in one place, so I think you should separate the roles of the different parties more explicitly, making it as clear as possible when the person going through the tutorial is putting on different hats. The choice of which steps are hidden away in the setup script vs explicitly covered in the tutorial doesn't seem to follow from that principle.

Step Role taking action In Setup Script?
Issuer config Issuer
Sender trust line setup Sender
Issuing token to sender / Sender acquiring token Issuer
Receiver trust line setup Receiver
Sending trust line token payment Sender

I think the idealized scope of this tutorial is mainly the last row of this table, so it feels out of place to have the receiver setup not be covered by the setup script, too.

To address this issue and simplify the tutorial, I think the best approach would be to switch to using the TST.rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd token which should be pre-configured on both Testnet and Devnet as part of our docs data setup scripts. This would simplify the setup script steps and help keep the code for this tutorial on-topic. You might still have a setup script that covers steps like funding the sender, setting up their trust line, and having the sender acquire TST by buying it from the DEX. (Acquiring the token in the DEX or having the issuer send it to the sender directly are both potentially representative of real-world usage, but using the DEX shifts the role of who's taking action to the sender.)

I think another great simplification would be to have a preconfigured, hardcoded receiver account that already has a TST trust line (with a maximum limit). That account's setup would be something to add to the Docs Data Scripts so it's guaranteed that the receiver would already exist and be ready to receive TST on any test network.

Then the steps that need to be in-scope for this tutorial would be:

  1. Get a sender account and acquire the token to send—can be handled by the setup script, since that's a precondition for the tutorial rather than the goal of the tutorial.
  2. Check and display the sender's balance of the token. This would basically verify that the setup steps have been completed successfully, which is especially relevant if the user is adapting the tutorial to use their own token.
  3. Check that the recipient can receive the payment, including:
    • Do they have a trust line to the issuer?
    • Is rippling enabled on the issuer's side?
    • Is the limit high enough to accommodate the intended payment? (i.e. their limit > current balance + payment amount)
    • Does the issuer require auth, and if so, does the receiver have it? (TST doesn't require auth, but the code would be in place to handle other token configs)
    • What transfer fee applies for this token, if any? If one does, you need to set a SendMax to accommodate for it, and you might want to put a check or safeguard in place so asking to send a $100 payment doesn't automatically approve a massive transfer fee. (TST doesn't have a transfer fee, but the code would be in place to handle other token configs)
  4. Check and display the receiver's current balance (this would not be a static value, but would accumulate over time as more people do the tutorial—which should be fine) as well as the sender's balance
  5. Send the payment
  6. Check and display the respective balances

Ideally the values for TST and the receiver would be hard-coded constants that are easily changed, so you could, for example, set up a token using the Issue a Fungible Token tutorial and then use that instead.

We could also potentially make docs data scripts to pre-configure some alternative tokens with different properties, like one with a reasonable transfer fee, one with an unreasonably high transfer fee, and one that requires auth. The auth one would not be especially useful unless we also set up a faucet-like service that grants auth on demand; otherwise, potential senders couldn't hold the token. (It's not like we could let them use some kind of pre-approved sending account, since that would involve giving out that account's keys and anyone could ruin it for everyone.) I think it would still be possible to use cross-currency payments deliver the auth token to a preauthed recipient as long as there is also a preauthed market maker with a standing offer to trade XRP or a non-auth token for the auth token, but that is getting way outside the scope of this tutorial.

@@ -0,0 +1,3 @@
# Send a Trust Line Token Examples

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's omit "Examples". It's a bit extraneous and the heading works better as a card title on the Code Samples page without it.

Suggested change
# Send a Trust Line Token Examples
# Send a Trust Line Token


# Send a Trust Line Token

This tutorial shows you how to send a direct [trust line token](../../concepts/tokens/fungible-tokens/trust-line-tokens.md) payment on the XRP Ledger.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The word "direct" isn't quite accurate here: with trust line tokens, the only "direct" payments are to and from the issuer. Others, like the type of payment shown here, ripple through the issuer. This distinction is important because it clarifies why the issuer's DefaultRipple setting is needed, how the transfer fee applies, and more.

@@ -0,0 +1,221 @@
---
seo:
description: Send a direct payment of a trust line token on the XRP Ledger.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Direct" isn't quite right (see my comment on the first line of body text)


This tutorial shows you how to send a direct [trust line token](../../concepts/tokens/fungible-tokens/trust-line-tokens.md) payment on the XRP Ledger.

Each account must create a trust line to the issuer before it can hold the token. Holders can send the token to each other only if the issuer has the **Default Ripple** flag enabled, which lets the token move indirectly between holders through the issuer. This indirect movement of funds is called [rippling](../../concepts/tokens/fungible-tokens/rippling.md).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Holders can send the token to each other only if the issuer has the Default Ripple flag enabled

Not strictly true. If the issuer individually allows rippling on either the sender or receiver's trust line, that can also let those holders transact this way. Of course, Default Ripple is the preferred and recommended way to allow this, but we have seen confusion in the past when an issuer had some trust lines in with rippling enabled even though DefaultRipple was disabled, which meant certain specific pairs of accounts couldn't transact.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants