sphinx-doc: Initial checkin

Signed-off-by: Christian Decker <decker.christian@gmail.com>

doc/development.rst

@@ -0,0 +1,107 @@
+Development
+***********
+
+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>`_.
+Patches are welcome!
+
+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.
+
+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.
+
+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.
+
+Channel State Machine
+#####################
+
+The following is a state transition diagram that a connection and an eventual channel move through:
+
+.. graphviz::
+
+   digraph foo {
+      subgraph gossipd {
+        UNINITIALIZED;
+        GOSSIPING;
+	label = "gossipd";
+	color=lightgrey;
+      }
+      "GOSSIPING" -> "UNINITIALIZED";
+      "UNINITIALIZED" -> "OPENINGD" [ label="fundchannel" ];
+      "OPENINGD" -> "CHANNELD_AWAITING_LOCKIN";
+      "CHANNELD_AWAITING_LOCKIN" -> "CHANNELD_NORMAL" [ label="~6 confirmations" ];
+      "CHANNELD_NORMAL" -> "FUNDING_SPEND_SEEN";
+      "FUNDING_SPEND_SEEN" -> "ONCHAIND_OUR_UNILATERAL";
+      "FUNDING_SPEND_SEEN" -> "ONCHAIND_THEIR_UNILATERAL";
+      "CHANNELD_NORMAL" -> "CHANNELD_SHUTTING_DOWN";
+      "CHANNELD_SHUTTING_DOWN" -> "CLOSINGD_SIGEXCHANGE";
+      "CLOSINGD_SIGEXCHANGE" -> "CLOSINGD_COMPLETE";
+   }
+
+Code Structure
+##############
+
+The Components
+--------------
+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
+   - Do not edit this!  If you want a wrapper, add one to `common/utils.h`.
+* `bitcoin/` - bitcoin script, signature and transaction routines.
+   - Not a complete set, but enough for our purposes.
+* `external/` - external libraries from other sources
+   - `libbacktrace` - library to provide backtraces when things go wrong.
+   - `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.
+   - `mockup.sh`, `update-mocks.sh`: tools to generate mock functions for unit tests.
+* `devtools/`: tools for developers
+   - Currently just `bolt11-cli` for decoding bolt11
+* `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.
+* `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.
+
+Memory Management
+#################
+
+.. c:function:: tal(ctx, type)
+
+  `tal` allocate memory for the given `type` as a child of the given
+  `ctx`. That means that a future call to `tal_free(ctx)` or one of
+  the parents of `ctx` will cascade and free this allocation. In the
+  rate case of not having a parent context from which to allocate
+  from, you can pass in `NULL` as `ctx` to create a new rooted tree of
+  allocations.
+
+.. c:function:: tal_free(alloc)
+
+  `tal_free` is the counterpart of `tal` and will free any child
+  allocations of `alloc` recursively before freeing `alloc`
+  itself. Should `alloc` have a destructor attached, it'll get called
+  *before* the `alloc` itself is freed.

doc/faq.rst

@@ -0,0 +1,78 @@
+Frequently Asked Questions
+**************************
+
+My channel is stuck in state `x`, what can I do?
+================================================
+
+That depends very much on the state that the channel is in, but in
+most cases it should resolve itself after a while. Here's a list of
+states, their meaning and how long you can expect a channel to be in
+this state:
+
+ - ``CHANNELD_AWAITING_LOCKIN``: both endpoints of the channel have
+   cooperated to create a funding transaction and we are now waiting
+   for the channel to confirm. This usually takes 2 - 6 confirmations,
+   i.e., 1 hour on expectation, longer when there are many
+   transactions waiting to be confirmed. Both endpoints need to be
+   connected to progress from this state so they can exchange the
+   ``funding_locked`` message. If you lose connection just ``connect``
+   again. If the peer cannot be contacted again you can use ``dev-fail``
+   to unilaterally close the channel and recover funds.
+
+ - ``ONCHAIND_THEIR_UNILATERAL``: the other endpoint decided to
+   unilaterally close the channel. This can happen for a variety of
+   reasons: either side wasn't reachable anymore, the endpoints are
+   out of sync, or reconnection failed. This state will return your
+   funds to you immediately, but the channel may be in this state for
+   a long time until the timeouts for any ongoing payment clear. If
+   there are payments that were being negotiated this can take
+   approximately 150 confirmations, i.e., over a day. The exact time
+   depends on the parameters chosen when establishing the channel and
+   are likely overly protective, but better safe than sorry. No
+   further action is required to eventually clear the channel.
+
+ - ``ONCHAIND_OUR_UNILATERAL``: this is the counterpart of the previous
+   state. It means that your client decided to close the channel, due
+   to a timeout or because a reconnection failed. The channel will be
+   in this state until the unilateral close timeout expires (144
+   blocks by default), plus an eventual HTLC timeout should a payment
+   have been interrupted. There is no intervention needed at this
+   point, just wait for it to settle.
+
+
+If for any reason the channels are still stuck in a state after
+several days you can use the following procedure to close and forget
+the channel:
+
+ - First of all make sure to be running the latest version: pull the
+   latest ``master`` commit and recompile the binary. Then restart the
+   daemon and wait for it to startup.
+ - Check that the channel was confirmed in the first place: use
+   ``listpeers [peerid]`` to retrieve the funding transaction ID. Look
+   up the funding transaction ID on a block explorer (or your own
+   ``bitcoind`` instance) to see if that transaction ever made it to the
+   blockchain and was confirmed. If it was not confirmed, use
+   ``dev-rescan-outputs`` to get the funding transactions inputs back
+   and use ``dev-forget-channel [peerid]`` to remove the channel from
+   the channel from your daemon (this should no longer be necessary
+   since the issue that was causing this was patched).
+ - If the channel was confirmed, make sure you are connected to the
+   peer. Use ``listpeers [peerid]`` to check that its ``connected`` field
+   is ``true``. If not, try ``connect [peerid] [host] [port]`` to
+   reconnect.
+ - If the channel is in ``CLOSINGD_SIGEXCHANGE`` for a long time, and
+   the peer not connected you can unilaterally close the channel using
+   ``dev-fail [peerid]``, this will put you in ``ONCHAIND_OUT_UNILATERAL``
+   which will take a day to clear by default.
+
+Why can't I open a new channel to one of my peers?
+==================================================
+
+c-lightning currently only supports a single active channel per
+peer. That means that if there is an existing channel with the peer in
+state ``OPENINGD``, ``CHANNELD_AWAITING_LOCKIN``, ``CHANNELD_NORMAL``,
+``ONCHAIND_THEIR_UNILATERAL``, ``ONCHAIND_OUR_UNILATERAL``, or
+``CLOSINGD_SIGEXCHANGE``, you will not be able to opena new channel
+with that peer. The good news though is that, since lightning has
+multihop payments, you can open a channel with someone else, and you
+will still be able to route to that peer.

doc/index.rst

@@ -0,0 +1,25 @@
+.. c-lightning documentation master file, created by
+   sphinx-quickstart on Thu Feb  1 00:24:47 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to c-lightning's documentation!
+=======================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   faq
+   development
+   jsonrpc
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/jsonrpc.rst

@@ -0,0 +1,8 @@
+Building on top of c-lightning
+******************************
+
+JSON-RPC interface
+##################
+
+.. autoclass:: lightning.LightningRpc
+   :members: