{"id":13651936,"url":"https://github.com/patractlabs/europa","last_synced_at":"2026-01-11T21:06:32.311Z","repository":{"id":45984157,"uuid":"286742818","full_name":"patractlabs/europa","owner":"patractlabs","description":"A sandbox to run and debug smart contracts for FRAME Contracts pallet and also a sandbox framework for Substrate runtime.","archived":false,"fork":false,"pushed_at":"2022-06-18T14:21:05.000Z","size":913,"stargazers_count":75,"open_issues_count":3,"forks_count":14,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-01-24T04:15:11.959Z","etag":null,"topics":["europa","smart-contracts","substrate","wasm","webassembly"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patractlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-11T12:47:13.000Z","updated_at":"2024-01-24T04:15:11.960Z","dependencies_parsed_at":"2022-08-29T10:01:10.085Z","dependency_job_id":null,"html_url":"https://github.com/patractlabs/europa","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patractlabs%2Feuropa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patractlabs%2Feuropa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patractlabs%2Feuropa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patractlabs%2Feuropa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patractlabs","download_url":"https://codeload.github.com/patractlabs/europa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250357677,"owners_count":21417326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["europa","smart-contracts","substrate","wasm","webassembly"],"created_at":"2024-08-02T02:00:53.565Z","updated_at":"2026-01-11T21:06:27.277Z","avatar_url":"https://github.com/patractlabs.png","language":"Rust","funding_links":[],"categories":["Tools"],"sub_categories":[],"readme":"# Europa\nEuropa 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).\n\n* **As a framework for Substrate runtime development**\n\n    Since Europa removes WASM runtime executor, p2p, consensus protocols and other unnecessary parts, Europa can be used as a framework for runtime development \n    **only keeps the native execution environment and RPC interface**. \n\n    Europa sandbox framework also provides a local database storing the blockchain state changes,workspaces to isolate different developing environments. \n\n* **As a sandbox for `pallet-contracts` module to debug and test contracts**\n\n    Regarding Europa as a sandbox for executing contracts, Europa reveals more insights such as execution details and WASM backtrace.\n    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.\n\n* **As a one-click blockchain with UI**\n\n    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)\n\nRiot Group for discussion: https://app.element.io/#/room/#PatractLabsDev:matrix.org\n\n**Note: Currently, `FRAME Contracts pallet(pallet-contract)` is under developments, which may contain some breaking changes. \nThus we use different branch to differentiate `FRAME Contracts pallet` version.**\n\n*Note: We name `FRAME Contracts pallet` as `pallet-contract` in following doc.*\n\nWe provide three main branches now:\n\n* `master`: runs latest `pallet-contracts`.\n* `substrate/v3.0.0`: runs `pallet-contracts` based on v3.0.0 substrate dependencies.\n* `substrate/v2.0.0`: runs `pallet-contracts` based on v2.0.0 substrate dependencies.\n\nIn those branches:\n\n* `master` branch is our default branch, which provides our forked `pallet-contracts` crate that tracks the newest substrate `pallet-contracts` module.\n\n    In `master` branch, Europa use `vender/substrate`'s `pallet-contracts` as dependency. This forked `pallet-contracts` is from \n    the branch `europa-contracts` in our `vendor/substrate` repo. In this forked `pallet-contracts` Europa provides \n    many self test features.\n    \n    More information about this forked substrate refers to [this repo](https://github.com/patractlabs/substrate)\n    \n    Currently, the tracked substrate commit is [deac6324a16fc4128b94a7b4c3826eebcb86917f](https://github.com/paritytech/substrate/commit/deac6324a16fc4128b94a7b4c3826eebcb86917f)\n\n* `substrate/v3.0.0` branch is fixed in v3.0.0 substrate:\n\n    In this branch, Europa use substrate v3.0.0 from crate.io as dependencies, so as the `pallet-contracts` in vendor.\n\n* `substrate/v2.0.0` branch is fixed in v2.0.0 substrate and does not contain vendor:\n\n    \u003e P.S. Please avoid using v2.0.0 in most circumstances as we are no longer maintaining this version.\n\nFor master, Europa is tracking [newest substrate (deac6324)](https://github.com/paritytech/substrate/commit/deac6324a16fc4128b94a7b4c3826eebcb86917f) now. \nThus, `pallet-contracts` can use the newest features.\n\n\u003e 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`).\n\u003e You should delete old database or use a new version.\n\n## Documentation\n[Europa Overview](https://docs.patract.io/en/europa/intro/overview)\n\n## Extending types\nWhen 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.\n\nEuropa **current** \"extending types\" is (This may be changed for different Europa version):\n```json\n{\n  \"LookupSource\": \"MultiAddress\",\n  \"Address\": \"MultiAddress\",\n  \"AliveContractInfo\": {\n    \"trieId\": \"TrieId\",\n    \"storageSize\": \"u32\",\n    \"pairCount\": \"u32\",\n    \"codeHash\": \"CodeHash\",\n    \"rentAllowance\": \"Balance\",\n    \"rentPaid\": \"Balance\",\n    \"deductBlock\": \"BlockNumber\",\n    \"lastWrite\": \"Option\u003cBlockNumber\u003e\",\n    \"_reserved\": \"Option\u003cNull\u003e\"\n  }\n}\n```\n\n## Features\n1. Europa is another implementation for [substrate client](https://github.com/paritytech/substrate/tree/master/client).\n\n    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.\n    \n    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.  \n\n2. Producing a block only when receiving new extrinsics.\n3. Removing related parts for WASM runtime.\n4. Providing another database called `state-kv` to record blockchain's state changes when a new block gets mined.\n5. Providing custom RPCs to tweak the blockchain.\n    * `europa_forwardToHeight`: produce empty blocks to reach to the designated height\n    * `europa_backwardToHeight`: revert the blockchain to designated height and remove states\n    * ...\n    \n6. Use workspace to isolate different node environments.\n\nFor more details, please refer to [Europa Guides](https://docs.patract.io/en/europa/guides/architecture)\n \nAnd for Europa `pallet-contracts` sandbox, we split into two parts:\n\n`pallet-contracts` modifications:\n\n- [x] Using `ep-sandbox` instead of `sp-sandbox` in `pallet-contracts`.\n    - [x] Using [`forked wasmi`](https://github.com/patractlabs/wasmi) to support **WASM panic backtrace**.\n    - [X] Using `wasmtime` as WASM JIT-executor\n    - [ ] Support gdb/lldb debug. (developing)\n    - [ ] Using `wasm3` as a more faster WASM interpreter. (not in plan)\n- [x] Supporting `NestedRuntime` event track feature to record all useful thing in `pallet-contracts`.\n    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:\n    \n    ```bash\n    1: NestedRuntime {\n        ext_result: [success] ExecReturnValue { flags: 0, data: 01 },\n        caller: 0000000000000000000000000000000000000000000000000000000000000000 (5C4hrfjw...),\n        self_account: 3790ddf4d8c63d559b3b46b96ca9b7b5f07b772c9ad4587eca6c0738e5d48422 (5DKZXRQN...),\n        selector: 0x1e5ca456,\n        args: None,\n        value: 0,\n        gas_limit: 4999999999999,\n        gas_left: 4998334662707,\n        env_trace: [\n            seal_value_transferred(Some(0x00000000000000000000000000000000)),\n            seal_input(Some(0x1e5ca456)),\n            seal_get_storage((Some(0x0000000000000000000000000000000000000000000000000000000000000000), Some(0x01))),\n            seal_return((0, Some(0x01))),\n        ],\n        trap_reason: TrapReason::Return(ReturnData { flags: 0, data: 01 }),\n        nest: [],\n    }\n    ```\n\n- [ ] `pallet-contracts` support.\n    For now, Europa is tracing the version before 4.0.0-dev(commit [deac6324a16fc4128b94a7b4c3826eebcb86917f](https://github.com/paritytech/substrate/commit/deac6324a16fc4128b94a7b4c3826eebcb86917f)).\n    \n    Thus, the recent feature: \"contracts: Allow contracts to dispatch calls into the runtime ([#9276](https://github.com/paritytech/substrate/pull/9276))\" can support.\n    This feature and the following modifications will be merged **after substrate release 4.0.0**.\n  \nChainExtensions:\nEuropa supports two custom `chain extensions`\n- [x] Contract Logger support, refer to this link [PIP-102](https://github.com/patractlabs/PIPs/blob/main/PIPs/pip-102.md)\n- [x] Zero-Knowledge support, refer to this link [PIP-101](https://github.com/patractlabs/PIPs/blob/main/PIPs/pip-101.md)\n\n  *Currently we use a simple static way to charge weight for ZKP, we would change this part with benchmarks result in future.*\n\nFor details of Europa's `pallet-contracts` extensions, please refer to [Europa's `pallet-contracts` implementation](https://docs.patract.io/en/europa/guides/implementation) \n\n## Build and run\n### Build\n#### clone this repo\n```bash\n\u003e git clone --recurse-submodules https://github.com/patractlabs/europa.git\n## or do following commands\n\u003e git clone https://github.com/patractlabs/europa.git\n\u003e cd europa/vendor\n\u003e git submodule update --init --recursive\n```\n\n#### compile\nThe compilation for this project is same as [substrate](https://github.com/paritytech/substrate/).\n\nOnce compilation is finished, current executable file is named `europa` in `target` directory.\n\n### Run\n#### Run Europa\n*Following example are built in debug mode. If you build with release mode, using `release` replace `debug` in following commands.*\n```bash\n$ ./target/debug/europa \n# if you what to specify a directory, add `-d` or `--base-path`\n$ ./target/debug/europa -d database\n# if you just want to test without storing the actual blockchain database, add `--tmp`\n$ ./target/debug/europa --tmp\n```\nthen, the Europa will start:\n```bash\nNov 12 17:10:14.524  INFO Europa Dev Node    \nNov 12 17:10:14.524  INFO ✌️  version 0.1.0-7b4463c-x86_64-linux-gnu    \nNov 12 17:10:14.524  INFO ❤️  by patract labs \u003chttps://github.com/patractlabs\u003e, 2020-2020    \nNov 12 17:10:14.524  INFO 📋 Chain specification: Development    \nNov 12 17:10:14.524  INFO 💾 Database: RocksDb at .sub/default/chains/dev/db    \nNov 12 17:10:14.524  INFO 📖 Workspace: default | Current workspace list: [\"default\"]    \nNov 12 17:10:14.524  INFO ⛓  Native runtime: europa-1 (europa-1.tx1.au1)    \nNov 12 17:10:14.986  INFO 🔨 Initializing Genesis block/state (state: 0x8fc7…d968, header-hash: 0xc7e1…7529)\nNov 12 17:10:14.988  INFO 📦 Highest known block at #0    \nNov 12 17:10:14.991  INFO Listening for new connections on 127.0.0.1:9944.   \n```\n#### Access Europa\nnow, you could use apps([https://polkadot.js.org/apps/](https://polkadot.js.org/apps/)) to access Europa:\n* click left tab to switch `DEVELOPMENT` - `Local Node`.\n* click `Settings` - `Developer`, and paste \"extending types\"(see [above](#extending-types)) to here:\n* click \"save\"\n\nthen, you could do transfer call as normal and could see the Europa log like:\n```bash\nNov 12 17:21:23.544  INFO Accepted a new tcp connection from 127.0.0.1:44210.    \nNov 12 17:21:32.238  INFO 🙌 Starting consensus session on top of parent 0xc7e1ce585807b34b7fecabe1242cafb2628c958b984ec0aee7727cdd34117529    \nNov 12 17:21:32.252  INFO 🎁 Prepared block for proposing at 1 [hash: 0x0109608217316a298c88135cf39a87cc31c37729fbe567b4a1a9f8dcdb81ebeb; parent_hash: 0xc7e1…7529; extrinsics (2): [0x2194…baf8, 0x0931…58bb]]    \nNov 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 } }    \n```\n\nMore operations please refers to the doc [Europa-CLI](https://docs.patract.io/en/europa/intro/europa-cli)\n\n## Plan/Reports\n1. v0.1: An independent runtime environment as the foundation for future developments (finished)\n\n    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.\n    For more details, please refer to [Report v0.1](https://docs.patract.io/en/europa/reports/v0.1Report)\n\n2. v0.2: `pallet-contract` modification to provide more information. (finish)\n\n    In this version, we forked the `pallet-contracts` module for the part of the error logging for contract developers, such as :\n    * WASM back trace, the function call stack during WASM contract execution;\n    * Contracts stack traces, the call stack of a contract calling another contract;\n    * Console.log, provides libraries and methods to print command lines during contract development;\n    * Strengthen the error type and error display of the contract module;\n    * Integration with Redspot;\n    \n3. v0.3: Improve the development experience, better integration with other tools, and extend the sandbox to be compatible with other runtime modules. (under development)\n\n    * Better integration with Redspot\n    * Better integration with polkadot.js.org/apps to achieve complete RPC support\n    * Support status data query\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatractlabs%2Feuropa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatractlabs%2Feuropa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatractlabs%2Feuropa/lists"}