Blockchain-as-a-Service

Documentation
DATABETA

Blockchain-as-a-Service API Overview

The Blockchain-as-a-Service API allows you to build your own private chain, based on Ethereum technology in a secured cloud.

Manage your blockchain nodes

The nodes of your chain will be hosted in docker containers, running on Proximus infrastructure. The nodes are based on Geth, one of the official implementations of the Ethereum protocol. We also support multiple consensus mechanisms like Proof-of-Work (PoW) or Proof-of-Authority (PoA, default in Private chain setups).

Easy to integrate with other assets

With our Blockchain Management module you can create and manage your wallets and contracts easily, on your private or a public chain. Use the contract-to-api conversion to directly interact with your Blockchain components using a REST api, and integrate your app with an Ethereum Blockchain.

Go to Blockchain Management

Thanks to our CloudEngine module, Blockchain applications are very easy to build and to integrate with other tools. If you haven't discovered our CloudEngine yet, now is the time!

Go to CloudEngine

Blockchain-as-a-Service API (BC-aaS)

Introduction

The Proximus Blockchain-as-a-Service API allows you to easily set up and manage your private blockchain architecture. Through a simple user interface or API, you are able to configure, manage and monitor your own blockchain nodes.

The following technologies are currently supported:

  • Ethereum : Ethereum nodes based on Geth, the official GoLang implementation of the ethereum protocol. We support both the ethhash Proof-of-Work (PoW), as well as the clique Proof-of-Authority consensus algorithms. For more information regarding these, please see here.

Getting started

To get started using the BC-aaS asset, navigate to https://bcaas.enco.io/, where you'll find a wizard to lead you through the setup process.

During the wizard, you'll be asked to enter some values. In this section, we'll go over all the values, explaining their meaning.

Ethereum

Shared values

Name Values Description
Genesis file JSON A representation of the first block. For values and an example, see below.
Authorised users STRING The client ID of each user you want to give access to your chain.
Visible name STRING The name for your chain. Due to technical constraints, we will append a unique identifier to this name, which will result in the final name of your chain.
Consensus type STRING The name of the consensus algorithm you would like your blockchain to use. WORK or AUTHORITY for geth-based ethereum nodes.

PoA-specific values

Name Values Description
initial signers INTEGER The number of signer wallets (that can be used to sign blocks) to be generated
additional wallets INTEGER The amount of extra wallets to be pre-funded with tokens. Please note: In a PoA chain, making blocks does not generate tokens, it only burns them. This parameter is needed to get tokens on the chain and can only be done at setup. Signer wallets are also pre-funded

The GenesisFile

The genesis file is a representation of the very first block in an ethereum chain. It also contains various parameters you can set to change certain behaviour.

Shared values

The following values are shared between all consensus algorithms:

Name Values Description
gasLimit INTEGER (Hex) The maximum amount of gas that can be used within a single block.
chainId INTEGER A unique identifier for your chain
PoW-specific values

In a PoW chain, the most important values are:

Name Values Description
Difficulty INTEGER (Hex) The difficulty is the amount of effort it takes to "mine" a new block. After starting, geth will automatically keep adjusting this value so that a block time of 15s is achieved.

You can find an example here.

PoA-specific values

For PoA, the following values are important:

Name Values Description
config.clique.period INTEGER The blocktime in seconds.
extradata STRING (Hex) This field contains the addresses that can be used to sign new blocks. This field is managed by EnCo.

You can find an example here.

Permissions & voting

Authorized users

In order to be able to undertake various actions in a private blockchain, you need permission of the owner(s). There are different types of permission, each one allowing you to undertake different actions. These types are:

  • Access permission

  • This allows you to access the private chain, and see its setup. This also allows you to add nodes to the chain, and, depending on the consensus algorithm, make them sign blocks (PoW).

  • Anchoring permission

  • This allows you to anchor blocks to a public chain. For more information, please refer to the article on anchoring.

  • Signing permission

  • This permission is needed to be able to run a signer node in a PoA blockchain

Voting

These permissions can be acquired using the voting API. A member that has a specific permission can initiate a vote to grant another user the same permission. When the majority (50% + 1 vote) agrees, the user will be granted the permission. This also works the other way around to revoke permissions from a member.

When you cast the first vote using the "create" endpoint on the API, a vote context id will be returned that other people will have to use if they want to participate in the vote. If you try and create a vote for which a context already exists, you will receive a context id where you should add your vote to.

Vote types

Add a member

This vote can be cast when you want to allow a new member to join your chain, and host (non-authorative) nodes. These members will be able to see the current state of the blockchain, as well as start a miner, if applicable to the consensus algorithm.

Model
    {
      "action":"NEW_MEMBER",
      "ctxId": 1,
      "data":{
        "identifier":"<clientId>",
        "accept":"<true|false>"
      }
    }
Propose a member as a signer

This vote is only applicable to chains using PoA consensus, and it will allow the owner of the target address to spin up 1 authorative node. Because this vote is done by "wallets" rather than EnCo users, it is possible to send a list of all authorative addresses you own.

Model
    {
      "action":"PROPOSE",
      "ctxId": 1,
      "data":{
        "nodes":"<wallet,addresses,comma,separated>",
        "target":"<walletAddressToPropose>",
        "accept":"<true|false>"
      }
    }
Transfer the chain ownership

This vote can only be started by the current "owner" of the chain. The "owner" is the person who also has the bootnode under its name, and is the only one able to delete a chain (only after all nodes are gone). The target of the vote can accept the transfer by voting for his/her own identifier, or deny by entering the identifier of the current owner again (or ignore it).

Model
        {
          "action":"TRANSFER",
          "ctxId": 1,
          "data":{
            "identifier":"<clientId>"
          }
        }

UI overview

Coming soon

Genesis File

Values

Name Default Value Description
chainId 1 (=Mainnet) The ID of the current chain, used to prevent replay attacks
*Block N/A These parameters are only relevant in mainnet, but need to be included. It is recommended to leave these at the values shown below
ethash N/A Tells the network to use the ethash algorithm to validate blocks, which is a Proof-of-Work algorithm
clique N/A Tells the network to use the clique algorithm to validate blocks, which is a Proof-of-Authority algorithm
clique - period 15 The blocktime, in seconds
clique - epoch 30000 The number of blocks after which to reset the pending votes & create a "checkpoint"
nonce 0x0 The nonce of the genesis block. This value can be anything, as it has no meaning in the genesis block
timestamp N/A The timestamp on which the block was created. Must be in the past, can be used as an indicator of when the chain was started
extraData 0x0000000000000000000000000000000000000000000000000000000000000000 Can contain 32 bytes of anything. In clique, it contains the accounts that are initially allowed to sign blocks (the "authorities")
gasLimit N/A The maximum amount of GAS that can be spent in a single block.
difficulty 0x80000 The difficulty of the cryptographic puzzle to be solved when using PoW. This value is ignored in PoA
mixHash 0x0000000000000000000000000000000000000000000000000000000000000000 Used for verifying that a block was mined correctly
coinbase 0x0000000000000000000000000000000000000000 The default address to be used by Geth
alloc N/A A structure that allows you to define pre-allocated funds. It contains all pre-funded wallets, and the amount of ether assigned to them
number 0x0 The block number. Must be 0 for the genesis block
gasUsed 0x0 The amount of gas used within this block. Must be smaller than gasLimit, but is always 0 in the genesis block, as no transactions are done in the genesis block
parentHash 0x0000000000000000000000000000000000000000000000000000000000000000 The keccak-256 hash of the previous block's header. Set to all zeroes in the genesis block, as it is the first block, and thus has no parent

Proof-of-Work(PoW) example genesis.json

{
  "config": {
    "chainId": 1234,
    "homesteadBlock": 1,
    "eip150Block": 2,
    "eip150Hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "eip155Block": 3,
    "eip158Block": 3,
    "byzantiumBlock": 4,
    "ethash": {}
  },
  "nonce": "0x0",
  "timestamp": "0x5b4db2ea",
  "extraData": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "gasLimit": "0x47b760",
  "difficulty": "0x80000",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "alloc": {},
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}

Proof-of-Authority(PoA) example genesis.json

    {
      "config": {
        "chainId": 1234,
        "homesteadBlock": 1,
        "eip150Block": 2,
        "eip150Hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "eip155Block": 3,
        "eip158Block": 3,
        "byzantiumBlock": 4,
        "clique": {
          "period": 15,
          "epoch": 30000
        }
      },
      "nonce": "0x0",
      "timestamp": "0x5b4db31a",
      "extraData": "0x00000000000000000000000000000000000000000000000000000000000000004ad6a46189ac58bd4b665f825f845af3573648780000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
      "gasLimit": "0x47b760",
      "difficulty": "0x1",
      "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "coinbase": "0x0000000000000000000000000000000000000000",
      "alloc": {
        "4ad6a46189ac58bd4b665f825f845af357364878": {
          "balance": "0x200000000000000000000000000000000000000000000000000000000000000"
        }
      },
      "number": "0x0",
      "gasUsed": "0x0",
      "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
    }

Blockchain basics

Introduction

This section will briefly cover some of the terms you may encounter while reading the Blockchain-as-a-Service documentation.

Ethereum terminology

  • Uncle: A block that was generated almost simultaneously with another block, but was ultimately not selected by the majority as "the next block". It can be included in another block later, causing the miner of the uncle to be rewarded with a small amount of ether.
  • Gas: Gas is used as a measure to see how much work doing a transaction would take. A standard ethereum transaction (sending some ether from one wallet to another) will always use 21000 gas. In a smart contract the amount of gas depends on what is done in the contract. The total cost for a transaction is calculated by taking the gas usage, and multiplying it with the current gas price (determined by the network).

Consensus algorithms

As only 1 block will be made every x time, the participants of the network need a way to ensure that the person ultimately making the block is doing so in the network's best interest.

There are a couple of ways to ensure the person signing a block cannot influence the chain in such a way that it compromises the chain's integrity or security. In this section we'll go over 2 of them that are currently supported by the Blockchain-as-a-Service application.

Proof-of-Work

In a Proof-of-Work (PoW) network, each "mining" node simultaneously creates a new block. In order to decide on which block will be accepted by the network, all nodes will have to submit "proof" that they have solved a cryptographic puzzle. The node to first solve this puzzle will receive a reward, usually in the form of crypto currency.

This puzzle involves calculating the block hash over and over with different values for the "nonce" value, until the resulting block hash has a certain number of zeroes. When more processing power is added to the network, the network will adjust the number of zeroes required, resulting in a puzzle that requires more processing power to complete. This keeps the blocktime in check.

This consensus algorithm provides "safety in numbers", where one malicious actor cannot have enough impact to destabilize the system.

The advantage of this consensus algorithm is the fact that there needs to be no centralized authority, and no one needs to trust anyone. The drawback is, of course, that these calculations are resource intensive.

Proof-of-Authority

In Proof-of-Authority blocks are created by a predefined set of "authorities", in a way where each authoritative node only gets to create 1 in every (numberofauthoritative_nodes)/2 + 1 blocks By doing so, a single malicious authority will not be able to flood the network with bad blocks.

Authorities (in ethereum) are identified by a public wallet address. The initial authorities are identified in the genesis block of the chain. To add or remove an authority, current existing authorities can vote on a wallet address to add or remove them from the list of authorities. When a node gains authority, it can also enter in the rotation to sign blocks.

Unlike in Proof-of-Work, nodes that generate new blocks are not awarded tokens. Instead, all tokens in the system should be pre-allocated in the genesis file's "alloc" object. After creation, there is no way to add additional funds to the chain: All wallets that need funds must be defined in the genesis block. There is no limit to the amount of wallets that can receive funds, nor is there a limit to the total amount of funds allocated.

This consensus algorithm is ideal for private chains, as there usually are only a couple of parties that take part in it. It is also a lot more resource efficient, as there is no equivalent to mining. The drawback is that these few entities need to be trusted by the non-authorative nodes, so this is not feasible for public chains.

Anchoring

Anchoring is the act of linking a certain piece of data to a (usually public) blockchain. Doing so gives you irrefutable proof of a piece of data's existence at a certain time.

In the context of private chains, this can be used to validate the state of a private chain at a point in time. Since it is usually much easier to tamper with data in a private chain (though still a lot harder than tampering with a database), we can use anchoring to link the private chain to the public chain, giving irrefutable proof of a private chain's state at a specific point in time.

This can be done by placing block hashes from your private chain's blocks onto the public chain at certain intervals. The EnCo Bc-aaS supports this, and requires a majority consensus before an anchor can be added to the public chain.

TPS - Transactions per second

The number of transactions per second a blockchain can handle depends on a few parameters. In this section, we'll go over the parameters that affect this in Ethereum.

Tuning your ethereum blockchain for maximum performance is a balancing act between the block time, the gas limit and the network your nodes are running on. Reducing the block time will allow your chain to generate more blocks, but it will be more difficult for other nodes to catch up with the newest block, which in turn may result in a high uncle count.

The same basic premise exists for the gas limit. Increasing this will allow you to fit more transactions in a single block, but because of the larger size of the block (in bytes) , it may end up requiring more time to propagate over the network, resulting in an increased uncle count.

  • All rights reserved. © 2019 Proximus|Cookie policy
  • This site was created and is managed in accordance with Belgian law.
  • Proximus API Solutions - powered by ClearMedia NV. Merksemsesteenweg 148, B-2100 Deurne. BE 0831.425.897