SwapInfo

SwapInfo returns all known details about a single swap.

Source: looprpc/client.proto

gRPC

rpc SwapInfo (SwapInfoRequest) returns (SwapStatus);

REST

HTTP Method	Path
GET	/v1/loop/swap/{id}

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 = {
  id: <bytes>,
};
client.swapInfo(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "amt": <int64>,
//    "id": <string>,
//    "id_bytes": <bytes>,
//    "type": <SwapType>,
//    "state": <SwapState>,
//    "failure_reason": <FailureReason>,
//    "initiation_time": <int64>,
//    "last_update_time": <int64>,
//    "htlc_address": <string>,
//    "htlc_address_p2wsh": <string>,
//    "htlc_address_p2tr": <string>,
//    "cost_server": <int64>,
//    "cost_onchain": <int64>,
//    "cost_offchain": <int64>,
//    "last_hop": <bytes>,
//    "outgoing_chan_set": <uint64>,
//    "label": <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.SwapInfoRequest(
  id=<bytes>,
)
response = stub.SwapInfo(request)
print(response)
# {
#    "amt": <int64>,
#    "id": <string>,
#    "id_bytes": <bytes>,
#    "type": <SwapType>,
#    "state": <SwapState>,
#    "failure_reason": <FailureReason>,
#    "initiation_time": <int64>,
#    "last_update_time": <int64>,
#    "htlc_address": <string>,
#    "htlc_address_p2wsh": <string>,
#    "htlc_address_p2tr": <string>,
#    "cost_server": <int64>,
#    "cost_onchain": <int64>,
#    "cost_offchain": <int64>,
#    "last_hop": <bytes>,
#    "outgoing_chan_set": <uint64>,
#    "label": <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 options = {
  url: `https://${REST_HOST}/v1/loop/swap/{id}`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "amt": <string>, // <int64> 
//    "id": <string>, // <string> 
//    "id_bytes": <string>, // <bytes> 
//    "type": <string>, // <SwapType> 
//    "state": <string>, // <SwapState> 
//    "failure_reason": <string>, // <FailureReason> 
//    "initiation_time": <string>, // <int64> 
//    "last_update_time": <string>, // <int64> 
//    "htlc_address": <string>, // <string> 
//    "htlc_address_p2wsh": <string>, // <string> 
//    "htlc_address_p2tr": <string>, // <string> 
//    "cost_server": <string>, // <int64> 
//    "cost_onchain": <string>, // <int64> 
//    "cost_offchain": <string>, // <int64> 
//    "last_hop": <string>, // <bytes> 
//    "outgoing_chan_set": <array>, // <uint64> 
//    "label": <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/swap/{id}'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "amt": <int64>,
#    "id": <string>,
#    "id_bytes": <bytes>,
#    "type": <SwapType>,
#    "state": <SwapState>,
#    "failure_reason": <FailureReason>,
#    "initiation_time": <int64>,
#    "last_update_time": <int64>,
#    "htlc_address": <string>,
#    "htlc_address_p2wsh": <string>,
#    "htlc_address_p2tr": <string>,
#    "cost_server": <int64>,
#    "cost_onchain": <int64>,
#    "cost_offchain": <int64>,
#    "last_hop": <bytes>,
#    "outgoing_chan_set": <uint64>,
#    "label": <string>,
# }

Shell

$ loop swapinfo --help

NAME:
   loop swapinfo - show the status of a swap

USAGE:
   loop swapinfo [command options] id

DESCRIPTION:
   Allows the user to get the status of a single swap currently stored in the database

OPTIONS:
   --id value  the ID of the swap (default: 0)
   

Messages

looprpc.SwapInfoRequest

Source: looprpc/client.proto

Field	gRPC Type	REST Type	REST Placement
id The swap identifier which currently is the hash that locks the HTLCs. When using REST, this field must be encoded as URL safe base64.	bytes	string	path

looprpc.SwapStatus

Source: looprpc/client.proto

Field	gRPC Type	REST Type
amt Requested swap amount in sat. This does not include the swap and miner fee.	int64	string
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
type The type of the swap.	SwapType	string
state State the swap is currently in, see State enum.	SwapState	string
failure_reason A failure reason for the swap, only set if the swap has failed.	FailureReason	string
initiation_time Initiation time of the swap.	int64	string
last_update_time Initiation time of the swap.	int64	string
htlc_addressdeprecated DEPRECATED: This field stores the address of the onchain htlc. - 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 HTLC address (native segwit), used in loop-in and loop-out swaps.	string	string
htlc_address_p2tr The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.	string	string
cost_server Swap server cost	int64	string
cost_onchain On-chain transaction cost	int64	string
cost_offchain Off-chain routing fees	int64	string
last_hop Optional last hop if provided in the loop in request.	bytes	string
outgoing_chan_set Optional outgoing channel set if provided in the loop out request.	uint64[]	array
label An optional label given to the swap on creation.	string	string

Enums

looprpc.FailureReason

Name	Number
FAILURE_REASON_NONE FAILURE_REASON_NONE is set when the swap did not fail, it is either in progress or succeeded.	0
FAILURE_REASON_OFFCHAIN FAILURE_REASON_OFFCHAIN indicates that a loop out failed because it wasn't possible to find a route for one or both off chain payments that met the fee and timelock limits required.	1
FAILURE_REASON_TIMEOUT FAILURE_REASON_TIMEOUT indicates that the swap failed because on chain htlc did not confirm before its expiry, or it confirmed too late for us to reveal our preimage and claim.	2
FAILURE_REASON_SWEEP_TIMEOUT FAILURE_REASON_SWEEP_TIMEOUT indicates that a loop out permanently failed because the on chain htlc wasn't swept before the server revoked the htlc.	3
FAILURE_REASON_INSUFFICIENT_VALUE FAILURE_REASON_INSUFFICIENT_VALUE indicates that a loop out has failed because the on chain htlc had a lower value than requested.	4
FAILURE_REASON_TEMPORARY FAILURE_REASON_TEMPORARY indicates that a swap cannot continue due to an internal error. Manual intervention such as a restart is required.	5
FAILURE_REASON_INCORRECT_AMOUNT FAILURE_REASON_INCORRECT_AMOUNT indicates that a loop in permanently failed because the amount extended by an external loop in htlc is insufficient.	6
FAILURE_REASON_ABANDONED FAILURE_REASON_ABANDONED indicates that a swap permanently failed because the client manually abandoned the swap.	7
FAILURE_REASON_INSUFFICIENT_CONFIRMED_BALANCE FAILURE_REASON_INSUFFICIENT_CONFIRMED_BALANCE indicates that a swap wasn't published due to insufficient confirmed balance.	8
FAILURE_REASON_INCORRECT_HTLC_AMT_SWEPT FAILURE_REASON_INCORRECT_HTLC_AMT_SWEPT indicates that a swap wasn't published due to insufficient confirmed balance.	9

looprpc.SwapState

Name	Number
INITIATED INITIATED is the initial state of a swap. At that point, the initiation call to the server has been made and the payment process has been started for the swap and prepayment invoices.	0
PREIMAGE_REVEALED PREIMAGE_REVEALED is reached when the sweep tx publication is first attempted. From that point on, we should consider the preimage to no longer be secret and we need to do all we can to get the sweep confirmed. This state will mostly coalesce with StateHtlcConfirmed, except in the case where we wait for fees to come down before we sweep.	1
HTLC_PUBLISHED HTLC_PUBLISHED is reached when the htlc tx has been published in a loop in swap.	2
SUCCESS SUCCESS is the final swap state that is reached when the sweep tx has the required confirmation depth.	3
FAILED FAILED is the final swap state for a failed swap with or without loss of the swap amount.	4
INVOICE_SETTLED INVOICE_SETTLED is reached when the swap invoice in a loop in swap has been paid, but we are still waiting for the htlc spend to confirm.	5

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