Lightning Network Initialization Tasks

Lightning methods are currently only available using the native Komodo DeFi Framework. WASM support should be available in late 2023.

API-v2task::enable_lightning::init

Initialize Lightning

The task::enable_lightning::init request a task to run a lightning node. Use the returned task_id as an input to check the status of the lightning node (i.e, running or still initiating). An error will be returned if a lightning node was already running for the requested ticker.

Any methods with a task:: prefix will be linked to a numeric task_id value which is used to query the status or outcome of the task.

Request Parameters

Parameter	Type	Description
ticker	string	Ticker of coin to activate
activation_params	object	A standard LightningActivationParams object.

📌 Example

Initialize Lightning

POST

task::enable_lightning::init

{
  "method": "task::enable_lightning::init",
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "params": {
    "ticker": "tBTC-lightning",
    "activation_params": {
      "name": "KomoDeFi-Docs-Node-1",
      "listening_port": 9735,
      "color": "000000",
      "payment_retries": 5
    }
  },
  "id": 2
}

Response Parameters

Parameter	Type	Description
task_id	integer	An identifying number which is used to query task status.

Response

{
    "mmrpc": "2.0",
    "result": {
        "task_id": 1
    },
    "id": null
}

L2ConfigIsNotFound Error

Coin is not in coins file. Refer to the coins file configuration for lightning for more information.

{
	"mmrpc": "2.0",
	"error": "Layer 2 tBTC-lightning config is not found",
	"error_path": "init_l2.prelude",
	"error_trace": "init_l2:82] prelude:82]",
	"error_type": "L2ConfigIsNotFound",
	"error_data": "tBTC-lightning",
	"id": 2
}

InvalidRequest Error

A parameter is incorrect.

{
	"mmrpc": "2.0",
	"error": "Error parsing request: invalid type: string "9735", expected u16",
	"error_path": "dispatcher",
	"error_trace": "dispatcher:110]",
	"error_type": "InvalidRequest",
	"error_data": "invalid type: string "9735", expected u16",
	"id": 762
}

UnexpectedL2Protocol Error

Coin is wrong protocol type.

{
	"mmrpc": "2.0",
	"error": "Unexpected layer 2 protocol UTXO for tBTC-segwit",
	"error_path": "init_l2.prelude.lightning_activation",
	"error_trace": "init_l2:82] prelude:93] lightning_activation:92]",
	"error_type": "UnexpectedL2Protocol",
	"error_data": {
		"ticker": "tBTC-segwit",
		"protocol": {
			"type": "UTXO"
		}
	},
	"id": 2
}

Internal Error

Address already in use.

{
    "mmrpc": "2.0",
    "result": {
        "status": "Error",
        "details": {
            "error": "I/O error Address already in use (os error 48)",
            "error_path": "lib.lightning_activation.ln_p2p",
            "error_trace": "lib:103] lightning_activation:280] ln_p2p:196]",
            "error_type": "Internal",
            "error_data": "I/O error Address already in use (os error 48)"
        }
    },
    "id": null
}

PlatformCoinIsNotActivated Error

The selected coin is not activated. It needs to be activated before the lightning node can be initialized.

{
	"mmrpc": "2.0",
	"error": "Platform coin tBTC-lightning is not activated",
	"error_path": "init_l2.lp_coins",
	"error_trace": "init_l2:87] lp_coins:3087]",
	"error_type": "PlatformCoinIsNotActivated",
	"error_data": "tBTC-lightning",
	"id": 2
}

InvalidPlatformConfiguration Error

Coin's configuration is missing a required parameter. Refer to the coins file configuration for lightning for more information.

{
	"mmrpc": "2.0",
	"error": "Invalid config for platform coin: tBTC-segwit, error: 'avg_blocktime' field is not found in platform coin config",
	"error_path": "init_l2.lightning_activation",
	"error_trace": "init_l2:95] lightning_activation:254]",
	"error_type": "InvalidPlatformConfiguration",
	"error_data": {
		"platform_coin_ticker": "tBTC-segwit",
		"err": "'avg_blocktime' field is not found in platform coin config"
	},
	"id": 2
}

API-v2task::enable_lightning::status

Initialization Status

The task::enable_lightning::status request checks the status of lightning node initialization.

Request Parameters

Parameter	Type	Description
task_id	integer	The task id returned from `task::enable_lightning::init`
forget_if_finished	boolean	Optional, defaults to `true`. If `false`, the status of the `task_id` will still be available after the task has completed.

📌 Example

Initialization Status

POST

task::enable_lightning::status

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::enable_lightning::status",
  "params": {
    "task_id": 1,
    "forget_if_finished": false
  },
  "id": 2
}

Response Parameters

Parameter	Type	Description
platform_coin	string	The coin ticker for which the lightning node is being intitialized.
address	string	This node's address for the activated coin.
balance	object	A standard BalanceInfo object.

The unspendable balance for lightning is different to a layer-1 unspendable balance. The channel reserve is part of the unspendable balance in lightning - the user will get this part of the balance on chain when closing the channel, but it can't be spent on layer 2 (lightning) because it's part of the security mechanism to prevent channel breaches and ensure that both parties fulfill their obligations within the channel.

Response (ready, success)

{
    "mmrpc": "2.0",
    "result": {
        "status": "Ok",
        "details": {
            "platform_coin": "BTC-segwit",
            "address": "0321937a095229510bd2b02a930d7b7eb273147e348ef1086b22e8790e3c609804",
            "balance": {
                "spendable": "0",
                "unspendable": "0"
            }
        }
    },
    "id": null
}

In the above response spendable will always be 0 since the balance is unspendable until connections with lightning channels counterparties are established. Using the my_balance method after the coin is activated will get the spendable balance depending on how many channel counterparties are online. For exact channels balances and which channels are usable, use lightning::channels::list_open_channels_by_filter.

Response (in progress state)

{
    "mmrpc": "2.0",
    "result": {
        "status": "InProgress",
        "details": "ReadingNetworkGraphFromFile"
    },
    "id": null
}

Possible in progress statuses:

ActivatingCoin
GettingFeesFromRPC
ReadingNetworkGraphFromFile
InitializingChannelManager
InitializingPeerManager
ReadingScorerFromFile
InitializingBackgroundProcessor
ReadingChannelsAddressesFromFile

API-v2task::enable_lightning::cancel

Cancel Initialization

The task::enable_lightning::cancel request cancels lightning node initialization.

Request Parameters

Parameter	Type	Description
task_id	integer	The task id returned from `task::enable_lightning::init`

📌 Example

Cancel Initialization

POST

task::enable_lightning::cancel

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::enable_lightning::cancel",
  "params": {
    "task_id": 1
  },
  "id": 1
}

Response

{
    "mmrpc": "2.0",
    "result": "success",
    "id": null
}

TaskFinished Error

Task has already been completed.

{
    "mmrpc": "2.0",
    "error": "Task is finished already",
    "error_path": "init_l2.manager",
    "error_trace": "init_l2:157] manager:104]",
    "error_type": "TaskFinished",
    "error_data": 3,
    "id": null
}

On this page

Lightning Network Initialization Tasks

Initialize Lightning

Initialization Status

Cancel Initialization