diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +book diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..1c27d9d --- /dev/null +++ b/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Roei Erez"] +language = "en" +multilingual = true +src = "src" +title = "Breez SDK" diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..e10b99d --- /dev/null +++ b/src/README.md @@ -0,0 +1 @@ +# Introduction diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..7204a0a --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,12 @@ +# Summary + +# API Overview + +- [Getting Started](guide/getting_started.md) +- [Payments](guide/payments.md) +- [Receive via Onchain](guide/recieve_onchain.md) +- [Lnurl](guide/lnurl.md) + - [Lnurl Pay](guide/lnurl_pay.md) + - [Lnurl Withdraw](guide/lnurl_withdraw.md) + - [Lnurl Auth](guide/lnurl_auth.md) +- [Send Onchain](guide/send_onchain.md) diff --git a/src/guide/getting_started.md b/src/guide/getting_started.md new file mode 100644 index 0000000..5f0ffb4 --- /dev/null +++ b/src/guide/getting_started.md @@ -0,0 +1,41 @@ +# Getting Started + +Connecting to your node is the first step before attempting to send and receive lightning payments. + +The SDK is implemented in rust and is made accessible to other languages using ffi binding. +Connecting to a node requires a seed (your master key) and credentials. The seed represents a bip39 mnemonics and the credentials are retrieved by registering a new node or recovering an existing one. + +## Registering a new node +```rust +let seed = ; +let credentials = BreezServices::register_node(Network::Bitcoin, seed).await?; +``` +## Recovering an existing node +```rust +let seed = ; +let credentials = BreezServices::register_node(Network::Bitcoin, seed).await?; +``` + +Once you got your credentials you should save them in a secure storage and then you are able to initialize the SDK and start using your node: + +## Initializing the SDK +```rust +// Create the default config +let config = BreezServices::default_config(EnvironmentType::Production) + +// Customize the config object according to your needs +config.api_key = Some("your API key".into()); +config.working_dir = "path to an existing directory".into(); + +let sdk = BreezServices::init_services( + config, + seed.to_vec(), + credentials.clone(), + Box::new(AppEventListener {}), + ) + .await?; + +BreezServices::start(rt(), &sdk).await?; +``` + +Now your node is ready to receive payments. \ No newline at end of file diff --git a/src/guide/lnurl.md b/src/guide/lnurl.md new file mode 100644 index 0000000..9d04b53 --- /dev/null +++ b/src/guide/lnurl.md @@ -0,0 +1 @@ +# Lnurl diff --git a/src/guide/lnurl_auth.md b/src/guide/lnurl_auth.md new file mode 100644 index 0000000..eff0ef8 --- /dev/null +++ b/src/guide/lnurl_auth.md @@ -0,0 +1 @@ +# Lnurl Auth diff --git a/src/guide/lnurl_pay.md b/src/guide/lnurl_pay.md new file mode 100644 index 0000000..79e428c --- /dev/null +++ b/src/guide/lnurl_pay.md @@ -0,0 +1 @@ +# Lnurl Pay diff --git a/src/guide/lnurl_withdraw.md b/src/guide/lnurl_withdraw.md new file mode 100644 index 0000000..874432e --- /dev/null +++ b/src/guide/lnurl_withdraw.md @@ -0,0 +1 @@ +# Lnurl Withdraw diff --git a/src/guide/payments.md b/src/guide/payments.md new file mode 100644 index 0000000..7f5670a --- /dev/null +++ b/src/guide/payments.md @@ -0,0 +1,24 @@ +# Payments + +## Receiving Lightning Payments +Breez SDK doesn't require you to open a channel and set up your inbound liquidity. at this stage your node should already be connected to the LSP peer and you can use the follwing code to receive payments: + +```rust +let invoice = sdk.receive_payment(3000, "Invoice for 3000 sats".into()).await?; +``` + +The above will create an invoice that is ready to be paid. +Once this invoice is paid the LSP connected to your node will open a JIT (just in time) channel to your node and forward the amount minus some setup fee. + +## Sending Lightning Payments +```rust +let bolt11 = "..."; +sdk.send_payment(bolt11.into(), Some(3000)).await?; +``` + +## Sending Spontaneus Lightning Payments +```rust +let node_id = "..."; +sdk.send_payment(node_id.into(), Some(3000)).await?; +``` + diff --git a/src/guide/recieve_onchain.md b/src/guide/recieve_onchain.md new file mode 100644 index 0000000..ebb009e --- /dev/null +++ b/src/guide/recieve_onchain.md @@ -0,0 +1,35 @@ +# Receive via Onchain +There are cases when you have funds in some bitcoin address and you would like to send those to your lightning node. + +```rust +let swap_info = sdk.receive_onchain().await?; + +// Send your funds to the bellow bitcoin address +let address = swap_info.bitcoin_address; +``` + +Once you send the funds to the above address the SDK will monitor this address for unspent confirmed outputs and use a trustless submarine swap process to receive these into your lightning node. +You can always monitor the status of the current in progress swap using the follwing code: + +```rust +let swap_info = sdk.in_progress_swap().await? +``` + +The process of receiving via onchain address is trustless and uses submarine swap. this means there are two ways to spend the sent funds: +1. Either by a preimage that is exposed when the lightning payment is completed - This is the positive case where the swap was succesfull. +2. Or by your node when the swap didn't complete in a certiain timeout - This is the negative case where your node will execute a refund. + +In order to execute a refund you need to supply an onchain address to where the refunded amount will be sent to. +The following code will retrieve the refundable swaps: + +```rust +let refundables = sdk.list_refundables().await? +``` + +Once you have a refundable swap in hand, use the follwing code to execute a refund: + +```rust +let destination_address = "...".into() +let sat_per_byte = +sdk.refund(refundable.bitcoin_address, destination_address, sat_per_byte).await? +``` diff --git a/src/guide/send_onchain.md b/src/guide/send_onchain.md new file mode 100644 index 0000000..be3b5d8 --- /dev/null +++ b/src/guide/send_onchain.md @@ -0,0 +1 @@ +# Send Onchain