Local dev network

One command runs a network of real Dassie nodes on your machine, sets each one up as its owner would, and opens a dashboard that shows them all. Use it to build against Dassie, or to work on Dassie itself, without touching a public network.

On the dev network, even the test money is pretend. The simple scenarios run on a stub ledger that settles nothing, and the ones on the XRP Ledger run on a fake XRP Ledger the dev environment builds and runs on your machine.

What you need

• Linux or macOS. On Windows, use WSL, a container or a VM.
• A clone of the repository.
• The tools at the versions the repository pins. On Linux, the easiest way is Nix: nix develop in the repository gives you a shell with Rust, Node, pnpm and mkcert. On macOS, or without Nix, the README lists what to install, and Contributing says more.

Starting it

1. Open the development shell, and install the packages:

   $nix develop
   $pnpm install

2. Build the WebAssembly modules the wallet uses. Do it again when you change the Rust crates they come from.

   $node --run build:wasm

3. Let your browser trust the dev certificates. You do this once per machine:

   $mkcert -install

4. On Linux, let it listen on port 443, so every node gets a name of its own in your browser. Without this, the dev server says so and runs without its proxy, and you reach the pages at their own ports.

   $sudo sysctl -w net.ipv4.ip_unprivileged_port_start=0

5. Start it:

   $node --run dev
   Dassie//dev  Starting the development environment…
   building the node…
   building the fake XRP Ledger…
   building the wallet and the dashboard…
   
     Dashboard: https://localhost/  <- Start here
     If the browser warns about the certificate, run `mkcert -install` once.
     Keys: space opens the dashboard, r restarts the nodes, q quits

   The first build takes a while. Later starts reuse it.

6. Press Space to open the dashboard, or go to https://localhost. Without the proxy, it is at https://localhost:10100.

The first time, it runs the two-nodes scenario: two nodes, d1 and d2, that find each other and peer. After that it runs whichever scenario you chose last.

If it does not start: it checks what it needs first and prints what is missing, such as mkcert. "another dev environment (PID …) runs on …: stop it first" means one is already running on the same state; stop it, or give this one its own with --state-dir and --port-offset. A port in use often means another checkout of Dassie runs its dev network or its tests.

The dashboard

The dashboard shows the whole network at once. Its sidebar has three pages and the list of nodes:

• Dashboard: the network as a graph, two nodes linked once each lists the other as its peer, and the links light up as packets cross them. Below it, every node's log in one place.
• Logs: the logs on a page of their own.
• Scenarios: every scenario, with Run to switch to it. On the one running, Start over wipes its nodes' data and starts it fresh, and Restart the nodes restarts them with their data.
• Nodes: host is the dev server's own log. Each node opens its page with the wallet's debug views: logs, nodes, ledger, routing, packets, state and database. The ↗ next to a node opens its wallet, signed in. + adds a node to the scenario.

A node that does not start, or stops on its own, shows as failed, with the end of its output.

A first payment

In the two-nodes scenario:

1. Open d1's wallet with its ↗. It has a stub ledger with 100 test dollars on it.

2. Choose Send, enter d2's wallet address, $d2.localhost:5002, and choose Continue. Enter an amount, choose Review, then Send.

3. Watch the link between d1 and d2 light up on the dashboard. The payment shows in d1's activity, and the money in d2's wallet.

From your own code, the same nodes take a BTP client and STREAM. The dev network's certificates come from mkcert's local CA, so tell your client to trust it: its file is in the directory mkcert -CAROOT prints. See Connect an ILP client over BTP and STREAM on Dassie.

Scenarios, with hubs

A scenario says how many nodes run, which ledgers each one uses, and which of them validate or join a settlement hub. Pick one on the dashboard's Scenarios page, or start with one:

$node --run dev -- --scenario hub

The dev network does not start dassie market-maker itself. To watch it trade, run it with a config for the market maker's node. Run a market maker describes the config, and tests/e2e/market_maker.ts writes one for these scenarios.

The live scenarios hold no real money. Their nodes enter the live realm through a dev switch that only a debug build honors, and settle only on the fake ledger. A released node refuses the live realm.

Every scenario with a hub, and both live scenarios, start from scratch on every run, a restart too. The fake ledger is a new chain each time. A hub's escrow cannot move to a new chain, so the scenario founds a new hub, and a live scenario runs on a new fake mainnet, which never resets. The other scenarios keep their data across restarts, until you pick another scenario or start over.

Peers in the dev network settle only over hubs, as everywhere in Dassie. Each scenario also serves its own fixed exchange rates, so no run depends on an outside rate service.

How each scenario is set up

Talking to a node

Each node is the real dassie binary, with its own data, IPC socket and ports, at https://dN.localhost through the proxy. A node without a domain name, such as a market maker's, answers its owner only at localhost, so the dashboard opens its wallet at https://localhost: and its own HTTPS port. Run the dassie command against any node with:

$node --run cli -- d1 status

For a dev network started with --state-dir, set DASSIE_DEV_STATE_DIR to the same directory first.

--port-offset moves every one of them by the same amount. Everything listens on loopback only: the dev nodes' keys come from a table in the repository, so anyone could act as them.

Changing the code

The dev network rebuilds what you change while it runs:

• Rust or the RPC contract (crates/, proto/): it rebuilds the node and restarts every node, with its data except in the scenarios that start from scratch. If the build fails, the dashboard shows the error and the nodes keep running the last build.
• The wallet and the dashboard are watch builds in development mode. Reload the page to see your change; the nodes serve the wallet from that build.

Flags

Pass them after --, as in node --run dev -- --no-proxy.

--scenario <id>

Run this scenario instead of the one chosen last.

--dassie <path>

Run this binary, without building or watching the node. The scenarios on the XRP Ledger then use the fake ledger built last, if there is one.

--no-watch

Build the wallet and the dashboard once, and watch nothing.

--no-proxy

Run without the proxy on port 443.

--headless

No keys and no hints, for scripts and tests.

--port-offset <n>

Move every port by n, from 0 to 40000.

--state-dir <dir>

Keep the state there instead of local/dev/ in the repository. DASSIE_DEV_STATE_DIR does the same.

Stopping and starting over

Press q or Ctrl+C to stop the dev network and every node; press it twice to quit at once. The nodes' data stays in local/dev/, and the next start resumes where you left off. To begin again from nothing, use Start over on the dashboard's Scenarios page. If a run crashed, the next start stops whatever it left behind.