RenewAccount

RenewAccount renews the expiration of an account.

Source: poolrpc/trader.proto

gRPC

rpc RenewAccount (RenewAccountRequest) returns (RenewAccountResponse);

REST

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

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_key: <bytes>,
  absolute_expiry: <uint32>,
  relative_expiry: <uint32>,
  fee_rate_sat_per_kw: <uint64>,
  new_version: <AccountVersion>,
};
client.renewAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "account": <Account>,
//    "renewal_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.RenewAccountRequest(
  account_key=<bytes>,
  absolute_expiry=<uint32>,
  relative_expiry=<uint32>,
  fee_rate_sat_per_kw=<uint64>,
  new_version=<AccountVersion>,
)
response = stub.RenewAccount(request)
print(response)
# {
#    "account": <Account>,
#    "renewal_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 = {
  account_key: <string>, // <bytes> (base64 encoded)
  absolute_expiry: <integer>, // <uint32> 
  relative_expiry: <integer>, // <uint32> 
  fee_rate_sat_per_kw: <string>, // <uint64> 
  new_version: <string>, // <AccountVersion> 
};
let options = {
  url: `https://${REST_HOST}/v1/pool/accounts/renew`,
  // 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> 
//    "renewal_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/renew'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'account_key': base64.b64encode(<bytes>),
  'absolute_expiry': <uint32>,
  'relative_expiry': <uint32>,
  'fee_rate_sat_per_kw': <uint64>,
  'new_version': <AccountVersion>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "account": <Account>,
#    "renewal_txid": <bytes>,
# }

Shell

$ pool accounts renew --help

NAME:
   pool accounts renew - renew the expiration of an account

USAGE:
   pool accounts renew [command options] trader_key sat_per_vbyte [--expiry_height | --expiry_blocks]

DESCRIPTION:
   
  Renews the expiration of an account. This will broadcast a chain
  transaction as the expiry is enforced within the account output script.
  The fee rate of said transaction must be specified.

OPTIONS:
   --trader_key value     the hex-encoded trader key of the account to renew
   --sat_per_vbyte value  the fee rate expressed in sat/vbyte that should be used for the renewal transaction (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 of 30 days equivalent in blocks) (default: 4320)
   --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.RenewAccountRequest

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type	REST Placement
account_key The key associated with the account to renew.	bytes	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
fee_rate_sat_per_kw The fee rate, in satoshis per kw, to use for the renewal transaction.	uint64	string	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 renewal.	AccountVersion	string	body

poolrpc.RenewAccountResponse

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type
account The state of the account after processing the renewal.	Account	object
renewal_txid The transaction used to renew the expiration of 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

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