InitAccount

InitAccount creates a new account with the requested size and expiration, funding it from the wallet of the connected lnd node.

Source: poolrpc/trader.proto

gRPC

rpc InitAccount (InitAccountRequest) returns (Account);

REST

HTTP Method	Path
POST	/v1/pool/accounts

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/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 = {
  account_value: <uint64>,
  absolute_height: <uint32>,
  relative_height: <uint32>,
  conf_target: <uint32>,
  fee_rate_sat_per_kw: <uint64>,
  initiator: <string>,
  version: <AccountVersion>,
};
client.initAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "trader_key": <bytes>,
//    "outpoint": <OutPoint>,
//    "value": <uint64>,
//    "available_balance": <uint64>,
//    "expiration_height": <uint32>,
//    "state": <AccountState>,
//    "latest_txid": <bytes>,
//    "version": <AccountVersion>,
//  }

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/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.InitAccountRequest(
  account_value=<uint64>,
  absolute_height=<uint32>,
  relative_height=<uint32>,
  conf_target=<uint32>,
  fee_rate_sat_per_kw=<uint64>,
  initiator=<string>,
  version=<AccountVersion>,
)
response = stub.InitAccount(request)
print(response)
# {
#    "trader_key": <bytes>,
#    "outpoint": <OutPoint>,
#    "value": <uint64>,
#    "available_balance": <uint64>,
#    "expiration_height": <uint32>,
#    "state": <AccountState>,
#    "latest_txid": <bytes>,
#    "version": <AccountVersion>,
# }

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 = {
  account_value: <string>, // <uint64> 
  absolute_height: <integer>, // <uint32> 
  relative_height: <integer>, // <uint32> 
  conf_target: <integer>, // <uint32> 
  fee_rate_sat_per_kw: <string>, // <uint64> 
  initiator: <string>, // <string> 
  version: <string>, // <AccountVersion> 
};
let options = {
  url: `https://${REST_HOST}/v1/pool/accounts`,
  // 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:
//  {
//    "trader_key": <string>, // <bytes> 
//    "outpoint": <object>, // <OutPoint> 
//    "value": <string>, // <uint64> 
//    "available_balance": <string>, // <uint64> 
//    "expiration_height": <integer>, // <uint32> 
//    "state": <string>, // <AccountState> 
//    "latest_txid": <string>, // <bytes> 
//    "version": <string>, // <AccountVersion> 
//  }

Python

import base64, codecs, json, requests

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

url = f'https://{REST_HOST}/v1/pool/accounts'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'account_value': <uint64>,
  'absolute_height': <uint32>,
  'relative_height': <uint32>,
  'conf_target': <uint32>,
  'fee_rate_sat_per_kw': <uint64>,
  'initiator': <string>,
  'version': <AccountVersion>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "trader_key": <bytes>,
#    "outpoint": <OutPoint>,
#    "value": <uint64>,
#    "available_balance": <uint64>,
#    "expiration_height": <uint32>,
#    "state": <AccountState>,
#    "latest_txid": <bytes>,
#    "version": <AccountVersion>,
# }

Shell

$ pool accounts new --help

NAME:
   pool accounts new - create an account

USAGE:
   pool accounts new [command options] amt [--expiry_height | --expiry_blocks]

DESCRIPTION:
   
    Send the amount in satoshis specified by the amt argument to a
    new account.

OPTIONS:
   --amt value            the amount in satoshis to create account for (default: 0)
   --expiry_height value  the new block height which this account should expire at (default: 0)
   --expiry_blocks value  the relative height (from the current chain height) that the account should expire at (default of 30 days equivalent in blocks) (default: 4320)
   --conf_target value    the target number of blocks the on-chain account funding transaction should confirm within (default: 6)
   --sat_per_vbyte value  the fee rate expressed in sat/vbyte that should be used for the account creation transaction (default: 0)
   --force                skip account fee confirmation
   --version value        the account version to use; version 0 means auto-decide dependent on lnd version; version 1 is a p2wsh account, version 2 is a p2tr account, version 3 is a p2tr account with MuSig2 v1.0.0-rc2 support; version 2 requires lnd 0.15 or later, version 3 requires lnd 0.16 or later (default: 0)
   

Messages

poolrpc.InitAccountRequest

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type	REST Placement
account_value	uint64	string	body
absolute_height	uint32	integer	body
relative_height	uint32	integer	body
conf_target The target number of blocks that the transaction should be confirmed in.	uint32	integer	body
fee_rate_sat_per_kw The fee rate, in satoshis per kw, to use for the initial funding transaction.	uint64	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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI).	string	string	body
version The version of account to create.	AccountVersion	string	body

poolrpc.Account

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type
trader_key The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer.	bytes	string
outpoint The current outpoint associated with the account. This will change every time the account has been updated.	OutPoint	object
value The current total amount of satoshis in the account.	uint64	string
available_balance The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders.	uint64	string
expiration_height The height at which the account will expire.	uint32	integer
state The current state of the account.	AccountState	string
latest_txid The hash of the account's latest transaction.	bytes	string
version The current version of the account.	AccountVersion	string

Nested Messages

poolrpc.OutPoint

Field	gRPC Type	REST Type
txid Raw bytes representing the transaction id.	bytes	string
output_index The index of the output on the transaction.	uint32	integer

Enums

poolrpc.AccountState

Name	Number
PENDING_OPEN The state of an account when it is pending its confirmation on-chain.	0
PENDING_UPDATE The state of an account when it has undergone an update on-chain either as part of a matched order or a trader modification and it is pending its confirmation on-chain.	1
OPEN The state of an account once it has confirmed on-chain.	2
EXPIRED The state of an account once its expiration has been reached and its closing transaction has confirmed.	3
PENDING_CLOSED The state of an account when we're waiting for the closing transaction of an account to confirm that required cooperation with the auctioneer.	4
CLOSED The state of an account once its closing transaction has confirmed.	5
RECOVERY_FAILED The state of an account that indicates that the account was attempted to be recovered but failed because the opening transaction wasn't found by lnd. This could be because it was never published or it never confirmed. Then the funds are SAFU and the account can be considered to never have been opened in the first place.	6
PENDING_BATCH The account has recently participated in a batch and is not yet confirmed.	7

poolrpc.AccountVersion

Name	Number
ACCOUNT_VERSION_LND_DEPENDENT Let the version of lnd decide. If a version of lnd >= 0.15.0-beta is detected then a Taproot account is created. For earlier versions a legacy account is created. If a version of lnd >= 0.16.0-beta is detected, then a Taproot v2 account is created.	0
ACCOUNT_VERSION_LEGACY A legacy SegWit v0 p2wsh account with a single script.	1
ACCOUNT_VERSION_TAPROOT A Taproot enabled account with MuSig2 combined internal key and the expiry script as a single tap script leaf.	2
ACCOUNT_VERSION_TAPROOT_V2 A Taproot enabled account with MuSig2 combined internal key and the expiry script as a single tap script leaf. This version uses the MuSig2 v1.0.0-rc2 protocol for creating the combined internal key. This can only be selected when the connected lnd version is >= 0.16.0-beta.	3