DotNetLightning


PluginServerBase Type

abstract base class for your c-lightning plugin. It talks to c-lightning through stdin/stdout. It will automatically create methods necessary for working as a plugin for you.

1. rpc method exposure

If you want to handle an rpc call from users, you must implement the rpc handler, and annotate the handler with PluginJsonRpcMethod, which is a class that inherits from StreamJsonRpc.JsonRpcMethod It will automatically be exposed as an additional rpc method for c-lightning. The behavior of argument binding etc can be found at StreamJsonRpc's document

IMPORTANT: plugin will use stdin/stdout for communicating with c-lightning, so you must never write naively to stdout in your application's code otherwise json rpc messages will be corrupted.

If you really want to do it, say for logging, use the same synchronized stream for both plugin and your code. i.e.

1: 
2: 
3: 
4: 
let outputStream = Console.OpenStandardOutput() |> Stream.Synchronized
let logger = MyCustomLogger(outputStream) // log to output stream
let plugin =
    MyPlugin().StartAsync(outputStream, Console.OpenStandardInput())

Or just use stderr (e.g. from Console.Error)

2. Subscribing to the topic.

If you want to subscribe to a notification from c-lightning (or other plugins), You must implement it with PluginJsonRpcSubscription instead of PluginJsonRpcMethod. By using it, the response value is ignored by c-lightning, and the method is not exposed to an user.

3. sending notification to c-lightning

plugins can send notification to c-lightning, Use SendNotification method for it. But before that, you must register the notification topics with constructor argument to PluginServerBase, since c-lightning must know the list of possible topics beforehand.

4. other features

For other features, e.g. taking cli options, validating c-lightning init message, etc, see corresponding abstract properties or methods.

If you set ObsoleteAttribute to methods, those will not be shown to users unless they specify "allow-deprecated-apis" to true.

Hooks are currently unsupported since it is a quite advanced feature. Please send a PR if you really want it.

val outputStream: obj
val logger: obj
val plugin: obj

Constructors

Constructor Description

PluginServerBase(logger)

Full Usage: PluginServerBase(logger)

Parameters:
    logger : string -> unit

Returns: PluginServerBase
logger : string -> unit
Returns: PluginServerBase

PluginServerBase(topics, logger)

Full Usage: PluginServerBase(topics, logger)

Parameters:
    topics : seq<string>
    logger : string -> unit

Returns: PluginServerBase
topics : seq<string>
logger : string -> unit
Returns: PluginServerBase

PluginServerBase(topics, dynamic)

Full Usage: PluginServerBase(topics, dynamic)

Parameters:
    topics : seq<string>
    dynamic : bool

Returns: PluginServerBase
topics : seq<string>
dynamic : bool
Returns: PluginServerBase

PluginServerBase(topics)

Full Usage: PluginServerBase(topics)

Parameters:
    topics : seq<string>

Returns: PluginServerBase
topics : seq<string>
Returns: PluginServerBase

PluginServerBase()

Full Usage: PluginServerBase()

Returns: PluginServerBase
Returns: PluginServerBase

PluginServerBase(dynamic)

Full Usage: PluginServerBase(dynamic)

Parameters:
    dynamic : bool

Returns: PluginServerBase
dynamic : bool
Returns: PluginServerBase

PluginServerBase(notificationTopics, dynamic, logDebug)

Full Usage: PluginServerBase(notificationTopics, dynamic, logDebug)

Parameters:
    notificationTopics : seq<string> - The list of topic names that might be notified to c-lightning by SendNotification
    dynamic : bool - Is it ok for this plugin to terminate when the c-lightning sends "stop" call. set false if the plugin is critical for an user and it should never stop.
    logDebug : string -> unit - custom logging function for debug message on startup.

Returns: PluginServerBase
notificationTopics : seq<string>

The list of topic names that might be notified to c-lightning by SendNotification

dynamic : bool

Is it ok for this plugin to terminate when the c-lightning sends "stop" call. set false if the plugin is critical for an user and it should never stop.

logDebug : string -> unit

custom logging function for debug message on startup.

Returns: PluginServerBase

Instance members

Instance member Description

this.AsyncSemaphore

Full Usage: this.AsyncSemaphore

Returns: AsyncSemaphore

Semaphore to assure the thread safety when writing to the stdout.

Returns: AsyncSemaphore

this.Dynamic

Full Usage: this.Dynamic

Returns: bool

If this value is false, c-lightning will never try to stop this plugin. default: false

Returns: bool

this.FeatureBits

Full Usage: this.FeatureBits

Modifiers: abstract

Plugins can set its own feature bits, this value will be passed to c-lightning through getmanifest and it will be announced to other nodes in several ways.

this.GetClientOutputStream

Full Usage: this.GetClientOutputStream

output stream for client to send notification. Default is STDOUT. you can replace your own in test.

this.GetManifest

Full Usage: this.GetManifest

Parameters:
    ?allow-deprecated-apis : bool
    ?_otherparams : obj

Returns: Task<Manifest>
?allow-deprecated-apis : bool
?_otherparams : obj
Returns: Task<Manifest>

this.GetStdoutClient

Full Usage: this.GetStdoutClient

Returns: ClnClient
Returns: ClnClient

this.Init

Full Usage: this.Init

Parameters:
Returns: Task<obj>
configuration : LightningInitConfigurationDTO
options : Dictionary<string, obj>
Returns: Task<obj>

this.InitCore

Full Usage: this.InitCore

Parameters:
Modifiers: abstract

When the c-lightning gets ready, it will send you init rpc call. You probably want to validate the init msg and abort the plugin when the value passed in is not the one expected. You may also want to store the configuration object as your need. If this method throws exception, the plugin shuts down.

configuration : LightningInitConfigurationDTO
cliOptions : Dictionary<string, obj>

this.InitializationStatus

Full Usage: this.InitializationStatus

The status of how we have processed the init message from c-lightning

this.JsonConverters

Full Usage: this.JsonConverters

You can add optional JsonConverters for your own type with this property.

this.JsonRpc

Full Usage: this.JsonRpc

this.Network

Full Usage: this.Network

this.Options

Full Usage: this.Options

Modifiers: abstract

CLI options that plugin takes from users (via lightningd's initialization options).

this.SendNotification

Full Usage: this.SendNotification

Parameters:
Returns: Task<unit>

Send notification to the c-lightning, the topic must be registered in constructor parameter of PluginServerBase

topic : string
arg : 'T
?cancellationToken : CancellationToken
Returns: Task<unit>

this.StartAsync

Full Usage: this.StartAsync

Parameters:
Returns: Task<PluginJsonRpc>
cancellationToken : CancellationToken
Returns: Task<PluginJsonRpc>

this.StartAsync

Full Usage: this.StartAsync

Returns: Task<PluginJsonRpc>
Returns: Task<PluginJsonRpc>

this.StartAsync

Full Usage: this.StartAsync

Parameters:
Returns: Task<PluginJsonRpc>
pipeWriter : PipeWriter
pipeReader : PipeReader
Returns: Task<PluginJsonRpc>

this.StartAsync

Full Usage: this.StartAsync

Parameters:
Returns: Task<PluginJsonRpc>
outStream : Stream
inStream : Stream
Returns: Task<PluginJsonRpc>

this.StartAsync

Full Usage: this.StartAsync

Parameters:
Returns: Task<PluginJsonRpc>
outStream : Stream
inStream : Stream
ct : CancellationToken
Returns: Task<PluginJsonRpc>

this.StartAsync

Full Usage: this.StartAsync

Parameters:
Returns: Task<PluginJsonRpc>

Start listening as a rpc server, returns a task when finish processing "init" message from c-lightning.

You can inject streams other than STDIN/STDOUT with parameters. This feature might be useful for testing.

writer : PipeWriter
reader : PipeReader
cancellationToken : CancellationToken
Returns: Task<PluginJsonRpc>