LoopIn

LoopIn initiates a loop in swap with the given parameters. The call returns after the swap has been set up with the swap server. From that point onwards, progress can be tracked via the SwapStatus stream that is returned from Monitor().

Source: looprpc/client.proto

gRPC

rpc LoopIn (LoopInRequest) returns (SwapResponse);

REST

HTTP Method	Path
POST	/v1/loop/in

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 = {
  amt: <int64>,
  max_swap_fee: <int64>,
  max_miner_fee: <int64>,
  last_hop: <bytes>,
  external_htlc: <bool>,
  htlc_conf_target: <int32>,
  label: <string>,
  initiator: <string>,
  route_hints: <RouteHint>,
  private: <bool>,
};
client.loopIn(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "id": <string>,
//    "id_bytes": <bytes>,
//    "htlc_address": <string>,
//    "htlc_address_p2wsh": <string>,
//    "htlc_address_p2tr": <string>,
//    "server_message": <string>,
//  }

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.LoopInRequest(
  amt=<int64>,
  max_swap_fee=<int64>,
  max_miner_fee=<int64>,
  last_hop=<bytes>,
  external_htlc=<bool>,
  htlc_conf_target=<int32>,
  label=<string>,
  initiator=<string>,
  route_hints=<RouteHint>,
  private=<bool>,
)
response = stub.LoopIn(request)
print(response)
# {
#    "id": <string>,
#    "id_bytes": <bytes>,
#    "htlc_address": <string>,
#    "htlc_address_p2wsh": <string>,
#    "htlc_address_p2tr": <string>,
#    "server_message": <string>,
# }

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 = {
  amt: <string>, // <int64> 
  max_swap_fee: <string>, // <int64> 
  max_miner_fee: <string>, // <int64> 
  last_hop: <string>, // <bytes> (base64 encoded)
  external_htlc: <boolean>, // <bool> 
  htlc_conf_target: <integer>, // <int32> 
  label: <string>, // <string> 
  initiator: <string>, // <string> 
  route_hints: <array>, // <RouteHint> 
  private: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/loop/in`,
  // 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:
//  {
//    "id": <string>, // <string> 
//    "id_bytes": <string>, // <bytes> 
//    "htlc_address": <string>, // <string> 
//    "htlc_address_p2wsh": <string>, // <string> 
//    "htlc_address_p2tr": <string>, // <string> 
//    "server_message": <string>, // <string> 
//  }

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/loop/in'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'amt': <int64>,
  'max_swap_fee': <int64>,
  'max_miner_fee': <int64>,
  'last_hop': base64.b64encode(<bytes>),
  'external_htlc': <bool>,
  'htlc_conf_target': <int32>,
  'label': <string>,
  'initiator': <string>,
  'route_hints': <RouteHint>,
  'private': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "id": <string>,
#    "id_bytes": <bytes>,
#    "htlc_address": <string>,
#    "htlc_address_p2wsh": <string>,
#    "htlc_address_p2tr": <string>,
#    "server_message": <string>,
# }

Shell

$ loop in --help

NAME:
   loop in - perform an on-chain to off-chain swap (loop in)

USAGE:
   loop in [options] amt

DESCRIPTION:
   
       Send the amount in satoshis specified by the amt argument 
       off-chain.
       
       By default the swap client will create and broadcast the 
       on-chain htlc. The fee priority of this transaction can 
       optionally be set using the conf_target flag. 

       The external flag can be set to publish the on chain htlc 
       independently. Note that this flag cannot be set with the 
       conf_target flag.
       

OPTIONS:
   --amt uint                                     the amount in satoshis to loop in. To check for the minimum and maximum amounts to loop in please consult "loop terms" (default: 0)
   --external                                     expect htlc to be published externally (default: false)
   --conf_target uint                             the target number of blocks the on-chain htlc broadcast by the swap client should confirm within (default: 0)
   --last_hop string                              the pubkey of the last hop to use for this swap
   --label string                                 an optional label for this swap,limited to 500 characters. The label may not start with our reserved prefix: [reserved].
   --force                                        Assumes yes during confirmation. Using this option will result in an immediate swap (default: false)
   --verbose, -v                                  show expanded details (default: false)
   --route_hints string [ --route_hints string ]  route hints that can each be individually used to assist in reaching the invoice's destination
   --private                                      generates and passes routehints. Should be used if the connected node is only reachable via private channels (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.LoopInRequest

Source: looprpc/client.proto

Field	gRPC Type	REST Type	REST Placement
amt Requested swap amount in sat. This does not include the swap and miner fee.	int64	string	body
max_swap_fee Maximum we are willing to pay the server for the swap. This value is not disclosed in the swap initiation call, but if the server asks for a higher fee, we abort the swap. Typically this value is taken from the response of the GetQuote call.	int64	string	body
max_miner_fee Maximum in on-chain fees that we are willing to spend. If we want to publish the on-chain htlc and the fee estimate turns out higher than this value, we cancel the swap. max_miner_fee is typically taken from the response of the GetQuote call.	int64	string	body
last_hop The last hop to use for the loop in swap. If empty, the last hop is selected based on the lowest routing fee for the swap payment from the server.	bytes	string	body
external_htlc If external_htlc is true, we expect the htlc to be published by an external actor.	bool	boolean	body
htlc_conf_target The number of blocks that the on chain htlc should confirm within.	int32	integer	body
label An optional label for this swap. This field is limited to 500 characters and may not be one of the reserved values in loop/labels Reserved list.	string	string	body
initiator An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of loop. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (loopd, LiT) and the method used for triggering the swap (loop CLI, autolooper, LiT UI, other 3rd party UI).	string	string	body
route_hints Optional route hints to reach the destination through private channels.	RouteHint[]	array	body
private Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.	bool	boolean	body

looprpc.SwapResponse

Source: looprpc/client.proto

Field	gRPC Type	REST Type
iddeprecated Swap identifier to track status in the update stream that is returned from the Start() call. Currently this is the hash that locks the htlcs. DEPRECATED: To make the API more consistent, this field is deprecated in favor of id_bytes and will be removed in a future release.	string	string
id_bytes Swap identifier to track status in the update stream that is returned from the Start() call. Currently this is the hash that locks the htlcs.	bytes	string
htlc_addressdeprecated DEPRECATED. This field stores the address of the onchain htlc, but depending on the request, the semantics are different. - For internal loop-in htlc_address contains the address of the native segwit (P2WSH) htlc. / - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.	string	string
htlc_address_p2wsh The native segwit address of the on-chain htlc. Used for both loop-in and loop-out.	string	string
htlc_address_p2tr The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.	string	string
server_message A human-readable message received from the loop server.	string	string