clplug: Create Core Lightning Plugins

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Library to create plugins to extend the functionality of Core Lightning daemon.


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.2.0.0, 0.3.0.0, 0.3.1.0, 0.3.1.0, 0.3.2.0, 0.3.3.0, 0.4.0.0, 1.0.0.0
Change log CHANGELOG.md
Dependencies aeson (<2.1), attoparsec (<0.15), base (>=4.7 && <5), bytestring (<0.12), conduit (<1.4), mtl (<2.3), network (<3.2), text (<1.3) [details]
License BSD-3-Clause
Copyright 2023
Author Taylor Singleton-Fookes
Maintainer taylorsingletonfookes@live.com
Category bitcoin, lightning, plugin
Home page https://github.com/AutonomousOrganization/blitz#readme
Bug tracker https://github.com/AutonomousOrganization/blitz/issues
Source repo head: git clone https://github.com/AutonomousOrganization/blitz
Uploaded by autonomousorganization at 2023-03-17T05:02:18Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for clplug-0.3.1.0

[back to package description]

Core Lightning Plug

Create core lightning (lightningd) plugins in haskell.

To get started you need to import the Library. It is on hackage as clplug or you can load it from github in the stack.yaml:

extra-deps:
- git: https://github.com/autonomousorganization/blitz.git
  commit: a916dd3d74780e1023b161b4e85773ccc06051d4

Once the library is imported there are two external modules. Data.Lightning is all of the data types for the manifest, the notification and the hooks. Control.Plugin contains the monadic context and interface to your node.

A manifest defines the interface your plugin will have with core lightning.

import Data.Aeson
import Data.Lightning
manifest = object [
       "dynamic" .= True
     , "subscriptions" .= ([] :: [Text] )
     , "options" .= ([]::[Option])
     , "rpcmethods" .= ([
         , RpcMethod "command" "[label]" "description" Nothing False
         ])
     , "hooks" .= ([Hook "invoice_payment" Nothing])
     , "featurebits" .= object [ ]
     , "notifications" .= ([]::[Notification])
     ]

A start function runs in the InitMonad, it has access to a reader (ask) and to lightningCli. The data that returns from this function will initialize the state that is shared in the PluginMonad. If you want to run a service fork a thread within this function. The lightningCli function interfaces to core lightnings rpc. The available functions depend on your version of core lightning and the set of plugins you have installed. You need to pass a Command that defines the data you want returned in a filter.

import Control.Plugin 
import Control.Client
start = do 
    (rpcHandle, Init options config) <- ask
    Just response <- lightningCli (Command "getinfo" filter params)
    _ <- liftIO . forkIO $ < service > 
    return < state >

An app function runs every time data comes in from the plugin. You define handlers that processes the data. If an id is present that means that core lightning is expecting a response and default node operation or the operation of other plugins may be pending your response. Use release to allow default to continue, reject to abort default behavior, and respond to send a custom response which in the case of custom rpcmethods will pass through back to the user.

app :: (Maybe Id, Method, Params) -> PluginMonad a b
app (Just i, "method", params) = 
    if contition 
        then release i 
        else reject i      

Finally use the plugin function to create an executable that can be installed as a plugin!

main :: IO ()
main = plugin manifest start app

tipjar: bc1q5xx9mathvsl0unfwa3jlph379n46vu9cletshr