Home

Awesome

Europa

Europa is a private test blockchain based on Substrate to help Runtime Pallet and pallet-contracts development. It modifies the native Substrate chain by removing unnecessary components such as Wasm execution and p2p while adding some great features to help developers get more insights of the contract execution details. Europa supports all programming languages that compiles to WASM such as ink!, ask! and Solang.

Riot Group for discussion: https://app.element.io/#/room/#PatractLabsDev:matrix.org

Note: Currently, FRAME Contracts pallet(pallet-contract) is under developments, which may contain some breaking changes. Thus we use different branch to differentiate FRAME Contracts pallet version.

Note: We name FRAME Contracts pallet as pallet-contract in following doc.

We provide three main branches now:

In those branches:

For master, Europa is tracking newest substrate (deac6324) now. Thus, pallet-contracts can use the newest features.

Note: The database format of Europa v0.3 and v0.2 is not compatible, please do not use the database directory generated by v0.2 for v0.3 (-d/--database parameter or use default data path). You should delete old database or use a new version.

Documentation

Europa Overview

Extending types

When using Substrate Portal, @polkadot/api and Redspot or other 3rd parties clients to connect Europa pallet-contracts node, please remember to add "extending types" for Europa requirements.

Europa current "extending types" is (This may be changed for different Europa version):

{
  "LookupSource": "MultiAddress",
  "Address": "MultiAddress",
  "AliveContractInfo": {
    "trieId": "TrieId",
    "storageSize": "u32",
    "pairCount": "u32",
    "codeHash": "CodeHash",
    "rentAllowance": "Balance",
    "rentPaid": "Balance",
    "deductBlock": "BlockNumber",
    "lastWrite": "Option<BlockNumber>",
    "_reserved": "Option<Null>"
  }
}

Features

  1. Europa is another implementation for substrate client.

    Europa client crates are named ec-*, for Substrate client crates are named sc-*. Thus, Europa sandbox framework can be used by any blockchain projects based on Substrate.

    The directory bin/europa is the implementation example for Europa like bin/node, bin/node-template in Substrate. Other Substrate based blockchain could integrate Europa's framework for the following features.

  2. Producing a block only when receiving new extrinsics.

  3. Removing related parts for WASM runtime.

  4. Providing another database called state-kv to record blockchain's state changes when a new block gets mined.

  5. Providing custom RPCs to tweak the blockchain.

    • europa_forwardToHeight: produce empty blocks to reach to the designated height
    • europa_backwardToHeight: revert the blockchain to designated height and remove states
    • ...

  6. Use workspace to isolate different node environments.

For more details, please refer to Europa Guides

And for Europa pallet-contracts sandbox, we split into two parts:

pallet-contracts modifications:

ChainExtensions: Europa supports two custom chain extensions

For details of Europa's pallet-contracts extensions, please refer to Europa's pallet-contracts implementation

Build and run

Build

clone this repo

> git clone --recurse-submodules https://github.com/patractlabs/europa.git
## or do following commands
> git clone https://github.com/patractlabs/europa.git
> cd europa/vendor
> git submodule update --init --recursive

compile

The compilation for this project is same as substrate.

Once compilation is finished, current executable file is named europa in target directory.

Run

Run Europa

Following example are built in debug mode. If you build with release mode, using release replace debug in following commands.

$ ./target/debug/europa 
# if you what to specify a directory, add `-d` or `--base-path`
$ ./target/debug/europa -d database
# if you just want to test without storing the actual blockchain database, add `--tmp`
$ ./target/debug/europa --tmp

then, the Europa will start:

Nov 12 17:10:14.524  INFO Europa Dev Node    
Nov 12 17:10:14.524  INFO ✌️  version 0.1.0-7b4463c-x86_64-linux-gnu    
Nov 12 17:10:14.524  INFO ❤️  by patract labs <https://github.com/patractlabs>, 2020-2020    
Nov 12 17:10:14.524  INFO 📋 Chain specification: Development    
Nov 12 17:10:14.524  INFO 💾 Database: RocksDb at .sub/default/chains/dev/db    
Nov 12 17:10:14.524  INFO 📖 Workspace: default | Current workspace list: ["default"]    
Nov 12 17:10:14.524  INFO ⛓  Native runtime: europa-1 (europa-1.tx1.au1)    
Nov 12 17:10:14.986  INFO 🔨 Initializing Genesis block/state (state: 0x8fc7…d968, header-hash: 0xc7e1…7529)
Nov 12 17:10:14.988  INFO 📦 Highest known block at #0    
Nov 12 17:10:14.991  INFO Listening for new connections on 127.0.0.1:9944.

Access Europa

now, you could use apps(https://polkadot.js.org/apps/) to access Europa:

then, you could do transfer call as normal and could see the Europa log like:

Nov 12 17:21:23.544  INFO Accepted a new tcp connection from 127.0.0.1:44210.    
Nov 12 17:21:32.238  INFO 🙌 Starting consensus session on top of parent 0xc7e1ce585807b34b7fecabe1242cafb2628c958b984ec0aee7727cdd34117529    
Nov 12 17:21:32.252  INFO 🎁 Prepared block for proposing at 1 [hash: 0x0109608217316a298c88135cf39a87cc31c37729fbe567b4a1a9f8dcdb81ebeb; parent_hash: 0xc7e1…7529; extrinsics (2): [0x2194…baf8, 0x0931…58bb]]    
Nov 12 17:21:32.267  INFO Instant Seal success: CreatedBlock { hash: 0x0109608217316a298c88135cf39a87cc31c37729fbe567b4a1a9f8dcdb81ebeb, aux: ImportedAux { header_only: false, clear_justification_requests: false, needs_justification: false, bad_justification: false, needs_finality_proof: false, is_new_best: true } }

More operations please refers to the doc Europa-CLI

Plan/Reports

  1. v0.1: An independent runtime environment as the foundation for future developments (finished)

    The independent runtime environment of Europa's exclusive node can be futher expanded without the constraints of the node environment and WASM runtime, and can be easily integrated with other components. In v0.1, it is more like simulating the Ganache project in Ethereum ecosystem, enabling contract developers to develop with a pre-built blockchain designed for contract development. Developers can quickly fire up a personal Substrate chain, which can be used to run tests, execute commands, and inspect state changes with full control of the blockchain through RPCs. For more details, please refer to Report v0.1

  2. v0.2: pallet-contract modification to provide more information. (finish)

    In this version, we forked the pallet-contracts module for the part of the error logging for contract developers, such as :

    • WASM back trace, the function call stack during WASM contract execution;
    • Contracts stack traces, the call stack of a contract calling another contract;
    • Console.log, provides libraries and methods to print command lines during contract development;
    • Strengthen the error type and error display of the contract module;
    • Integration with Redspot;

  3. v0.3: Improve the development experience, better integration with other tools, and extend the sandbox to be compatible with other runtime modules. (under development)

    • Better integration with Redspot
    • Better integration with polkadot.js.org/apps to achieve complete RPC support
    • Support status data query