######################################################################### ############################ Deprecated!!!! ############################ ######################################################################### Please use new repos instead:
- kinecosystem/blockchain-ops/apps/docker-quickstart -> https://github.com/kinecosystem/blockchain-docker-quickstart.git
- kinecosystem/blockchain-ops/apps/horizon-health-check -> https://github.com/kinecosystem/horizon-health-check
- kinecosystem/blockchain-ops/dashboard/prometheus -> https://github.com/kinecosystem/blockchain-prometheus.git
- kinecosystem/blockchain-ops/dashboard/healthcheck-telegraf-client -> https://github.com/kinecosystem/blockchain-healthcheck-telegraf-client.git
- kinecosystem/blockchain-ops/images/dockerfiles/blockchain-healthcheck-telegraf ->https://github.com/kinecosystem/blockchain-healthcheck-telegraf.git
- kinecosystem/blockchain-ops/images/dockerfiles/filebeat-for-docker-logs -> https://github.com/kinecosystem/filebeat-for-docker-logs.git
- kinecosystem/blockchain-ops/images/dockerfiles/horizon-nginx-proxy/ -> https://github.com/kinecosystem/horizon-nginx-proxy.git
- kinecosystem/blockchain-ops/images/dockerfiles/horizon-telegraf-test-env/ ->https://github.com/kinecosystem/horizon-telegraf-test-env.git
- kinecosystem/blockchain-ops/images/dockerfiles/horizon-telegraf/ -> https://github.com/kinecosystem/horizon-telegraf.git
- kinecosystem/blockchain-ops/images/dockerfiles/postgres-core -> https://github.com/kinecosystem/postgres-core.git
- kinecosystem/blockchain-ops/images/dockerfiles/postgres-horizon -> https://github.com/kinecosystem/postgres-horizon.git
- kinecosystem/blockchain-ops/images/dockerfiles/stellar-core-metrics-exporter -> https://github.com/kinecosystem/stellar-core-metrics-exporter.git
- kinecosystem/blockchain-ops/images/dockerfiles/stellar-core-telegraf-test-env ->https://github.com/kinecosystem/stellar-core-telegraf-test-env.git
- kinecosystem/blockchain-ops/images/dockerfiles/stellar-core-telegraf -> https://github.com/kinecosystem/stellar-core-telegraf.git
- kinecosystem/blockchain-ops/images/dockerfiles/telegraf-datadog-forwarder-testnet/ ->https://github.com/kinecosystem/telegraf-datadog-forwarder-testnet.git
- kinecosystem/blockchain-ops/images/dockerfiles/telegraf-datadog-forwarder -> https://github.com/kinecosystem/telegraf-datadog-forwarder.git
######################################################################################################### #########################################################################################################
This repository contains all operational code and guides for the Kin blockchain. This includes infrastructure automation and orchestration to launch and manage the Kin blockchain.
A Docker image that provides a default, non-validating, ephemeral configuration that should work for most cases. Check out apps/docker-quickstart/ for more information.
- apps/docker-quickstart/ - Simple way to incorporate Core and Horizon into your private infrastructure.
- images/ - Docker images for running all the various apps in the Kin network i.e. Validator, HTTP API Frontend, etc. Also includes automation for running a test network on your local machine for testing purposes.
- deploy/terraform/ - Automation code for launching Kin network infrastructure.
- deploy/ansible/ - Orchestration for deploying and managing Kin blockchain apps in production.
The Kin network is made up of the following applications:
Core is a validator and history archiver. This is the primary app that operates the network and takes part in consensus. Its primary responsibilities are:
- Participate in consensus, validate and add new ledgers and transactions.
- Submit and relay transactions to other nodes.
- Store and archive ledger information. This allows other nodes to catch-up on ledger information and join the network.
A core node can be configured to participate only in part of the above actions. If it participates in all of these - it is considered a Full node.
Horizon is an HTTP API frontend app that makes it easier on clients to access the network. It abstracts the asynchronous nature of the blockchain from clients wishing to submit transactions or fetch account information.
Laboratory is a web application that allows to construct and submit transactions on the network.
The following are applications only available on a test network, and are irrelevant for a production environment.
Friendbot is a web application that creates and funds accounts with Kin.
The Kin blockchain currently differs from Stellar in the following aspects:
Cores must be aware of a unique account in the network called a “Whitelist” account. This is configured in the Core app’s configuration file (See the example in this document). This is a required configuration, and without this your Core node will fail to successfully perform a complete catchup with the network.
The decimal precision in the Kin blockchain is 5 decimals, e.g. the smallest value available is 0.00001 Kin. This is in contrast to Stellar’s network where the decimal precision is 7.
NOTE that Kin SDKs account for this feature, while Stellar’s SDKs do not.
Our SDKs prepend a text to every submitted transaction. Please keep this in mind if you’re implementation relies on transaction memos. For more information please see the following sections in each SDK documentation:
Kin HD wallet derivation path is 44'/2017'/0'. Note that currently the underlying cryptographic implementation is similar to Stellar, but we still use a different path for the sake of being explicit.
The following are instructions on setting up a group of Core validators in order to setup a new or join an existing network.
The Kin Foundation is currently using AWS for managing its infrastructure, though other cloud providers are possible as well.
Before launching a single node or more, it is important to decide on the following:
- How many nodes to run, keeping in mind high-availabiltiy considerations. Specifically, multiple nodes should be deployed on different cloud regions e.g. AWS us-east-1 and us-west-1. Prefer a separate region for each node.
- Decide on your quorum set and safety threshold percentage.
- Configure Core.
- See how to install and run Core.
- Kin Foundation runs Core using Docker.
- See our Dockerfile and the additional build image for an example on how to build and run on Ubuntu.
- See the Docker Compose template file for an exampe on how to run Core.
- Read on hardware requirements and launch the required infrastructure:
- Launch a cloud instance such as AWS EC2, used for running the Core application.
- Launch a PostgreSQL database instance such as AWS RDS, used for storing ledger state and other operational information by the Core application.
- Create an AWS S3 bucket, used for storing the history archive.
- Repeat the above process for other Core nodes on your system.
- Finally, see Core's Administration Guide.
- Launch an EC2 and RDS instance, similar to the above.
- Configure Horizon
- Similar to Core, we run Horizon using Docker.
- See images/Dockerfile.Horizon and the additional build image for an example on how to build and run Horizon on Ubuntu.
- See the Docker Compose template file for an example on how to build and configure Horizon on Ubuntu.
- Finally, see Horizon's Administration Guide.
At Kin Foundation we use Ansible for orchestration and provisioning, and Terraform for infrastructure automation.
Ansible playbooks and roles can serve as specific step-by-step guide to deploying Core and Horizon on production. Specific points of interest include:
- Core deploy role.
- Horizon init, setup, and start roles.
- Kernel network parameter optimization role.
See deploy/ansible/ directory for further resources.
Similar to Ansible, our Terraform code can serve as a guidelines to properly configure the cloud infrastructure on your preferred provider.
See deploy/terraform/ directory for more information. Please keep the security concerns guide in mind when launching infrastructure.
The following is a security checklist of issues that should be taken into account when managing Core and Horizon nodes.
Start by reading through Stellar's security guide.
The seed of every core node is the most critical information to secure. If a seed is compromised, an attacker could impersonate the Core node whose seed belongs to.
- Secure and limit access to all copies of the seed:
- Core configuration file containing the seed should have limited user read access on the Core node instance.
- Backups should have very limited access.
- At Kin we store the seed backups using AWS SSM Parameter Store using very limited permissions.
Core exposes two ports: P2P (11625) and control (11626).
- The P2P port should be publicly open.
- The control port should be private and accessible only to Core's related Horizon.
- At Kin we manage access to EC2 and RDS instances using AWS EC2 security groups. Refer to our terraform code for examples.
- Databases should not be exposed, and given access only to the Core and related Horizon apps.
Core's RDS should have two users set up:
- User for Core access with read/write permissions to the "core" database.
- User for Horizon access with read-only permissions to the "core" database.
- RDS admin user should not be used in production.
Horizon's RDS should have a single user set up:
- User for Horizon access with read/write permissions to the "horizon" database.
- RDS admin user should not be used in production.
- The history archive should be publicly readable globally, and specifically available for other nodes to catch up.
- Write access should only be given to the Core instance managing the archive.
- At Kin we manage access to history archives using AWS IAM roles.
- Core Administration
- Hardware Requirements
- Security
- Horizon Administration
- Stellar Node Performance Tips
This folder includes a tasks.py file which can be used to build linux horizon and core binaries. You'll need to have pipenv and invoke installed and then:
pipenv run invoke build-go --version a-name-for-the-version --branch repo-name/my-branch-name # builds horizon
pipenv run invoke build-core --version test --branch master # builds core