Run a market maker
A core node that converts between XRP and dollars slowly runs out of one of them. A market maker brings it back: it swaps with the node when the node's quotes beat what its own holdings are worth, and rebalances on a pool on the XRP Ledger once it has moved far from even. This page sets one up, with one node of your own.
On this page
How it works
Each core node prices what it converts by what it holds: it quotes more for the asset it has least of. It signs a snapshot of its quotes, and pushes it to its peers. Your market maker's node peers with the core nodes it trades through, its targets, and reads their snapshots. The market maker values its own holdings the way a core node does, at the market's price on the XRP Ledger between XRP and a dollar token, from its pool and the order book beside it, but on a flatter curve: it gives a little more for the asset it holds less of. Every ten seconds it:
- rebalances first, if its share of either asset is too far from even: one swap on the pool, from one asset to the other on its node's XRP Ledger account, back to even;
- otherwise asks its node to swap with each target whose quote beats that valuation by a margin, after what selling the trade back on the pool would cost. Each swap is as large as the target's quotes allow, up to a cap, and up to four run at once.
The node sends a swap only while the target's snapshot promises at least the rate that clears. So the target gets back the asset it ran short of, and the market maker keeps the margin. It is a client of its node, not a node: every amount it moves is moved by the node or by the XRP Ledger. Exchange rates explains quotes and snapshots.
Why market makers, not the nodes, rebalance, why they swap with their peers, and why it values its holdings by a curve
One node, pinned
You run one node, in the settlement hubs of both of the pool's assets:
-
The testnet's XRP hub, funded from its XRP
ledger,
xrpl-testnet-xrp. -
The testnet's DSUSD hub, funded from its DSUSD
ledger,
xrpl-testnet-dsusd. The XRP ledger pays this hub's fees on the XRP Ledger too.
Both ledgers are on the node's one XRP Ledger account, and peer with no one. A swap with a target from one hub to the other makes that target convert, so one node trades through any number of targets, and its funds are shared by all of them.
The node is a periphery node, with no hostname and no relay, and it
pins every target as an uplink. So it peers with the targets and no
one else, and each swap goes to the target it was meant for. Each
target must be a core node in both hubs that offers swaps, as core
nodes do unless their owner turns it off. On the testnet,
boot1, boot2 and boot3 are
such nodes. Your node pins each by its node ID, from its discovery
document:
$curl -fsS https://boot1.dassie.xyz/.well-known/dassie/node | jq -r .id
Running the node
This runs the node as your user, with a data directory, IPC socket and ports of its own, apart from any other node on the machine:
$DASSIE_STATE_DIRECTORY=$HOME/mm/node \
DASSIE_IPC_SOCKET_PATH=$XDG_RUNTIME_DIR/mm.sock \
DASSIE_RELAY= \
DASSIE_UPLINKS=<target node ID>,<another target's node ID> \
dassie daemon --runtime standalone --http-port 4101 --https-port 5101 \
--feed-listen 127.0.0.1:0
-
DASSIE_RELAY=keeps no relay. Nobody pays this node at a name, so it needs none, and no front door learns when it is online. Leave it out, and the node keeps thedassiepay.netfront door, as a node without a hostname does by default. -
DASSIE_UPLINKSpins the targets, by node ID, comma separated. -
--feed-listen 127.0.0.1:0keeps the node off the snapshot port, 7768, which a periphery node never answers on anyway. -
Leave out
--listen: the node's QUIC socket takes the address of its HTTPS listener, and must reach the targets. Nothing needs to reach the node's ports from outside, so keep them closed in your firewall.
For a server, the units Dassie's own market maker runs with are a
good model:
apps/market-maker/vm.
Setting it up
Keep the node's recovery phrase in a file of its own, and set the node up from it. Setup joins both hubs, which are built into Dassie, with the ledgers they are funded from. What the node is paid beyond each hub's float goes to your own account, which the swaps on the pool spend from:
$DASSIE_IPC_SOCKET_PATH=$XDG_RUNTIME_DIR/mm.sock \
dassie setup --passphrase-file ~/mm/node.phrase \
--hub hub-xrpl-testnet-xrp --hub hub-xrpl-testnet-dsusd
Running setup again changes nothing, so you can run it at every start. The node asks the testnet's faucet for XRP while its account does not exist yet. A node with XRP alone is far from even, so the market maker's first swap on the pool buys DSUSD with half of it, and you need not buy DSUSD yourself.
Leave the node's Swapping with peers setting on, as it is for a new node, so that it reads its targets' snapshots. Give it no swap targets in its settings, so that it swaps only when the market maker asks. The market maker refuses to start while swapping is off.
Config and secrets
The market maker reads one JSON file, and checks all of it before it connects to anything:
{
"socket": "/run/user/1000/mm.sock",
"passphraseFile": "/home/me/mm/node.phrase",
"xrpl": {
"server": "wss://s.altnet.rippletest.net:51233",
"token": { "currency": "DSUSD", "issuer": "rURgPoYNN7tGqBzGXFeCLmKYgpSjYgJP6M" }
},
"xrp": {
"ledger": "hub-xrpl-testnet-xrp+xrp",
"ownerBook": "xrpl-testnet-xrp+xrp",
"cap": 10000000000
},
"token": {
"ledger": "hub-xrpl-testnet-dsusd+usd",
"ownerBook": "xrpl-testnet-dsusd+usd",
"cap": 10000000000
},
"curvePpm": 10000,
"marginPpm": 2000,
"thresholdPpm": 50000,
"slippagePpm": 10000,
"standingOffer": true
}
socket-
The node's IPC socket.
passphraseFile-
The file with the node's recovery phrase, below.
xrpl-
The XRP Ledger server,
wss://, on the testnet, and the token the pool pairs with XRP: its currency code and issuer. The market maker refuses to sign for a server that is not on the testnet. xrp,token-
Each of the pool's two assets:
-
ledger: the node's ledger of the asset's hub, which its swaps with targets pay on and are paid back on. -
ownerBook: the node's ledger of the same asset on its XRP Ledger account, which funds the hub and which the swaps on the pool spend. -
cap: the most one swap with a target pays of the asset. A swap pays from the node's hub, so keep it at most what the node keeps there.
Amounts are in the node's ledger units, a billion to one XRP or one dollar:
10000000000is 10. -
curvePpm-
How much more it gives for the asset it holds less of, in parts per million, at most
100000: the curve's strength. Keep it below the core nodes' own, 5%, so that it takes on their imbalance. marginPpm-
What a swap must gain, after what selling it back on the pool would cost, in parts per million:
2000is 0.2%. thresholdPpm-
How far its share of either asset may be from even before it rebalances on the pool, in parts per million of its value:
50000is five points, 55% in one asset. slippagePpm-
How far the pool may move against a swap on it before that swap fails rather than pays a worse price, in parts per million.
standingOffer-
Optional,
trueunless you set it tofalse: whether it keeps a standing offer on the order book while it is off even. caFile-
Optional: a file of root certificates to trust the XRP Ledger server by, beside the system's, for a host that has none of its own.
The config names no targets: they are the node's uplinks, which
DASSIE_UPLINKS pins. These values are those of Dassie's
own market maker, and they are starting points.
allowPrivate is for dev networks and tests only. A config
of bands, with tradeSize and band as releases
before the curve read, is refused, as is one in the format of 0.2.x.
dassie market-maker --config <file> --check checks
a config and exits. The full rules are in
config.rs.
The phrase
The market maker signs its swaps on the pool with the node's account key, so it needs the node's phrase, not only its socket. It checks that the phrase opens the account both of the node's owner books are on, keeps only the signing key in memory, and never logs a phrase.
Run it
$dassie market-maker --config ~/mm/config.json
It decides every ten seconds, and logs a line for each swap with a target, with what it paid and what came back, for a swap on the pool, or for why it holds. It stops at start if something it needs is missing, such as a ledger its config names that the node does not run. Once it runs, it rides out outages and keeps going.
It trades only through targets whose snapshot is current, so a target that has gone quiet is left out while the others trade. A target whose swap failed, or paid nothing, is left out for a minute, then twice as long each time it fails again, up to half an hour, and is back as soon as a swap through it pays.
Its curve and rebalancing
The market maker counts what its node holds of each asset in its hub and on its own account together, and values both at the market's mid: halfway between the best bid and ask of the pool, its fee counted, and of the order book beside it, where 100 XRP of offers would fill.
-
Its curve: it gives a little more than the pool
for the asset it holds less of, up to
curvePpmmore, as a core node does but more gently. So it keeps taking on a core node's imbalance after its own holdings start to lean. - The cost of undoing a swap: what a swap takes beyond even, the market maker will sell back one day, on the pool or the order book, whichever is cheaper. So that part pays what that costs: the pool's fee and the price impact of a rebalance, or the book's spread and depth, read when it decides. A swap back toward even pays none of it. What is left over is the margin, its profit.
-
Rebalancing: once its share of either asset is
more than
thresholdPpmfrom even, it swaps back to even on the pool in one payment, spending from its own account, before it trades again. One that fails, or cannot go, is tried again after a wait, and meanwhile it trades only back toward even.
So the market maker holds an imbalance of up to the threshold's share of its value between rebalances: with five points and $1,500, about $75, and a 1% move in XRP's price changes that by 75 cents either way. A smaller threshold holds less and rebalances more often.
The standing offer
Between rebalances, the market maker lets others bring it back to
even, rather than paying the pool's fee itself. While its share of
either asset is more than a fifth of thresholdPpm from
even, one point by default, it keeps one offer on the XRP Ledger's
order book from its node's account: it gives the asset it holds too
much of, as much as takes it back to even, for the other at the
market's mid.
- It replaces the offer, in one transaction, once the mid moves more than a twentieth of a percent or the amount by more than a tenth, and before it expires. Each offer expires by itself after five minutes, so one left behind by a stopped market maker doesn't stand for long.
- It takes the offer away once it is back within the band, before a swap on the pool past the threshold, and when it stops.
- While it stands, the offer holds the XRP Ledger's owner reserve for one object, 0.2 XRP, on your node's account. Your node books each fill as a deposit and a withdrawal on its own.
On a quiet book, such as the testnet's, few traders take it, and the market maker mostly rebalances on the pool past its threshold.
The market maker in full, in the spec: what it trusts, and how it counts a swap on its way.