diff --git a/DEV.md b/DEV.md index f0a074d5baf9..e28e9071cf45 100644 --- a/DEV.md +++ b/DEV.md @@ -1,4 +1,4 @@ -- Build with `--configure --enable-debugbuild` and `uv run make`. Much faster with `uv run make RUST=0`. +- Build with `./configure --enable-debugbuild` and `uv run make`. Much faster with `uv run make RUST=0`. - Env vars for tests: `RUST=0` (if RUST plugins were not built), `VALGRIND=0` (much faster), `TIMEOUT=10` to speed failures (or 100 if VALGRIND=1). - *gen.[ch] files are generated by the Makefile. - ccan/ is imported from ccan repo: PRs should go there, then `make update-ccan`. @@ -7,9 +7,9 @@ - assert-based unit tests can "#include ../file.c", OR add objects to Makefile targets: `make update-mocks` will regenerate mocks for functions from link errors. - Commits should be reviewable, bisectable, and include tests. Pattern: one commit adds a python test with @pytest.mark.xfail(strict=True), next commit fixes the problem and removes that line. - Commits which fix crashes or bug MUST quote the bug for later searches: do not rely on being able to find the bug report in future! -- Commits which create signficant user (not developer!) visible changes should have Changelog-(Added|Deprecated|Changed|Fixed|EXPERIMENTAL) for assembling CHANGELOG.md at release time. +- Commits which create significant user (not developer!) visible changes should have Changelog-(Added|Deprecated|Changed|Fixed|EXPERIMENTAL) for assembling CHANGELOG.md at release time. - Deprecations must use the deprecation infrastructure, and append to the table in doc/developers-guide/deprecated-features.md -- Adding a new JSON-RPC command requires the most careful design: start with doc/schemas/NAME.json and add doc/NAME.json to MARKDOWNPAGES in doc/Makefile. `make doc-all` will regen the rest. +- Adding a new JSON-RPC command requires the most careful design: start with doc/schemas/NAME.json and add doc/NAME.7 to MARKDOWNPAGES in doc/Makefile. `make doc-all` will regen the rest. - In pytest integration tests, name nodes l1, l2, etc in creation order. This matches the log prefixes they use (`lightningd-1` etc) and on test failure the logs and other ephemera will in /tmp/ltests-*/TESTNAME*/lightning-1/. - In pytest, never assert that a command raises an exception without specifying *exactly what* it raises! Use `with pytest.raises(RpcError, match='xxx'):` - tal_bytelen / tal_count of NULL are defined to be zero, and you may assume this. diff --git a/README.md b/README.md index 48445f7c5f6e..0824710ec582 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Core Lightning (previously c-lightning) is a lightweight, highly customizable an * [Sending and Receiving Payments](#sending-and-receiving-payments) * [Configuration File](#configuration-file) * [Further Information](#further-information) - * [FAQ](doc/FAQ.md) + * [FAQ](doc/node-operators-guide/faq.md) * [Pruning](#pruning) * [HD wallet encryption](#hd-wallet-encryption) * [Developers](#developers) @@ -37,7 +37,7 @@ Don't hesitate to reach out to us on the implementation-specific [mailing list][ ## Getting Started -Core Lightning only works on Linux and macOS, and requires a locally (or remotely) running `bitcoind` (version 25.0 or above) that is fully caught up with the network you're running on, and relays transactions (ie with `blocksonly=0`). +Core Lightning only works on Linux and macOS, and requires a locally (or remotely) running `bitcoind` (version 23.0 or above) that is fully caught up with the network you're running on, and relays transactions (ie with `blocksonly=0`). Pruning (`prune=n` option in `bitcoin.conf`) is partially supported, see [here](#pruning) for more details. ### Installation @@ -228,6 +228,5 @@ Developers wishing to contribute should start with the developer guide [here](do [releases]: https://github.com/ElementsProject/lightning/releases [dockerhub]: https://hub.docker.com/r/elementsproject/lightningd/ [jsonrpcspec]: https://www.jsonrpc.org/specification -[helpme-github]: https://github.com/lightningd/plugins/tree/master/helpme [actions-badge]: https://github.com/ElementsProject/lightning/workflows/Continuous%20Integration/badge.svg [actions]: https://github.com/ElementsProject/lightning/actions diff --git a/doc/beginners-guide/backup-and-recovery/recovery.md b/doc/beginners-guide/backup-and-recovery/recovery.md index 34b55e7bac16..a4a0e7e9de2c 100644 --- a/doc/beginners-guide/backup-and-recovery/recovery.md +++ b/doc/beginners-guide/backup-and-recovery/recovery.md @@ -16,7 +16,7 @@ privacy: - Copy the valid binary formatted `hsm_secret` into `$LIGHTNINGDIR` directory - Copy the latest `emergency.recover` backup file into the `$LIGHTNINGDIR` before starting up the node - Start `lightningd` - - Run `lightning-cli emergencyrecover` (RPC command)[https://docs.corelightning.org/reference/lightning-emergencyrecover] to recover all the channels on the node + - Run `lightning-cli emergencyrecover` (RPC command)[https://docs.corelightning.org/reference/emergencyrecover] to recover all the channels on the node - Wait until your peer force closes the channel and the node would automatically sweep the funds. This could take some time @@ -29,11 +29,11 @@ privacy: - Run `lightning-cli emergencyrecover` (RPC command)[https://docs.corelightning.org/reference/lightning-emergencyrecover] to recover all the channels on the node -> 🚧 +> 🚧 > > **Only** recover from database if you are sure that it is **latest**. > -> Snapshot-style backups of the lightningd database is **discouraged**, as _any_ loss of state may result in permanent loss of funds. +> Snapshot-style backups of the lightningd database is **discouraged**, as _any_ loss of state may result in permanent loss of funds. > > See the [penalty mechanism](https://github.com/lightning/bolts/blob/master/05-onchain.md#revoked-transaction-close-handling) for more details. diff --git a/doc/beginners-guide/beginners-guide.md b/doc/beginners-guide/beginners-guide.md index 430a28ad189b..c76680cb5512 100644 --- a/doc/beginners-guide/beginners-guide.md +++ b/doc/beginners-guide/beginners-guide.md @@ -57,4 +57,4 @@ Once you've started for the first time, there's a script called `contrib/bootstr There are also numerous plugins available for Core Lightning which add capabilities: see the [Plugins](doc:plugins) guide, and check out the plugin collection at: https://github.com/lightningd/plugins. -For a less reckless experience, you can encrypt the HD wallet seed: see [HD wallet encryption](doc:backup-and-recovery#hsm-secret-backup). +For a less reckless experience, you can encrypt the HD wallet seed: see [HD wallet encryption](doc:backup#hsm-secret-backup). diff --git a/doc/contribute-to-core-lightning/coding-style-guidelines.md b/doc/contribute-to-core-lightning/coding-style-guidelines.md index 3b5a04c4fce1..97a3b4f905e5 100644 --- a/doc/contribute-to-core-lightning/coding-style-guidelines.md +++ b/doc/contribute-to-core-lightning/coding-style-guidelines.md @@ -30,9 +30,9 @@ We have to stop somewhere. The two tools here are extracting deeply-indented co } ``` -## Tabs and indentaion +## Tabs and indentation -The C code uses TAB charaters with a visual indentation of 8 whitespaces. +The C code uses TAB characters with a visual indentation of 8 whitespaces. If you submit code for a review, make sure your editor knows this. When breaking a line with more than 80 characters, align parameters and arguments like so: diff --git a/doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md b/doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md index 110793183487..7adecc3c4c53 100644 --- a/doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md +++ b/doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md @@ -17,7 +17,7 @@ Similarly, if you deprecate a field, add "deprecated": "VERSION" (where VERSION ## How to Write a Schema Name the schema doc/schemas/`command`.json: the testsuite should pick it up and check all invocations of that command against it. -The core lightning RPC commands use custom schema specification defined in [rpc-schema-draft](https://github.com/ElementsProject/lightning/doc/rpc-schema-draft.json). +The core lightning RPC commands use custom schema specification defined in [rpc-schema-draft](https://github.com/ElementsProject/lightning/blob/master/doc/rpc-schema-draft.json). I recommend copying an existing one to start. If something goes wrong, try tools/fromscheme.py doc/schemas/`command`.json to see how far it got before it died. diff --git a/doc/contribute-to-core-lightning/release-checklist.md b/doc/contribute-to-core-lightning/release-checklist.md index a3222c13bfd1..17aae99b60d1 100644 --- a/doc/contribute-to-core-lightning/release-checklist.md +++ b/doc/contribute-to-core-lightning/release-checklist.md @@ -20,7 +20,7 @@ Here's a checklist for the release process. 1. Make sure any `CHANGELOG.md` changes from point releases have been imported. 2. Use `devtools/changelog.py` to collect the changelog entries from pull request commit messages and merge them into the manually maintained `CHANGELOG.md`. This does API queries to GitHub, which are severely ratelimited unless you use an API token: set the `GH_TOKEN` environment variable to a Personal Access Token from https://github.com/settings/tokens -3. Check that `CHANGELOG.md` is well formatted, ordered in areas, covers all signficant changes, and sub-ordered approximately by user impact & coolness. +3. Check that `CHANGELOG.md` is well formatted, ordered in areas, covers all significant changes, and sub-ordered approximately by user impact & coolness. 4. Manually remove any entries which were mentioned for in the previous point releases (they will be duplicates!) 5. Create a new CHANGELOG.md heading to `vrc1`, and create a link at the bottom. Note that you should exactly copy the date and name format from a previous release, as the `build-release.sh` script relies on this. 6. Update the package versions: `uv run make update-versions NEW_VERSION=vrc1` @@ -71,7 +71,7 @@ Here's a checklist for the release process. 7. Run `tools/build-release.sh bin-Fedora bin-Ubuntu sign` (with `--sudo` if you need root to run Docker) to: - Create reproducible zipfile - Build reproducible Fedora image - - Build reproducible Ubuntu-v20.04, Ubuntu-v22.04 and Ubuntu-v24.04 images. Follow [link](https://docs.corelightning.org/docs/repro#building-using-the-builder-image) for manually Building Ubuntu Images. + - Build reproducible Ubuntu-v22.04, Ubuntu-v24.04 and Ubuntu-v26.04 images. Follow [link](https://docs.corelightning.org/docs/repro#building-using-the-builder-image) for manually Building Ubuntu Images. - Build Docker images for amd64 and arm64v8. Follow [link](https://docs.corelightning.org/docs/docker-images) for more details on Docker publishing. - Create and sign checksums. Follow [link](https://docs.corelightning.org/docs/repro#co-signing-the-release-manifest) for manually signing the release. 8. If you used `--sudo`, the tarballs may be owned by root, so revert ownership if necessary: `sudo chown ${USER}:${USER} *${VERSION}*` @@ -101,7 +101,7 @@ Here's a checklist for the release process. 1. Create a PR to update: * `Makefile`: variables CLN_NEXT_VERSION and CLN_PREV_VERSION (this may break tests as deprecated things are disabled!) - * `tools/lightningd-downgrade.c`: to downgrade to the just-released version. + * `tools/lightning-downgrade.c`: to downgrade to the just-released version. * `.github/workflows/ci.yaml`: change old-cln to download the just-released version. * `.github/PULL_REQUEST_TEMPLATE.md` for important dates for the next release. 2. Look through PRs which were delayed for release and merge them. diff --git a/doc/developers-guide/app-development/grpc.md b/doc/developers-guide/app-development/grpc.md index 55c8725052de..50ffbc3baee8 100644 --- a/doc/developers-guide/app-development/grpc.md +++ b/doc/developers-guide/app-development/grpc.md @@ -102,7 +102,7 @@ Notice that we override the expected SSL name with `cln`. This is required becau We then use the channel to instantiate the `NodeStub` representing the service and its methods, so we can finally call the `Getinfo` method with default arguments. -### Generating custom certificates (optional) +### Generating custom certificates The automatically generated mTLS certificate will not know about potential domains that it'll be served under, and will chose a number of other parameters by default. If you'd like to generate a server certificate with a custom domain, you can use the following: diff --git a/doc/developers-guide/app-development/json-rpc.md b/doc/developers-guide/app-development/json-rpc.md index d061d55c39ab..e6799fe2b03d 100644 --- a/doc/developers-guide/app-development/json-rpc.md +++ b/doc/developers-guide/app-development/json-rpc.md @@ -4,8 +4,8 @@ slug: json-rpc privacy: view: public --- -> πŸ“˜ -> +> πŸ“˜ +> > Used for applications running on the same system as CLN. ## Using `lightning-cli` @@ -38,9 +38,9 @@ This will add links to the library into your environment so changing the checked Check out the following recipes to learn how to use pyln-client in your applications. -πŸ¦‰ **[Write a program in Python to interact with lightningd](https://docs.corelightning.org/v1.0/recipes/write-a-program-in-python-to-interact-with-lightningd)** +πŸ¦‰ **[Write a program in Python to interact with lightningd](https://docs.corelightning.org/recipes/write-a-program-in-python-to-interact-with-lightningd)** -πŸ¦‰ **[Write a hello-world plugin in Python](https://docs.corelightning.org/v1.0/recipes/write-a-hello-world-plugin-in-python)** +πŸ¦‰ **[Write a hello-world plugin in Python](https://docs.corelightning.org/recipes/write-a-hello-world-plugin-in-python)** ## Using Rust diff --git a/doc/developers-guide/app-development/rest.md b/doc/developers-guide/app-development/rest.md index a71fadce280c..eac7c1b014c0 100644 --- a/doc/developers-guide/app-development/rest.md +++ b/doc/developers-guide/app-development/rest.md @@ -7,17 +7,17 @@ privacy: # CLNRest -CLNRest is a lightweight Rust-based built-in Core Lightning plugin (from v23.08) that transforms RPC calls into a REST service. -It also broadcasts Core Lightning notifications to listeners connected to its websocket server. By generating REST API endpoints, +CLNRest is a lightweight Rust-based built-in Core Lightning plugin (from v23.08) that transforms RPC calls into a REST service. +It also broadcasts Core Lightning notifications to listeners connected to its websocket server. By generating REST API endpoints, it enables the execution of Core Lightning's RPC methods behind the scenes and provides responses in JSON format. An online demo for the REST interface is available at [REST API REFERENCE](ref:get_list_methods_resource). > πŸ“˜ Pro-tip -> +> > [REST API REFERENCE](ref:get_list_methods_resource) can also be tested with your own server. > -> By default, the base URL is set to connect with the Blockstream-hosted regtest node. +> By default, the base URL is set to connect with the Blockstream-hosted regtest node. > > However, it can be configured to connect to your own cln node as described below: > @@ -45,13 +45,13 @@ If `clnrest-port` is not specified, the plugin will disable itself. - --clnrest-certs: Defines the path for HTTPS cert & key. Default path is same as RPC file path to utilize gRPC's client certificate. If it is missing at the configured location, new identity will be generated. -- --clnrest-csp: Creates a whitelist of trusted content sources that can run on a webpage and helps mitigate the risk of attacks. +- --clnrest-csp: Creates a whitelist of trusted content sources that can run on a webpage and helps mitigate the risk of attacks. Default CSP: `default-src 'self'; font-src 'self'; img-src 'self' data:; frame-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline';` Example CSP: `clnrest-csp=default-src 'self'; font-src 'self'; img-src 'self'; frame-src 'self'; style-src 'self'; script-src 'self';`. -- --clnrest-cors-origins: Define multiple origins which are allowed to share resources on web pages to a domain different from the +- --clnrest-cors-origins: Define multiple origins which are allowed to share resources on web pages to a domain different from the one that served the web page. Default is `*` which allows all origins. Example to define multiple origins: ``` @@ -65,14 +65,14 @@ clnrest-cors-origins=https?://127.0.0.1:([0-9]{1,4}|[1-5][0-9]{4}|6[0-4][0-9]{3} ## Server -With the default configurations, the Swagger user interface will be available at https://127.0.0.1:3010/. +With the default configurations, the Swagger user interface will be available at https://127.0.0.1:3010/. The POST method requires `rune` header for authorization. -- A new `rune` can be created via [createrune](https://docs.corelightning.org/reference/lightning-createrune) or the list of -existing runes can be retrieved with [showrunes](https://docs.corelightning.org/reference/lightning-showrunes) command. +- A new `rune` can be created via [createrune](https://docs.corelightning.org/reference/createrune) or the list of +existing runes can be retrieved with [showrunes](https://docs.corelightning.org/reference/showrunes) command. -Note: in version v23.08, a parameter `Nodeid` was required to be the id of the node we're talking to (see `id (pubkey)` received -from [getinfo](https://docs.corelightning.org/reference/lightning-getinfo)). You can still send this for backwards compatibility, +Note: in version v23.08, a parameter `Nodeid` was required to be the id of the node we're talking to (see `id (pubkey)` received +from [getinfo](https://docs.corelightning.org/reference/getinfo)). You can still send this for backwards compatibility, but it is completely ignored. ### cURL @@ -83,7 +83,7 @@ With `-k` or `--insecure` option curl proceeds with the connection even if the S This option should be used only when testing with self signed certificate. ## Websocket Server -Websocket server is available at `https://127.0.0.1:3010`. clnrest broadcasts notifications to all listeners. +Websocket server is available at `https://127.0.0.1:3010`. clnrest broadcasts notifications to all listeners. This websocket server requires a `rune` with at least `readonly` access for authorization. The default method used for current validation is `listclnrest-notifications`. User can either provided a rune with minimum `readonly` diff --git a/doc/developers-guide/deprecated-features.md b/doc/developers-guide/deprecated-features.md index 470fef6f88d9..3ef335a9c9a1 100644 --- a/doc/developers-guide/deprecated-features.md +++ b/doc/developers-guide/deprecated-features.md @@ -46,7 +46,7 @@ Types of deprecation: For each deprecation: 1. The deprecation is listed here, and in the CHANGELOG.md file. 2. We try to give at least 2 versions before removal. -3. Then one version where we issue a warning message if we detect a deprecated feature being used (not possible for deprecatred `Field` types). +3. Then one version where we issue a warning message if we detect a deprecated feature being used (not possible for deprecated `Field` types). 4. At least one version where the deprecated feature can be explicit re-enabled using `i-promise-to-fix-broken-api-user=FEATURENAME`. diff --git a/doc/developers-guide/plugin-development.md b/doc/developers-guide/plugin-development.md index c2014ba82990..a647259d51d2 100644 --- a/doc/developers-guide/plugin-development.md +++ b/doc/developers-guide/plugin-development.md @@ -10,7 +10,7 @@ privacy: --- Plugins are a simple yet powerful way to extend the functionality provided by Core Lightning. They are subprocesses that are started by the main `lightningd` daemon and can interact with `lightningd` in a variety of ways: -- **[Command line option passthrough](doc:a-day-in-the-life-of-a-plugin)** allows plugins to register their own command line options that are exposed through `lightningd` so that only the main process needs to be configured. Option values are not remembered when a plugin is stopped or killed, but can be passed as parameters to [`plugin start`][lightning-plugin]. +- **[Command line option passthrough](doc:a-day-in-the-life-of-a-plugin)** allows plugins to register their own command line options that are exposed through `lightningd` so that only the main process needs to be configured. Option values are not remembered when a plugin is stopped or killed, but can be passed as parameters to rpc command [`plugin start`](ref:plugin). - **[JSON-RPC command passthrough](doc:json-rpc-passthrough)** adds a way for plugins to add their own commands to the JSON-RPC interface. - **[Event stream subscriptions](doc:event-notifications)** provide plugins with a push-based notification mechanism about events from the `lightningd`. - **[Hooks](doc:hooks)** are a primitive that allows plugins to be notified about internal events in `lightningd` and alter its behavior or inject custom behaviors. diff --git a/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md b/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md index 8aea0df625e9..30bcd767e34c 100644 --- a/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md +++ b/doc/developers-guide/plugin-development/a-day-in-the-life-of-a-plugin.md @@ -6,10 +6,10 @@ privacy: --- A plugin may be written in any language, and communicates with `lightningd` through the plugin's `stdin` and `stdout`. JSON-RPCv2 is used as protocol on top of the two streams, with the plugin acting as server and `lightningd` acting as client. The plugin file needs to be executable (e.g. use `chmod a+x plugin_name`). -> 🚧 -> +> 🚧 +> > As noted, `lightningd` uses `stdin` as an intake mechanism. This can cause unexpected behavior if one is not careful. To wit, care should be taken to ensure that debug/logging statements must be routed to `stderr` or directly to a file. Activities that are benign in other contexts (`println!`, `dbg!`, etc) will cause the plugin to be killed with an error along the lines of: -> +> > `UNUSUAL plugin-cln-plugin-startup: Killing plugin: JSON-RPC message > does not contain "jsonrpc" field` @@ -108,12 +108,12 @@ The `nonnumericids` indicates that the plugin can handle string JSON request `id The `dynamic` indicates if the plugin can be managed after `lightningd` has been started using the [lightning-plugin](ref:plugin) JSON-RPC command. Critical plugins that should not be stopped should set it to false. Plugin `options` can be passed to dynamic plugins as argument to the `plugin` command . If you can handle the `check` command on your commands, you should set `cancheck` to `true` and expect `lightningd` to pass through any user-requested `check` commands to you directly (without this, `check` currently always passes, which is not very useful!). - + If a `disable` member exists, the plugin will be disabled and the contents of this member is the reason why. This allows plugins to disable themselves if they are not supported in this configuration. The `hooks` array is either an array of hook names, or an array of objects with `name`, and optional `before` and `after` arrays specifying what the calling order is with respect to any other plugins (there's no problem if these plugins don't exist, but if they do we'll insist on obeying everyone's ordering constraints). You can also specify a `filters` array to some hooks to avoid being called on every occurrence. -The `featurebits` object allows the plugin to register featurebits that should be announced in a number of places in [the protocol](https://github.com/lightning/bolts/blob/master/09-features). They can be used to signal support for custom protocol extensions to direct peers, remote nodes and in invoices. Custom protocol extensions can be implemented for example using the `sendcustommsg` method and the `custommsg` hook, or the `sendonion` method and the `htlc_accepted` hook. The keys in the `featurebits` object are `node` for features that should be announced via the `node_announcement` to all nodes in the network, `init` for features that should be announced to direct peers during the connection setup, `channel` for features which should apply to `channel_announcement`, and `invoice` for features that should be announced to a potential sender of a payment in the invoice. The low range of featurebits is reserved for standardize features, so please pick random, high position bits for experiments. If you'd like to standardize your extension please reach out to the [specification repository][spec] to get a featurebit assigned. +The `featurebits` object allows the plugin to register featurebits that should be announced in a number of places in [the protocol](https://github.com/lightning/bolts/blob/master/09-features.md). They can be used to signal support for custom protocol extensions to direct peers, remote nodes and in invoices. Custom protocol extensions can be implemented for example using the `sendcustommsg` method and the `custommsg` hook, or the `sendonion` method and the `htlc_accepted` hook. The keys in the `featurebits` object are `node` for features that should be announced via the `node_announcement` to all nodes in the network, `init` for features that should be announced to direct peers during the connection setup, `channel` for features which should apply to `channel_announcement`, and `invoice` for features that should be announced to a potential sender of a payment in the invoice. The low range of featurebits is reserved for standardize features, so please pick random, high position bits for experiments. If you'd like to standardize your extension please reach out to the [specification repository](https://github.com/lightning/bolts) to get a featurebit assigned. The `notifications` array allows plugins to announce which custom notifications they intend to send to `lightningd`. These custom notifications can then be subscribed to by other plugins, allowing them to communicate with each other via the existing publish-subscribe mechanism and react to events that happen in other plugins, or collect information based on the notification topics. diff --git a/doc/developers-guide/plugin-development/additional-resources.md b/doc/developers-guide/plugin-development/additional-resources.md index 4904365e9a4d..53f2bb44862a 100644 --- a/doc/developers-guide/plugin-development/additional-resources.md +++ b/doc/developers-guide/plugin-development/additional-resources.md @@ -8,7 +8,7 @@ privacy: Check out a step-by-step recipe for building a simple `helloworld.py` example plugin based on [pyln-client](https://github.com/ElementsProject/lightning/tree/master/contrib/pyln-client). -πŸ¦‰ **[Write a hello-world plugin in Python](https://docs.corelightning.org/v1.0/recipes/write-a-hello-world-plugin-in-python)** +πŸ¦‰ **[Write a hello-world plugin in Python](https://docs.corelightning.org/recipes/write-a-hello-world-plugin-in-python)** You can also follow along the video below where Blockstream Engineer Rusty Russell walks you all the way from getting started with Core Lightning to building a plugin in Python. diff --git a/doc/developers-guide/plugin-development/event-notifications.md b/doc/developers-guide/plugin-development/event-notifications.md index ce16cd78f048..7a1555e056d0 100644 --- a/doc/developers-guide/plugin-development/event-notifications.md +++ b/doc/developers-guide/plugin-development/event-notifications.md @@ -4,7 +4,7 @@ slug: event-notifications privacy: view: public --- -Event notifications allow a plugin to subscribe to events in `lightningd`. `lightningd` will then send a push notification if an event matching the subscription occurred. A notification is defined in the JSON-RPC [specification][jsonrpc-spec] as an RPC call that does not include an `id` parameter: +Event notifications allow a plugin to subscribe to events in `lightningd`. `lightningd` will then send a push notification if an event matching the subscription occurred. A notification is defined in the JSON-RPC [specification](https://www.jsonrpc.org/specification) as an RPC call that does not include an `id` parameter: > A Notification is a Request object without an "id" member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request. > @@ -12,8 +12,8 @@ Event notifications allow a plugin to subscribe to events in `lightningd`. `ligh Plugins subscribe by returning an array of subscriptions as part of the `getmanifest` response. The result for the `getmanifest` call above for example subscribes to the two topics `connect` and `disconnect`. -> πŸ“˜ -> +> πŸ“˜ +> > This is a way of specifying that you want to subscribe to all possible event notifications. It is not recommended, but is useful for plugins which want to provide generic infrastructure for others (in future, we may add the ability to dynamically subscribe/unsubscribe). Lookup the **[Notification APIs](ref:notification-balance_snapshot)** for details on each notification and their payload. diff --git a/doc/developers-guide/tracing-cln-performance.md b/doc/developers-guide/tracing-cln-performance.md index 47b322f80a61..4451eeddce5b 100644 --- a/doc/developers-guide/tracing-cln-performance.md +++ b/doc/developers-guide/tracing-cln-performance.md @@ -63,47 +63,34 @@ usdt:lightningd/lightningd:lightningd:span_start usdt:lightningd/lightningd:lightningd:span_suspend ``` -There is a sample exporter that can be used to instrument a single -binary, batch the spans it receives and submit them as a batch to an -`otelcol` or `tempo` instance in [contrib/cln-tracer][cln-tracer] -using the zipkin format for spans and traces. +There is a sample exporter that can be used to instrument a single binary, batch the spans it receives and submit them as a batch to an `otelcol` or `tempo` instance in [contrib/cln-tracer][cln-tracer] using the zipkin format for spans and traces. [cln-tracer]: https://github.com/ElementsProject/lightning/tree/master/contrib/cln-tracer -Notice that due to a [limitation][bpftracer305] in the way the eBPF -script is handled you'll at most get the first 495 bytes of the -payload. This is due to the 512 byte limitation for eBPF programs out -of the box. +Notice that due to a [limitation][bpftracer305] in the way the eBPF script is handled you'll at most get the first 495 bytes of the payload. This is due to the 512 byte limitation for eBPF programs out of the box. -[bpftracer]: https://github.com/iovisor/bpftrace/issues/305 +[bpftracer305]: https://github.com/bpftrace/bpftrace/issues/305 ## Backend 2: Unix Domain Socket Datagrams -The UDS backend sends completed spans as atomic datagrams to a Unix -domain socket. This is designed for environments where kernel eBPF -access is unavailable, such as Kubernetes pods. +The UDS backend sends completed spans as atomic datagrams to a Unix domain socket. This is designed for environments where kernel eBPF access is unavailable, such as Kubernetes pods. ### How it works -Set the `CLN_TRACE_SOCKET` environment variable to the filesystem path -of a `SOCK_DGRAM` Unix domain socket: +Set the `CLN_TRACE_SOCKET` environment variable to the filesystem path of a `SOCK_DGRAM` Unix domain socket: ```bash $ CLN_TRACE_SOCKET=/tmp/cln-traces.sock lightningd ``` -When a span completes, its Zipkin-format JSON payload is sent via -`sendto()` to the specified socket. Key properties: +When a span completes, its Zipkin-format JSON payload is sent via `sendto()` to the specified socket. Key properties: -- **Atomic delivery**: Each datagram contains a complete, self-contained - JSON span payload. No framing or reassembly needed. +- **Atomic delivery**: Each datagram contains a complete, self-contained JSON span payload. No framing or reassembly needed. - **Non-blocking**: The socket is set to `O_NONBLOCK`. If the collector - is down or the socket buffer is full, the `sendto()` silently fails - without affecting the node. + is down or the socket buffer is full, the `sendto()` silently fails without affecting the node. - **Multi-writer safe**: Multiple CLN daemons can write to the same - socket path concurrently. The kernel guarantees datagram boundaries - are preserved. + socket path concurrently. The kernel guarantees datagram boundaries are preserved. - **No USDT dependency**: Works on any system, regardless of whether `systemtap-sdt-dev` is installed or `HAVE_USDT` is set. @@ -120,13 +107,11 @@ Each datagram is a Zipkin v2 JSON array containing a single span: "traceId":"4bf92f3577b34da6a3ce929d0e0e4736"}] ``` -Payloads are capped at 2048 bytes, well below the UDS datagram limit -(~200KB on Linux). +Payloads are capped at 2048 bytes, well below the UDS datagram limit (~200KB on Linux). ### Setting up a collector -Any process that binds a `SOCK_DGRAM` Unix domain socket at the -configured path can receive spans. A minimal Python collector: +Any process that binds a `SOCK_DGRAM` Unix domain socket at the configured path can receive spans. A minimal Python collector: ```python import socket, os, json @@ -185,6 +170,4 @@ Benchmark 1: common/test/run-trace Range (min … max): 546.5 ms … 598.9 ms 10 runs ``` -So depending on whether an exporter is attached, creating and emitting -span without and with an exporter takes around 370ns and 560ns -respectively. +So depending on whether an exporter is attached, creating and emitting span without and with an exporter takes around 370ns and 560ns respectively. diff --git a/doc/getting-started/advanced-setup/bitcoin-core.md b/doc/getting-started/advanced-setup/bitcoin-core.md index 5335ae55120c..5462b262a776 100644 --- a/doc/getting-started/advanced-setup/bitcoin-core.md +++ b/doc/getting-started/advanced-setup/bitcoin-core.md @@ -21,6 +21,5 @@ In order to avoid this situation you should be monitoring the gap between Core L You can use _trusted_ third-party plugins as bitcoin backends instead of using your own node. -- [sauron](https://github.com/lightningd/plugins/tree/master/sauron) is a bitcoin backend plugin relying on [Esplora](https://github.com/Blockstream/esplora). - [trustedcoin](https://github.com/nbd-wtf/trustedcoin) is a plugin that uses block explorers (blockstream.info, mempool.space, blockchair.com and blockchain.info) as backends instead of your own bitcoin node. - [bps](https://github.com/coinos/bps) is a proxy server that exposes just the RPC commands that lightning needs. There's a public endpoint at https://coinos.io/proxy or you can host your own. diff --git a/doc/getting-started/getting-started.md b/doc/getting-started/getting-started.md index a886105a8741..de380c6def16 100644 --- a/doc/getting-started/getting-started.md +++ b/doc/getting-started/getting-started.md @@ -26,7 +26,7 @@ The following steps will get you up and running with Core Lightning: For a thorough understanding of the best hardware setup for your usage / scenario, see guidance at [hardware considerations](doc:hardware-considerations). - [x] **Bitcoin Core** - Core Lightning requires a locally (or remotely) running `bitcoind` (version 0.16 or above) that is fully caught up with the network you're running on, and relays transactions (ie with `blocksonly=0`). Pruning (`prune=n` option in `bitcoin.conf`) is partially supported, see [here](doc:bitcoin-core#using-a-pruned-bitcoin-core-node) for more details. You can also connect your Core Lightning node to a remotely running Bitcoin Core, see [here](doc:bitcoin-core#connecting-to-bitcoin-core-remotely) to learn how. + Core Lightning requires a locally (or remotely) running `bitcoind` (version 23.0 or above) that is fully caught up with the network you're running on, and relays transactions (ie with `blocksonly=0`). Pruning (`prune=n` option in `bitcoin.conf`) is partially supported, see [here](doc:bitcoin-core#using-a-pruned-bitcoin-core-node) for more details. You can also connect your Core Lightning node to a remotely running Bitcoin Core, see [here](doc:bitcoin-core#connecting-to-bitcoin-core-remotely) to learn how. ## 2. [Install](doc:installation) Core Lightning diff --git a/doc/getting-started/getting-started/installation.md b/doc/getting-started/getting-started/installation.md index 643a90d78e2b..7b6b2b3f4979 100644 --- a/doc/getting-started/getting-started/installation.md +++ b/doc/getting-started/getting-started/installation.md @@ -23,7 +23,7 @@ sudo rm -R /usr/local/libexec/c-lightning/plugins # If you are upgrading run thi sudo tar -xvf .tar.xz -C /usr/local --strip-components=2 ``` -If you're on a different distribution or OS, you can compile the source by following the instructions from [Installing from Source](doc:installing-from-source). +If you're on a different distribution or OS, you can compile the source by following the instructions from [Installing from Source](#installing-from-source). # Docker @@ -32,9 +32,9 @@ To install the Docker image for the latest stable release: docker pull elementsproject/lightningd:latest ``` -To install for a specific version, for example, 24.05: +To install for a specific version, for example, v26.06.6: ```shell -docker pull elementsproject/lightningd:v24.05 +docker pull elementsproject/lightningd:v26.06.6 ``` To run the Docker container: @@ -66,7 +66,7 @@ For actually doing development and running the tests, you will also need: - pip3: to install python-bitcoinlib - valgrind: for extra debugging checks -You will also need a version of bitcoind with segregated witness and `estimatesmartfee` with `ECONOMICAL` mode support. Version 0.16 or above should work. +You will also need a version of bitcoind with segregated witness and `estimatesmartfee` with `ECONOMICAL` mode support. Version 23.0 or above should work. ## To Build on Ubuntu @@ -322,7 +322,7 @@ Finally, build `c-lightning`: ## To Build on NixOS -Core Lightning ships a [Nix flake](https://nixos.wiki/wiki/Flakes), so on NixOS +Core Lightning ships a [Nix flake](https://wiki.nixos.org/wiki/Flakes), so on NixOS you don't need to install any build dependencies by hand. Make sure the `nix-command` and `flakes` features are enabled. diff --git a/doc/lightningd-config.5.md b/doc/lightningd-config.5.md index aaa3e8fb8bc7..bc7b3c9faec1 100644 --- a/doc/lightningd-config.5.md +++ b/doc/lightningd-config.5.md @@ -491,7 +491,7 @@ have to do that. Normally HTLC onions which contain unknown even fields are rejected. This option specifies that this type is to be accepted, and ignored. Can be -specified multuple times. (Added in v23.08). +specified multiple times. (Added in v23.08). * **min-emergency-msat**=*msat* @@ -683,7 +683,7 @@ announced addresses are public (e.g. not localhost). This option can be used multiple times to add more addresses, and its use disables autolisten. - Since v23.058, the `dns:` prefix can be used to indicate that this hostname and port should be announced as a DNS hostname entry. Please note that most mainnet nodes do not yet use, read or propagate this information correctly. + Since v23.08, the `dns:` prefix can be used to indicate that this hostname and port should be announced as a DNS hostname entry. Please note that most mainnet nodes do not yet use, read or propagate this information correctly. * **announce-addr-dns**=*BOOL* (deprecated in v23.08) @@ -835,7 +835,7 @@ load plugins which have been disabled, using lightning-plugin(7) `start`. * **important-plugin**=*PLUGIN* - Speciy a plugin to run as part of Core Lightning. + Specify a plugin to run as part of Core Lightning. This can be specified multiple times to add multiple plugins. Plugins specified via this option are considered so important, that if the plugin stops for any reason (including via lightning-plugin(7) `stop`), @@ -939,6 +939,6 @@ Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered by the BSD-style MIT license. [bolt]: https://github.com/lightning/bolts -[bolt12]: https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md +[bolt12]: https://github.com/lightning/bolts/blob/master/12-offer-encoding.md [pr4421]: https://github.com/ElementsProject/lightning/pull/4421 [blip]: https://github.com/lightning/blips diff --git a/doc/lightningd-rpc.7.md b/doc/lightningd-rpc.7.md index 018705b340ce..3de7fcd7cbb7 100644 --- a/doc/lightningd-rpc.7.md +++ b/doc/lightningd-rpc.7.md @@ -11,7 +11,7 @@ DESCRIPTION lightningd(8) communicates via RPC, especially JSONRPC over the UNIX domain socket (by default **$HOME/.lightning/bitcoin/lightning-rpc**, -but configuable with lightningd-config(5)). +but configurable with lightningd-config(5)). JSON WIRE FORMAT @@ -82,7 +82,7 @@ be added in future. You should safely ignore any unknown fields. Any field name which starts with "warning" is a specific warning, and should be documented in the commands' manual page. Each warning field -has an associated human-readable string, but it's redudant, as each +has an associated human-readable string, but it's redundant, as each separate warning should have a distinct field name (e.g. **warning\_offer\_unknown\_currency** and **warning\_offer\_missing\_description**). @@ -105,7 +105,7 @@ referred to in addition to simple JSON types: * `pubkey`: a 66-character `hex` which is an SEC-1 encoded secp256k1 point (usually used as a public key). * `msat`: a `u64` which indicates an amount of millisatoshis. Deprecated: may also be a string of the number, with "msat" appended. As an input parameter, lightningd(8) will accept strings with suffixes (see below). * `txid`: a 64-character `hex` Bitcoin transaction identifier. -* `signature`: a `hex` (144 bytes or less), which is a DER-encoded Bitcoin signature (without any sighash flags appended), +* `signature`: a `hex` (144 bytes or less), which is a DER-encoded Bitcoin signature (without any sighash flags appended), * `bip340sig`: a 128-character `hex` which is a BIP-340 (Schnorr) signature. * `point32`: a 64-character `hex` which represents an x-only pubkey. * `short_channel_id`: a string of form BLOCK "x" TXNUM "x" OUTNUM. @@ -250,7 +250,7 @@ Note: `"filter"` doesn't change the order, just which fields are printed. Any fields not explicitly mentioned are omitted from the output, but plugins which don't support filter (and some routines doing simple JSON transfers) may ignore `"filter"`, so you should treat -it as an optimazation only). +it as an optimization only). Note: if you specify an array where an object is specified or vice versa, the response may include a `warning_parameter_filter` field diff --git a/doc/lightningd.8.md b/doc/lightningd.8.md index 85c3717572ff..0a6eb64d12c5 100644 --- a/doc/lightningd.8.md +++ b/doc/lightningd.8.md @@ -121,7 +121,7 @@ which you can do by using dig(1) and querying *lseed.bitcoinstats.com*: This will give 25 IPv4 addresses, you can select any one of those. You will also need to learn the corresponding public key, which you can -determine by searching the IP addrss on [https://1ml.com/](https://1ml.com/) . The public +determine by searching the IP address on [https://1ml.com/](https://1ml.com/) . The public key is a long hex string, like so: *024772ee4fa461febcef09d5869e1238f932861f57be7a6633048514e3f56644a1*. (this example public key is not used as of this writing) diff --git a/doc/node-operators-guide/faq.md b/doc/node-operators-guide/faq.md index 17ad832d7174..44c6c1869b5c 100644 --- a/doc/node-operators-guide/faq.md +++ b/doc/node-operators-guide/faq.md @@ -65,10 +65,10 @@ Effort has been made to get `lightningd` running on Android, [see issue #3484](h ### How to forget about a channel? -> 🚧 -> +> 🚧 +> > Never use any `dev` command unless you know exactly what you are doing, and have checked with a developer that your understanding is correct. They are meant only as a means of last resort and have the potential to mess things up. You have been warned❗️ -> +> Channels may end up stuck during funding and never confirm on-chain. There is a variety of causes, the most common ones being that the funds have been double-spent, or the funding fee was too low to be confirmed. This is unlikely to happen in normal operation, as CLN tries to use sane defaults and prevents double-spends whenever possible, but using custom feerates or when the bitcoin backend has no good fee estimates it is still possible. @@ -86,7 +86,7 @@ lightning-cli withdraw $ADDR all This step is not required if the funding transaction was already double-spent, however it is safe to do it anyway, just in case. -Then wait for the transaction moving the funds to confirm. This ensures any pending funding transaction can no longer be confirmed. +Then wait for the transaction moving the funds to confirm. This ensures any pending funding transaction can no longer be confirmed. As an additional step you can also force-close the unconfirmed channel: @@ -159,7 +159,7 @@ There are 3 types of 'rescans' you can make: ### Database corruption / channel state lost -If you lose data (likely corrupted `lightningd.sqlite3`) about a channel **with `option_static_remotekey` enabled**, you can wait for your peer to unilateraly close the channel, then use `tools/lightning-hsmtool` with the `guesstoremote` command to attempt to recover your funds from the peer's published unilateral close transaction. +If you lose data (likely corrupted `lightningd.sqlite3`) about a channel **with `option_static_remotekey` enabled**, you can wait for your peer to unilaterally close the channel, then use `tools/lightning-hsmtool` with the `guesstoremote` command to attempt to recover your funds from the peer's published unilateral close transaction. If `option_static_remotekey` was not enabled, you're probably out of luck. The keys for your funds in your peer's unilateral close transaction are derived from information you lost. Fortunately, since version `0.7.3` channels are created with `option_static_remotekey` by default if your peer supports it. Which is to say that channels created after block [598000](https://blockstream.info/block/0000000000000000000dd93b8fb5c622b9c903bf6f921ef48e266f0ead7faedb) (short channel id starting with > 598000) have a high chance of supporting `option_static_remotekey`. You can verify it using the `features` field from the [`listpeers` command](ref:listpeers)'s result. diff --git a/doc/node-operators-guide/plugins.md b/doc/node-operators-guide/plugins.md index b3cd5a79440c..8b050df2a96a 100644 --- a/doc/node-operators-guide/plugins.md +++ b/doc/node-operators-guide/plugins.md @@ -12,9 +12,9 @@ Power up your Core Lightning node and tailor it for your business needs with com `reckless` is a plugin manager for Core Lightning that you can use to install and uninstall plugins with a single command. -> πŸ“˜ -> -> Reckless currently supports python plugins only. Additional language support will be provided in future releases. For plugins built by the community in other languages, see the complete list of plugins [here](https://github.com/lightningd/plugins). +> πŸ“˜ +> +> Reckless currently supports python and rust plugins only. Additional language support will be provided in future releases. For plugins built by the community in other languages, see the complete list of plugins [here](https://github.com/lightningd/plugins). Typical plugin installation involves: finding the source plugin, copying, installing dependencies, testing, activating, and updating the lightningd config file. Reckless does all of these by invoking: @@ -110,8 +110,8 @@ Available option flags: **-v**, **--verbose** request additional debug output -> πŸ“˜ -> +> πŸ“˜ +> > Running the first time will prompt the user that their lightningd's bitcoin config will be appended (or created) to inherit the reckless config file (this config is specific to bitcoin by default.) Management of plugins will subsequently modify this file. ## Troubleshooting diff --git a/doc/reckless.7.md b/doc/reckless.7.md index 49918023d56b..3fc5275cbe71 100644 --- a/doc/reckless.7.md +++ b/doc/reckless.7.md @@ -4,12 +4,12 @@ reckless -- Issue a command to the reckless plugin manager utility SYNOPSIS -------- -**reckless** *command* [*target/subcommand*] [*target*] +**reckless** *command* [*target/subcommand*] [*target*] DESCRIPTION ----------- -The **reckless** RPC starts a reckless process with the *command* and *target* provided. Node configuration, network, and lightning direrctory are automatically passed to the reckless utility. +The **reckless** RPC starts a reckless process with the *command* and *target* provided. Node configuration, network, and lightning directory are automatically passed to the reckless utility. - **command** (string) (one of "install", "uninstall", "search", "enable", "disable", "source", "--version"): Determines which command to pass to reckless - *command* **install** takes a *plugin\_name* to search for and install a named plugin. @@ -52,7 +52,7 @@ EXAMPLES -------- -**Example 1**: +**Example 1**: Request: ```shell @@ -86,7 +86,7 @@ Response: } ``` -**Example 2**: +**Example 2**: Request: ```shell