Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/patractlabs/europa

A sandbox to run and debug smart contracts for FRAME Contracts pallet and also a sandbox framework for Substrate runtime.
https://github.com/patractlabs/europa

europa smart-contracts substrate wasm webassembly

Last synced: 3 months ago
JSON representation

A sandbox to run and debug smart contracts for FRAME Contracts pallet and also a sandbox framework for Substrate runtime.

Host: GitHub
URL: https://github.com/patractlabs/europa
Owner: patractlabs
Created: 2020-08-11T12:47:13.000Z (almost 4 years ago)
Default Branch: master
Last Pushed: 2022-06-18T14:21:05.000Z (about 2 years ago)
Last Synced: 2024-01-24T04:15:11.959Z (5 months ago)
Topics: europa, smart-contracts, substrate, wasm, webassembly
Language: Rust
Homepage:
Size: 892 KB
Stars: 75
Watchers: 7
Forks: 14
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md

Lists

awesome-substrate - Europa - A sandbox for the Substrate runtime execution environment. (Tools)

README

# Europa
Europa is a private test blockchain based on Substrate to help [Runtime Pallet](https://github.com/paritytech/substrate/) and [`pallet-contracts`](https://substrate.dev/docs/en/knowledgebase/smart-contracts/contracts-pallet) 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!](https://github.com/paritytech/ink), [ask!](https://github.com/patractlabs/ask) and [Solang](https://github.com/hyperledger-labs/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](https://github.com/patractlabs/europa-ui)

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](https://github.com/patractlabs/substrate)

Currently, the tracked substrate commit is [deac6324a16fc4128b94a7b4c3826eebcb86917f](https://github.com/paritytech/substrate/commit/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)](https://github.com/paritytech/substrate/commit/deac6324a16fc4128b94a7b4c3826eebcb86917f) 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](https://docs.patract.io/en/europa/intro/overview)

## Extending types
When using [Substrate Portal](https://polkadot.js.org/apps), [@polkadot/api](https://github.com/polkadot-js/api) and [Redspot](https://github.com/patractlabs/redspot) or other 3rd parties clients to connect Europa `pallet-contracts` node, please remember to add ["extending types"](https://polkadot.js.org/docs/api/start/types.extend/) for Europa requirements.

Europa **current** "extending types" is (This may be changed for different Europa version):
```json
{
"LookupSource": "MultiAddress",
"Address": "MultiAddress",
"AliveContractInfo": {
"trieId": "TrieId",
"storageSize": "u32",
"pairCount": "u32",
"codeHash": "CodeHash",
"rentAllowance": "Balance",
"rentPaid": "Balance",
"deductBlock": "BlockNumber",
"lastWrite": "Option",
"_reserved": "Option"
}
}
```

## Features
1. Europa is another implementation for [substrate client](https://github.com/paritytech/substrate/tree/master/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`](https://github.com/paritytech/substrate/tree/master/bin/node), [`bin/node-template`](https://github.com/paritytech/substrate/tree/master/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](https://docs.patract.io/en/europa/guides/architecture)

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`](https://github.com/patractlabs/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`](https://github.com/patractlabs/cargo-contract/) now), Europa would print:

```bash
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: [
seal_value_transferred(Some(0x00000000000000000000000000000000)),
seal_input(Some(0x1e5ca456)),
seal_get_storage((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](https://github.com/paritytech/substrate/commit/deac6324a16fc4128b94a7b4c3826eebcb86917f)).

Thus, the recent feature: "contracts: Allow contracts to dispatch calls into the runtime ([#9276](https://github.com/paritytech/substrate/pull/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](https://github.com/patractlabs/PIPs/blob/main/PIPs/pip-102.md)
- [x] Zero-Knowledge support, refer to this link [PIP-101](https://github.com/patractlabs/PIPs/blob/main/PIPs/pip-101.md)

*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](https://docs.patract.io/en/europa/guides/implementation)

## Build and run
### Build
#### clone this repo
```bash
> 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](https://github.com/paritytech/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.*
```bash
$ ./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:
```bash
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 , 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/](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](#extending-types)) to here:
* click "save"

then, you could do transfer call as normal and could see the Europa log like:
```bash
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](https://docs.patract.io/en/europa/intro/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](https://docs.patract.io/en/europa/reports/v0.1Report)

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