169 lines
No EOL
5.2 KiB
Markdown
169 lines
No EOL
5.2 KiB
Markdown
# 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 ✅
|
|
```bash
|
|
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 ✅
|
|
```bash
|
|
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 ✅
|
|
```bash
|
|
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 ❌
|
|
```bash
|
|
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`:
|
|
```bash
|
|
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`:
|
|
```bash
|
|
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`
|
|
```javascript
|
|
BTC_NODE_LOCATION=remote // Avoid full blockchain sync
|
|
BTC_WALLET_LOCATION=local // Local testing
|
|
```
|
|
|
|
### Production Environment
|
|
File: `packages/server/tools/build-prod-env.js`
|
|
```javascript
|
|
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`:
|
|
|
|
```javascript
|
|
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
|
|
```conf
|
|
rpcuser=lamassuserver
|
|
rpcpassword=<generated>
|
|
server=1
|
|
rpcport=8333
|
|
bind=0.0.0.0:8332
|
|
```
|
|
|
|
### Remote Node Configuration
|
|
```conf
|
|
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 |