From 9da5abc39c29941b7b3c0889cabef85dd94cdc95 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 29 Aug 2017 14:45:39 +0930 Subject: [PATCH] docs: update, move into doc/ Signed-off-by: Rusty Russell --- HACKING.md | 84 ------------------------------------ README.md | 4 +- TODO.md | 39 ----------------- doc/HACKING.md | 79 +++++++++++++++++++++++++++++++++ INSTALL.md => doc/INSTALL.md | 0 5 files changed, 81 insertions(+), 125 deletions(-) delete mode 100644 HACKING.md delete mode 100644 TODO.md create mode 100644 doc/HACKING.md rename INSTALL.md => doc/INSTALL.md (100%) diff --git a/HACKING.md b/HACKING.md deleted file mode 100644 index 34039421d..000000000 --- a/HACKING.md +++ /dev/null @@ -1,84 +0,0 @@ -Welcome, fellow coder! - -This repository contains a prototype for testing the lightning protocols. - -Getting Started ---------------- -It's in C, to encourage alternate implementations. It uses the Linux -coding style. Patches are welcome! See the TODO.md file if you want -ideas. - -To read the code, you'll probably need to understand ccan/tal: it's a -heirarchical 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. - -The daemon uses 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. - -Here's a list of parts, with notes: - -* ccan - useful routines from http://ccodearchive.net - - Use make update-ccan to update it. - - Use make update-ccan CCAN_NEW="mod1 mod2..." to add modules - -* bitcoin/ - bitcoin script, signature and transaction routines. - - Not a complete set, but enough for our purposes. - -* secp256k1/ - a copy of libsecp256k1. - - TODO: Replace this will the library once 1.0 is well distributed. - -* test/ - A few standalone test programs - - test_onion: C code to generate and decode the routing onion (Obsolete; will replace with Sphynx!) - - test_state_coverage: routine to test state machine. - -* daemon/ - The start of a lightningd daemon and lightning-cli - - Networking and comms: - - cryptopkt: cryptographic handshake and comms routines. - - dns: async dns lookup - - netaddr: wrapper type for network addresses. - - - JSON and command support: - - jsmn/ : a "minimalistic JSON parser" from http://zserge.com/jsmn.html - - json: simple wrappers around jsmn for parsing and creating JSON - - jsonrpc: routines for handing JSON commands (async). - - lightning-cli: simple lightning command line client. - - - Misc: - - configdir: support for ~/.lightning/config - - log: logging routines - - pseudorand: pseudorandom wrapper - - secrets: routines for using secret keys. - - timeout: timer support. - - - Dealing with bitcoin events: - - bitcoind: communication with bitcoind to monitor/send txs. - - watch: wrapper for watching specific events. - - - Core code: - - lightningd: main routine for lightning - - packets: per-peer packet creation and acceptance routines - - peer: peer routines and data structure. - -* Top level: - - funding: tracking of state of a channel, including feesplit logic. - - state: core state machine for the lightning protocol. - - Helpers for lightning-specific transactions - - close_tx: mutual close transaction - - commit_tx: commit transaction (optionally with htlcs) - - permute_tx: code to permute transactions outputs for anon - - Various helper routines: - - find_p2sh_out: helper to find a given tx output. - - gen_state_names: source generator for enum names. - - opt_bits: commandline parser for "bits" (100 satoshi) - - protobuf_convert: conversion to/from protobufs. - - version: helper to print the version and build features. - -Feel free to ask questions on the lightning-dev mailing list, or on #lightning-dev on IRC, or email me at rusty@rustcorp.com.au. - -Cheers!
-Rusty. diff --git a/README.md b/README.md index 07b0b4a22..69f0ef9fe 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ This implementation is still very much work in progress, and, although it can be We do our best to identify and fix problems, and implement missing feature. Any help testing the implementation, reporting bugs, or helping with outstanding issues is very welcome. -Don't hesitate to reach out to us on IRC at [#lightning-dev @ freenode.net](http://webchat.freenode.net/?channels=%23lightning-dev) or on the mailing list [lightning-dev@lists.linuxfoundation.org](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev). +Don't hesitate to reach out to us on IRC at [#lightning-dev @ freenode.net](http://webchat.freenode.net/?channels=%23lightning-dev), [#c-lightning @ freenode.net](http://webchat.freenode.net/?channels=%23c-lightning), or on the mailing list [lightning-dev@lists.linuxfoundation.org](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev). ## Getting Started @@ -19,7 +19,7 @@ c-lightning currently only works on Linux (and possibly Mac OS with some tweakin ### Installation -Please refer to the [installation documentation](INSTALL.md) for detailed instructions. +Please refer to the [installation documentation](doc/INSTALL.md) for detailed instructions. For the impatient here's the gist of it for Ubuntu and Debian: ``` diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 6518abfc4..000000000 --- a/TODO.md +++ /dev/null @@ -1,39 +0,0 @@ -# Looking for things to hack on? # - -## Cleanups ## - -* Remove our specific libsecp256k1 in secp256k1/ and use the installed one. - -## Minor improvements ## - -* Make `json_get_params` fail if unknown parameters are specified by user. -* Print backtrace in `log_crash` -* When unpacking a packet, reject any with an unknown odd-numbered field as per BOLT #2. -* Limit total number of peers in `new_peer`, or at least in `peer_connected_in`. -* logging: add IO logging for peers. -* Add `history` RPC command which shows all prior commit txs. -* Improve `getpeers` to show status of peers when connecting, DNS lookups etc. -* Add pings to protocol - * Timeout a peer if they don't respond in a given time (eg. 2 pings) - -## Testing: ## - -* Add more unit tests in bitcoin/test and daemon/test -* Test more scenarios with daemon/test/test.sh, and split it up. -* Implement compile-time crypto-free mode - * Implement canned conversation files for fuzz testing (eg AFL). -* Write canned input/output test cases for various conversations, and - include them in a form suitable for other implementations to test. - -## Major improvements: ## - -* (MAJOR) Implement onion - * (MAJOR) Implement failure message encryption - -## Other ## - -* Grep for other FIXMEs and fix one :) -* Look on https://github.com/ElementsProject/lightning/issues - -Happy hacking!
-Rusty. diff --git a/doc/HACKING.md b/doc/HACKING.md new file mode 100644 index 000000000..fcbb18c59 --- /dev/null +++ b/doc/HACKING.md @@ -0,0 +1,79 @@ +Welcome, fellow coder! + +This repository contains a code to run a lightning protocol daemon. +It's broken into subdaemons, with the idea being that we can add more +layers of separation between different clients and extra barriers to +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. Patches are welcome! + +To read the code, you'll probably need to understand ccan/tal: it's a +heirarchical 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. + +The daemons mostly 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. + +Here's a list of parts, with notes: + +* ccan - useful routines from http://ccodearchive.net + - Use make update-ccan to update it. + - Use make update-ccan CCAN_NEW="mod1 mod2..." to add modules + +* bitcoin/ - bitcoin script, signature and transaction routines. + - Not a complete set, but enough for our purposes. + +* external/ - external libararies from other sources + - libsodium - encryption library (should be replaced soon with built-in) + - libwally-core - bitcoin helper library + - secp256k1 - bitcoin curve encryption library within libwally-core + - jsmn - tiny JSON parsing helper + - libbase58 - base58 address encoding/decoding library. + +* tools/ - tools for building + - check-bolt.c: check the source code contains correct BOLT quotes + (as used by check-source) + - generate-wire.py: generate marshal/unmarshal routines from + extracts from BOLT specs, and as specified by subdaemons. + +* contrib/ - python support and other stuff which doesn't belong :) + +* wire/ - basic marshalling/un + +* common/ - routines needed by any two or more of the directories below + +* cli/ - commandline utility to control lightning daemon. + +* 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. + +* handshaked/ - daemon to establish a single cryptographic handshake a-la BOLT 8. + +* 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. + +* 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. + +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!
+Rusty. diff --git a/INSTALL.md b/doc/INSTALL.md similarity index 100% rename from INSTALL.md rename to doc/INSTALL.md