Animal strategies for neighbour-to-neighbour clearing.
Can we find loops of debt and clear them by talking to our neighbours? This is our workbench: small creatures, awkward graphs, messages crossing in flight, and experiments we can learn from together.
The rule for a node-local algorithm is simple: each node makes decisions from its own balances and state, plus messages exchanged with its direct neighbours. No participant gets a bird’s-eye view of the credit graph. Finding a loop, agreeing how much to clear, and completing the settlement are separate problems.
The issue tracker in docs/issues/ records proposals, experiments and open questions. Start with Headroom Clearing: reusing cleared capacity without exceeding the original debt on any link.
The one-unit retention research note preserves an offline Headroom reference and counterexamples. Product work now focuses on comfort zones; Headroom remains a debt-reduction baseline with different bounds and objectives.
The product roadmap proposes a community clearing assistant, a durable peer protocol, and staged pilots with explicit release gates. The next milestone is a three-node crash-recovery testnet alongside a read-only user demo.
The component PRDs and interactive wireframes turn that roadmap into draft requirements and phone/desktop flows.
The runnable hashlock app connects a responsive client to independent SQLite-backed peer nodes without enumerated routes or loop lengths. Try conditional approvals, locally verified fulfillment receipts and restart recovery using TEST units. See private network validation and the phone screenshot.
These are research prototypes from several generations. Early animals explored loop discovery and message ordering; later ones attempted negotiation and settlement. Their descriptions explain what we learned, rather than establish a performance ranking. The historical source links point to the last snapshot before the older implementations were removed.
| Animal | What it explores |
|---|---|
 |
Salmon floods probes and recognises a returning probe as evidence of a loop. A starting point that exposes the trouble with overlapping loops and notifications escaping into unrelated branches. |
 |
Pelican gives branching discoveries separate identities. Suppressing old probes can still hide opportunities when a new neighbour arrives. |
 |
Petrogale replays existing probes to new neighbours. A useful lesson for growing networks, at the cost of more duplicate discoveries and messages. |
 |
Stingray remembers probe routes and traces backwards to reconstruct loops. Additional pinned probes help where paths meet; crossing messages still make ordering difficult. |
 |
Jackal pauses a neighbour’s responses while sending a batch of probes. It tackles discovery races, but depends on ordered messages and successful pause/resume operation. |
 |
Squid alternates which neighbour may send. Local turn-taking makes coordination more systematic, while introducing its own liveness questions. |
 |
Butterfly combines probe-exchange handshakes, pinned probes and reverse traces. It explores concurrent discovery with more explicit bookkeeping; some trace handling still assumes restrictive path structures. |
 |
Giraffe handles harder cycle shapes with multi-leg traces, then adds exchange rates and proposal/commit negotiation. Separating discovery from settlement is a lasting contribution; the financial accounting remains preliminary. |
 |
Saiga fixes exchange rates at one and removes Giraffe’s intermediary profit haircut. It fits a common-unit model, but still needs an explicit debt-reduction objective and full settlement accounting. |
 |
Badger proposed majority-based, all-or-nothing finality. That direction remained unfinished: in this snapshot its implementation matches Saiga apart from the class name. |
The historical README, discovery protocol notes and lift-resolution notes preserve the longer explanations, including early ideas about trustlines and participant preferences.
Jerboa has its own repository. It brings neighbour messaging, probe/backtrack discovery, amount scouting and hashlock proposal/commit messages together with actual balance updates. It is an important settlement prototype. Its historical 50k Sarafu fixture results report 15.3% clearing, against 16.6% for DFS and 18.9% for MCF. These are a different input from the full Sarafu benchmark. June 2025 code removed the central semaphore still described in the README; those older measurements do not establish the revised concurrency design’s guarantees.
Jaribu also has its own repository. Multiple search worms claim visited nodes and stop on collisions. It is a useful experiment in contention; the implementation uses a shared global graph and controller, so it does not yet meet the node-local rule above.
Numbat is a new node-local experiment: sample outgoing links with a bias towards available capacity, carry observed bottlenecks along the search path, then recheck and reserve capacity before clearing a loop. Local retries let it revisit a changing network. It inherits the distributed simulator’s assumptions and limits, including reliable delivery and no crashes.
Held-out results and reproduction instructions show gains over our earlier node-local DFS variants in the larger synthetic cases, while largest-first remains stronger on average in the small cases. On the shared 50k Sarafu comparison, it trails historical Jerboa and Jaribu in achieved clearing. Numbat remains provisional and does not guarantee optimal clearing.
New timestamped experiments add dropped messages and sleeping peers; local turn-taking has generally added cost in the tested workloads. A Headroom postpass improves static Numbat clearing, but currently requires serialized initiation and retained zero-balance channels. These models have different assumptions and do not establish one universal winner.
- DFS, neighbour-message protocols and continuously growing graphs: reproducible runs, measured results and independent settlement checks.
- Trustlines and moving debt: signed balances, credit limits, loop adjustments and optimization references.
- The bird’s-eye worm and Sarafu benchmarks: centralized DFS, minimum-cost flow, dataset construction and solution formats.
The worm and MCF are useful reference points for measuring our animals. Their graph-wide access is part of the benchmark, not something a node-local contestant may use.
The detailed benchmark documentation has moved. These anchors keep links from earlier discussions useful.
Reproducible DFS and streaming experiments
Sarafu-Based Netting Challenge