diff --git a/README.md b/README.md index 5607067a..e5fd3644 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,17 @@ # Boltz LND -This repository contains a [Boltz](https://boltz.exchange) client for [LND](https://github.com/lightningnetwork/lnd). It supports Normal Submarine Swaps (from onchain to Lightning coins) and Reverse ones (from Lightning to onchain coins). +This repository contains `boltz-lnd`, a [Boltz](https://boltz.exchange) client for [LND](https://github.com/lightningnetwork/lnd). It supports Normal Submarine Swaps (Bitcoin -> Lightning) and Reverse Submarine Swaps (Lightning -> Bitcoin). -The full documentation can be found [here](https://lnd.docs.boltz.exchange/) or in the `docs` folder +The full documentation can be found [here](https://docs.boltz.exchange/boltz-lnd) or in the [`docs`](./docs) folder of this repo. ## Building -To build Go version 1.14 or higher is required. `boltz-lnd` also has C dependencies which means a C compiler has to be installed to compile the daemon successfully. +To build `boltz-lnd`, [go](https://github.com/golang/go) version 1.14 or higher is required. `boltz-lnd` also has C dependencies which means a C compiler has to be installed to compile the daemon successfully. -The build process requires patches for dependencies, and some build flags, therefore the `Makefile` in the repository root should be used. +The build process requires patches for dependencies, and some build flags, therefore the provided [`Makefile`](Makefile) should be used. +To start the build process, run: ``` go mod vendor make build -``` \ No newline at end of file +``` diff --git a/docs/.gitbook/assets/boltz-lnd_header.png b/docs/.gitbook/assets/boltz-lnd_header.png new file mode 100644 index 00000000..e2b1b872 Binary files /dev/null and b/docs/.gitbook/assets/boltz-lnd_header.png differ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..21718f60 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,37 @@ +--- +cover: .gitbook/assets/boltz-lnd_header.png +coverY: 0 +--- + +# 👋 Introduction + +`boltz-lnd` is a [Boltz](https://boltz.exchange) client for [LND](https://github.com/lightningnetwork/lnd). It supports Normal Submarine Swaps (mainchain Bitcoin -> Lightning) and Reverse Submarine Swaps (Lightning -> mainchain Bitcoin). Other layers like Liquid are currently _not_ supported. It consists of two main components: + +## `boltzd` + +`boltzd` is the daemon that runs alongside your LND node. It connects to your LND node and hooks it up with the [Boltz API](https://api.boltz.exchange/) to create and execute swaps. + +## `boltzcli` + +`boltzcli` is the CLI tool to interact with the gRPC interface that `boltzd` exposes. + +## Setup + +The LND node to which the daemon connects has to be version `v0.10.0-beta` or higher. Also, LND needs to be compiled with these build flags (official binaries from [Lightning Labs releases](https://github.com/lightningnetwork/lnd/releases) include them already): + +* `invoicerpc` (hold invoices) +* `routerrpc` (multi path payments) +* `chainrpc` (block listener) +* `walletrpc` (fee estimations) + +Binaries of `boltz-lnd` can be found [here](https://github.com/BoltzExchange/boltz-lnd/releases). If no binaries are available for your platform, you can build them yourself with the instructions provided [here](https://github.com/BoltzExchange/boltz-lnd#building). + +### Configuration + +`boltzd` requires a connection to a LND node. In most cases the CLI flags `--lnd.certificate ` and `--lnd.macaroon ` should be enough. To view all CLI flags use `--help`. + +`boltzd` can also be configured via a `TOML` file. The full documentation for the configuration file can be found in the [configuration](configuration.md) section. + +### Macaroons + +Macaroons for the gRPC server of `boltzd` can be found in the `macaroons` folder inside the data directory of the daemon. By default, that data directory is `~/.boltz-lnd` on Linux. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 00000000..461d3082 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,7 @@ +# Table of contents + +* [👋 Introduction](README.md) +* [🎛 Configuration](configuration.md) +* [🤖 gRPC API](grpc.md) +* [🤖 REST API](https://github.com/BoltzExchange/boltz-lnd/blob/master/boltzrpc/rest-annotations.yaml) +* [🔙 Back to Docs Home](http://127.0.0.1:5000/o/SPM8mTvJyc7OIzGL3HD7/s/XUXMXrD8YTzvuqvAeom7/) diff --git a/docs/configuration.md b/docs/configuration.md index 6193552c..ddfe9451 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,25 +1,25 @@ -# Configuration +# 🎛 Configuration -`boltz-lnd` can be configured via CLI arguments, and a TOML config file. By default, the config file is called `boltz.toml` and located in the data directory of `boltz-lnd` (`/home//.boltz-lnd` by default on Linux). +`boltz-lnd` can be configured via a `TOML` config file or CLI arguments. By default, the config file is called `boltz.toml` and located in the data directory of `boltz-lnd` (`/home//.boltz-lnd` by default on Linux). ## Example ```toml -# Path the the log file +# Path to the log file logfile = "" # Prefix for all log messages. -# Useful in cases two boltz-lnd instances (one for BTC and LTC) are running in a single Docker container +# Useful in cases where multiple boltz-lnd instances are running in a Docker container logprefix = "[BTC] " [BOLTZ] -# By default the daemon automatically connects to the official Boltz instance for the network LND is on -# This value is used to override that -url = "https://testnet.boltz.exchange/api" +# By default the daemon automatically connects to the official Boltz Backend for the network LND is on +# This value is used to overwrite that +url = "https://api.boltz.exchange" [DATABASE] # Path to the SQLite database file -path = "/home/michael/test.db" +path = "/home/me/test.db" [LND] # Host of the gRPC interface of LND @@ -63,6 +63,6 @@ noMacaroons = false # Path to the admin macaroon for the gRPC and REST interface adminMacaroonPath = "" -# Path to the read only macaroon for the gRPC and REST interface +# Path to the read-only macaroon for the gRPC and REST interface readOnlyMacaroonPath = "" ``` diff --git a/docs/grpc.md b/docs/grpc.md index d839a5aa..3f39973f 100644 --- a/docs/grpc.md +++ b/docs/grpc.md @@ -1,428 +1,285 @@ -# gRPC Documentation - - - +# 🤖 gRPC API This page was automatically generated based on the protobuf file `boltzrpc.proto`. Paths for the REST proxy of the gRPC interface can be found [here](https://github.com/BoltzExchange/boltz-lnd/blob/master/boltzrpc/rest-annotations.yaml). - ## boltzrpc.Boltz - ### Methods + #### GetInfo Gets general information about the daemon like the chain of the LND node it is connected to and the IDs of pending swaps. -| Request | Response | -| ------- | -------- | -| [`GetInfoRequest`](#boltzrpc.GetInfoRequest) | [`GetInfoResponse`](#boltzrpc.GetInfoResponse) | +| Request | Response | +| --------------------------------------------------- | ----------------------------------------------------- | +| [`GetInfoRequest`](grpc.md#boltzrpc.GetInfoRequest) | [`GetInfoResponse`](grpc.md#boltzrpc.GetInfoResponse) | #### GetServiceInfo Fetches the latest limits and fees from the Boltz backend API it is connected to. -| Request | Response | -| ------- | -------- | -| [`GetServiceInfoRequest`](#boltzrpc.GetServiceInfoRequest) | [`GetServiceInfoResponse`](#boltzrpc.GetServiceInfoResponse) | +| Request | Response | +| ----------------------------------------------------------------- | ------------------------------------------------------------------- | +| [`GetServiceInfoRequest`](grpc.md#boltzrpc.GetServiceInfoRequest) | [`GetServiceInfoResponse`](grpc.md#boltzrpc.GetServiceInfoResponse) | #### ListSwaps Returns a list of all swaps, reverse swaps and channel creations in the database. -| Request | Response | -| ------- | -------- | -| [`ListSwapsRequest`](#boltzrpc.ListSwapsRequest) | [`ListSwapsResponse`](#boltzrpc.ListSwapsResponse) | +| Request | Response | +| ------------------------------------------------------- | --------------------------------------------------------- | +| [`ListSwapsRequest`](grpc.md#boltzrpc.ListSwapsRequest) | [`ListSwapsResponse`](grpc.md#boltzrpc.ListSwapsResponse) | #### GetSwapInfo Gets all available information about a swap from the database. -| Request | Response | -| ------- | -------- | -| [`GetSwapInfoRequest`](#boltzrpc.GetSwapInfoRequest) | [`GetSwapInfoResponse`](#boltzrpc.GetSwapInfoResponse) | +| Request | Response | +| ----------------------------------------------------------- | ------------------------------------------------------------- | +| [`GetSwapInfoRequest`](grpc.md#boltzrpc.GetSwapInfoRequest) | [`GetSwapInfoResponse`](grpc.md#boltzrpc.GetSwapInfoResponse) | #### Deposit This is a wrapper for channel creation swaps. The daemon only returns the ID, timeout block height and lockup address. The Boltz backend takes care of the rest. When an amount of onchain coins that is in the limits is sent to the address before the timeout block height, the daemon creates a new lightning invoice, sends it to the Boltz backend which will try to pay it and if that is not possible, create a new channel to make the swap succeed. -| Request | Response | -| ------- | -------- | -| [`DepositRequest`](#boltzrpc.DepositRequest) | [`DepositResponse`](#boltzrpc.DepositResponse) | +| Request | Response | +| --------------------------------------------------- | ----------------------------------------------------- | +| [`DepositRequest`](grpc.md#boltzrpc.DepositRequest) | [`DepositResponse`](grpc.md#boltzrpc.DepositResponse) | #### CreateSwap Creates a new swap from onchain to lightning. -| Request | Response | -| ------- | -------- | -| [`CreateSwapRequest`](#boltzrpc.CreateSwapRequest) | [`CreateSwapResponse`](#boltzrpc.CreateSwapResponse) | +| Request | Response | +| --------------------------------------------------------- | ----------------------------------------------------------- | +| [`CreateSwapRequest`](grpc.md#boltzrpc.CreateSwapRequest) | [`CreateSwapResponse`](grpc.md#boltzrpc.CreateSwapResponse) | #### CreateChannel Create a new swap from onchain to a new lightning channel. The daemon will only accept the invoice payment if the HTLCs is coming trough a new channel channel opened by Boltz. -| Request | Response | -| ------- | -------- | -| [`CreateChannelRequest`](#boltzrpc.CreateChannelRequest) | [`CreateSwapResponse`](#boltzrpc.CreateSwapResponse) | +| Request | Response | +| --------------------------------------------------------------- | ----------------------------------------------------------- | +| [`CreateChannelRequest`](grpc.md#boltzrpc.CreateChannelRequest) | [`CreateSwapResponse`](grpc.md#boltzrpc.CreateSwapResponse) | #### CreateReverseSwap Creates a new reverse swap from lightning to onchain. If `accept_zero_conf` is set to true in the request, the daemon will not wait until the lockup transaction from Boltz is confirmed in a block, but will claim it instantly. -| Request | Response | -| ------- | -------- | -| [`CreateReverseSwapRequest`](#boltzrpc.CreateReverseSwapRequest) | [`CreateReverseSwapResponse`](#boltzrpc.CreateReverseSwapResponse) | - - - +| Request | Response | +| ----------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| [`CreateReverseSwapRequest`](grpc.md#boltzrpc.CreateReverseSwapRequest) | [`CreateReverseSwapResponse`](grpc.md#boltzrpc.CreateReverseSwapResponse) | ### Messages -####
ChannelCreationInfo
-Channel creations are an optional extension to a submarine swap in the data types of boltz-lnd. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `swap_id` | [`string`](#string) | | ID of the swap to which this channel channel belongs | -| `status` | [`string`](#string) | | | -| `inbound_liquidity` | [`uint32`](#uint32) | | | -| `private` | [`bool`](#bool) | | | -| `funding_transaction_id` | [`string`](#string) | | | -| `funding_transaction_vout` | [`uint32`](#uint32) | | | - - - - - -####
CombinedChannelSwapInfo
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `swap` | [`SwapInfo`](#boltzrpc.SwapInfo) | | | -| `channel_creation` | [`ChannelCreationInfo`](#boltzrpc.ChannelCreationInfo) | | | - - - - - -####
CreateChannelRequest
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `amount` | [`int64`](#int64) | | | -| `inbound_liquidity` | [`uint32`](#uint32) | | Percentage of inbound liquidity the channel that is opened should have. 25 by default. | -| `private` | [`bool`](#bool) | | | - - - - - -####
CreateReverseSwapRequest
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `amount` | [`int64`](#int64) | | | -| `address` | [`string`](#string) | | If no value is set, the daemon will query a new P2WKH address from LND | -| `accept_zero_conf` | [`bool`](#bool) | | | - - - - - -####
CreateReverseSwapResponse
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `id` | [`string`](#string) | | | -| `lockup_address` | [`string`](#string) | | | -| `routing_fee_milli_sat` | [`uint32`](#uint32) | | | -| `claim_transaction_id` | [`string`](#string) | | Only populated when 0-conf is accepted | - - - - - -####
CreateSwapRequest
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `amount` | [`int64`](#int64) | | | - - - - - -####
CreateSwapResponse
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `id` | [`string`](#string) | | | -| `address` | [`string`](#string) | | | -| `expected_amount` | [`int64`](#int64) | | | -| `bip21` | [`string`](#string) | | | - - - - - -####
DepositRequest
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `inbound_liquidity` | [`uint32`](#uint32) | | Percentage of inbound liquidity the channel that is opened in case the invoice cannot be paid should have. 25 by default. | - - - - - -####
DepositResponse
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `id` | [`string`](#string) | | | -| `address` | [`string`](#string) | | | -| `timeout_block_height` | [`uint32`](#uint32) | | | - - - - - -####
Fees
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `percentage` | [`float`](#float) | | | -| `miner` | [`MinerFees`](#boltzrpc.MinerFees) | | | - +#### ChannelCreationInfo +Channel creations are an optional extension to a submarine swap in the data types of boltz-lnd. +| Field | Type | Label | Description | +| -------------------------- | -------------------------- | ----- | ---------------------------------------------------- | +| `swap_id` | [`string`](grpc.md#string) | | ID of the swap to which this channel channel belongs | +| `status` | [`string`](grpc.md#string) | | | +| `inbound_liquidity` | [`uint32`](grpc.md#uint32) | | | +| `private` | [`bool`](grpc.md#bool) | | | +| `funding_transaction_id` | [`string`](grpc.md#string) | | | +| `funding_transaction_vout` | [`uint32`](grpc.md#uint32) | | | +#### CombinedChannelSwapInfo -####
GetInfoRequest
- - - - - - -####
GetInfoResponse
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `symbol` | [`string`](#string) | | | -| `network` | [`string`](#string) | | | -| `lnd_pubkey` | [`string`](#string) | | | -| `block_height` | [`uint32`](#uint32) | | | -| `pending_swaps` | [`string`](#string) | repeated | | -| `pending_reverse_swaps` | [`string`](#string) | repeated | | - - - - - -####
GetServiceInfoRequest
- - - - - - -####
GetServiceInfoResponse
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `fees` | [`Fees`](#boltzrpc.Fees) | | | -| `limits` | [`Limits`](#boltzrpc.Limits) | | | - - - - - -####
GetSwapInfoRequest
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `id` | [`string`](#string) | | | - - - - - -####
GetSwapInfoResponse
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `swap` | [`SwapInfo`](#boltzrpc.SwapInfo) | | | -| `channel_creation` | [`ChannelCreationInfo`](#boltzrpc.ChannelCreationInfo) | | | -| `reverse_swap` | [`ReverseSwapInfo`](#boltzrpc.ReverseSwapInfo) | | | - - - - - -####
Limits
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `minimal` | [`int64`](#int64) | | | -| `maximal` | [`int64`](#int64) | | | - - - - - -####
ListSwapsRequest
- - - - - - -####
ListSwapsResponse
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `swaps` | [`SwapInfo`](#boltzrpc.SwapInfo) | repeated | | -| `channel_creations` | [`CombinedChannelSwapInfo`](#boltzrpc.CombinedChannelSwapInfo) | repeated | | -| `reverse_swaps` | [`ReverseSwapInfo`](#boltzrpc.ReverseSwapInfo) | repeated | | - - - - - -####
MinerFees
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `normal` | [`uint32`](#uint32) | | | -| `reverse` | [`uint32`](#uint32) | | | - - - - - -####
ReverseSwapInfo
- - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `id` | [`string`](#string) | | | -| `state` | [`SwapState`](#boltzrpc.SwapState) | | | -| `error` | [`string`](#string) | | | -| `status` | [`string`](#string) | | Latest status message of the Boltz backend | -| `private_key` | [`string`](#string) | | | -| `preimage` | [`string`](#string) | | | -| `redeem_script` | [`string`](#string) | | | -| `invoice` | [`string`](#string) | | | -| `claim_address` | [`string`](#string) | | | -| `onchain_amount` | [`int64`](#int64) | | | -| `timeout_block_height` | [`uint32`](#uint32) | | | -| `lockup_transaction_id` | [`string`](#string) | | | -| `claim_transaction_id` | [`string`](#string) | | | +| Field | Type | Label | Description | +| ------------------ | ------------------------------------------------------------- | ----- | ----------- | +| `swap` | [`SwapInfo`](grpc.md#boltzrpc.SwapInfo) | | | +| `channel_creation` | [`ChannelCreationInfo`](grpc.md#boltzrpc.ChannelCreationInfo) | | | +#### CreateChannelRequest +| Field | Type | Label | Description | +| ------------------- | -------------------------- | ----- | -------------------------------------------------------------------------------------- | +| `amount` | [`int64`](grpc.md#int64) | | | +| `inbound_liquidity` | [`uint32`](grpc.md#uint32) | | Percentage of inbound liquidity the channel that is opened should have. 25 by default. | +| `private` | [`bool`](grpc.md#bool) | | | +#### CreateReverseSwapRequest +| Field | Type | Label | Description | +| ------------------ | -------------------------- | ----- | ---------------------------------------------------------------------- | +| `amount` | [`int64`](grpc.md#int64) | | | +| `address` | [`string`](grpc.md#string) | | If no value is set, the daemon will query a new P2WKH address from LND | +| `accept_zero_conf` | [`bool`](grpc.md#bool) | | | -####
SwapInfo
+#### CreateReverseSwapResponse +| Field | Type | Label | Description | +| ----------------------- | -------------------------- | ----- | -------------------------------------- | +| `id` | [`string`](grpc.md#string) | | | +| `lockup_address` | [`string`](grpc.md#string) | | | +| `routing_fee_milli_sat` | [`uint32`](grpc.md#uint32) | | | +| `claim_transaction_id` | [`string`](grpc.md#string) | | Only populated when 0-conf is accepted | +#### CreateSwapRequest -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| `id` | [`string`](#string) | | | -| `state` | [`SwapState`](#boltzrpc.SwapState) | | | -| `error` | [`string`](#string) | | | -| `status` | [`string`](#string) | | Latest status message of the Boltz backend | -| `private_key` | [`string`](#string) | | | -| `preimage` | [`string`](#string) | | | -| `redeem_script` | [`string`](#string) | | | -| `invoice` | [`string`](#string) | | | -| `lockup_address` | [`string`](#string) | | | -| `expected_amount` | [`int64`](#int64) | | | -| `timeout_block_height` | [`uint32`](#uint32) | | | -| `lockup_transaction_id` | [`string`](#string) | | | -| `refund_transaction_id` | [`string`](#string) | | If the swap times out or fails for some other reason, the damon will automatically refund the coins sent to the `lockup_address` back to the LND wallet and save the refund transaction id to the database. | +| Field | Type | Label | Description | +| -------- | ------------------------ | ----- | ----------- | +| `amount` | [`int64`](grpc.md#int64) | | | +#### CreateSwapResponse +| Field | Type | Label | Description | +| ----------------- | -------------------------- | ----- | ----------- | +| `id` | [`string`](grpc.md#string) | | | +| `address` | [`string`](grpc.md#string) | | | +| `expected_amount` | [`int64`](grpc.md#int64) | | | +| `bip21` | [`string`](grpc.md#string) | | | +#### DepositRequest +| Field | Type | Label | Description | +| ------------------- | -------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | +| `inbound_liquidity` | [`uint32`](grpc.md#uint32) | | Percentage of inbound liquidity the channel that is opened in case the invoice cannot be paid should have. 25 by default. | +#### DepositResponse + +| Field | Type | Label | Description | +| ---------------------- | -------------------------- | ----- | ----------- | +| `id` | [`string`](grpc.md#string) | | | +| `address` | [`string`](grpc.md#string) | | | +| `timeout_block_height` | [`uint32`](grpc.md#uint32) | | | + +#### Fees + +| Field | Type | Label | Description | +| ------------ | ----------------------------------------- | ----- | ----------- | +| `percentage` | [`float`](grpc.md#float) | | | +| `miner` | [`MinerFees`](grpc.md#boltzrpc.MinerFees) | | | + +#### GetInfoRequest + +#### GetInfoResponse + +| Field | Type | Label | Description | +| ----------------------- | -------------------------- | -------- | ----------- | +| `symbol` | [`string`](grpc.md#string) | | | +| `network` | [`string`](grpc.md#string) | | | +| `lnd_pubkey` | [`string`](grpc.md#string) | | | +| `block_height` | [`uint32`](grpc.md#uint32) | | | +| `pending_swaps` | [`string`](grpc.md#string) | repeated | | +| `pending_reverse_swaps` | [`string`](grpc.md#string) | repeated | | + +#### GetServiceInfoRequest + +#### GetServiceInfoResponse + +| Field | Type | Label | Description | +| -------- | ----------------------------------- | ----- | ----------- | +| `fees` | [`Fees`](grpc.md#boltzrpc.Fees) | | | +| `limits` | [`Limits`](grpc.md#boltzrpc.Limits) | | | + +#### GetSwapInfoRequest + +| Field | Type | Label | Description | +| ----- | -------------------------- | ----- | ----------- | +| `id` | [`string`](grpc.md#string) | | | + +#### GetSwapInfoResponse + +| Field | Type | Label | Description | +| ------------------ | ------------------------------------------------------------- | ----- | ----------- | +| `swap` | [`SwapInfo`](grpc.md#boltzrpc.SwapInfo) | | | +| `channel_creation` | [`ChannelCreationInfo`](grpc.md#boltzrpc.ChannelCreationInfo) | | | +| `reverse_swap` | [`ReverseSwapInfo`](grpc.md#boltzrpc.ReverseSwapInfo) | | | + +#### Limits + +| Field | Type | Label | Description | +| --------- | ------------------------ | ----- | ----------- | +| `minimal` | [`int64`](grpc.md#int64) | | | +| `maximal` | [`int64`](grpc.md#int64) | | | + +#### ListSwapsRequest + +#### ListSwapsResponse + +| Field | Type | Label | Description | +| ------------------- | --------------------------------------------------------------------- | -------- | ----------- | +| `swaps` | [`SwapInfo`](grpc.md#boltzrpc.SwapInfo) | repeated | | +| `channel_creations` | [`CombinedChannelSwapInfo`](grpc.md#boltzrpc.CombinedChannelSwapInfo) | repeated | | +| `reverse_swaps` | [`ReverseSwapInfo`](grpc.md#boltzrpc.ReverseSwapInfo) | repeated | | + +#### MinerFees + +| Field | Type | Label | Description | +| --------- | -------------------------- | ----- | ----------- | +| `normal` | [`uint32`](grpc.md#uint32) | | | +| `reverse` | [`uint32`](grpc.md#uint32) | | | + +#### ReverseSwapInfo + +| Field | Type | Label | Description | +| ----------------------- | ----------------------------------------- | ----- | ------------------------------------------ | +| `id` | [`string`](grpc.md#string) | | | +| `state` | [`SwapState`](grpc.md#boltzrpc.SwapState) | | | +| `error` | [`string`](grpc.md#string) | | | +| `status` | [`string`](grpc.md#string) | | Latest status message of the Boltz backend | +| `private_key` | [`string`](grpc.md#string) | | | +| `preimage` | [`string`](grpc.md#string) | | | +| `redeem_script` | [`string`](grpc.md#string) | | | +| `invoice` | [`string`](grpc.md#string) | | | +| `claim_address` | [`string`](grpc.md#string) | | | +| `onchain_amount` | [`int64`](grpc.md#int64) | | | +| `timeout_block_height` | [`uint32`](grpc.md#uint32) | | | +| `lockup_transaction_id` | [`string`](grpc.md#string) | | | +| `claim_transaction_id` | [`string`](grpc.md#string) | | | + +#### SwapInfo + +| Field | Type | Label | Description | +| ----------------------- | ----------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | [`string`](grpc.md#string) | | | +| `state` | [`SwapState`](grpc.md#boltzrpc.SwapState) | | | +| `error` | [`string`](grpc.md#string) | | | +| `status` | [`string`](grpc.md#string) | | Latest status message of the Boltz backend | +| `private_key` | [`string`](grpc.md#string) | | | +| `preimage` | [`string`](grpc.md#string) | | | +| `redeem_script` | [`string`](grpc.md#string) | | | +| `invoice` | [`string`](grpc.md#string) | | | +| `lockup_address` | [`string`](grpc.md#string) | | | +| `expected_amount` | [`int64`](grpc.md#int64) | | | +| `timeout_block_height` | [`uint32`](grpc.md#uint32) | | | +| `lockup_transaction_id` | [`string`](grpc.md#string) | | | +| `refund_transaction_id` | [`string`](grpc.md#string) | | If the swap times out or fails for some other reason, the damon will automatically refund the coins sent to the `lockup_address` back to the LND wallet and save the refund transaction id to the database. | ### Enums - - - #### SwapState - -| Name | Number | Description | -| ---- | ------ | ----------- | -| PENDING | 0 | | -| SUCCESSFUL | 1 | | -| ERROR | 2 | Unknown client error. Check the error field of the message for more information | -| SERVER_ERROR | 3 | Unknown server error. Check the status field of the message for more information | -| REFUNDED | 4 | Client refunded locked coins after the HTLC timed out | -| ABANDONED | 5 | Client noticed that the HTLC timed out but didn't find any outputs to refund | - - - +| Name | Number | Description | +| ------------- | ------ | -------------------------------------------------------------------------------- | +| PENDING | 0 | | +| SUCCESSFUL | 1 | | +| ERROR | 2 | Unknown client error. Check the error field of the message for more information | +| SERVER\_ERROR | 3 | Unknown server error. Check the status field of the message for more information | +| REFUNDED | 4 | Client refunded locked coins after the HTLC timed out | +| ABANDONED | 5 | Client noticed that the HTLC timed out but didn't find any outputs to refund | ## Scalar Value Types -| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | -| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | -|
`double` | | `double` | `double` | `float` | `float64` | `double` | `float` | `Float` | -|
`float` | | `float` | `float` | `float` | `float32` | `float` | `float` | `Float` | -|
`int32` | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | `int32` | `int` | `int` | `int32` | `int` | `integer` | `Bignum or Fixnum (as required)` | -|
`int64` | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | `int64` | `long` | `int/long` | `int64` | `long` | `integer/string` | `Bignum` | -|
`uint32` | Uses variable-length encoding. | `uint32` | `int` | `int/long` | `uint32` | `uint` | `integer` | `Bignum or Fixnum (as required)` | -|
`uint64` | Uses variable-length encoding. | `uint64` | `long` | `int/long` | `uint64` | `ulong` | `integer/string` | `Bignum or Fixnum (as required)` | -|
`sint32` | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | `int32` | `int` | `int` | `int32` | `int` | `integer` | `Bignum or Fixnum (as required)` | -|
`sint64` | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | `int64` | `long` | `int/long` | `int64` | `long` | `integer/string` | `Bignum` | -|
`fixed32` | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | `uint32` | `int` | `int` | `uint32` | `uint` | `integer` | `Bignum or Fixnum (as required)` | -|
`fixed64` | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | `uint64` | `long` | `int/long` | `uint64` | `ulong` | `integer/string` | `Bignum` | -|
`sfixed32` | Always four bytes. | `int32` | `int` | `int` | `int32` | `int` | `integer` | `Bignum or Fixnum (as required)` | -|
`sfixed64` | Always eight bytes. | `int64` | `long` | `int/long` | `int64` | `long` | `integer/string` | `Bignum` | -|
`bool` | | `bool` | `boolean` | `boolean` | `bool` | `bool` | `boolean` | `TrueClass/FalseClass` | -|
`string` | A string must always contain UTF-8 encoded or 7-bit ASCII text. | `string` | `String` | `str/unicode` | `string` | `string` | `string` | `String (UTF-8)` | -|
`bytes` | May contain any arbitrary sequence of bytes. | `string` | `ByteString` | `str` | `[]byte` | `ByteString` | `string` | `String (ASCII-8BIT)` | - +| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------- | --------- | ------------ | ---------------- | -------------------------------- | +| `double` | | `double` | `double` | `float` | `float64` | `double` | `float` | `Float` | +| `float` | | `float` | `float` | `float` | `float32` | `float` | `float` | `Float` | +| `int32` | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | `int32` | `int` | `int` | `int32` | `int` | `integer` | `Bignum or Fixnum (as required)` | +| `int64` | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | `int64` | `long` | `int/long` | `int64` | `long` | `integer/string` | `Bignum` | +| `uint32` | Uses variable-length encoding. | `uint32` | `int` | `int/long` | `uint32` | `uint` | `integer` | `Bignum or Fixnum (as required)` | +| `uint64` | Uses variable-length encoding. | `uint64` | `long` | `int/long` | `uint64` | `ulong` | `integer/string` | `Bignum or Fixnum (as required)` | +| `sint32` | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | `int32` | `int` | `int` | `int32` | `int` | `integer` | `Bignum or Fixnum (as required)` | +| `sint64` | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | `int64` | `long` | `int/long` | `int64` | `long` | `integer/string` | `Bignum` | +| `fixed32` | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | `uint32` | `int` | `int` | `uint32` | `uint` | `integer` | `Bignum or Fixnum (as required)` | +| `fixed64` | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | `uint64` | `long` | `int/long` | `uint64` | `ulong` | `integer/string` | `Bignum` | +| `sfixed32` | Always four bytes. | `int32` | `int` | `int` | `int32` | `int` | `integer` | `Bignum or Fixnum (as required)` | +| `sfixed64` | Always eight bytes. | `int64` | `long` | `int/long` | `int64` | `long` | `integer/string` | `Bignum` | +| `bool` | | `bool` | `boolean` | `boolean` | `bool` | `bool` | `boolean` | `TrueClass/FalseClass` | +| `string` | A string must always contain UTF-8 encoded or 7-bit ASCII text. | `string` | `String` | `str/unicode` | `string` | `string` | `string` | `String (UTF-8)` | +| `bytes` | May contain any arbitrary sequence of bytes. | `string` | `ByteString` | `str` | `[]byte` | `ByteString` | `string` | `String (ASCII-8BIT)` | diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 73cb574a..00000000 --- a/docs/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# boltz-lnd v1.2.3 documentation - -`boltz-lnd` is a [Boltz](https://boltz.exchange) client for [LND](https://github.com/lightningnetwork/lnd). It supports Normal Submarine Swaps (from onchain to Lightning coins) and Reverse Submarine Swaps (from Lightning to onchain coins). - -## `boltzd` - -`boltzd` is a daemon that should run alongside of your LND node. It connects to your LND node, and the Boltz API to create and execute Swaps. - -## `boltzcli` - -`boltzcli` is a CLI tool to interact with the gRPC interface `boltzd` exposes. - -## Setup - -The LND node to which the daemon connects has to be version `v0.10.0-beta` or higher. Also, LND needs to be compiled with these build flags (official binaries from Lightning Labs releases include them): - -- `invoicerpc` (hold invoices) -- `routerrpc` (multi path payments) -- `chainrpc` (block listener) -- `walletrpc` (fee estimations) - -Binaries for the latest release of `boltz-lnd` can be found on the [releases page](https://github.com/BoltzExchange/boltz-lnd/releases). If no binaries are available for your platform, you can build them yourself with the instructions provided in the [README](https://github.com/BoltzExchange/boltz-lnd#building). - -### Configuration - -`boltzd` requires a connection to a LND node. In most cases the CLI flags `--lnd.certificate ` and `--lnd.macaroon ` should be enough. To view all CLI flags use `--help`. - -`boltzd` can also be configured via a TOML file. The full documentation for the configuration file can be found [here](configuration.md). - -### Macaroons - -The macaroons for the gRPC server of `boltzd` can be found in the `macaroons` folder inside the data directory of the daemon. By default, that data directory is `~/.boltz-lnd` on Linux.