Topics

#europa #smart-contracts #substrate #wasm #webassembly

Language breakdown

Rust 99.5%

Makefile 0.5%

▸ Files click to expand

README

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.

As a framework for Substrate runtime development

Since Europa removes WASM runtime executor, p2p, consensus protocols and other unnecessary parts, Europa can be used as a framework for runtime development only keeps the native execution environment and RPC interface.

Europa sandbox framework also provides a local database storing the blockchain state changes,workspaces to isolate different developing environments.

As a sandbox for pallet-contracts module to debug and test contracts

Regarding Europa as a sandbox for executing contracts, Europa reveals more insights such as execution details and WASM backtrace. Those information is quite useful to help developers to locate the bugs and errors in contracts, especially when multiple contracts call each other in a nested way, which is very common in DEFI applications.

As a one-click blockchain with UI

Europa also comes with a super powerful UI as a pre-compiled one-click binary file. You can download the UI from our git repository

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:

master: runs latest pallet-contracts.
substrate/v3.0.0: runs pallet-contracts based on v3.0.0 substrate dependencies.
substrate/v2.0.0: runs pallet-contracts based on v2.0.0 substrate dependencies.

In those branches:

master branch is our default branch, which provides our forked pallet-contracts crate that tracks the newest substrate pallet-contracts module.

In master branch, Europa use vender/substrate's pallet-contracts as dependency. This forked pallet-contracts is from the branch europa-contracts in our vendor/substrate repo. In this forked pallet-contracts Europa provides many self test features. More information about this forked substrate refers to this repo Currently, the tracked substrate commit is deac6324a16fc4128b94a7b4c3826eebcb86917f

substrate/v3.0.0 branch is fixed in v3.0.0 substrate:

In this branch, Europa use substrate v3.0.0 from crate.io as dependencies, so as the pallet-contracts in vendor.

substrate/v2.0.0 branch is fixed in v2.0.0 substrate and does not contain vendor:

> P.S. Please avoid using v2.0.0 in most circumstances as we are no longer maintaining this version.

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

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.

Producing a block only when receiving new extrinsics.
Removing related parts for WASM runtime.
Providing another database called state-kv to record blockchain's state changes when a new block gets mined.
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 * ...

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:

[x] Using ep-sandbox instead of sp-sandbox in pallet-contracts.

- [x] Using forked wasmi to support WASM panic backtrace. - [X] Using wasmtime as WASM JIT-executor - [ ] Support gdb/lldb debug. (developing) - [ ] Using wasm3 as a more faster WASM interpreter. (not in plan)

[x] Supporting NestedRuntime event track feature to record all useful thing in pallet-contracts.

When instantiate or call a contract (This contract needs to be compiled by PatractLabs's cargo-contract now), Europa would print:

1: NestedRuntime {
        ext_result: [success] ExecReturnValue { flags: 0, data: 01 },
        caller: 0000000000000000000000000000000000000000000000000000000000000000 (5C4hrfjw...),
        self_account: 3790ddf4d8c63d559b3b46b96ca9b7b5f07b772c9ad4587eca6c0738e5d48422 (5DKZXRQN...),
        selector: 0x1e5ca456,
        args: None,
        value: 0,
        gas_limit: 4999999999999,
        gas_left: 4998334662707,
        env_trace: [
            sealvaluetransferred(Some(0x00000000000000000000000000000000)),
            seal_input(Some(0x1e5ca456)),
            sealgetstorage((Some(0x0000000000000000000000000000000000000000000000000000000000000000), Some(0x01))),
            seal_return((0, Some(0x01))),
        ],
        trap_reason: TrapReason::Return(ReturnData { flags: 0, data: 01 }),
        nest: [],
    }

[ ] pallet-contracts support.

For now, Europa is tracing the version before 4.0.0-dev(commit deac6324a16fc4128b94a7b4c3826eebcb86917f). Thus, the recent feature: "contracts: Allow contracts to dispatch calls into the runtime (#9276)" can support. This feature and the following modifications will be merged after substrate release 4.0.0. ChainExtensions: Europa supports two custom chain extensions

[x] Contract Logger support, refer to this link PIP-102
[x] Zero-Knowledge support, refer to this link PIP-101

Currently we use a simple static way to charge weight for ZKP, we would change this part with benchmarks result in future.

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:

click left tab to switch DEVELOPMENT - Local Node.
click Settings - Developer, and paste "extending types"(see above) to here:
click "save"

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 { headeronly: false, clearjustificationrequests: false, needsjustification: false, badjustification: false, needsfinalityproof: false, isnew_best: true } }

More operations please refers to the doc Europa-CLI

Plan/Reports

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

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;

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

🔗 More in this category