umbra Documentation

umbra DocumentationRelease 0.1

Raphael Vicente Rosa

Feb 20, 2020

Contents:

1 Umbra 11.1 Intro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.4 How it Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.5 Roadmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Getting Started 32.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 1. Install the Main Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.3 2. Install the Fabric Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.4 3. Create the Fabric Configs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.5 4. Run the Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.6 4. Check the Test Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.7 4. Stop the Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Installing 53.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2 Main Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.3 Requirements for Hyperledger Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 Architecture 74.1 Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.2 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Views 95.1 Use Case View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.2 Logical View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95.3 Flow View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105.4 Deployment View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.5 Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6 Example 136.1 Building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136.2 Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146.3 Modifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

i

7 Internals 157.1 umbra/design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157.2 umbra/broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157.3 umbra/scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

8 Extending Umbra 178.1 umbra/design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178.2 umbra/broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188.3 umbra/scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188.4 build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

9 Indices and tables 19

ii

CHAPTER 1

Umbra

An emulation platform for Hyperledger blockchains.

1.1 Intro

The simulation research internship during the summer of 2018 led to the creation of the Hyperledger Umbra Lab.Due to the overall difficulty of getting Hyperledger blockchain frameworks running under the Shadow simulation tool,work on the Umbra lab has slowed to a crawl. A different network emulation tool called Mininet was proposed as analternative to using Shadow and it has the potential to drastically reduce the startup cost of getting a network emulationtool running Hyperledger blockchains.

1.2 Scope

Umbra is a platform by the means of Mininet and plugins for Hyperledger distributed ledgers so that they can rununder emulation in a lab environment.

It is intended to be an ongoing project to provide a research tool for understanding and improving the Hyperledgerblockchain platforms as well as for conducting future research in consensus algorithms, scalability, security, etc.

1.3 Foundation

• Mininet - http://mininet.org/

• Maxinet - http://maxinet.github.io/

• Containernet - https://containernet.github.io/

Mininet was developed for fast prototyping of emulated programmable networks in a laptop. Later there were dif-ferent extensions proposed on top of it, such as maxinet enabling experiments in distributed clusters of servers, andcontainernet enabling the experimentation with Docker containers. Mininet was developed for high fidelity and later

1

http://mininet.org/

http://maxinet.github.io/

https://containernet.github.io/

umbra Documentation, Release 0.1

on extended to support the features proposed by Maxinet. Containernet was built on top of mininet version 2.2.0, there-fore inheriting its most recent enhancements. Umbra elaborates its architecture on top of the enhancements proposedby containernet. As being evaluated, possible contributions to containernet will be performed in order to enhance itwith the most recent features provided by Docker (i.e., current docker-py API) as well as mininet (i.e., currently inversion 2.3).

1.4 How it Works

Umbra works with support of virtualization technologies, containers (Docker) and programmable switches (OpenvSwitch). Using containernet it deployes an underlying network which serves as the infrastructure for the blockchainplatform of choice (e.g., Iroha, Fabric, Indy, etc) to be executed as the overlay application network. Nodes and linkscan be configured with resource constraint rules (e.g., cpu, memory, bandwidth, latency, etc). Besides, umbra allowsevents (e.g., transactions, chaincode invoke, etc) to be scheduled targeting the blockchain platform using plugins.

1.5 Roadmap

Umbra lives in its childhood, currently developed mostly using the Python 3 programming language.

The road so far:

• Umbra was developed in the Hyperledger Internship 2019 program;

• It contains 3 main components (scenario, broker, design) - see the Architecture section;

• There is support for Fabric v1.4 blockchain project and an example with instructions.

Work ahead:

• Support for other blockchain projects;

• Scale to multiple servers;

• Implement a common dashboard with run-time status of the emulated blockchain network;

• Output a comprehensive report of the test with compute/network statistics.

2 Chapter 1. Umbra

CHAPTER 2

Getting Started

The steps below comprehend how to install and run a Fabric topology using Umbra.

2.1 Requirements

Umbra works on Ubuntu 18.04.

To run the getting started example it is recommended a machine with Ubuntu 18.04 installed and containing 4 vCPUs(cores), 4 GB of memory, and at least 5GB of disk available.

2.2 1. Install the Main Components

Umbra contains 3 python components (design, broker, scenario), the build script below installs the requirements andthe components themselves.

$ git clone https://github.com/hyperledger-labs/umbra/

$ cd umbra/build

$ sudo chmod +x build.sh

$ ./build.sh

$ cd -

Please note, the script above (build.sh) install docker-ce and adds the $USER to the docker group (no need to usersudo before the docker command). To enable this setting, logout and login again, or execute su $USER (to start a newsession). You can test if it works simply running docker ps -a.

3


2.3 2. Install the Fabric Requirements

As Umbra is plugin oriented (i.e., each Hyperledger project needs its own umbra-plugin), the build_fabric script belowinstalls all the Fabric (v1.4) components needed to run the Umbra Fabric plugin.

$ cd umbra/build

$ sudo chmod +x build_fabric.sh

$ ./build_fabric.sh

$ cd -

2.4 3. Create the Fabric Configs

The build_configs script below creates the config files for the Fabric scenario. Open this file to see what is the scenariocreated, the topology and its events.

$ cd umbra/examples/fabric

$ /usr/bin/python3 build_configs.py

$ cd -

2.5 4. Run the Test

The run.sh script below executes the Fabric scenario (topology and events). In order to run the Mininet, a sudopassword will be asked to run the Umbra scenario component.

$ cd umbra/examples/

$ ./run.sh start -c ./fabric/fabric_configs/config_fabric_simple.json

2.6 4. Check the Test Logs

As the broker and scenario components save logs during their execution, they can be seen by the commands below.

$ tail -f logs/broker.log

$ tail -f logs/scenario.log

2.7 4. Stop the Test

The command below stops all the Umbra processes and clean their breadcrumbs.

$ ./run.sh stop

4 Chapter 2. Getting Started

CHAPTER 3

Installing

3.1 Prerequisites

Currently, Umbra is developed and tested on Ubuntu 18.04.

There are no strict requirements of hardware for Umbra. It will depend on the size of the network that’s being tested,and the configuration of resources to be allocated for nodes and links. Therefore, Umbra can be installed and run indifferent machine configurations, the need of specific hardware specs will depend on the use case being evaluated,which must be correctly dimensioned using the resource constraints for nodes and links available in Umbra.

The main components of Umbra require python 3. All the other requirements can be checked in the build scripts asdescribed below. In general, Umbra uses apt, git and pip to install its requirements.

3.2 Main Components

All the Umbra components requirements are installed together with them by the build.sh script inside the build folder.The steps below contain the Umbra installation commands.

$ git clone https://github.com/hyperledger-labs/umbra/

$ cd umbra/build

$ sudo chmod +x build.sh

$ ./build.sh

$ cd -

Please note, the script above (build.sh) install docker-ce and adds the $USER to the docker group (no need to usersudo before the docker command). To enable this setting, logout and login again, or execute su $USER (to start a newsession). You can test if it works simply running docker ps -a.

5


When executing this script, it will install all the Umbra python components and their dependencies, and it will installcontainernet and its requirements.

Notice, two executables will be created, umbra-scenario and umbra-broker.

3.3 Requirements for Hyperledger Projects

Umbra was designed to support multiple blockchains, so in an independent way each blockchain platform whensupported has its own build files also inside the build folder. As such, for each blockchain platform there will bea installation script inside the build folder. For instance, as Umbra supports Hyperledger Fabric v1.4, installing therequirements to execute Fabric on Umbra can be done with the steps below.

$ cd umbra/build

$ sudo chmod +x build_fabric.sh

$ ./build_fabric.sh

$ cd -

When executing this script, it will install the fabric-python SDK, download all the Fabric docker images, modify themaccordingly to enable support for containernet functionalities (i.e., they must have the packages net-tools and iproute2installed on them), and add the binaries configtxgen and cryptogen to the PATH env variable (i.e., as they are requiredby the fabric-python-sdk, and the umbra-broker component).

6 Chapter 3. Installing

CHAPTER 4

Architecture

4.1 Design Principles

Umbra was designed having in mind the following guidance:

• Fast and simple prototypes: with simple APIs it is possible to construct different topologies for blockchainnetworks to be experimented. Those are easily generated in any laptop, enabling deployments in small or largescale.

• Lightweight execution: the source code is easily portable, installed and utilized in multiple underlying environ-ments (e.g., laptop, cloud servers, etc).

• Transparent reproduction: configuration files are recipes to be shared and executed in different environments forcomparability among experiments, enabling reproducible research.

4.2 Components

Umbra has three independent components:

• design: defines APIs to implement the topology and events that will be respectively deployed and triggeredwhen testing a blockchain platform.

• broker: main component, responsible for the orchestration and management of the scenario (topology andevents)

• scenario: the actual interface that deploys the topology (i.e. network, containers, virtual switches)

7


8 Chapter 4. Architecture

CHAPTER 5

Views

5.1 Use Case View

There exists two roles in the umbra use case view, the blockchain Tester and the Analyst/Viewer. Using the providedAPIs (by umbra/design), a Tester defines the configuration file, uses it (with umbra/broker) to perform the test in a tar-get execution environment (by umbra/scenario), and collects the experimental data metrics and logs (raw and analyzed)output of the logged activities. An Analyst just visualizes and performs analysis on the test results. Visualization oftest results can be triggered during the execution of the test and after it. So an Analyst might visualize tests metrics inruntime via plugins (e.g., grafana, kibana, plots). The experiments are meant to be fully automated, but Testers mightinteract with the running topology during the tests too.

5.2 Logical View

Using an API provided by umbra/design, a tester codes the scenario needed for an experiment, the output of suchscenario is a set of configuration files. A script starts the applications components umbra-broker and umbra-scenario,both detaining gRPC services. The scenario (config) file is sent to the umbra-broker component which parses it,sends the scenario topology to umbra-scenario, which is deployed. Acknowledging the instantiated topology by amessage received from umbra-scenario, umbra-broker triggers the events scheduled in the scenario config file. Theseevents interface the management APIs of the running blockchain components via their SDK (e.g., fabric-python-sdkinteracting with Fabric peers/CAs/orderers). At the end of events, the tester can finish the execution of the scenariosand the running components and checks the logs of the executed components, collecting the needed information.

As such, for each main umbra component the following logic describes the most important classes, their organizationand the most important use case realizations.

• umbra/design

– Graph: defines the inner structure for Topology, a graph that can be used by different graph algorithms viathe python3 networkx library.

– Topology: is a graph that contains nodes and links with profiles assigned. Profiles define resource con-straints to nodes (i.e., cpu and memory) and links (i.e., bandwidth, delay, loss).

9


– Events: defines a set of events, each one defined by a category, when (schedule timestamp to be trig-gered), and parameters. Events are intended to have other fields, specially for scheduling (e.g., duration,repeatitions, until).

– Scenario: joins a Topology with Events.

• umbra/broker

– Broker: implements the gRPC interface for umbra-broker, enabling the types of messages it can handleand their callbacks, included interfaces to an instance of Operator.

– Operator: defines all the interfaces to call the deployment of a topology, and schedule events to be triggeredafter the instantiation of an experiment.

• umbra/scenario

– Environment: sets the main component that interfaces Containernet APIs to instantiate containers, virtualswitches, interconnect them, and assign resources to them.

– Scenario: implements the gRPC interface for umbra-scenario, creating Environment(s) as requested andinterfacing the infrastructure deployed according to requested events (e.g., update nodes/links resources).

5.3 Flow View

How it works in summary: a configuration file is parsed and converted into an internal data structure that is usedto instantiate the specified topology. Executed the topology, the events specified in the configuration file take place.During the test, monitoring functions might collect metrics to be shown in graphics online. After the test, the analysisof the whole monitored data is analyzed and a report is generated containing the test life cycle (i.e., status involvingthe phases of pre-deployment, execution, and post-mortem).

1. The Tester defines the scenario configuration that will be executed. It contains the whole lifecycle of the struc-tural (topology/infrastructure) and functional (events/visualization) definitions. This is done via APIs specifiedby the umbra/design component.

2. Given such configuration to the umbra-broker component, it will execute the parsing of the configuration, set allthe deployment configuration to be deployed.

3. A Environment class instance in umbra-scenario will deploy the given configuration file, creating the Contain-ernet network. It will send back to Broker the management information of the deployed components. Suchinformation contains among other settings, the IP address of the management interface of the containers de-ployed in the network.

4. Broker will start triggering the scheduled events (defined in the Scenario configuration file) to take place in theinfrastructure and/or topology.

5. In addition, the Tester can utilize the Manager interface to trigger events during the execution of the experiment.

6. The Operator component of Broker then parses such event requests and schedule their occurrence in the topologyand/or infrastructure.

7. Events take place, e.g.: containers running hyperledger project components start/stop mining, links/nodesfail/restore or have resources changed, metrics are monitored from infrastructure perspective, etc.

8. Metrics, output of events execution, are received in Operator. The set of events-metrics pairs are pushed toBroker, and possibly a Visualization component.

9. Metrics are displayed in different graphic formats according to the pushed instructions.

10. Given the schedule of the Experiment Configuration or a request from the Tester, Manager stores all events-metrics, and request the end of the topology/infrastructure components.

10 Chapter 5. Views


11. All the components are stopped and removed, leaving the infrastructure as it was before the experiment started.

12. Acknowledged the end of the infrastructure/topology execution, Broker outputs a Scenario status report con-taining the comprehensive set of events and their collected metrics during the whole experiment.

13. Tester receives the output report and possibly send it to an experiment Analyst/Viewer.

5.4 Deployment View

In general, the project code can be installed in one or more servers interconnected by a common network, composinga cluster. In one server, specified as the jump server, the main components of the Umbra project load the configurationfile and execute the experiments.

For now, Umbra runs in a single server. Evolving the project, in the future a single jump server will trigger theexecution of Umbra in multiple servers.

5.5 Directory Structure

• build: contains the installation scripts for all the Umbra components, in addition to the scripts needed to installthe dependencies for the blockchain platforms be executed by Umbra.

• docs: all the documentation is stored in docs, included all the source files (.rst) needed to compile the html pagesfor readthedocs.

• examples: contains a README file on how to run umbra examples, and for each example it contains a folderreferencing the name of the blockchain platform containing instructions and all the scripts needed to run theexample.

• umbra/common: contains all the common application models (i.e., protocol buffer messages and services)implemented to be used by the other Umbra components.

• umbra/broker: contains all the component source code to install and run the orchestration logic of umbra, i.e.,how to receive a scenario configuration request, deploy it and trigger the events programmed in the scenariologic. The executable umbra-broker contains plugins, each one specified for a different blockchain platform itsupports.

• umbra/design: contains all the component source code to install and enable APIs for the configuration logicof umbra, i.e., how to specify different topology APIs to build the configuration needed for each blockchainplatform to be executed by umbra-broker.

• umbra/scenario: contains all the component source code to install and run the plugin that enables Containernetto deploy the topology needed to execute a blockchain platform.

5.4. Deployment View 11


12 Chapter 5. Views

CHAPTER 6

Example

To examplify how Umbra can be utilized, an extension was coded to support Hyperledger Fabric v1.4. The details ofhow that was coded are exposed in the Extensions section. Here is just the explanation of what the Fabric examplerealizes.

6.1 Building

Here, it is assumed that the steps mentioned in the Installing section were already followed and performed in a hostmachine.

In the root folder named build/ a script named build_fabric.sh downloads and installs all the requirements needed torun the Fabric example.

In the root folder named examples/, the fabric/ folder contains all the requirements needed to build the configurationfiles to be used by the Fabric example. The source code in the file build_configs.py realizes all the construction of theneeded skeleton of files for the Fabric nodes (docker containers). This file import a class from umbra/design componentnamed FabricTopology and builds the experimental topology using it. A file located in the folder base_configtx/ namedfabric.py is the source of the policies for organizations and the main configtx file build to create the requirements forthe fabric blockchain (e.g., genesis, anchors, channel). When the build() function is called upon the FabricTopologyinstance (to save the scenario config), all the configurations files needed for the Fabric blockchain network are auto-matically created. For instance, this includes all the crypto material for all the peers, and the configuration file namedfabric_sdk_config.json to be imported by the fabric python SDK when calling the scheduled events to peers in theFabric blockchain. At the end of this file, a configuration is saved based on the Scenario instance created, which hasthe FabricTopology instance and the events defined accordingly. This configuration file, named fabric_configs/Fabric-Simple-01.json, contains all the hooks for the crypto material, fabric-python-sdk configuration file, and other neededfiles such as the genesis block. Executing the file as the commands below, all the requirements are satisfied to executethe Fabric blockchain in Umbra.

In the examples/fabric folder, the files/folder structure is described below:

• base_configtx: contains all the source material for the creation of the configtx.yaml file needed by Fabric (e.g.,python SDK, configtxgen, etc).

• chaincode: contains source code with examples of chaincode to be executed by the Fabric network on umbra.

13


• fabric_configs: contains all the skeleton of configuration files to execute Fabric.

• build_configs.py: a python script, making use of umbra/design component, to create Fabric configuration files(placed in fabric_configs) enabling Fabric to be executed by umbra.

Pay attention that in the file fabric_configs/Fabric-Simple-01.json all the nodes (references to docker container tem-plates) already have defined all the environment variables, volumes, commands, etc, that are correctly fulfilled basedon all the material generated from building the FabricTopology instance (i.e., crypto keys, certificates, policies).

$ cd umbra/examples/fabric

$ /usr/bin/python3 build_configs.py

$ cd -

6.2 Running

Considering all the execution of the Installing requirements and the build_configs.py file realizing all the requirementsfor the Fabric blockchain example to be executed by Umbra, now the execution of the Umbra components can beinitialized to instantiate the specified Fabric configuration (topology and events).

The executable file named run.sh in the umbra/examples/ folder contains the commands to start/stop the python3scripts umbra-broker and umbra-scenario, create/remove a management docker network named umbra, and deploy thegenerated Fabric-Simple-01.json in umbra-broker.

Having that executed, all the instantiation of components from the saved FabricTopology will take place (i.e., peers,orderers, links, etc) and events will be called on them.

The commands bellow respectivelly start and stop the example experiment with Fabric.

$ sudo -H ./run.sh start -c ./fabric/fabric_configs/config_fabric_simple.json

$ sudo -H ./run.sh stop

In addition, during the execution of the experiment, the command below checks the logs that each component executesin Umbra.

$ tail -f ./logs/broker.log

$ tail -f ./logs/scenario.log

As the Fabric containers will be initialized, it is also possible to check their logs via the command docker logs (con-tainer name), and thus check the execution of the Fabric components.

6.3 Modifying

To modify the Fabric experiment, it is just needed to modify the build_configs.py file, changing how the FabricTopol-ogy instance is built, besides changing how the events are scheduled. If new orgs are added, the file fabric.py insidebase_configtx folder needs to be modified accordingly to define the policies in configtx needed for the creation of theFabric requirements.

14 Chapter 6. Example

CHAPTER 7

Internals

This part aims to explain the inner contents of the main Umbra components, and the reasons of their design. Itcomplements the comments inside the main functions of each class. The sections are organized per components.

7.1 umbra/design

It was designed to host the APIs that can be extended to enable the creation of configuration files to be utilized byother Umbra components to instantiate and operate different blockchain platforms.

7.2 umbra/broker

TBD.

7.3 umbra/scenario

TBD.

15


16 Chapter 7. Internals

CHAPTER 8

Extending Umbra

In order to explain how umbra was coded to support multiple Hyperledger blockchain projects, this part explains theextensions coded in Umbra to support Fabric. As such, this part also illustrates how other blockchain projects can besupported by Umbra. The extensions are separated by components, and at the end it is showed how to construct aspecific example, included the build of requirements needed for that.

8.1 umbra/design

In umbra/design/configs.py file the major change was due to creating a extension of the Topology class, named Fabric-Topology. As the source of knowledge for Fabric was the tutorial named Building your First Network, such inspirationwas translated into an API that could be used to add orgs, orderers and peers that creates multiple configuration filesin an automated way. In general, these configuration files consist of:

• Cryptographic material: all the public/private keys, tls certificates, and other crypto material generated fromthe binary named cryptogen, which needs a source file (usually named crypto-config.yaml) to output such files.Thus, from the FabricTopology it was needed to create such file, and call cryptogen passing it as parameter.

• Genesis, Anchors, etc. . . : all the initial block and channel join anchors used by peers and orderers generatedfrom the binary named configtxgen, which needs a source file (usually named configtx.yaml) to output such files.Thus, from the FabricTopology it was needed to create such file, and call configtxgen passing it as parameter.

• Python SDK settings: all the reference to crypto material and path of them for each component of the Fab-ric Topology in order to be loaded and used by the fabric-python-sdk when triggering events on the Fabricinstantiated topology.

• Scenario Topology: the main configuration file to be used by umbra/broker and umbra/scenario to deploy theactual topology with containers and virtual switches as infrastructure to the Fabric blockchain network. It makesuse of a file named fabric.yaml (located at umbra/design/fabric/base) which contains all the base templates forthe docker containers executing the images of CAs, orderers and peers.

Therefore, the FabricTopology class enables the abstracted definition of orgs, peers, CAs and orderers, which are usedto build all the configuration files described above. Any changes in the way the Fabric containers are deployed canbe done in the fabric.yaml base file. Besides, all the policy definitions used as source of configtx need to be specified

17


when building the topology (in the examples/fabric/base_configtx folder the file fabric.py has such policies definedthat are used in the build_configs.py file).

8.2 umbra/broker

The core of umbra/broker allows it to be extensible to multiple blockchain projects in a plugin manner. In the pluginsfolder inside umbra/broker, a file named fabric.py contains a class named FabricEvents, which is responsible to in-terface the fabric-python-sdk and trigger the needed/scheduled events on the instantiated Fabric blockchain network.This structure of plugins are imported by the Operator component in umbra/broker, and loads all the events accordingto their category, which references a different blochchain name, in this case plugin.

FabricEvents thus loads the fabric-python-sdk component and uses it to interface the instantiated Fabric components.In order to do so, fabric-python-sdk needs the following files:

• fabric-python-sdk.yaml: the generated file from umbra/design that contains all the reference to the Fabricblockchain components and their crypto material.

• configtx.yaml: the python SDK needs the configtx file in order to load the needed policies to interface the Fabriccomponents.

• chaincode directory: to compile, instantiate and invoke chaincode the python SDK needs to reference a directorywhere such source code resides.

Multiple interfaces, i.e., functions, to the python SDK can be coded to reference events schedule upon the FabricTopology. In this case, such events must be clearly and well-defined in umbra/design. For any other implementationsof blockchain projects, interfaces to python SDKs must be implemented similar to the fabric.py plugin file. And similarto the class FabricEvents, Operator component of umbra/broker must import the coded component and reference theevents to be built upon the category of the blockchain project referenced in the events.

8.3 umbra/scenario

The overall interface to Containernet written in the umbra/scenario/environment.py file that was coded to create aumbra management network, assign IP addresses to interfaces of containers, already apply MAC addresses known toall the nodes in the network, and have all of the nodes also known by their DNS names. Those features are avail-able for all blockchain projects, not just Fabric. Thus, just enabling the abstractions of nodes and links to constructa topology file to be interpreted by umbra/scenario is the main requirement that umbra/design must detain. The En-vironment class inside the file umbra/scenario/environment.py, parses and translates nodes and links into instantiatedcontainers/switches and links, the parameters for thoses entities can be modified in that class.

8.4 build

Each Hyperledger blockchain project, when supported by Umbra, must have its dependencies installed by abuild_project.sh file inside the build directory. For instance, build/build_fabric.sh containes all the commands toinstall the Fabric requirements, download the docker images, and install the fabric-python-sdk.

18 Chapter 8. Extending Umbra

CHAPTER 9

Indices and tables

• genindex

• modindex

• search

19

Documents

umbra Documentation