WithdrawAccount

WithdrawAccount splits off parts of the account balance into the specified outputs while recreating the account with a reduced balance.

Source: poolrpc/trader.proto

gRPC

rpc WithdrawAccount (WithdrawAccountRequest) returns (WithdrawAccountResponse);

REST

HTTP Method	Path
POST	/v1/pool/accounts/withdraw

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 = {
  trader_key: <bytes>,
  outputs: <Output>,
  fee_rate_sat_per_kw: <uint64>,
  absolute_expiry: <uint32>,
  relative_expiry: <uint32>,
  new_version: <AccountVersion>,
};
client.withdrawAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "account": <Account>,
//    "withdraw_txid": <bytes>,
//  }

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.WithdrawAccountRequest(
  trader_key=<bytes>,
  outputs=<Output>,
  fee_rate_sat_per_kw=<uint64>,
  absolute_expiry=<uint32>,
  relative_expiry=<uint32>,
  new_version=<AccountVersion>,
)
response = stub.WithdrawAccount(request)
print(response)
# {
#    "account": <Account>,
#    "withdraw_txid": <bytes>,
# }

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 = {
  trader_key: <string>, // <bytes> (base64 encoded)
  outputs: <array>, // <Output> 
  fee_rate_sat_per_kw: <string>, // <uint64> 
  absolute_expiry: <integer>, // <uint32> 
  relative_expiry: <integer>, // <uint32> 
  new_version: <string>, // <AccountVersion> 
};
let options = {
  url: `https://${REST_HOST}/v1/pool/accounts/withdraw`,
  // 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:
//  {
//    "account": <object>, // <Account> 
//    "withdraw_txid": <string>, // <bytes> 
//  }

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/withdraw'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'trader_key': base64.b64encode(<bytes>),
  'outputs': <Output>,
  'fee_rate_sat_per_kw': <uint64>,
  'absolute_expiry': <uint32>,
  'relative_expiry': <uint32>,
  'new_version': <AccountVersion>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "account": <Account>,
#    "withdraw_txid": <bytes>,
# }

Shell

$ pool accounts withdraw --help

NAME:
   pool accounts withdraw - withdraw funds from an existing account

USAGE:
   pool accounts withdraw [command options] trader_key amt addr sat_per_vbyte

DESCRIPTION:
   
  Withdraw funds from an existing account to a supported address.
  

OPTIONS:
   --trader_key value     the hex-encoded trader key of the account to withdraw funds from
   --addr value           the address the withdrawn funds should go to
   --amt value            the amount that will be sent to the address and withdrawn from the account (default: 0)
   --sat_per_vbyte value  the fee rate expressed in sat/vbyte that should be used for the withdrawal (default: 0)
   --expiry_height value  the new block height which this account should expire at (default: 0)
   --expiry_blocks value  the new relative height (from the current chain height) that the account should expire at (default: 0)
   --new_version value    the new account version to use; version 0 means auto-decide dependent on lnd version; version 1 is a p2wsh account while version 2 is a p2tr account; version 2 requires lnd 0.15 or later (default: 0)
   

Messages

poolrpc.WithdrawAccountRequest

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type	REST Placement
trader_key The trader key associated with the account that funds will be withdrawed from.	bytes	string	body
outputs The outputs we'll withdraw funds from the account into.	Output[]	array	body
fee_rate_sat_per_kw The fee rate, in satoshis per kw, to use for the withdrawal transaction.	uint64	string	body
absolute_expiry The new absolute expiration height of the account.	uint32	integer	body
relative_expiry The new relative expiration height of the account.	uint32	integer	body
new_version The new version of the account. If this is set and is a valid version greater than the account's current version, then the account is upgraded to that version during the withdrawal.	AccountVersion	string	body

poolrpc.WithdrawAccountResponse

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type
account The state of the account after processing the withdrawal.	Account	object
withdraw_txid The transaction used to withdraw funds from the account.	bytes	string

Nested Messages

poolrpc.Account

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

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

poolrpc.Output

Field	gRPC Type	REST Type
value_sat The value, in satoshis, of the output.	uint64	string
address The address corresponding to the output.	string	string

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