Skip to content

Commit 0af037a

Browse files
dangerossdangeross
committed
Add API docs tags
1 parent 1f44066 commit 0af037a

27 files changed

+214
-52
lines changed

‎book.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ title = "Breez SDK - Greenlight"
77

88
[output.html]
99
theme="theme"
10-
additional-css = ["task-lists.css"]
10+
additional-css = ["styles.css"]
1111
additional-js = ["tabs.js"]
1212
git-repository-url = "https://github.com/breez/breez-sdk-docs"
1313
edit-url-template = "https://github.com/breez/breez-sdk-docs/edit/main/{path}"

‎src/guide/buy_btc.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Buying Bitcoin
1+
<h1 id="buying-bitcoin">
2+
<a class="header" href="#buying-bitcoin">Buying Bitcoin</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.buy_bitcoin">API docs</a>
4+
</h1>
25

36
This section of the Breez SDK documentation provides an example on purchasing Bitcoin using Moonpay as the provider. The example code snippet demonstrates how to initiate a Bitcoin purchase transaction using the Breez SDK.
47

‎src/guide/closed_channels.md

+10-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22

33
When channels are closed (due to a misbehaving node or by the LSP), the remaining funds are sent to an on-chain address. To redeem these funds please follow the steps below.
44

5-
## Preparing the transaction
5+
<h2 id="preparing-the-transaction">
6+
<a class="header" href="#preparing-the-transaction">Preparing the transaction</a>
7+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.prepare_redeem_onchain_funds">API docs</a>
8+
</h2>
9+
610
Prepare the transaction to retrieve its weight and the calculated fees before broadcasting it:
711

812
<custom-tabs category="lang">
@@ -71,7 +75,11 @@ Prepare the transaction to retrieve its weight and the calculated fees before br
7175
</section>
7276
</custom-tabs>
7377

74-
## Redeeming the on-chain funds
78+
<h2 id="redeeming-the-on-chain-funds">
79+
<a class="header" href="#redeeming-the-on-chain-funds">Redeeming the on-chain funds</a>
80+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.redeem_onchain_funds">API docs</a>
81+
</h2>
82+
7583
Redeem the on-chain funds by broadcasting the transaction to the network:
7684

7785
<custom-tabs category="lang">

‎src/guide/communicating_fees.md

+13-5
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22

33
In the LSP model, fees are involved when the user wants to receive a payment, but doesn't have a sufficient receivable amount. This section provides recommendations on how to communicate these fees to a user.
44

5-
### Before receiving a Lightning payment
5+
<h2 id="before-receiving-a-lightning-payment">
6+
<a class="header" href="#before-receiving-a-lightning-payment">Before receiving a Lightning payment</a>
7+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.open_channel_fee">API docs</a>
8+
</h2>
9+
610
When the user wants to receive a payment, a setup fee is paid when the resulting invoice would exceed the receivable amount.
711
The setup fee is made up of two parts:
812
- A minimum fee
@@ -80,7 +84,7 @@ You can construct this message as follows:
8084
</section>
8185
</custom-tabs>
8286

83-
### After creating an invoice
87+
## After creating an invoice
8488
After calling `receive_payment`, you would typically show the recipient a screen containing a QR code with the invoice that the sender can scan.
8589

8690
This is another place to show the user the opening fees applied to the invoice. At this point the amount the user wants to receive is known, so the message can be more concise:
@@ -161,12 +165,16 @@ Here is how you can build this message:
161165
</section>
162166
</custom-tabs>
163167

164-
### Sending a Lightning payment
168+
## Sending a Lightning payment
165169
Routing fees for sending Lightning payments vary based on the available path, as some channels incur higher fees due to the distribution of liquidity across the network. Developers have the option to set limits on Lightning fees, which are capped by default at 1% of the payment amount. However, it's important to note that restricting fees can increase the likelihood of payment failures.
166170

167171
For users leveraging trampoline payments (recommended for reliabily), routing fees are currently fixed at 0.5% + 4 sat.
168172

169-
### Receiving an on-chain transaction
173+
<h2 id="receiving-an-on-chain-transaction">
174+
<a class="header" href="#receiving-an-on-chain-transaction">Receiving an on-chain transaction</a>
175+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.receive_onchain">API docs</a>
176+
</h2>
177+
170178
For receiving onchain, there is a minimum and a maximum amount the user can receive. The fees are made up of the same components as receiving a lightning payment.
171179

172180
The user gets an onchain address from `receive_onchain`. There is no way to know ahead of time exactly the amount that will be received on this address, so it is recommended to show the user the receivable boundaries and the fees involved:
@@ -241,7 +249,7 @@ Below code sample constructs this message.
241249
</section>
242250
</custom-tabs>
243251

244-
### Sending an on-chain transaction
252+
## Sending an on-chain transaction
245253
Sending an on-chain transaction to a BTC address involves a trustless [reverse swap](https://medium.com/breez-technology/reverse-submarine-swaps-another-step-towards-a-p2p-lightning-economy-bacb040fdca7). Reverse swaps have a minimum transaction amount of 50,000 sats, which may increase during periods of high fees. The reverse swap provider, [Boltz](https://boltz.exchange/), charges a fixed service fee of 0.5% plus an additional mining fee based on current Bitcoin mempool usage.
246254

247255
Follow the instructions [here](./pay_onchain.html) to calculate limits and fees.

‎src/guide/connecting.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Connecting to a node
1+
<h1 id="connecting-to-a-node">
2+
<a class="header" href="#connecting-to-a-node">Connecting to a node</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.connect">API docs</a>
4+
</h1>
25

36
The first step is to construct the SDK configuration. In it the environment and Greenlight node configuration is defined, whether you are using an invite code or partner credentials.
47

‎src/guide/connecting_lsp.md

+12-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Connecting to an LSP
22

3-
## Getting the current LSP Information
3+
<h2 id="getting-the-current-lsp-information">
4+
<a class="header" href="#getting-the-current-lsp-information">Getting the current LSP Information</a>
5+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.lsp_info">API docs</a>
6+
</h2>
47

58
Based on the API key provided to the Breez SDK, a default LSP is selected for your node to provide liquidity to it. To get the information about the selected LSP you can do the following:
69

@@ -70,7 +73,10 @@ Based on the API key provided to the Breez SDK, a default LSP is selected for yo
7073
</section>
7174
</custom-tabs>
7275

73-
## Listing available LSPs
76+
<h2 id="listing-available-lsps">
77+
<a class="header" href="#listing-available-lsps">Listing available LSPs</a>
78+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.list_lsps">API docs</a>
79+
</h2>
7480

7581
In order to list all available LSPs you may connect to, you may do the following:
7682

@@ -140,7 +146,10 @@ In order to list all available LSPs you may connect to, you may do the following
140146
</section>
141147
</custom-tabs>
142148

143-
## Switching to another LSP
149+
<h2 id="switching-to-another-lsp">
150+
<a class="header" href="#switching-to-another-lsp">Switching to another LSP</a>
151+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.connect_lsp">API docs</a>
152+
</h2>
144153

145154
When you have selected an LSP you may then connect to it:
146155

‎src/guide/failure_report.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Reporting payment failures
1+
<h1 id="reporting-payment-failures">
2+
<a class="header" href="#reporting-payment-failures">Reporting payment failures</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.report_issue">API docs</a>
4+
</h1>
25

36
While attempting to send payments it may be that sometimes payment failures occur. Reporting these issues through the Breez SDK will help us to improve LSP routing.
47

‎src/guide/fiat_currencies.md

+9-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Supporting fiat currencies
1+
<h1 id="supporting-fiat-currencies">
2+
<a class="header" href="#supporting-fiat-currencies">Supporting fiat currencies</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.list_fiat_currencies">API docs</a>
4+
</h1>
25

36
You can get the full details of supported fiat currencies, such as symbols and localized names:
47

@@ -68,6 +71,11 @@ You can get the full details of supported fiat currencies, such as symbols and l
6871
</section>
6972
</custom-tabs>
7073

74+
<h1 id="fetch-fiat-rates">
75+
<a class="header" href="#fetch-fiat-rates">Fetch fiat rates</a>
76+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.fetch_fiat_rates">API docs</a>
77+
</h1>
78+
7179
To get the current BTC rate in the various supported fiat currencies:
7280

7381
<custom-tabs category="lang">

‎src/guide/list_payments.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Listing payments
1+
<h1 id="listing-payments">
2+
<a class="header" href="#listing-payments">Listing payments</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.list_payments">API docs</a>
4+
</h1>
25

36
To view your payment history you can list and filter all the sent and received payments made.
47

‎src/guide/lnurl_auth.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# LNURL-Auth
1+
<h1 id="lnurl-auth">
2+
<a class="header" href="#lnurl-auth">LNURL-Auth</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.lnurl_auth">API docs</a>
4+
</h1>
25

36
## Usage
47

‎src/guide/lnurl_pay.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# LNURL-Pay
1+
<h1 id="lnurl-pay">
2+
<a class="header" href="#lnurl-pay">LNURL-Pay</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.lnurl_pay">API docs</a>
4+
</h1>
25

36
## Usage
47

‎src/guide/lnurl_withdraw.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# LNURL-Withdraw
1+
<h1 id="lnurl-withdraw">
2+
<a class="header" href="#lnurl-withdraw">LNURL-Withdraw</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.lnurl_withdraw">API docs</a>
4+
</h1>
25

36
## Usage
47

‎src/guide/logging.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Adding logging
1+
<h1 id="adding-logging">
2+
<a class="header" href="#adding-logging">Adding logging</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.init_logging">API docs</a>
4+
</h1>
25

36
Breez SDK implements detailed logging via a streaming interface you can manage within your application. The log entries are split into several levels that you can filter and store as desired within your application, for example, by appending them to a log file.
47

‎src/guide/messages.md

+8-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@
22

33
Through signing and verifying messages we can provide proof that a digital signature was created by a private key.
44

5-
## Signing a message
5+
<h2 id="signing-a-message">
6+
<a class="header" href="#signing-a-message">Signing a message</a>
7+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.sign_message">API docs</a>
8+
</h2>
69

710
By signing a message using the SDK we can provide a digital signature. Anyone with the `message`, `pubkey` and `signature` can verify the signature was created by the private key of this pubkey.
811

@@ -72,7 +75,10 @@ By signing a message using the SDK we can provide a digital signature. Anyone wi
7275
</section>
7376
</custom-tabs>
7477

75-
## Verifying a message
78+
<h2 id="verifying-a-message">
79+
<a class="header" href="#verifying-a-message">Verifying a message</a>
80+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.check_message">API docs</a>
81+
</h2>
7682

7783
You can prove control of a private key by verifying a `message` with it's `signature` and `pubkey`.
7884

‎src/guide/node_state.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Getting the node state
1+
<h1 id="getting-the-node-state">
2+
<a class="header" href="#getting-the-node-state">Getting the node state</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.node_info">API docs</a>
4+
</h1>
25

36
At any point we can fetch our balance from the node and check the lightning and onchain balances.
47

‎src/guide/pay_onchain.md

+19-6
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
1-
# Sending an on-chain transaction (Swap-Out)
1+
# Sending an on-chain transaction
22

33
You can send funds from the Breez SDK wallet to an on-chain address as follows.
44

5-
## Checking the limits
5+
<h2 id="checking-the-limits">
6+
<a class="header" href="#checking-the-limits">Checking the limits</a>
7+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.onchain_payment_limits">API docs</a>
8+
</h2>
9+
610
First, fetch the current reverse swap limits:
711

812
<custom-tabs category="lang">
@@ -81,7 +85,11 @@ It is best to fetch these limits just before your app shows the Pay Onchain (rev
8185

8286
</div>
8387

84-
## Preparing to send, checking fees
88+
<h2 id="preparing-to-send-checking-fees">
89+
<a class="header" href="#preparing-to-send-checking-fees">Preparing to send, checking fees</a>
90+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.prepare_onchain_payment">API docs</a>
91+
</h2>
92+
8593
The next step is to get an overview of the exact amount that will be sent, the amount that will be received, and the fees.
8694

8795
There are two ways to do this:
@@ -160,8 +168,10 @@ If instead you'd like to specify the recipient amount, simply change the `SwapAm
160168

161169
In case you want to drain your channels and send the maximum amount possible, you can use the above snippet with `amount_sat` set to `current_limits.max_sat` and `amount_type` as `Send`.
162170

163-
164-
## Executing the Swap
171+
<h2 id="executing-the-swap">
172+
<a class="header" href="#executing-the-swap">Executing the Swap</a>
173+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.pay_onchain">API docs</a>
174+
</h2>
165175

166176
Once you checked the amounts and the fees are acceptable, you can continue with sending the payment.
167177

@@ -237,7 +247,10 @@ Starting the onchain payment (reverse swap) will trigger a HODL invoice payment,
237247
This means you will see an outgoing pending payment in your list of payments, which locks those funds until the invoice
238248
is either settled or cancelled. This will happen automatically at the end of the reverse swap.
239249

240-
## List in-progress Swaps
250+
<h2 id="list-in-progress-swaps">
251+
<a class="header" href="#list-in-progress-swaps">List in-progress Swaps</a>
252+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.in_progress_onchain_payments">API docs</a>
253+
</h2>
241254

242255
You can check the ongoing onchain payments (reverse swaps) and their status with:
243256

‎src/guide/payment_metadata.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Adding and filtering for payment metadata
1+
<h1 id="adding-and-filtering-for-payment-metadata">
2+
<a class="header" href="#adding-and-filtering-for-payment-metadata">Adding and filtering for payment metadata</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.set_payment_metadata">API docs</a>
4+
</h1>
25

36
## Usage
47

‎src/guide/receive_onchain.md

+25-6
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Receiving an on-chain transaction (Swap-In)
1+
<h1 id="receiving-an-on-chain-transaction">
2+
<a class="header" href="#receiving-an-on-chain-transaction">Receiving an on-chain transaction</a>
3+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.receive_onchain">API docs</a>
4+
</h1>
25

36
There are cases when you have funds in some bitcoin address and you would like to send those to your lightning node.
47

@@ -79,8 +82,10 @@ The `swap_info` above includes maximum and minimum limits. Your application's us
7982

8083
</div>
8184

82-
83-
## Get the in-progress Swap
85+
<h2 id="get-the-in-progress-swap">
86+
<a class="header" href="#get-the-in-progress-swap">Get the in-progress Swap</a>
87+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.in_progress_swap">API docs</a>
88+
</h2>
8489

8590
Once you've sent the funds to the above address, the SDK will monitor this address for unspent confirmed outputs and use a trustless submarine swap to receive these into your Lightning node. You can always monitor the status of the current in-progress swap using the following code:
8691

@@ -170,7 +175,10 @@ This means that, when the user performs a swap-in (receive onchain), the app wil
170175
- automatically complete the swap in the background when the onchain transaction is confirmed, even if the app is closed
171176
- display an OS notification, informing the user of the received funds
172177

173-
## Refund a Swap
178+
<h2 id="refund-a-swap">
179+
<a class="header" href="#refund-a-swap">Refund a Swap</a>
180+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.list_refundables">API docs</a>
181+
</h2>
174182

175183
In order to execute a refund, you need to supply an on-chain address to where the refunded amount will be sent. The following code will retrieve the refundable swaps:
176184

@@ -240,6 +248,11 @@ In order to execute a refund, you need to supply an on-chain address to where th
240248
</section>
241249
</custom-tabs>
242250

251+
<h2 id="execute-a-refund">
252+
<a class="header" href="#execute-a-refund">Execute a refund</a>
253+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.refund">API docs</a>
254+
</h2>
255+
243256
Once you have a refundable swap in hand, use the following code to execute a refund:
244257

245258
<custom-tabs category="lang">
@@ -315,7 +328,10 @@ A refund can be attempted several times. A common scenario where this is useful
315328

316329
</div>
317330

318-
# Rescanning swaps
331+
<h2 id="rescanning-swaps">
332+
<a class="header" href="#rescanning-swaps">Rescanning swaps</a>
333+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.rescan_swaps">API docs</a>
334+
</h2>
319335

320336
The SDK continuously monitors any ongoing swap transactions until they are either completed or refunded. Once one of these outcomes occurs, the SDK ceases its monitoring activities, and users are advised against sending additional funds to the swap address. However, if users inadvertently send additional funds to a swap address that was already used, the SDK won't automatically recognize it. In such cases, the SDK provides an option to manually scan the used swap addressed to identify additional transactions. This action allows the address to be included in the list eligible for refunds, enabling the initiation of a refund process. For the purpose of rescanning all historical swap addresses and updating their on-chain status, the following code can be used:
321337

@@ -385,7 +401,10 @@ The SDK continuously monitors any ongoing swap transactions until they are eithe
385401
</section>
386402
</custom-tabs>
387403

388-
# Calculating fees
404+
<h2 id="calculating-fees">
405+
<a class="header" href="#calculating-fees">Calculating fees</a>
406+
<a class="tag" target="_blank" href="https://breez.github.io/breez-sdk-greenlight/breez_sdk_core/struct.BreezServices.html#method.open_channel_fee">API docs</a>
407+
</h2>
389408

390409
When the amount to be received exceeds the inbound liquidity of the node, a new channel will be opened by the LSP in order for the node to receive it. This can checked by retrieving the NodeState from the SDK and comparing the inbound liquidity to the amount to be received. If the amount is greater or equal to the inbound liquidity, a new channel opening is required.
391410

0 commit comments

Comments
 (0)