github.com/arkade-os/arkd @v0.9.12
Chat with this repoWhat it actually does AI analysis from the code graph — generated when you open this
README
arkd
⚠️ IMPORTANT DISCLAIMER: ALPHA SOFTWARE
arkdis currently in alpha stage. This software is experimental and under active development. DO NOT ATTEMPT TO USE IN PRODUCTION. Use at your own risk.
What is arkd?
arkd is the server implementation of Arkade instance that builds on top of the Ark protocol, a Bitcoin scaling solution that enables fast, low-cost off-chain transactions while maintaining Bitcoin's security guarantees. As an Arkade Operator, the server:
- Creates and manages Batch Outputs through on-chain Bitcoin transactions
- Facilitates off-chain transactions between users
- Provides liquidity for commitment transactions (on-chain settlements that finalize each batch)
The Operator's role is designed with strict boundaries that ensure users always maintain control over their funds. This architecture allows for efficient transaction batching while preserving the trustless nature of Bitcoin.
Supported Networks and Wallets
arkd supports the following Bitcoin network:
* regtest
* testnet3
* signet
* mutinynet
* mainnet
and makes use of arkd-wallet, an on-chain wallet based on NBXplorer, as liquidity provider and optionally also as signer.
Usage Documentation
In this documentation, you'll learn how to install and use arkd, a Bitcoin server for off-chain Bitcoin transactions.
Installing from GitHub Releases
-
Download the latest
arkdbinary from the GitHub Releases page -
Make the binary executable:
sh chmod +x arkd -
Move the binary to a directory in your PATH (optional):
sh sudo mv arkd /usr/local/bin/
Configuration Options
The arkd server can be configured using environment variables and the admin settings API.
Environment Variables
| Environment Variable | Description | Default |
|---|---|---|
ARKD_DATADIR |
Directory to store data | App data directory |
ARKD_PORT |
Port (public) to listen on | 7070 |
ARKD_ADMIN_PORT |
Admin port (private) to listen on, fallback to service port if 0 | 7071 |
ARKD_ENABLE_CHANNELZ |
Expose gRPC channelz introspection; query via grpc_cli on the admin port |
false |
ARKD_LOG_LEVEL |
Logging level (0-6, where 6 is trace) | 4 (info) |
ARKD_SESSION_DURATION |
How long a batch session lasts (in seconds) before timing out once it started | 30 |
ARKD_DB_TYPE |
Database type (postgres, sqlite, badger) | postgres |
ARKD_PG_DB_URL |
Postgres connection url if ARKD_DB_TYPE is set to postgres |
- |
ARKD_EVENT_DB_TYPE |
Event database type (postgres, badger) | postgres |
ARKD_PG_EVENT_DB_URL |
Event database url if ARKD_EVENT_DB_TYPE is set to postgres |
- |
ARKD_PG_DB_AUTOCREATE |
Toggles postgres database creation when it does not exist |
false |
ARKD_PG_DB_MAX_OPEN_CONN |
Maximum number of open Postgres connections per pool | 50 |
ARKD_PG_DB_MAX_IDLE_CONN |
Maximum number of idle Postgres connections per pool | 50 |
ARKD_PG_DB_CONN_MAX_IDLE_MINS |
Maximum idle time for Postgres connections in minutes | 5 |
ARKD_PG_DB_CONN_MAX_LIFE_MINS |
Maximum lifetime for Postgres connections in minutes | 30 |
ARKD_TX_BUILDER_TYPE |
Transaction builder type (covenantless) | covenantless |
ARKD_LIVE_STORE_TYPE |
Cache service type (redis, inmemory) | redis |
ARKD_REDIS_URL |
Redis db connection url if ARKD_LIVE_STORE_TYPE is set to redis |
- |
ARKD_REDIS_NUM_OF_RETRIES |
Maximum number of retries for Redis write operations in case of conflicts | - |
ARKD_ESPLORA_URL |
Esplora API URL | https://blockstream.info/api |
ARKD_WALLET_ADDR |
The arkd wallet address to connect to in the form host:port |
- |
ARKD_SIGNER_ADDR |
The signer address to connect to in the form host:port |
value of ARKD_WALLET_ADDR |
ARKD_NO_MACAROONS |
Disable macaroon authentication | false |
ARKD_NO_TLS |
Disable TLS | true |
ARKD_UNLOCKER_TYPE |
Wallet unlocker type (env, file) to enable auto-unlock | - |
ARKD_UNLOCKER_FILE_PATH |
Path to unlocker file | - |
ARKD_UNLOCKER_PASSWORD |
Wallet unlocker password | - |
ARKD_SCHEDULER_TYPE |
Scheduler type (gocron, block) | gocron |
ARKD_TLS_EXTRA_IP |
Extra IP addresses for TLS (comma-separated) | - |
ARKD_TLS_EXTRA_DOMAIN |
Extra domains for TLS (comma-separated) | - |
ARKD_NOTE_URI_PREFIX |
Note URI prefix | - |
ARKD_SCHEDULED_SESSION_START_TIME |
Scheduled session start time (Unix timestamp) | - |
ARKD_SCHEDULED_SESSION_END_TIME |
Scheduled session end time (Unix timestamp) | - |
ARKD_SCHEDULED_SESSION_PERIOD |
Scheduled session period in minutes | - |
ARKD_SCHEDULED_SESSION_DURATION |
Scheduled session duration in seconds | - |
ARKD_SCHEDULED_SESSION_MIN_ROUND_PARTICIPANTS_COUNT |
Min participants for scheduled sessions | - |
ARKD_SCHEDULED_SESSION_MAX_ROUND_PARTICIPANTS_COUNT |
Max participants for scheduled sessions | - |
ARKD_OTEL_COLLECTOR_ENDPOINT |
OpenTelemetry collector endpoint | - |
ARKD_OTEL_PUSH_INTERVAL |
OpenTelemetry push interval in seconds | 10 |
ARKD_HEARTBEAT_INTERVAL |
Heartbeat interval in seconds | 60 |
ARKD_ROUND_REPORT_ENABLED |
Enable round report service | false |
ARKD_INDEXER_EXPOSURE. |
Require intent for getting vtxo chain (public, private, withheld) | public |
ARKD_INDEXER_SIGNING_PRIVKEY |
Hex-encoded private key for indexer auth token signing (sensitive) | - |
ARKD_INDEXER_AUTH_TOKEN_EXPIRY |
Auth token TTL in seconds | 300 (5 minutes) |
ARKD_BATCH_TRIGGER |
Optional CEL formula returning bool. When set, the server only starts a new batch round when the formula evaluates to true. See pkg/ark-lib/batchtrigger/README.md for the available variables and examples. |
- (always start) |
Admin Settings
The following settings are persisted in the database and managed via the admin API.
Default values are seeded from
ARKD_*environment variables on the first startup only. After that, those environment variables are ignored and settings are managed exclusively via the admin API. See Settings: first-boot seeding and runtime management for the full list of seed variables, units, defaults, and how to change settings at runtime.
| Endpoint | Method | Description |
|---|---|---|
/v1/admin/settings |
GET | Retrieve current settings |
/v1/admin/settings |
POST | Update settings (partial; only provided fields change) |
| Setting | Description | Default |
|---|---|---|
vtxo_tree_expiry |
VTXO tree expiry (blocks or seconds depending on scheduler) | 604672 (gocron) / 20 (block) |
unilateral_exit_delay |
Unilateral exit delay in seconds | 86400 (24 hours) |
public_unilateral_exit_delay |
Public unilateral exit delay in seconds | 86400 (24 hours) |
checkpoint_exit_delay |
Checkpoint exit delay (blocks or seconds) | 86400 (gocron) / 10 (block) |
boarding_exit_delay |
Boarding exit delay in seconds | 7776000 (3 months) |
round_min_participants_count |
Minimum number of participants per round | 1 |
round_max_participants_count |
Maximum number of participants per round | 128 |
vtxo_min_amount |
Minimum allowed amount for vtxos | -1 (dust) |
vtxo_max_amount |
Maximum allowed amount for vtxos | -1 (unset) |
utxo_min_amount |
Minimum allowed amount for boarding or collaborative exit | -1 (dust) |
utxo_max_amount |
Maximum allowed amount for boarding or collaborative exit | -1 (unset) |
ban_duration |
Ban duration in seconds | 300 (5 minutes) |
ban_threshold |
Number of crimes to trigger a ban | 3 |
max_tx_weight |
Max transaction weight | 40000 |
settlement_min_expiry_gap |
Minimum gap between settlement and VTXO expiry in seconds | 0 |
vtxo_no_csv_validation_cutoff_date |
Unix timestamp after which CSV validation is enforced | 0 (disabled) |
Provisioning
Data Directory
By default, arkd stores all data in the following location:
- Linux:
~/.arkd/ - macOS:
~/Library/Application Support/arkd/ - Windows:
%APPDATA%\arkd\
You can specify a custom data directory using the ARKD_DATADIR environment variable.
Connect to Bitcoin
arkd-wallet is the wallet used by arkd as liquidity provider.
It is based on NBXplorer and requires a running instance to connect to. You can check the [example](https://gi