AddSession

AddSession adds and starts a new LNC session.

Source: lit-sessions.proto

gRPC

rpc AddSession (AddSessionRequest) returns (AddSessionResponse);

REST

HTTP Method	Path
POST	/v1/sessions

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:8443'
const MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
const TLS_PATH = 'LIT_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('lit-sessions.proto', loaderOptions);
const litrpc = grpc.loadPackageDefinition(packageDefinition).litrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new litrpc.Sessions(GRPC_HOST, creds);
let request = {
  label: <string>,
  session_type: <SessionType>,
  expiry_timestamp_seconds: <uint64>,
  mailbox_server_addr: <string>,
  dev_server: <bool>,
  macaroon_custom_permissions: <MacaroonPermission>,
  account_id: <string>,
};
client.addSession(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "session": <Session>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lit-sessions.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lit-sessions_pb2 as litrpc, lit-sessions_pb2_grpc as lit-sessionsstub

GRPC_HOST = 'localhost:8443'
MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
TLS_PATH = 'LIT_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = lit-sessionsstub.SessionsStub(channel)
request = litrpc.AddSessionRequest(
  label=<string>,
  session_type=<SessionType>,
  expiry_timestamp_seconds=<uint64>,
  mailbox_server_addr=<string>,
  dev_server=<bool>,
  macaroon_custom_permissions=<MacaroonPermission>,
  account_id=<string>,
)
response = stub.AddSession(request)
print(response)
# {
#    "session": <Session>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8443'
const MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'

let requestBody = {
  label: <string>, // <string> 
  session_type: <string>, // <SessionType> 
  expiry_timestamp_seconds: <string>, // <uint64> 
  mailbox_server_addr: <string>, // <string> 
  dev_server: <boolean>, // <bool> 
  macaroon_custom_permissions: <array>, // <MacaroonPermission> 
  account_id: <string>, // <string> 
};
let options = {
  url: `https://${REST_HOST}/v1/sessions`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "session": <object>, // <Session> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8443'
MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
TLS_PATH = 'LIT_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/sessions'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'label': <string>,
  'session_type': <SessionType>,
  'expiry_timestamp_seconds': <uint64>,
  'mailbox_server_addr': <string>,
  'dev_server': <bool>,
  'macaroon_custom_permissions': <MacaroonPermission>,
  'account_id': <string>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "session": <Session>,
# }

Shell

$ litcli sessions add --help

NAME:
   litcli sessions add - Create a new Lightning Node Connect session.

USAGE:
   litcli sessions add [command options] [arguments...]

DESCRIPTION:
   Add a new active session.

OPTIONS:
   --label value              The session label.
   --expiry value             The number of seconds that the session should remain active. (default: 7776000)
   --mailboxserveraddr value  The host:port of the mailbox server to be used. (default: "mailbox.terminal.lightning.today:443")
   --devserver                Set to true to skip verification of the server's tls cert.
   --type value               The session type to be created which will determine the permissions a user has when connecting with the session; options include readonly|admin|account|custom. (default: "readonly")
   --uri lnrpc                The URI that should be included in the macaroon of a custom session. Note that this flag will only be used if the 'type' flag is set to 'custom'. This flag can be specified multiple times if multiple URIs should be included. Note that a regex can also be specified which will then result in all URIs matching the regex to be included. For example, '/lnrpc\..*' will result in all lnrpc permissions being included.
   --account_id value         The account id that should be used for the account session. Note that this flag will only be used if the 'type' flag is set to 'account'.
   

Messages

litrpc.AddSessionRequest

Source: lit-sessions.proto

Field	gRPC Type	REST Type	REST Placement
label A user assigned label for the session.	string	string	body
session_type The session type. This will be used during macaroon construction to determine how restrictive to make the macaroon and thus the session access.	SessionType	string	body
expiry_timestamp_seconds The time at which the session should automatically be revoked.	uint64	string	body
mailbox_server_addr The address of the mailbox server that the LNC connection should use.	string	string	body
dev_server If set to true, tls will be skipped when connecting to the mailbox.	bool	boolean	body
macaroon_custom_permissions Any custom permissions to add the session's macaroon.	MacaroonPermission[]	array	body
account_id The ID of the account to associate this session with. This should only be set if the session_type is TYPE_MACAROON_ACCOUNT.	string	string	body

litrpc.AddSessionResponse

Source: lit-sessions.proto

Field	gRPC Type	REST Type
session The session of the newly created session.	Session	object

Nested Messages

litrpc.ChannelConstraint

Field	gRPC Type	REST Type
min_capacity_sat The minimum channel size autopilot has to set for a channel.	uint64	string
max_capacity_sat The maximum channel size autopilot can set for a channel.	uint64	string
max_push_sat The maximum push amount for a channel.	uint64	string
private_allowed Indicates whether opening of private channels is allowed.	bool	boolean
public_allowed Indicates whether opening of public channels is allowed.	bool	boolean

litrpc.ChannelPolicyBounds

Field	gRPC Type	REST Type
min_base_msat The minimum base fee in msat that the autopilot can set for a channel.	uint64	string
max_base_msat The maximum base fee in msat that the autopilot can set for a channel.	uint64	string
min_rate_ppm The minimum ppm fee in msat that the autopilot can set for a channel.	uint32	integer
max_rate_ppm The maximum ppm fee in msat that the autopilot can set for a channel.	uint32	integer
min_cltv_delta The minimum cltv delta that the autopilot may set for a channel.	uint32	integer
max_cltv_delta The maximum cltv delta that the autopilot may set for a channel.	uint32	integer
min_htlc_msat The minimum htlc msat that the autopilot may set for a channel.	uint64	string
max_htlc_msat The maximum htlc msat that the autopilot may set for a channel.	uint64	string

litrpc.ChannelRestrict

Field	gRPC Type	REST Type
channel_ids A list of channel IDs that the Autopilot should not perform any actions on.	uint64[]	array

litrpc.HistoryLimit

Field	gRPC Type	REST Type
start_time The absolute unix timestamp in seconds before which no information should be shared. This should only be set if duration is not set.	uint64	string
duration The maximum relative duration in seconds that a request is allowed to query for. This should only be set if start_time is not set.	uint64	string

litrpc.MacaroonPermission

Field	gRPC Type	REST Type
entity The entity a permission grants access to. If a entity is set to the "uri" keyword then the action entry should be one of the special cases described in the comment for action.	string	string
action The action that is granted. If entity is set to "uri", then action must be set to either: - a particular URI to which access should be granted. - a URI regex, in which case access will be granted to each URI that matches the regex. - the "readonly" keyword. This will result in the access being granted to all read-only endpoints.	string	string

litrpc.MacaroonRecipe

Field	gRPC Type	REST Type
permissions A list of permissions that should be included in the macaroon.	MacaroonPermission[]	array
caveats A list of caveats to add to the macaroon.	string[]	array

litrpc.OffChainBudget

Field	gRPC Type	REST Type
max_amt_msat The maximum amount that can be spent off-chain excluding fees.	uint64	string
max_fees_msat The maximum amount that can be spent off-chain on fees.	uint64	string

litrpc.OnChainBudget

Field	gRPC Type	REST Type
absolute_amt_sats The maximum amount that can be spent on-chain including fees.	uint64	string
max_sat_per_v_byte The maximum amount that can be spent on-chain in fees.	uint64	string

litrpc.PeerRestrict

Field	gRPC Type	REST Type
peer_ids A list of peer IDs that the Autopilot should not perform any actions on.	string[]	array

litrpc.Rate

Field	gRPC Type	REST Type
iterations The number of times a call is allowed in num_hours number of hours.	uint32	integer
num_hours The number of hours in which the iterations count takes place over.	uint32	integer

litrpc.RateLimit

Field	gRPC Type	REST Type
read_limit The rate limit for read-only calls.	Rate	object
write_limit The rate limit for write/execution calls.	Rate	object

litrpc.RulesMap

Field	gRPC Type	REST Type
rules A map of rule name to RuleValue. The RuleValue should be parsed based on the name of the rule.	RulesEntry[]	object

litrpc.RulesMap.RulesEntry

Field	gRPC Type	REST Type
key	string	unknown
value	RuleValue	unknown

litrpc.RuleValue

Field	gRPC Type	REST Type
rate_limit	RateLimit	object
chan_policy_bounds	ChannelPolicyBounds	object
history_limit	HistoryLimit	object
off_chain_budget	OffChainBudget	object
on_chain_budget	OnChainBudget	object
send_to_self	SendToSelf	object
channel_restrict	ChannelRestrict	object
peer_restrict	PeerRestrict	object
channel_constraint	ChannelConstraint	object

litrpc.SendToSelf

note

This response has no parameters.

litrpc.Session

Field	gRPC Type	REST Type
id A unique ID assigned to the session. It is derived from the session macaroon.	bytes	string
label A user assigned label for the session.	string	string
session_state The current state that the session is in. This will give an indication of if the session is currently usable or not.	SessionState	string
session_type The session type. The will given an indication of the restrictions applied to the macaroon assigned to the session.	SessionType	string
expiry_timestamp_seconds The time at which the session will automatically be revoked.	uint64	string
mailbox_server_addr The address of the mailbox server that the LNC connection should use.	string	string
dev_server If set to true, tls will be skipped when connecting to the mailbox.	bool	boolean
pairing_secret The LNC pairing phrase in byte form.	bytes	string
pairing_secret_mnemonic The LNC pairing phrase in mnemonic form.	string	string
local_public_key The long term, local static public key used by this node for the LNC connection.	bytes	string
remote_public_key The long term, remote static public key used by the remote party for the LNC connection.	bytes	string
created_at The time at which the session was created.	uint64	string
macaroon_recipe The recipe used for creating a macaroon to use with this session. This will be closely linked to the session type.	MacaroonRecipe	object
account_id If the session is for a specific account, then this will be the account ID it is associated with.	string	string
autopilot_feature_info If this session is for Autopilot use, then this will be the set of features that the session can be used for along with the rules for each feature.	AutopilotFeatureInfoEntry[]	object
revoked_at The unix timestamp indicating the time at which the session was revoked. Note that this field has not been around since the beginning and so it could be the case that a session has been revoked but that this field will not have been set for that session. Therefore, it is suggested that readers should not assume that if this field is zero that the session is not revoked. Readers should instead first check the session_state field.	uint64	string
group_id The ID of the group of Session's that this Session is linked to. If this session is not linked to any older Session, then this value will be the same as the ID.	bytes	string
feature_configs Configurations for each individual feature mapping from the feature name to a JSON-serialized configuration.	FeatureConfigsEntry[]	object
privacy_flags Privacy flags used for the session that determine how the privacy mapper operates.	uint64	string

litrpc.Session.AutopilotFeatureInfoEntry

Field	gRPC Type	REST Type
key	string	unknown
value	RulesMap	unknown

litrpc.Session.FeatureConfigsEntry

Field	gRPC Type	REST Type
key	string	unknown
value	string	unknown

Enums

litrpc.SessionState

Name	Number
STATE_CREATED	0
STATE_IN_USE	1
STATE_REVOKED	2
STATE_EXPIRED	3

litrpc.SessionType

Name	Number
TYPE_MACAROON_READONLY	0
TYPE_MACAROON_ADMIN	1
TYPE_MACAROON_CUSTOM	2
TYPE_UI_PASSWORD	3
TYPE_AUTOPILOT	4
TYPE_MACAROON_ACCOUNT	5