arkd

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)
• Co-signs multisignature arrangements while preserving user exit rights

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 uses lnwallet as embedded on-chain wallet.

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.

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.

Connecting to Bitcoin

Option 1: Connect to Bitcoin Core via RPC

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

export ARKD_BITCOIND_RPC_USER=admin1
export ARKD_BITCOIND_RPC_PASS=123
export ARKD_BITCOIND_RPC_HOST=localhost:18443

For ZMQ notifications (recommended for better performance):

export ARKD_BITCOIND_ZMQ_BLOCK=tcp://localhost:28332
export ARKD_BITCOIND_ZMQ_TX=tcp://localhost:28333

Option 2: Connect via Neutrino

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

export ARKD_NEUTRINO_PEER=yourhost:p2p_port_bitcoin

Wallet Setup

1. Start the server:

   arkd
   

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

3. Unlock the wallet:

   arkd wallet unlock --password <password>
   

4. Generate a funding address:

   arkd wallet address
   

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

6. Check your wallet balance:

   arkd wallet balance
   

7. Withdraw funds from your wallet:

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

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][./pkg/ark-lib]: collection of data structures and functions reusable by arkd and sdk.
  • [arkd-wallet][./pkg/arkd-wallet]: bitcoin wallet service used as liquidity provider and signer.
  • [ark-cli][./pkg/ark-cli]: ark offchain and onchain wallet as command line interface.

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.18 or later)

2. Install Nigiri for local Bitcoin networks

3. Clone this repository:

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

4. Install dependencies:

   go mod download
   

5. Lint and format code:

   make lint
   

6. Run unit tests:

   make test
   

7. Run integration tests:

   make docker-run
   make integrationtest
   make docker-stop
   

8. Run arkd wallet in dev mode:

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

9. Run arkd in dev mode:

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

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

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.