Skip to content

Commit

Permalink
add readme file (#99)
Browse files Browse the repository at this point in the history 
Co-authored-by: bonan <[email protected]>
  • Loading branch information
@Astrapolis-peasant
Astrapolis-peasant and bonan authored Oct 27, 2021
1 parent 72dc7ca commit 2f77370
Showing 1 changed file with 55 additions and 59 deletions.
114 changes: 55 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,36 @@
# Europa
Europa is a sandbox environment that runs [`FRAME Contracts pallet`](https://substrate.dev/docs/en/knowledgebase/smart-contracts/contracts-pallet),
and it is also a framework that provides a sandbox environment for [substrate](https://github.com/paritytech/substrate/) runtime.
Europa could be used to simplify the developing, debugging, and integration test when developers develop Substrate
runtime pallets and test smart contract (like [ink!](https://github.com/paritytech/ink), [ask!](https://github.com/patractlabs/ask) and [Solang](https://github.com/hyperledger-labs/solang)) for `FRAME Contracts pallet`.
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 the framework for Substrate runtime**
* **As a framework for Substrate runtime development**

When regarding this project as a lib framework, this sandbox framework already removes WASM executor, p2p,
consensus functions and other unnecessary parts, **just remaining the native execution environment and RPC interface**.
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, a concept of workspaces which isolates different developing environments.
Europa sandbox framework also provides a local database storing the blockchain state changes,workspaces to isolate different developing environments.

* **As the sandbox for `FRAME Contracts pallet` module for debugging and testing contracts**
* **As a sandbox for `pallet-contracts` module to debug and test contracts**

When regarding this project as an executable file which is used for running contracts, Europa provides more detail and richer
information and wasm panic backtrace for executing contracts. This information is very useful to help developers
to locate the bugs and errors in contracts, especially for the cases which multiple contracts call each other in a
complex way, like defi or else.
And in the future, We may build it as an electron app to allow developers to download and run directly.
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 developing, which may contain some breaking changes.
Thus we use different branch to distinguish different `FRAME Contracts pallet` version.**
**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`: run newest `pallet-contracts` on newest substrate dependencies now.
* `substrate/v3.0.0`: run substrate-v3.0.0 `pallet-contracts` based on v3.0.0 substrate dependencies.
* `substrate/v2.0.0`: run substrate-v2.0.0 `pallet-contracts` based on v2.0.0 substrate dependencies.
* `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 branch:
In those branches:

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

Expand All @@ -50,18 +48,16 @@ In those branch:

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

> P.S. We do not advice you to use v2.0.0, for we no longer maintain this version.
> 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 data generated by v0.2 as the data directory of v0.3 (`-d/--database parameter or use default data path`).
> 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
[https://docs.patract.io/en/europa/introduction.html](https://docs.patract.io/en/europa/introduction.html)

> Chinese: [https://docs.patract.io/europa/introduction.html](https://docs.patract.io/europa/introduction.html)
[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.
Expand All @@ -86,28 +82,27 @@ Europa **current** "extending types" is (This may be changed for different Europ
```

## Features
In details, current Europa sandbox framework provides:
1. This framework is another implementation for [substrate client](https://github.com/paritytech/substrate/tree/master/client).
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 could also be used by any blockchain projects which are based on Substrate.
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. Substrate blockchain could integrate Europa framework for following features.

2. Producing a block only when receive new extrinsic.
3. Removing all WASM related parts.
4. Providing another database called `state-kv` to records every block modified state.
5. Providing some particular rpc to operate this sandbox.
* `europa_forwardToHeight`: developer can call this rpc to auto generate empty blocks to pointed height.
* `europa_backwardToHeight`: developer could revert block height and states to pointed height.
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 environment.

More information about sandbox framework detailed features refers to the doc: [basic.md](./doc/basic.md)
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:

Europa self modifications:
`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**.
Expand Down Expand Up @@ -138,20 +133,20 @@ Europa self modifications:
}
```
- [ ] `pallet-contracts` self features.
- [ ] `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 features:
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.*
More information about Europa `pallet-contracts` sandbox detailed features refers to the doc: [europa.md](./doc/europa.md)
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
Expand All @@ -165,9 +160,9 @@ More information about Europa `pallet-contracts` sandbox detailed features refer
```
#### compile
The building for this project is same as [substrate](https://github.com/paritytech/substrate/).
The compilation for this project is same as [substrate](https://github.com/paritytech/substrate/).
When building finish, current executable file is named `europa` in `target` directory.
Once compilation is finished, current executable file is named `europa` in `target` directory.
### Run
#### Run Europa
Expand All @@ -176,10 +171,10 @@ When building finish, current executable file is named `europa` in `target` dire
$ ./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 in tmp, add `--tmp`
# if you just want to test without storing the actual blockchain database, add `--tmp`
$ ./target/debug/europa --tmp
```
then, the Europa sandbox is starting:
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
Expand All @@ -206,24 +201,25 @@ Nov 12 17:21:32.252 INFO 🎁 Prepared block for proposing at 1 [hash: 0x010960
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 [basic.md](./doc/basic.md)
More operations please refers to the doc [Europa-CLI](https://docs.patract.io/en/europa/intro/europa-cli)
## Plan
1. v0.1: Have an independent runtime environment to facilitate more subsequent expansion directions. (finish)
## Plan/Reports
1. v0.1: An independent runtime environment as the foundation for future developments (finished)
The independent runtime environment of excluded nodes can be expanded more without the constraints of the node environment and WASM compilation, and can be easily integrated with other components. In this version, it is more like simulating the Ganache project in Ethereum ecosystem, enabling contract developers to develop without having to build a contract blockchain. Developers can quickly fire up a personal Substrate chain, which can be used to run tests, execute commands, and inspect state while controlling how the chain operates.
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: Modify at contract module level to provide more information. (finish)
2. v0.2: `pallet-contract` modification to provide more information. (finish)
In this version, we will fork the pallet-contracts module for secondary development. We will strengthen the part of the error notification for contract developers, such as providing:
* WASM stack traces, the function call stack during WASM contract execution;
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;
* Simple integration with Redspot; (not yet)
* Integration with Redspot;
3. v0.3: Improve the development experience, strengthen collaboration with other tools, and extend the sandbox to be compatible with other runtime modules. (in future)
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)
* Strengthen the integration with Redspot
* Strengthen the integration with polkadot.js.org/apps to achieve complete RPC support
* Better integration with Redspot
* Better integration with polkadot.js.org/apps to achieve complete RPC support
* Support status data query

0 comments on commit 2f77370

Please sign in to comment.