CyberWay Testnet. Руководство по установке для блок-продюсеров

CyberWay Testnet

Руководство по установке

Уважаемые делегаты и члены комьюнити!

Настоящее руководство предназначено для валидаторов и блок-продюсеров блокчейн-платформы CyberWay, а также персонала, занимающегося ее разработкой и сопровождением.

Документ содержит инструкции по начальной установке и запуску программного продукта CyberWay в тестовом режиме на сервере под управлением операционной системы Ubuntu 16.04 либо иной системы семейства Linux с использованием программного обеспечения Docker и Docker-compose.
Приведенные в руководстве инструкции рассчитаны на персонал, владеющий базовыми навыками работы с компьютерным оборудованием и знакомый с основными понятиями блокчейн-технологии.

Раздел_1 Общее

Назначение

Блокчейн-платформа CyberWay разрабатывается на базе логики EOS для предоставления сервиса пользователям разных сообществ. Основным направлением развития CyberWay является создание децентрализованной системы с поддержкой на одном блокчейне одновременно нескольких приложений, функционирующих на основе смарт-контрактов.

Реализация CyberWay в тестовом варианте (далее — Testnet) предназначена для проведения испытаний в части установки и запуска CyberWay на сервере, а также для проведения отладочных работ по результатам испытаний.

Установка и проверка функционирования Testnet

Инструкции по установке и проверке функционирования Testnet условно разделяются на следующие этапы:

• настройка параметров;
• настройка сервисов;
• построение контейнеров;
• построение Docker-образа.

Установка Testnet на сервер выполняется с использованием доступной платформы Docker и инструмента командной строки Docker-compose. Использование платформы Docker обеспечивает:
создание необходимого программного окружения, в том числе необходимого перечня библиотек, независимо от версии операционной системы;
создание среды, изолированной от ненужных временных файлов, сохраняемых системой в строящемся пространстве.

Для задания конфигурации nodeos используется файл config.ini.
Для сборки Docker-контейнера используется Docker-файл. Для настройки набора сервисов используется docker-compose.yml (для Testnet требуется настройка двух сервисов — nodeosd и mongo).

Для построения Testnet требуется сервер с операционной системой Ubuntu 16.04 и определенным набором библиотек. В случае отсутствия сервера с требуемой операционной системой следует воспользоваться сервером с операционной системой семейства Linux. Имеется возможность установки Testnet на такой сервер с помощью платформы Docker, обеспечивающий создание необходимого окружения, независимо от версии системы Linux.
Установка и функционирование Testnet на сервер под управлением каких-либо иных классов систем не поддерживается.
Для установки Testnet на сервер с использованием платформы Docker необходимо выполнить следующие операции:

• сконфигурировать Docker-образ в отдельном пространстве;
• создать контейнеры с использованием Docker-образа. Контейнеры можно размещать как на локальном, так и на удаленном или виртуальном компьютере.

Для проверки функционирования Testnet необходимо подключиться к узлу (ноде) через cleos.

Генезис-данные

В качестве изначальных данных при установке Testnet на сервер используются генезис-информация о блокчейне и данные блокчейна Голос, зафиксированные на определенном блоке. К настоящему моменту для установки Testnet на сервер перенесены и доступны следующие объекты:

• пользовательские аккаунты. Для каждого аккаунта в блокчейне Голос создан аккаунт CyberWay и привязан к имени пользователя в домене @golos. Например, пользователю, зарегистрированному в блокчейне Голос под именем < username>, в Testnet будет соответствовать имя < username>@golos. Это имя будет использоваться в транзакциях;
• публичные ключи. Для каждого аккаунта блокчейна Голос были перенесены его публичные ключи с сохранением соответствующих полномочий, в том числе owner, active и posting.

Рекомендация

Перед началом выполнения приведенных в руководстве инструкций настоятельно рекомендуется сохранить код личного ключа.

Раздел_2 Конфигурирование Docker-образа

2.1. Создать репозиторий cyberway в отдельном пространстве. Открыть командное окно и войти в директорию cyberway, в которой будет создан Docker-образ. Далее исполнить:

git clone https://github.com/goloschain/cyberway

В пространство, из которого была исполнена команда, должен скопироваться каталог cyberway с его содержимым. В процессе копирования не должны появляться сообщения об ошибках.

2.2. Создать отдельную директорию testnet. Местонахождение данной директории выбирается произвольно (здесь и далее используется директория ~/testnet):

mkdir -p ~/testnet

2.3. В созданную директорию ~/testnet скопировать файлы docker-compose.yml и образец конфигурационного файла config.ini из репозитория Cyberway. Используемые для копирования команды:

cp Docker/config.ini ~/testnet/
cp Docker/docker-compose.yml ~/testnet/

2.4. Перейти в директорию ~/testnet. Все остальные команды должны выполняться из этой директории.

cd ~/testnet/

2.5. Настроить параметры в конфигурационном файле config.ini.

2.5.1. Установить адрес БД состояния системы. Рекомендуемый адрес параметра chaindb_address:

chaindb_address = mongodb://mongo:27017

2.5.2. Установить адреса остальных узлов (нод) сети, к которым необходимо выполнить подключение:

p2p-peer-address = <Node address>

Параметр p2p-peer-address настраивается отдельно для каждого подключаемого узла сети. Для подключения N узлов сети необходимо данный параметр указать N раз. Для корректного старта ноды и подключения к Testnet (предоставленному разработчиками CyberWay) рекомендуется указать адрес 116.203.104.164:9876.

2.5.3. Для приема входящих подключений от других узлов сети необходимо раскомментировать параметр p2p-listen-endpoint и указать адрес сетевого интерфейса, на котором следует ожидать подключений, а также номер порта. Задание адреса интерфейса в виде 0.0.0.0 позволит сервису nodeosd слушать подключения других узлов сети на всех доступных сетевых интерфейсах. Рекомендуемый адрес:

p2p-listen-endpoint = 0.0.0.0:9876

2.5.4. Если валидатор желает авторизоваться в качестве блок-продюсера, необходимо дополнительно указать имя блок-продюсера и ключи, которые будут использованы для подписания блоков.

По умолчанию параметр producer-name закомментирован. В этом случае узел используется только для подключения к Testnet без производства блоков. Для подключения к Testnet с возможностью производить блоки необходимо дополнительно установить параметры producer-name и signature-provider.

producer-name = <Producer name>
signature-provider = <Public key>=KEY:<Private key>

Данные параметры может установить только блок-продюсер, так как именно он располагает данными об имени аккаунта и ключах, которые необходимо использовать для создания блоков. Значения личного и публичного ключей блок-продюсер должен сгенерировать самостоятельно (либо использовать ключи блокчейна Голос). Личный ключ блок-продюсера используется для подписания блоков.
В следующей таблице приведен рекомендуемый перечень параметров конфигурационного файла, используемых для подключения узла к Testnet, а также для настройки узла блок-продюсера.

2.6. Сформировать данные генезиса.

2.6.1. В директорию ~/testnet загрузить архивированный файл с содержимым генезиса и распаковать его, исполнив:

wget http://download.golos.io/genesis.tar.gz
tar -zxf genesis.tar.gz

После выполнения этих команд в ~/testnet должна появится директория genesis, содержащая файлы genesis.dat и genesis.dat.map.

2.6.2. Переименовать директорию genesis в genesis-data, исполнив:

mv genesis genesis-data

2.6.3. В директории ~/testnet/genesis-data создать файл genesis.json со следующим содержимым:

{
  "initial_timestamp": "2019-03-01T12:00:00.000",
  "initial_key": "GLS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
  "initial_configuration": {
    "max_block_net_usage": 1048576,
    "target_block_net_usage_pct": 1000,
    "max_transaction_net_usage": 524288,
    "base_per_transaction_net_usage": 12,
    "net_usage_leeway": 500,
    "context_free_discount_net_usage_num": 20,
    "context_free_discount_net_usage_den": 100,
    "max_block_cpu_usage": 2500000,
    "target_block_cpu_usage_pct": 1000,
    "max_transaction_cpu_usage": 1800000,
    "min_transaction_cpu_usage": 100,
    "max_transaction_lifetime": 3600,
    "deferred_trx_expiration_window": 600,
    "max_transaction_delay": 3888000,
    "max_inline_action_size": 4096,
    "max_inline_action_depth": 4,
    "max_authority_depth": 6
  },
  "initial_chain_id": "0000000000000000000000000000000000000000000000000000000000000000"
}

Раздел_3 Создание контейнера

Процесс построения сервисов представляет собой построение томов Docker volume.

3.1. Создать тома Docker для хранения базы данных состояния системы и данных цепочки, исполнив:

sudo docker volume create cyberway-mongodb-data
sudo docker volume create cyberway-nodeos-data

3.2. Выполнить проверку создания томов. Для этого исполнить:

docker volume ls

Создание томов считается успешным, если в выдаче команды содержится информация о созданных томах:

local cyberway-mongodb-data
local cyberway-nodeos-data

3.3. Для запуска узла требуется запуск двух сервисов — nodeosd и mongo. Для упрощения процесса запуска используется утилита docker-compose.
Войти в директорию ~/testnet (в которой находится docker-compose.yml), и исполнить команду загрузки сервисов:

sudo docker-compose up -d

где:
-d — запускает контейнер в фоновом режиме.

3.4. Для проверки успешного запуска контейнеров необходимо исполнить следующую команду:

sudo docker ps

Создание контейнеров считается успешным, если в тексте лог-файлов будут отсутствовать сообщения об ошибках и появятся сообщения о создании контейнеров с именами nodeosd и mongo. Для анализа текста лог-файлов можно использовать команды вида:

sudo docker logs --tail 100 -f nodeosd
sudo docker logs --tail 100 -f mongo

где:
--tail — задает количество последних строк текста;
-f — указывает, что необходимо следить за обновлением лог-файла.

Текст лог-файла nodeosd должен также содержать информацию о сгенерированных блоках, а также о блоках, принимаемых из Testnet. Информация в лог-файле о сгенерированном блоке должна иметь следующий вид:

info  2019-03-07T06:57:09.024 thread-0  producer_plugin.cpp:1491      produce_block        ] Produced block 00000c992d36ab56... #3225 @ 2019-03-07T06:57:09.000 signed by producera [trxs: 0, lib: 2564, confirmed: 0]

Информация в лог-файле о получаемых по сети блоках должна иметь следующий вид:

info  2019-03-07T06:57:00.096 thread-0  producer_plugin.cpp:344       on_incoming_block    ] Received block 6d6ac52bfe754174... #3222 @ 2019-03-07T06:57:00.000 signed by cyber [trxs: 0, lib: 2562, conf: 0, latency: 96 ms]

При успешном старте тестнета в лог-файл периодически сохраняется информация о полученных по сети блоках.

3.5. Рекомендуется:
В случае появления ошибок во время запуска контейнера рекомендуется остановить функционирование сервисов, удалить Docker volume и создать его заново.
Для останова функционирования сервисов исполнить:

sudo docker-compose down

Для удаления Docker volume необходимо испольнить следующую команду:

sudo docker volume rm cyberway-mongodb-data cyberway-nodeos-data

Для повторного создания Docker volume необходимо заново выполнить указания, начиная с п. 3.1. В случае наличия ошибок при повторном создании Docker volume следует сообщить об этом команде разработчиков CyberWay.

Раздел_4 Подключение к узлу

Подключение и работа с блокчейном выполняется с помощью утилиты cleos. Перед выполнением данной инструкции убедиться, что в лог-файл nodeosd прекращено поступление новой информации и что его текст не содержит сообщения об ошибках. Утилита cleos требует для своей работы запущенный сервис по сохранению приватных ключей keosd. Сервис keosd запускается на компьютере пользователя. Один из вариантов запуска keosd/cleos является их запуск в виде Docker контейнера. Для этого необходимо:

4.1. Запустить сервис keosd и подключить его к Docker-сети, в которой запущен nodeos:

sudo docker run -ti -d --name keosd --net cyberway-net cyberway/cyberway:stable /opt/cyberway/bin/keosd

4.2. Прописать alias для запуска cleos в контейнере keosd:

alias cleos='sudo docker exec -ti keosd cleos --url http://nodeosd:8888 '

4.3. Проверить успешное подключение к блокчейну. Для этого необходимо исполнить команду:

cleos get info

Подключение считается успешным, если во время выполнении команды не возникали ошибки.
4.4. Создать хранилище для личных ключей:

cleos wallet create --file wallet.pass

В случае прекращения использования хранилища, сервис keosd автоматически его блокирует. После этого хранилище может быть разблокировано с помощью команды:

cleos wallet unlock --password `sudo docker exec -ti keosd cat wallet.pass`

4.5. Импортировать личный ключ с помощью команды:

cleos wallet import --private-key <private-key>

Раздел_5 Перечень команд, применяемых к любому виду контейнера

Ниже приведен перечень команд, которые могут быть использовании в работе с любым видом контейнера.

5.1. Установление соединения с docker и запускается контейнера:

sudo docker exec -ti nodeosd /bin/bash

5.2. Получение текста лог-файла о контейнере:

sudo docker logs --tail 10 -f nodeosd

5.3. Подключение через cleos к узлу (ноде) для проверки его успешного функционирования (для выполнения данной инструкции необходимо, чтобы был сконфигурирован кошелек wallet):
sudo docker exec -ti nodeosd
/opt/cyberway/bin/cleos

5.4. Команда запуска контейнеров (команда выполняется из директории, в которой находится файл docker-compose.yml):

sudo docker start nodeosd mongo

5.5. Команда останова контейнеров (команда выполняется из директории, в которой находится файл docker-compose.yml):

sudo docker stop nodeosd mongo

Используемая терминология

Аккаунт (англ. account) — хранимая в системе учетная запись пользователя для его опознавания (аутентификации) и предоставления доступа к его личным данным и настройкам.
Блок или блок транзакций — специальная структура для записи группы транзакций в системе Биткойн и аналогичных ей. Блок состоит из заголовка и списка транзакций. Заголовок блока включает в себя свой хэш, хэш предыдущего блока, хеши транзакций и дополнительную служебную информацию.
Блокчейн (англ. block chain) — строго структурированная база данных с определенными правилами построения цепочек транзакций и доступа к информации, которая исключает кражу данных, мошенничество, нарушение имущественных прав и т. д.
Блок-продюсер (англ. witness) — пользователь блокчейна, наделенный определенными полномочиями. Используя свое (арендованное) оборудование, обеспечивает функционирование Узлов (нод) сети, создает и подписывает новые блоки, обеспечивая безопасность сети.
Валидатор (англ. validator) — пользователь блокчейна CyberWay, который подключается к Testnet с целью проверки правильного его функционирования. Валидатор принимает и обрабатывает блоки. К ноде можно подключиться в режиме валидатора для того, что получать от нее блоки.
Генезис (греч. genesis)— начало формирования какого-либо объекта или субъекта и последующий процесс его развития, приведший к определенному состоянию.
Демон (англ. daemon) — программа в системах семейства Linux, запускаемая самой системой и работающая в фоновом режиме без прямого взаимодействия с пользователем.
Личный ключ (англ. private key) — кодовая строка, при помощи которой осуществляется доступ к кошельку или биткоин-адресу. Необходима для осуществления транзакций.
Ключ (англ. key) — строка символов (битовая строка), используемая криптографическим алгоритмом при шифровании и дешифровании сообщений, постановке и проверке цифровой подписи, а также идентификации. Ключи бывают симметричные (один и тот же ключ используется для шифрования и дешифрования) и ассиметричные (публичный и личный).
Контейнер — объект, создаваемый с помощью Docker-образа и содержащий все необходимые компоненты для работы приложения. Контейнер является безопасной платформой для функционирования приложения.
Кошелек (англ. wallet) —  программное приложение, позволяющее производить транзакцию с заданного адреса и просматривать его баланс.
Плагин (англ. plugin) — программный компонент, выполненный в виде отдельного модуля и являющийся дополнением к основной программе.
Публичный ключ (англ. public key)  —  кодовая строка, к которой имеется открытый доступ. Используется наряду с секретным личным ключом для отправки транзакций. Публичный ключ соответствует биткоин-адресу.
Узел (англ. node) — отдельное (программное) устройство, подключаемое к сети блокчейн по схеме клиент-сервер. Узлы являются активными элементами и составляют основу технологии сети блокчейн.
Cleos (cli + eos = cleos) — интерфейс командной строки для взаимодействия с блокчейном и для управления кошельками.
Docker — программное обеспечение для автоматизации установки приложения в среде виртуализации на уровне операционной системы. Обеспечивает установку приложения со всем его окружением и зависимостями в контейнер, который может быть перенесён на любую Linux-систему с поддержкой cgroups в ядре, а также предоставляет среду по управлению контейнером.
Docker-compose — инструмент командной строки для управления несколькими мульти-контейнерами приложений Docker.
Docker-образ — шаблон платформы Docker, доступный только по чтению и используемый для создания контейнеров.
Docker-файл (англ. dockerfile) — файл, содержащий инструкции и параметры для создания Docker-образа под конкретные задачи.
Keosd (key + eos = keosd) — компонент, который надежно хранит ключи EOSIO в кошельках.

Nodeos (node + eos = nodeos) — базовый демон узла EOSIO, который можно настроить с помощью плагинов для запуска узла. Примеры использования: производство блоков, выделенные конечные точки API и локальная разработка.
P2P (англ. Peer to Peer)  —  одноранговая компьютерная сеть, в которой все участники (узлы) равноправны и могут взаимодействовать друг с другом, являясь клиентом и сервером одновременно.