Configuration

Bark uses a configuration file (config.toml) and supports environment variables for flexible setup across different networks and backends.

Configuration File

The configuration file is located at $DATADIR/config.toml (default: ~/.bark/config.toml).

File Structure

config.toml

server_address = "https://ark.signet.2nd.dev"
esplora_address = "https://esplora.signet.2nd.dev/"

# Optional: Use bitcoind instead of esplora
# bitcoind_address = "http://127.0.0.1:38332"
# bitcoind_cookiefile = "/path/to/.cookie"
# Or use user/pass:
# bitcoind_user = "rpcuser"
# bitcoind_pass = "rpcpassword"

# VTXO refresh threshold in blocks (default: 144 for mainnet, 12 for testnet)
vtxo_refresh_expiry_threshold = 12

# Safety margin for exits in blocks (default: 12)
vtxo_exit_margin = 12

# HTLC receive claim delta in blocks (default: 18)
htlc_recv_claim_delta = 18

# Fallback fee rate in sat/kWu (optional)
# Example for 1 sat/vB: 250
fallback_fee_rate = 250

# Required confirmations for round tx (default: 6 for mainnet, 1 for testnet)
round_tx_required_confirmations = 1

Configuration Options

Required Options

`server_address`

The address of your Ark server.

Type: String (URL)
Required: Yes
Example: "https://ark.signet.2nd.dev"

Chain Source

You must configure either esplora_address or bitcoind_address.

Using Esplora

esplora_address = "https://esplora.signet.2nd.dev"

Type: String (URL)
Use case: Easiest setup, no local node required
Networks: Mainnet, Signet, Mutinynet

Using Bitcoind

bitcoind_address = "http://127.0.0.1:38332"
bitcoind_cookiefile = "/home/user/.bitcoin/signet/.cookie"

Or with user/pass:

bitcoind_address = "http://127.0.0.1:18443"
bitcoind_user = "rpcuser"
bitcoind_pass = "rpcpassword"

Type: String (URL)
Authentication: Cookie file or user/pass required
Use case: Full node control, privacy

Optional Options

`vtxo_refresh_expiry_threshold`

The number of blocks before expiration to refresh VTXOs.

Type: Integer (block height)
Default: 144 (24h) for mainnet, 12 for testnets
Example: 12

When VTXOs are within this many blocks of expiration, they will be refreshed automatically during maintenance or when manually triggered.

`vtxo_exit_margin`

An upper limit of the number of blocks needed to safely exit VTXOs.

Type: Integer (block delta)
Default: 12
Example: 12

This is a safety buffer for unilateral exits.

`htlc_recv_claim_delta`

The number of blocks to claim a HTLC-recv VTXO.

Type: Integer (block delta)
Default: 18
Example: 18

Used for Lightning payment timelock configuration.

`fallback_fee_rate`

A fallback fee rate to use (in sat/kWu) when fee estimation fails.

Type: Integer (sat/kWu)
Default: None for mainnet, 250 (1 sat/vB) for testnets
Example: 250 (1 sat/vB), 500 (2 sat/vB)

Conversion: sat/vB * 250 = sat/kWu

`round_tx_required_confirmations`

The number of confirmations required before considering a round tx fully confirmed.

Type: Integer (confirmations)
Default: 6 for mainnet, 1 for testnets
Example: 1

Network Defaults

Bark uses network-specific defaults:

Mainnet

vtxo_refresh_expiry_threshold = 144  # 24 hours
round_tx_required_confirmations = 6
# No fallback fee rate (rely on network estimates)

Testnets (Signet, Mutinynet, Regtest)

vtxo_refresh_expiry_threshold = 12   # 2 hours
round_tx_required_confirmations = 1
fallback_fee_rate = 250              # 1 sat/vB

Configuration Priority

Configuration values are loaded in the following priority order (highest to lowest):

Environment variables with BARK_ prefix
Config file values (config.toml)
Network defaults (mainnet vs testnet)

Example:

# Config file has: esplora_address = "https://esplora.signet.2nd.dev"
# Environment variable overrides:
export BARK_ESPLORA_ADDRESS="https://custom-esplora.example.com"
bark balance
# Uses the environment variable value

Environment Variables

Global Options

Variable	Description	CLI Equivalent
`BARK_DATADIR`	Set the datadir path	`--datadir`
`BARK_VERBOSE`	Enable verbose logging	`-v, --verbose`
`BARK_QUIET`	Disable all terminal logging	`-q, --quiet`

Configuration Overrides

Variable	Description	Config Field
`BARK_SERVER_ADDRESS`	Ark server URL	`server_address`
`BARK_ESPLORA_ADDRESS`	Esplora server URL	`esplora_address`
`BARK_BITCOIND_ADDRESS`	Bitcoind RPC URL	`bitcoind_address`
`BARK_BITCOIND_COOKIEFILE`	Bitcoind cookie path	`bitcoind_cookiefile`
`BARK_BITCOIND_USER`	Bitcoind RPC user	`bitcoind_user`
`BARK_BITCOIND_PASS`	Bitcoind RPC password	`bitcoind_pass`
`BARK_FALLBACK_FEE_RATE`	Fallback fee rate	`fallback_fee_rate`

barkd Daemon Options

Variable	Description	CLI Equivalent
`BARKD_DATADIR`	Set the datadir path	`--datadir`
`BARKD_PORT`	Port to listen on	`--port`
`BARKD_HOST`	Host to bind to	`--host`
`BARK_VERBOSE`	Enable verbose logging	`-v`
`BARK_QUIET`	Disable console output	`-q`

Configuration Examples

Signet with Esplora

config.toml

server_address = "https://ark.signet.2nd.dev"
esplora_address = "https://esplora.signet.2nd.dev/"
vtxo_refresh_expiry_threshold = 12
fallback_fee_rate = 250
round_tx_required_confirmations = 1

Mainnet with Bitcoind

config.toml

server_address = "https://ark.example.com"
bitcoind_address = "http://127.0.0.1:8332"
bitcoind_cookiefile = "/home/user/.bitcoin/.cookie"
vtxo_refresh_expiry_threshold = 144
vtxo_exit_margin = 12
htlc_recv_claim_delta = 18
round_tx_required_confirmations = 6

Regtest with Bitcoind User/Pass

config.toml

server_address = "http://127.0.0.1:3535"
bitcoind_address = "http://127.0.0.1:18443"
bitcoind_user = "rpcuser"
bitcoind_pass = "rpcpassword"
vtxo_refresh_expiry_threshold = 12
fallback_fee_rate = 250
round_tx_required_confirmations = 1

Mutinynet

config.toml

server_address = "https://ark.mutinynet.example.com"
esplora_address = "https://mutinynet.com/api"
vtxo_refresh_expiry_threshold = 12
fallback_fee_rate = 250
round_tx_required_confirmations = 1

Creating Configuration

Automatic Creation

When you create a wallet, bark automatically generates config.toml:

bark create --signet \
  --ark https://ark.signet.2nd.dev \
  --esplora https://esplora.signet.2nd.dev

This creates ~/.bark/config.toml with your settings.

Manual Creation

You can create the config file manually before running bark create:

mkdir -p ~/.bark
cat > ~/.bark/config.toml << 'EOF'
server_address = "https://ark.signet.2nd.dev"
esplora_address = "https://esplora.signet.2nd.dev/"
EOF

bark create --signet

Validation

View your configuration:

bark config

Example output:

{
  "server_address": "https://ark.signet.2nd.dev",
  "esplora_address": "https://esplora.signet.2nd.dev/",
  "bitcoind_address": null,
  "bitcoind_cookiefile": null,
  "bitcoind_user": null,
  "bitcoind_pass": null,
  "vtxo_refresh_expiry_threshold": 12,
  "vtxo_exit_margin": 12,
  "htlc_recv_claim_delta": 18,
  "fallback_fee_rate": "0.25 sat/vB",
  "round_tx_required_confirmations": 1
}

Data Directory Structure

The datadir contains all wallet data:

~/.bark/
├── config.toml        # Configuration file
├── mnemonic           # BIP39 seed phrase (12 words)
├── db.sqlite          # Wallet database
└── debug.log          # Debug logs

Permissions

Ensure proper file permissions:

chmod 700 ~/.bark
chmod 600 ~/.bark/mnemonic
chmod 600 ~/.bark/config.toml
chmod 600 ~/.bark/db.sqlite

Multiple Wallets

Run multiple wallets using different datadirs:

bark --datadir ~/.bark-signet balance

Updating Configuration

Modify Existing Config

Edit ~/.bark/config.toml directly:

nano ~/.bark/config.toml

Changes take effect immediately (no restart needed for CLI, restart required for barkd).

Switch Chain Source

Change from Esplora to Bitcoind:

# Edit config.toml
cp ~/.bark/config.toml ~/.bark/config.toml.bak
cat > ~/.bark/config.toml << 'EOF'
server_address = "https://ark.signet.2nd.dev"
bitcoind_address = "http://127.0.0.1:38332"
bitcoind_cookiefile = "/home/user/.bitcoin/signet/.cookie"
vtxo_refresh_expiry_threshold = 12
fallback_fee_rate = 250
round_tx_required_confirmations = 1
EOF

# Verify
bark config

Change Ark Server

# Edit config.toml
sed -i 's|server_address = ".*"|server_address = "https://new-ark-server.com"|' ~/.bark/config.toml

# Verify
bark config

Troubleshooting

Configuration Errors

If you see “error loading bark config file”:

Check TOML syntax:
```
cat ~/.bark/config.toml
```

Validate URLs:

curl https://ark.signet.2nd.dev
curl https://esplora.signet.2nd.dev/api/blocks/tip/height

Test bitcoind connection:
```
bitcoin-cli -signet getblockcount
```

Missing Chain Source

Error: “You need to provide a chain source using either —esplora or —bitcoind” Solution: Add one of:

esplora_address = "https://esplora.signet.2nd.dev"

bitcoind_address = "http://127.0.0.1:38332"
bitcoind_cookiefile = "/path/to/.cookie"

Bitcoind Authentication

Error: “When providing —bitcoind, you need to provide auth args as well” Solution: Add authentication:

# Option 1: Cookie file
bitcoind_cookiefile = "/home/user/.bitcoin/signet/.cookie"

# Option 2: User/pass
bitcoind_user = "rpcuser"
bitcoind_pass = "rpcpassword"

Network Mismatch

Error: “address is not valid for configured network” Solution: Ensure your wallet network matches the Ark server:

Signet wallet → Signet Ark server
Mainnet wallet → Mainnet Ark server
Regtest wallet → Regtest Ark server

Check wallet network:

bark config | grep -A5 server

Best Practices

Backup config and mnemonic: Store securely offline
Use environment variables for secrets: Don’t commit passwords to config files
Set appropriate refresh thresholds: Balance between transaction frequency and VTXO freshness
Use Esplora for simplicity: Unless you need full node privacy
Test configuration changes: Use bark config to verify before operations
Monitor logs: Check debug.log for connection issues
Keep fee rates current: Adjust fallback_fee_rate based on network conditions

Get Started

Core Concepts

Wallet Integration

CLI Tools

​Configuration File

​File Structure

​Configuration Options

​Required Options

​server_address

​Chain Source

Using Esplora

Using Bitcoind

​Optional Options

​vtxo_refresh_expiry_threshold

​vtxo_exit_margin

​htlc_recv_claim_delta

​fallback_fee_rate

​round_tx_required_confirmations

​Network Defaults

​Mainnet

​Testnets (Signet, Mutinynet, Regtest)

​Configuration Priority

​Environment Variables

​Global Options

​Configuration Overrides

​barkd Daemon Options

​Configuration Examples

​Signet with Esplora

​Mainnet with Bitcoind

​Regtest with Bitcoind User/Pass

​Mutinynet

​Creating Configuration

​Automatic Creation

​Manual Creation

​Validation

​Data Directory Structure

​Permissions

​Multiple Wallets

​Updating Configuration

​Modify Existing Config

​Switch Chain Source

​Change Ark Server

​Troubleshooting

​Configuration Errors

​Missing Chain Source

​Bitcoind Authentication

​Network Mismatch

​Best Practices

​See Also

Build docs developers (and LLMs) love

Configuration File

File Structure

Configuration Options

Required Options

`server_address`

Chain Source

Optional Options

`vtxo_refresh_expiry_threshold`

`vtxo_exit_margin`

`htlc_recv_claim_delta`

`fallback_fee_rate`

`round_tx_required_confirmations`

Network Defaults

Mainnet

Testnets (Signet, Mutinynet, Regtest)

Configuration Priority

Environment Variables

Global Options

Configuration Overrides

barkd Daemon Options

Configuration Examples

Signet with Esplora

Mainnet with Bitcoind

Regtest with Bitcoind User/Pass

Mutinynet

Creating Configuration

Automatic Creation

Manual Creation

Validation

Data Directory Structure

Permissions

Multiple Wallets

Updating Configuration

Modify Existing Config

Switch Chain Source

Change Ark Server

Troubleshooting

Configuration Errors

Missing Chain Source

Bitcoind Authentication

Network Mismatch

Best Practices

See Also