Preparing to work

In order to start working with containerized smart contracts, their execution should be set up.

Execution of smart contracts is set up in the node configuration file. There is also an opportunity to set up a used image for a separate smart contract with the use of the ref:103 CreateContractTransaction <CreateContractTransaction> transaction.

Setting up of Docker contracts execution in the node configuration file

This method allows to flexibly set up execution of all Docker contracts for the node. To do this, there is the docker-engine section in the node.conf file containing following configuration parameters:

  • enable – enable processing of transactions for all Docker contracts.

  • integration-tests-mode-enable – test mode for Docker contracts. With this option, smart contracts are executed locally in a container.

  • docker-host – docker daemon address (optional).

  • node-rest-api – path to the node REST API (optional).

  • startup-timeout – time period for creation of a gRPC contract container and its registration in the node (in seconds).

  • timeout – time period for contract execution (in seconds).

  • memory – memory limit for a contract container (in megabytes).

  • memory-swap – virtual memory for a contract container (in megabytes).

  • reuse-containers – using of the same container for multiple contracts that use the same Docker image.

  • remove-container-after – the time interval of container inactivity, after which it will be removed.

  • allow-net-access – allowing of access to the network.

  • remote-registries – address of Docker repositories and authorization settings for them.

  • check-registry-auth-on-startup – check of Docker repositories authorization on the node startup.

  • default-registry-domain – default address of a Docker repository (optional). This parameter is used, if a repository is not stated in the contract image name.

  • contract-execution-messages-cache – settings of the cache with statuses of execution of Docker contracts transactions;

  • expire-after – time period for storage of a smart contract status.

  • max-buffer-size and max-buffer-time – settings of volume and time for storage of status caches.

  • contract-auth-expires-in – lifetime of an authorization token used by smart contracts for node calls.

  • grpc-server – section of gRPC server settings for interaction of Docker contracts with the gRPC API.

  • host – node network address (optional).

  • port – gRPC port.

  • akka-http-settings – section for settings of the Akka HTTP framework, used for the gRPC server.

  • remove-container-on-fail – removing of a container if an error has taken place during its start.

The remote-registries parameters block can include addresses of multiple repositories. If this parameter is used, address of each repository should be stated for access to it, as well as username and password. In order to address to a definite repository from a list, the address of this repository should be stated in the Docker image name.

The default-registry-domain parameter is used in cases when a repository address is not stated in the Docker image name. If this parameter is used and the Docker image name includes a repository address, a smart contract refers to the repository stated in the image name.


If the repository path is stated with the use of the 103 CreateContractTransaction transaction, this path has a priority to the remote-registries` and default-registry-domain node parameters.

Example of the docker-engine section of the node configuration file

In this example, we consider a variant of the Docker contract execution with the repository address and its authorization settings (the remote-registries block is filled in, the default-registry-domain parameter is commented out). The standard Docker daemon and the node REST API are also used (the docker-host and node-rest-api parameters are commented out). Removal of a container in case of a startup error (parameter remove-container-on-fail) is enabled to find errors while working with smart contracts.

docker-engine {
  enable = yes
  integration-tests-mode-enable = no
  # docker-host = "unix:///var/run/docker.sock"
  # node-rest-api = ""
  execution-limits {
    startup-timeout = 10s
    timeout = 10s
    memory = 512
    memory-swap = 0
  reuse-containers = yes
  remove-container-after = 10m
  allow-net-access = yes
  remote-registries = [
     domain = ""
     username = "user"
     password = "password"
  check-registry-auth-on-startup = no
  # default-registry-domain = ""
  contract-execution-messages-cache {
    expire-after = 60m
    max-buffer-size = 10
    max-buffer-time = 100ms
  contract-auth-expires-in = 1m
  grpc-server {
    # host = ""
    port = 6865
    akka-http-settings {
        akka {
        http.server.idle-timeout = infinite
        http.client.idle-timeout = infinite = infinite = infinite
  remove-container-on-fail = yes

Setting up of definite Docker contract execution with the use of the 103 CreateContractTransaction

The 103 CreateContractTransaction transaction is used for creation of a Docker contract. While developing this transaction, there is an opportunity to set an image for execution of a smart contract created with the use of this transaction. To do this, following parameters are used:

  • image - name of a Docker image for a smart contract to be created.

  • image-hash - hash sum of a used Docker image.

  • contract-name - smart contract name.

  • password - password for access to a Docker repository (optional).


If only an image name is specified in the image field, the smart contract accesses the address specified in the remote-registries or default-registry-domain node configuration parameters and finds the Docker image specified in the image field of the transaction at that address. This field may also contain the full image address: in this case, the image at that address is used to execute the smart contract being created, and the corresponding node configuration parameters are not applied.

Example of setting up of Docker contract execution with the use of the 103 CreateContractTransaction

In the above example, we consider a transaction that creates a Docker contract from a separate image whose full address is specified in the image field. Accordingly, the addresses specified in the node configuration file will not be applied to this smart contract.

    "type": 103,
    "id": "ULcq9R7PvUB2yPMrmBdxoTi3bcRmQPT3JDLLLZVj4Ky",
    "sender": "3N3YTj1tNwn8XUJ8ptGKbPuEFNa9GFnhqew",
    "senderPublicKey": "3kW7vy6nPC59BXM67n5N56rhhAv38Dws5skqDsjMVT2M",
    "fee": 500000,
    "timestamp": 1550591678479,
    "proofs": [ "yecRFZm9iBLyDy93bDVaNo1PR5Qkkic7196GAgUt9TNH1cnQphq4yGQQ8Fxj4BYA4TaqYVw5qxtWzGMPQyVeKYv" ],
    "version": 1,
    "image": "",
    "imageHash": "7d3b915c82930dd79591aab040657338f64e5d8b842abe2d73d5c8f828584b65",
    "contractName": "stateful-increment-contract",
    "params": [],
    "height": 1619