CreateAccount

CreateAccount adds an entry to the account database. This entry represents an amount of satoshis (account balance) that can be spent using off-chain transactions (e.g. paying invoices).

Macaroons can be created to be locked to an account. This makes sure that the bearer of the macaroon can only spend at most that amount of satoshis through the daemon that has issued the macaroon.

Accounts only assert a maximum amount spendable. Having a certain account balance does not guarantee that the node has the channel liquidity to actually spend that amount.

Source: lit-accounts.proto

gRPC

rpc CreateAccount (CreateAccountRequest) returns (CreateAccountResponse);

REST

HTTP Method	Path
POST	/v1/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:8443'
const MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
const TLS_PATH = 'LIT_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('lit-accounts.proto', loaderOptions);
const litrpc = grpc.loadPackageDefinition(packageDefinition).litrpc;
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 litrpc.Accounts(GRPC_HOST, creds);
let request = {
  account_balance: <uint64>,
  expiration_date: <int64>,
  label: <string>,
};
client.createAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "account": <Account>,
//    "macaroon": <bytes>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lit-accounts.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lit-accounts_pb2 as litrpc, lit-accounts_pb2_grpc as lit-accountsstub

GRPC_HOST = 'localhost:8443'
MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
TLS_PATH = 'LIT_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 = lit-accountsstub.AccountsStub(channel)
request = litrpc.CreateAccountRequest(
  account_balance=<uint64>,
  expiration_date=<int64>,
  label=<string>,
)
response = stub.CreateAccount(request)
print(response)
# {
#    "account": <Account>,
#    "macaroon": <bytes>,
# }

REST

Javascript

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

const REST_HOST = 'localhost:8443'
const MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'

let requestBody = {
  account_balance: <string>, // <uint64> 
  expiration_date: <string>, // <int64> 
  label: <string>, // <string> 
};
let options = {
  url: `https://${REST_HOST}/v1/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:
//  {
//    "account": <object>, // <Account> 
//    "macaroon": <string>, // <bytes> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8443'
MACAROON_PATH = 'LIT_DIR/regtest/lit.macaroon'
TLS_PATH = 'LIT_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/accounts'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'account_balance': <uint64>,
  'expiration_date': <int64>,
  'label': <string>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "account": <Account>,
#    "macaroon": <bytes>,
# }

Shell

$ litcli accounts create --help

NAME:
   litcli accounts create - Create a new off-chain account with a balance.

USAGE:
   litcli accounts create [command options] balance [expiration_date] [--label=LABEL] [--save_to=FILE]

DESCRIPTION:
   Adds an entry to the account database.
This entry represents an amount of satoshis (account balance) that can be spent
using off-chain transactions (e.g. paying invoices).

Macaroons can be created to be locked to an account. This makes sure that the
bearer of the macaroon can only spend at most that amount of satoshis through
the daemon that has issued the macaroon.

Accounts only assert a maximum amount spendable. Having a certain account
balance does not guarantee that the node has the channel liquidity to actually
spend that amount.

OPTIONS:
   --balance value          The initial balance of the account. (default: 0)
   --expiration_date value  The expiration date of the account expressed in seconds since the unix epoch. 0 means it does not expire. (default: 0)
   --save_to value          Store the account macaroon created for the account to the given file.
   --label value            (optional) The unique label of the account.
   

Messages

litrpc.CreateAccountRequest

Source: lit-accounts.proto

Field	gRPC Type	REST Type	REST Placement
account_balance The initial account balance in satoshis representing the maximum amount that can be spent.	uint64	string	body
expiration_date The expiration date of the account as a timestamp. Set to 0 to never expire.	int64	string	body
label An optional label to identify the account. If the label is not empty, then it must be unique, otherwise it couldn't be used to query a single account.	string	string	body

litrpc.CreateAccountResponse

Source: lit-accounts.proto

Field	gRPC Type	REST Type
account The new account that was created.	Account	object
macaroon The macaroon with all permissions required to access the account.	bytes	string

Nested Messages

litrpc.Account

Field	gRPC Type	REST Type
id The ID of the account.	string	string
initial_balance The initial balance in satoshis that was set when the account was created.	uint64	string
current_balance The current balance in satoshis.	int64	string
last_update Timestamp of the last time the account was updated.	int64	string
expiration_date Timestamp of the account's expiration date. Zero means it does not expire.	int64	string
invoices The list of invoices created by the account. An invoice created by an account will credit the account balance if it is settled.	AccountInvoice[]	array
payments The list of payments made by the account. A payment made by an account will debit the account balance if it is settled.	AccountPayment[]	array
label An optional label to identify the account. If this is not empty, then it is guaranteed to be unique.	string	string

litrpc.AccountInvoice

Field	gRPC Type	REST Type
hash The payment hash of the invoice.	bytes	string

litrpc.AccountPayment

Field	gRPC Type	REST Type
hash The payment hash.	bytes	string
state The state of the payment as reported by lnd.	string	string
full_amount The full amount in satoshis reserved for this payment. This includes the routing fee estimated by the fee limit of the payment request. The actual debited amount will likely be lower if the fee is below the limit.	int64	string