Installation and usage of the platform
General platform configuration: execution of smart contracts¶
A number of parameters for working with smart contracts are configured in the following sections of the node configuration file:
node.docker-engine
– general execution parameters for Docker smart contracts,node.corporate-features.tls.docker
– TLS settings for the link to a Docker host,node.wasm
– WASM smart contracts execution parameters.
Docker smart contracts execution configuration¶
If you are going to develop and execute Docker smart contracts in your blockchain, set their execution parameters in the node.docker-engine and node.corporate-features.tls.docker sections of the node configuration file as described in the following subsections.
General configuration for Docker smart contracts¶
This subsection describes the general execution parameters for Docker smart contracts:
# 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
– flag to enable transaction processing for Docker contracts;docker-host
– Docker daemon address (optional parameter). If this field is commented out, the address of the daemon for smart contracts execution will be taken from the system environment;use-node-docker-host
– set the parameter toyes
to define the IP address of the gRPC API available to the contracts. This will read the IP address from the/etc/hosts
file inside the node container. Also, in order for the contracts to be able to access the node, their containers, when created, will be attached to the same Docker network in which the node container was created;contracts-parallelism
– the parameter determines the number of parallel transactions of all containerized smart contracts. The default value is8
;execution-limits
– contract execution settings section:startup-timeout
– time taken to create a contract container and register it in the node (in seconds);timeout
– time allocated for contract execution; the field specifies the value of the parameter and units of measurement;memory
– memory limit for the contract container (in megabytes);memory-swap
– allocated amount of virtual memory for the contract container (in megabytes);
remove-container-after
– the time interval of container inactivity, after which it will be removed;remote-registries
– Docker registry addresses and their authorization settings;check-registry-auth-on-startup
– authorization verification for Docker registries at node startup. To enable the option, specifyyes
, to disable it specifyno
;default-registry-domain
– default Docker registry address – optional parameter. This parameter is used if no repository is specified in the contract image name;contract-execution-messages-cache
– section for contract execution results messages cache settings; these messages contain transaction execution statuses of Docker contracts. The messages are cached, the size of the cache is limited by themax-size
parameter. The messages are also distributed during validation to then make a decision whether to execute the contract or not; this is determined by thecontract-error-quorum
parameter described below:max-size
– size limit of the cache of messages on contract execution result;expire-after
– time to store the smart contract status;max-buffer-size
andmax-buffer-time
– settings of cache buffer size and time for storing statuses in the cache buffer; these settings make it convenient to split the flow of messages either by number or by time;utx-cleanup-interval
– when the specified interval elapses, invalid transactions (withError
status) are removed from the UTX pool of a non-miner node.1m
is used by default;contract-error-quorum
– the minimum number of messages in which the status of a smart contract call transaction contains a business error (Error) received from different miner-nodes; after the number is reached, the smart-contract call transaction is removed from the UTX pool of a non-miner node. In other words, when there are enough messages in the cache that a contract has failed, the node removes it from the UTX. The default value is2
;ignore-successful
– when the parameter is set totrue
, the node ignores positive contract execution statuses it receives over the network and does not broadcast its positive statuses when mining contracts. This parameter helps to offload the network layer under load. The default value isfalse
;
contract-auth-expires-in
– lifetime of the authorization token used by smart contracts for calls to the node;grpc-server
– this section holds gRPC server settings for Docker contracts to work with the gRPC API:host
– node network address – optional parameter;port
– gRPC server port. Specify the gRPC request listening port used by the platform;
remove-container-on-fail
– to remove a container in case an error occurred during its startup, specifyyes
; otherwise specifyno
;circuit-breaker
– section of Circuit Breaker pattern settings. In the case of the Waves Enterprise blockchain platform, Circuit Breaker is a special “layer” between the contract executor in the node and the container (as well as the Docker host when the container is created):max-failures
– the maximum number of consecutive errors; when this number is reached, Circuit Breaker switches to theOpen
status;contract-opening-limit
– the maximum number of consecutive Circuit Breaker openings for a particular contract image. After the limit is reached, transactions are immediately removed from the UTX pool if an error occurs;opened-breakers-limit
– the maximum number of open Circuit Breakers (for all contracts processed by the node). After the limit is reached, transactions are immediately removed from the UTX pool if an error occurs;expire-after
– if the contract has never been executed during that time, Circuit Breaker resets its state to save memory;reset-timeout
– the initial timeout Circuit Breaker awaits in theOpen
status to provide an opportunity to conduct atrial
contract execution;exponential-backoff-factor
– multiplier by whichreset-timeout
is increased in case Circuit Breaker status changes fromHalfOpen
toOpen
;max-reset-timeout
– the maximum possible value ofreset-timeout
when it is successively increased byexponential-backoff-factor
times.
TLS configuration for Docker smart contracts¶
To work with Docker smart contracts, a node uses two connection types, for each of which you can configure TLS:
Connection to the Docker host, the remote machine on which smart contracts are run. This machine uses a Docker library that accesses the socket using its protocols. You can enable the secure connection option for it. Such a connection is referred to as “Docker-TLS” in this documentation. The Docker-TLS connection is configured in the
node.corporate-features.tls.docker
section of the node configuration file; this setting is described below in this section;The connection the running smart contract opens towards the node using gRPC protocol. This is an API connection as the connection point of the smart contract to the node is the same as for any other user or application. This API is configured in the
node.api.grpc
section. For instance, you can enable or disable TLS for it. You can find an example of such a configuration in the Examples of node configuration files section.
Note
The TLS protocol is not available in the opensource version of the platform.
The execution parameters for Docker smart contracts in the corporate-features.tls
section of the node configuration file are as follows:
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
– the flag indicating whether TLS is enabled or disabled; if you specifyyes
, certificates are searched for in the directory specified in thecerts-path
parameter; if you specifyno
, certificates are not searched for.certs-path
– the path to the directory where TLS certificates are stored.{node.directory}/certificates
is used by default.
WASM smart contracts execution configuration¶
If you are going to develop and execute WASM smart contracts in your blockchain, set their execution parameters in the node.wasm
section of the node configuration file:
wasm
{
fuel-limit = 20000
}
fuel-limit
– limit on the number of contract execution conventional units (similar to gas for Ethereum). One bytecode instruction corresponds to one unit of fuel. Use the parameter to limit the time of a WASM smart contract transaction execution by a virtual machine, thus excluding cases where the contract could be performed infinitely.