arkd

⚠️ IMPORTANT DISCLAIMER: ALPHA SOFTWARE arkd is 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 arkd-signer as the transaction 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

1. Download the latest arkd binary from the GitHub Releases page

2. Make the binary executable:

   chmod +x arkd

3. Move the binary to a directory in your PATH (optional):

   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_DB_TYPE	Database type (postgres)	postgres
ARKD_PG_DB_URL	Postgres connection url if ARKD_DB_TYPE is set to postgres	-
ARKD_EVENT_DB_TYPE	Event database type (postgres)	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)	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_FINALIZATION_LOCK_TTL	Initial offchain finalization lock TTL in seconds (positive; first boot only)	300
ARKD_ESPLORA_URL	Esplora API URL	https://blockstream.info/api
ARKD_ARKADE_EXPLORER_URL	Arkade explorer URL	https://arkade.space
ARKD_ALERT_MANAGER_URL	AlertManager URL for pushing alerts	-
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 (required)	-
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_TLS_EXTRA_IP	Extra IP addresses for TLS (comma-separated)	-
ARKD_TLS_EXTRA_DOMAIN	Extra domains for TLS (comma-separated)	-
ARKD_OTEL_COLLECTOR_ENDPOINT	OpenTelemetry collector endpoint	-
ARKD_OTEL_PUSH_INTERVAL	OpenTelemetry push interval in seconds	10
ARKD_PYROSCOPE_SERVER_URL	Pyroscope server URL for continuous profiling	-
ARKD_ENABLE_PPROF	Expose pprof endpoints on the admin port	false
ARKD_HEARTBEAT_INTERVAL	Heartbeat interval in seconds	60
ARKD_MAX_CONCURRENT_STREAMS	Max concurrent gRPC streams per connection	1000
ARKD_STREAM_CONN_POOL_SIZE	Number of gRPC connections in the stream pool	4
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
session_duration	How long a batch session lasts (in seconds) before timing out once it started	30
vtxo_tree_expiry	VTXO tree expiry (relative locktime: ≥ 512 = seconds, < 512 = blocks)	604672
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 (24 hours)
boarding_exit_delay	Boarding exit delay in seconds	7776000 (3 months)
unrolled_vtxo_min_expiry_margin	Min expiry margin for unrolled vtxos in seconds	300 (5 minutes)
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
max_op_return_outputs	Max OP_RETURN outputs per transaction	3
asset_tx_max_weight_ratio	Max weight ratio for asset transactions, in (0, 1)	0.5
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)
note_uri_prefix	Note URI prefix	""
build_version_header	Min accepted client build version (semver, e.g. v2.3.4)	"" (no minimum)
build_version_header_required	Require clients to send a valid X-Build-Version header	false
digest_header_required	Require clients to send a matching X-Digest header	false

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 in the official repository, or our Docker Compose file, to see how to start one.

To connect arkd-wallet to your running NBXplorer instance use this environment variable:

# Make sure to use the right URL, this is just an example.
export ARKD_WALLET_NBXPLORER_URL=http://localhost:32838

Configure signer

arkd-signer is a standalone service that holds the operator signing key and signs arkd's protocol transactions. It is configured via the following environment variables:

Environment Variable	Description	Default
ARKD_SIGNER_SECRET_KEY	Hex-encoded operator signing key (required, sensitive)	-
ARKD_SIGNER_DEPRECATED_KEYS	Comma-separated old keys still accepted for signing, each as <hexkey>[:<cutoff_unix_seconds>] (sensitive)	-
ARKD_SIGNER_PORT	Port to listen on	6061
ARKD_SIGNER_LOG_LEVEL	Logging level (0-6, where 6 is trace)	4 (info)

Configure the signing key (required):

# Make sure to use a random private key, this is just an example.
export ARKD_SIGNER_SECRET_KEY=19422b10efd05403820ff6a3365422be2fc5f07f34a6d1603f7298328f0f80f6

To rotate the signer key while still accepting coins locked to old keys, set ARKD_SIGNER_DEPRECATED_KEYS to a comma-separated list of old keys. Each entry is a hex key, optionally followed by : and a cutoff date, which is a Unix timestamp in seconds (UTC), after which clients should stop locking new funds to that key. Omit the cutoff to leave it unset:

# Format: <hexkey>[:<cutoff_unix_seconds>],<hexkey>[:<cutoff_unix_seconds>]
# Example with two deprecated keys: the first retires at a cutoff date, the second has no cutoff.
export ARKD_SIGNER_DEPRECATED_KEYS=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6:1735689600,f0e1d2c3b4a59687766554433221100ff1e2d3c4b5a69788796a5b4c3d2e1f00

Connect to wallet

To connect arkd to arkd-wallet use this environment variable:

# Make sure to use the right URL in the form host:port, this is just an example.
export ARKD_WALLET_ADDR=localhost:6060

Connect to signer

arkd connects to arkd-signer via this environment variable (required):

# Make sure to use the right URL in the form host:port, this is just an example.
export ARKD_SIGNER_ADDR=localhost:6061

Setup arkd

1. Start the wallet:

   arkd-wallet

2. Start the signer:

   arkd-signer

3. Start arkd (requires ARKD_WALLET_ADDR and ARKD_SIGNER_ADDR):

   arkd

4. Create a new wallet:

   arkd wallet create --password <password>

   Or restore from mnemonic:

   arkd wallet create --mnemonic "your twelve word mnemonic phrase here" --password <password>

   You can repoint arkd at a different signer URL at runtime if needed:

   arkd signer load --signer-url localhost:6061

5. Unlock the wallet:

   arkd wallet unlock --password <password>

6. Generate a funding address:

   arkd wallet address

7. Fund the on-chain address with BTC and wait for at least 2 confirmations.

8. Check your wallet balance:

   arkd wallet balance

9. Withdraw funds from your wallet:

   arkd wallet withdraw --address <address> --amount <amount_in_btc>

For a complete list of available commands and options:

arkd --help

Repository Structure

• api-spec: Ark Protocol Buffer API specification.
• pkg: collection of reusable packages and services.
  • ark-lib: collection of data structures and functions reusable by arkd and sdk.
  • arkd-wallet: bitcoin wallet service used as liquidity provider.
  • arkd-signer: standalone service that holds the operator key and signs arkd's protocol transactions.
  • ark-cli: ark offchain and onchain wallet as command line interface.
  • client-lib: Go client library to interact with arkd (transport, explorer, batch sessions).
  • client-wallet: client-side wallet built on top of client-lib.
  • errors: shared error types and codes.
• internal: arkd implementation.
  • core: contains the core business logic of arkd.
    • application: contains the implementation of the service responsible for the core operations.
    • domain: models and events managed by the application service.
    • ports: collection of interfaces of the services used by the application one, like for example the wallet, the cache or the database.
  • infrastructure: contains implementations of the interfaces defined in internal/core/ports. Every folder contains the different implementations of the same interface.
  • interface: contains the implementations of the interface layer of arkd
    • grpc: the gRPC implementation of the arkd interface. All gRPC methods are also mapped to REST endpoints.
• test/e2e: contains the integration tests.

Development

Compile binary from source

To compile the arkd binary from source, you can use the following Make commands from the root of the repository:

• make build: Builds the arkd binary for your platform.
• make build-all: Builds the arkd binary for all platforms.

Contributing Guidelines

1. No force pushing in PRs: Always use git push --force-with-lease to avoid overwriting others' work.
2. Sign your commits: Use GPG to sign your commits for verification.
3. Squash and merge: When merging PRs, use the "Squash and merge" option to maintain a clean commit history.
4. Testing: Add tests for each new major feature or bug fix.
5. Keep master green: The master branch should always be in a passing state. All tests must pass before merging.

Local Development Setup

1. Install Go (version 1.27 or later)

2. Install Nigiri for local Bitcoin networks

3. Start Nigiri to setup a regtest Bitcoin environment:

   nigiri start

4. Clone this repository:

   git clone https://github.com/arkade-os/arkd.git
   cd arkd

5. Install dependencies:

   go mod download

6. Run arkd wallet and signer in dev mode (each in its own tab):

   make run-wallet
   make run-signer

   NOTE: make run-wallet starts the pg and nbxplorer services defined in docker-compose.regtest.yml, make sure to tear them down once you want to delete your dev env with make docker-stop

7. Run arkd in dev mode:

   # with Postgres and Redis
   make run

Testing

1. Lint and format code:

   make lint

2. Run unit tests:

   make test

3. Run integration tests (start nigiri if needed first):

   make docker-run
   make integrationtest
   make docker-stop

   make docker-run brings up the full stack defined in docker-compose.regtest.yml (postgres, redis, nbxplorer, arkd-wallet, arkd-signer, and arkd).

Protobuf Breaking Change Detection

To ensure API compatibility, breaking changes in protobuf definitions are automatically detected:

Local verification:

./scripts/check-proto-breaking

GitHub Actions:

• Automatically runs on all pull requests that modify api-spec/**
• Compares changes against the target branch
• Fails if breaking changes are detected

For detailed information about breaking changes, common issues, and best practices, see api-spec/BREAKING_CHANGES.md.

In the envs/ folder you can find the several dev-mode configurations for arkd, arkd-wallet and arkd-signer.

Support

If you encounter any issues or have questions, please file an issue on our GitHub Issues page.

Security

We take the security of Ark seriously. If you discover a security vulnerability, we appreciate your responsible disclosure.

Currently, we do not have an official bug bounty program. However, we value the efforts of security researchers and will consider offering appropriate compensation for significant, responsibly disclosed vulnerabilities.

License

This project is licensed under the MIT License - see the LICENSE file for details.