Run.XML

Run.XML format is used to define a run-time configuration of a Rell node. The configuration consists of two key parts:

  1. The list of Postchain nodes (the target node is one of those nodes).
  2. The list of blockchains, each having an associated configuration(s) and a Rell application.

The format is used:

  • By Rell command-line utilities multirun.sh and multigen.sh.
  • By the Eclipse IDE (which internally uses multirun.sh to launch Postchain applications).

The Format

Example of a Run.XML file:

<run wipe-db="true">
    <nodes>
        <config src="config/node-config.properties" add-signers="false" />
    </nodes>
    <chains>
        <chain name="user" iid="1">
            <config height="0">
                <app module="user" />
                <gtv path="gtx/rell/moduleArgs/user">
                    <dict>
                        <entry key="foo"><bytea>0373599a61cc6b3bc02a78c34313e1737ae9cfd56b9bb24360b437d469efdf3b15</bytea></entry>
                    </dict>
                </gtv>
            </config>
            <config height="1000">
                <app module="user_1000">
                    <args module="user_1000">
                        <arg key="foo"><bytea>0373599a61cc6b3bc02a78c34313e1737ae9cfd56b9bb24360b437d469efdf3b15</bytea></arg>
                    </args>
                </app>
                <gtv path="path" src="config/template.xml"/>
            </config>
        </chain>
        <chain name="city" iid="2">
            <config height="0" add-dependencies="false">
                <app module="city" />
                <gtv path="signers">
                    <array>
                        <bytea>0350fe40766bc0ce8d08b3f5b810e49a8352fdd458606bd5fafe5acdcdc8ff3f57</bytea>
                    </array>
                </gtv>
                <dependencies>
                    <dependency name="user" chain="user" />
                </dependencies>
            </config>
            <include src="config/city-include-1.xml"/>
            <include src="config/city-include-2.xml" root="false"/>
        </chain>
    </chains>
</run>

Top-level elements are:

  • nodes - defines Postchain nodes
  • chains - defines blockchains

Nodes

Node configuration is provided in a standard Postchain node-config.properties format.

Specifying a path to an existing node-config.properties file (path is relative to the Run.XML file):

<nodes>
    <config src="config/node-config.properties" add-signers="false" />
</nodes>

Specifying node configuration properties directly, as text:

<nodes>
    <config add-signers="false">
        database.driverclass=org.postgresql.Driver
        database.url=jdbc:postgresql://localhost/postchain
        database.username=postchain
        database.password=postchain
        database.schema=test_app

        activechainids=1

        api.port=7740
        api.basepath=

        node.0.id=node0
        node.0.host=127.0.0.1
        node.0.port=9870
        node.0.pubkey=0350fe40766bc0ce8d08b3f5b810e49a8352fdd458606bd5fafe5acdcdc8ff3f57

        messaging.privkey=3132333435363738393031323334353637383930313233343536373839303131
        messaging.pubkey=0350fe40766bc0ce8d08b3f5b810e49a8352fdd458606bd5fafe5acdcdc8ff3f57
    </config>
</nodes>

Chains

A chain element can have multiple config elements and a dependencies element inside.

A single chain may have specific configurations assigned to specific block heights.

<config height="0" add-dependencies="false">
    <app module="city" />
    <gtv path="signers">
        <array>
            <bytea>0350fe40766bc0ce8d08b3f5b810e49a8352fdd458606bd5fafe5acdcdc8ff3f57</bytea>
        </array>
    </gtv>
</config>

An app element specifies a Rell application used by the chain. Attribute module is the name of the main module of the app. The source code of the main module and all modules it imports will be injected into the generated blockchain XML configuration.

Elements gtv are used to inject GTXML fragments directly into the generated Postchain blockchain XML configuration. Attribute path specifies a dictionary path for the fragment (default is root). For example, the fragment

<gtv path="gtx/rell/moduleArgs/user">
    <dict>
        <entry key="foo"><bytea>0373599a61cc6b3bc02a78c34313e1737ae9cfd56b9bb24360b437d469efdf3b15</bytea></entry>
    </dict>
</gtv>

will produce a blockchain XML:

<dict>
    <entry key="gtx">
        <dict>
            <entry key="rell">
                <dict>
                    <entry key="moduleArgs">
                        <dict>
                            <entry key="user">
                                <dict>
                                    <entry key="foo">
                                        <bytea>0373599A61CC6B3BC02A78C34313E1737AE9CFD56B9BB24360B437D469EFDF3B15</bytea>
                                    </entry>
                                </dict>
                            </entry>
                        </dict>
                    </entry>
                </dict>
            </entry>
        </dict>
    </entry>
</dict>

GTXML contents to be injected shall be either specified as a nested element of a gtv element, or placed in an XML file referenced via the src attribute.

Included files

Other XML files can be included anywhere in a Run.XML using include tag. Included files may include other XML files as well.

Including a file with its root element replacing the include element:

<include src="config/city-include-1.xml"/>

Including a file without its root element, the include is replaced by the child elements of the root element of the file:

<include src="config/city-include-2.xml" root="false"/>

Utilities

Those utilities are a part of the Rell language.

multirun.sh

Runs an application described by a Run.XML configuration.

Usage: RellRunConfigLaunch [-d=SOURCE_DIR] RUN_CONFIG
Launch a run config
      RUN_CONFIG   Run config file
  -d, --source-dir=SOURCE_DIR
                   Rell source code directory (default: current directory)

multigen.sh

Creates a Postchain blockchain XML configuration from a Run.XML configuration.

Usage: RellRunConfigGen [--dry-run] [-d=SOURCE_DIR] [-o=OUTPUT_DIR] RUN_CONFIG
Generate blockchain config from a run config
      RUN_CONFIG   Run config file
      --dry-run    Do not create files
  -d, --source-dir=SOURCE_DIR
                   Rell source code directory (default: current directory)
  -o, --output-dir=OUTPUT_DIR
                   Output directory

Example of a generated directory tree:

out/
├── blockchains
│   ├── 1
│   │   ├── 0.gtv
│   │   ├── 0.xml
│   │   ├── 1000.gtv
│   │   ├── 1000.xml
│   │   └── brid.txt
│   └── 2
│       ├── 0.gtv
│       ├── 0.xml
│       ├── 1000.gtv
│       ├── 1000.xml
│       ├── 2000.gtv
│       ├── 2000.xml
│       ├── 3000.gtv
│       ├── 3000.xml
│       └── brid.txt
├── node-config.properties
└── private.properties