miscellaneous files

misc-aio/BTC_NODE_WALLET_CONFIGURATION.md

@@ -0,0 +1,169 @@
+# 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