{"id":28455542,"url":"https://github.com/elementsproject/glightning","last_synced_at":"2025-06-27T02:32:34.966Z","repository":{"id":41511665,"uuid":"484013805","full_name":"ElementsProject/glightning","owner":"ElementsProject","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-04T17:19:00.000Z","size":550,"stargazers_count":11,"open_issues_count":8,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-06T22:09:37.354Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ElementsProject.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2022-04-21T10:53:16.000Z","updated_at":"2025-02-15T05:46:45.000Z","dependencies_parsed_at":"2023-11-26T06:23:38.343Z","dependency_job_id":"d3f6e4b5-0652-4621-9ae4-17699f93f081","html_url":"https://github.com/ElementsProject/glightning","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ElementsProject/glightning","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Fglightning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Fglightning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Fglightning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Fglightning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ElementsProject","download_url":"https://codeload.github.com/ElementsProject/glightning/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Fglightning/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262177871,"owners_count":23270952,"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":"2025-06-06T22:09:39.084Z","updated_at":"2025-06-27T02:32:34.952Z","avatar_url":"https://github.com/ElementsProject.png","language":"Go","readme":"# glightning: a c-lightning plugin driver and RPC client\n\n[![CircleCI](https://circleci.com/gh/niftynei/glightning.svg?style=svg)](https://circleci.com/gh/niftynei/glightning)\n\nglightning is a driver for the Lightning Daemon [c-lightning](https://github.com/ElementsProject/lightning).\n\nIt offers an RPC client for calling lightning commands and a framework for writing \nGo-native [plugins](https://github.com/ElementsProject/lightning/blob/master/doc/PLUGINS.md)\n\n\n## Plugins: How to Use\nFor a complete example of the Hooks, Options, Subscriptions and Methods see the examples in [examples/plugin](examples/plugin/plugin_example.go)\n\nBelow is a quick primer on each of these options.\n\n\n### Options\n\nc-lightning plugins allow you to specify command line options that you can set\nwhen you startup lightningd.\n\nFor example, here's how you'd set the `name` option\n\n```\n$ ./lightningd --network=testnet --name=Ginger\n```\n\nHere's how to register an option with the `glightning` plugin.\n\n```\n// The last value is the default value, e.g. this option will default to 'Mary' \n// if not set.\noption := glightning.NewOption(\"name\", \"How you'd like to be called\", \"Mary\")\nplugin.RegisterOption(option)\n\n```\n\n### Creating a new Method\n\nYou can create your own RPC methods to add additional functionality to a clightning node by registering\nnew methods!\n\nEach method definition requires a struct that implements the jrpc2.ServerMethod interface.\nThere are three method on this interface: \n\n   - Name, which returns the callable name of the function, \n   - New, which returns a new copy of this method struct, and\n   - Call, which executes when this method is called.\n\n\nHere's a quick example\n\n```\n// Set up the struct for the RPC method you'd like to add to c-lightning\ntype Hello struct {\n\t// This method takes no parameters, so there's no fields here\n}\n\nfunc (h *Hello) New() interface{} {\n\treturn \u0026Hello{}\n}\n\n// The command line invocation of this command will be \n// ./cli/lightning-cli say-hi\nfunc (h *Hello) Name() string {\n\treturn \"say-hi\"\n}\n\n// This is what gets run when you call the command.\nfunc (h *Hello) Call() (jrpc2.Result, error) {\n\t// Here we're using an startup option value in the result\n\tname := plugin.GetOptionValue(\"name\")\n\treturn fmt.Sprintf(\"Howdy %s!\", name), nil\n}\n```\n\nA method should be registered so c-lightning knows about it. These are \ndefined before starting up the plugin.\n\n```\nplugin := glightning.NewPlugin(initfn)\n\n// The second parameter here is the short command description\nrpcHello := glightning.NewRpcMethod(\u0026Hello{}, \"Say hello!\")\nrpcHello.LongDesc = \"Say hello! To whom you'll be greeting is set by the 'name' options, passed in at startup.\"\nplugin.RegisterMethod(rpcHello)\n```\n\n\n### Subscriptions\n\nSubscriptions allow your plugin to receive a notification every time an \nevent matching the notification type occurs within c-lightning. \n\nHere's how you'd create a `connect` callback and register it with \nthe plugin.\n\n    func OnConnect(e *glightning.ConnectEvent) {\n        log.Printf(\"Connected to %s\\n\", e.PeerId)\n    }\n    \n    func main() {\n    \tplugin := glightning.NewPlugin(initfn)\n\tplugin.SubscribeConnect(OnConnect)\n    }\n\n\n### Initializing a Plugin\n\nc-lightning will call your plugin's Init method when it's started. `glightning` registers this for you automatically. \nYou need to supply the `NewPlugin` method with a callback function that will trigger once the plugin has been initialized.\n\nThe init function has the following signature:\n\n```\nfunc onInit(plugin *glightning.Plugin, options map[string]glightning.Option, config *glightning.Config)\n```\n\n### Wiring into Lightning's RPC\n\nThe `init` command call will pass back to your plugin a Config object, which includes a lightning-rpc filename and the lightning directory. You can pass this\ninformation directly into `glightning`'s `Lightning.StartUp` to create a working\nRPC connection. e.g.\n\n```\ngo lightning.StartUp(config.RpcFile, config.LightningDir)\n```\n\nAfter the connection has been opened, `lightning.IsUp()` will flip to `true`.\nYou can make any calls provided on the Lightning RPC then. \n\n```\n\tlightning.StartUp(config.RpcFile, config.LightningDir)\n\tchannels, _ := lightning.ListChannels()\n\tlog.Printf(\"You know about %d channels\", len(channels))\n```\n\n\n### Dynamic plugin loading and unloading\n\nPlugins can be configured to be dynamically controlled through the CLI/RPC.  \nBy default a plugin loaded at startup will be stoppable.  This behavior can be \noverridden by calling the plugin's `SetDynamic` command.\n\n```\nfunc main() {\n\tplugin := glightning.NewPlugin(initfn)\n\tplugin.SetDynamic(false)\n}\n```\n\nwill disable management with the [plugin control](https://github.com/ElementsProject/lightning/blob/master/doc/lightning-plugin.7.txt) feature.\n\n\n## Logging as a c-lightning Plugin\n\nThe c-lightning plugin subsystem uses stdin and stdout as its communication pipes. As most logging would \ninterfere with normal operation of the plugin `glightning` overrides the `log` package to pipe all \nlogs to c-lightning. When developing a plugin, it is best practice to use the `log` library write \nall print statements, so as not to interfere with normal operation of the plugin.\n\nYou can override this by providing a logfile to write to via the environment variable \n`GOLIGHT_DEBUG_LOGFILE`. See [plugin debugging](#plugin_debugging).\n\n\n### Plugin Debugging\n\n`glightning` provides a few environment variables to help with debugging.\n\n`GOLIGHT_DEBUG_LOGFILE`: If set, will log to the file named in this variable. Otherwise, sends logs back to c-lightning to be added to its internal log buffer.\n\n`GOLIGHT_DEBUG_IO_IN`: Logs any incoming IO messages. Useful if you want to log incoming messages without specifying a debug log file.\n\n`GOLIGHT_DEBUG_IO`: Logs all json messages sent and received from c-lightning. Must be used in conjunction with `GOLIGHT_DEBUG_LOGFILE` to avoid creating a log loop.\n\n\nExample usage: \n\n```\n$ GOLIGHT_DEBUG_IO=1 GOLIGHT_DEBUG_LOGFILE=plugin.log lightningd --plugin=/path/to/plugin/exec --daemon \n```\n\n\n#### Using Strict Mode\n\nglightning is meant to be used with the corresponding c-lightning version. Updates to the \nc-lightning RPC API are reflected in each new glightning version.\n\nSupport for older versions of lightningd is coming soon TM\n\nThe default configuration of glightning is such that it works `allow-deprecated-apis=true`, which is the \ndefault setting on c-lightning; however if you wish to run it 'strict mode', such that glightning \nwill fail if an RPC response includes unexpected parameters, you should set the environment \nvariable`GOLIGHT_STRICT_MODE=1` and the c-lightning startup flag `allow-deprecated-apis=false`.\n\n\n### Dev Commands\n\nNote that most of the 'dev' commands aren't well tested, and that many of them require you to set \nvarious flags at compile or configuration time (of lightningd) in order to use them. You'll \nneed to at least have configured your c-lightning build into developer mode, ie:\n\n```\ncwd/lightning$ ./configure --enable-developer \u0026\u0026 make\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felementsproject%2Fglightning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felementsproject%2Fglightning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felementsproject%2Fglightning/lists"}