Koinos Node (QuickStart Guide)

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.

cd koinos-docker

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 2001:2001 and -p 8080:8080 map 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/koinos maps a directory on your host machine to the Docker container. This is where the Koinos blockchain data will be stored.
koinos is 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 connect command:

connect https://api.koinos.io/

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.

Example:

create my.wallet password1234

To open a previously created wallet, use the command open <filename> <password>.

Example:

open my.wallet password1234

To import an existing Wallet Import Format (WIF) private key, use the commands import <wif> <filename> <password>.

Example:

import 5KPJcpkw7GBtxjNrzroYgVwjR8CnTwbPrybuwfb8ff1Hw4GcqB5 imported.wallet password1234

To close the open wallet, simply use the close command.

9. Other Useful Commands

To check the balance of a given public address, use the command balance <address>.

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.

Example:

upload token.wasm

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.

Example:

register koin 15im92XgZiV39

tcKMhMGtDYhJjXPMjUu8r abi/koin.abi

Its methods will then be added to the list of available commands in the CLI.

Example:

koin.balance_of 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM

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 session view.

To cancel the current session, use session cancel.

When you are done adding commands to the session, session submit will send the attached commands as a single transaction to the blockchain.

Example:

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.