node-red-contrib-lwk

Node-RED nodes for Liquid Wallet Kit (LWK) integration.

Installation

npm install node-red-contrib-lwk

Configuration

Wallet Configuration Nodes

This package uses Wallet Configuration Nodes (similar to the Twitter node pattern) to manage wallet settings. Create wallet configuration nodes once and reuse them across multiple nodes.

Creating a Wallet Configuration

1. Add an LWK Wallet configuration node to your flow
2. Configure the wallet settings:
   • Name: A friendly name for this wallet configuration
   • Network: Select mainnet, testnet, or regtest
   • CT Descriptor: Optional watch-only wallet descriptor
   • Account Index: BIP44 account index (default: 0)
   • Mnemonic: Optional BIP39 mnemonic phrase (stored securely in credentials)
   • Client Type: Choose waterfalls (optimized HTTP) or electrum (TCP)
   • Server Provider: Choose blockstream or mempool.space (waterfalls server is used automatically)
   • Electrum URL: Optional Electrum server URL (only used when Client Type is electrum)
   • UTXO-Only Mode: When enabled, only fetches transactions with unspent outputs (faster but no full history)

Note: Either descriptor or mnemonic must be provided. If both are provided, descriptor takes precedence. If only mnemonic is provided, the descriptor will be automatically generated.

Using Wallet Configurations in Nodes

All LWK nodes allow you to select a wallet configuration:

1. Open any LWK node (e.g., Generate Address, Sync, Get Balance)
2. In the node configuration, select the wallet from the Wallet dropdown
3. The node will use that wallet's configuration

Important: Wallet instances are cached, so sync state (transactions, balance, UTXOs) persists across all nodes using the same wallet configuration.

Optional: Global Defaults (settings.js)

You can optionally set global defaults in Node-RED's settings.js file. These defaults are used as fallbacks when creating wallet configurations:

module.exports = {
  // ... other Node-RED settings ...
  
  lwk: {
    networkType: 'testnet',        // Default network
    clientType: 'waterfalls',      // Default client type
    electrumUrl: '',               // Default Electrum URL
    utxoOnly: false                // Default UTXO-only mode
  }
};

Note: These are only defaults. Each wallet configuration node can override these values.

Nodes

All nodes require selecting a wallet configuration node:

Core Wallet Operations

• lwk-wallet: Wallet configuration node (create this first)
• lwk-generate-address: Generate a new address for the wallet
• lwk-get-balance: Get the current wallet balance
• lwk-get-descriptor: Get the wallet descriptor
• lwk-sync: Synchronize wallet with blockchain (uses waterfalls endpoint for optimal performance)
• lwk-list-transactions: List all transactions in the wallet
• lwk-get-utxos: Get all unspent transaction outputs (UTXOs)

Transaction Operations

• lwk-create-transaction: Create an unsigned PSET (Partially Signed Elements Transaction)
• lwk-sign-pset: Sign a PSET using the mnemonic from the wallet configuration
• lwk-finalize-pset: Finalize a signed PSET into a broadcastable transaction
• lwk-decode-pset: Decode a PSET and return detailed information
• lwk-broadcast: Broadcast a finalized transaction to the Liquid network

Usage Examples

Basic Flow: Generate Address and Check Balance

1. Create an LWK Wallet configuration node:

   • Set Network to testnet
   • Enter your mnemonic (or descriptor)
   • Name it "My Test Wallet"

2. Add a Generate Address node:

   • Select "My Test Wallet" from the Wallet dropdown
   • Configure address index and chain (external/internal)

3. Add a Get Balance node:

   • Select the same "My Test Wallet" from the Wallet dropdown
   • Connect it to receive messages

4. Add a Sync node:

   • Select "My Test Wallet" from the Wallet dropdown
   • This will sync the wallet with the blockchain before checking balance

Transaction Flow: Create, Sign, and Broadcast

1. Create an LWK Wallet configuration node with a mnemonic (required for signing)

2. Create Transaction node:

   • Select your wallet
   • Input: msg.payload.recipient (address) and msg.payload.amount

3. Sign PSET node:

   • Select the same wallet (must have mnemonic configured)
   • Input: msg.payload.pset from Create Transaction node

4. Finalize PSET node:

   • Select the same wallet
   • Input: msg.payload.pset from Sign PSET node

5. Broadcast node:

   • Select the same wallet
   • Input: msg.payload.pset or msg.payload.hex from Finalize PSET node

Input/Output Format

Generate Address

Input: Any message (address index and chain can be overridden via msg.payload.index and msg.payload.chain)

Output:

{
  address: "VJL...",
  index: 0,
  chain: "external",
  scriptPubkey: "..."
}

Get Balance

Input: Any message

Output:

{
  balance: {
    "asset1": "1000000",
    "asset2": "500000"
  },
  balanceString: "1 asset1, 0.5 asset2"
}

Sync

Input: Any message

Output:

{
  synced: true,
  transactions: 5,
  balance: "1 asset1"
}

Create Transaction

Input:

{
  recipient: "VJL...",  // or address
  amount: "1000000",     // in satoshis
  assetId: "..."        // optional, defaults to network policy asset
}

Output:

{
  pset: "cHNidP8...",
  message: "PSET created. Use sign-pset action to sign it."
}

Sign PSET

Input:

{
  pset: "cHNidP8..."  // or psetString
}

Output:

{
  pset: "cHNidP8...",
  signed: true,
  message: "PSET signed. Use finalize-pset and broadcast actions to complete."
}

Finalize PSET

Input:

{
  pset: "cHNidP8..."  // or psetString
}

Output:

{
  txid: "...",
  hex: "01000000...",
  pset: "cHNidP8...",
  finalized: true
}

Broadcast

Input:

{
  hex: "01000000...",     // or transaction
  pset: "cHNidP8..."      // or psetString (will be finalized if hex not provided)
}

Output:

{
  txid: "...",
  broadcast: true
}

Network Configuration

Testnet (Default)

• Network: testnet
• Waterfalls URL: https://waterfalls.liquidwebwallet.org/liquidtestnet/api
• Use for testing and development

Mainnet

• Network: mainnet
• Waterfalls URL: https://waterfalls.liquidwebwallet.org/liquid/api
• Use for production with real funds

Regtest

• Network: regtest
• URL: http://localhost:3000/api
• Use for local development with a local Liquid node

Security Notes

1. Mnemonic Storage: Mnemonics are stored securely in Node-RED's credential system and are never exposed in flow files.

2. Multiple Wallets: You can create multiple wallet configuration nodes for different wallets or networks. Each wallet maintains its own cached state.

3. Wallet State Persistence: Wallet instances are cached, so sync state (transactions, balance, UTXOs) persists across all nodes using the same wallet configuration. This means:

   • Sync once, use balance/transactions in multiple nodes
   • State is shared across nodes using the same wallet config
   • State persists until Node-RED restarts or wallet config is updated

4. Never Commit Secrets: Never commit wallet configurations with real mnemonics to version control. Use Node-RED's credential system (which stores credentials separately from flow files).

Troubleshooting

"LWK Wallet configuration not selected"

• Make sure you've created an LWK Wallet configuration node
• Select the wallet in the node's configuration dialog

"Sync failed: endpoint not found"

• Check that the waterfalls server is accessible
• Verify the network type matches the URL (testnet vs mainnet)
• Ensure the wallet descriptor/mnemonic is valid

"Mnemonic required to sign PSET"

• Make sure the selected wallet configuration has a mnemonic set
• Mnemonics are stored in credentials, so check the wallet config node's credentials

Wallet state not updating

• Run the Sync node to update wallet state
• Wallet state is cached per wallet configuration
• Multiple nodes using the same wallet config share the same state

License

See LICENSE file for details.