Dollar tokens and the peg guard
Your node counts a dollar token as one dollar. While the token is worth clearly more or less than that, a guard pauses it. This page shows you what the wallet says then, and when the token runs again.
On this page
What the guard watches
On the XRP Ledger testnet, your dollar token is DSUSD, Dassie's own
test dollar. Your node books it as USD, one to one with
every other dollar. That only works while a DSUSD really is worth
about a dollar. If it were worth 90 cents, someone could pay your
node DSUSD and take a full dollar's worth of XRP back out.
So the node checks. Once a minute it reads the testnet's XRP/DSUSD AMM pool, proven from the ledger itself, and works out what one DSUSD costs in dollars: the pool's ratio of XRP to DSUSD, times the node's own XRP rate. A reading counts only when it is recent, the pool holds enough XRP to be a real price, and the node's XRP rate is less than ten minutes old.
| The guard | When |
|---|---|
| Pauses DSUSD | Every reading for ten minutes was more than 3% off a dollar, below $0.97 or above $1.03. |
| Runs it again | Every reading for an hour was within 1% of a dollar, between $0.99 and $1.01. |
| Pauses it, unread | No reading counted for ten minutes: the pool could not be read, held too little, or the XRP rate was stale. |
The bands and holds are in
peg.rs.
The narrower band for coming back keeps a price that hovers near
the edge from pausing and resuming over and over. Off upward and off
downward are the same pause. A gap in the readings longer than ten
minutes starts either hold again.
On the XRP Ledger mainnet the same guard watches RLUSD, through mainnet's XRP/RLUSD pool. Dassie does not run on mainnet yet, so today you only meet the guard with DSUSD.
Why it works this way: what an off-peg token can cost, and why the guard fails closed.
What you see in the wallet
Open Ledgers. The card for DSUSD on the XRP Ledger Testnet shows the guard's last reading in small print, such as:
DSUSD on its XRP/DSUSD pool: $1.0002, as of ledger 12345678The card for DSUSD in a settlement hub on the XRP Ledger Testnet shows the same guard, but for now it names the token by its ledger's currency, USD, and the pool as XRP/USD: USD on its XRP/USD pool, and USD in its notices. It is the same DSUSD and the same XRP/DSUSD pool.
The price is cut to four decimals, never rounded, so it never looks closer to a dollar than it is. While the guard pauses the token, a red notice sits above that line. It says which of two things happened:
- Paused: DSUSD is off its dollar peg. The pool prices it too far from a dollar, for too long. The notice gives the price.
- Paused: the price of DSUSD cannot be read. The node has had no reading that counts for too long. The pool could not be read or holds too little, or the node's XRP rate is stale.
On the hub's card, the notices say USD where these say DSUSD. The DSUSD tab under Receive shows your own DSUSD account, with the same notice, since what arrives there is still booked while the token is paused. The node also writes each pause and each recovery to its log.
What pauses, and what goes on
While DSUSD is paused:
- Your node converts nothing into or out of DSUSD: not on your DSUSD ledger, and not on the DSUSD hub's ledger. Payments that would turn XRP or another currency into DSUSD, or DSUSD into anything else, are refused.
- Peers can't swap into or out of DSUSD with your node: a core node's snapshot still lists the DSUSD hub, but closed. Nor does your node swap into or out of it by itself.
- A payment that stays in DSUSD all the way needs no conversion, so it can still pass. Settling with your peers over the DSUSD hub goes on: the hub moves DSUSD as it is.
- DSUSD that arrives on your account is still booked, at par. You can still move your DSUSD, for example between your account and the hub on the Hubs page. A token off its peg is still yours.
The ledger stays connected and in sync the whole time. Nothing needs to be done on your side.
When it runs again
- Off its peg: once every reading for an hour has been within 1% of a dollar. A price that comes back for twenty minutes and leaves again starts the hour over.
- Price unread: with the next reading within 3% of a dollar. A reading further off counts as the start of a de-peg instead.
The notice goes away by itself once the node says the token runs. The guard's state survives a restart, so restarting your node neither skips a recovery nor pauses the token again.
If it stays paused
On the testnet, a keeper holds DSUSD's pool near the market, and brings it back within seconds of a trade. If the notice says the price cannot be read, the trouble is more likely on your node's side. Check these, in order:
- The XRP rate. On Ledgers, the Exchange rates card shows how old the XRP rate is. If it is more than ten minutes old, or says stale, the guard cannot read the price, so check your rate sources; see Exchange-rate settings.
- The ledger connection. A DSUSD ledger that says it is connecting or catching up has no fresh readings. See Add and fund a ledger and Troubleshooting.
- The node's clock. A reading counts only from a recent ledger, judged by your node's clock. A clock that runs far behind or ahead makes every reading look old. Keep the server's time synced.
You cannot turn the guard off. Taking XRP's rate from mainnet's XRP/RLUSD pool, which turns the guard off, is not there yet. What's next
The peg guard in the spec: the readings, the holds and the hub's ledger in full.
