Skip to content

Commit

Permalink
Overhaul Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@cburgdorf
cburgdorf committed Jan 11, 2021
1 parent 8b00838 commit 37e459d
Showing 1 changed file with 44 additions and 167 deletions.
211 changes: 44 additions & 167 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -45,152 +21,53 @@ though we include a summary of them here:
* Binary fixed-point math
* Restrictions on reentrancy
* Static looping
* Module imports
* 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<address, BookMsg>
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

Expand Down

0 comments on commit 37e459d

Please sign in to comment.