Coopos

Important

Coopos - операционная система смарт-контрактов платформы Кооперативной Экономики (https://coopenomics.world).

1. Ветки
2. Быстрый старт с Docker
3. Поддерживаемые операционные системы
4. Бинарная установка
5. Сборка и установка из исходного кода
6. Bash автодополнение

Coopos - это C++ реализация протокола Antelope с расширениями для кооперативной экономики. Содержит программное обеспечение блокчейн-узла и вспомогательные инструменты для разработчиков и операторов узлов.

Ветки

Ветка main является веткой разработки; не используйте её для продакшена. Обратитесь к странице релизов для получения актуальной информации о релизах, предварительных релизах и устаревших релизах, а также соответствующих тегах для этих релизов.

Быстрый старт с Docker

Для быстрого знакомства с Coopos и разработки смарт-контрактов на любой операционной системе (Windows, macOS, Linux) рекомендуется использовать готовый Docker-контейнер.

Запуск контейнера

docker run -it --rm \
  -v $(pwd)/workspace:/workspace \
  -p 8888:8888 \
  -p 9876:9876 \
  -p 8070:8070 \
  dicoop/blockchain_v5.1.1:dev

Что включено в контейнер

Контейнер основан на том же исходном коде Coopos и дополнительно содержит:

• CDT (Contract Development Toolkit) - инструменты для компиляции смарт-контрактов
• eosio-cpp - компилятор смарт-контрактов
• cleos - командная строка для взаимодействия с блокчейном
• nodeos - блокчейн-узел
• leap-util - дополнительные утилиты
• Все необходимые зависимости для разработки и запуска

Использование

# В контейнере вы можете сразу начать разработку
cd /workspace

# Создать новый смарт-контракт
eosio-cpp -abigen hello.cpp -o hello.wasm

# Запустить локальный блокчейн-узел с полным набором параметров
nodeos \
  # Основные плагины для работы блокчейн-узла
  --plugin eosio::chain_plugin \
  --plugin eosio::producer_plugin \
  --plugin eosio::chain_api_plugin \
  --plugin eosio::http_plugin \
  --plugin eosio::state_history_plugin \
  --plugin eosio::producer_api_plugin \
  --plugin eosio::resource_monitor_plugin \
  # Настройки производства блоков
  --enable-stale-production true \
  --read-only-read-window-time-us 120000 \
  --producer-name eosio \
  --producer-name core \
  --signature-provider EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV=KEY:5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3 \
  # Сетевые настройки
  --net-threads 2 \
  --p2p-listen-endpoint 0.0.0.0:9876 \
  # HTTP API настройки
  --http-server-address 0.0.0.0:8888 \
  --access-control-allow-origin "*" \
  --access-control-allow-credentials false \
  --http-validate-host false \
  --verbose-http-errors true \
  --http-max-response-time-ms 30000 \
  --max-body-size 10485760 \
  # Настройки производительности и лимитов
  --max-transaction-time 2000 \
  --abi-serializer-max-time-ms 200000 \
  --max-block-cpu-usage-threshold-us 5000 \
  --max-block-net-usage-threshold-bytes 1024 \
  # Отладка и история
  --contracts-console true \
  --chain-state-history true \
  --trace-history true \
  --state-history-endpoint 0.0.0.0:8070 \
  # Мониторинг ресурсов
  --resource-monitor-space-threshold 90 \
  --resource-monitor-not-shutdown-on-threshold-exceeded true \
  # WASM runtime
  --wasm-runtime eos-vm

Монтирование рабочей директории

Параметр -v $(pwd)/workspace:/workspace монтирует вашу локальную папку workspace в контейнер, позволяя работать с файлами на хост-системе.

⚠️ Важно: Для регулярной стабильной работы и продакшена рекомендуется установка deb-пакета или сборка из исходного кода на нативной системе. Docker-контейнер предназначен для разработки и тестирования.

Поддерживаемые операционные системы

В настоящее время мы поддерживаем следующие операционные системы:

• Ubuntu 22.04 Jammy
• Ubuntu 20.04 Focal

Другие Unix-производные, такие как macOS, поддерживаются в режиме best-effort и могут быть не полностью функциональными. Если вы не используете Ubuntu, посетите страницу "Сборка неподдерживаемой ОС" для изучения ваших вариантов.

Если вы используете неподдерживаемую производную Ubuntu, такую как Linux Mint, вы можете узнать версию Ubuntu, на которой она основана, используя эту команду:

cat /etc/upstream-release/lsb-release

Ваш лучший вариант - следовать инструкциям для вашей базовой версии Ubuntu, но мы не даём никаких гарантий.

Бинарная установка

Это самый быстрый способ начать работу. Со страницы последнего релиза скачайте бинарный файл для одной из наших поддерживаемых операционных систем, или посетите теги релизов для скачивания бинарного файла конкретной версии Coopos.

После того, как вы скачали файл *.deb для вашей версии Ubuntu, вы можете установить его следующим образом:

sudo apt-get update
sudo apt-get install -y ~/Downloads/coopos*.deb

Ваш путь загрузки может отличаться. Если вы находитесь в Ubuntu docker контейнере, опустите sudo, поскольку вы работаете как root по умолчанию.

Наконец, проверьте, что Coopos был установлен корректно:

nodeos --full-version

Вы должны увидеть строку семантической версии, за которой следует git commit hash без ошибок. Например:

v5.1.0-abc123def456...

Сборка и установка из исходного кода

Вы также можете собрать и установить Coopos из исходного кода.

Системные требования

Требования к сборке

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

• Процессор: минимум 4 ядра (рекомендуется 8 ядер)
• Оперативная память: минимум 8 GB RAM (рекомендуется 16 GB)
• Дисковое пространство: минимум 20 GB для сборки и тестов

При меньших ресурсах сборка может быть невозможна или крайне медленной. Некоторые этапы компиляции требуют значительных ресурсов памяти.

Требования к работе

Для работы блокчейн-узла Coopos достаточно:

• Процессор: минимум 2 ядра
• Оперативная память: минимум 4 GB RAM
• Дисковое пространство: зависит от высоты цепочки блоков. На текущий момент для основной сети кооперативной экономики требуется около 20 GB, поэтому минимально рекомендуется 40 GB, оптимально - 160 GB для комфортной работы и хранения истории.

Предварительные требования

Вам нужно собирать на поддерживаемой операционной системе.

Требования для сборки:

• Компилятор C++20 и стандартная библиотека
• CMake 3.16+
• LLVM 7 - 11 - только для Linux
  • более новые версии не работают
• libcurl 7.40.0+
• git
• GMP
• Python 3
• python3-numpy
• zlib

Шаг 1 - Клонирование

Если у вас ещё не клонирован репозиторий Coopos, откройте терминал и перейдите в папку, где хотите клонировать репозиторий Coopos:

cd ~/Downloads

Клонируйте Coopos используя либо HTTPS...

git clone --recursive https://github.com/AntelopeIO/leap.git

...либо SSH:

git clone --recursive git@github.com:AntelopeIO/leap.git

ℹ️ HTTPS vs. SSH Clone ℹ️
И HTTPS, и SSH клонирование дадут одинаковый результат - папку с именем leap, содержащую наш исходный код. Не важно, какой тип вы используете.

Перейдите в эту папку:

cd leap

Шаг 2 - Переключение на тег релиза или ветку

Выберите, какой релиз или ветку вы хотите собрать, затем переключитесь на неё. Если вы не уверены, используйте последний релиз. Например, если вы хотите собрать релиз 5.1.0, то переключитесь на его тег v5.1.0. В примере ниже замените v0.0.0 на выбранный вами тег релиза:

git fetch --all --tags
git checkout v5.1.0

После того, как вы находитесь на ветке или теге релиза, который хотите собрать, убедитесь, что всё обновлено:

git pull
git submodule update --init --recursive

Шаг 3 - Сборка

Выберите инструкции по сборке ниже для закреплённой сборки (предпочтительно) или незакреплённой сборки.

ℹ️ Закреплённая vs. Незакреплённая сборка ℹ️ У нас есть два типа сборок для Coopos: "закреплённая" и "незакреплённая". Закреплённая сборка - это воспроизводимая сборка с фиксированной средой сборки и версиями зависимостей, установленными командой разработчиков. В отличие от этого, незакреплённые сборки используют версии зависимостей, предоставляемые платформой сборки. Незакреплённые сборки обычно быстрее, потому что закреплённая среда сборки должна быть построена с нуля. Закреплённые сборки, помимо воспроизводимости, обеспечивают, чтобы компилятор оставался тем же между сборками разных основных версий Coopos. Coopos требует, чтобы версия компилятора оставалась той же, иначе его состояние может потребовать восстановления из портативного снимка или цепочка должна быть перезапущена.

⚠️ Предупреждение о параллельных задачах компиляции (флаг -j) ⚠️ При сборке программного обеспечения C/C++, часто сборка выполняется параллельно с помощью команды типа make -j "$(nproc)", которая использует все доступные потоки CPU. Однако учтите, что некоторые единицы компиляции (*.cpp файлы) в Coopos будут потреблять почти 4GB памяти. Сбои из-за исчерпания памяти обычно, но не всегда, проявляются как сбои компилятора. Использование всех доступных потоков CPU также может помешать вам делать другие вещи на вашем компьютере во время компиляции. По этим причинам рассмотрите возможность уменьшения этого значения.

🐋 Docker и sudo 🐋 Если вы находитесь в Ubuntu docker контейнере, опустите sudo из всех команд, поскольку вы работаете как root по умолчанию. Большинство других docker контейнеров также исключают sudo, особенно Debian-семейные контейнеры. Если ваш промпт оболочки - хэш-тег (#), опустите sudo.

Закреплённая воспроизводимая сборка

Закреплённая воспроизводимая сборка требует Docker. Убедитесь, что вы находитесь в корне репозитория leap, затем выполните

DOCKER_BUILDKIT=1 docker build -f tools/reproducible.Dockerfile -o . .

Эта команда займёт существенное время, потому что цепочка инструментов собирается с нуля. После завершения текущая директория будет содержать собранные .deb и .tar.gz файлы (вы можете изменить аргумент -o . для размещения вывода в другой директории). Если нужно уменьшить количество параллельных задач, как предупреждалось выше, выполните команду как:

DOCKER_BUILDKIT=1 docker build --build-arg LEAP_BUILD_JOBS=4 -f tools/reproducible.Dockerfile -o . .

Незакреплённая сборка

Следующие инструкции действительны для этой ветки. Другие ветки релизов могут иметь разные требования, поэтому убедитесь, что следуете указаниям в ветке или релизе, который собираетесь собирать. Если вы находитесь в Ubuntu docker контейнере, опустите sudo, поскольку вы работаете как root по умолчанию.

Установите зависимости:

sudo apt-get update
sudo apt-get install -y \
        build-essential \
        cmake \
        git \
        libcurl4-openssl-dev \
        libgmp-dev \
        llvm-11-dev \
        python3-numpy \
        file \
        zlib1g-dev

На Ubuntu 20.04 установите gcc-10, который имеет поддержку C++20:

sudo apt-get install -y g++-10

Для сборки убедитесь, что вы находитесь в корне репозитория leap, затем выполните следующую команду:

mkdir -p build
cd build

## на Ubuntu 20 укажите компилятор gcc-10
cmake -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_CXX_COMPILER=g++-10 -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/usr/lib/llvm-11 ..

## на Ubuntu 22 версия gcc по умолчанию 11, использование компилятора по умолчанию нормально
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=/usr/lib/llvm-11 ..

make -j "$(nproc)" package

Теперь вы можете опционально протестировать вашу сборку, или установить бинарные пакеты *.deb, которые будут в корне вашей директории сборки.

Шаг 4 - Тестирование

Coopos поддерживает следующие наборы тестов:

Набор тестов	Тип теста	Размер теста	Примечания
Параллелизуемые тесты	Модульные тесты	Маленький
WASM spec тесты	Модульные тесты	Маленький	Модульные тесты для нашего WASM runtime, каждый короткий но очень CPU-интенсивный
Сериальные тесты	Компонент/Интеграция	Средний
Долго выполняемые тесты	Интеграция	Средний-Крупный	Тесты, которые занимают чрезвычайно много времени на выполнение

При сборке из исходного кода мы рекомендуем запускать как минимум параллелизуемые тесты.

Параллелизуемые тесты

Этот набор тестов состоит из любых тестов, которые не требуют разделяемых ресурсов, таких как файловые дескрипторы, специфические папки или порты, и поэтому могут выполняться параллельно в разных потоках без побочных эффектов (следовательно, легко параллелизуемы). Это в основном модульные тесты и маленькие тесты, которые завершаются за короткое время.

Вы можете запустить их, выполнив ctest из терминала в вашей директории сборки Coopos и указав следующие аргументы:

ctest -j "$(nproc)" -LE _tests

WASM Spec тесты

WASM spec тесты проверяют, что наш движок выполнения WASM соответствует стандарту web assembly. Это очень маленькие, очень быстрые модульные тесты. Однако их более тысячи, так что набор может занять немного времени на выполнение. Эти тесты чрезвычайно CPU-интенсивны.

Вы можете запустить их, выполнив ctest из терминала в вашей директории сборки Coopos и указав следующие аргументы:

ctest -j "$(nproc)" -L wasm_spec_tests

Мы наблюдали серьёзные проблемы с производительностью, когда несколько виртуальных машин запускают этот набор тестов на одном физическом хосте одновременно, например в системе CICD. Это можно решить, отключив hyperthreading на хосте.

Сериальные тесты

Набор сериальных тестов состоит из средних компонентных или интеграционных тестов, которые используют специфические пути, порты, полагаются на имена процессов или подобное, и не могут выполняться параллельно с другими тестами. Сериальные тесты могут быть чувствительны к другому программному обеспечению, работающему на том же хосте, и они могут отправлять SIGKILL другим процессам nodeos. Эти тесты занимают умеренное время на завершение, но мы рекомендуем их запускать.

Вы можете запустить их, выполнив ctest из терминала в вашей директории сборки Coopos и указав следующие аргументы:

ctest -L "nonparallelizable_tests"

Долго выполняемые тесты

Долго выполняемые тесты - это средние-крупные интеграционные тесты, которые полагаются на разделяемые ресурсы и занимают очень много времени на выполнение.

Вы можете запустить их, выполнив ctest из терминала в вашей директории сборки Coopos и указав следующие аргументы:

ctest -L "long_running_tests"

Шаг 5 - Установка

После того, как вы собрали Coopos и протестировали вашу сборку, вы можете установить Coopos в вашу систему. Не забудьте опустить sudo, если вы работаете в docker контейнере.

Мы рекомендуем установить бинарный пакет, который вы только что собрали. Перейдите в вашу директорию сборки Coopos в терминале и выполните эту команду:

sudo apt-get update
sudo apt-get install -y ./leap[-_][0-9]*.deb

Также возможно установить используя make:

sudo make install

Bash автодополнение

cleos и leap-util предлагают существенный объём функциональности. Рассмотрите использование поддержки автодополнения bash, которая облегчает обнаружение всех их различных опций.

Для наших предоставленных .deb пакетов просто установите Ubuntu пакет bash-completion: apt-get install bash-completion (вам может понадобиться выйти и войти снова после установки).

Если собираете из исходного кода, установите файлы build/programs/cleos/bash-completion/completions/cleos и build/programs/leap-util/bash-completion/completions/leap-util в вашу директорию bash-completion. Обратитесь к документации bash-completion по возможным местам установки.