{"id":13961743,"url":"https://github.com/tezedge/tezedge-specification","last_synced_at":"2025-07-21T06:31:48.457Z","repository":{"id":45420295,"uuid":"325349529","full_name":"tezedge/tezedge-specification","owner":"tezedge","description":"TLA+ specs and models for the TezEdge node's p2p overlay network, shell, and consensus","archived":false,"fork":false,"pushed_at":"2021-12-14T21:31:04.000Z","size":3335,"stargazers_count":20,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-28T07:34:38.987Z","etag":null,"topics":["formal-verification","tezos","tezos-blockchain","tla","tla-specification","tlaplus"],"latest_commit_sha":null,"homepage":"","language":"TLA","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tezedge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-29T17:38:44.000Z","updated_at":"2023-03-31T05:01:13.000Z","dependencies_parsed_at":"2022-08-29T23:41:01.703Z","dependency_job_id":null,"html_url":"https://github.com/tezedge/tezedge-specification","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tezedge/tezedge-specification","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tezedge%2Ftezedge-specification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tezedge%2Ftezedge-specification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tezedge%2Ftezedge-specification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tezedge%2Ftezedge-specification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tezedge","download_url":"https://codeload.github.com/tezedge/tezedge-specification/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tezedge%2Ftezedge-specification/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266253576,"owners_count":23900052,"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":["formal-verification","tezos","tezos-blockchain","tla","tla-specification","tlaplus"],"created_at":"2024-08-08T17:01:24.478Z","updated_at":"2025-07-21T06:31:43.448Z","avatar_url":"https://github.com/tezedge.png","language":"TLA","funding_links":[],"categories":["TLA"],"sub_categories":[],"readme":"# tezedge-specification\n\nThis project contains various formal specifications and models for different aspects of the Tezedge node's p2p overlay network, shell, and consensus.\n\nIn 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.\n\nPart 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.\n\nFormal 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.\n\nSee [project navigation](./README.md#project-navigation) for a brief description of each directory's contents.\n\n## Quick start\n\n### TLA+\n\nDownload and install the latest release of the [TLA+ toolbox](https://github.com/tlaplus/tlaplus/releases/tag/v1.7.1).\n\n[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.\n\n### Apalache\n\n[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.\n\nWe 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):\n\n1. Pull the `unstable` image (one may use the `latest` image, but `unstable` provides more features)\n\n```\n$ docker pull apalache/mc:unstable\n```\n\n2. Set an alias for the `unstable` image (if you're using Linux or macOS)\n\n```\n$ alias apalache='docker run --rm -v $(pwd):/var/apalache apalache/mc:unstable'\n```\n\n3. Verify that the setup works\n\n```\n$ apalache version\n```\n\nNote that this command will generate a `detailed.log` file in the directory in which it is run.\n\nSpecific instructions to verify inductive invariants are provided in the corresponding spec's directory.\n\n### TLA+ command line tool\n\nThe 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.\n\n### TLA+ VSCode extension\n\nFor 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.\n\n## Project navigation\n\nThere are three main objects of focus for our specifications, corresponding to the three layers in Tezos: `p2p`, `shell`, and `consensus`\n\n### p2p\n\nThis project contains specifications and models related to the p2p overlay network:\n\n- [hanshaking](./p2p/handshaking)\n- I/O resource management\n  - counter\n  - scheduler\n\n### shell\n\nThis project contains specifications and models related to the shell:\n\n- [bootstrapping](./shell/bootstrapping)\n- distributed_db\n- [mempool](./shell/mempool)\n\n### consensus\n\nThis project contains specifications and models related to consensus:\n\n- [Emmy/Emmy+/Emmy★](./consensus/Emmy)\n- [Tenderbake](./consensus/Tenderbake)\n\n### utils\n\nThis project contains TLA+ functions and operators used extensively in the other projects\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftezedge%2Ftezedge-specification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftezedge%2Ftezedge-specification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftezedge%2Ftezedge-specification/lists"}