SetLiquidityParams

SetLiquidityParams sets a new set of parameters for the daemon's liquidity manager. Note that the full set of parameters must be provided, because this call fully overwrites our existing parameters. [EXPERIMENTAL]: endpoint is subject to change.

Source: looprpc/client.proto

gRPC

rpc SetLiquidityParams (SetLiquidityParamsRequest) returns (SetLiquidityParamsResponse);

REST

HTTP Method	Path
POST	/v1/liquidity/params

Code Samples

gRPC

Javascript

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

const GRPC_HOST = 'localhost:11010'
const MACAROON_PATH = 'LOOP_DIR/regtest/loop.macaroon'
const TLS_PATH = 'LOOP_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('looprpc/client.proto', loaderOptions);
const looprpc = grpc.loadPackageDefinition(packageDefinition).looprpc;
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 looprpc.SwapClient(GRPC_HOST, creds);
let request = {
  parameters: <LiquidityParameters>,
};
client.setLiquidityParams(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the looprpc/client.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import client_pb2 as looprpc, client_pb2_grpc as clientstub

GRPC_HOST = 'localhost:11010'
MACAROON_PATH = 'LOOP_DIR/regtest/loop.macaroon'
TLS_PATH = 'LOOP_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 = clientstub.SwapClientStub(channel)
request = looprpc.SetLiquidityParamsRequest(
  parameters=<LiquidityParameters>,
)
response = stub.SetLiquidityParams(request)
print(response)
# {
# }

REST

Javascript

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

const REST_HOST = 'localhost:8081'
const MACAROON_PATH = 'LOOP_DIR/regtest/loop.macaroon'

let requestBody = {
  parameters: <object>, // <LiquidityParameters> 
};
let options = {
  url: `https://${REST_HOST}/v1/liquidity/params`,
  // 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:
//  {
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8081'
MACAROON_PATH = 'LOOP_DIR/regtest/loop.macaroon'
TLS_PATH = 'LOOP_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/liquidity/params'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'parameters': <LiquidityParameters>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
# }

Shell

$ loop setparams --help

NAME:
   loop setparams - update the parameters set for the liquidity manager

USAGE:
   loop setparams [options]

DESCRIPTION:
   Updates the parameters set for the liquidity manager. Note the parameters are persisted in db to save the trouble of setting them again upon loopd restart. To get the defaultvalues, use `getparams` before any `setparams`.

OPTIONS:
   --sweeplimit int                    the limit placed on our estimated sweep fee in sat/vByte. (default: 0)
   --feepercent float                  the maximum percentage of swap amount to be used across all fee categories (default: 0)
   --maxswapfee float                  the maximum percentage of swap volume we are willing to pay in server fees. (default: 0)
   --maxroutingfee float               the maximum percentage of off-chain payment volume that we are willing to pay in routingfees. (default: 0)
   --maxprepayfee float                the maximum percentage of off-chain prepay volume that we are willing to pay in routing fees. (default: 0)
   --maxprepay uint                    the maximum no-show (prepay) in satoshis that swap suggestions should be limited to. (default: 0)
   --maxminer uint                     the maximum miner fee in satoshis that swap suggestions should be limited to. (default: 0)
   --sweepconf int                     the number of blocks from htlc height that swap suggestion sweeps should target, used to estimate max miner fee. (default: 0)
   --failurebackoff uint               the amount of time, in seconds, that should pass before a channel that previously had a failed swap will be included in suggestions. (default: 0)
   --autoloop                          set to true to enable automated dispatch of swaps, limited to the budget set by autobudget. (default: false)
   --destaddr string                   custom address to be used as destination for autoloop loop out, set to "default" in order to revert to default behavior.
   --account string                    the name of the account to generate a new address from. You can list the names of valid accounts in your backing lnd instance with "lncli wallet accounts list".
   --account_addr_type string          the address type of the extended public key specified in account. Currently only pay-to-taproot-pubkey(p2tr) is supported (default: "p2tr")
   --autobudget uint                   the maximum amount of fees in satoshis that automatically dispatched loop out swaps may spend. (default: 0)
   --autobudgetrefreshperiod duration  the time period over which the automated loop budget is refreshed. (default: 0s)
   --autoinflight uint                 the maximum number of automatically dispatched swaps that we allow to be in flight. (default: 0)
   --minamt uint                       the minimum amount in satoshis that the autoloop client will dispatch per-swap. (default: 0)
   --maxamt uint                       the maximum amount in satoshis that the autoloop client will dispatch per-swap. (default: 0)
   --htlc_conf int                     the confirmation target for loop in on-chain htlcs. (default: 0)
   --easyautoloop                      set to true to enable easy autoloop, which will automatically dispatch swaps in order to meet the target local balance. (default: false)
   --localbalancesat uint              the target size of total local balance in satoshis, used by easy autoloop. (default: 0)
   --asset_easyautoloop                set to true to enable asset easy autoloop, which will automatically dispatch asset swaps in order to meet the target local balance. (default: false)
   --asset_id string                   If set to a valid asset ID, the easyautoloop and localbalancesat flags will be set for the specified asset.
   --asset_localbalance uint           the target size of total local balance in asset units, used by asset easy autoloop. (default: 0)
   --fast                              if set new swaps are expected to be published immediately, paying a potentially higher fee. If not set the swap server might choose to wait up to 30 minutes before publishing swap HTLCs on-chain, to save on chain fees. Not setting this flag therefore might result in a lower swap fees (default: false)
   --help, -h                          show help

GLOBAL OPTIONS:
   --rpcserver string           loopd daemon address host:port (default: "localhost:11010") [$LOOPCLI_RPCSERVER]
   --network string, -n string  the network loop is running on e.g. mainnet, testnet, etc. (default: "mainnet") [$LOOPCLI_NETWORK]
   --loopdir string             path to loop's base directory (default: "/home/runner/.loop") [$LOOPCLI_LOOPDIR]
   --tlscertpath string         path to loop's TLS certificate (default: "/home/runner/.loop/mainnet/tls.cert") [$LOOPCLI_TLSCERTPATH]
   --macaroonpath string        path to macaroon file (default: "/home/runner/.loop/mainnet/loop.macaroon") [$LOOPCLI_MACAROONPATH]

Messages

looprpc.SetLiquidityParamsRequest

Source: looprpc/client.proto

Field	gRPC Type	REST Type	REST Placement
parameters Parameters is the desired new set of parameters for the liquidity management subsystem. Note that the current set of parameters will be completely overwritten by the parameters provided (if they are valid), so the full set of parameters should be provided for each call.	LiquidityParameters	object	body

looprpc.SetLiquidityParamsResponse

Source: looprpc/client.proto

note

This response has no parameters.

Nested Messages

looprpc.EasyAssetAutoloopParams

Field	gRPC Type	REST Type
enabled Set to true to enable easy autoloop for this asset. If set the client will automatically dispatch swaps in order to meet the configured local balance target size. Currently only loop out is supported, meaning that easy autoloop can only reduce the funds that are held as balance in channels.	bool	boolean
local_target_asset_amt The local balance target size, expressed in the asset's base units. This is used by easy autoloop to determine how much liquidity should be maintained in channels.	uint64	string

looprpc.LiquidityParameters

Field	gRPC Type	REST Type
rules A set of liquidity rules that describe the desired liquidity balance.	LiquidityRule[]	array
fee_ppm The parts per million of swap amount that is allowed to be allocated to swap fees. This value is applied across swap categories and may not be set in conjunction with sweep fee rate, swap fee ppm, routing fee ppm, prepay routing, max prepay and max miner fee.	uint64	string
sweep_fee_rate_sat_per_vbyte The limit we place on our estimated sweep cost for a swap in sat/vByte. If the estimated fee for our sweep transaction within the specified confirmation target is above this value, we will not suggest any swaps.	uint64	string
max_swap_fee_ppm The maximum fee paid to the server for facilitating the swap, expressed as parts per million of the swap volume.	uint64	string
max_routing_fee_ppm The maximum fee paid to route the swap invoice off chain, expressed as parts per million of the volume being routed.	uint64	string
max_prepay_routing_fee_ppm The maximum fee paid to route the prepay invoice off chain, expressed as parts per million of the volume being routed.	uint64	string
max_prepay_sat The maximum no-show penalty in satoshis paid for a swap.	uint64	string
max_miner_fee_sat The maximum miner fee we will pay to sweep the swap on chain. Note that we will not suggest a swap if the estimate is above the sweep limit set by these parameters, and we use the current fee estimate to sweep on chain so this value is only a cap placed on the amount we spend on fees in the case where the swap needs to be claimed on chain, but fees have suddenly spiked.	uint64	string
sweep_conf_target The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.	int32	integer
failure_backoff_sec The amount of time we require pass since a channel was part of a failed swap due to off chain payment failure until it will be considered for swap suggestions again, expressed in seconds.	uint64	string
autoloop Set to true to enable automatic dispatch of swaps. All swaps will be limited to the fee categories set by these parameters, and total expenditure will be limited to the autoloop budget.	bool	boolean
autoloop_budget_sat The total budget for automatically dispatched swaps since the budget start time, expressed in satoshis.	uint64	string
autoloop_budget_start_secdeprecated Deprecated, use autoloop_budget_refresh_period_sec. The start time for autoloop budget, expressed as a unix timestamp in seconds. If this value is 0, the budget will be applied for all automatically dispatched swaps. Swaps that were completed before this date will not be included in budget calculations.	uint64	string
auto_max_in_flight The maximum number of automatically dispatched swaps that we allow to be in flight at any point in time.	uint64	string
min_swap_amount The minimum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.	uint64	string
max_swap_amount The maximum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.	uint64	string
htlc_conf_target The confirmation target for loop in on-chain htlcs.	int32	integer
autoloop_dest_address The destination address to use for autoloop loop outs. Set to "default" in order to revert to default behavior.	string	string
autoloop_budget_refresh_period_sec The period over which the autoloop budget is refreshed, expressed in seconds.	uint64	string
autoloop_budget_last_refresh The time at which the autoloop budget was last refreshed, expressed as a UNIX timestamp in seconds.	uint64	string
easy_autoloop Set to true to enable easy autoloop. If set, all channel/peer rules will be overridden and the client will automatically dispatch swaps in order to meet the configured local balance target size. Currently only loop out is supported, meaning that easy autoloop can only reduce the funds that are held as balance in channels.	bool	boolean
easy_autoloop_local_target_sat The local balance target size, expressed in satoshis. This is used by easy autoloop to determine how much liquidity should be maintained in channels.	uint64	string
account An alternative destination address source for the swap. This field represents the name of the account in the backing lnd instance. Refer to lnd's wallet import functions for reference.	string	string
account_addr_type The address type of the account specified in the account field.	AddressType	string
easy_asset_params A map of asset parameters to use for swaps. The key is the asset id and the value is the parameters to use for swaps in that asset.	EasyAssetParamsEntry[]	object
fast_swap_publication Set to true to enable fast swap publication. If set, the server will publish the HTLC immediately after receiving the swap request. This setting has direct implications on the swap fees, as fast swaps may not be able to be batched with other swaps.	bool	boolean

looprpc.LiquidityParameters.EasyAssetParamsEntry

Field	gRPC Type	REST Type
key	string	unknown
value	EasyAssetAutoloopParams	unknown

looprpc.LiquidityRule

Field	gRPC Type	REST Type
channel_id The short channel ID of the channel that this rule should be applied to. This field may not be set when the pubkey field is set.	uint64	string
swap_type The type of swap that will be dispatched for this rule.	SwapType	string
pubkey The public key of the peer that this rule should be applied to. This field may not be set when the channel id field is set.	bytes	string
type Type indicates the type of rule that this message rule represents. Setting this value will determine which fields are used in the message. The comments on each field in this message will be prefixed with the LiquidityRuleType they belong to.	LiquidityRuleType	string
incoming_threshold THRESHOLD: The percentage of total capacity that incoming capacity should not drop beneath.	uint32	integer
outgoing_threshold THRESHOLD: The percentage of total capacity that outgoing capacity should not drop beneath.	uint32	integer

Enums

looprpc.AddressType

Name	Number
ADDRESS_TYPE_UNKNOWN	0
TAPROOT_PUBKEY	1

looprpc.LiquidityRuleType

Name	Number
UNKNOWN	0
THRESHOLD	1

looprpc.SwapType

Name	Number
LOOP_OUT LOOP_OUT indicates an loop out swap (off-chain to on-chain)	0
LOOP_IN LOOP_IN indicates a loop in swap (on-chain to off-chain)	1