Doppler (A Lightning Domain-Specific Language)

• GOAL: Create a DSL for Lightning that enables users to easily experiment with and test against various Lightning implementations. Whether it's for discovery testing, inclusion in a comprehensive integration testing suite, or simply investigating the interactions between different components. Given the potential occurrence of intriguing and unique issues across different implementations of Lightning, this project aims to simplify the lives of application developers reliant on the network.

The DSL should empower developers to compose a concise script that configures an entire cluster of nodes running a single docker network, even if they are of different implementation types, to suit precise testing requirements. This should provide a sensation similar to working with a set of Lego blocks, where all the necessary components are at your fingertips, ready to be assembled based on the idea at hand.

Additionally, this DSL can be used against a cluster of remote LND nodes (more implementations will follow) to generate activity across them. This could be payments or channel related activity at the moment, but more work can be done to further expand this to include starting and stopping the remote nodes as well as funding them from a configured faucet. Still would not recommend running these doppler files on a mainnet cluster of nodes, but we wont stop you from being reckless 😉

Installing

Requires:

• docker-compose:
  • https://docs.docker.com/compose/install/#scenario-one-install-docker-desktop
• nvm:
  • https://github.com/nvm-sh/nvm

Download installing script

  curl --proto '=https' --tlsv1.2 -LsSf "https://raw.githubusercontent.com/tee8z/doppler/refs/heads/master/doppler-installer.sh" > doppler_installer.sh

  chmod +x doppler_installer.sh

Execute installer with a release tag

  ./doppler_installer.sh <release tag to install>

Running after install:

To run with UI (navigate to 0.0.0.0:3000 in your browser to view the UI)

  cd $HOME/.doppler/<release tag> && node ./build

To run as cli

  cd $HOME/.doppler && doppler -h

More information on how to use this tool can be found here: USAGE.md

Supports:

• creating a cluster of bitcoind nodes
• setting up one or many as miners on a provided time interval
• setting up and funding a cluster of LND nodes, backed by a specified bitcoind node
• outputing the cluster configuration as a docker-compose
• making all the logs/data of the nodes available to the running of doppler
• allowing to set values in LND's native configuration file
• setup all the networking deterministically
• OPEN_CHANNEL
• SEND_LN (amp/keysend/bolt11 via subcommand)
• SEND_ONCHAIN (only taproot addresses)
• LOOP a set of commands over an optional interval
• CLOSE_CHANNEL
• support multiple node implementations (supports LND, CoreLN, Eclair)
• add a cluster level UI to see how all the nodes connect (comes from https://github.com/litch/lightning-conformance/tree/master/operator)
• SETTLE_HOLD_LN -- only works for LND nodes
• SEND_HOLD_LN -- only works for LND nodes
• SEND_COINS -- to send from a btc miner to any of the L2 node types (helpful in making sure there are enough funds for channels to open)
• FORCE_CLOSE_CHANNEL - forces an L2 node to close a give channel
• TAG - allows for hodl invoices payment hashes to be stored between doppler files being run, enable a shared state between files (these will be used in the future to enable closing a specific channel with another node instead of just picking one at random that the two nodes share)
• STOP_BTC - stops a BTC container
• START_BTC - starts a BTC container
• STOP_LN - stops a LN container
• START_LN - starts a LN container
• WAIT BLOCKS - uses one of the hooked up LND nodes and waits to proceed in the script until a certain block height is reached

Interesting Simulations

• Chain of force closures due to an inflight htlc: force_closures
• Executing a successful hodl invoice in LND nodes: hodl_invoice
• Using external LND nodes and generating payment activity: external_nodes
• Running with multiple versions of lightning implementations: different_versions

Acknowledgments

• Thank you polar for having such easy docker images to work with
• Thank you litch for creating lightning-conformance which helped inspire this project
• Thank you w3irdrobot for getting this project started and helping pick the tool to build the grammar in rust

Disclaimer

• This is very much a work in progress, but feel free to use what works today and PR's are welcome!