";
// Collect signer data
let signer_data = signer.amp0_signer_data()?;
// Connect to AMP0
let amp0 = Amp0Connected::new(network, signer_data)?;
// Obtain and sign the authentication challenge
let challenge = amp0.get_challenge()?;
let sig = signer.amp0_sign_challenge(&challenge)?;
// Login
let mut amp0 = amp0.login(&sig)?;
// Create a new AMP0 account
let pointer = amp0.next_account()?;
let account_xpub = signer.amp0_account_xpub(pointer)?;
let amp_id = amp0.create_amp0_account(pointer, &account_xpub)?;
// Create watch only entries
amp0.create_watch_only(&username, &password)?;
// Use watch only credentials to interact with AMP0
let amp0 = Amp0::new(network, &username, &password, &_id)?;
```
#### Alternative setup
It's possible to setup an AMP0 account using GDK based apps:
1. [Blockstream App](https://blockstream.com/app/) (easiest, GUI, mobile, desktop, Jade support), or
2. [`green_cli`](https://github.com/Blockstream/green_cli/) (CLI, Jade support), or
3. [GDK](https://github.com/blockstream/gdk) directly (fastest, [example](https://github.com/blockstream/lwk/blob/master/docs/src/gdk-amp0.py))
### AMP0 daily operations
LWK allows to manage created AMP0 accounts.
You can receive funds, monitor transactions and send to other wallets.
#### Receive
To receive funds you need an address, you can get addresses with `Amp0::address()`.
β οΈ For AMP0 wallets, do not use Wollet::address() or WolletDescriptor::address(), using them can lead to loss of funds.
AMP0 server only monitors addresses that have been returned by the server.
If you send funds to an address that was not returned by the server, the AMP0 server will not cosign transactions spending that inputs.
Which means that those funds are lost (!), since AMP0 accounts are 2of2.
#### Monitor
LWK allows to monitor Liquid wallets, including AMP0 accounts.
First you get the AMP0 descriptor with `Amp0::wollet_descriptor()`.
You then create a wallet with `Wollet::new()`.
Once you have the AMP0 `Wollet`, you can get `Wollet::transactions()`, `Wollet::balance()` and other information.
LWK wallets needs to be updated with new data from the Liquid blockchain.
First create a blockchain client, for instance `EsploraClient::new()`.
Then get an update with `BlockchainBackend::full_scan_to_index()` passing the value returned by `Amp0::last_index()`.
Finally update the wallet with `Wollet::apply_update()`.
β οΈ For AMP0 wallets, do not sync the wallet with BlockchainBackend::full_scan(), otherwise some funds might not show up.
AMP0 accounts do not have the concept of GAP_LIMIT and they can have several unused addresses in a row.
The default scanning mechanism when it sees enough unused addresses in a row it stops.
So it can happen that some transactions are not returned, and the wallet balance could be incorrect.
#### Send
For AMP0 you can follow the standard LWK transaction flow, with few small differences.
Use the `TxBuilder`, add recipients `TxBuilder::add_recipient()`, and use the other available methods if needed.
Then instead of using `TxBuilder::finish()`, use `TxBuilder::finish_for_amp0()`.
This creates an `Amp0Pset` which contains the PSET and the `blinding_nonces`, some extra data needed by the AMP0 cosigner.
Now you need to interact with secret key material (π) corresponding to this AMP0 account.
Create a signer, using `SWSigner` or `Jade` and sign the PSET with the signer, using `Signer::sign()`.
Once the PSET is signed, you need to have it cosigned by AMP0.
Construct an `Amp0Pset` using the signed PSET and the `blinding_nonces` obtained before.
Call `Amp0::sign()` passing the signed `Amp0Pset`.
If all the AMP0 rules are respected, the transaction is cosigned by AMP0 and can be broadcast, e.g. with `EsploraClient::broadcast()`.
```rust
use lwk_common::Signer;
use lwk_signer::SwSigner;
use lwk_wollet::amp0::{blocking::Amp0, Amp0Pset};
use lwk_wollet::{clients::blocking::EsploraClient, Network, WolletBuilder};
// Signer
let mnemonic = "";
// AMP0 Watch-Only credentials
let username = "";
let password = "";
// AMP ID (optional)
let amp_id = "";
// Create AMP0 context
let network = Network::TestnetLiquid;
let mut amp0 = Amp0::new(network, username, password, amp_id)?;
// Create AMP0 Wollet
let wd = amp0.wollet_descriptor();
let mut wollet = WolletBuilder::new(Network::TestnetLiquid, wd).build()?;
// Get a new address
let addr = amp0.address(None);
// Update the wallet with (new) blockchain data
let url = "https://blockstream.info/liquidtestnet/api";
let mut client = EsploraClient::new(url, Network::TestnetLiquid)?;
if let Some(update) = client.full_scan_to_index(&wollet, amp0.last_index())? {
wollet.apply_update(update)?;
}
// Get balance
let balance = wollet.balance()?;
// Construct a PSET sending LBTC back to the wallet
let amp0pset = wollet
.tx_builder()
.drain_lbtc_wallet()
.finish_for_amp0()?;
let mut pset = amp0pset.pset().clone();
let blinding_nonces = amp0pset.blinding_nonces();
// User signs the PSET
let is_mainnet = false;
let signer = SwSigner::new(mnemonic, is_mainnet)?;
let sigs = signer.sign(&mut pset)?;
assert!(sigs > 0);
// Reconstruct the Amp0 PSET with the PSET signed by the user
let amp0pset = Amp0Pset::new(pset, blinding_nonces.to_vec())?;
// AMP0 signs
let tx = amp0.sign(&0pset)?;
// Broadcast the transaction
let txid = client.broadcast(&tx)?;
```
### Examples
We provide a few examples on how to use AMP0 with LWK:
* [liquidwebwallet.org](https://liquidwebwallet.org) integrates AMP0 using WASM
* Rust tests in [amp0.rs](https://github.com/blockstream/lwk/blob/master/lwk_wollet/src/amp0.rs)
---
## LiquiDEX
LiquiDEX is a 2-step atomic swap protocol for the Liquid Network that enables trustless peer-to-peer asset exchanges. It allows users to swap Liquid Bitcoin (LBTC) and other Liquid assets without requiring a trusted third party or centralized exchange.
### Overview
A LiquiDEX swap involves two parties:
- **Maker**: Creates a swap proposal offering to exchange one asset for another
- **Taker**: Accepts the proposal and completes the swap
The protocol uses an incomplete but signed transaction (unbalanced and without fees) created by the maker. The taker completes the transaction by adding inputs and outputs, balancing the amounts and adding fees. This ensures atomicity: either both parties get what they want, or the transaction cannot be broadcast.
The proposal always spend a full utxo, since there is no way to add change address for the **maker**.
### How It Works
1. **Maker creates a proposal**: The maker creates a PSET with one input (UTXO to be spent) and one output (the asset he want to receive). The transaction is signed but incomplete. The PSET is converted in a Liquid Proposal, a structure containing all the relevant information for the swap.
2. **Proposal validation**: The taker receives the proposal and validates it using primitives available in LWK.
3. **Taker completes the swap**: The taker recreate the PSET and adds inputs and outputs to balance the transaction, adds fees, and signs their part.
4. **Transaction broadcast**: The completed transaction is broadcast to the Liquid Network, executing the atomic swap.
### Key Concepts
#### LiquidexProposal
A `LiquidexProposal` represents a swap offer. It comes in two states:
- **Unvalidated**: The proposal has been created but not yet verified
- **Validated**: The proposal has been verified and is ready to be taken
### Creating a Swap Proposal (Maker)
The maker creates a swap proposal by building a transaction with `liquidex_make()`, signing it, and converting it to a proposal:
```rust
// LiquiDEX make
let addr = wallet_maker.address_result(None).address().clone();
let mut pset = wallet_maker
.tx_builder()
.liquidex_make(utxo_send, &addr, sats_recv, asset_recv)
.unwrap()
.finish()
.unwrap();
let details = wallet_maker.wollet.get_details(&pset).unwrap();
wallet_maker.sign(signer_maker, &mut pset);
let proposal = LiquidexProposal::from_pset(&pset).unwrap();
```
### Validating a Proposal (Taker)
Before accepting a proposal, the taker must validate it by fetching the previous transaction and verifying the proposal:
```rust
let txid = proposal.needed_tx().unwrap();
let tx = wallet_maker.wollet.transaction(&txid).unwrap().unwrap().tx;
let proposal = proposal.validate(tx).unwrap();
```
### Taking a Proposal (Taker)
Once validated, the taker can accept the proposal by using `liquidex_take()` to complete the transaction:
```rust
// LiquiDEX take
let mut pset = wallet_taker
.tx_builder()
.liquidex_take(vec![proposal])
.unwrap()
.finish()
.unwrap();
wallet_taker.sign(signer_taker, &mut pset);
let _txid = wallet_taker.send(&mut pset);
```
### Additional Resources
- [LiquiDEX Blog Post](https://blog.blockstream.com/liquidex-2-step-atomic-swaps-on-the-liquid-network/)
---
Previous: [Ledger](https://github.com/blockstream/lwk/blob/master/docs/src/ledger.md)
---
## BIP85
The [BIP85 specification](https://github.com/bitcoin/bips/blob/master/bip-0085.mediawiki) allows you to deterministically derive new BIP39 mnemonics from an existing mnemonic. This is useful for creating separate wallets or accounts while maintaining a single backup.
### Deriving a Mnemonic
To derive a BIP85 mnemonic, you need a software signer initialized with a mnemonic (hardware wallet-based signers are not supported at the moment). The derived mnemonic is obtained with `Signer::derive_bip85_mnemonic()`, which takes an `index` (0-based) and a `word_count` (12 or 24).
```rust
// Load mnemonic
let mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
// Create signer
let is_mainnet = false;
let signer = SwSigner::new(mnemonic, is_mainnet)?;
// Derive menmonics
let derived_0_12 = signer.derive_bip85_mnemonic(0, 12)?;
let derived_0_24 = signer.derive_bip85_mnemonic(0, 24)?;
let derived_1_12 = signer.derive_bip85_mnemonic(1, 12)?;
```
----
Next: [CLI](#cli)
---
## CLI
### LWK CLI
All LWK functions are exposed via a local JSON-RPC server that communicates with a CLI tool so you can see LWK in action.
This JSON-RPC Server also makes it easier to build your own frontend, GUI, or integration.
If you want to see an overview of LWK and a demo with the CLI tool check out this [video](https://community.liquid.net/c/videos/demo-liquid-wallet-kit-lwk)
#### Installing LWK_CLI from crates.io
```shell
cargo install lwk_cli
```
or if you want to connect Jade over serial:
```shell
cargo install lwk_cli --features serial
```
#### Building LWK_CLI from source
First you need [rust](https://www.rust-lang.org/tools/install), our MSRV is 1.85.0
then you can build from source:
```shell
git clone git@github.com:Blockstream/lwk.git
cd lwk
cargo install --path ./lwk_cli/
```
Or
```
cargo install --path ./lwk_cli/ --features serial
```
To enable connection with Jade over serial.
### Using LWK_CLI
Help will show available commands:
```shell
lwk_cli --help
```
Start the rpc server (default in Liquid Testnet)
and put it in background
```shell
lwk_cli server start
```
Every command requires the server running so open a new shell to run the client.
Create new BIP39 mnemonic for a software signer
```shell
lwk_cli signer generate
```
Load a software *signer* named `sw` from a given BIP39 mnemonic
```shell
lwk_cli signer load-software --signer sw --persist false --mnemonic "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
```
Create a p2wpkh *wallet* named `ss` (install [`jq`](https://github.com/jqlang/jq) or extract the descriptor manually)
```shell
DESC=$(lwk_cli signer singlesig-desc -signer sw --descriptor-blinding-key slip77 --kind wpkh | jq -r .descriptor)
lwk_cli wallet load --wallet ss -d $DESC
```
Get the wallet balance
```shell
lwk_cli wallet balance -w ss
```
If you have a Jade, you can plug it in and use it to create a
wallet and sign its transactions.
Probe connected Jades and prompt user to unlock it to get identifiers needed to load Jade on LWK
```shell
lwk_cli signer jade-id
```
Load Jade using returned ID
```shell
lwk_cli signer load-jade --signer --id
```
Get xpub from loaded Jade
```shell
lwk_cli signer xpub --signer --kind
```
When you're done, stop the rpc server.
```shell
lwk_cli server stop
```
---
## High-Volume Wallets
When the number of transactions grows significantly,
handling a wallet can become challenging.
To make it easier, LWK provides various utilities to handle high-volume wallets.
In this section we provide an overview.
You can use one, or combinations of them.
The approaches in this guide are complex or experimental.
Before trying them,
our first and most obvious suggestion is to increase the computing resources on your machine.
This might be the simplest approach, with little to none engineering overhead.
If this is not possible, or not enough consider applying one or more of the suggestions below.
### Transaction Batching
To reduce the number of transaction consider using a single transaction for multiple "send" operation (e.g. calling `add_recipient` multiple times).
In this way you can do a "batch send" with a single transaction.
### Rotate Wallets
Once a `Wollet` has too many transactions it might become impractical to use it,
it can become too slow or have unsustainable resource requirements.
A simple approach to avoid this is to rotate the wallet.
Once it reaches a certain number of transactions,
you stop using it and you start to use another.
Note that you don't need to generate another BIP39 mnemonic/seed.
You can use the same secret,
and use the next BIP32 account, just by bumping the index.
### Update Pruning
The largest component in memory and disk usage are Liquid transactions.
They are huge, and their largest part are rangeproofs.
Those are used when unblinding transactions,
but later they're not used anymore (unless in extremely particular cases).
You can remove them calling `Update::prune()` before applying and persisting the update.
### Merge Updates
Every time you get new transactions,
the `Wollet` fetches a new `Update` which is applied and (optionally) persisted.
These updates are sequential, the new one applies on top of the previous.
When the `Wollet` restarts,
it reads the `Update`s from where they were perstised and applies them to reconstruct the last `Wollet` state.
These `Update`s can become quite a lot and it could be useful to compact them.
One way it's to sync specifying another directory,
all transactions will be downloaded again,
and you will have a single compacted update.
However for large wallets, this might not be ideal.
For them we have `WolletBuilder::with_merge_thresold()`.
It allows to specify a threshold after which all updates are compacted into one.
### Waterfalls
If your wallet consists in a large number of scriptpubkeys,
using `Esplora` or `Electrum` will require a large number of network roundtrips to perform a full scan of the wallet.
If this is an issue for your setup,
consider using `Waterfalls` to fetch blockchain data.
`Waterfalls` is an optimized scriptpubkey/address data indexer that reduces server load, client load, network roundtrip.
Switching to it makes full scan faster.
This improvement comes with a trade off, the client shares with the Waterfalls server its descriptor (without the descriptor blinding key) revealing all the descriptor scriptpubkeys.
We think this trade off is reasonable,
moreover if you're using a self-hosted Waterfalls server, you have no downside.
### UTXO only mode
In some cases you don't care about all transactions,
and you just care about your UTXOs.
Having the UTXOs allows you to show the balance and construct transactions,
and often times this is enough.
For this case you can use "utxo only" mode.
You need to mark you `Wollet` as "utxo only" with `WolletBuilder::utxo_only()`,
and you need to use Waterfalls with a "utxo only" client (`EsploraClientBuilder::utxo_only()`).
Then automatically you will only download transactions that have an unspent output,
drastically reducing the network, memory and disk usage.
### Use `txs_store`
By default, transactions are stored in memory,
this allows to make operations such as return transactions list fast.
However for large wallets, they might saturate all the available memory of the host.
A possible solution is to use a `Store` for the transactions with `WolletBuilder::with_txs_store()`.
The store can be a file, multiple files, a database or something more complicated.
This can reduce the memory usage significantly,
however it could make operation such as getting all transactions slower.
---
## LWK Structure
LWK functionalities are split into different component crates that might be useful independently.
* [`lwk_cli`](https://github.com/blockstream/lwk/tree/master/lwk_cli): a CLI tool to use LWK wallets.
* [`lwk_wollet`](https://github.com/blockstream/lwk/tree/master/lwk_wollet): library for watch-only wallets;
specify a CT descriptor, generate new addresses, get balance,
create PSETs and other actions.
* [`lwk_signer`](https://github.com/blockstream/lwk/tree/master/lwk_signer): interact with Liquid signers
to get your PSETs signed.
* [`lwk_jade`](https://github.com/blockstream/lwk/tree/master/lwk_jade): unlock Jade, get xpubs,
register multisig wallets, sign PSETs and more.
* [`lwk_bindings`](https://github.com/blockstream/lwk/tree/master/lwk_bindings): use LWK from other languages.
* [`lwk_wasm`](https://github.com/blockstream/lwk/tree/master/lwk_wasm): use LWK from WebAssembly.
* and more:
common or ancillary components ([`lwk_common`](https://github.com/blockstream/lwk/tree/master/lwk_common),
[`lwk_rpc_model`](https://github.com/blockstream/lwk/tree/master/lwk_rpc_model), [`lwk_tiny_rpc`](../lwk_tiny_rpc),
[`lwk_app`](https://github.com/blockstream/lwk/tree/master/lwk_app)),
future improvements ([`lwk_hwi`](https://github.com/blockstream/lwk/tree/master/lwk_hwi)),
testing infrastructure ([`lwk_test_util`](https://github.com/blockstream/lwk/tree/master/lwk_test_util),
[`lwk_containers`](https://github.com/blockstream/lwk/tree/master/lwk_containers))
For instance, mobile app devs might be interested mainly in
`lwk_bindings`, `lwk_wollet` and `lwk_signer`.
While backend developers might want to directly use `lwk_cli`
in their systems.
Internal crate dependencies are shown in this diagram: an arrow indicates "depends on" (when dotted the dependency is feature-activated, when blue is a dev-dependency):
(generated with `cargo depgraph --workspace-only --dev-deps | dot -Tsvg > docs/src/dep-tree.svg`)
---
## Users of LWK
This section showcases a series of projects that are built on LWK or its components.
| Name | Description | Type | Language |
|-----------------|-----------------------|--------|----------|
|[Liquidtestnet.com](https://liquidtestnet.com)| Testnet Faucet| Server| Python|
|[Liquidwebwallet.org](https://liquidwebwallet.org)| Browser wallet| Wallet| Wasm|
|[AMP2](https://amp2.testnet.blockstream.com/info/spec)| Registered Assets| Server| Closed source|
|[Breeze SDK Liquid](https://github.com/breez/breez-sdk-liquid)| Lightning swaps| SDK| Rust|
|[Boltz](https://boltz.exchange/)| Atomic swaps| Server| Go|
|[Aqua](https://aqua.net/)| Atomic swaps| Wallet| Dart|
|[Bull Bitcoin](https://wallet.bullbitcoin.com/)| Atomic swaps| Wallet| Dart|
|[Blitz Wallet](https://blitz-wallet.com/)| Atomic swaps| Wallet| Javascript|
|[Peerswap](https://www.peerswap.dev/)| LN Balancing| Server| Go|
|[Banco Libre](https://bancolibre.com/)| Browser wallet| Wallet| Wasm|
|[Misty Breeze](https://breez.technology/)| Lightning wallet| Wallet| Dart|
|[Onion Mill - StashPay](https://blog.onionmill.com/)| Lightning wallet| Wallet| |
|[PSET GUI](https://github.com/dev4bitcoin/psetgui/)| PSET Analyzer| Tool| JavaScript|
|[Satsails](https://www.satsails.com/)| Wallet| Wallet| Dart|
|[Shopstr](https://shopstr.store/)| Nostr Marketplace| Server| TypeScript|
|[Ibis Wallet](https://github.com/aeonBTC/IbisWallet)| Atomic swaps| Wallet| Kotlin|
Feel free to open a PR to add or remove your product.
### Liquidtestnet.com
[Liquidtestnet.com](https://liquidtestnet.com) provides a several utilities to interact with Liquid testnet.
It also has a testnet faucet which distributes testnet assets (LBTC, standard assets and AMP0, AMP2 assets).
The faucet is built using LWK python wheels.
Liquidtestnet.com is open source, source available in the [Github repository](https://github.com/valerio-vaccaro/liquidtestnet.com).
### Liquidwebwallet.org
[Liquidwebwallet.org](https://liquidwebwallet.org) is a companion app for Liquid running in the browser.
The website allows the use of read-only wallets or hardware wallets such as Jade or Ledger to access one's wallet, view the balance, create transactions, create issuance, reissuance, and burn transactions.
The wallet is built using [LWK_wasm](https://www.npmjs.com/package/lwk_wasm).
Liquidwebwallet.org is open source, source available in the [Github repository](https://github.com/RCasatta/liquid-web-wallet)
### AMP2
[AMP2](https://amp2.testnet.blockstream.com/info/spec) is a platform able to issue and manage digital assets on the Liquid Network with flexible API.
The platform allows for the management of the entire token lifecycle, enabling the control and authorization of each individual operation.
AMP2 uses LWK internally.
AMP2 is closed source.
### Breeze SDK Liquid
The [Breeze SDK Liquid](https://github.com/breez/breez-sdk-liquid) provides developers with a end-to-end solution for integrating self-custodial Lightning payments into their apps and services.
The SDK use LWK as internal liquid wallet and signer.
Breeze SDK Liquid is open source, source available in the [Github repository](https://github.com/breez/breez-sdk-liquid)
### Boltz
[Boltz](https://boltz.exchange/) the Non-Custodial Bitcoin Bridge able to swap between different Bitcoin layers.
The SDK use LWK as internal liquid wallet and signer.
Boltz is open source, source available in the [Github repository](https://github.com/BoltzExchange/boltz-client)
### Aqua
[Aqua](https://aqua.net/) AQUA is a free, open-source wallet for iOS and Android.
The app use LWK in the backend.
Aqua is open source, source available in the [Github repository](https://github.com/AquaWallet/aqua-wallet)
### Bull Bitcoin
[Bull Bitcoin](https://wallet.bullbitcoin.com/) is a mobile wallet with Bitcoin, Liquid and lightning support.
Bull Bitcoin uses LWK for its Liquid wallet.
Bull Bitcoin is open source, source available in the [Github repository](https://github.com/SatoshiPortal/bullbitcoin-mobile)
### Blitz Wallet
[Blitz Wallet](https://blitz-wallet.com/) is a react native wallet.
The app is based on Breeze SDK Liquid.
Blitz Wallet is open source, source available in the [Github repository](https://github.com/BlitzWallet/BlitzWallet)
### Peerswap
[Peerswap](https://www.peerswap.dev/) Atomic swaps for rebalancing Lightning channels.
The app use LWK as internal liquid wallet and signer.
Peerswap is open source, source available in the [Github repository](https://github.com/ElementsProject/peerswap)
### Banco Libre
[Banco Libre](https://bancolibre.com/) is a web wallet using LWK_wasm.
The app use LWK_wasm as internal liquid wallet and signer.
Banco Libre is open source, source available in the [Github repository](https://github.com/kipu-org/banco-client)
### Misty Breeze
[Misty Breeze](https://breez.technology/) is a flutter app based on Breez SDK Liquid.
The app is based on Breeze SDK Liquid.
Misty Breeze is open source, source available in the [Github repository](https://github.com/breez/misty-breez)
### Onion Mill - StashPay
[Onion Mill - StashPay](https://blog.onionmill.com/) is a minimalist Bitcoin wallet based on Breeze SDK Liquid.
The app is based on Breeze SDK Liquid.
Onion Mill - StashPay is open source, source available in the [Github repository](https://github.com/onionmill/stashpay-bin)
### PSET GUI
[PSET GUI](https://github.com/dev4bitcoin/psetgui/) is a user-friendly application designed for analyzing and signing PSETs.
The app use LWK_wasm as internal liquid wallet and signer.
PSET GUI is open source, source available in the [Github repository](https://github.com/dev4bitcoin/psetgui/)
### Satsails
[Satsails](https://www.satsails.com/) is a self-custodial Bitcoin and Liquid wallet with support for stablecoins.
The app use LWK_wasm as internal liquid wallet and signer.
Satsails is open source, source available in the [Github repository](https://github.com/Satsails/Satsails)
### Shopstr
[Shopstr](https://shopstr.store/) is a global, permissionless Nostr marketplace for Bitcoin commerce.
WIP for [Liquid integration](https://github.com/shopstr-eng/shopstr/issues/74)
Shopstr is open source, source available in the [Github repository](https://github.com/shopstr-eng/)
### Ibis Wallet
A self-custody Bitcoin wallet for Android, inspired by Sparrow Wallet but built for mobile.
Ibis has support fo BTC (via BDK), LBTC and LN (via LWK and Boltz).
Ibis is open source, source available in the [Github repository](https://github.com/aeonBTC/IbisWallet)
### Unknown users
There may be many other users of the libraries who are currently unknown or not publicly disclosed
The libraries' license allows their integration into both open-source and closed-source solutions.These users can leverage lwk to:
- Develop wallets and online services for asset management,
- Create swap services,
- Issue, reissue, and burn assets.
---
## LWK History
BEWallet was [originally](https://github.com/LeoComandini/BEWallet/)
an Elements/Liquid wallet library written in Rust to develop
prototypes and experiments.
BEWallet was based on [Blockstream's GDK](https://github.com/Blockstream/gdk).
Essentially some GDK Rust pieces were moved to this project.
This was used as the starting point for the Liquid Wallet Kit project.
Parts that were not necessary have been dropped,
many things have been polished, and new features have been added.
The codebase has been entirely re-written, and now it has
almost no similarity with the original code.
---
## C#
### Examples
C# bindings use dotnet SDK 6.0, they are very immature at the moment:
- They use a uniffi bindings generator from a [third party](https://github.com/NordSecurity/uniffi-bindgen-cs) which didn't yet ship for uniffi 0.28
- It's currently tested only in linux
- The dynamic library is referenced in a non-standard way
* [List transactions](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/list_transactions.cs) of a wpkh/slip77 wallet
---
## LWK Demo
In this demo we will display some of the capabilities of **LWK**,
using `lwk_cli`.
### Multisig wallet creation:
* start a local LWK server
* create a software signer
* load a Jade signer
* create a 2of2 multisig wallet with the software signer and Jade
* get an address
### Issuance using the multisig wallet:
* receive some funds
* create a PSET issuing an asset
* sign it with the software signer
* sign it with Jade
* combine the PSETs
* broadcast the transaction
This is the [unblinded issuance transaction](https://blockstream.info/liquidtestnet/tx/8ac20c80b115f202c03a3110f1b0a826c4ed9a91f0c09cd246e0bccdbfab914e#blinded=100000,144c654344aa716d6f3abcc1ca90e5641e4e2a7f633bc09fe3baf64585819a49,eb72bab75085ab5861ac6e280977fdeb6c3c1c5f92af6a75bb6542c74d7c48fc,7804a46eb345dabbf136817e972cdacbbfe69f9641b09a3110d53e6b6f43ccf3,10,eeb2284be710e22b732416e9694e461c94da3208d4e1be7574295cd754dd766f,cf5840ee706fd12057479814ed68aa0607f1c0eb08ec2ab98640e3f806199705,df5b53c9ceff78595eaecbad828bdbc26296b08b59a7c49b86ee1ef75c28d4b5,1,fb6bd60cb0d5b91c1f41011d90f188cef9ecd61c306376b4fa61ba244874bf46,2bb129e283b713626942a6e0e2dec2c6b58d8e313ee1ebafa19964f5d55dd41b,cc94d5e59f7f1a57199d35659cbc4d91369c798eef9cb5b6c5d8ed0df9939262,99613,144c654344aa716d6f3abcc1ca90e5641e4e2a7f633bc09fe3baf64585819a49,be5a56fcb0983c32f559e9ea2a5915fd0b42bbd1e234b825638a10124f254a36,59fbe4dead525c8ca428a6cad5048a78b9d260cb26f45bcb8b2505cbee5e4549):
---
## Docs
To generate documentation you can use
```
RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features --no-deps --open
```
---
## Kotlin
### Build
Create Kotlin Multiplatform bindings
```shell
just kotlin-multiplatform
```
### Examples
* [List transactions](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/list_transactions.kts) of a wpkh/slip77 wallet
---
## Nix
We provide a flake for a dev environment and for running the `lwk_cli`.
If you use direnv and allow the `.envrc` the dev environment is automatically loaded
as soon as you enter the directory, otherwise you can run:
```
nix develop
```
To run `lwk_cli` on nix-enabled system:
```
nix run github:blockstream/lwk
```
---
## Python
### Install from PyPI
```shell
pip install lwk
```
### Build wheel
First, create a virtual env, skip the step if you already created it.
```shell
cd lwk/lwk_bindings
virtualenv venv
source venv/bin/activate
pip install maturin maturin[patchelf] uniffi-bindgen
```
Then build the wheel
```shell
cd lwk/lwk_bindings
maturin develop
```
Try it (note there is still an issue in how we import the package when using the wheel):
```python
import lwk
str(lwk.Network.mainnet())
```
### Examples
* [List transactions](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/list_transactions.py) of a wpkh/slip77 wallet, also compute the UTXO only balance
* [Send transaction](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/send_transaction.py) of a wpkh/slip77 wallet in a regtest environment
* [Send asset](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/send_asset.py) of a wpkh/slip77 wallet in a regtest environment
* [Issue a Liquid asset](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/issue_asset.py)
* [Custom persister](../lwk_bindings/tests/bindings/custom_persister.py), the caller code provide how the wallet updates are persisted
* [AMP0](../lwk_bindings/tests/bindings/amp0.py) demonstrates Asset Management Platform version 0 integration
* [AMP2](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/amp2.py) demonstrates Asset Management Platform protocol integration
* [External unblinding](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/external_unblind.py) shows how to unblind transaction data externally
* [LiquiDEX](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/liquidex.py) demonstrates Liquid decentralized swap functionality
* [Manual coin selection](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/manual_coin_selection.py) shows how to manually select coins for transactions
* [Multisig](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/multisig.py) demonstrates multisignature wallet setup and usage
* [PSET details](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/pset_details.py) shows how to inspect and work with Partially Signed Elements Transactions
* [Authenticated Esplora](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/authenticated_esplora_client.py) connects to an authenticated Esplora/Waterfalls backend using OAuth2, a static token, or custom headers
---
## Rust
### Build
You can build all crates with:
```shell
cargo build
```
Or you can build a single crate with:
```shell
cargo build -p lwk_wollet
```
### Examples
* [Create a testnet watch-only wallet from a CT wallet descriptor and get list of transactions](https://github.com/blockstream/lwk/blob/master/lwk_wollet/examples/list_transactions.rs)
* Documentation for all Rust crates is available at [docs.rs](https://docs.rs/releases/search?query=lwk)
---
## Swift
### Examples
* [List transactions](https://github.com/blockstream/lwk/blob/master/lwk_bindings/tests/bindings/list_transactions.swift) of a wpkh/slip77 wallet
---
## Tests
Run unit tests:
```shell
cargo test --lib
```
End-to-end tests need some local servers:
```shell
./context/download_bins.sh # needed once unless server binaries changes
. .envrc # not needed if you use direnv and you executed `direnv allow`
```
And also the following docker images:
```shell
docker pull xenoky/local-jade-emulator:1.0.27
docker pull tulipan81/blind_pin_server:v0.0.7
```
Note: Failed test executions can leave docker containers running. To stop all running containers run:
```shell
docker stop $(docker ps -a -q)
```
To run end-to-end tests:
```shell
cargo test
```
To see log outputs use `RUST_LOG` for example
```shell
RUST_LOG=info cargo test -- test_name
RUST_LOG=jade=debug cargo test -- test_name # filter only on specific module
```
#### Test with a physical Jade
Tests using Jade over serial (via USB cable) need an additional dependency:
```shell
apt install -y libudev-dev
```
These serial tests cannot be executed in parallel, so we need the `--test-threads 1` flag.
```shell
cargo test -p lwk_jade --features serial -- serial --include-ignored --test-threads 1
cargo test -p lwk_wollet --features serial -- serial --include-ignored --test-threads 1
```
---
## WASM
We currently provide preliminary support but are committed to continue working on this to have a fully featured LWK working on WASM environments.
[See these instructions to try out LWK on WASM](https://github.com/blockstream/lwk/tree/master/lwk_wasm)