Crate lwk

Crate lwk 

Source
Expand description

§Bindings

To generate bindings the projects use Mozilla uniffi giving support for: Kotlin, Swift, Python, Ruby and also third party support for Kotlin multiplatform, Go, C++, C# and Dart.

There is an architectural refactor already planned for the crates the bindings are created on, this initial version is for experimentation only, expect breaking changes in the API

Most of the rust types in this crate are wrappers on types in lwk_wollet and lwk_signer which satisfy uniffi requirements such as:

  • Methods on types support only &self, thus if the inner type needs mutability, it is usually enclosed in a std::sync::Mutex.
  • Returned values must be wrapped in std::sync::Arc so that there aren’t issue in memory management.

§Host & Requirements

Build supported on Mac and Linux.

Note the following commands requires some env var defined in ../context/env.sh. If you use direnv and allowed the .envrc file they are automatically evaluated when entering the dir, otherwise launch manually via . ./context/env.sh

For android build you need the NDK greater than r23 in ${PROJECT_DIR}/bin/android-ndk, if you already have it elsewhere just symlink your path.

Building bindings requires launching commands with many arguments, just tool is used for that. It’s a simple make-like tool, you can either install the tool or copy-paste the shell commands inside it.

§Python

§Examples

§Build Python wheel

First, create a virtual env, skip the step if you already created it.

cd lwk/lwk_bindings
virtualenv venv
source venv/bin/activate
pip install maturin maturin[patchelf] uniffi-bindgen==0.28.0

Then build the wheel

cd lwk/lwk_bindings
maturin develop

Try it (note there is still an issue in how we import the package when using the wheel):

import lwk
str(lwk.Network.mainnet())

§Publish Python wheel

Download 4 artifacts from github CI:

  • windows
  • linux
  • mac arm64
  • mac x86_64
$ twine upload *.whl

§Test

cargo test -p lwk_bindings --features foreign_bindings --test bindings -- py

Live environment

just python-env-bindings

§Kotlin Multiplatform

§Example

§Build

Build the Kotlin Multiplatform bindings (Android, iOS, and iOS Simulator) and generate the shared Kotlin sources:

just kotlin-multiplatform

§Swift

§Example

§C++

§Example

§Build

Install uniffi-bindgen-cpp:

uniffi-bindgen-cpp --git https://github.com/NordSecurity/uniffi-bindgen-cpp --rev f02896c3e9fdce2f374656a32c46ae14c0051a26

Build the bindings and generate the shared C++ sources:

cargo build --release -p lwk_bindings
mkdir cpp
cp target/release/liblwk.so cpp/
uniffi-bindgen-cpp --library cpp/liblwk.so --out-dir cpp

Import resources to your project:

  • LWK library (liblwk.so/dll/dylib)
  • lwk.hpp
  • lwk.cpp

Include lwk.cpp in source files of your project and link LWK library in project build.

§CI

C++ bindings are generated in CI artifacts:

  • LWK library in bindings_<platfrom> (for ex. bindings-x86_64-unknown-linux-gnu)
  • Source and header files bindings_interface_cpp

Re-exports§

pub use blockdata::address::Address;
pub use blockdata::address_result::AddressResult;
pub use blockdata::block_header::BlockHeader;
pub use blockdata::external_utxo::ExternalUtxo;
pub use blockdata::out_point::OutPoint;
pub use blockdata::script::Script;
pub use blockdata::transaction::Transaction;
pub use blockdata::tx_in::TxIn;
pub use blockdata::tx_out::TxOut;
pub use blockdata::tx_out_secrets::TxOutSecrets;
pub use blockdata::txid::Txid;
pub use blockdata::wallet_tx::WalletTx;
pub use blockdata::wallet_tx_out::WalletTxOut;

Modules§

blockdata
Elements block data.
types
In this module there are wrapper of existing foreign simple types that:

Structs§

AssetAmount
An asset identifier and an amount
Bip
wrapper over lwk_common::Bip
Bip21
A parsed Bitcoin BIP21 URI with optional parameters.
Bip321
A parsed Bitcoin BIP321 URI with optional parameters.
Bolt11Invoicelightning
Represents a syntactically and semantically correct lightning BOLT11 invoice.
BoltzSessionlightning
A session to pay and receive lightning payments.
Contract
Wrapper over lwk_wollet::Contract
CurrencyCode
Currency code as defined by ISO 4217
ElectrumClient
A client to issue TCP requests to an electrum server.
EsploraClient
A blockchain backend implementation based on the esplora HTTP API But can also use the waterfalls endpoint to speed up the scan if supported by the server.
EsploraClientBuilder
A builder for the EsploraClient
ForeignPersisterLink
An object to define persistency at the caller level
Issuance
The details of an issuance or reissuance
LightningPaymentlightning
Represents a lightning payment (bolt11 invoice or bolt12 offer)
LiquidBip21
Liquid BIP21 payment details
LoggingLinklightning
An object to define logging at the caller level
LwkTestEnv
Test environment
Mnemonic
Wrapper over bip39::Mnemonic
Network
The network of the elements blockchain.
Payment
A parsed payment category from a payment instruction string.
PosConfig
POS (Point of Sale) configuration for encoding/decoding
Precision
Wrapper over lwk_common::Precision
Pset
A Partially Signed Elements Transaction
PsetDetails
The details of a Partially Signed Elements Transaction:
PsetInput
PSET input
Signer
A Software signer, wrapper over lwk_signer::SwSigner
TxBuilder
Wrapper over lwk_wollet::TxBuilder
UnvalidatedLiquidexProposal
LiquiDEX swap proposal
Update
Wrapper over lwk_wollet::Update
ValidatedLiquidexProposal
Created by validating UnvalidatedLiquidexProposal via validate() or insecure_validate()
Wollet
A Watch-Only wallet, wrapper over lwk_wollet::Wollet
WolletDescriptor
The output descriptors, wrapper over lwk_wollet::WolletDescriptor

Enums§

Chain
see lwk_wollet::Chain
LogLevellightning
Log level for logging messages
LwkError
Possible errors emitted
PaymentKind
The kind/type of a payment category without the associated data

Traits§

ForeignPersister
An exported trait, useful for caller-defined persistence.
Logginglightning
An exported trait for handling logging messages.

Functions§

test_argssimplicity