@ -8,29 +8,33 @@ exploits.
It is designed to implement the lightning protocol as specified in
[various BOLTs ](https://github.com/lightningnetwork/lightning-rfc ).
Getting Started
---------------
It's in C, to encourage alternate implementations. It uses the [Linux
coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html).
It's in C, to encourage alternate implementations.
It uses the [Linux coding style][style].
Patches are welcome!
[style]: https://www.kernel.org/doc/html/v4.10/process/coding-style.html
To read the code, you'll probably need to understand ccan/tal: it's a
hierarchical memory allocator, where each allocation has a parent, and
thus lifetimes are grouped. eg. a `struct bitcoin_tx` has a pointer
to an array of `struct bitcoin_tx_input` ; they are allocated off the
`struct bitcoind_tx` , so freeing the `struct bitcoind_tx` frees them
all. Tal also supports destructors, which are usually used to remove
things from lists, etc.
`struct bitcoind_tx` , so freeing the `struct bitcoind_tx` frees them all.
Tal also supports destructors, which are usually used to remove things
from lists, etc.
Some routines use take(): take() marks a pointer as to be consumed
(e.g. freed automatically before return) by a called function. It can
safely accept NULL pointers. Functions whose prototype in headers has
the macro TAKES can have the specific argument as a take() call. Use
this sparingly, as it can be very confusing.
(e.g. freed automatically before return) by a called function.
It can safely accept NULL pointers.
Functions whose prototype in headers has the macro TAKES can have the
specific argument as a take() call.
Use this sparingly, as it can be very confusing.
The more complex daemons use async io (ccan/io): you register callbacks and they
happen once I/O is available, then you return what to do next. This
does not use threads, so the code flow is generally fairly simple.
The more complex daemons use async io (ccan/io): you register callbacks
and they happen once I/O is available, then you return what to do next.
This does not use threads, so the code flow is generally fairly simple.
The Components
--------------
@ -57,7 +61,8 @@ Here's a list of parts, with notes:
(as used by check-source)
- generate-wire.py: generate marshal/unmarshal routines from
extracts from BOLT specs, and as specified by subdaemons.
- mockup.sh / update-mocks.sh: tools to generate mock functions for unit tests.
- mockup.sh / update-mocks.sh: tools to generate mock functions for
unit tests.
* devtools/ - tools for developers
- Currently just bolt11-cli for decoding bolt11
@ -70,40 +75,47 @@ Here's a list of parts, with notes:
* cli/ - commandline utility to control lightning daemon.
* lightningd/ - master daemon which controls the subdaemons and passes peer file descriptors between them.
* lightningd/ - master daemon which controls the subdaemons and passes
peer file descriptors between them.
* wallet/ - database code used by master for tracking what's happening.
* hsmd/ - daemon which looks after the cryptographic secret, and performs commitment signing.
* hsmd/ - daemon which looks after the cryptographic secret, and performs
commitment signing.
* gossipd/ - daemon to chat to peers which don't have any channels, and maintains routing information and broadcasts gossip.
* gossipd/ - daemon to chat to peers which don't have any channels,
and maintains routing information and broadcasts gossip.
* openingd/ - daemon to open a channel for a single peer.
* channeld/ - daemon to operate a single peer once channel is operating normally.
* channeld/ - daemon to operate a single peer once channel is operating
normally.
* closingd/ - daemon to handle mutual closing negotiation with a single peer.
* onchaind/ - daemon to hand a single channel which has had its funding transaction spent.
* onchaind/ - daemon to hand a single channel which has had its funding
transaction spent.
Debugging
---------
You can debug crashing subdaemons with the argument
`--dev-debugger=lightning_channeld` , where `channeld` is the subdaemon name. It
will print out (to stderr) a command such as:
`--dev-debugger=lightning_channeld` , where `channeld` is the subdaemon name.
It will print out (to stderr) a command such as:
gdb -ex 'attach 22398' -ex 'p debugger_connected=1' lightningd/lightning_hsmd
Run this command to start debugging. You may need to type `return` one more time
to exit the infinite while loop, otherwise you can type `continue` to begin.
Run this command to start debugging.
You may need to type `return` one more time to exit the infinite while
loop, otherwise you can type `continue` to begin.
Database
--------
c-lightning state is persisted in `lightning-dir` . It is a sqlite database
stored in the `lightningd.sqlite3` file, typically under `~/.lightning` . You can
run queries against this file like so:
c-lightning state is persisted in `lightning-dir` .
It is a sqlite database stored in the `lightningd.sqlite3` file, typically
under `~/.lightning` .
You can run queries against this file like so:
$ sqlite3 ~/.lightning/lightningd.sqlite3 "SELECT HEX(prev_out_tx), prev_out_index, status FROM outputs"
@ -121,8 +133,8 @@ Or you can launch into the sqlite3 repl and check things out from there:
Some data is stored as raw bytes, use `HEX(column)` to pretty print these.
Make sure that clightning is not running when you query the database, as some
queries may lock the database and cause crashes.
Make sure that clightning is not running when you query the database,
as some queries may lock the database and cause crashes.
#### Common variables
Table `vars` contains global variables used by lightning node.
@ -141,8 +153,10 @@ Variables:
* `next_pay_index` next resolved invoice counter that will get assigned.
* `bip32_max_index` last wallet derivation counter.
Note: Each time `newaddr` command is called, `bip32_max_index` counter is increased to the last derivation index.
Each address generated after `bip32_max_index` is not included as lightning funds.
Note: Each time `newaddr` command is called, `bip32_max_index` counter
is increased to the last derivation index.
Each address generated after `bip32_max_index` is not included as
lightning funds.
Testing
@ -156,24 +170,28 @@ valgrind installed, and build with DEVELOPER=1 (currently the default).
exists (currently disabled, since BOLTs are being re-edited).
* unit tests - run by `make check` , these are `run-*.c` files in test/
subdirectories which can test routines inside C source files. You
should insert `/* AUTOGENERATED MOCKS START */` and `/* AUTOGENERATED MOCKS END */`
lines, and `make update-mocks` will automatically generate stub functions
which will allow you to link (which will conveniently crash if they're called).
subdirectories which can test routines inside C source files.
You should insert `/* AUTOGENERATED MOCKS START */` and
`/* AUTOGENERATED MOCKS END */` lines, and `make update-mocks`
will automatically generate stub functions which will allow you to
link (which will conveniently crash if they're called).
* blackbox tests - run by `make check` or directly as
`PYTHONPATH=contrib/pylightning DEVELOPER=1 python3 tests/test_lightningd.py -f` .
You can run these much faster by putting `NO_VALGRIND=1` after DEVELOPER=1, or
after `make check` , which has the added bonus of doing memory leak detection.
You can also append `LightningDTests.TESTNAME` to run a single test.
`PYTHONPATH=contrib/pylightning DEVELOPER=1 python3
tests/test_lightningd.py -f`.
You can run these much faster by putting `NO_VALGRIND=1` after
DEVELOPER=1, or after `make check` , which has the added bonus of doing
memory leak detection. You can also append `LightningDTests.TESTNAME`
to run a single test.
Our Travis CI instance (see `.travis.yml` ) runs all these for each pull request.
Our Travis CI instance (see `.travis.yml` ) runs all these for each
pull request.
Subtleties
----------
There are a few subtleties you should be aware of as you modify deeper parts
of the code:
There are a few subtleties you should be aware of as you modify deeper
parts of the code:
* `structeq` will not work on some structures.
For example, it will not work with `struct short_channel_id` --- use
@ -191,7 +209,8 @@ of the code:
Further Information
-------------------
Feel free to ask questions on the lightning-dev mailing list, or on #c -lightning on IRC, or email me at rusty@rustcorp.com.au.
Feel free to ask questions on the lightning-dev mailing list, or on
#c -lightning on IRC, or email me at rusty@rustcorp.com.au.
Cheers!< br >
Rusty.
Jan Sarenik
7 years ago
Christian Decker