⚠️ 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.

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.

arkd supports the following Bitcoin network:

• regtest
• testnet3
• signet
• mutinynet
• mainnet

and uses lnwallet as embedded on-chain wallet.

In this documentation, you'll learn how to install and use arkd, a Bitcoin server for off-chain Bitcoin transactions.

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/

The arkd server can be configured using environment variables.

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.

To connect arkd to your own Bitcoin Core node via RPC, use these environment variables:

export ARKD_WALLET_BITCOIND_RPC_USER=admin1
export ARKD_WALLET_BITCOIND_RPC_PASS=123
export ARKD_WALLET_BITCOIND_RPC_HOST=localhost:18443

For ZMQ notifications (recommended for better performance):

export ARKD_WALLET_BITCOIND_ZMQ_BLOCK=tcp://localhost:28332
export ARKD_WALLET_BITCOIND_ZMQ_TX=tcp://localhost:28333

For a lighter setup using Neutrino (BIP 157/158):

export ARKD_WALLET_NEUTRINO_PEER=yourhost:p2p_port_bitcoin

If none of the above options are specified, the wallet uses Neutrino by default with peer discovery.

1. Start the wallet:

   arkd-wallet

2. Start arkd:

   arkd

3. 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>

4. Unlock the wallet:

   arkd wallet unlock --password <password>

5. Generate a funding address:

   arkd wallet address

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

7. Check your wallet balance:

   arkd wallet balance

8. 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

• 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 and signer.
  • ark-cli: ark offchain and onchain wallet as command line interface.
• 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.

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.

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.

1. Install Go (version 1.23 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 in dev mode:

   # with neutrino
   make run-wallet-neutrino
   # or with bitcoind
   make run-wallet-bitcoind

7. Run arkd in dev mode:

   # with sqlite db and inmemory cache
   make run-light
   # or with postgres db and redis cache
   make run

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

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

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

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.

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