RegisterSidecar

RegisterSidecarRequest is step 2/4 of the sidecar negotiation between the provider (the trader submitting the bid order) and the recipient (the trader receiving the sidecar channel). This step must be run by the recipient. The result is a sidecar ticket with the recipient's node information and channel funding multisig pubkey filled in. The ticket returned by this call will have the state "registered".

Source: poolrpc/trader.proto

gRPC

rpc RegisterSidecar (RegisterSidecarRequest) returns (SidecarTicket);

REST

HTTP Method	Path
POST	/v1/pool/sidecar/register

Code Samples

gRPC

Javascript

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

const GRPC_HOST = 'localhost:12010'
const MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
const TLS_PATH = 'POOL_DIR/regtest/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
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 poolrpc.Trader(GRPC_HOST, creds);
let request = {
  ticket: <string>,
  auto_negotiate: <bool>,
};
client.registerSidecar(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "ticket": <string>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the poolrpc/trader.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub

GRPC_HOST = 'localhost:12010'
MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
TLS_PATH = 'POOL_DIR/regtest/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 = traderstub.TraderStub(channel)
request = poolrpc.RegisterSidecarRequest(
  ticket=<string>,
  auto_negotiate=<bool>,
)
response = stub.RegisterSidecar(request)
print(response)
# {
#    "ticket": <string>,
# }

grpcurl

# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightninglabs/pool
GRPC_HOST=localhost:12010
POOL_DIR=~/.pool
POOL_SOURCE=path/to/pool
NETWORK=mainnet
MACAROON_PATH="$POOL_DIR/$NETWORK/pool.macaroon"
TLS_PATH="$POOL_DIR/$NETWORK/tls.cert"

grpcurl \
    -import-path $POOL_SOURCE \
    -proto poolrpc/trader.proto \
    -cacert $TLS_PATH \
    -H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "ticket": <string>, "auto_negotiate": <bool> }' \
    $GRPC_HOST \
    poolrpc.Trader/RegisterSidecar

REST

Javascript

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

const REST_HOST = 'localhost:8281'
const MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'

let requestBody = {
  ticket: <string>, // <string> 
  auto_negotiate: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/pool/sidecar/register`,
  // 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:
//  {
//    "ticket": <string>, // <string> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8281'
MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
TLS_PATH = 'POOL_DIR/regtest/tls.cert'

url = f'https://{REST_HOST}/v1/pool/sidecar/register'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'ticket': <string>,
  'auto_negotiate': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "ticket": <string>,
# }

curl

REST_HOST=localhost:8281
POOL_DIR=~/.pool
NETWORK=mainnet
MACAROON_PATH="$POOL_DIR/$NETWORK/pool.macaroon"
TLS_PATH="$POOL_DIR/$NETWORK/tls.cert"

curl -X POST \
    --cacert $TLS_PATH \
    -H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "ticket": <string>, "auto_negotiate": <bool> }' \
    https://$REST_HOST/v1/pool/sidecar/register

pool

$ pool sidecar register --help

NAME:
   pool sidecar register - register an incoming sidecar channel and add node info to ticket

USAGE:
   pool sidecar register ticket

DESCRIPTION:
   
  Registers a sidecar ticket for an incoming sidecar channel with the node
  and adds its recipient information to it, resulting in an updated ticket
  that needs to be handed back to the provider.

Messages

poolrpc.RegisterSidecarRequest

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type	REST Placement
ticket The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered".	string	string	body
auto_negotiate If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down.	bool	boolean	body

poolrpc.SidecarTicket

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type
ticket The complete sidecar ticket in its string encoded form which is base58 encoded, has a human readable prefix ('sidecar...') and a checksum built in. The string encoded version will only be used on the trader side of the API. All requests to the auctioneer expect the ticket to be in its raw, tlv encoded byte form.	string	string