Please note that while this guide is designed to be as user-friendly as possible, some basic understanding of command line interface and system administration is beneficial.
Step 1: Prerequisites
Before you start, make sure you have the following installed:
- Docker: Docker is a platform that allows you to develop, ship, and run applications in containers. You can download Docker from here.
- Git: Git is a distributed version control system that lets you manage and keep track of your source code history. You can download Git from here.
Step 2: Clone the Koinos Docker Repository
Open your terminal and clone the Koinos Docker repository using Git. This repository contains the necessary Docker configuration to run a Koinos node.
git clone https://github.com/koinos/koinos-docker.git
Step 3: Navigate to the Koinos Docker Directory
Navigate to the directory where the Koinos Docker repository was cloned.
Step 4: Build the Docker Image
Build the Docker image for the Koinos node. This may take some time as Docker needs to download and install the necessary dependencies.
docker build -t koinos .
Step 5: Run the Koinos Node
Now that the Docker image is built, you can run the Koinos node.
docker run -p 2001:2001 -p 8080:8080 -v $(pwd)/data:/var/lib/koinos koinos
This command does the following:
-p 8080:8080map the ports from the Docker container to your host machine. Port 2001 is used for peer-to-peer communication, and port 8080 is used for JSON-RPC API calls.
-v $(pwd)/data:/var/lib/koinosmaps a directory on your host machine to the Docker container. This is where the Koinos blockchain data will be stored.
koinosis the name of the Docker image that you built in the previous step.
Step 6: Interacting with the Koinos Node
6.1. Installing and Starting the CLI
The Koinos CLI is a comprehensive command-line tool for interacting with the Koinos Blockchain. You can download the latest release from GitHub. After downloading, you can start the CLI with the binary included in the archive.
6.2 Basic Usage of the CLI
When running the wallet, it will start in interactive mode. You can press tab or type
list to see a list of possible commands. The
help <command-name> command will show a help message for the given command.
Some commands require a node RPC endpoint. This can be specified either when starting the CLI with
--rpc command line switch, or with the
connect command from within the CLI. Both take an endpoint URL.
Here is an example of launching from the command line with an RPC:
koinos-cli --rpc https://api.koinos.io/
And here is an example of the
You can use the public RPC server for testing at this address: https://api.koinos.io/
Step 7: Stopping the Koinos Node
To stop the Koinos node, you can press
Ctrl+C in the terminal where the Docker container is running.
Step 8: Updating the Koinos Node
To update the Koinos node, you need to pull the latest changes from the Koinos Docker repository, rebuild the Docker image, and run the Docker container again.
git pull docker build -t koinos . docker run -p 2001:2001 -p 8080:8080 -v $(pwd)/data:/var/lib/koinos koinos
Step 9. Wallet Creation & Management
To create a new wallet, use the command
create <filename> <password>. The new wallet will then be created in the given file, and automatically opened.
create my.wallet password1234
To open a previously created wallet, use the command
open <filename> <password>.
open my.wallet password1234
To import an existing Wallet Import Format (WIF) private key, use the commands
import <wif> <filename> <password>.
import 5KPJcpkw7GBtxjNrzroYgVwjR8CnTwbPrybuwfb8ff1Hw4GcqB5 imported.wallet password1234
To close the open wallet, simply use the
9. Other Useful Commands
To check the balance of a given public address, use the command
To transfer tKOIN from the currently open wallet, use the command
transfer <amount> <address>.
10. Smart Contract Management
To upload a smart contract, use the command
upload <filename>. The file given should be a compiled wasm smart contract. The contract id will be the public address of the currently open wallet.
To interact with a smart contract, first register its ABI file with the command
register <name> <address> <abi-filename> using the contract’s address and a name of your choosing.
register koin 15im92XgZiV39 tcKMhMGtDYhJjXPMjUu8r abi/koin.abi
Its methods will then be added to the list of available commands in the CLI.
11. Transaction Sessions
Sometimes it is important to ensure multiple operations are included in the same block in a specific order. To accomplish this with the CLI, you use a session.
To begin a session, use the command
session begin. Any command that interacts with the chain will now be added to the current session.
To view the current session, use
To cancel the current session, use
When you are done adding commands to the session,
session submit will send the attached commands as a single transaction to the blockchain.
session begin transfer 1.0 1BLUi4ogqptnyBnSuKFyWMxEyVJzxiZWhM upload token.wasm transfer 25.0 15Pb7o5GFBB56njFNvU2fAfa9Mm7rmsJH1 session view session submit
12. Block Production
To produce blocks, you need to have a Koinos node running and be connected to the network. You also need to have a private key for signing the blocks. The private key is set in the
miner.json configuration file.
Get started now, refer to running your Koinos node.
Your All Set!
Congratulations! You’ve successfully set up and launched a Koinos node. Remember to regularly update your node to get the latest features and security updates. If you encounter any issues, you can ask for help in the Koinos community.