{"id":29193921,"url":"https://github.com/intersectmbo/cardano-formal-specifications","last_synced_at":"2026-02-04T16:02:53.904Z","repository":{"id":279439102,"uuid":"938811913","full_name":"IntersectMBO/cardano-formal-specifications","owner":"IntersectMBO","description":"Formal specifications for the Cardano Blockchain","archived":false,"fork":false,"pushed_at":"2026-01-27T16:28:35.000Z","size":176,"stargazers_count":4,"open_issues_count":7,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-01-28T02:59:34.414Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TeX","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/IntersectMBO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-25T14:42:01.000Z","updated_at":"2025-12-08T11:48:35.000Z","dependencies_parsed_at":"2025-02-25T15:44:18.429Z","dependency_job_id":"cf4e8f07-f195-4f8c-b327-baf253fbe9c6","html_url":"https://github.com/IntersectMBO/cardano-formal-specifications","commit_stats":null,"previous_names":["intersectmbo/cardano-formal-specifications"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/IntersectMBO/cardano-formal-specifications","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-formal-specifications","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-formal-specifications/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-formal-specifications/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-formal-specifications/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IntersectMBO","download_url":"https://codeload.github.com/IntersectMBO/cardano-formal-specifications/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-formal-specifications/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29089915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2025-07-02T03:37:12.746Z","updated_at":"2026-02-04T16:02:53.890Z","avatar_url":"https://github.com/IntersectMBO.png","language":"TeX","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cardano Formal Specifications\n\nThis repository is used to provide a top level entry point to the full\ncollection of formal specifications for Cardano for current and future\nfeatures.\n\nMost specifications are in their own repositories which we link to\nbelow. The Cardano performance model will be is in this repo. In the\nfuture it may also house a 'Cardano Node properties' library, which\nwould combine the Consensus and Ledger specifications and prove\ncombined properties about them that cannot be stated or proven about\neither of them alone.\n\nThis readme is in three sections: section one is a table of contents\nlisting all the areas the specifications cover; section two goes into\nmore detail about the current state of each component of the node,\nwith links to pdf artifacts, and source repositories; section three\ncovers new features for Cardano that are currently in the R\u0026D phase.\n\n# Table of Contents\n\n| Components  |\n|-------------|\n| [Plutus Core](#plutus-specifications) |\n| [Ledger](#ledger-specifications) |\n| [Consensus](#consensus-specifications) |\n| [Networking](#networking-specifications) |\n| [Performance model](#performance-model) |\n\n| New features |\n|--------------|\n| [Nested Transactions](#nested-transactions) |\n| [Peras](#peras) |\n| [Leios](#leios) |\n\n# Cardano Specifications\n\nThe Cardano Specifications are intended to provide a language agnostic\nsingle-source-of-truth reference for key components of the\nsystem. The are intended to communicate how the system works to\nimplementors, innovators, and technical community members.\n\nA second important use beyond a reference of how the system is now is\nto provide a baseline and communication medium for developing new\nfeatures.\n\nThe specifications are presented in formal notation using computer\nscience concepts familiar to somebody who has completed the first\nyear of a undergraduate computer science course or who has equivalent\nprofessional experience.\n\nThe approach we have taken to write the specs has evolved over\ntime. We started with PDF documents written in LaTeX and now we\ngenerate PDFs and also executable specifications (reference\nimplementations/test oracles usually in Haskell). While aiming to stay\nas close as possible to the style for the reader we now write our\nspecifications in Agda and generate both the readable PDF and the\nexecutable specifications from the Agda source code. This gives us the\nbenefit of type checking our definitions, using the executable\nspecifications for conformance testing and also the ability to prove\nproperties about the design and have these formally verified.\n\n## Plutus specifications\n\nPlutus has two specifications:\n\n1. The [metatheory](https://github.com/IntersectMBO/plutus/tree/master/plutus-metatheory)\nis an Agda specification of both the typed and untyped layers of the\nPlutus Core language, and includes a specification for the CEK machine\nwhich evaluates them.\n\n2. Additionally, there is the\n\"[paper](https://plutus.cardano.intersectmbo.org/resources/plutus-core-spec.pdf)\"\nspecification document which defines the language elements, and has\ndenotational semantics for each of the supported builtin operations.\n\nDiscussions are ongoing about how to merge or otherwise get the both\nof both worlds here.\n\n### Properties\n\n### Testing\n\nPlutus also has a conformance test suite which can be used to ensure\nconformant behaviour between executable specification, Haskell and\nother implementations. This was previously used to conformance test a\nuplc implementation built by RV.\n\n## Ledger specifications\n\nThe ledger is our biggest and longest running specification project.\n\nWe have specifications going all the way back to Byron and the whole\nsystem up to the present Conway era is covered.\n\nEarlier specs (Byron to Babbage) are documents written in\nmathematical/Computer Science notation. They are written in LaTeX and\nreadable in PDF.\n\nSince Conway we have moved to a machine checked specification written\nin Agda, again readable in PDF but also type checked, executable and\nwith machine verified proofs of key properties. The aim of this\nproject was to stay as close as possible to the style of the earlier\nspecifications for readability, while gaining the benefits of type\nchecking the definitions, and new abilities to compile to Haskell for\ntesting purposes and supporting machine checked proofs of properties\nsuch as preservation of value.\n\nEarlier specs followed an approach of adding a 'delta' spec for the\nfunctionality added by each new era rather than a complete new self\ncontained spec. We did this also for Conway but we're currently\nworking adding all the functionality from previous eras into a\ncomplete spec - contributions welcome!\n\n\nEra | Design Documents | Formal Specification | CDDL\n----|------------------|----------------------|-----\nByron | | [Chain Spec](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/byron-blockchain.pdf \"Specification of the Blockchain Layer\"), [Ledger Spec](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/byron-ledger.pdf \"A Formal Specification of the Cardano Ledger\") | [CDDL](https://github.com/intersectmbo/cardano-ledger/tree/master/eras/byron/cddl-spec/byron.cddl), [PDF](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/byron-binary.pdf)\nShelley | [Design](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/shelley-delegation.pdf \"Design Specification for Delegation and Incentives in Cardano\") | [Spec](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/shelley-ledger.pdf \"A Formal Specification of the Cardano Ledger\") | [CDDL](https://github.com/intersectmbo/cardano-ledger/tree/master/eras/shelley/impl/cddl-files)\nAllegra | Same as Mary era below | Same as Mary era below | [CDDL](https://github.com/intersectmbo/cardano-ledger/tree/master/eras/allegra/impl/cddl-files)\nMary | [Multi-Currency](https://eprint.iacr.org/2020/895 \"Multi-Currency Ledgers\"), [UTXOma](https://iohk.io/en/research/library/papers/utxoma-utxo-with-multi-asset-support/ \"UTXOma:UTXO with Multi-Asset Support\") | [Spec](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/mary-ledger.pdf \"A Formal Specification of the Cardano Ledger with a Native Multi-Asset Implementation\") | [CDDL](https://github.com/intersectmbo/cardano-ledger/tree/master/eras/mary/impl/cddl-files)\nAlonzo | [eUTXO](https://iohk.io/en/research/library/papers/the-extended-utxo-model/ \"The Extended UTXO Model\")| [Spec](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/alonzo-ledger.pdf \"A Formal Specification of the Cardano Ledger integrating Plutus Core\") | [CDDL](https://github.com/intersectmbo/cardano-ledger/tree/master/eras/alonzo/impl/cddl-files)\nBabbage | [batch-verification](https://iohk.io/en/research/library/papers/on-uc-secure-range-extension-and-batch-verification-for-ecvrf/ \"On UC-Secure Range Extension and Batch Verification for ECVRF\"), [CIP-31](https://github.com/cardano-foundation/CIPs/pull/159 \"Reference inputs\"), [CIP-32](https://github.com/cardano-foundation/CIPs/pull/160 \"Inline datums\"), [CIP-33](https://github.com/cardano-foundation/CIPs/pull/161 \"Reference scripts\") | [Spec](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/babbage-ledger.pdf \"Formal Specification of the Cardano Ledger for the Babbage era\") | [CDDL](https://github.com/intersectmbo/cardano-ledger/tree/master/eras/babbage/impl/cddl-files)\n| Conway | | https://github.com/IntersectMBO/formal-ledger-specifications |\n\nOther Documents:\n- [Non-integer calculations specification](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/non-integer-calculations.pdf): details on the parts of the Shelley specification that use real numbers.\n- [Stake pool ranking specification](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/pool-ranking.pdf): details for a robust stake pool ranking mechanism.\n- [Explanation of the small-step-semantics framework](https://github.com/intersectmbo/cardano-ledger/releases/latest/download/small-step-semantics.pdf): a guide to the notation and style used by our ledger rules.\n\n### Properties\n\n### Testing\n\nThe ledger specification is actively used for conformance testing. As\nmore previous era features are added more coverage will be possible.\n\n## Consensus specifications\n\nThe consensus specification is a relatively new effort that in the\nfirst instance focusses on block headers. This is essentially the part\nof the chain that the consensus layer cares about.\n\nGenerated PDF file:\nhttps://ouroboros-consensus.cardano.intersectmbo.org/assets/files/consensus-spec-agda-f25982fd23b1e0baface9345c26549e0.pdf\n\nSource repository:\nhttps://github.com/IntersectMBO/ouroboros-consensus/tree/main/docs/agda-spec\n\nA formal model of Ouroboros Praos and its corresponding proofs of\nsafety and liveness are currently WIP, see\nhttps://github.com/input-output-hk/ouroboros-praos-formal-spec.\n\n### Properties\n\n### Testing\n\nThe block header specification is executable and usable for conformance testing.\n\n## Networking specifications\n\n\n## Performance model\n\nThis repository includes a subdirectory src/performance that contains\na literate Haskell file that documents a performance model of Cardano\nblock diffusion. This is intended to provide a baseline from which the\npotential consequences of parameter or design changes on the\ntimeliness of block diffusion can be investigated.\n\n# New features\n\n## Nested Transactions\n\n\"Nested Transactions\" (see [CIP](https://github.com/cardano-foundation/CIPs/pull/862))\nconstitutes a set of (primarily ledger) changes that revolve around supporting a\nspecific kind of transaction batching. This type of transaction batching allows batches to be constructed using \none-way communication, meaning that users submitting transactions do not need to approve the completed batches\ninto which their transactions get added by batchers. This is  \nreferred to as *counterparty irrelevance*. There are no restrictions on who can run batching services.\nA nested transactions batch consists of a list of sub-transactions, and a single top-level transaction, \nwhich fixes the contents of the batch.\n\nBatches supported as part of this feature may contain unbalanced transactions, however, the full \nbatch is required to balance.\nThe primary purpose for introducing this feature is to enable processing transactions constructed \nwithout any ada. The most common anticipated use case for this feature is atomic swaps, \nin particular, of non-ada tokens for the ada required for the system fees and script collateral. \n\nThe [formal specification](https://github.com/IntersectMBO/formal-ledger-specifications/blob/polina-nested-txs/)\nis available.\n\n## Peras\n\nOuroboros Peras is an extension of Ouroboros Praos adding a voting layer to achieve faster settlement. The details of the protocol are explained in the [CIP](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0140/README.md).\nThe [formal specification](https://github.com/input-output-hk/peras-design/blob/main/src/Peras/SmallStep.lagda.md) of the Peras protocol was built with a focus on conformance testing: a testing model has been lifted into Agda and proofed sound with respect to the formal specification of Peras.\n\n## Leios\n\nThe [formal specification](https://github.com/input-output-hk/ouroboros-leios-formal-spec) for Leios implements different variants of the Leios Protocol. In addition to the relational specification there is also a deterministic specification, that can be run as model in conformance tests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintersectmbo%2Fcardano-formal-specifications","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintersectmbo%2Fcardano-formal-specifications","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintersectmbo%2Fcardano-formal-specifications/lists"}