lamassu-server/misc-aio/BTC_NODE_WALLET_CONFIGURATION.md

Bitcoin Node and Wallet Configuration Guide

Overview

The Lamassu server uses environment variables BTC_NODE_LOCATION and BTC_WALLET_LOCATION to control how it interacts with Bitcoin infrastructure. These variables determine whether Bitcoin node and wallet operations run locally or connect to remote services.

Configuration Values

Both variables accept two values:

• local - Run Bitcoin Core node/wallet on the same server as Lamassu
• remote - Connect to external Bitcoin Core node/wallet services

Valid Configuration Combinations

1. Local Node + Local Wallet ✅

BTC_NODE_LOCATION=local
BTC_WALLET_LOCATION=local

• Use case: Full local Bitcoin Core setup
• Requirements: Sufficient storage for blockchain, bandwidth for sync
• Security: Maximum control and security

2. Remote Node + Remote Wallet ✅

BTC_NODE_LOCATION=remote
BTC_WALLET_LOCATION=remote

• Use case: Fully hosted Bitcoin infrastructure
• Requirements: All remote connection variables (see below)
• Security: Depends on remote service trust

3. Remote Node + Local Wallet ✅

BTC_NODE_LOCATION=remote
BTC_WALLET_LOCATION=local

• Use case: Use remote blockchain data with local key management
• Requirements: Remote node connection variables
• Security: Local key control, remote blockchain dependency

4. Local Node + Remote Wallet ❌

BTC_NODE_LOCATION=local
BTC_WALLET_LOCATION=remote

• Status: FORBIDDEN by Lamassu validation
• Error: "It's not possible to use a remote wallet without using a remote node!"
• Reason: Remote wallet services need their own blockchain access

Required Environment Variables

For Remote Node Configurations

When BTC_NODE_LOCATION=remote:

BTC_NODE_HOST=<remote-node-ip>
BTC_NODE_PORT=<p2p-port>        # Usually 8333 for mainnet, 18333 for testnet

For Remote Wallet Configurations

When BTC_WALLET_LOCATION=remote:

BTC_NODE_RPC_HOST=<rpc-host>
BTC_NODE_RPC_PORT=<rpc-port>    # Usually 8332 for mainnet, 18332 for testnet
BTC_NODE_USER=<rpc-username>
BTC_NODE_PASSWORD=<rpc-password>

Environment Setup Scripts

Development Environment

File: packages/server/tools/build-dev-env.js

BTC_NODE_LOCATION=remote     // Avoid full blockchain sync
BTC_WALLET_LOCATION=local    // Local testing

Production Environment

File: packages/server/tools/build-prod-env.js

BTC_NODE_LOCATION=local      // Full control
BTC_WALLET_LOCATION=local    // Maximum security

Validation Logic

The configuration is validated in packages/server/lib/blockchain/install.js:

function isEnvironmentValid(crypto) {
  // Prevent remote wallet + local node
  if (isRemoteWallet(crypto) && !isRemoteNode(crypto))
    throw new Error(
      `Invalid environment setup for ${crypto.display}: It's not possible to use a remote wallet without using a remote node!`
    )
  
  // Validate required variables for each configuration...
}

Logic Breakdown

For BTC_NODE_LOCATION=remote + BTC_WALLET_LOCATION=local:

• isRemoteWallet(crypto) → false (wallet is local)
• !isRemoteNode(crypto) → false (node is remote, so !remote = false)
• false && false → false (validation passes)

Bitcoin Core Configuration Impact

The variables affect the generated bitcoin.conf:

Local Node Configuration

rpcuser=lamassuserver
rpcpassword=<generated>
server=1
rpcport=8333
bind=0.0.0.0:8332

Remote Node Configuration

rpcuser=lamassuserver  
rpcpassword=<generated>
server=1
rpcport=8333
bind=0.0.0.0:8332
connect=<BTC_NODE_HOST>:<BTC_NODE_PORT>  # Only connect to specified peer

Multi-Cryptocurrency Support

The same pattern applies to all supported cryptocurrencies:

• BCH_NODE_LOCATION / BCH_WALLET_LOCATION
• LTC_NODE_LOCATION / LTC_WALLET_LOCATION
• DASH_NODE_LOCATION / DASH_WALLET_LOCATION
• ZEC_NODE_LOCATION / ZEC_WALLET_LOCATION
• XMR_NODE_LOCATION / XMR_WALLET_LOCATION

Bitcoin Core Compatibility

These configurations align with standard Bitcoin Core functionality:

• Local Node + Local Wallet: Standard bitcoind with wallet enabled
• Remote Node + Remote Wallet: Client connecting to remote Bitcoin Core RPC
• Remote Node + Local Wallet: Local wallet connecting to remote node via RPC

The restriction on "Local Node + Remote Wallet" is a Lamassu design choice, not a Bitcoin protocol limitation.

Security Considerations

Configuration	Storage	Bandwidth	Security	Trust
Local + Local	High	High	Maximum	Self
Remote + Remote	Low	Low	Depends on service	Remote service
Remote + Local	Low	Medium	Keys local, blockchain remote	Remote node
Local + Remote	High	High	❌ Not allowed	N/A

Troubleshooting

Common Errors

1. "Environment variable BTC_NODE_LOCATION is not set!"

   • Solution: Set the required environment variable

2. "It's not possible to use a remote wallet without using a remote node!"

   • Solution: Use a valid configuration combination

3. Missing RPC connection variables

   • Solution: Set all required variables for remote configurations