{"id":18928835,"url":"https://github.com/lightninglabs/faraday","last_synced_at":"2025-04-13T07:50:11.574Z","repository":{"id":37919396,"uuid":"217486639","full_name":"lightninglabs/faraday","owner":"lightninglabs","description":"Lightning Channel Management \u0026 Optimization Tool","archived":false,"fork":false,"pushed_at":"2025-03-23T14:12:35.000Z","size":1732,"stargazers_count":128,"open_issues_count":18,"forks_count":30,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-04-13T07:50:04.182Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lightninglabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-25T08:20:39.000Z","updated_at":"2025-03-23T14:12:33.000Z","dependencies_parsed_at":"2023-10-04T01:23:42.955Z","dependency_job_id":"57b1d5b1-aa70-446e-8959-ed85b2004467","html_url":"https://github.com/lightninglabs/faraday","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Ffaraday","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Ffaraday/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Ffaraday/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightninglabs%2Ffaraday/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lightninglabs","download_url":"https://codeload.github.com/lightninglabs/faraday/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681494,"owners_count":21144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T11:28:12.823Z","updated_at":"2025-04-13T07:50:11.551Z","avatar_url":"https://github.com/lightninglabs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# faraday\n\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/lightninglabs/faraday/blob/master/LICENSE)\n\nFaraday is a suite of tools built to help node operators and businesses run [lnd](https://github.com/lightningnetwork/lnd), the leading implementation of the [Lightning Network](https://github.com/lightningnetwork/lightning-rfc). Faraday’s tools decrease the operational overhead of running a Lightning node and make it easier to build businesses on Lightning. The current features in the Faraday suite provide insight into node channel performance and support for accounting with both on-chain and off-chain reports for lnd. \n## LND\nNote that Faraday requires lnd to be built with **all of its subservers** and requires running at least v0.11.1. Download the [official release binary](https://github.com/lightningnetwork/lnd/releases/tag/v0.11.1-beta) or see the [instructions](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md) in the lnd repo for more detailed installation instructions. If you choose to build lnd from source, following command to enable all the relevant subservers:\n\n```shell\nmake install tags=\"signrpc walletrpc chainrpc invoicesrpc\"\n```\n\n\n## Installation\nA [Makefile](https://github.com/lightninglabs/faraday/blob/master/Makefile) is provided. To install faraday and all its dependencies, run:\n\n```shell\ngit clone https://github.com/lightninglabs/faraday.git\ncd faraday\nmake \u0026\u0026 make install\n```\n\n## Usage\nFaraday connects to a single instance of lnd. It requires access to `lnd`'s\n`admin.macaroon` (or a custom scoped macaroon, see below) and a valid TLS\ncertificate. It will attempt to use the default `lnd` values if no command line\nflags are specified.\n\n```shell\n./faraday                                                   \\\n--lnd.macaroonpath={full path to lnd's admin.macaroon}   \\\n--lnd.tlscertpath={path to lnd cert}                        \\\n--lnd.rpcserver={host:port of lnd's rpcserver} \n```\n\nBy default, faraday runs on mainnet. The `--network` flag can be used to run in\ntest environments.\n\n### Baking a custom macaroon for Faraday\n\nFaraday needs to derive a shared key with `lnd` to create an encryption password\nfor its macaroon database. That's why on top of the permissions in the\n`readonly.macaroon` the `uri:/signrpc.Signer/DeriveSharedKey` is also required.\nA custom scoped macaroon just for Faraday can be baked with:\n\n```shell\nlncli bakemacaroon onchain:read offchain:read address:read peers:read info:read invoices:read uri:/signrpc.Signer/DeriveSharedKey\n```\n\n## Authentication and transport security\n\nThe gRPC and REST connections of `faraday` are encrypted with TLS and secured\nwith macaroon authentication the same way `lnd` is.\n\nIf no custom faraday directory is set then the TLS certificate is stored in\n`~/.faraday/\u003cnetwork\u003e/tls.cert` and the base macaroon in\n`~/.faraday/\u003cnetwork\u003e/faraday.macaroon`.\n\nThe `frcli` command will pick up these file automatically on mainnet if no\ncustom faraday directory is used. For other networks it should be sufficient to\nadd the `--network` flag to tell the CLI in what sub directory to look for the\nfiles.\n\nFor more information on macaroons,\n[see the macaroon documentation of lnd.](https://github.com/lightningnetwork/lnd/blob/master/docs/macaroons.md)\n\n**NOTE**: Faraday's macaroons are independent from `lnd`'s. The same macaroon\ncannot be used for both `faraday` and `lnd`.\n\n### Chain Backend\nFaraday offers node accounting services which require access to a Bitcoin node with `--txindex` set so that it can perform transaction lookup. Currently the `CloseReport` endpoint requires this connection, and will fail if it is not present. It is *strongly recommended* to provide this connection when utilizing the `NodeAudit` endpoint, but it is not required. This connection is *optional*, and all other endpoints will function if it is not configured. \n\nTo connect Faraday to bitcoind:\n```text\n--connect_bitcoin                       \\\n--bitcoin.host={host:port of bitcoind}  \\\n--bitcoin.user={bitcoind username}      \\\n--bitcoin.password={bitcoind  password}\n```\n\nTo connect Faraday to btcd:\n```text\n--connect_bitcoin                   \\\n--bitcoin.host={host:port of btcd}  \\\n--bitcoin.user={btcd username}      \\\n--bitcoin.password={btcd password}  \\\n--bitcoin.usetls                    \\\n--bitcoin.tlspath={path to btcd cert}\n```\n\n#### RPCServer\nFaraday serves requests over grpc by default on `localhost:8465`. This default can be overwritten:\n```text\n--rpclisten={host:port to listen for requests}\n```\n\n#### Cli Tool\nThe RPC server can be conveniently accessed using a command line tool. \n1. Run faraday as detailed above\n```shell\n./frcli {command}\n```\n\n##### Commands\n- `insights`: expose metrics gathered for one or many channels.\n- `revenue`: generate a revenue report over a time period for one or many channels.\n- `outliers`: close recommendations based whether channels are outliers based on a variety of metrics.\n- `threshold`: close recommendations based on thresholds a variety of metrics.\n- `audit`: produce an accounting report for your node over a period of time, please see the [accounting documentation](https://github.com/lightninglabs/faraday/blob/master/docs/accounting.md) for details. *Chain backend strongly recommended*, fee entries for channel closes and sweeps will be *missing* if a chain connection is not provided.\n- `fiat`: get the USD price for an amount of Bitcoin at a given time, currently obtained from CoinCap's [historical price API](https://docs.coincap.io/?version=latest).\n- `closereport`: provides a channel specific fee report, including fees paid on chain. This endpoint is currently only implemented for cooperative closes.  *Requires chain backend*.\n\n#### Metrics currently tracked\nThe following metrics are tracked in faraday and exposed via `insights` and used for `outliers` and `threshold` close recommendations.\n- Uptime\n- Revenue\n- Total Volume\n- Incoming Volume\n- Outgoing Volume\n\n## Development\nIf you would like to contribute to Faraday, please see our [issues page](https://github.com/lightninglabs/faraday/issues) for currently open issues. If a feature that you would like to add is not covered by an existing issue, please open an issue to discuss the proposed addition. Contributions are hugely appreciated, and we will do our best to review pull requests timeously. \n\n### Tests\nTo run all the unit tests in the repo:\n```shell\nmake check\n```\nTo run Faraday's itests locally, you will need docker installed. To run all itests:\n```shell\nmake itest\n```\n\nIndividual itests can also be run using:\n```shell\n./run_itest.sh {test name}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightninglabs%2Ffaraday","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flightninglabs%2Ffaraday","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightninglabs%2Ffaraday/lists"}