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:

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 to yes 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 is 8;

  • 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, specify yes, to disable it specify no;

  • 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 the max-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 the contract-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 and max-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 (with Error 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 is 2;

    • ignore-successful – when the parameter is set to true, 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 is false;

  • 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, specify yes; otherwise specify no;

  • 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 the Open 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 the Open status to provide an opportunity to conduct a trial contract execution;

    • exponential-backoff-factor – multiplier by which reset-timeout is increased in case Circuit Breaker status changes from HalfOpen to Open;

    • max-reset-timeout – the maximum possible value of reset-timeout when it is successively increased by exponential-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:

  1. 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;

  2. 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 specify yes, certificates are searched for in the directory specified in the certs-path parameter; if you specify no, 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.

See also