diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index a3ba67343..000000000 --- a/doc/conf.py +++ /dev/null @@ -1,246 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# core-lightning documentation build configuration file, created by -# sphinx-quickstart on Thu Feb 1 00:24:47 2018. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -from datetime import datetime -import subprocess - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.mathjax', - 'sphinx.ext.githubpages', - 'sphinx.ext.graphviz', - 'sphinx.ext.autodoc', - 'recommonmark', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ['.rst', '.md'] - -# The encoding of source files. -# -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'core-lightning' -author = 'Core Lightning Developers' -copyright = datetime.now().strftime('2015 — %Y, {}'.format(author)) - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = subprocess.check_output('git describe --always --dirty=-modded --abbrev=7'.split()).decode('ASCII') -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = 'en' - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# -# today = '' -# -# Else, today_fmt is used as the format for a strftime call. -# -today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'release-notes'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -# -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# -# show_authors = False - -# The name of the Pygments style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. -# " v documentation" by default. -# -html_title = 'Core Lightning ' + version - -# A shorter title for the navigation bar. Default is the same as html_title. -# -html_short_title = html_title - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# -# html_logo = None - -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# -# html_extra_path = [] - -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# -html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# -# html_additional_pages = {} - -# If false, no module index is generated. -# -# html_domain_indices = True - -# If false, no index is generated. -# -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# -html_show_sourcelink = False - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' -# -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -# -# html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -# -# html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'core-lightningdoc' diff --git a/doc/dev/contributors/codegen.md b/doc/dev/contributors/codegen.md deleted file mode 100644 index 3c05d4fd7..000000000 --- a/doc/dev/contributors/codegen.md +++ /dev/null @@ -1,138 +0,0 @@ -# Code Generation - -The CLN project has a multitude of interfaces, most of which are -generated from an abstract schema: - - - Wire format for peer-to-peer communication: this is the binary - format that is specific by the [LN spec][spec]. It uses the - [generate-wire.py][generate-wire.py] script to parse the (faux) CSV - files that are automatically extrated from the specification and - writes C source code files that are then used internally to encode - and decode messages, as well as provide print functions for the - messages. - - - Wire format for inter-daemon communication: CLN follows a - multi-daemon architecture, making communication explicit across - daemons. For this inter-daemon communication we use a slightly - altered message format from the [LN spec][spec]. The changes are 1) - addition of FD passing semantics to allow establishing a new - connection between daemons (communication uses - [socketpair][socketpair]s, so no `connect`), and 2) change the - message length prefix from `u16` to `u32`, allowing for messages - larger than 65Kb. The CSV files are with the respective sub-daemon - and also use [generate-wire.py][generate-wire.py] to generate - encoding, decoding and printing functions. - - - We describe the JSON-RPC using [JSON Schema][jschema] in the - [`doc/schemas`][doc-schemas] directory. Each method has a - `.request.json` for the request message, and a `.schema.json` for - the response (the mismatch is historical and will eventually be - addressed). During tests the `pytest` target will verify responses, - however the JSON-RPC methods are _not_ generated (yet?). We do - generate various client stubs for languages, using the - [`msggen`][msggen] tool. More on the generated stubs and utilities - below. - -## Man pages - -The [manpages][man] are partially generated from the JSON schemas -using the [`fromschema`][fromschema] tool. It reads the request schema -and fills in the manpage between two markers: - -```markdown -[comment]: # (GENERATE-FROM-SCHEMA-START) -... -[comment]: # (GENERATE-FROM-SCHEMA-END) -``` - -!!! note - - Some of this functionality overlaps with [`msggen`][msggen] (parsing the Schemas) - and [blockreplace.py][blockreplace.py] (filling in the template). It - is likely that this will eventually be merged. - -[blockreplace.py]: https://github.com/ElementsProject/lightning/blob/master/devtools/blockreplace.py -[man]: ../../reference/ -[fromschema]: https://github.com/ElementsProject/lightning/blob/master/tools/fromschema.py - -## `msggen` - -`msggen` is used to generate JSON-RPC client stubs, and converters -between in-memory formats and the JSON format. In addition, by -chaining some of these we can expose a [grpc][grpc] interface that -matches the JSON-RPC interface. This conversion chain is implemented -in the [grpc-plugin][grpc-plugin] - - -
-```mermaid -graph LR - A[JSON schema]; - A --> B[cln-rpc]; - B --> B1[Request Structs]; - B --> B2[Response Structs]; - B --> B3[Method stubs]; - - A --> C[cln-grpc]; - C --> C1[Protobuf File]; - C --> C2[In-memory conversion]; - C --> C3[Service Implementation]; -``` -
Artifacts generated from the JSON Schemas using `msggen`
-
- -### `cln-rpc` - -We use `msggen` to generate the Rust bindings crate -[`cln-rpc`][cln-rpc]. These bindings contain the stubs for the -JSON-RPC methods, as well as types for the request and response -structs. The [generator code][cln-rpc-gen] maps each abstract JSON-RPC -type to a Rust type, minimizing size (e.g., binary data is -hex-decoded). - -The calling pattern follows the `call(req_obj) -> resp_obj` format, -and the individual arguments are not expanded. For more ergonomic -handling of generic requests and responses we also define the -`Request` and `Response` enumerations, so you can hand them to a -generic function without having to resort to dynamic dispatch. - -The remainder of the crate implements an async/await JSON-RPC client, -that can deal with the Unix Domain Socket [transport][man:json-rpc] -used by CLN. - -### `cln-grpc` - -The `cln-grpc` crate is mostly used to provide the primitives to build -the `grpc-plugin`. As mentioned above, the grpc functionality relies on a chain of generated parts: - - - First `msggen` is used to generate the [protobuf file][proto], - containing the service definition with the method stubs, and the types - referenced by those stubs. - - Next it generates the `convert.rs` file which is used to convert - the structs for in-memory representation from `cln-rpc` into the - corresponding protobuf structs. - - Finally `msggen` generates the `server.rs` file which can be bound - to a grpc endpoint listening for incoming grpc requests, and it - will convert the request and forward it to the JSON-RPC. Upon - receiving the response it gets converted back into a grpc response - and sent back. - -```mermaid -graph LR - A[grpc client] --> B[grpc server] -->|convert.rs| C[cln-rpc] --> D[lightningd]; - D --> C -->|convert.rs| B --> A; -``` - -[proto]: https://github.com/ElementsProject/lightning/blob/master/cln-grpc/proto/node.proto -[man:json-rpc]: ../../lightningd-rpc.7.md -[cln-rpc-gen]: https://github.com/ElementsProject/lightning/blob/master/contrib/msggen/msggen/gen/rust.py -[spec]: https://github.com/lightning/bolts -[generate-wire.py]: https://github.com/ElementsProject/lightning/blob/master/tools/generate-wire.py -[socketpair]: https://man7.org/linux/man-pages/man2/socketpair.2.html -[jschema]: https://json-schema.org/ -[doc-schemas]: https://github.com/ElementsProject/lightning/tree/master/doc/schemas -[msggen]: https://github.com/ElementsProject/lightning/tree/master/contrib/msggen -[grpc]: https://grpc.io/ -[cln-grpc]: https://docs.rs/cln-grpc/0.1.1/cln_grpc/ -[grpc-plugin]: https://github.com/ElementsProject/lightning/tree/master/plugins/grpc-plugin -[cln-rpc]: https://github.com/ElementsProject/lightning/tree/master/cln-rpc diff --git a/doc/dev/contributors/index.md b/doc/dev/contributors/index.md deleted file mode 100644 index 4796167e6..000000000 --- a/doc/dev/contributors/index.md +++ /dev/null @@ -1 +0,0 @@ -# Developer Documentation diff --git a/doc/dev/index.md b/doc/dev/index.md deleted file mode 100644 index 4796167e6..000000000 --- a/doc/dev/index.md +++ /dev/null @@ -1 +0,0 @@ -# Developer Documentation diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index f8a931341..000000000 --- a/doc/index.md +++ /dev/null @@ -1,10 +0,0 @@ - -Core Lightning (previously c-lightning) is a lightweight, highly -customizable and [standard compliant][std] implementation of the -Lightning Network protocol. - -This documentation site will walk you through your first steps, teach -you how to develop on top of CLN and act as a reference for veteran -programmers. - -[std]: https://github.com/lightning/bolts diff --git a/doc/reference/index.md b/doc/reference/index.md deleted file mode 100644 index aa7d2c531..000000000 --- a/doc/reference/index.md +++ /dev/null @@ -1 +0,0 @@ -# Core-Lightning References diff --git a/doc/release-notes/release-0.6.md b/doc/release-notes/release-0.6.md deleted file mode 100644 index d84c4cea2..000000000 --- a/doc/release-notes/release-0.6.md +++ /dev/null @@ -1,109 +0,0 @@ -# Release Announce for 0.6 -## a.k.a. "I Accidentally The Smart Contract" - -The long wait is over: the c-lightning team is excited to announce the 0.6 release of -[c-lightning][clightning], an important milestone for the project. This complete rewrite of the previous implementation is the first fully specification-compliant release of c-lightning. It migrates away from the protocol used while designing the specification and toward a new architecture that is modular and extensible, to better adapt to your needs and your infrastructure. - -## New Features - -While there are far too many new features in the 0.6 release to list, the following are the most interesting and impactful: - - - __Lightweight nodes__: Previous releases required a full `bitcoind` node - running alongside c-lightning, to provide access to the Bitcoin network. This release still requires the `bitcoin-cli` utility to be present, but it - can now talk to remote nodes as well, including some lightweight nodes such - as [`spruned`][spruned]. This makes it possible to run a c-lightning node on - Raspberry Pis as well as other low-powered devices. - - The __gossip protocol__ has been updated to use a more lightweight bandwidth mechanism that - asks for specific information, rather than exchanging full network - Views as the previous release did. This is particular important for low-powered and mobile devices that - would otherwise spend a lot of bandwidth and energy downloading and - verifying information they already have. - - __API stability__: The c-lightning - JSON-RPC interface and supporting libraries have been redesigned in order to minimize - changes in future releases. This API stability should make it easy for other - projects to build on top of c-lightning because we will support this version of - the API for the foreseeable future, maintaining backward compatibility, - should we introduce any changes. - - __Wallet and sync__: c-lightning now includes a full-fledged wallet that - manages both on-chain and off-chain funds. There is no more raw - transaction handling! All funds are automatically tracked and returned to the - internal wallet as soon as possible, with no user interaction required. In - addition the blockchain tracking now maintains an internal view of the blockchain, ending long blockchain rescans. - - __TOR support__: c-lightning now supports connecting to nodes over the - TOR network, auto-registering as a hidden service, and accepting - incoming connections over TOR. - - The __payment logic__ has undergone a major overhaul to support automatic retries - for routing failures, randomization of route selection, and better feedback about - the current state of a payment. - - And as always: performance, performance, performance. - -## Flexibility through Modularity - -The c-lightning architecture is based on a number of independent communicating -processes, each with its own responsibilities. This allows better integration into -your infrastructure and better adaptation to your needs. Two -daemons that are global for all channels,`gossipd` and `hsmd`, are of particular note because of their modular design - -`gossipd` manages a local view of the network and is tasked with finding a path -from the source of a payment to its destination. The default implementation -attempts to find a route with reasonable tradeoffs between fees, timeouts, and -stability. It also obfuscates the route by selecting randomly among a -number of candidate routes and tweaking the amounts and timeouts in order to -conceal the endpoints of a payment. The default implementation can easily be -switched out if you have particular routing requirements or want to -enforce a specific routing policy, such as always selecting the route with the lowest -timeouts or the lowest fees. - -`hsmd` manages all operations that touch cryptographic materials and controls -the funds in the channel. It is the sole subsystem that has access to the node's -private key. This means that other subsystems do not hold any private -information and must communicate with the `hsmd` daemon to sign or decrypt -anything. Centralizing the cryptographic operations in this manner reduces the -surface that needs to be secured and opens up a number of interesting -applications. While the default `hsmd` implementation already provides good -security through process separation and the ability to further secure it via OS -level security, e.g., SELinux and AppArmor, it can be easily replaced with an implementation that talks to a physical HSM. Replacing the `hsmd` -implementation furthermore allows headless operation, e.g., running a -c-lightning node at home, with a paired mobile app managing the private keys -and initiating payments or creating invoices. - -This separation of c-lightning functionality into multiple daemons is not only a big -improvement in flexibility, but also a robust improvement to node security, as it ensures that an attacker cannot directly -interface with anything that touches the private keys. Each subsystem -independently verifies the consistency of the internal state, disconnecting a -peer and killing its process if any inconsistency is detected. The multi-daemon -architecture also enables the use of Docker, SELinux and AppArmor to lock down -what information each daemon can access and what actions they can perform. - -## What's Next? - -Our work with c-lightning is far from done; we are constantly working on -[features][features] and [enhancements][enhancements], as well as improvements to -performance, stability and usability. Didn’t find your favorite feature? Have -some feedback that might be helpful? Why not file an [issue on -Github][gh-issue], drop us a line on the [mailing list][ml], or [contact us on -IRC][irc]. - -In parallel we are also contributing to the advancement of the Lightning specification -itself and are actively researching what the next iteration of the protocol could -look like through initiatives like our [eltoo][eltoo] proposal and upstream -Bitcoin proposals such as [`SIGHASH_NOINPUT`][sighash-noinput]. - -We'd like to thank the many contributors who have not only contributed code to -c-lightning, but also those who were #reckless enough to test and give feedback -about what works and what could be improved. And finally, we'd like to thank the -other Lightning Network teams, ACINQ and Lightning Labs, as well as all individual contributors -that pitched in to make the Lightning Network community such a pleasant, collaborative and open -environment! - -[spruned]: https://github.com/gdassori/spruned -[clightning]: https://github.com/ElementsProject/lightning -[features]: https://github.com/ElementsProject/lightning/issues?q=is%3Aissue+is%3Aopen+label%3Afeature -[enhancements]: https://github.com/ElementsProject/lightning/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement -[irc]: irc://c-lightning@irc.freenode.net -[ml]: mailto:c-lightning@lists.ozlabs.org -[gh-issue]: https://github.com/ElementsProject/lightning/issues/new -[sighash-noinput]: https://github.com/bitcoin/bips/blob/master/bip-0118.mediawiki -[eltoo]: https://blockstream.com/2018/04/30/eltoo-next-lightning.html - - diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index 7032599c9..000000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -mkdocs-exclude -mkdocs-material -mkdocs -Jinja2==3.1.0 diff --git a/doc/user/index.md b/doc/user/index.md deleted file mode 100644 index e69de29bb..000000000