diff --git a/docs/cli_tutorial/bitcoind_setup.md b/docs/cli_tutorial/bitcoind_setup.md new file mode 100644 index 00000000..67ffe54b --- /dev/null +++ b/docs/cli_tutorial/bitcoind_setup.md @@ -0,0 +1,117 @@ +# Setting up `bitcoind` + +This tutorial will guide you through setting up `bitcoind` on a machine, running a Bitcoin `regtest` node, and performing basic operations like creating a wallet, generating blocks, and checking the balance. + +## 1. Installing `bitcoind` + +To start working with Bitcoin, it's necessary to install the Bitcoin Core software, which includes `bitcoind` (the Bitcoin daemon). + +### Steps: + +1. **Get Bitcoin Core:** + - Visit the [official Bitcoin Core website](https://bitcoin.org/en/download) and download the appropriate version for the operating system. + - Follow the instructions on the site to verify the downloaded files by checking the signatures to ensure authenticity. + +2. **Verify Installation:** + - After installation, run the following command to confirm that `bitcoind` is properly installed: + ```bash + bitcoind --version + ``` + - This will output the version of `bitcoind` if it's installed correctly. + +## 2. Setting up a `bitcoin.conf` File + +While `bitcoind` can be run on various Bitcoin networks, this tutorial will focus on the `regtest` network, which is a local blockchain environment ideal for development and testing. + +Before running `bitcoind`, it's important to configure the node with a `bitcoin.conf` file to set up the `regtest` network. + +### Sample `bitcoin.conf` File for `regtest` + +First, create a directory for Bitcoin data and configuration files if it doesn’t already exist: + +```bash +mkdir -p ~/.bitcoin +``` +Then, create a `bitcoin.conf` file in `~/.bitcoin/` and add the following lines: + +```ini +regtest=1 +server=1 +fallbackfee=0.0001 +rpcuser=admin +rpcpassword=password +rpcbind=0.0.0.0:18443 +rpcallowip=0.0.0.0/0 +txindex=1 +``` + +### Explanation of Configurations: + +- `regtest=1`: Runs the node in regtest mode. +- `server=1`: Enables `bitcoind` to run as a server and accept RPC (Remote Procedure Call) commands. +- `rpcuser` and `rpcpassword`: Set the username and password for `bitcoin-cli` RPC access. These values can be customized or left as provided. +- `rpcbind=0.0.0.0:18443`: Binds the RPC server to this IP and port. +- `rpcallowip=0.0.0.0/0`: Allows RPC connections from any IP address. Be cautious when using this in a non-development environment. +- `fallbackfee=0.0001`: Specifies a fallback transaction fee when none is provided. +- `txindex=1`: Enables a full transaction index for your node, which is useful for querying historical transactions. + +After setting up the configuration file, your node will be ready to run in `regtest` mode. + +## 3. Basic Operations + +Once the `bitcoin.conf` file is configured, `bitcoind` can be started, and basic operations can be performed using `bitcoin-cli`. + + + +### 3.1 Start the `bitcoind` daemon: + +Run the following command to start the Bitcoin node: +```bash +bitcoind -daemon +``` + +- **Note**: we don't need to pass the flag to mention on the bitcoin mention on which we want to run the bitcoind as `bitcoin.conf` already mentions the bitcoin network. + +Check the status to ensure it’s running: + +```bash +bitcoin-cli getblockchaininfo +``` + +This command provides details about the blockchain's current state, including the number of blocks and synchronization status. + +### 3.2 Create a Wallet + +Create a wallet to perform wallet-related operations in the `regtest` environment: + +```bash +bitcoin-cli createwallet "testwallet" +``` + +### 3.3 Get a New Bitcoin Address + +Generate a new Bitcoin address to receive funds: + +```bash +bitcoin-cli getnewaddress +``` + +### 3.4 Generate Some Blocks + +Since this is regtest, so we can generate new blocks and receive Bitcoin as block rewards: + +```bash +bitcoin-cli generatetoaddress 101
+``` + +### 3.5 Check the wallet balance: +Check the balance in your wallet: + +```bash +bitcoin-cli getbalance +``` + +This should display a balance corresponding to the block rewards from the generated blocks. + +That's everything needed to get started with `bitcoind` on the `regtest` network. Now you're ready to explore Bitcoin transactions and experiment with coinswap CLI apps. + diff --git a/docs/cli_tutorial/taker.md b/docs/cli_tutorial/taker.md new file mode 100644 index 00000000..82103878 --- /dev/null +++ b/docs/cli_tutorial/taker.md @@ -0,0 +1,197 @@ +# Taker-Cli Tutorial + +## What is the Taker in Coinswap? + +A **taker** initiates a coinswap transaction, seeking to exchange their coins with the assistance of **makers**, without losing control of their funds. + +## Prerequisites + +You will need to have `bitcoind` set up before proceeding with the steps below. + +### Start Bitcoind + +Make sure you start your `bitcoind` daemon to work with the `taker-cli` by running the following command: + +```bash +bitcoind -daemon +``` + +## Create a Wallet + +To perform basic operations such as generating new blocks, you'll need a wallet. Let's create a wallet named `default`. + +```bash +bitcoin-cli createwallet "default" +``` + +## Send Funds to the `default` Wallet by Generating Blocks + +### Step 1: Get a New Address + +First, get a new address from the `default` wallet. + +```bash +bitcoin-cli getnewaddress +``` + +### Step 2: Generate 101 Blocks and Send Funds + +Generate 101 blocks and send the funds to the address generated in Step 1. + +```bash +bitcoin-cli generatetoaddress 101
+``` + +## About the Taker Wallet + +Currently, there is no specific command to initialize a new taker wallet or load an existing one. Each command automatically loads the wallet from the specified data directory or creates a new one if it doesn't exist. + +## Fund 1 BTC to the Taker Wallet + +### Step 1: Get a New Address from the Taker Wallet + +```bash +./taker -a -r get-new-address +``` + +### Step 2: Send 1 BTC from the Default Wallet to the Taker Wallet + +```bash +bitcoin-cli -rpcwallet="default" sendtoaddress
1 +``` + +### Step 3: Generate a Block to Confirm the Transaction + +```bash +bitcoin-cli -rpcwallet="default" getnewaddress +bitcoin-cli generatetoaddress 1
+``` + +## Check the Taker Wallet Balance + +After funding, you can check different types of balances in the `taker` wallet. + +### Seed Balance + +This represents the available balance received by the `default` wallet. + +```bash +./taker -a -r seed-balance +``` + +### Contract Balance + +Currently, this will show 0 SAT as there are no contracts yet. + +```bash +./taker -a -r contract-balance +``` + +### Swap Balance + +This will also show 0 SAT for now, as no swaps have been initiated. + +```bash +./taker -a -r swap-balance +``` + +### Total Balance + +The total balance is the sum of seed, contract, and swap balances. Currently, it will be equal to the seed balance. + +```bash +./taker -a -r total-balance +``` + +## Check UTXOs in the Taker Wallet + +You can check the UTXOs in the `taker` wallet as follows: + +### Seed UTXO + +The seed UTXO will reflect the 1 BTC sent earlier. + +```bash +./taker -a -r seed-utxo +``` + +### Contract UTXO + +This will return an empty vector as there are no contracts yet. + +```bash +./taker -a -r contract-utxo +``` + +### Swap UTXO + +Similar to the contract UTXO, this will also return an empty vector for now. + +```bash +./taker -a -r swap-utxo +``` + +## Send 0.5 BTC from the `taker` Wallet to the `default` Wallet + +### Step 1: Get an Address from the `Default` Wallet + +```bash +bitcoin-cli -rpcwallet="default" getnewaddress +``` + +### Step 2: Send Funds Using the `send-to-address` Command + +Call the `send-to-address` command with the following parameters: + +- `amount`: Amount to be sent +- `address`: Recipient address +- `fee`: Fee for the transaction being created. + +> **Note:** +> Currently, the command requires the `fee` parameter instead of `fee_rate` because it's not possible to calculate the fee for a transaction that hasn't been created yet using only a `fee_rate`. +> When the `fee` is provided, the command will return two outputs: +> +> 1. The hex of the signed transaction (which is not yet broadcasted). +> 2. The calculated `fee_rate`. +> Having the calculated `fee_rate` allows us to infer the necessary fee for a successful transaction. Based on this, we can adjust the `fee` parameter and determine the appropriate fee required. +> While this process might seem unconventional, it will be improved with future BDK integration. + +### Step 3: Execute the `send-to-address` Command + +To get the hex of the signed transaction and the calculated `fee_rate` from the given `fee`, use the `send-to-address` command. +For example, with a `fee` of 1000 SAT: + +```bash +./taker -a -r send-to-address
50000000 1000 +``` + +### Step 4: Broadcast the Signed Transaction + +After receiving the transaction hex, broadcast the signed transaction to the network using: + +```bash +bitcoin-cli sendrawtransaction +``` + +### Step 5: Generate a Block to Confirm the Transaction + +Generate a block using the `default` wallet to confirm the transaction. After this, 0.5 BTC will be successfully spent from the `taker` wallet to the `default` wallet. + +```bash +bitcoin-cli generatetoaddress 1
+``` + +## Check the Balance and UTXOs of the Taker Wallet + +- **Seed Balance**: + After spending, the seed balance will be 49,999,000 SAT, calculated as: + `(Initial balance (1 BTC) - spend amount (0.5 BTC) - fee (1000 SAT))` + +- **Total Balance**: + The total balance will be the same as the seed balance. + +- **Swap Balance and Contract Balance**: + Both of these will remain at 0 SAT, as no swaps or contracts have been initiated. + + +