# 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