Integration overview

A Dassie node speaks the standard Interledger protocols, so you build on it with tools you may already know. This page helps you pick the right way in, and tells you which ones you can count on to stay put.

Choosing a way in

Each node serves a few doors to the outside. Most apps need only the first one.

Open Payments

Open Payments is how other wallets and apps reach a node. The node serves all three of its parts as the specs define them: wallet addresses, an authorization server and a resource server. The reference client, @interledger/open-payments, runs against a real node in Dassie's tests.

A node has one wallet address for each asset it holds, at https://<name>/pay/<asset>. On the testnet the asset is xrp or dsusd. In the local dev network it may also be usd, the play money that only a development build runs. The payment pointer $<name> stands for https://<name>/.well-known/pay, the asset the owner picked as the default. The name is the node's hostname, such as node.example.com. A node without one, such as the desktop app, is named <node ID>.dassiepay.net. The dassiepay.net front door reaches it there over a connection the node keeps to it as its relay, which it does by default.

A node reached through a front door can't ask its owner for consent yet, so it grants nothing its owner must approve, such as outgoing payments. Build those against a node with a hostname. What's next

A node does not speak SPSP: Open Payments replaced it, so a wallet that knows only SPSP cannot pay a Dassie node. It issues no STREAM receipts either.

Why it works this way

BTP and ILDCP

An ILP client connects to a node over a WebSocket, with a URL like btp+wss://:<token>@node.example.com/btp. The token is an API key the owner makes in the wallet. The client learns its address and asset through ILDCP, then sends and receives ILP packets. It spends the owner's money on one ledger, so the owner can cap what each key spends.

STREAM

Every payment in Dassie moves over STREAM. An incoming payment hands out STREAM credentials, an ILP address and a shared secret, and any STREAM sender can pay them. Dassie's STREAM is tested against ilp-protocol-stream, and the STREAM Toy runs Dassie's own code in your browser.

Snapshots

Peers swap assets with each other. A node with a hostname that offers swaps signs a snapshot of the prices it swaps at: a bid and an ask, each with a ladder, for each settlement method its peers pay it on. Peers that swap with it subscribe, and get each new snapshot over their peering. Anyone else asks for it once over UDP, on port 7768 by default, and gets the same signed bytes. The node's discovery document, /.well-known/dassie/node, names its ID, its two public keys and, while it answers, that port, so a tool that knows only the node's URL can find the snapshot and check it.

Why it works this way

What stays stable

Some of what a node speaks is held by software outside its release: other wallets, your app, the ledgers. Those parts are frozen: no release changes them.

• The Interledger wire formats: ILPv4, ILDCP, BTP 2.0, STREAM and Open Payments. Build on these freely.
• The snapshot's wire format, within its version. A new layout comes as a new version.
• The public domains, below.

Other parts change with each release, on purpose:

• The owner's RPC, which the wallet and the dassie command use, over the WebSocket at /rpc and over a local socket. Its two ends ship in one binary, so it changes whenever the node needs it to. It is not a public API: please do not build on it yet.
• The discovery document is public, but not among the frozen surfaces.

Apps that pair with a node and act as its owner are not there yet: the node pairs them, but the contract they would rely on is not frozen. What's next

ILP over HTTP (RFC 35) is not there yet: a node serves no /ilp route. What's next

Why it works this way: the full list, and what pins each surface.

Public domains

A few names leave the release and are kept by others. The project keeps them for good, with one exception for the testnet, below.

• dassiepay.net holds payment names. A node without a hostname is paid at <node ID>.dassiepay.net, and a node that holds a name at <name>.dassiepay.net. Wallets and apps store these as wallet addresses, so once the live realm opens, its names here are kept for good. A short list of names, such as relay and test, is reserved there; every other name belongs to someone's node, and its answers are that node's.
• dassie.land is the project's site. Its URIs also name the memo types on the ledgers, such as https://dassie.land/hub/open/v1 on the deposit that opens a hub account. Nothing fetches them.
• get.dassie.land holds the releases, and sh.dassie.land serves the installer.

The testnet's own payment domain, test.dassiepay.net, is not there yet. Testnet nodes are paid under dassiepay.net today. Those names move once, to test.dassiepay.net, when the testnet gets its own domain, and they may be reset with the testnet, so don't store them for good. What's next

Public domains lists every name, and Names and addresses explains how a node comes to hold one.

Why it works this way

A node to build against

You need a node whose owner you are, or one whose owner agrees to your app. The quickest is your own:

• A server node with a hostname, from the Quick Start. It serves every door above, and its wallet addresses carry its own name.
• The local dev network, which runs several nodes on your machine, with play money or a stand-in for the XRP Ledger.
• The desktop app, through BTP on localhost from a client on the same computer, and for incoming payments at <node ID>.dassiepay.net while it is connected to the front door there.

On the testnet, a node keeps its test money in a settlement hub. dassie setup joins the testnet's XRP hub unless you tell it otherwise, and Add and fund a ledger shows how to put money in.