Add Ability to Run as Full Simulator #2

adamjonas · 2024-03-19T15:46:14Z

This PR is a WIP that adds the ability to run SimLN without any real lightning nodes, instead providing "simulated nodes" that copy the the routing policies and liquidity constraints of real nodes. The last commit hard-codes a graph to run this "full simulation" on as an example, whereas in reality we'd load from a json description of the desired topology/policies.

High Level Overview

Lightning implementations in SimLN are abstracted using the LightningNode: (https://github.com/bitcoin-dev-project/sim-ln/blob/main/sim-lib/src/lib.rs#L180) trait. The steps that we follow to support a simulated implementation of this trait (SimNode) are as follows:

Run the simulator with a –from_graph option, which allows starting the simulator with a graph file (format tbd) that provides channel policies and topology (not included in this PR).
Use a single, top-level SimGraph struct to manage:
- A hashmap of simulated channels available
- Propagation of payments through the simulated channels
Implement LightningNode: (https://github.com/bitcoin-dev-project/sim-ln/blob/main/sim-lib/src/lib.rs#L180) on a SimNode struct which:
- Handles implementation of send/tracking functionality
- Points to the coordinating SimGraph struct to manage payment dispatch.

Graph Abstraction

Management of payments through the simulated network is separated managed with the following layers:

SimGraph: high level coordinator that keeps a hashmap of each simulated channel (see below) in the network, along with their forwarding policies. Responsible for coordinating addition/removal of HTLCs as they propagate through the network.
SimNode: implementation of the LightningNode trait which rely on the SimGraph to propagate payments on their behalf.

`

These structs are primarily used to provide send/track payment APIs, receiving updates on the state of their payments from SimGraph.

Channel State Machine

Implementation of channel state is broken down into three layers:

Channel Policy: representation of the directional policy of a participant (fees etc)
Channel State: tracks the “live” state of the outgoing state of the channel
Simulated Channel: tracks state for each direction of the channel, and high level information

`

Each channel state is responsible for handling tracking of liquidity and HTLC limits in one direction, and the simulated channel is responsible for enforcing sanity checks across the channel (eg, that we don’t exceed our capacity).

An example state machine update is provided in the table below:

Step Alice Channel State Bob Channel State

Channel Opened by Alice Local_balance: 100_000 / In_Flight: nil Local_balance: 0 / In_Flight: Nil

Alice sends 100 sats to Bob Local_balance: 999_000 / In_Flight: 100 sats Local_balance: 0 / In_Flight: Nil

Alice payment succeeds Local_balance: 999_000 / In_Flight: nil Local_balance: 100 / In_Flight: Nil

Bob sends 50 sats to Alice Local_balance: 999_000 / In_Flight: nil Local_balance: 50 / In_Flight: 50

Bob payment fails Local_balance: 999_000 / In_Flight: nil Local_balance: 100 / In_Flight: nil

tl;dr

`

This commit adds a ChannelState struct which is used to track the policy and state of a channel in the *outgoing* direction. This will be used to check forwards against the node's advertised policy and track the movement of outgoing HTLCs through the channel. Note that we choose to implement this state *unidirectionally*, so a single channel will be represented by two ChannelState structs (one in each direction).

Add a single representation of a simulated lightning channel which uses our state representation to add and remove htlcs. For simplicity, each side of the channel is represented as a separate state, with the only interaction between the two through the changes to local balance that happen when we settle htlcs.

Add an implementation of the LightningNode trait that represents the underlying lightning node. This implementation is intentionally kept simple, depending on some SimNetwork trait to handle the mechanics of actually simulating the flow of payments through a simulated graph.

We want to be able to distinguish between expected and critical payment errors in our simulated payments. An expected error occurs due to a lightning-related failure (such as running out of liquidity), and a critical one happens because something has gone wrong with our simulator (for example, an assertion failure about balances). This commit adds an some utilities to ForwardingError to make this distinction and display errors properly.

Add an implementation of our SimNetwork trait that will do the heavy lifting of propagating htlcs through a simulated network.

fresheyes-staging-bot