From cf01a231546224ad498cbffc2633bdee040e37fe Mon Sep 17 00:00:00 2001 From: Christoph Burgdorf Date: Mon, 11 Jan 2021 14:51:16 +0100 Subject: [PATCH] Overhaul Readme Fixes #176 --- README.md | 212 +++++++++------------------------------ newsfragments/177.doc.md | 1 + 2 files changed, 46 insertions(+), 167 deletions(-) create mode 100644 newsfragments/177.doc.md diff --git a/README.md b/README.md index 1c8a2eeb16..ca1dd2f721 100644 --- a/README.md +++ b/README.md @@ -6,36 +6,12 @@ Fe is an emerging smart contract language for the Ethereum blockchain. [![Build Status](https://github.com/ethereum/fe/workflows/CI/badge.svg)](https://github.com/ethereum/fe/actions) [![Coverage](https://codecov.io/gh/ethereum/fe/branch/master/graph/badge.svg)](https://codecov.io/gh/ethereum/fe) -## Getting started - -- [Build the compiler](https://github.com/ethereum/fe/blob/master/docs/build.md) ## Overview -Fe is inspired by Vyper and aims to achieve the goals of the [existing Vyper -project](https://github.com/vyperlang/vyper) along with the following -additional goals: - -* Emphasis on correct implementation via use of better tooling, application of - formal methods, and stricter development practices -* A complete language specification to aid in verification of compiler - correctness -* Support for both eWASM and EVM code generation via use of the [YUL IR - format](https://solidity.readthedocs.io/en/v0.5.13/yul.html) -* Implementation in a powerful, systems-oriented language (Rust) with strong - safety guarantees -* Syntactic improvements and additional code re-use features -* Statically built compiler binaries for smoother installation process -* WASM compiler binaries for enhanced portability and in-browser compilation of - Fe contracts - -## Inherited goals +Fe is a statically typed language for the Ethereum Virtual Machine (EVM). It is inspired by Python and Rust and is easy to learn even for developers who are new to the Ethereum ecosystem. -Fe aims to achieve most of the goals of the [existing Vyper -project](https://github.com/vyperlang/vyper). Those goals are [described in -that project's -documentation](https://vyper.readthedocs.io/en/latest/index.html#principles-and-goals) -though we include a summary of them here: +## Features & Goals * Bounds and overflow checking * Decidability by limitation of dynamic program behavior @@ -45,152 +21,54 @@ though we include a summary of them here: * Binary fixed-point math * Restrictions on reentrancy * Static looping +* Module imports +* Standard library +* Usage of [YUL](https://docs.soliditylang.org/en/latest/yul.html) IR to target both EVM and eWASM +* WASM compiler binaries for enhanced portability and in-browser compilation of + Fe contracts +* Implementation in a powerful, systems-oriented language (Rust) with strong safety guarantees to reduce risk of compiler bugs + +Additional information about design goals and background can be found in the [official announcement](https://snakecharmers.ethereum.org/fe-a-new-language-for-the-ethereum-ecosystem/). + +## Language Specification + +We aim to provide a full language specification that should eventually be used to formally verify the correctness of the compiler. A work in progress draft of the specification can be found [here](https://github.com/ethereum/fe/blob/master/spec/index.md). + +## Progress -The following is a list of goals or aspects of the existing Vyper project that -we *do not necessarily* wish to duplicate: - -* Lack of code re-use features such as: - - Modifiers (re-usable assertions) - - Method resolution and class inheritance (though we're on the fence about - this) - - Module imports -* Strict enforcement of limits on dynamic behavior -- Though we aim to provide - Vyper's decidability by default, we believe it may also be useful to allow - disabling of decidability features if the expressivity trade-off doesn't make - sense for certain projects. - -## Additional goals - -### Stricter development practices - -We wish to promote the following development practices: - -* Thorough unit testing of *all* compiler components, from lexing and parsing - routines to type checking and compilation routines. -* Thorough integration testing of combined components to identify issues with - abstraction boundaries. -* Property-based testing or fuzz testing of components where appropriate. For - examples of property-based testing frameworks, see [QuickCheck for - Rust](https://github.com/BurntSushi/quickcheck), [QuickCheck for - Haskell](https://github.com/nick8325/quickcheck), and - [hypothesis](https://hypothesis.works/). -* The above testing goals should, at a minimum, give 100% code coverage but - should also redundantly test the same code sections in different modes of - use. -* Separation of concerns -- Components responsible for different stages of - compilation (parsing, type checking, compilation, etc.) should be clearly - separated into different libraries with distinct APIs. -* Maintainability -- Code should be written with future contributors in mind. - Complex features should not only be automatically tested but also described - in developer documentation. Code should be DRY and should include - abstractions that naturally encapsulate specific tasks. - -### Support for eWASM and EVM and the use of YUL - -We wish to leverage the YUL IR format as a means of targeting both the eWASM -and EVM platforms. YUL is actively developed by the Solidity community and we -see a great opportunity for synergy with the Solidity project through shared -use of YUL. - -### Use of Rust as an implementation language - -The Rust programming language has been a rising star in the PL community for a -number of years. We believe it provides a reasonable balance between the -following factors: - -* Type and memory safety -* Ease of use -* Expressivity -* Size and quality of developer community -* Availability of modern language idioms such as iterators, functional - programming features, etc. -* Support from established organizations such as Mozilla - -The Rust project and Mozilla foundation are also some of the primary drivers -behind the WASM project, which will likely end up playing a central role in the -Ethereum community. The Rust compiler is one of the premier compilers to -target the WASM platform. - -The use of a compiled language in general, and Rust in particular, will -facilitate improvements in the compiler release process. New compiler versions -could be offered as statically compiled binaries (removing dependence on -existing Python binaries) or as WASM binaries (opening up the possibility to -run Fe in-browser or, in the distant future, on-chain). - -### Language specification and formal methods - -We wish to provide a complete language specification with the following parts: - -* Syntax specification in extended BNF format similar to the [Python grammar - specification](https://docs.python.org/3/reference/grammar.html). -* An [operational, small-step - semantics](https://en.wikipedia.org/wiki/Operational_semantics#Small-step_semantics) - to describe correct program evaluation and behavior. -* Sections of informal prose to aid in understanding of the grammar, semantics, - their relationship, and the context in which they operate. - -A work in progress draft of the specification can be found [here](https://github.com/ethereum/fe/blob/master/spec/index.md). - -A secondary goal to providing a specification document could be to also provide -an executable specification via tools such as the [K -framework](http://www.kframework.org/index.php/Main_Page). Providing such an -executable specification may become a primary goal if it can be achieved -without too much effort and without hampering the achievement of other goals. - -Through the application of rigorous development practices and the availability -of a complete language specification, we hope to apply formal verification -methods to the Fe compiler and also to programs generated by it. - -## Progress and roadmap - -Development of Fe is currently in its early stages. Here's a rough -overview of recently completed work as well as some short and long-term goals. -None of these lists should be considered exhaustive and should also not be -considered to represent the exact prioritization of work items. - -### Recently achieved goals - -* [x] Completed port of [python's stdlib `tokenize` - module](https://github.com/python/cpython/blob/2a58b0636d1f620f8a85a2e4c030cc10551936a5/Lib/tokenize.py) - to Rust -* [x] Settled on overall design of parser -* [x] Completed a few basic parsers -* [x] All code is now tested on both native and WASM platforms with WASM - testing via node.js -* [x] Achieve ~100% code coverage by tests. Coverage is currently maximized at - ~99% due to some code paths being unreachable and our coverage tool currently - having no support for ignoring specific lines of code. -* [x] Identify an appropriate subset of the Python grammar and any grammatical - extensions needed to define a Fe EBNF grammar - - Eliminate certain Pythonic grammatical elements that don't apply to Fe - (such as `async` constructs, `lambda` expressions, argument packing syntax - like `*args` and `**kwargs`, etc.) - - Include grammatical elements that more directly capture Fe language - constructs (such as event, contract, or interface definitions, type - dimensions, etc.) -* [x] Finish writing parsers for the Fe EBNF grammar -* [x] Parse a basic greeter contract to AST -* [x] Compile the AST of a basic guest book contract to YUL -* [x] Generate YUL source code from YUL AST objects (via [yultsur](https://github.com/axic/yultsur/)) -* [x] Invoke the Solidity compiler with generated YUL source to produce a - compiled binary (via [solc-rust](https://github.com/axic/solc-rust)) -* [x] Implement a functional [ERC20 token contract](https://github.com/ethereum/fe/blob/00121f5ec06e46fcca261ad4d340f43e7183c2c7/compiler/tests/fixtures/erc20_token.fe) in Fe and compile it. - -### Short-term goals - -* [ ] Implement a functional Uniswap Demo in Fe - -### Long-term goals - -* Implement compilation routines for the full set of current Fe features -* Implement a YUL compiler in Rust to eliminate the need to interact with the - Solidity compiler -* Formally verify the Fe compiler using the language specification +Fe development is still in its early stages. We have a basic [Roadmap for 2021](https://notes.ethereum.org/LVhaTF30SJOpkbG1iVw1jg) that we want to follow. We generally try to drive the development by working through real world use cases. Our next goal is to provide a working Uniswap implementation in Fe which will help us to advance and form the language. + +The first alpha version will be out in January 2021, followed by another release every month. ## Examples -We have a [functional ERC-20 demo](https://github.com/ethereum/fe/blob/00121f5ec06e46fcca261ad4d340f43e7183c2c7/compiler/tests/fixtures/erc20_token.fe) as well as many other examples as part of our [fixture tests](https://github.com/ethereum/fe/tree/master/compiler/tests/fixtures). +The following is a simple contract implemented in Fe. + +``` +type BookMsg = bytes[100] + +contract GuestBook: + pub guest_book: map + + event Signed: + book_msg: BookMsg + + pub def sign(book_msg: BookMsg): + self.guest_book[msg.sender] = book_msg + + emit Signed(book_msg=book_msg) + pub def get_msg(addr: address) -> BookMsg: + return self.guest_book[addr].to_mem() +``` + +A lot more working examples can be found in our [test fixtures directory](https://github.com/ethereum/fe/tree/master/compiler/tests/fixtures). + +The most advanced example that we can provide at this point is a fully working [ERC20 implementation](https://github.com/ethereum/fe/blob/master/compiler/tests/fixtures/erc20_token.fe). + +## Getting started + +- [Build the compiler](https://github.com/ethereum/fe/blob/master/docs/build.md) ## Community diff --git a/newsfragments/177.doc.md b/newsfragments/177.doc.md new file mode 100644 index 0000000000..e0b49fa616 --- /dev/null +++ b/newsfragments/177.doc.md @@ -0,0 +1 @@ +Overhaul README page to better reflect the current state of the project. \ No newline at end of file