package poolrpc
Get desktop application:
View/edit binary Protocol Buffers messages
rpc ReserveAccount (, )
auctioneer.proto:12message
auctioneer.proto:47uint64 account_value = 1
The desired value of the account in satoshis.
uint32 account_expiry = 2
The block height at which the account should expire.
bytes trader_key = 3
The trader's account key.
uint32 version = 4
The account version. Must be set to 0 for legacy (non-taproot) accounts.
message
auctioneer.proto:68bytes auctioneer_key = 1
The base key of the auctioneer. This key should be tweaked with the trader's per-batch tweaked key to obtain the corresponding per-batch tweaked auctioneer key. Or, in case of the version 1, Taproot enabled account, the trader and auctioneer key will be combined into a MuSig2 combined key that is static throughout the lifetime of the account. The on-chain uniqueness of the generated output will be ensured by the merkle root hash that is applied as a tweak to the MuSig2 combined internal key. The merkle root hash is either the hash of the timeout script path (which uses the trader key tweaked with the per-batch key) directly or the root of a tree with one leaf that is the timeout script path and a leaf that is a Taro commitment (which is a root hash by itself).
bytes initial_batch_key = 2
The initial per-batch key to be used for the account. For every cleared batch that the account participates in, this key will be incremented by the base point of its curve, resulting in a new key for both the trader and auctioneer in every batch.
rpc InitAccount (, )
auctioneer.proto:14message
auctioneer.proto:93optional account_point = 1
Transaction output of the account. Has to be unspent and be a P2WSH of the account script below. The amount must also exactly correspond to the account value below.
bytes account_script = 2
The script used to create the account point. For version 1 (Taproot enabled) accounts this represents the 32-byte (x-only) Taproot public key with the combined MuSig2 key of the auctioneer's key and the trader's key with the expiry script path applied as a single tapscript leaf.
uint64 account_value = 3
The value of the account in satoshis. Must match the amount of the account_point output.
uint32 account_expiry = 4
The block height at which the account should expire.
bytes trader_key = 5
The trader's account key.
string user_agent = 6
The user agent string that identifies the software running on the user's side. This can be changed in the user's client software but it _SHOULD_ conform to the following pattern and use less than 256 characters: Agent-Name/semver-version(/additional-info) Examples: poold/v0.4.2-beta/commit=3b635821,initiator=pool-cli litd/v0.4.0-alpha/commit=326d754,initiator=lit-ui
uint32 version = 7
The account version. Must be set to 0 for legacy (non-taproot) accounts.
message
auctioneer.proto:139(message has no fields)
rpc ModifyAccount (, )
auctioneer.proto:17message
auctioneer.proto:1159bytes trader_key = 1
The trader's account key of the account to be modified.
repeated new_inputs = 2
An additional set of inputs that can be included in the spending transaction of an account. These can be used to deposit more funds into an account. These must be under control of the backing lnd node's wallet.
repeated new_outputs = 3
An additional set of outputs that can be included in the spending transaction of an account. These can be used to withdraw funds from an account.
optional new_params = 4
The new parameters to apply for the account.
bytes trader_nonces = 5
A set of 66-byte nonces for each version 1 (Taproot enabled) account. The nonces can be used to produce a MuSig2 partial signature to spend the account using the key spend path, which is a MuSig2 combined key of the auctioneer key and the trader key.
repeated prev_outputs = 6
The full list of UTXO information for each of the inputs being spent. This is required when spending a Taproot enabled (account version 1) output or when adding additional Taproot inputs.
message
auctioneer.proto:1209bytes account_sig = 1
The auctioneer's signature that allows a trader to broadcast a transaction spending from an account output. For version 1 (Taproot enabled) accounts, this merely represents a partial MuSig2 signature that can be combined into a full signature by the trader daemon by adding its own partial signature. A set of nonces will be provided by the server (in case this is a v1 account) to allow finalizing the MuSig2 signing session.
bytes server_nonces = 2
An optional set of 66-byte nonces for a version 1 (Taproot enabled) account spend. The nonces can be used to produce a MuSig2 partial signature to spend the account using the key spend path, which is a MuSig2 combined key of the auctioneer key and the trader key.
rpc SubmitOrder (, )
auctioneer.proto:20message
auctioneer.proto:142oneof details
ask = 1
Submit an ask order.
bid = 2
Submit a bid order.
string user_agent = 3
The user agent string that identifies the software running on the user's side. This can be changed in the user's client software but it _SHOULD_ conform to the following pattern and use less than 256 characters: Agent-Name/semver-version(/additional-info) Examples: poold/v0.4.2-beta/commit=3b635821,initiator=pool-cli litd/v0.4.0-alpha/commit=326d754,initiator=lit-ui
message
auctioneer.proto:164oneof details
invalid_order = 1
Order failed with the given reason.
bool accepted = 2
Order was accepted.
rpc CancelOrder (, )
auctioneer.proto:23message
auctioneer.proto:178bytes order_nonce_preimage = 1
The preimage to the order's unique nonce.
message
auctioneer.proto:184(message has no fields)
rpc OrderState (, )
auctioneer.proto:26message
auctioneer.proto:1229bytes order_nonce = 1
message
auctioneer.proto:1243OrderState state = 1
The state the order currently is in.
uint32 units_unfulfilled = 2
The number of currently unfilled units of this order. This will be equal to the total amount of units until the order has reached the state PARTIAL_FILL or EXECUTED.
rpc SubscribeBatchAuction (stream , stream )
auctioneer.proto:28rpc SubscribeSidecar (stream , stream )
auctioneer.proto:31rpc Terms (, )
auctioneer.proto:34message
auctioneer.proto:1257(message has no fields)
message
auctioneer.proto:1286uint64 max_account_value = 1
The maximum account size in satoshis currently allowed by the auctioneer.
uint32 max_order_duration_blocks = 2
Deprecated, use explicit order duration from lease_duration_buckets.
optional execution_fee = 3
The execution fee charged per matched order.
map<uint32, bool> lease_durations = 4
Deprecated, use lease_duration_buckets.
uint32 next_batch_conf_target = 5
The confirmation target to use for fee estimation of the next batch.
uint64 next_batch_fee_rate_sat_per_kw = 6
The fee rate, in satoshis per kiloweight, estimated to use for the next batch.
uint64 next_batch_clear_timestamp = 7
The absolute unix timestamp at which the auctioneer will attempt to clear the next batch.
map<uint32, DurationBucketState> lease_duration_buckets = 8
The set of lease durations the market is currently accepting and the state the duration buckets currently are in.
uint32 auto_renew_extension_blocks = 9
The value used by the auctioneer to determine if an account expiry height needs to be extended after participating in a batch and for how long.
message
auctioneer.proto:1335bytes id = 1
The unique identifier of the batch.
repeated bytes accounts = 2
The set of accounts the trader is interested in retrieving information for within the batch. Each account is identified by its trader key.
message
auctioneer.proto:1346uint32 version = 1
The version of the batch.
bytes id = 2
The unique identifier of the batch.
repeated charged_accounts = 3
The set of modifications that should be applied to the requested accounts as a result of this batch.
map<string, > matched_orders = 4
Deprecated, use matched_markets.
uint32 clearing_price_rate = 5
Deprecated, use matched_markets.
optional execution_fee = 6
The fee parameters used to calculate the execution fees.
bytes transaction = 7
The batch transaction including all witness data.
uint64 fee_rate_sat_per_kw = 8
Fee rate of the batch transaction, expressed in satoshis per 1000 weight units (sat/kW).
uint64 creation_timestamp_ns = 9
The unix timestamp in nanoseconds the batch was made.
map<uint32, > matched_markets = 10
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.
rpc BatchSnapshot (, )
auctioneer.proto:38rpc NodeRating (, )
auctioneer.proto:40message
auctioneer.proto:1520repeated bytes node_pubkeys = 1
The target node to obtain ratings information for.
message
auctioneer.proto:1533repeated node_ratings = 1
A series of node ratings for each of the queried nodes.
rpc BatchSnapshots (, )
auctioneer.proto:42rpc MarketInfo (, )
auctioneer.proto:44message
auctioneer.proto:1558(message has no fields)
message
auctioneer.proto:1586map<uint32, > markets = 1
A map of all markets identified by their lease duration and the current set of statistics.
service HashMail
hashmail.proto:16HashMail exposes a simple synchronous network stream that can be used for various types of synchronization and coordination. The service allows authenticated users to create a simplex stream call a cipher box. Once the stream is created, any user that knows of the stream ID can read/write from the stream, but only a single user can be on either side at a time.
rpc NewCipherBox (, )
hashmail.proto:23NewCipherBox creates a new cipher box pipe/stream given a valid authentication mechanism. If the authentication mechanism has been revoked, or needs to be changed, then a CipherChallenge message is returned. Otherwise the method will either be accepted or rejected.
message
hashmail.proto:88oneof resp
success = 1
CipherSuccess is returned if the initialization of the cipher box was successful.
challenge = 2
CipherChallenge is returned if the authentication mechanism was revoked or needs to be refreshed.
error = 3
CipherError is returned if the authentication mechanism failed to validate.
rpc DelCipherBox (, )
hashmail.proto:30DelCipherBox attempts to tear down an existing cipher box pipe. The same authentication mechanism used to initially create the stream MUST be specified.
message
hashmail.proto:74(message has no fields)
rpc SendStream (stream , )
hashmail.proto:37SendStream opens up the write side of the passed CipherBox pipe. Writes will be non-blocking up to the buffer size of the pipe. Beyond that writes will block until completed.
rpc RecvStream (, stream )
hashmail.proto:44RecvStream opens up the read side of the passed CipherBox pipe. This method will block until a full message has been read as this is a message based pipe/stream abstraction.
service Trader
trader.proto:9rpc GetInfo (, )
trader.proto:14pool: `getinfo` GetInfo returns general information about the state of the Pool trader daemon.
message
trader.proto:1281(message has no fields)
message
trader.proto:1284string version = 1
The version of the Pool daemon that is running.
uint32 accounts_total = 2
The total number of accounts in the local database.
uint32 accounts_active = 3
The total number of accounts that are in an active, non-archived state, including expired accounts.
uint32 accounts_active_expired = 4
The total number of accounts that are active but have expired.
uint32 accounts_archived = 5
The total number of accounts that are in an archived/closed state.
uint32 orders_total = 6
The total number of orders in the local database.
uint32 orders_active = 7
The total number of active/pending orders that are still waiting for execution.
uint32 orders_archived = 8
The total number of orders that have been archived.
uint32 current_block_height = 9
The current block height as seen by the connected lnd node.
uint32 batches_involved = 10
The number of batches an account of this node was ever involved in.
optional node_rating = 11
Our lnd node's rating as judged by the auctioneer server.
uint32 lsat_tokens = 12
The number of available LSAT tokens.
bool subscribed_to_auctioneer = 13
Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server.
bool new_nodes_only = 14
Indicates whether the global `--newnodesonly` command line flag or `newnodesonly=true` configuration parameter was set on the Pool trader daemon.
map<uint32, > market_info = 15
A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest.
rpc StopDaemon (, )
trader.proto:19pool: `stop` Stop gracefully shuts down the Pool trader daemon.
message
trader.proto:1350(message has no fields)
message
trader.proto:1353(message has no fields)
rpc QuoteAccount (, )
trader.proto:26QuoteAccount gets a fee quote to fund an account of the given size with the given confirmation target. If the connected lnd wallet doesn't have enough balance to fund an account of the requested size, an error is returned.
message
trader.proto:282uint64 account_value = 1
oneof fees
uint32 conf_target = 2
The target number of blocks that the transaction should be confirmed in.
message
trader.proto:296uint64 miner_fee_rate_sat_per_kw = 1
uint64 miner_fee_total = 2
rpc InitAccount (, )
trader.proto:32pool: `accounts new` InitAccount creates a new account with the requested size and expiration, funding it from the wallet of the connected lnd node.
message
trader.proto:246uint64 account_value = 1
oneof account_expiry
uint32 absolute_height = 2
uint32 relative_height = 3
oneof fees
uint32 conf_target = 4
The target number of blocks that the transaction should be confirmed in.
uint64 fee_rate_sat_per_kw = 6
The fee rate, in satoshis per kw, to use for the initial funding transaction.
string initiator = 5
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).
AccountVersion version = 7
The version of account to create.
rpc ListAccounts (, )
trader.proto:38pool: `accounts list` ListAccounts returns a list of all accounts known to the trader daemon and their current state.
message
trader.proto:302bool active_only = 1
Only list accounts that are still active.
message
trader.proto:308repeated accounts = 1
rpc CloseAccount (, )
trader.proto:44pool: `accounts close` CloseAccount closes an account and returns the funds locked in that account to the connected lnd node's wallet.
message
trader.proto:341bytes trader_key = 1
The trader key associated with the account that will be closed.
oneof funds_destination
output_with_fee = 2
A single output/address to which the remaining funds of the account will be sent to at the specified fee. If an address is not specified, then the funds are sent to an address the backing lnd node controls.
outputs = 3
The outputs to which the remaining funds of the account will be sent to. This should only be used when wanting to create two or more outputs, otherwise OutputWithFee should be used instead. The fee of the account's closing transaction is implicitly defined by the combined value of all outputs.
message
trader.proto:363bytes close_txid = 1
The hash of the closing transaction.
rpc WithdrawAccount (, )
trader.proto:50pool: `accounts withdraw` WithdrawAccount splits off parts of the account balance into the specified outputs while recreating the account with a reduced balance.
message
trader.proto:368bytes trader_key = 1
The trader key associated with the account that funds will be withdrawed from.
repeated outputs = 2
The outputs we'll withdraw funds from the account into.
uint64 fee_rate_sat_per_kw = 3
The fee rate, in satoshis per kw, to use for the withdrawal transaction.
oneof account_expiry
uint32 absolute_expiry = 4
The new absolute expiration height of the account.
uint32 relative_expiry = 5
The new relative expiration height of the account.
AccountVersion new_version = 6
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.
message
trader.proto:398optional account = 1
The state of the account after processing the withdrawal.
bytes withdraw_txid = 2
The transaction used to withdraw funds from the account.
rpc DepositAccount (, )
trader.proto:57pool: `accounts deposit` DepositAccount adds more funds from the connected lnd node's wallet to an account.
message
trader.proto:406bytes trader_key = 1
The trader key associated with the account that funds will be deposited into.
uint64 amount_sat = 2
The amount in satoshis to deposit into the account.
uint64 fee_rate_sat_per_kw = 3
The fee rate, in satoshis per kw, to use for the deposit transaction.
oneof account_expiry
uint32 absolute_expiry = 4
The new absolute expiration height of the account.
uint32 relative_expiry = 5
The new relative expiration height of the account.
AccountVersion new_version = 6
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 deposit.
message
trader.proto:436optional account = 1
The state of the account after processing the deposit.
bytes deposit_txid = 2
The transaction used to deposit funds into the account.
rpc RenewAccount (, )
trader.proto:62pool: `accounts renew` RenewAccount renews the expiration of an account.
message
trader.proto:444bytes account_key = 1
The key associated with the account to renew.
oneof account_expiry
uint32 absolute_expiry = 2
The new absolute expiration height of the account.
uint32 relative_expiry = 3
The new relative expiration height of the account.
uint64 fee_rate_sat_per_kw = 4
The fee rate, in satoshis per kw, to use for the renewal transaction.
AccountVersion new_version = 5
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.
message
trader.proto:466optional account = 1
The state of the account after processing the renewal.
bytes renewal_txid = 2
The transaction used to renew the expiration of the account.
rpc BumpAccountFee (, )
trader.proto:72pool: `accounts bumpfee` BumpAccountFee attempts to bump the fee of an account's transaction through child-pays-for-parent (CPFP). Since the CPFP is performed through the backing lnd node, the account transaction must contain an output under its control for a successful bump. If a CPFP has already been performed for an account, and this RPC is invoked again, then a replacing transaction (RBF) of the child will be broadcast.
message
trader.proto:474bytes trader_key = 1
The trader key associated with the account that will have its fee bumped.
uint64 fee_rate_sat_per_kw = 2
The new fee rate, in satoshis per kw, to use for the child of the account transaction.
message
trader.proto:486(message has no fields)
rpc RecoverAccounts (, )
trader.proto:78pool: `accounts recover` RecoverAccounts queries the auction server for this trader daemon's accounts in case we lost our local account database.
message
trader.proto:973bool full_client = 1
Recover the latest account states without interacting with the Lightning Labs server.
uint32 account_target = 2
Number of accounts that we are trying to recover. Used during the full_client recovery process.
string auctioneer_key = 3
Auctioneer's public key. Used during the full_client recovery process. This field should be left empty for testnet/mainnet, its value is already hardcoded in our codebase.
uint32 height_hint = 4
Initial block height. We won't try to look for any account with an expiry height smaller than this value. Used during the full_client recovery process.
string bitcoin_host = 5
bitcoind/btcd instance address. Used during the full_client recovery process.
string bitcoin_user = 6
bitcoind/btcd user name. Used during the full_client recovery process.
string bitcoin_password = 7
bitcoind/btcd password. Used during the full_client recovery process.
bool bitcoin_httppostmode = 8
Use HTTP POST mode? bitcoind only supports this mode. Used during the full_client recovery process.
bool bitcoin_usetls = 9
Use TLS to connect? bitcoind only supports non-TLS connections. Used during the full_client recovery process.
string bitcoin_tlspath = 10
Path to btcd's TLS certificate, if TLS is enabled. Used during the full_client recovery process.
message
trader.proto:1025uint32 num_recovered_accounts = 1
The number of accounts that were recovered.
pool: `accounts listfees` AccountModificationFees returns a map from account key to an ordered list of account action modification fees.
message
trader.proto:1030(message has no fields)
message
trader.proto:1064map<string, > accounts = 1
A map from account key to an ordered list of account modification fees.
rpc SubmitOrder (, )
trader.proto:92pool: `orders submit` SubmitOrder creates a new ask or bid order and submits for the given account and submits it to the auction server for matching.
message
trader.proto:568oneof details
ask = 1
bid = 2
string initiator = 3
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 submitting the order (pool CLI, LiT UI, other 3rd party UI).
message
trader.proto:583oneof details
invalid_order = 1
Order failed with the given reason.
bytes accepted_order_nonce = 2
The order nonce of the accepted order.
string updated_sidecar_ticket = 3
In case a bid order was submitted for a sidecar ticket, that ticket is updated with the new state and bid order nonce.
rpc ListOrders (, )
trader.proto:98pool: `orders list` ListOrders returns a list of all active and archived orders that are currently known to the trader daemon.
message
trader.proto:603bool verbose = 1
Can be set to true to list the orders including all events, which can be very verbose.
bool active_only = 2
Only list orders that are still active.
message
trader.proto:615repeated asks = 1
repeated bids = 2
rpc CancelOrder (, )
trader.proto:104pool: `orders cancel` CancelOrder cancels an active order with the auction server to remove it from future matching.
message
trader.proto:620bytes order_nonce = 1
message
trader.proto:623(message has no fields)
rpc QuoteOrder (, )
trader.proto:110QuoteOrder calculates the premium, execution fees and max batch fee rate for an order based on the given order parameters.
message
trader.proto:788uint64 amt = 1
Order amount in satoshis.
uint32 rate_fixed = 2
Fixed order rate in parts per billion.
uint32 lease_duration_blocks = 3
Required number of blocks that a channel opened as a result of this bid should be kept open.
uint64 max_batch_fee_rate_sat_per_kw = 4
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).
uint32 min_units_match = 5
The minimum number of order units that must be matched per order pair.
message
trader.proto:814uint64 total_premium_sat = 1
The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees.
double rate_per_block = 2
The fixed order rate expressed as a fraction instead of parts per billion.
double rate_percent = 3
The fixed order rate expressed as a percentage instead of parts per billion.
uint64 total_execution_fee_sat = 4
The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order.
uint64 worst_case_chain_fee_sat = 5
The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation).
rpc AuctionFee (, )
trader.proto:116pool: `auction fee` AuctionFee returns the current auction order execution fee specified by the auction server.
message
trader.proto:1069(message has no fields)
message
trader.proto:1072optional execution_fee = 1
The execution fee charged per matched order.
rpc LeaseDurations (, )
trader.proto:122pool: `auction leasedurations` LeaseDurations returns the current set of valid lease duration in the market as is, and also information w.r.t if the market is currently active.
message
trader.proto:1226(message has no fields)
message
trader.proto:1229map<uint32, bool> lease_durations = 1
Deprecated, use lease_duration_buckets.
map<uint32, DurationBucketState> lease_duration_buckets = 2
The set of lease durations the market is currently accepting and the state the duration buckets currently are in.
rpc NextBatchInfo (, )
trader.proto:128pool: `auction nextbatchinfo` NextBatchInfo returns information about the next batch the auctioneer will perform.
message
trader.proto:1242(message has no fields)
message
trader.proto:1245uint32 conf_target = 5
The confirmation target the auctioneer will use for fee estimation of the next batch.
uint64 fee_rate_sat_per_kw = 6
The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch.
uint64 clear_timestamp = 7
The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch.
uint32 auto_renew_extension_blocks = 8
The value used by the auctioneer to determine if an account expiry height needs to be extended after participating in a batch and for how long.
rpc BatchSnapshot (, )
trader.proto:135pool: `auction snapshot` BatchSnapshot returns the snapshot of a past batch identified by its ID. If no ID is provided, the snapshot of the last finalized batch is returned. Deprecated, use BatchSnapshots instead.
rpc GetLsatTokens (, )
trader.proto:140pool: `listauth` GetLsatTokens returns all LSAT tokens the daemon ever paid for.
message
trader.proto:1171(message has no fields)
message
trader.proto:1174repeated tokens = 1
* List of all tokens the daemon knows of, including old/expired tokens.
rpc Leases (, )
trader.proto:146pool: `auction leases` Leases returns the list of channels that were either purchased or sold by the trader within the auction.
message
trader.proto:1146repeated bytes batch_ids = 1
An optional list of batches to retrieve the leases of. If empty, leases throughout all batches are returned.
repeated bytes accounts = 2
An optional list of accounts to retrieve the leases of. If empty, leases for all accounts are returned.
message
trader.proto:1160repeated leases = 1
The relevant list of leases purchased or sold within the auction.
uint64 total_amt_earned_sat = 2
The total amount of satoshis earned from the leases returned.
uint64 total_amt_paid_sat = 3
The total amount of satoshis paid for the leases returned.
rpc NodeRatings (, )
trader.proto:152pool: `auction ratings` Returns the Node Tier information for this target Lightning node, and other related ranking information.
message
trader.proto:1271repeated bytes node_pubkeys = 1
The target node to obtain ratings information for.
message
trader.proto:1276repeated node_ratings = 1
A series of node ratings for each of the queried nodes.
rpc BatchSnapshots (, )
trader.proto:161pool: `auction snapshot` BatchSnapshots returns a list of batch snapshots starting at the start batch ID and going back through the history of batches, returning at most the number of specified batches. A maximum of 100 snapshots can be queried in one call. If no start batch ID is provided, the most recent finalized batch is used as the starting point to go back from.
rpc OfferSidecar (, )
trader.proto:172pool: `sidecar offer` OfferSidecar is step 1/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 provider. The result is a sidecar ticket with an offer to lease a sidecar channel for the recipient. The offer will be signed with the provider's lnd node public key. The ticket returned by this call will have the state "offered".
message
trader.proto:1356bool auto_negotiate = 1
If false, then only the trader_key, unit, self_chan_balance, and lease_duration_blocks need to be set in the bid below. Otherwise, the fields as they're set when submitting a bid need to be filled in.
optional bid = 2
The bid template that will be used to populate the initial sidecar ticket as well as auto negotiate the remainig steps of the sidecar channel if needed.
rpc RegisterSidecar (, )
trader.proto:182pool: `sidecar register` 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".
message
trader.proto:1447string ticket = 1
The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered".
bool auto_negotiate = 2
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.
rpc ExpectSidecarChannel (, )
trader.proto:193pool: `sidecar expectchannel` ExpectSidecarChannel is step 4/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 once the provider has submitted the bid order for the sidecar channel. From this point onwards the Pool trader daemon of both the provider as well as the recipient need to be online to receive and react to match making events from the server.
message
trader.proto:1464string ticket = 1
The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered".
message
trader.proto:1472(message has no fields)
rpc DecodeSidecarTicket (, )
trader.proto:200pool: `sidecar printticket` Decodes the base58 encoded sidecar ticket into its individual data fields for a more human-readable representation.
rpc ListSidecars (, )
trader.proto:207pool: `sidecar list` ListSidecars lists all sidecar tickets currently in the local database. This includes tickets offered by our node as well as tickets that our node is the recipient of. Optionally a ticket ID can be provided to filter the tickets.
message
trader.proto:1475bytes sidecar_id = 1
The optional sidecar ID to filter for. If set, the result should either be a single ticket or no ticket in most cases. But because the ID is just 8 bytes and is randomly generated, there could be collisions, especially since tickets can also be crafted by a malicious party and given to any node. That's why the offer's public key is also used as an identifying element since that cannot easily be forged without also producing a valid signature. So an attacker cannot overwrite a ticket a node offered by themselves offering a ticket with the same ID and tricking the victim into registering that. Long story sort, there could be multiple tickets with the same ID but different offer public keys, which is why those keys should be checked as well.
message
trader.proto:1492repeated tickets = 1
rpc CancelSidecar (, )
trader.proto:214pool: `sidecar cancel` CancelSidecar cancels the execution of a specific sidecar ticket. Depending on the state of the sidecar ticket its associated bid order might be canceled as well (if this ticket was offered by our node).
message
trader.proto:1496bytes sidecar_id = 1
message
trader.proto:1500(message has no fields)
message
trader.proto:533Used as response type in: Trader.InitAccount
Used as field type in: , , ,
bytes trader_key = 1
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.
optional outpoint = 2
The current outpoint associated with the account. This will change every time the account has been updated.
uint64 value = 3
The current total amount of satoshis in the account.
uint64 available_balance = 4
The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders.
uint32 expiration_height = 5
The height at which the account will expire.
AccountState state = 6
The current state of the account.
bytes latest_txid = 7
The hash of the account's latest transaction.
AccountVersion version = 8
The current version of the account.
message
auctioneer.proto:231Used in:
bytes commit_hash = 1
The SHA256 hash of the trader's account key and a 32 byte random nonce. commit_hash = SHA256(accountPubKey || nonce)
uint32 batch_version = 2
The batch verification protocol version the client is using. Clients that don't use the latest version will be declined to connect and participate in an auction. The user should then be informed that a software update is required.
message
auctioneer.proto:841Used in: ,
uint64 ending_balance = 1
The final balance of the account after the executed batch.
AccountDiff.AccountState ending_state = 2
Depending on the amount of the final balance of the account, the remainder is either sent to a new on-chain output, extended off-chain or fully consumed by the batch and its fees.
int32 outpoint_index = 3
If the account was re-created on-chain then the new account's index in the transaction is set here. If the account was fully spent or the remainder was extended off-chain then no new account outpoint is created and -1 is returned here.
bytes trader_key = 4
The trader's account key this diff is referring to.
uint32 new_expiry = 5
The new account expiry height used to verify the batch. If the batch is successfully executed the account must update its expiry height to this value.
uint32 new_version = 6
The new account version used to verify the batch. If this is non-zero, it means the account was automatically upgraded to the given version during the batch execution.
Used in:
OUTPUT_RECREATED = 0
OUTPUT_DUST_EXTENDED_OFFCHAIN = 1
OUTPUT_DUST_ADDED_TO_FEES = 2
OUTPUT_FULLY_SPENT = 3
message
trader.proto:1033Used in:
string action = 1
Modification action type.
string txid = 2
Transaction ID.
int32 block_height = 3
Action transaction block height.
int64 timestamp = 4
Action transaction timestamp.
int64 output_amount = 5
Action transaction output amount.
oneof fee
Action transaction fee.
bool fee_null = 6
A flag which is true if fee value has not been set, and is otherwise false.
int64 fee_value = 7
Action transaction fee value.
message
auctioneer.proto:442Used in:
bytes trader_key = 1
The trader's account key of the account to recover.
Used in:
PENDING_OPEN = 0
The state of an account when it is pending its confirmation on-chain.
PENDING_UPDATE = 1
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.
OPEN = 2
The state of an account once it has confirmed on-chain.
EXPIRED = 3
The state of an account once its expiration has been reached and its closing transaction has confirmed.
PENDING_CLOSED = 4
The state of an account when we're waiting for the closing transaction of an account to confirm that required cooperation with the auctioneer.
CLOSED = 5
The state of an account once its closing transaction has confirmed.
RECOVERY_FAILED = 6
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.
PENDING_BATCH = 7
The account has recently participated in a batch and is not yet confirmed.
message
auctioneer.proto:247Used in:
bytes trader_key = 1
The trader's account key of the account to subscribe to.
bytes commit_nonce = 2
The random 32 byte nonce the trader used to create the commitment hash.
bytes auth_sig = 3
The signature over the auth_hash which is the hash of the commitment and challenge. The signature is created with the trader's account key they committed to. auth_hash = SHA256(SHA256(accountPubKey || nonce) || challenge)
Used in: , , , ,
ACCOUNT_VERSION_LND_DEPENDENT = 0
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.
ACCOUNT_VERSION_LEGACY = 1
A legacy SegWit v0 p2wsh account with a single script.
ACCOUNT_VERSION_TAPROOT = 2
A Taproot enabled account with MuSig2 combined internal key and the expiry script as a single tap script leaf.
ACCOUNT_VERSION_TAPROOT_V2 = 3
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.
message
trader.proto:758Used in: ,
optional details = 1
The common fields shared between both ask and bid order types.
uint32 lease_duration_blocks = 2
The number of blocks the liquidity provider is willing to provide the channel funds for.
uint32 version = 3
The version of the order format that is used. Will be increased once new features are added.
ChannelAnnouncementConstraints announcement_constraints = 4
The constraints for selling the liquidity based on channel discoverability.
ChannelConfirmationConstraints confirmation_constraints = 5
The constraints for selling the liquidity based on the number of blocks before considering the channel confirmed.
message
auctioneer.proto:1420Used in:
uint32 version = 1
The version of the order.
uint32 lease_duration_blocks = 2
The period of time the channel will survive for.
uint32 rate_fixed = 3
The true bid price of the order in parts per billion.
OrderChannelType chan_type = 4
The channel type to be created.
message
auctioneer.proto:748Used in: ,
uint64 value = 1
The value of the account in satoshis. Must match the amount of the account_point output.
uint32 expiry = 2
The block height at which the account should expire.
bytes trader_key = 3
The trader's account key.
bytes auctioneer_key = 4
The long term auctioneer's account key.
bytes batch_key = 5
The current batch key used to create the account output.
AuctionAccountState state = 6
The current state of the account as the auctioneer sees it.
uint32 height_hint = 7
The block height of the last change to the account's output. Can be used to scan the chain for the output's spend state more efficiently.
optional outpoint = 8
Transaction output of the account. Depending on the state of the account, this output might have been spent.
bytes latest_tx = 9
The latest transaction of an account. This is only known by the auctioneer after the account has met its initial funding confirmation.
uint32 version = 10
The account version. Will be set to 0 for legacy (non-taproot) accounts.
Used in:
STATE_PENDING_OPEN = 0
The account's funding transaction is not yet confirmed on-chain.
STATE_OPEN = 1
The account is fully open and confirmed on-chain.
STATE_EXPIRED = 2
The account is still open but the CLTV expiry has passed and the trader can close it without the auctioneer's key. Orders for accounts in this state won't be accepted.
STATE_PENDING_UPDATE = 3
The account was modified by a deposit or withdrawal and is currently waiting for the modifying transaction to confirm.
STATE_CLOSED = 4
The account is closed. The auctioneer doesn't track whether the closing transaction is already confirmed on-chain or not.
STATE_PENDING_BATCH = 5
The account has recently participated in a batch and is not yet confirmed.
STATE_EXPIRED_PENDING_UPDATE = 6
The account has reached the expiration height while it had a pending update that hasn't yet confirmed. This allows accounts to be renewed once confirmed and expired.
Used in: ,
AUCTION_TYPE_BTC_INBOUND_LIQUIDITY = 0
Default auction type where the bidder is paying for getting bitcoin inbound liqiudity from the asker.
AUCTION_TYPE_BTC_OUTBOUND_LIQUIDITY = 1
Auction type where the bidder is paying the asker to accept a channel (bitcoin outbound liquidity) from the bidder.
message
auctioneer.proto:1463Used as request type in: ChannelAuctioneer.BatchSnapshot, Trader.BatchSnapshot
bytes batch_id = 1
The unique identifier of the batch encoded as a compressed pubkey.
message
auctioneer.proto:1481Used as response type in: ChannelAuctioneer.BatchSnapshot, Trader.BatchSnapshot
Used as field type in:
uint32 version = 1
The version of the batch.
bytes batch_id = 2
The unique identifier of the batch.
bytes prev_batch_id = 3
The unique identifier of the prior batch.
uint32 clearing_price_rate = 4
Deprecated, use matched_markets.
repeated matched_orders = 5
Deprecated, use matched_markets.
string batch_tx_id = 7
The txid of the batch transaction.
bytes batch_tx = 6
The batch transaction including all witness data.
uint64 batch_tx_fee_rate_sat_per_kw = 8
The fee rate, in satoshis per kiloweight, of the batch transaction.
uint64 creation_timestamp_ns = 9
The unix timestamp in nanoseconds the batch was made.
map<uint32, > matched_markets = 10
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.
message
auctioneer.proto:1538Used as request type in: ChannelAuctioneer.BatchSnapshots, Trader.BatchSnapshots
bytes start_batch_id = 1
The unique identifier of the first batch to return, encoded as a compressed pubkey. This represents the newest/most current batch to fetch. If this is empty or a zero batch ID, the most recent finalized batch is used as the starting point to go back from.
uint32 num_batches_back = 2
The number of batches to return at most, including the start batch.
message
auctioneer.proto:1553Used as response type in: ChannelAuctioneer.BatchSnapshots, Trader.BatchSnapshots
repeated batches = 1
The list of batches requested.
message
trader.proto:705Used in: , ,
optional details = 1
The common fields shared between both ask and bid order types.
uint32 lease_duration_blocks = 2
Required number of blocks that a channel opened as a result of this bid should be kept open.
uint32 version = 3
The version of the order format that is used. Will be increased once new features are added.
NodeTier min_node_tier = 4
The minimum node tier this order should be matched with. Only asks backed by a node this tier or higher will be eligible for matching with this bid.
uint64 self_chan_balance = 5
Give the incoming channel that results from this bid being matched an initial outbound balance by adding additional funds from the taker's account into the channel. As a simplification for the execution protocol and the channel reserve calculations the min_chan_amt must be set to the full order amount. For the inbound liquidity market the self_chan_balance can be at most the same as the order amount.
string sidecar_ticket = 6
If this bid order is meant to lease a channel for another node (which is dubbed a "sidecar channel") then this ticket contains all information required for setting up that sidecar channel. The ticket is expected to be the base58 encoded ticket, including the prefix and the checksum.
bool unannounced_channel = 7
Signals if this bid is interested in an announced or unannounced channel.
bool zero_conf_channel = 8
Signals if this bid is interested in a zero conf channel or not.
message
auctioneer.proto:1433Used in:
uint32 version = 1
The version of the order.
uint32 lease_duration_blocks = 2
The period of time the matched channel should be allocated for.
uint32 rate_fixed = 3
The true bid price of the order in parts per billion.
OrderChannelType chan_type = 4
The channel type to be created.
message
auctioneer.proto:1128bytes order_nonce = 1
Channel announcement constraints for matched channels.
Used in: ,
ANNOUNCEMENT_NO_PREFERENCE = 0
ONLY_ANNOUNCED = 1
ONLY_UNANNOUNCED = 2
Channel confirmation constraints for matched channels.
Used in: ,
CONFIRMATION_NO_PREFERENCE = 0
ONLY_CONFIRMED = 1
ONLY_ZEROCONF = 2
message
auctioneer.proto:383Used in:
ChannelType type = 1
The identifying type of the channel.
bytes local_node_key = 2
The node's identifying public key.
bytes remote_node_key = 3
The remote node's identifying public key.
bytes local_payment_base_point = 4
The node's base public key used within the non-delayed pay-to-self output on the commitment transaction.
bytes remote_payment_base_point = 5
RemotePaymentBasePoint is the remote node's base public key used within the non-delayed pay-to-self output on the commitment transaction.
Used in:
TWEAKLESS = 0
The channel supports static to_remote keys.
ANCHORS = 1
The channel uses an anchor-based commitment.
SCRIPT_ENFORCED_LEASE = 2
The channel build upon the anchor-based commitment and requires an additional CLTV of the channel lease maturity on any commitment and HTLC outputs that pay directly to the channel initiator (the seller).
SIMPLE_TAPROOT = 3
A channel type that uses a Pay-to-Taproot output for the funding output.
message
hashmail.proto:114Used as request type in: HashMail.SendStream
Used as response type in: HashMail.RecvStream
optional desc = 1
bytes msg = 2
message
hashmail.proto:63Used as request type in: HashMail.DelCipherBox, HashMail.NewCipherBox
optional desc = 1
A description of the stream one is attempting to initialize.
oneof auth
acct_auth = 2
sidecar_auth = 3
message
hashmail.proto:110Used as request type in: HashMail.RecvStream
Used as response type in: HashMail.SendStream
Used as field type in: , ,
bytes stream_id = 1
message
hashmail.proto:77TODO(roasbeef): payment request, node key, etc, etc
Used in:
(message has no fields)
message
hashmail.proto:81Used in:
(message has no fields)
message
hashmail.proto:84Used in:
optional desc = 1
message
auctioneer.proto:187Used as request type in: ChannelAuctioneer.SubscribeBatchAuction, ChannelAuctioneer.SubscribeSidecar
oneof msg
commit = 1
Signal the intent to receive updates about a certain account and start by sending the commitment part of the authentication handshake. This is step 1 of the 3-way handshake.
subscribe = 2
Subscribe to update and interactive order execution events for account given and all its orders. Contains the final signature and is step 3 of the 3-way authentication handshake.
accept = 3
Accept the orders to be matched.
reject = 4
Reject a whole batch.
sign = 5
The channel funding negotiations with the matched peer were successful and the inputs to spend from the accounts are now signed.
recover = 6
The trader has lost its database and is trying to recover their accounts. This message can be sent after the successful completion of the 3-way authentication handshake where it will be established if the account exists on the auctioneer's side. This message must only be sent if the auctioneer knows of the account, otherwise it will regard it as a critical error and terminate the connection.
message
trader.proto:1383Used as response type in: Trader.DecodeSidecarTicket
Used as field type in:
bytes id = 1
The unique, pseudorandom identifier of the ticket.
uint32 version = 2
The version of the ticket encoding format.
string state = 3
The state of the ticket.
uint64 offer_capacity = 4
The offered channel capacity in satoshis.
uint64 offer_push_amount = 5
The offered push amount in satoshis.
uint32 offer_lease_duration_blocks = 6
The offered lease duration in blocks.
bytes offer_sign_pubkey = 7
The public key the offer was signed with.
bytes offer_signature = 8
The signature over the offer's digest.
bool offer_auto = 9
Whether the offer was created with the automatic order creation flag.
bytes recipient_node_pubkey = 10
The recipient node's public identity key.
bytes recipient_multisig_pubkey = 11
The recipient node's channel multisig public key to be used for the sidecar channel.
uint32 recipient_multisig_pubkey_index = 12
The index used when deriving the above multisig pubkey.
bytes order_bid_nonce = 13
The nonce of the bid order created for this sidecar ticket.
bytes order_signature = 14
The signature over the order's digest, signed with the private key that corresponds to the offer_sign_pubkey.
bytes execution_pending_channel_id = 15
The pending channel ID of the sidecar channel during the execution phase.
string encoded_ticket = 16
The original, base58 encoded ticket.
bool offer_unannounced_channel = 17
If true, the channel acceptor for this ticket will expect an unannounced channel.
bool offer_zero_conf_channel = 18
If true, the channel acceptor for this ticket will expect a zero conf channel.
Used in: ,
NO_MARKET = 0
NO_MARKET indicates that this bucket doesn't actually exist, in that no market is present for this market.
MARKET_CLOSED = 1
MARKET_CLOSED indicates that this market exists, but that it isn't currently running.
ACCEPTING_ORDERS = 2
ACCEPTING_ORDERS indicates that we're accepting orders for this bucket, but not yet clearing for this duration.
MARKET_OPEN = 3
MARKET_OPEN indicates that we're accepting orders, and fully clearing the market for this duration.
message
auctioneer.proto:1391Used in: , , ,
uint64 base_fee = 1
The base fee in satoshis charged per order, regardless of the matched size.
uint64 fee_rate = 2
The fee rate in parts per million.
message
auctioneer.proto:1132Used in: ,
bytes order_nonce = 1
InvalidOrder.FailReason fail_reason = 2
string fail_string = 3
Used in:
INVALID_AMT = 0
message
trader.proto:1079Used in:
optional channel_point = 1
The outpoint of the channel created.
uint64 channel_amt_sat = 2
The amount, in satoshis, of the channel created.
uint32 channel_duration_blocks = 3
The intended duration, in blocks, of the channel created.
uint32 channel_lease_expiry = 4
The absolute height that this channel lease expires.
uint64 premium_sat = 5
The premium, in satoshis, either paid or received for the offered liquidity.
uint64 execution_fee_sat = 6
The execution fee, in satoshis, charged by the auctioneer for the channel created.
uint64 chain_fee_sat = 7
The fee, in satoshis, charged by the auctioneer for the batch execution transaction that created this lease.
uint64 clearing_rate_price = 8
The actual fixed rate expressed in parts per billionth this lease was bought/sold at.
uint64 order_fixed_rate = 9
The actual fixed rate of the bid/ask, this should always be 'better' than the clearing_rate_price.
bytes order_nonce = 10
The order executed that resulted in the channel created.
bytes matched_order_nonce = 16
The unique identifier for the order that was matched with that resulted in the channel created.
bool purchased = 11
Whether this channel was purchased from another trader or not.
bytes channel_remote_node_key = 12
The pubkey of the node that this channel was bought/sold from.
NodeTier channel_node_tier = 13
The tier of the node that this channel was bought/sold from.
uint64 self_chan_balance = 14
The self channel balance that was pushed to the recipient.
bool sidecar_channel = 15
Whether the channel was leased as a sidecar channel (bid orders only).
message
trader.proto:1060Used in:
repeated modification_fees = 1
message
trader.proto:1181Used in:
bytes base_macaroon = 1
* The base macaroon that was baked by the auth server.
bytes payment_hash = 2
* The payment hash of the payment that was paid to obtain the token.
bytes payment_preimage = 3
* The preimage of the payment hash, knowledge of this is proof that the payment has been paid. If the preimage is set to all zeros, this means the payment is still pending and the token is not yet fully valid.
int64 amount_paid_msat = 4
* The amount of millisatoshis that was paid to get the token.
int64 routing_fee_paid_msat = 5
* The amount of millisatoshis paid in routing fee to pay for the token.
int64 time_created = 6
* The creation time of the token as UNIX timestamp in seconds.
bool expired = 7
* Indicates whether the token is expired or still valid.
string storage_name = 8
* Identifying attribute of this token in the store. Currently represents the file name of the token where it's stored on the file system.
message
auctioneer.proto:1561Used in: ,
repeated num_asks = 1
The number of open/pending ask orders per node tier.
repeated num_bids = 2
The number of open/pending bid orders per node tier.
repeated ask_open_interest_units = 3
The total number of open/unmatched units in open/pending ask orders per node tier.
repeated bid_open_interest_units = 4
The total number of open/unmatched units in open/pending bid orders per node tier.
message
auctioneer.proto:1562Used in:
NodeTier tier = 1
uint32 value = 2
message
trader.proto:884Used in:
MatchState match_state = 1
The state of the match making process the order went through.
uint32 units_filled = 2
The number of units that would be (or were) filled with this match.
bytes matched_order = 3
The nonce of the order we were matched to.
MatchRejectReason reject_reason = 4
The reason why the trader daemon rejected the order. Is only set if match_state is set to REJECTED.
Used in:
NONE = 0
No reject occurred, this is the default value.
SERVER_MISBEHAVIOR = 1
The client didn't come up with the same result as the server and is rejecting the batch because of that.
BATCH_VERSION_MISMATCH = 2
The client doesn't support the current batch verification version the server is using.
PARTIAL_REJECT_COLLATERAL = 3
The client rejects some of the orders, not the full batch. This reason is set on matches for orders that were in the same batch as partial reject ones but were not themselves rejected.
PARTIAL_REJECT_DUPLICATE_PEER = 4
The trader's client has a preference to only match orders with peers it doesn't already have channels with. The order that is rejected with this reason type comes from a peer that the trader already has channels with.
PARTIAL_REJECT_CHANNEL_FUNDING_FAILED = 5
The trader's client couldn't connect to the remote node of the matched order or the channel funding could not be initialized for another reason. This could also be the rejecting node's fault if their connection is not stable. Using this code can have a negative impact on the reputation score of both nodes, depending on the number of errors recorded.
Used in:
PREPARE = 0
The OrderMatchPrepare message from the auctioneer was received initially.
ACCEPTED = 1
The OrderMatchPrepare message from the auctioneer was processed successfully and the batch was accepted.
REJECTED = 2
The order was rejected by the trader daemon, either as an answer to a OrderMatchSignBegin or OrderMatchFinalize message from the auctioneer.
SIGNED = 3
The OrderMatchSignBegin message from the auctioneer was processed successfully.
FINALIZED = 4
The OrderMatchFinalize message from the auctioneer was processed successfully.
message
auctioneer.proto:818Used in:
optional ask = 1
The ask order that was matched against.
uint32 units_filled = 2
The number of units that were filled from/by this matched order.
message
auctioneer.proto:829Used in:
optional bid = 1
The ask order that was matched against.
uint32 units_filled = 2
The number of units that were filled from/by this matched order.
message
auctioneer.proto:521Used in: ,
map<string, > matched_orders = 1
Maps a user's own order_nonce to the opposite order type they were matched with. The order_nonce is a 32 byte hex encoded string because bytes is not allowed as a map key data type in protobuf.
uint32 clearing_price_rate = 2
The uniform clearing price rate in parts per billion that was used for this batch.
message
auctioneer.proto:1468Used in:
repeated matched_orders = 1
The set of all orders matched in the batch.
uint32 clearing_price_rate = 2
The uniform clearing price rate in parts per billion that was used for this batch.
message
auctioneer.proto:804Used in: , ,
repeated matched_bids = 1
The bids the trader's own order was matched against. This list is empty if the trader's order was a bid order itself.
repeated matched_asks = 2
The asks the trader's own order was matched against. This list is empty if the trader's order was an ask order itself.
message
auctioneer.proto:1446Used in: ,
optional ask = 1
The full ask order that was matched.
optional bid = 2
The full bid order that was matched.
uint32 matching_rate = 3
The fixed rate premium that was matched, expressed in parts-ber-billion.
uint64 total_sats_cleared = 4
The total number of satoshis that were bought.
uint32 units_matched = 5
The total number of units that were matched.
message
auctioneer.proto:1403Used in:
string network = 1
string addr = 2
message
auctioneer.proto:1525Used in: , ,
bytes node_pubkey = 1
The pubkey for the node these ratings belong to.
NodeTier node_tier = 2
The tier of the target node.
Used in: , , , ,
TIER_DEFAULT = 0
The default node tier. This value will be determined at run-time by the current order version.
TIER_0 = 1
Tier 0, bid with this tier are opting out of the smaller "higher quality" pool of nodes to match their bids. Nodes in this tier are considered to have "no rating".
TIER_1 = 2
Tier 1, the "base" node tier. Nodes in this tier are shown to have a higher degree of up time and route-ability compared to the rest of the nodes in the network. This is the current default node tier when submitting bid orders.
message
trader.proto:626Used in: ,
bytes trader_key = 1
The trader's account key of the account that is used for the order.
uint32 rate_fixed = 2
Fixed order rate in parts per billion.
uint64 amt = 3
Order amount in satoshis.
uint64 max_batch_fee_rate_sat_per_kw = 4
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).
bytes order_nonce = 5
Order nonce, acts as unique order identifier.
OrderState state = 6
The state the order currently is in.
uint32 units = 7
The number of order units the amount corresponds to.
uint32 units_unfulfilled = 8
The number of currently unfilled units of this order. This will be equal to the total amount of units until the order has reached the state PARTIAL_FILL or EXECUTED.
uint64 reserved_value_sat = 9
The value reserved from the account by this order to ensure the account can pay execution and chain fees in case it gets matched.
uint64 creation_timestamp_ns = 10
The unix timestamp in nanoseconds the order was first created/submitted.
repeated events = 11
A list of events that were emitted for this order. This field is only set when the verbose flag is set to true in the request.
uint32 min_units_match = 12
The minimum number of order units that must be matched per order pair.
OrderChannelType channel_type = 13
The channel type to use for the resulting matched channels.
repeated bytes allowed_node_ids = 14
List of nodes that will be allowed to match with our order. Incompatible with the `not_allowed_node_ids` field.
repeated bytes not_allowed_node_ids = 15
List of nodes that won't be allowed to match with our order. Incompatible with the `allowed_node_ids` field.
AuctionType auction_type = 16
Auction type where this order must be considered during the matching.
bool is_public = 17
Flag used to signal that this order can be shared in public market places.
Used in: , , ,
ORDER_CHANNEL_TYPE_UNKNOWN = 0
Used to set defaults when a trader doesn't specify a channel type.
ORDER_CHANNEL_TYPE_PEER_DEPENDENT = 1
The channel type will vary per matched channel based on the features shared between its participants.
ORDER_CHANNEL_TYPE_SCRIPT_ENFORCED = 2
A channel type that builds upon the anchors commitment format to enforce channel lease maturities in the commitment and HTLC outputs that pay to the channel initiator/seller.
ORDER_CHANNEL_TYPE_SIMPLE_TAPROOT = 3
A channel type that uses a Pay-to-Taproot output for the funding output.
message
trader.proto:848Used in:
int64 timestamp_ns = 1
The unix timestamp in nanoseconds the event was emitted at. This is the primary key of the event and is unique across the database.
string event_str = 2
The human readable representation of the event.
oneof event
state_change = 3
The order was updated in the database.
matched = 4
The order was involved in a match making attempt.
message
auctioneer.proto:267Used in:
bytes batch_id = 1
The batch ID this acceptance message refers to. Must be set to avoid out-of- order responses from disrupting the batching process.
message
auctioneer.proto:637Used in:
bytes batch_id = 1
The unique identifier of the finalized batch.
bytes batch_txid = 2
The final transaction ID of the published batch transaction.
message
auctioneer.proto:536Used in:
map<string, > matched_orders = 1
Deprecated, use matched_markets.
uint32 clearing_price_rate = 2
Deprecated, use matched_markets.
repeated charged_accounts = 3
A list of the user's own accounts that are being spent by the matched orders. The list contains the differences that would be applied by the server when executing the orders.
optional execution_fee = 4
The fee parameters used to calculate the execution fees.
bytes batch_transaction = 5
The batch transaction with all non-witness data.
uint64 fee_rate_sat_per_kw = 6
Fee rate of the batch transaction, expressed in satoshis per 1000 weight units (sat/kW).
uint64 fee_rebate_sat = 7
Fee rebate in satoshis, offered if another batch participant wants to pay more fees for a faster confirmation.
bytes batch_id = 8
The 32 byte unique identifier of this batch.
uint32 batch_version = 9
The batch verification protocol version the server is using. Clients that don't support this version MUST return an `OrderMatchAccept` message with an empty list of orders so the batch can continue. The user should then be informed that a software update is required.
map<uint32, > matched_markets = 10
Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.
uint32 batch_height_hint = 11
The earliest absolute height in the chain in which the batch transaction can be found within. This will be used by traders to base off their absolute channel lease maturity height.
message
auctioneer.proto:275Used in:
bytes batch_id = 1
The ID of the batch to reject.
string reason = 2
The reason/error string for the rejection.
OrderMatchReject.RejectReason reason_code = 3
The reason as a code.
map<string, > rejected_orders = 4
The map of order nonces the trader was matched with but doesn't accept. The map contains the _other_ trader's order nonces and the reason for rejecting them. This can be a subset of the whole list of orders presented as matches if the trader only wants to reject some of them. This map is only considered by the auctioneer if the main reason_code is set to PARTIAL_REJECT. Otherwise it is assumed that the whole batch was faulty for some reason and that the trader rejects all orders contained. The auctioneer will only accept a certain number of these partial rejects before a trader's account is removed completely from the current batch. Abusing this functionality can also lead to a ban of the trader. The order nonces are hex encoded strings because the protobuf map doesn't allow raw bytes to be the map key type.
Used in:
UNKNOWN = 0
The reason cannot be mapped to a specific code.
SERVER_MISBEHAVIOR = 1
The client didn't come up with the same result as the server and is rejecting the batch because of that.
BATCH_VERSION_MISMATCH = 2
The client doesn't support the current batch verification version the server is using.
PARTIAL_REJECT = 3
The client rejects some of the orders, not the full batch. When this code is set, the rejected_orders map must be set.
message
auctioneer.proto:406Used in:
bytes batch_id = 1
The ID of the batch that the signatures are meant for.
map<string, bytes> account_sigs = 2
A map with the signatures to spend the accounts being spent in a batch transaction. The map key corresponds to the trader's account key of the account in the batch transaction. The account key/ID has to be hex encoded into a string because protobuf doesn't allow bytes as a map key data type. For version 1 (Taproot enabled) accounts, this merely represents a partial MuSig2 signature that can be combined into a full signature by the auction server by adding its own partial signature. A set of nonces will be provided by the trader for each v1 account to allow finalizing the MuSig2 signing session.
map<string, > channel_infos = 3
The information for each channel created as part of a batch that's submitted to the auctioneer to ensure they can properly enforce a channel's service lifetime. Entries are indexed by the string representation of a channel's outpoint.
map<string, bytes> trader_nonces = 4
A set of 66-byte nonces for each version 1 (Taproot enabled) account. The nonces can be used to produce a MuSig2 partial signature to spend the account using the key spend path, which is a MuSig2 combined key of the auctioneer key and the trader key.
message
auctioneer.proto:615Used in:
bytes batch_id = 1
The 32 byte unique identifier of this batch.
map<string, bytes> server_nonces = 2
A set of 66-byte nonces for each version 1 (Taproot enabled) account. The nonces can be used to produce a MuSig2 partial signature to spend the account using the key spend path, which is a MuSig2 combined key of the auctioneer key and the trader key.
repeated prev_outputs = 3
The full list of UTXO information for each of the inputs being spent. This is required when spending one or more Taproot enabled (account version 1) outputs.
message
auctioneer.proto:332Used in:
string reason = 1
The reason/error string for the rejection.
OrderReject.OrderRejectReason reason_code = 2
The reason as a code.
Used in:
DUPLICATE_PEER = 0
The trader's client has a preference to only match orders with peers it doesn't already have channels with. The order that is rejected with this reason type comes from a peer that the trader already has channels with.
CHANNEL_FUNDING_FAILED = 1
The trader's client couldn't connect to the remote node of the matched order or the channel funding could not be initialized for another reason. This could also be the rejecting node's fault if their connection is not stable. Using this code can have a negative impact on the reputation score of both nodes, depending on the number of errors recorded.
Used in: , ,
ORDER_SUBMITTED = 0
ORDER_CLEARED = 1
ORDER_PARTIALLY_FILLED = 2
ORDER_EXECUTED = 3
ORDER_CANCELED = 4
ORDER_EXPIRED = 5
ORDER_FAILED = 6
message
auctioneer.proto:1408Used in: , , , ,
bytes txid = 1
Raw bytes representing the transaction id.
uint32 output_index = 2
The index of the output on the transaction.
message
trader.proto:312Used in: ,
uint64 value_sat = 1
The value, in satoshis, of the output.
string address = 2
The address corresponding to the output.
message
trader.proto:320Used in:
string address = 1
The address corresponding to the output.
oneof fees
uint32 conf_target = 2
The target number of blocks that the transaction should be confirmed in.
uint64 fee_rate_sat_per_kw = 3
The fee rate, in satoshis per kw, to use for the withdrawal transaction.
message
trader.proto:337Used in:
repeated outputs = 1
message
hashmail.proto:47Used in:
bytes acct_key = 1
The account key being used to authenticate.
bytes stream_sig = 2
A valid signature over the stream ID being used.
message
auctioneer.proto:1098Used in: ,
optional details = 1
The common fields shared between both ask and bid order types.
uint32 lease_duration_blocks = 4
The number of blocks the liquidity provider is willing to provide the channel funds for.
uint32 version = 5
The version of the order format that is used. Will be increased once new features are added.
ChannelAnnouncementConstraints announcement_constraints = 6
The constraints for selling the liquidity based on channel discoverability.
ChannelConfirmationConstraints confirmation_constraints = 7
The constraints for selling the liquidity based on the number of blocks before considering the channel confirmed.
message
auctioneer.proto:449Used as response type in: ChannelAuctioneer.SubscribeBatchAuction, ChannelAuctioneer.SubscribeSidecar
oneof msg
challenge = 1
Step 2 of the 3-way authentication handshake. Contains the authentication challenge. Subscriptions sent by the trader must sign the message SHA256(SHA256(accountPubKey || nonce) || challenge) with their account key to prove ownership of said key.
success = 2
The trader has subscribed to account updates successfully, the 3-way authentication handshake completed normally.
error = 3
An error occurred during any part of the communication. The trader should inspect the error code and act accordingly.
prepare = 4
The auctioneer has matched a set of orders into a batch and now instructs the traders to validate the batch and prepare for order execution. Because traders have the possibility of backing out of a batch, multiple of these messages with the SAME batch_id can be sent.
sign = 5
This message is sent after all traders send back an OrderMatchAccept method. It signals that the traders should execute their local funding protocol, then send signatures for their account inputs.
finalize = 6
All traders have accepted and signed the batch and the final transaction was broadcast.
account = 7
The answer to a trader's request for account recovery. This message contains all information that is needed to restore the account to working order on the trader side.
message
auctioneer.proto:1041Used in: ,
optional details = 1
The common fields shared between both ask and bid order types.
uint32 lease_duration_blocks = 2
Required number of blocks that a channel opened as a result of this bid should be kept open.
uint32 version = 4
The version of the order format that is used. Will be increased once new features are added.
NodeTier min_node_tier = 5
The minimum node tier this order should be matched with. Only asks backed by a node this tier or higher will be eligible for matching with this bid.
uint64 self_chan_balance = 6
Give the incoming channel that results from this bid being matched an initial outbound balance by adding additional funds from the taker's account into the channel. As a simplification for the execution protocol and the channel reserve calculations the min_chan_amt must be set to the full order amount. For the inbound liquidity market the self_chan_balance can be at most the same as the order amount.
bool is_sidecar_channel = 7
If this bid order is meant to lease a channel for another node (which is dubbed a "sidecar channel") then this boolean needs to be set to true. The multi_sig_key, node_pub and node_addr fields of the order details must then correspond to the recipient node's details.
bool unannounced_channel = 8
Signals if this bid is interested in an announced or unannounced channel.
bool zero_conf_channel = 9
Signals if this bid is interested in a zero conf channel or not.
message
auctioneer.proto:501Used in:
bytes challenge = 1
The unique challenge for each stream that has to be signed with the trader's account key for each account subscription.
bytes commit_hash = 2
The commit hash the challenge was created for.
message
auctioneer.proto:1140Used in:
optional outpoint = 1
The outpoint that the input corresponds to.
bytes sig_script = 2
The signature script required by the input. This only applies to NP2WKH inputs.
message
auctioneer.proto:1179Used in:
uint64 value = 1
The new value of the account.
uint32 expiry = 2
The new expiry of the account as an absolute height.
uint32 version = 3
The new version of the account.
message
auctioneer.proto:926Used in: ,
bytes trader_key = 1
The trader's account key of the account to use for the order.
uint32 rate_fixed = 2
Fixed order rate in parts per billion.
uint64 amt = 3
Order amount in satoshis.
uint64 min_chan_amt = 4
bytes order_nonce = 6
Order nonce of 32 byte length, acts as unique order identifier.
bytes order_sig = 7
Signature of the order's digest, signed with the user's account key. The signature must be fixed-size LN wire format encoded. Version 0 includes the fields version, rate_fixed, amt, max_batch_fee_rate_sat_per_kw and lease_duration_blocks in the order digest.
bytes multi_sig_key = 8
The multi signature key of the node creating the order, will be used for the target channel's funding TX 2-of-2 multi signature output.
bytes node_pub = 9
The pubkey of the node creating the order.
repeated node_addr = 10
The network addresses of the node creating the order.
OrderChannelType channel_type = 12
The type of the channel that should be opened.
uint64 max_batch_fee_rate_sat_per_kw = 13
Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/kW).
repeated bytes allowed_node_ids = 14
List of nodes that will be allowed to match with our order. Incompatible with the `not_allowed_node_ids` field.
repeated bytes not_allowed_node_ids = 15
List of nodes that won't be allowed to match with our order. Incompatible with the `allowed_node_ids` field.
AuctionType auction_type = 16
Auction type where this order must be considered during the matching.
bool is_public = 17
Flag used to signal that this order can be shared in public market places.
message
auctioneer.proto:1151Used in:
uint64 value = 1
The value, in satoshis, of the output.
bytes script = 2
The script of the output to send the value to.
message
hashmail.proto:55Used in:
string ticket = 1
A valid sidecar ticket that has been signed (offered) by a Pool account in the active state.
message
trader.proto:1372Used as request type in: Trader.DecodeSidecarTicket
Used as response type in: Trader.OfferSidecar, Trader.RegisterSidecar
string ticket = 1
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.
message
auctioneer.proto:652Used in:
string error = 1
The string representation of the subscription error.
SubscribeError.Error error_code = 2
The error code of the subscription error.
bytes trader_key = 3
The trader's account key this error is referring to. This is not set if the error code is SERVER_SHUTDOWN as that error is only sent once per connection and not per individual subscription.
optional account_reservation = 4
The auctioneer's partial account information as it was stored when creating the reservation. This is only set if the error code is INCOMPLETE_ACCOUNT_RESERVATION. Only the fields value, expiry, trader_key, auctioneer_key, batch_key and height_hint will be set in that case.
Used in:
UNKNOWN = 0
The error cannot be mapped to a specific code.
SERVER_SHUTDOWN = 1
The server is shutting down for maintenance. Traders should close the long-lived stream/connection and try to connect again after some time.
ACCOUNT_DOES_NOT_EXIST = 2
The account the trader tried to subscribe to does not exist in the auctioneer's database.
INCOMPLETE_ACCOUNT_RESERVATION = 3
The account the trader tried to subscribe to was never completed and a reservation for it is still pending.
message
auctioneer.proto:514Used in:
bytes trader_key = 1
The trader's account key this message is referring to.
message
auctioneer.proto:603Used in: ,
uint64 value = 1
The value of the transaction output in satoshis.
bytes pk_script = 2
The public key script of the output.
message
trader.proto:867Used in:
OrderState previous_state = 1
The state of the order previous to the change. This is what the state changed from.
OrderState new_state = 2
The new state of the order after the change. This is what the state changed to.
uint32 units_filled = 3
The units that were filled at the time of the event.