Peers and holds

Your node peers with a few neighbors and passes payments through them. This page explains how it keeps track of what each one owes, how much it puts at stake with each, and how it chooses between them.

Each node keeps its own books

Dassie is not a consensus system. There is no shared record that all nodes agree on. Each node writes down what it saw happen with each peer, in its own books, and decides everything from them: whether to take a payment, when to ask a peer to settle, how much to pay when asked, and when to stop peering.

Two peers' books can drift apart. A node can crash with payments in flight, an answer can arrive late, an amount can be too small for the ledger to move, or a peer can simply lie. Your node cannot tell these apart, and it does not try. It does not keep a copy of the peer's books, and it never reconciles with them. What a peer says is taken as a hint, never trusted past your node's own limits.

That gives one simple promise: however a peer behaves, honest, broken or hostile, it can cost your node at most what your node's limits allow. The next sections say what those limits are.

Why it works this way, and why drift and malice are treated as one case.

Holds are the credit

Peers settle only over settlement hubs. A hub keeps an account for each member, and inside it a member can set money aside for one peer: a hold. The peer is paid from that hold for the payments it carries for you, with the promise your node signed for each one, whether or not your node is still around to agree.

Your node's hold toward a peer is money it paid in advance. It is all the credit your node gives that peer, and nothing more. The same goes the other way: what a peer may run up with your node is what it has set aside for you. Neither side lends the other anything beyond the holds.

• A hold starts at nothing. A new peering has no credit either way, whichever node asked, so your node asks a new peer to fund its hold right away.
• The creditor asks, the debtor decides. As soon as a packet takes a peer's room with you to one and a half of the largest packets, your node asks it to top up its hold, and a check every few seconds catches anything else. The peer decides how much from its own books, and settles nothing smaller than one largest packet, so nobody can make it pay a ledger fee for every few drops. Your node answers the same way when asked, and never settles on its own: when its hub account cannot fund a request at once, it funds it as soon as the account can, without being asked again.
• Short of funds, core peers come first. When your hub account cannot give every peer a full hold, each gets a share: enough for a full load of packets in flight first, core peers before the peers that use your node as their way in, and the rest by the fees each earned you. Each can always count on one largest packet; a busy peer may take more from what idle ones leave unused. Requests that waited for funds are answered in the same order. Settlement hubs says more.
• Nothing about credit is announced. No message tells a peer how much your node will let it owe. More credit only means your node asks later.
• Each hub stands on its own. Two nodes that share more than one hub settle over each of them, each with its own hold, its own room and its own requests to settle. No budget spans hubs, since that would need exchange rates.

The largest packet is the unit all of these limits are counted in. It is how much your node is prepared to lose on one link, so every threshold scales with it.

Why peers settle only over hubs, and why a hold is all the credit a node extends.

What a peer can cost you

Put together, the most a peer can cost your node is bounded by three things:

• Its room with you, which over a hub is the hold the peer set aside for you, and your own hold toward it.
• What is in flight. Your node lets at most two and a half of the largest packets be in flight with a peer, each way, on each hub you share. A crash can lose the answers to those packets, so that is how far one crash can drift two nodes' books. A payment that would pass the cap is turned away with a temporary error, and the sender slows down.
• The hub itself. What your node keeps in a hub, its own holds included, is at risk if the hub fails. Your node keeps a thousand of the largest packets there, more than its holds are likely ever to need, and tops the hub account up from its own account on the ledger when it runs a tenth below that. What peers pay you arrives in the hub, and what goes a tenth past it moves on to your own account. Your hubs shows where each one stands.

Why every threshold is counted in packets

Trust grows sideways

Nobody hands out trust from above. Your node learns which peers to rely on from what they did for it, and it sends more payments through the peers that earn it the most.

For each destination, your node keeps up to four first hops on the shortest paths there. It draws the next hop for every packet at random among them, so no single peer carries a whole payment, and a packet sent again after a failure may take another path. The draw is weighted:

• By the fees a peer earned you. A peer's weight is the fees your node earned on packets that went through it and were fulfilled, counted on each ledger apart. Fees are money someone really paid, so they are hard to fake. A packet that fails counts for nothing, so nobody can make a peer look bad by sending it payments that fail.
• With room to explore. One draw in ten ignores the weights and gives every first hop the same chance, so a new or quiet peer still gets a chance to earn.
• Fading over time. What a peer earned counts half as much after an hour, so a peer that stops delivering loses its weight. A restart starts every weight from nothing: weights only pace routing, they hold no money.
• Keeping the ledger where it can. A packet goes to a peer it can pay on the ledger it came in on, if any first hop has one. Only when none does is it converted, and then every first hop has the same chance. Your own payments never convert on their way out.

Fees are zero unless you set one, and with no fee charged nobody earns anything, so every draw is even. Fees are set under Exchange-rate settings.

Your node also keeps its first hops its own way. Where more peers reach a destination than it keeps, it chooses by a secret derived from its own key, so each node keeps a different few, and nobody can make up a node ID that every node prefers.

Why it works this way, and what it accepts in return.

Withdraw readily, end reluctantly

Your node lists the peers it is ready to route through in its signed link state, which the rest of the network reads (see Joining the network). It takes a peer out of that list quickly, and ends a peering only slowly.

Withdrawing a peer

A peer is listed only while your node has heard from it recently, while you have not banned it, and while it has room. A peer whose room stays below one largest packet for about three minutes without settling is withdrawn: still peered, still asked to settle, but no packet crosses the link until its room is back. Each time a peer is withdrawn it is held out a little longer before it can come back, from thirty seconds up to an hour, so a peer that comes and goes does not shake the whole network's routes.

Ending a peering

Ending a peering is for good, so it takes much stronger evidence:

• you end it, or ban the peer;
• the peer has not been heard from for a day;
• its room has stayed short for a day while it could be reached;
• the two of you no longer share a hub to settle over;
• or your node's funds in a hub have stayed too short for its peers there, as below.

Before your node tells the peer, it waits for its own settlements to arrive and asks the peer to settle once more. Then the two stop. A ban skips this: your node tells the peer at once, and what it owes stays on the books. After you end a peering, or after one ends for room, the two nodes do not peer again for up to a day (a restart ends the wait sooner); to keep a node away for good, ban it. A ban lasts until you lift it, and only you can ban: a node never bans a peer for what it cost.

Ending a peering is not the end of the relationship. Each side's books keep what was owed, and a later peering between the same two nodes settles it as usual. Your node also keeps the settlement channel with every node it has peered with, so a settlement that arrives after the end is still counted, exactly once.

You can watch all of this, and end a peering or ban a node yourself, on the wallet's Network page (see Network and peers).

Why it works this way, and how a peering ends.

As many peers as your funds cover

A hold below one largest packet carries no payment. So over each hub, your node keeps at least one largest packet for each peer: your balance in the hub and what it holds for your peers. A peer that settles over two hubs counts toward each.

• Funds first. When the hub holds less than that, and one packet more to take a newcomer, your node deposits the rest and a tenth of its target more from your own account, even past the hub's ceiling, and never withdraws that. While your own account can pay, nothing below happens.
• Newcomers next. When the funds would not cover one more peer, your node takes no new one over that hub, and asks none. It refuses nodes that use yours as their uplink first, and other core nodes only once the funds no longer cover even the core nodes it has. A node with no core peer over the hub still takes one.
• Back with room to spare. Your node takes newcomers again only once the funds cover them with a few packets to spare, so one settlement either way does not flip it.
• Ending last. Only if the funds stay short of a packet for every peer while no deposit can come (your own account is empty, or the node's own moves are off or paused) for about ten minutes, long enough for a deposit of yours to land, does your node end as many peerings as bring it back to a packet each. Nodes that use yours as their uplink go first, those that never paid it before those that did, the newest first; other core nodes only once none of those is left, those that asked yours first, and never the last. A peer you also share another hub with loses only its link over this one. Your node collects first, as always, and the peer is not kept away. A node outside the core ends none of its uplinks.

Who goes is decided by what nobody can fake: how long a peering has lasted, who asked, and whether the peer ever paid. It matters only once your own account cannot refill the hub. The wallet's Hubs page and dassie hub show where each hub stands (see Your hubs).

Why it works this way, and what it accepts in return.