Crate lwk_wasm

Expand description

§Liquid Wallet Kit for WASM

This is only a proof of concept at the moment but we want to show our commitment to have the Liquid Wallet Kit working in the WASM environment.

Available as npm package.

For an example usage see the Liquid Web Wallet (source). Works as CT descriptor watch-only wallet or connected to a Jade.

§For LWK Library developers

To build the WASM library you need rust and wasm-pack installed

$ wasm-pack build --dev

To enable web-serial:

$ RUSTFLAGS="--cfg=web_sys_unstable_apis" wasm-pack build --dev --features serial

§For LWK library consumers (front-end developers)

Download the Liquid Web Wallet source

$ git clone https://github.com/RCasatta/liquid-web-wallet
$ npm install
$ npm run start

Open the browser at http://localhost:8080

§Test

$ cd lwk_wasm
$ wasm-pack test --firefox # or --chrome

Then open the browser at http://127.0.0.1:8000, open also the dev tools to see console messages and network requests.

To avoid requiring opening the browser the headless mode is possible.

Note the increased timeout specified via the env var, the 20s default one could be too low.

$ cd lwk_wasm
$ WASM_BINDGEN_TEST_TIMEOUT=60 wasm-pack test --firefox --headless

run specific test (note the double --)

$ wasm-pack test --firefox --headless -- -- balance_test_testnet

§Build NPM Package for release

Build rust crates in release mode, optimizing for space.

$ cd lwk_wasm/
$ RUSTFLAGS="--cfg=web_sys_unstable_apis" CARGO_PROFILE_RELEASE_OPT_LEVEL=z wasm-pack build --features serial

$ cd pkg
$ npm publish

§Build wasm lib for profiling

To analyze the generated wasm file to optimize for size, we want to follow the same optimization as release but we want to keep debug info to analyze the produced lib with function names.

$ cd lwk_wasm/
$ RUSTFLAGS="--cfg=web_sys_unstable_apis" CARGO_PROFILE_RELEASE_OPT_LEVEL=z CARGO_PROFILE_RELEASE_DEBUG=2 wasm-pack build --profiling --features serial

With twiggy is then possible to analyze the library:

twiggy top -n 10 pkg/lwk_wasm_bg.wasm

§Build for nodejs

$ cd lwk_wasm
$ RUSTFLAGS="--cfg=web_sys_unstable_apis" CARGO_PROFILE_RELEASE_OPT_LEVEL=z wasm-pack build --target nodejs --out-dir pkg_node -- --features serial

Rename the package to lwk_node so that we can publish it to npm.

sed -i 's/"lwk_wasm"/"lwk_node"/g' pkg_node/package.json

§Test node js examples

Requirement:

having built node pkg like shown in previous paragraph
having node and npm installed

cd lwk_wasm/tests/node
npm install
node network.js

§Javascript code conventions

§String

For object that have a string representation we implement std::fmt::Display and we expose them like that

#[wasm_bindgen(js_name = toString)]
pub fn to_string_js(&self) -> String {
    self.to_string()
}

§JSON

For objects that have a json representation, like the balance we provide a toJSON() method that must work when the caller use for example JSON.stringify(object) Unfortunately JSON.stringify cannot serialize big integers by default, thus we use string representation for BigInt.

§Entries

Since JSON doesn’t support BigInt some object expose also the js standard entries() method so that the following code is possible

const balance = wallet.balance();

// 1. Create a Map
const balanceMap = new Map(balance.entries());

// 2. Iterate directly in a for...of loop
for (const [currency, amount] of balance.entries()) {
  console.log(`${currency}: ${amount}`);
}

// 3. Convert to a plain object
const balanceObject = Object.fromEntries(balance.entries());

§Documentation

Documentation of this crate should not use link to rust types such as Transaction because they are not usable in end-user javascript packages. Many types are wrappers of types in lwk crates, in this cases we mostly duplicate the original documentation with context adjustment.

Structs§

Address: An Elements (Liquid) address
AddressResult: Value returned from asking an address to the wallet. Containing the confidential address and its derivation index (the last element in the derivation path)
Amp2: Context for actions interacting with Asset Management Platform version 2
Amp2Descriptor: An Asset Management Platform version 2 descriptor
AssetId: A valid asset identifier.
AssetIds: An ordered collection of asset identifiers.
AssetMeta: Data related to an asset in the registry:
Balance: A signed balance of assets, to represent a balance with negative values such as the results of a transaction from the perspective of a wallet.
Bip: The bip variant for a descriptor like specified in the bips (49, 84, 87)
BoltzSession: Wrapper over lwk_boltz::BoltzSession
BoltzSessionBuilder: Wrapper over lwk_boltz::BoltzSessionBuilder
Contract: A contract defining metadata of an asset such the name and the ticker
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.
ExchangeRates: Multiple exchange rates against BTC provided from various sources
Issuance: The details of an issuance or reissuance.
LightningPayment: Wrapper over lwk_boltz::LightningPayment
MagicRoutingHint: A struct representing a magic routing hint, with details on how to pay directly without using Boltz
Mnemonic: A mnemonic secret code used as a master secret for a bip39 wallet.
Network: The network of the elements blockchain such as mainnet, testnet or regtest.
OptionWalletTxOut: An optional wallet transaction output. Could be None when it’s not possible to unblind. It seems required by wasm_bindgen because we can’t return Vec<Option<WalletTxOut>>
OutPoint: A reference to a transaction output
PosConfig: POS (Point of Sale) configuration for encoding/decoding
Precision: Helper to convert satoshi values of an asset to the value with the given precision and viceversa.
PricesFetcher: Wrapper over lwk_wollet::PricesFetcher
PricesFetcherBuilder: Wrapper over lwk_wollet::PricesFetcherBuilder
Pset: Partially Signed Elements Transaction
PsetDetails: The details of a Partially Signed Elements Transaction:
Registry: A Registry, a repository to store and retrieve asset metadata, like the name or the ticker of an asset.
RegistryPost: The data to post to the registry to publish a contract for an asset id
Script: An Elements (Liquid) script
Signer: A Software signer.
Transaction: A Liquid transaction
TxBuilder: A transaction builder
TxOutSecrets: Contains unblinded information such as the asset and the value of a transaction output
Txid: A valid transaction identifier.
Update: An Update contains the delta of information to be applied to the wallet to reach the latest status. It’s created passing a reference to the wallet to the blockchain client
WalletTx: Value returned by asking transactions to the wallet. Contains details about a transaction from the perspective of the wallet, for example the net-balance of the transaction for the wallet.
WalletTxOut: Details of a wallet transaction output used in WalletTx
Wollet: A watch-only wallet defined by a CT descriptor.
WolletDescriptor: A wrapper that contains only the subset of CT descriptors handled by wollet
Xpub: An extended public key

Functions§

string_to_qr: Convert the given string to a QR code image uri

Crate lwk_wasm

Crate lwk_wasm Copy item path

§Liquid Wallet Kit for WASM

§For LWK Library developers

§For LWK library consumers (front-end developers)

§Test

§Build NPM Package for release

§Build wasm lib for profiling

§Build for nodejs

§Test node js examples

§Javascript code conventions

§String

§JSON

§Entries

§Documentation

Structs§

Functions§

Crate lwk_wasm