{"id":13499202,"url":"https://github.com/fiatjaf/sparko","last_synced_at":"2025-03-29T04:30:49.814Z","repository":{"id":48507463,"uuid":"178970766","full_name":"fiatjaf/sparko","owner":"fiatjaf","description":"c-lightning RPC over HTTP with fine-grained permissions, SSE and spark-wallet support","archived":true,"fork":false,"pushed_at":"2023-03-22T19:44:09.000Z","size":109,"stargazers_count":38,"open_issues_count":4,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-28T18:03:45.103Z","etag":null,"topics":["bitcoin","c-lightning","lightning","lightning-wallet","lightningd-plugin","sse","wallet"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fiatjaf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-04-02T00:52:30.000Z","updated_at":"2023-07-23T13:38:24.000Z","dependencies_parsed_at":"2024-01-16T09:57:26.416Z","dependency_job_id":"ed146962-4a03-449d-b497-cd192072542e","html_url":"https://github.com/fiatjaf/sparko","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiatjaf%2Fsparko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiatjaf%2Fsparko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiatjaf%2Fsparko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiatjaf%2Fsparko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fiatjaf","download_url":"https://codeload.github.com/fiatjaf/sparko/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246140565,"owners_count":20729797,"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","c-lightning","lightning","lightning-wallet","lightningd-plugin","sse","wallet"],"created_at":"2024-07-31T22:00:30.781Z","updated_at":"2025-03-29T04:30:49.186Z","avatar_url":"https://github.com/fiatjaf.png","language":"Go","funding_links":[],"categories":["Applications"],"sub_categories":["Desktop Interfaces"],"readme":"# The `sparko` plugin.\n\nThe famous [Spark wallet](https://github.com/shesek/spark-wallet) repackaged as a single-binary lightningd plugin.\n\nThis works either as a personal wallet with a nice UI (see link above) or as a **full-blown HTTP-RPC bridge to your node that can be used to develop apps**.\n\nIt has some differences (advantages?) over the original Spark wallet:\n\n  * Single binary: No dependencies to manage, just grab the manage and throw it in your `lightningd` plugins folder.\n  * Runs as a plugin: this means you don't have to manage the server, it will be managed by `lightningd` and will always be running as long as your node is running.\n  * Multiple keys with fine-grained permissions: create keys that can only call some methods.\n  * Centralized options management: since it runs as a plugin all options are read from your `lightningd` config file.\n  * Written in Go: lean, fast, relatively low on memory, doesn't require installing Node.js and a ton of dependencies.\n  * Unrestricted: any method can be called through the HTTP/JSON-RPC interface, including any methods provided by plugins you might have active in your node.\n  * Event streaming: makes it easy to write remote Lightning apps by exposing a [SSE stream](#listen-to-events) of all events (payments sent, received etc.) that happen on the node.\n  * No default login: you don't have to expose \"super user\" credentials over your node. You can have only access-keys to specific methods. But you can define a login an password too, of course.\n\n# How to install\n\nThis is distributed as a single binary for your delight (or you can compile it yourself with `go get`, or ask me for binaries for other systems if you need them).\n\n[Download it](https://github.com/fiatjaf/sparko/releases), call `chmod +x \u003cbinary\u003e` and put it in `~/.lightning/plugins` (create that directory if it doesn't exist).\n\nYou only need the binary you can get in [the releases page](https://github.com/fiatjaf/sparko/releases), nothing else.\n\n# How to use\n\nJust configure the options you want in you `~/.lightning/config` file, like the following:\n\n```shell\nsparko-host=0.0.0.0\nsparko-port=9737\n\n# the tls path is just the directory where your self-signed key and certificate are.\n# (see below for code snippets that generate them on Linux)\n# the path is relative to your lightning-dir, so \"sparko-tls\" will translate to \"~/.lightning/bitcoin/sparko-tls/\"\n# (you can also use an absolute path)\n# if not specified the app will run without TLS (as http://)\nsparko-tls-path=sparko-tls\n\n# login credentials for using the wallet app.\n# under the hood these are translated into an access key with full access.\n# the default login is none, which doesn't allow you to use the wallet app,\n#   but you can still use the /rpc endpoint with other keys specified at sparko-keys=\nsparko-login=mywalletusername:mywalletpassword\n\n# a list of semicolon-separated pairs of keys:permissions\n#   - each possible callable RPC method is a permission.\n#   - 'stream' is a special method that gives access to the SSE stream at /stream.\n#   - just writing the key and nothing else means that key has all permissions.\n#   - keys must be secret and random.\nsparko-keys=masterkeythatcandoeverything; secretaccesskeythatcanreadstuff: getinfo, listchannels, listnodes; verysecretkeythatcanpayinvoices: pay; keythatcanlistentoallevents: stream\n# for the example above the initialization logs (mixed with lightningd logs) should print something like\n2019/09/27 00:48:46 plugin-sparko Keys read: masterkeythatcandoeverything (full-access), secretaccesskeythatcanreadstuff (3 permission), verysecretkeythatcanpayinvoices(1 permission), keythatcanlistentoallevents (1 permission)\n```\n\nTo use TLS with a self-signed certificate (`https://`), generate your certificate first:\n\n```\nmkdir ~/.lightning/bitcoin/sparko-tls\ncd ~/.lightning/bitcoin/sparko-tls/\nopenssl genrsa -out key.pem 2048\nopenssl req -new -x509 -sha256 -key key.pem -out cert.pem -days 3650\n```\n\nTo use a certificate signed by LetsEncrypt, you must be able to bind to ports 80 and 443, which generally requires running as root. Specify options like the following:\n\n```shell\nsparko-host=sparko.mydomain.com\nsparko-tls-path=sparko-letsencrypt\nsparko-letsencrypt-email=myemail@gmail.com\n```\n\nThen try to visit `http://sparko.mydomain.com/`. If all is well you should get redirected to the `https://` page, if something is wrong it should appear on the logs.\n\nTo expose Sparko over CORS (who knows why), add `sparko-allow-cors=true` to the config file.\n\n## Errors\n\nWhen starting `lightningd`, check the logs for errors regarding `sparko` initialization, they will be prefixed with `\"plugin-sparko\"`.\n\n## Call the HTTP RPC\n\nReplace the following with your actual values:\n\n```\ncurl -k https://0.0.0.0:9737/rpc -d '{\"method\": \"pay\", \"params\": [\"lnbc...\"]}' -H 'X-Access: masterkeythatcandoeverything'\n```\n\nSee also [a list of client libraries](#client-libraries).\n\n### `Range` headers\n\nYou can also limit the number of things you're returning. For example, `listinvoices` and `listsendpays` tend to get out of hand quickly and you may not want to return all your invoices and payments. You can add a `Range` header to solve this issue:\n\n```\ncurl -k https://0.0.0.0:9737/rpc -d '{\"method\": \"listsendpays\"}' -H 'X-Access: masterkeythatcandoeverything' -H 'Range: payments=0-99'\n```\n\nThe above means that `sparko` will take the response it gets from `lightningd` and slice the array contained in the key `\"payments\"` to get values between 0 and 99, i.e., the first 100 payments. You could get the last 50 payments, for example, by passing `-H 'Range: payments=-50'` and so on. This is method-agnostic (that's why you must supply the `payments=` parameter), so you can use it on other methods and even methods provided by other plugins.\n\n## Listen to events\n\nSparko exposes a [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint at `/stream` that emits [all events](https://lightning.readthedocs.io/PLUGINS.html#event-notifications) a plugin may receive, in raw format given by lightningd. In some cases that's what you want when developing applications that must talk to a Lightning node remotely, better than webhooks. There are libraries for listening to Server-Sent Events in all languages. The `/stream` endpoint requires the `stream` permission to be accessed.\n\n## Client libraries\n\n * [JavaScript](https://github.com/fiatjaf/sparko-client) (Node.js and the browser)\n * [Go](https://pkg.go.dev/github.com/fiatjaf/lightningd-gjson-rpc?tab=doc#Client) (initialize it with the Spark URL and key/token instead of a lightning-rpc socket path)\n\n## Polar integration\n\n * There is an arm64 CLN w/ sparko plugin polar image [here](https://hub.docker.com/r/chongjin/polar-cln-sparko)\n * The instruction for installation \u0026 usage is on the page\n\n## Open the wallet UI\n\nThis is the same code used in [Spark wallet](https://github.com/shesek/spark-wallet).\n\nVisit `https://0.0.0.0:9737/`. Only available if `sparko-login` is provided.\n\n## Built with [github.com/fiatjaf/lightningd-gjson-rpc](https://pkg.go.dev/github.com/fiatjaf/lightningd-gjson-rpc/plugin?tab=doc)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffiatjaf%2Fsparko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffiatjaf%2Fsparko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffiatjaf%2Fsparko/lists"}