Установка и использование платформы

Общая настройка платформы: настройка исполнения смарт-контрактов¶

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

node.docker-engine – общие параметры исполнения Docker смарт-контрактов,
node.corporate-features.tls.docker – настройки TLS для соединения с Docker-хостом,
node.wasm – параметры исполнения WASM смарт-контрактов.

Настройка исполнения Docker смарт-контрактов¶

Если вы планируете разработку и исполнение Docker смарт-контрактов в вашем блокчейне, настройте параметры их исполнения в секциях node.docker-engine и node.corporate-features.tls.docker конфигурационного файла ноды, как описано в следующих подразделах.

Общие настройки Docker смарт-контрактов¶

В этом подразделе описаны общие параметры исполнения Docker смарт-контрактов:

# Docker smart contracts settings
docker-engine {
  # Docker smart contracts enabled flag
  enable = yes

  # Basic auth credentials for docker host (if it is behind some proxy, for example)
  # docker-auth {
  #   username = "some user"
  #   password = "some password"
  # }

  # Optional connection string to docker host for contracts execution.
  # If it is not set then it will be read from system environment
  # docker-host = "unix:///var/run/docker.sock"

  # Optional string to node REST API if remote docker host is used (set by 'docker-host' setting)
  # node-rest-api = "https://clinton.weservices.com/node-0"

  # Use the same docker host to start contracts containers this node application is started on.
  # Must be enabled, if node is started in docker container and 'docker-host' setting is not set
  use-node-docker-host = yes

  # Maximum number of concurrently executing contracts
  contracts-parallelism = 8

  # Execution settings
  execution-limits {
    # Separate timeout for contract container startup
    startup-timeout = 10s
    # Contract execution timeout. Must be less than 'average-block-delay' for PoS or 'round-duration' for PoA
    timeout = 5s
    # Memory limit in Megabytes
    memory = 512
    # Memory swap value in Megabytes (see https://docs.docker.com/config/containers/resource_constraints/)
    memory-swap = 0
  }
  # Remove contract container after specified duration passed and no contract calls was during this time
  remove-container-after = 10m
  # Remote registries auth information
  remote-registries = [
    {
     domain = "myregistry.com:5000"
     username = "user"
     password = "password"
    }
  ]
  # Check registry auth on node startup
  check-registry-auth-on-startup = yes
  # Optional default registry domain to pull images from if just contract name is set
  # default-registry-domain = "registry.wvservices.com"
  # Contract execution messages cache settings
  contract-execution-messages-cache {
    # Maximum messages count in cache
    max-size = 100000
    # Time to expire for messages in cache
    expire-after = 60m
    # Max number of messages in buffer. When the limit is reached, the node processes all messages in batch
    max-buffer-size = 10
    # Max time for buffer. When time is out, the node processes all messages in batch
    max-buffer-time = 100ms
    # Interval between the utx pool cleanup for executable transactions with error status.
    utx-cleanup-interval = 1m
    # Required number of error statuses to remove a transaction from the utx pool.
    contract-error-quorum = 2
    # Propagate only failed execution messages
    ignore-successful = false
  }
  # Expiration time for token given to contract
  contract-auth-expires-in = 1m
  # gRPC server settings
  grpc-server {
    # Optional node host if we use remote docker host (set by 'docker-host' setting)
    #host = "192.168.65.2"
    port = 6865
  }
  # Remove (or not) container if it failed. Useful for debug
  remove-container-on-fail = yes
  # CircuitBreaker settings
  circuit-breaker {
    # The maximum count for allowed failures before opening the circuit breaker
    max-failures = 10
    # Limit on the number of open circuit-breaker events per contract. When the limit is exceeded, the contract transactions will be removed from the UTX.
    contract-opening-limit = 5
    # Limit on the opened circuit-breakers. When the limit is exceeded, transactions of all contracts will be removed from the UTX.
    opened-breakers-limit = 100
    # Time to expire for contract circuit-breaker if it hasn't got access during this time
    expire-after = 4h
    # The timespan to wait in the `Open` state before attempting a close of the circuit breaker
    reset-timeout = 5s
    # A factor to use for resetting the resetTimeout when in the `HalfOpen` state, in case the attempt for `Close` fails
    exponential-backoff-factor = 2
    # The maximum timespan the circuit breaker is allowed to use
    max-reset-timeout = 1m
  }
}

enable – флаг включения обработки транзакций для Docker-контрактов;
docker-host – адрес демона Docker – опциональный параметр. Если это поле закомментировано, адрес демона для исполнения смарт-контрактов будет взят из системного окружения;
use-node-docker-host – задайте параметру значение yes, чтобы определить IP-адрес gRPC API, доступного контрактам. При этом IP-адрес будет считан из файла /etc/hosts внутри контейнера ноды. Также для того чтобы контракты могли обращаться к ноде, их контейнеры при создании будут присоединены к той же Docker сети (Docker network), в которой создан контейнер ноды;
contracts-parallelism – параметр определяет количество параллельно выполняемых транзакций всех контейнеризированных смарт-контрактов. По умолчанию параметр имеет значение 8;
execution-limits – секция настроек исполнения контракта:
- startup-timeout – время, отводимое на создание контейнера контракта и его регистрацию в ноде (в секундах);
- timeout – время, отводимое на выполнение контракта; в поле указывается значение параметра и единицы измерения;
- memory – ограничение по памяти для контейнера контракта (в мегабайтах);
- memory-swap – выделяемый объем виртуальной памяти для контейнера контракта (в мегабайтах);
remove-container-after – промежуток времени бездействия контейнера, по прошествии которого он будет удален;
remote-registries – адреса Docker-репозиториев и настройки авторизации к ним;
check-registry-auth-on-startup – проверка авторизации для Docker-репозиториев при запуске ноды. Включение опции – yes, отключение – no;
default-registry-domain – адрес Docker-репозитория по умолчанию – опциональный параметр. Этот параметр используется, если в имени образа контракта не указан репозиторий;
contract-execution-messages-cache – секция настроек кэша сообщений о результате выполнения контракта; эти сообщения содержат статусы исполнения транзакций по Docker контрактам. Сообщения кэшируются, размер кэша ограничивается значением параметра max-size. Также они рассылаются при валидации, чтобы затем принимать решение об исполнении контракта; за это отвечает параметр contract-error-quorum, описанный ниже:
- max-size – ограничение размера кэша сообщений о результате выполнения контракта;
- expire-after – время хранения статуса смарт-контракта;
- max-buffer-size и max-buffer-time – настройки объема буфера кэша и времени хранения статусов в буфере кэша; эти настройки позволяют удобно разбить поток сообщений либо по количеству, либо по времени;
- utx-cleanup-interval – интервал, по прошествии которого невалидные транзакции (со статусом Error) удаляются из UTX-пула ноды, которая не является майнером. Значение по умолчанию – 1m;
- contract-error-quorum – минимальное количество полученных от разных нод-майнеров сообщений, в которых статус транзакции по вызову смарт-контракта содержит бизнес-ошибку (Error); когда указанное в параметре количество сообщений получено, транзакция удаляется из UTX-пула ноды, которая не является майнером. То есть когда в кэше набирается достаточно сообщений о том, что контракт не исполнился, нода удаляет его из UTX. Значение по умолчанию – 2;
- ignore-successful – когда задано значение true, нода игнорирует положительные статусы исполнения контракта, приходящие ей по сети, и не распространяет свои положительные статусы при майнинге контрактов. Этот параметр нужен для того, чтобы разгрузить сетевой слой при нагрузке. По умолчанию параметр имеет значение false;
contract-auth-expires-in – время жизни токена авторизации, используемого смарт-контрактами для вызовов к ноде;
grpc-server – секция настроек gRPC сервера для работы Docker-контрактов с gRPC API:
- host – сетевой адрес ноды – опциональный параметр;
- port – порт gRPC-сервера. Укажите порт прослушивания gRPC-запросов, использующийся платформой;
remove-container-on-fail – удаление контейнера, если при его старте произошла ошибка. Включение опции – yes, отключение – no;
circuit-breaker – секция настроек паттерна Circuit Breaker. Circuit Breaker в случае блокчейн платформы Waves Enterprise представляет собой промежуточное звено между исполнителем контрактов в ноде и контейнером (а также докер-хостом при создании контейнера):
- max-failures – максимальное число последовательных ошибок, по достижении которого Circuit Breaker переходит в статус Open;
- contract-opening-limit – максимальное число подряд идущих открытий Circuit Breaker для конкретного образа контракта. После достижения лимита транзакции при возникновении ошибки сразу удаляются из UTX-пула;
- opened-breakers-limit – максимальное число открытых Circuit Breaker (для всех контрактов, которые обрабатывает нода). После достижения лимита транзакции при возникновении ошибки сразу удаляются из UTX-пула;
- expire-after – если в течении этого времени контракт ни разу не выполнился, то Circuit Breaker сбрасывает свое состояние для экономии памяти;
- reset-timeout – первоначальный временной интервал, в течение которого Circuit Breaker ожидает в статусе Open, чтобы предоставить возможность провести «пробное» исполнение контракта;
- exponential-backoff-factor – множитель, на который увеличивается reset-timeout в случае перехода Circuit Breaker из статуса HalfOpen в статус Open;
- max-reset-timeout – максимально возможное значение reset-timeout при последовательном увеличении в exponential-backoff-factor раз.

Настройка TLS для Docker смарт-контрактов¶

Для работы с Docker смарт-контрактами нода использует два типа соединения, для каждого из которых можно настроить TLS:

Соединение с Docker-хостом – удалённой машиной, на которой запускаются смарт-контракты. На этой машине используется Docker-библиотека, которая обращается на сокет по своим протоколам. Для неё можно включить опцию безопасного соединения, которое в этой документации обозначается как «Docker-TLS». Соединение Docker-TLS настраивается в секции node.corporate-features.tls.docker конфигурационного файла ноды; эта настройка описана ниже в этом разделе;
Соединение, которое открывает запущенный смарт-контракт в сторону ноды по протоколу gRPC. Это подключение по API, так как точка подключения смарт-контракта к ноде такая же, как и для любого другого пользователя или приложения. Этот API настраивается в секции node.api.grpc, в частности для него можно настроить TLS. Пример такой настройки дан в разделе Примеры конфигурационных файлов ноды.

Примечание

Протокол TLS недоступен в opensource версии платформы.

Параметры исполнения Docker смарт-контрактов в секции corporate-features.tls конфигурационного файла ноды выглядят следующим образом:

corporate-features {
    tls {
        internal {
            # Supported TLS types:
            # EMBEDDED: Certificate is signed by node's provider and packed into JKS Keystore.
            #           The same file is used as a Truststore.
            #           Has to be manually imported into system by user to avoid certificate warnings.
            # GOST: Certificate is signed by node's provider and packed into GOST Truststore with either
            #       type HDIMAGE or CertStore.
            #       The only currently supported Keystore type is HDIMAGE
            # DISABLED: TLS is fully DISABLED
            type = DISABLED

            # type = EMBEDDED
            # keystore-path = ${node.directory}"/we_tls.jks"
            keystore-password = ${?TLS_KEYSTORE_PASSWORD}
            private-key-password = ${?TLS_PRIVATE_KEY_PASSWORD}

            # type = GOST
            # keystore-type = "HDIMAGE"
            # keystore-password = ${?TLS_KEYSTORE_PASSWORD}
            # truststore-type = "CertStore"
            # truststore-path = "trust-store"
            # required-client-oids = ["1.3.6.1.4.1.8.1.1", "1.3.6.1.4.1.9.2.2"]
            truststore-password = ${?TLS_TRUSTSTORE_PASSWORD}

            # Supported modules:
            #    "PEER-API" - Binary P2P protocol;
            #    "REST-API" - REST API;
            #    "GRPC-API" - gRPC API and gRPC Contract API.
            # Value example: [ "PEER-API", "REST-API" ]
            modules = []
        }

        # Optional params for tls connection, overwrite system environmen variables
        docker {
             verification = yes
             cert-path = ${node.directory}"/certificates"

               }
        }
    }

verification – флаг, указывающий на включение или выключение TLS; если задано значение yes, то выполняется поиск сертификатов в директории, указанной в certs-path; если задано значение no, то поиск сертификатов не выполняется.
certs-path – путь до директории с сертификатами для TLS; по умолчанию параметр имеет значение {node.directory}/certificates.

Настройка исполнения WASM смарт-контрактов¶

Если вы планируете разработку и исполнение WASM смарт-контрактов в вашем блокчейне, настройте параметры их исполнения в секции node.wasm конфигурационного файла ноды:

wasm
  {
    fuel-limit = 20000
  }

fuel-limit – лимит по количеству условных единиц исполнения контракта (по аналогии с газом для эфира). Одна инструкция bytecode соответствует одной единице fuel. Параметр позволяет ограничить время исполнения транзакции WASM смарт-контракта виртуальной машиной; таким образом исключаются случаи, когда контракт мог бы исполняться бесконечно.