AddAutopilotSession

AddAutopilotSession creates a new LNC session and attempts to register it with the Autopilot server.

Source: lit-autopilot.proto

gRPC

rpc AddAutopilotSession (AddAutopilotSessionRequest) returns (AddAutopilotSessionResponse);

REST

HTTP Method	Path
POST	/v1/autopilot/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-autopilot.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.Autopilot(GRPC_HOST, creds);
let request = {
  label: <string>,
  expiry_timestamp_seconds: <uint64>,
  mailbox_server_addr: <string>,
  dev_server: <bool>,
  features: <FeaturesEntry>,
  session_rules: <RulesMap>,
  no_privacy_mapper: <bool>,
  linked_group_id: <bytes>,
  privacy_flags: <uint64>,
  privacy_flags_set: <bool>,
};
client.addAutopilotSession(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-autopilot.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lit-autopilot_pb2 as litrpc, lit-autopilot_pb2_grpc as lit-autopilotstub

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-autopilotstub.AutopilotStub(channel)
request = litrpc.AddAutopilotSessionRequest(
  label=<string>,
  expiry_timestamp_seconds=<uint64>,
  mailbox_server_addr=<string>,
  dev_server=<bool>,
  features=<FeaturesEntry>,
  session_rules=<RulesMap>,
  no_privacy_mapper=<bool>,
  linked_group_id=<bytes>,
  privacy_flags=<uint64>,
  privacy_flags_set=<bool>,
)
response = stub.AddAutopilotSession(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> 
  expiry_timestamp_seconds: <string>, // <uint64> 
  mailbox_server_addr: <string>, // <string> 
  dev_server: <boolean>, // <bool> 
  features: <object>, // <FeaturesEntry> 
  session_rules: <object>, // <RulesMap> 
  no_privacy_mapper: <boolean>, // <bool> 
  linked_group_id: <string>, // <bytes> (base64 encoded)
  privacy_flags: <string>, // <uint64> 
  privacy_flags_set: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/autopilot/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/autopilot/sessions'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'label': <string>,
  'expiry_timestamp_seconds': <uint64>,
  'mailbox_server_addr': <string>,
  'dev_server': <bool>,
  'features': <FeaturesEntry>,
  'session_rules': <RulesMap>,
  'no_privacy_mapper': <bool>,
  'linked_group_id': base64.b64encode(<bytes>),
  'privacy_flags': <uint64>,
  'privacy_flags_set': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "session": <Session>,
# }

Shell

$ litcli autopilot add --help

NAME:
   litcli autopilot add - Initialize an Autopilot session.

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

DESCRIPTION:
   
  Initialize an Autopilot session.

  If one of the 'feature-' flags is set for any 'feature', then that flag
  must be provided for each 'feature'.

  The rules and configuration options available for each feature can be
  seen in the 'autopilot features' output. For a rule, all fields must be
  set since the unset ones are interpreteded as zero values. Rule values
  must adhere to the limits found in 'autopilot features'. If a rule is
  not set, default values are used.
  
  An example call for AutoFees reads:
  
  #!/bin/bash
  ./litcli autopilot add --label=customRules \
  --feature=AutoFees \
  --feature-rules='{
    "rules": {
      "channel-policy-bounds":  {
        "chan_policy_bounds":  {
          "min_base_msat":  "0",
          "max_base_msat":  "10000",
          "min_rate_ppm":   10,
          "max_rate_ppm":   5000,
          "min_cltv_delta": 60,
          "max_cltv_delta": 120,
          "min_htlc_msat":  "1",
          "max_htlc_msat":  "100000000000"
        }
      },
      "peer-restriction":  {
        "peer_restrict":  {
          "peer_ids":  [
            "abcabc", 
            "defdef"
          ]
        }
      }
    }
  }' \
  --feature-config='{}'

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.
   --feature value            
   --group_id value           The hex encoded group ID of the session group to link this one to.
   --feature-config value     JSON-serialized configuration with the expected format: {"version":0,"option1":"parameter1","option2":"parameter2",...}. An empty configuration is allowed with {} to use the default configuration.
   --feature-rules value      JSON-serialized rule map (see main description for a format example).An empty rule map is allowed with {} to use the default rules.
   --privacy-flags value      String representation of privacy flags to set for the session. Each individual flag will remove privacy from certain aspects of messages transmitted to autopilot. The strongest privacy is on by default and an empty string means full privacy. Some features may not be able to run correctly with full privacy, see the autopilot features call for a list of default required privacy flags. Those minimally required privacy flags are set automatically if nothing is specified here. Combining several features will require the union of all individual feature's privacy flags, which is why it is recommended to register each feature separately for best privacy. Linking to a previous session must preserve privacy flags of the previous session. Example: "ClearPubkeys|ClearAmounts"
   

Messages

litrpc.AddAutopilotSessionRequest

Source: lit-autopilot.proto

Field	gRPC Type	REST Type	REST Placement
label A human readable label to assign to the session.	string	string	body
expiry_timestamp_seconds The unix timestamp at which this session should be revoked.	uint64	string	body
mailbox_server_addr The address of the mailbox server to connect to for this session.	string	string	body
dev_server Set to true if tls should be skipped for when connecting to the mailbox.	bool	boolean	body
features The features that the session should subscribe to. Each feature maps to a FeatureConfig that should be applied to that feature.	FeaturesEntry[]	object	body
session_rules Rules that apply to the entire session. By default, no rules will apply to the entire session.	RulesMap	object	body
no_privacy_mapper Set to true of the session should not make use of the privacy mapper.	bool	boolean	body
linked_group_id Set to the ID of the group to link this session to, if any.	bytes	string	body
privacy_flags The privacy flags used by this session. If set, then privacy_flags_set must be set.	uint64	string	body
privacy_flags_set Indicates whether privacy flags are set.	bool	boolean	body

litrpc.AddAutopilotSessionResponse

Source: lit-autopilot.proto

Field	gRPC Type	REST Type
session Details of the session that was just created.	Session	object

Nested Messages

litrpc.AddAutopilotSessionRequest.FeaturesEntry

Field	gRPC Type	REST Type
key	string	unknown
value	FeatureConfig	unknown

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.FeatureConfig

Field	gRPC Type	REST Type
rules The RulesMap acts as an override map. In other words, by default the rules values recommended by the Auto Pilot server will be used but the RulesMap can be used to override the defaults.	RulesMap	object
config Serialised configuration for the feature.	bytes	string

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

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