{"id":15148890,"url":"https://github.com/ledgerhq/satstack","last_synced_at":"2025-04-10T04:59:49.348Z","repository":{"id":39890308,"uuid":"256716365","full_name":"LedgerHQ/satstack","owner":"LedgerHQ","description":"Bitcoin full node with Ledger Live","archived":false,"fork":false,"pushed_at":"2024-05-20T02:48:10.000Z","size":4946,"stargazers_count":158,"open_issues_count":39,"forks_count":33,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-03T01:08:39.680Z","etag":null,"topics":["bitcoin","btcd","golang","ledger","ledger-live","privacy"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LedgerHQ.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":"2020-04-18T09:38:59.000Z","updated_at":"2025-04-01T14:31:24.000Z","dependencies_parsed_at":"2024-01-31T09:40:33.826Z","dependency_job_id":"9928079a-b4f8-4317-a371-b0f0a0ddb614","html_url":"https://github.com/LedgerHQ/satstack","commit_stats":{"total_commits":348,"total_committers":13,"mean_commits":26.76923076923077,"dds":0.2729885057471264,"last_synced_commit":"9366fec5187b64fb0fab893a6ad508a5e75226f0"},"previous_names":["onyb/sat-stack"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LedgerHQ%2Fsatstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LedgerHQ%2Fsatstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LedgerHQ%2Fsatstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LedgerHQ%2Fsatstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LedgerHQ","download_url":"https://codeload.github.com/LedgerHQ/satstack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161267,"owners_count":21057554,"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":["bitcoin","btcd","golang","ledger","ledger-live","privacy"],"created_at":"2024-09-26T13:40:16.411Z","updated_at":"2025-04-10T04:59:49.322Z","avatar_url":"https://github.com/LedgerHQ.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ledger SatStack\n\n\u003cimg src=\"/share/logo.svg\" align=\"right\" alt=\"satstack logo\" width=\"200\"\u003e\n\n\u003c/h1\u003e\n\nLedger SatStack is a lightweight bridge to connect Ledger Live with your personal Bitcoin full node. It's designed to allow Ledger Live users use Bitcoin without compromising on privacy, or relying on Ledger's infrastructure.\n\n\u003cp\u003e\n  \u003cimg src=\"https://github.com/ledgerhq/satstack/workflows/Build/badge.svg\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/v/release/ledgerhq/satstack?include_prereleases\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/downloads/ledgerhq/satstack/total\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-%3E%3D1.17-04ADD8.svg\" /\u003e\n\u003c/p\u003e\n\n\u003cimg src=\"share/screenshot.png\" align=\"center\" /\u003e\n\n## Table of Contents\n\n- [Background](#background)\n- [Architecture](#architecture)\n- [Requirements](#requirements)\n- [Usage](#usage)\n- [Misc](#misc)\n- [In the Press](#in-the-press)\n- [Community](#community)\n- [Contributing](#contributing)\n\n### Background\n\nRunning a full node is the only way you can use Bitcoin in a completely trustless way. A full node downloads the entire blockchain, and checks it against Bitcoin's consensus rules, and contributes to the decentralization and economic strength of Bitcoin. However, a far more compelling reason to run your own node is **privacy**. [...read more](https://en.bitcoin.it/wiki/Full_node).\n\nRunning a node can be difficult for some users, and has [associated costs](https://bitcoin.org/en/full-node#costs-and-warnings) in terms of network bandwidth and disk usage. This is why Live connects to Bitcoin nodes running on Ledger's infrastucture, wrapped around by indexer and explorer services to ensure fast queries. While security and privacy is core to Ledger, one can make a theoretical case that Ledger can spy on transaction details, or even censor certain addresses from using Ledger's services.\n\nSatStack aims to render Ledger's infrastructure dispensable, by allowing users to connect Ledger Live with their personal Bitcoin full node.\n\n### Architecture\n\nLedger SatStack is a standalone Go application, that acts as a bridge between the [Ledger Live](http://ledger.com/live) application and a Bitcoin Core full-node. It exposes a REST interface to the open-source JS library embedded by Live, and communicates to the Bitcoin node over RPC. It utilizes the transport layer and data-structures of [btcd](https://github.com/btcsuite/btcd).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"/share/architecture.svg\"/\u003e\n\u003c/p\u003e\n\n### Requirements\n\n- Bitcoin Nano app **`2+`**\n- Bitcoin Core **`0.22.0+`**\n- Ledger Live (desktop) **`2.44.0+`** but don't go as far 2.53+ that breaks satstack! https://download.live.ledger.com/ to get the latest supported i.e. 2.52.0\n- `txindex=1` in `bitcoin.conf` is not mandatory, but recommended. Pruned nodes are not currently supported.\n- Wallet should **NOT** be disabled (attn. Raspiblitz users).\n\n### Usage\n\n#### Setup Ledger Live (recommended way but only works without Tor)\n\nThe easiest way of getting started is to use the dedicated setup flow directly on Ledger Live.\nA detailed guide is available [here](https://support.ledger.com/hc/en-us/articles/360017551659).\n\n#### Manual setup (for advanced users)\n\n##### Retrieve descriptors from device\n\nSimply follow these steps:\n\n1. Plug in your Ledger device via USB.\n2. Enter your PIN code on the device, and open the Bitcoin app.\n3. Run the `scripts/getdescriptor` script, as shown below.\n\n```bash\n$ cd scripts\n$ python3 -m venv venv  # ensure Python 3.8+\n$ source venv/bin/activate\n(venv) $ pip install -r requirements.txt\n(venv) $ ./getdescriptor --scheme native_segwit --chain main --account 3\nExternal: wpkh([b91fb6c1/84'/0'/3']xpub6D1gvTP...VeMLtH6/0/*)\nInternal: wpkh([b91fb6c1/84'/0'/3']xpub6D1gvTP...VeMLtH6/1/*)\n```\n\nif you get an `unsupported hash type ripemd160` error, please see [this](https://stackoverflow.com/questions/72409563/unsupported-hash-type-ripemd160-with-hashlib-in-python)\n\n##### Create configuration file\n\nCreate a config file **`lss.json`** in your home directory.\nYou can use [this](https://github.com/ledgerhq/satstack/blob/master/lss.mainnet.json) sample config file as a template.\n\nAdd `\"torproxy\": \"socks5://127.0.0.1:9050\",` to connect to a Tor client running locally so that satstack can reach a full node behind Tor.\nReplace the `rpcurl` with the .onion address of your node.\n\n###### Optional account fields\n\n- **`depth`**: override the number of addresses to derive and import in the Bitcoin wallet. Defaults to `1000`.\n- **`birthday`**: set the earliest known creation date (`YYYY/MM/DD` format), for faster account import.\n  Defaults to `2013/09/10` ([BIP0039](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) proposal date).\n  Refer to the table below for a list of safe wallet birthdays to choose from.\n\n  | Event                                                    | Date (YYYY/MM/DD)    |\n  | -------------------------------------------------------- | -------------------- |\n  | BIP0039 proposal created                                 | 2013/09/10 (default) |\n  | First ever BIP39 compatible Ledger device (Nano) shipped | 2014/11/24           |\n  | First ever Ledger Nano S shipped                         | 2016/07/28           |\n\n##### Launch Bitcoin full node\n\nMake sure you've read the [requirements](#requirements) first, and that your node is configured properly.\nHere's the recommended configuration for `bitcoin.conf`:\n\nIt is not recommended to use rpcuser/rpcpassword in the bitcoin.conf of your full node use rpcauth instead.\nIf you still want to use it make sure the following settings are in your bitcoin.conf file:\n\n```\n# Enable RPC server\nserver=1\n\n# Enable indexes\ntxindex=1\nblockfilterindex=1\n\n# Set RPC credentials\nrpcuser=\u003cuser\u003e\nrpcpassword=\u003cpassword\u003e\n```\n\nIf you want to use the newest security standard recommended by the core-devs then read the following paragraph.\nGet the rpcauth.py script from the bitcoin repo and create a new user for satstack.\n\n```\nwget https://raw.githubusercontent.com/bitcoin/bitcoin/master/share/rpcauth/rpcauth.py\n\npython3 rpcauth.py satstack\n\nExample Output:\nrpcauth=satstack:a14191e6892facf70686a397b126423$ddd6f7480817bd6f8083a2e07e24b93c4d74e667f3a001df26c5dd0ef5eafd0d\nYour password:\nVX3z87LBVc_X7NBLABLABLABLA\n```\n\nCopy the `rpcauth=` into your bitcoin.conf\nNote down the password and use them in your lss.json. There you will use the credentials\n\n```\nIn your lss.json:\n\n\"rpcuser\": \"satstack\",\n\"rpcpassword\": \"VX3z87LBVc_X7NBLABLABLABLA\"\n```\n\n```config\n# Enable RPC server\nserver=1\n\n# Enable indexes\ntxindex=1\nblockfilterindex=1\n\n# Set RPC credentials\n# Example Auth, replace with your own.\n# see https://bitcoin.stackexchange.com/questions/46782/rpc-cookie-authentication why we are not using normal rpcuser/password\nrpcauth=satstack:a14191e6892facf70686a397b126423$ddd6f7480817bd6f8083a2e07e24b93c4d74e667f3a001df26c5dd0ef5eafd0d\n```\n\nThen launch `bitcoind` like this:\n\n```bash\nbitcoind\n```\n\n##### Launch SatStack\n\nPre-built binaries are available for download on the [releases](https://github.com/ledgerhq/satstack/releases)\npage (Linux, Windows, MacOS). Extract the tarball, and launch it as:\n\n```sh\n./lss\n```\nThere are some cmd handles which can be useful when configuring the setup the first time. List them with\n\n`./lss -h` or `./lss --help`\n\nWhen setting up a new wallet, the wallet is synced form the birthday date or your custom date set in `lss.json`\nWhen the initial sync sucessfully completes, satstack saves a file called `lss_rescan.json` at the exact location\nwhere the lss.json is stored. This file includes the latest blockheight your wallet was synced to, this allows \nsatstack on every restart to not rescan the whole wallet again but only rescan the difference between the current\nblockheight. You can also change the latest blockheight manually in the file which helps you to set the rescan delta\nmanually. This file is only created when an initial wallet sync was successful. Removing the file will lead satstack\nto rescan the complete wallet again when starting up.\n\nIf you want to build `lss` yourself, just do the following:\n\n(make sure you have [mage](https://magefile.org) installed first)\n\n```sh\nmage release  # or \"mage build\" for a development build\n```\n\nOn startup, SatStack will wait for the Bitcoin node to be fully synced,\nand import your accounts. This can take a while.\n\n##### Launch Ledger Live Desktop\n\n```sh\n# environment variables `EXPLORER` and `EXPLORER_SATSTACK` should point at the address\n# where `lss` is listening (can be a differnet computer/server)\n$ EXPLORER=http://127.0.0.1:20000 \u003cLedger Live executable\u003e\n```\n\n##### Turn SatStack into a service\n\nOnce descriptors are imported, you might want to automatically start SatStack on your computer as a background task. On Linux, you can do so thanks to systemd, you will have to use the `WorkingDirectory` settings so that SatStack finds the config file. You will also have to have a tor deamon running in the background.\n\n### Misc\n\nIf you get `error=failed to load wallet: -4: Wallet file verification failed. SQLiteDatabase: Unable to obtain an exclusive lock on the database, is it being used by another bitcoind?` maybe this is because you have bitcoind windows opened, if this is the case, please try closing them and restart lss.\n\n### In the press\n\n| Title                                                                                                                                                                                                               |                      Source                      |\n| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------: |\n| 🇬🇧 [Personal sovereignty with Ledger SatStack](https://blog.ledger.com/satstack)                                                                                                                                    |    [blog.ledger.com](https://blog.ledger.com)    |\n| 🇫🇷 [Ledger SatStack: un pont entre Bitcoin Core et votre Ledger Wallet](https://bitcoin.fr/ledger-sat-stack-un-pont-entre-bitcoin-core-et-votre-ledger-wallet/)                                                     |         [bitcoin.fr](https://bitcoin.fr)         |\n| 🇫🇷 [Votre propre coffre-fort à bitcoins… inviolable – Ledger annonce l’arrivée des full nodes Bitcoin](https://journalducoin.com/actualites/coffre-fort-bitcoins-inviolable-ledger-annonce-noeuds-complets-bitcoin) |   [Journal du Coin](https://journalducoin.com)   |\n| 🇫🇷 [Il est désormais possible d’exécuter un full node Bitcoin sur Ledger Live](https://fr.beincrypto.com/technologie/5770/full-node-bitcoin-ledger-live)                                                            |     [beincrypto.com](https://beincrypto.com)     |\n| 🇪🇸 [Ledger Live será compatible con nodos propios de Bitcoin](https://www.criptonoticias.com/tecnologia/ledger-live-sera-compatible-nodos-propios-bitcoin)                                                          | [CriptoNoticias](https://www.criptonoticias.com) |\n| 🇬🇧 [Bitcoin Tech Talk #218: Curing Monetary Stockholm Syndrome](https://jimmysong.substack.com/p/curing-monetary-stockholm-syndrome) (mention)                                                                      |   [Jimmy Song](https://jimmysong.substack.com)   |\n\n### Community\n\nFor feedback or support, please tag [@Ledger](https://twitter.com/Ledger) on Twitter. To report any bugs related to full node on Ledger Live, you can create issues on this repository. For support, please reach out to [Ledger Support](https://support.ledger.com/hc).\n\n### Contributing\n\nContributions in the form of code improvements, documentation, tutorials, and feedback are most welcome.\n\nFor contributions to the code, we recommend [these guidelines](https://github.com/btcsuite/btcd/blob/master/docs/code_contribution_guidelines.md).\n\n#### Call for Cowsay contributions\n\nOn startup, satstack will display a message about Bitcoin, randomly picked from a curated collection of interesting quotes, facts, email excerpts, etc. You are welcome to contribute by creating a [pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) modifying [this file](fortunes/db.go) (includes guidelines for editing the file). Here's an example of how it is rendered:\n\n\u003cimg src=\"/share/cowsay.png\" width=\"300\"\u003e\n\n##### Cowsay ideas\n\n- Extracts from [The Complete Satoshi](https://satoshi.nakamotoinstitute.org) by the [Nakamoto Institute](https://nakamotoinstitute.org).\n- Quotes by Satoshi, Hal Finney.\n- Excerpts from bitcointalk.org, email lists, etc.\n- Public criticisms of Bitcoin by famous people, media, etc. [Bitcoin Obituaries](https://99bitcoins.com/bitcoin-obituaries) is a great source.\n\nPlease mention the source when you make a contribution, so we can attribute the original author(s) and include a copy of the license if required.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fledgerhq%2Fsatstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fledgerhq%2Fsatstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fledgerhq%2Fsatstack/lists"}