lightning/HACKING.md

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
    • controlled_time: support for dev-mocktime to alter time.
    • 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.