Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tezedge/tezedge-specification
TLA+ specs and models for the TezEdge node's p2p overlay network, shell, and consensus
https://github.com/tezedge/tezedge-specification
formal-verification tezos tezos-blockchain tla tla-specification tlaplus
Last synced: 3 months ago
JSON representation
TLA+ specs and models for the TezEdge node's p2p overlay network, shell, and consensus
- Host: GitHub
- URL: https://github.com/tezedge/tezedge-specification
- Owner: tezedge
- License: mit
- Created: 2020-12-29T17:38:44.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-12-14T21:31:04.000Z (almost 3 years ago)
- Last Synced: 2024-07-16T18:12:05.261Z (4 months ago)
- Topics: formal-verification, tezos, tezos-blockchain, tla, tla-specification, tlaplus
- Language: TLA
- Homepage:
- Size: 3.18 MB
- Stars: 20
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tezedge-specification
This project contains various formal specifications and models for different aspects of the Tezedge node's p2p overlay network, shell, and consensus.
In the security-critical realm of blockchains, it is not enough to simply test our software. Since these systems contain sensitive financial information and business logic, we believe that it is absolutely necessary to formally verify the code we write.
Part of the formal verification process focuses on the design we intend to implement in our code. This is the realm of formal specification and model checking. TLA+, our formal specification language of choice, is well-known, widely used, and particularly well-suited to reasoning about concurrent and distributed algorithms.
Formal specification and model checking give us assurance and verification that our algorithms have the intended properties and no undesirable behavior. Formal specification is, of course, not a replacement for testing, but a necessary companion and counterpart. TLA+ gives one the ability to exhaustively check all possible behaviors of a system.
See [project navigation](./README.md#project-navigation) for a brief description of each directory's contents.
## Quick start
### TLA+
Download and install the latest release of the [TLA+ toolbox](https://github.com/tlaplus/tlaplus/releases/tag/v1.7.1).
[TLA+](https://lamport.azurewebsites.net/tla/tla.html) is our chosen specification language. It enables one to encode the specification of a state machine, as well as its safety and liveness properties, in the language of [temporal logic of actions](https://lamport.azurewebsites.net/pubs/lamport-actions.pdf). TLA+ comes with an explicit state model checker, [TLC](https://github.com/tlaplus/tlaplus), which exhaustively checks all behaviors of the specified state machine, verifies its properties, and provides counterexamples to violated properties.
### Apalache
[Apalache](https://github.com/informalsystems/apalache) is a symbolic model checker for TLA+; Apalache translates TLA+ into the logic supported by SMT solvers such as Z3.
We use Apalache extensively in this project to typecheck specifications and verify inductive (safety) invariants (see [Apalache docs](https://apalache.informal.systems/docs/apalache/index.html)). The easiest way to get and run Apalache is with [docker](https://apalache.informal.systems/docs/apalache/installation/docker.html):
1. Pull the `unstable` image (one may use the `latest` image, but `unstable` provides more features)
```
$ docker pull apalache/mc:unstable
```
2. Set an alias for the `unstable` image (if you're using Linux or macOS)
```
$ alias apalache='docker run --rm -v $(pwd):/var/apalache apalache/mc:unstable'
```
3. Verify that the setup works
```
$ apalache version
```
Note that this command will generate a `detailed.log` file in the directory in which it is run.
Specific instructions to verify inductive invariants are provided in the corresponding spec's directory.
### TLA+ command line tool
The default way to write TLA+ specs and run the model checker (TLC) is through the (graphical) toolbox. However, for the ease of running TLC on a remote server, one may be interested in also getting the TLA+ command line tool [tla-bin](https://github.com/pmer/tla-bin). Installation instructions are provided in that repo.
### TLA+ VSCode extension
For those who prefer to work in VSCode, there is the extension [vscode-tlaplus](https://github.com/alygin/vscode-tlaplus) which is well-maintained and highly recommended.
## Project navigation
There are three main objects of focus for our specifications, corresponding to the three layers in Tezos: `p2p`, `shell`, and `consensus`
### p2p
This project contains specifications and models related to the p2p overlay network:
- [hanshaking](./p2p/handshaking)
- I/O resource management
- counter
- scheduler
### shell
This project contains specifications and models related to the shell:
- [bootstrapping](./shell/bootstrapping)
- distributed_db
- [mempool](./shell/mempool)
### consensus
This project contains specifications and models related to consensus:
- [Emmy/Emmy+/Emmy★](./consensus/Emmy)
- [Tenderbake](./consensus/Tenderbake)
### utils
This project contains TLA+ functions and operators used extensively in the other projects