diff --git a/.circleci/config.yml b/.circleci/config.yml index 02f3b073f..3f9c638cf 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -33,6 +33,9 @@ jobs: - run: name: markdown lint command: just lint-specs-md-check + - run: + name: markdown toc + command: just lint-specs-toc-check lint-links: machine: image: <> diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index c7205be36..9d32c5f9b 100644 --- a/.github/workflows/deploy.yaml +++ b/.github/workflows/deploy.yaml @@ -24,7 +24,7 @@ jobs: mdbook-version: "latest" - name: Install mdbook plugins run: | - cargo install mdbook-katex mdbook-toc mdbook-linkcheck mdbook-mermaid + cargo install mdbook-katex mdbook-linkcheck mdbook-mermaid - name: Build book run: mdbook build - name: Deploy diff --git a/Justfile b/Justfile index f3ee9f43f..e3cad5e59 100644 --- a/Justfile +++ b/Justfile @@ -7,6 +7,9 @@ lint-specs-md-check: lint-specs-md-fix: npx markdownlint-cli2-fix "./specs/**/*.md" +lint-specs-toc-check: + npx doctoc '--title=**Table of Contents**' ./specs + lint-links: docker run --init -it -v `pwd`:/input lycheeverse/lychee --verbose --no-progress --exclude-loopback \ --exclude twitter.com --exclude explorer.optimism.io --exclude linux-mips.org --exclude vitalik.ca \ diff --git a/README.md b/README.md index f5644634e..ad0ff4054 100644 --- a/README.md +++ b/README.md @@ -24,11 +24,44 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh **`mdbook` + plugins** ```sh -cargo install mdbook mdbook-katex mdbook-toc mdbook-linkcheck mdbook-mermaid +cargo install mdbook mdbook-katex mdbook-linkcheck mdbook-mermaid ``` ### Serving the book locally ```sh -mdbook serve +just serve ``` + +### Linting + +`doctoc` is used to automatically add a table of contents. + +```sh +just lint-specs-toc-check +``` + +To fix markdown linting errors: + +```sh +just lint-specs-md-fix +``` + +See the [markdownlint rule reference](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) +and an example [config file](https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.jsonc). + +Justification for linting rules in +[.markdownlint.json](https://github.com/ethereum-optimism/specs/blob/main/.markdownlint.json): + +- _line_length_ (`!strict && stern`): don't trip up on url lines +- _no-blanks-blockquote_: enable multiple consecutive blockquotes separated by white lines +- _single-title_: enable reusing `

` for content +- _no-emphasis-as-heading_: enable emphasized paragraphs + +To lint links: + +```sh +just lint-links +``` + +[lychee][lychee] is used for linting links. diff --git a/book.toml b/book.toml index 411654b0e..1d9abe101 100644 --- a/book.toml +++ b/book.toml @@ -8,10 +8,6 @@ title = "OP Stack Specification" [preprocessor.katex] after = ["links"] -[preprocessor.toc] -command = "mdbook-toc" -renderer = ["html"] - [preprocessor.mermaid] command = "mdbook-mermaid" diff --git a/package.json b/package.json index d92a19e68..4c60bedad 100644 --- a/package.json +++ b/package.json @@ -7,6 +7,7 @@ "pnpm": ">=8" }, "dependencies": { + "doctoc": "^2.2.1", "markdownlint-cli2": "0.4.0" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d70f4262e..fd5817ed0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -5,6 +5,9 @@ settings: excludeLinksFromLockfile: false dependencies: + doctoc: + specifier: ^2.2.1 + version: 2.2.1 markdownlint-cli2: specifier: 0.4.0 version: 0.4.0 @@ -32,6 +35,42 @@ packages: fastq: 1.16.0 dev: false + /@textlint/ast-node-types@12.6.1: + resolution: {integrity: sha512-uzlJ+ZsCAyJm+lBi7j0UeBbj+Oy6w/VWoGJ3iHRHE5eZ8Z4iK66mq+PG/spupmbllLtz77OJbY89BYqgFyjXmA==} + dev: false + + /@textlint/markdown-to-ast@12.6.1: + resolution: {integrity: sha512-T0HO+VrU9VbLRiEx/kH4+gwGMHNMIGkp0Pok+p0I33saOOLyhfGvwOKQgvt2qkxzQEV2L5MtGB8EnW4r5d3CqQ==} + dependencies: + '@textlint/ast-node-types': 12.6.1 + debug: 4.3.4 + mdast-util-gfm-autolink-literal: 0.1.3 + remark-footnotes: 3.0.0 + remark-frontmatter: 3.0.0 + remark-gfm: 1.0.0 + remark-parse: 9.0.0 + traverse: 0.6.8 + unified: 9.2.2 + transitivePeerDependencies: + - supports-color + dev: false + + /@types/mdast@3.0.15: + resolution: {integrity: sha512-LnwD+mUEfxWMa1QpDraczIn6k0Ee3SMicuYSSzS6ZYl2gKS09EClnJYGd8Du6rfc5r/GZEk5o1mRb8TaTj03sQ==} + dependencies: + '@types/unist': 2.0.10 + dev: false + + /@types/unist@2.0.10: + resolution: {integrity: sha512-IfYcSBWE3hLpBg8+X2SEa8LVkJdJEkT2Ese2aaLs3ptGdVtABxndrMaxuFlQ1qdFf9Q5rDvDpxI3WwgvKFAsQA==} + dev: false + + /anchor-markdown-header@0.6.0: + resolution: {integrity: sha512-v7HJMtE1X7wTpNFseRhxsY/pivP4uAJbidVhPT+yhz4i/vV1+qx371IXuV9V7bN6KjFtheLJxqaSm0Y/8neJTA==} + dependencies: + emoji-regex: 10.1.0 + dev: false + /argparse@2.0.1: resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} dev: false @@ -41,6 +80,10 @@ packages: engines: {node: '>=12'} dev: false + /bail@1.0.5: + resolution: {integrity: sha512-xFbRxM1tahm08yHBP16MMjVUAvDaBMD38zsM9EMAUN61omwLmKlOpB/Zku5QkjZ8TZ4vn53pj+t518cH0S03RQ==} + dev: false + /braces@3.0.2: resolution: {integrity: sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==} engines: {node: '>=8'} @@ -48,6 +91,34 @@ packages: fill-range: 7.0.1 dev: false + /ccount@1.1.0: + resolution: {integrity: sha512-vlNK021QdI7PNeiUh/lKkC/mNHHfV0m/Ad5JoI0TYtlBnJAslM/JIkm/tGC88bkLIwO6OQ5uV6ztS6kVAtCDlg==} + dev: false + + /character-entities-legacy@1.1.4: + resolution: {integrity: sha512-3Xnr+7ZFS1uxeiUDvV02wQ+QDbc55o97tIV5zHScSPJpcLm/r0DFPcoY3tYRp+VZukxuMeKgXYmsXQHO05zQeA==} + dev: false + + /character-entities@1.2.4: + resolution: {integrity: sha512-iBMyeEHxfVnIakwOuDXpVkc54HijNgCyQB2w0VfGQThle6NXn50zU6V/u+LDhxHcDUPojn6Kpga3PTAD8W1bQw==} + dev: false + + /character-reference-invalid@1.1.4: + resolution: {integrity: sha512-mKKUkUbhPpQlCOfIuZkvSEgktjPFIsZKRRbC6KWVEMvlzblj3i3asQv5ODsrwt0N3pHAEvjP8KTQPHkp0+6jOg==} + dev: false + + /debug@4.3.4: + resolution: {integrity: sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==} + engines: {node: '>=6.0'} + peerDependencies: + supports-color: '*' + peerDependenciesMeta: + supports-color: + optional: true + dependencies: + ms: 2.1.2 + dev: false + /dir-glob@3.0.1: resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==} engines: {node: '>=8'} @@ -55,10 +126,69 @@ packages: path-type: 4.0.0 dev: false + /doctoc@2.2.1: + resolution: {integrity: sha512-qNJ1gsuo7hH40vlXTVVrADm6pdg30bns/Mo7Nv1SxuXSM1bwF9b4xQ40a6EFT/L1cI+Yylbyi8MPI4G4y7XJzQ==} + hasBin: true + dependencies: + '@textlint/markdown-to-ast': 12.6.1 + anchor-markdown-header: 0.6.0 + htmlparser2: 7.2.0 + minimist: 1.2.8 + underscore: 1.13.6 + update-section: 0.3.3 + transitivePeerDependencies: + - supports-color + dev: false + + /dom-serializer@1.4.1: + resolution: {integrity: sha512-VHwB3KfrcOOkelEG2ZOfxqLZdfkil8PtJi4P8N2MMXucZq2yLp75ClViUlOVwyoHEDjYU433Aq+5zWP61+RGag==} + dependencies: + domelementtype: 2.3.0 + domhandler: 4.3.1 + entities: 2.1.0 + dev: false + + /domelementtype@2.3.0: + resolution: {integrity: sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==} + dev: false + + /domhandler@4.3.1: + resolution: {integrity: sha512-GrwoxYN+uWlzO8uhUXRl0P+kHE4GtVPfYzVLcUxPL7KNdHKj66vvlhiweIHqYYXWlw+T8iLMp42Lm67ghw4WMQ==} + engines: {node: '>= 4'} + dependencies: + domelementtype: 2.3.0 + dev: false + + /domutils@2.8.0: + resolution: {integrity: sha512-w96Cjofp72M5IIhpjgobBimYEfoPjx1Vx0BSX9P30WBdZW2WIKU0T1Bd0kz2eNZ9ikjKgHbEyKx8BB6H1L3h3A==} + dependencies: + dom-serializer: 1.4.1 + domelementtype: 2.3.0 + domhandler: 4.3.1 + dev: false + + /emoji-regex@10.1.0: + resolution: {integrity: sha512-xAEnNCT3w2Tg6MA7ly6QqYJvEoY1tm9iIjJ3yMKK9JPlWuRHAMoe5iETwQnx3M9TVbFMfsrBgWKR+IsmswwNjg==} + dev: false + /entities@2.1.0: resolution: {integrity: sha512-hCx1oky9PFrJ611mf0ifBLBRW8lUUVRlFolb5gWRfIELabBlbp9xZvrqZLZAs+NxFnbfQoeGd8wDkygjg7U85w==} dev: false + /entities@3.0.1: + resolution: {integrity: sha512-WiyBqoomrwMdFG1e0kqvASYfnlb0lp8M5o5Fw2OFq1hNZxxcNk8Ik0Xm7LxzBhuidnZB/UtBqVCgUz3kBOP51Q==} + engines: {node: '>=0.12'} + dev: false + + /escape-string-regexp@4.0.0: + resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==} + engines: {node: '>=10'} + dev: false + + /extend@3.0.2: + resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==} + dev: false + /fast-glob@3.3.2: resolution: {integrity: sha512-oX2ruAFQwf/Orj8m737Y5adxDQO0LAB7/S5MnxCdTNDd4p6BsyIVsv9JQsATbTSq8KHRpLwIHbVlUNatxd+1Ow==} engines: {node: '>=8.6.0'} @@ -76,6 +206,12 @@ packages: reusify: 1.0.4 dev: false + /fault@1.0.4: + resolution: {integrity: sha512-CJ0HCB5tL5fYTEA7ToAq5+kTwd++Borf1/bifxd9iT70QcXr4MRrO3Llf8Ifs70q+SJcGHFtnIE/Nw6giCtECA==} + dependencies: + format: 0.2.2 + dev: false + /fill-range@7.0.1: resolution: {integrity: sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==} engines: {node: '>=8'} @@ -83,6 +219,11 @@ packages: to-regex-range: 5.0.1 dev: false + /format@0.2.2: + resolution: {integrity: sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==} + engines: {node: '>=0.4.x'} + dev: false + /glob-parent@5.1.2: resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==} engines: {node: '>= 6'} @@ -102,11 +243,40 @@ packages: slash: 4.0.0 dev: false + /htmlparser2@7.2.0: + resolution: {integrity: sha512-H7MImA4MS6cw7nbyURtLPO1Tms7C5H602LRETv95z1MxO/7CP7rDVROehUYeYBUYEON94NXXDEPmZuq+hX4sog==} + dependencies: + domelementtype: 2.3.0 + domhandler: 4.3.1 + domutils: 2.8.0 + entities: 3.0.1 + dev: false + /ignore@5.3.0: resolution: {integrity: sha512-g7dmpshy+gD7mh88OC9NwSGTKoc3kyLAZQRU1mt53Aw/vnvfXnbC+F/7F7QoYVKbV+KNvJx8wArewKy1vXMtlg==} engines: {node: '>= 4'} dev: false + /is-alphabetical@1.0.4: + resolution: {integrity: sha512-DwzsA04LQ10FHTZuL0/grVDk4rFoVH1pjAToYwBrHSxcrBIGQuXrQMtD5U1b0U2XVgKZCTLLP8u2Qxqhy3l2Vg==} + dev: false + + /is-alphanumerical@1.0.4: + resolution: {integrity: sha512-UzoZUr+XfVz3t3v4KyGEniVL9BDRoQtY7tOyrRybkVNjDFWyo1yhXNGrrBTQxp3ib9BLAWs7k2YKBQsFRkZG9A==} + dependencies: + is-alphabetical: 1.0.4 + is-decimal: 1.0.4 + dev: false + + /is-buffer@2.0.5: + resolution: {integrity: sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==} + engines: {node: '>=4'} + dev: false + + /is-decimal@1.0.4: + resolution: {integrity: sha512-RGdriMmQQvZ2aqaQq3awNA6dCGtKpiDFcOzrTWrDAT2MiWrKQVPmxLGHl7Y2nNu6led0kEyoX0enY0qXYsv9zw==} + dev: false + /is-extglob@2.1.1: resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==} engines: {node: '>=0.10.0'} @@ -119,17 +289,30 @@ packages: is-extglob: 2.1.1 dev: false + /is-hexadecimal@1.0.4: + resolution: {integrity: sha512-gyPJuv83bHMpocVYoqof5VDiZveEoGoFL8m3BXNb2VW8Xs+rz9kqO8LOQ5DH6EsuvilT1ApazU0pyl+ytbPtlw==} + dev: false + /is-number@7.0.0: resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==} engines: {node: '>=0.12.0'} dev: false + /is-plain-obj@2.1.0: + resolution: {integrity: sha512-YWnfyRwxL/+SsrWYfOpUtz5b3YD+nyfkHvjbcanzk8zgyO4ASD67uVMRt8k5bM4lLMDnXfriRhOpemw+NfT1eA==} + engines: {node: '>=8'} + dev: false + /linkify-it@3.0.3: resolution: {integrity: sha512-ynTsyrFSdE5oZ/O9GEf00kPngmOfVwazR5GKDq6EYfhlpFug3J2zybX56a2PRRpc9P+FuSoGNAwjlbDs9jJBPQ==} dependencies: uc.micro: 1.0.6 dev: false + /longest-streak@2.0.4: + resolution: {integrity: sha512-vM6rUVCVUJJt33bnmHiZEvr7wPT78ztX7rojL+LW51bHtLh6HTjx84LA5W4+oa6aKEJA7jJu5LR6vQRBpA5DVg==} + dev: false + /markdown-it@12.3.2: resolution: {integrity: sha512-TchMembfxfNVpHkbtriWltGWc+m3xszaRD0CZup7GFFhzIgQqxIfn3eGj1yZpfuflzPvfkt611B2Q/Bsk1YnGg==} hasBin: true @@ -141,6 +324,12 @@ packages: uc.micro: 1.0.6 dev: false + /markdown-table@2.0.0: + resolution: {integrity: sha512-Ezda85ToJUBhM6WGaG6veasyym+Tbs3cMAw/ZhOPqXiYsr0jgocBV3j3nx+4lk47plLlIqjwuTm/ywVI+zjJ/A==} + dependencies: + repeat-string: 1.6.1 + dev: false + /markdownlint-cli2-formatter-default@0.0.3(markdownlint-cli2@0.4.0): resolution: {integrity: sha512-QEAJitT5eqX1SNboOD+SO/LNBpu4P4je8JlR02ug2cLQAqmIhh8IJnSK7AcaHBHhNADqdGydnPpQOpsNcEEqCw==} peerDependencies: @@ -174,6 +363,97 @@ packages: markdown-it: 12.3.2 dev: false + /mdast-util-find-and-replace@1.1.1: + resolution: {integrity: sha512-9cKl33Y21lyckGzpSmEQnIDjEfeeWelN5s1kUW1LwdB0Fkuq2u+4GdqcGEygYxJE8GVqCl0741bYXHgamfWAZA==} + dependencies: + escape-string-regexp: 4.0.0 + unist-util-is: 4.1.0 + unist-util-visit-parents: 3.1.1 + dev: false + + /mdast-util-footnote@0.1.7: + resolution: {integrity: sha512-QxNdO8qSxqbO2e3m09KwDKfWiLgqyCurdWTQ198NpbZ2hxntdc+VKS4fDJCmNWbAroUdYnSthu+XbZ8ovh8C3w==} + dependencies: + mdast-util-to-markdown: 0.6.5 + micromark: 2.11.4 + transitivePeerDependencies: + - supports-color + dev: false + + /mdast-util-from-markdown@0.8.5: + resolution: {integrity: sha512-2hkTXtYYnr+NubD/g6KGBS/0mFmBcifAsI0yIWRiRo0PjVs6SSOSOdtzbp6kSGnShDN6G5aWZpKQ2lWRy27mWQ==} + dependencies: + '@types/mdast': 3.0.15 + mdast-util-to-string: 2.0.0 + micromark: 2.11.4 + parse-entities: 2.0.0 + unist-util-stringify-position: 2.0.3 + transitivePeerDependencies: + - supports-color + dev: false + + /mdast-util-frontmatter@0.2.0: + resolution: {integrity: sha512-FHKL4w4S5fdt1KjJCwB0178WJ0evnyyQr5kXTM3wrOVpytD0hrkvd+AOOjU9Td8onOejCkmZ+HQRT3CZ3coHHQ==} + dependencies: + micromark-extension-frontmatter: 0.2.2 + dev: false + + /mdast-util-gfm-autolink-literal@0.1.3: + resolution: {integrity: sha512-GjmLjWrXg1wqMIO9+ZsRik/s7PLwTaeCHVB7vRxUwLntZc8mzmTsLVr6HW1yLokcnhfURsn5zmSVdi3/xWWu1A==} + dependencies: + ccount: 1.1.0 + mdast-util-find-and-replace: 1.1.1 + micromark: 2.11.4 + transitivePeerDependencies: + - supports-color + dev: false + + /mdast-util-gfm-strikethrough@0.2.3: + resolution: {integrity: sha512-5OQLXpt6qdbttcDG/UxYY7Yjj3e8P7X16LzvpX8pIQPYJ/C2Z1qFGMmcw+1PZMUM3Z8wt8NRfYTvCni93mgsgA==} + dependencies: + mdast-util-to-markdown: 0.6.5 + dev: false + + /mdast-util-gfm-table@0.1.6: + resolution: {integrity: sha512-j4yDxQ66AJSBwGkbpFEp9uG/LS1tZV3P33fN1gkyRB2LoRL+RR3f76m0HPHaby6F4Z5xr9Fv1URmATlRRUIpRQ==} + dependencies: + markdown-table: 2.0.0 + mdast-util-to-markdown: 0.6.5 + dev: false + + /mdast-util-gfm-task-list-item@0.1.6: + resolution: {integrity: sha512-/d51FFIfPsSmCIRNp7E6pozM9z1GYPIkSy1urQ8s/o4TC22BZ7DqfHFWiqBD23bc7J3vV1Fc9O4QIHBlfuit8A==} + dependencies: + mdast-util-to-markdown: 0.6.5 + dev: false + + /mdast-util-gfm@0.1.2: + resolution: {integrity: sha512-NNkhDx/qYcuOWB7xHUGWZYVXvjPFFd6afg6/e2g+SV4r9q5XUcCbV4Wfa3DLYIiD+xAEZc6K4MGaE/m0KDcPwQ==} + dependencies: + mdast-util-gfm-autolink-literal: 0.1.3 + mdast-util-gfm-strikethrough: 0.2.3 + mdast-util-gfm-table: 0.1.6 + mdast-util-gfm-task-list-item: 0.1.6 + mdast-util-to-markdown: 0.6.5 + transitivePeerDependencies: + - supports-color + dev: false + + /mdast-util-to-markdown@0.6.5: + resolution: {integrity: sha512-XeV9sDE7ZlOQvs45C9UKMtfTcctcaj/pGwH8YLbMHoMOXNNCn2LsqVQOqrF1+/NU8lKDAqozme9SCXWyo9oAcQ==} + dependencies: + '@types/unist': 2.0.10 + longest-streak: 2.0.4 + mdast-util-to-string: 2.0.0 + parse-entities: 2.0.0 + repeat-string: 1.6.1 + zwitch: 1.0.5 + dev: false + + /mdast-util-to-string@2.0.0: + resolution: {integrity: sha512-AW4DRS3QbBayY/jJmD8437V1Gombjf8RSOUCMFBuo5iHi58AGEgVCKQ+ezHkZZDpAQS75hcBMpLqjpJTjtUL7w==} + dev: false + /mdurl@1.0.1: resolution: {integrity: sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==} dev: false @@ -183,6 +463,78 @@ packages: engines: {node: '>= 8'} dev: false + /micromark-extension-footnote@0.3.2: + resolution: {integrity: sha512-gr/BeIxbIWQoUm02cIfK7mdMZ/fbroRpLsck4kvFtjbzP4yi+OPVbnukTc/zy0i7spC2xYE/dbX1Sur8BEDJsQ==} + dependencies: + micromark: 2.11.4 + transitivePeerDependencies: + - supports-color + dev: false + + /micromark-extension-frontmatter@0.2.2: + resolution: {integrity: sha512-q6nPLFCMTLtfsctAuS0Xh4vaolxSFUWUWR6PZSrXXiRy+SANGllpcqdXFv2z07l0Xz/6Hl40hK0ffNCJPH2n1A==} + dependencies: + fault: 1.0.4 + dev: false + + /micromark-extension-gfm-autolink-literal@0.5.7: + resolution: {integrity: sha512-ePiDGH0/lhcngCe8FtH4ARFoxKTUelMp4L7Gg2pujYD5CSMb9PbblnyL+AAMud/SNMyusbS2XDSiPIRcQoNFAw==} + dependencies: + micromark: 2.11.4 + transitivePeerDependencies: + - supports-color + dev: false + + /micromark-extension-gfm-strikethrough@0.6.5: + resolution: {integrity: sha512-PpOKlgokpQRwUesRwWEp+fHjGGkZEejj83k9gU5iXCbDG+XBA92BqnRKYJdfqfkrRcZRgGuPuXb7DaK/DmxOhw==} + dependencies: + micromark: 2.11.4 + transitivePeerDependencies: + - supports-color + dev: false + + /micromark-extension-gfm-table@0.4.3: + resolution: {integrity: sha512-hVGvESPq0fk6ALWtomcwmgLvH8ZSVpcPjzi0AjPclB9FsVRgMtGZkUcpE0zgjOCFAznKepF4z3hX8z6e3HODdA==} + dependencies: + micromark: 2.11.4 + transitivePeerDependencies: + - supports-color + dev: false + + /micromark-extension-gfm-tagfilter@0.3.0: + resolution: {integrity: sha512-9GU0xBatryXifL//FJH+tAZ6i240xQuFrSL7mYi8f4oZSbc+NvXjkrHemeYP0+L4ZUT+Ptz3b95zhUZnMtoi/Q==} + dev: false + + /micromark-extension-gfm-task-list-item@0.3.3: + resolution: {integrity: sha512-0zvM5iSLKrc/NQl84pZSjGo66aTGd57C1idmlWmE87lkMcXrTxg1uXa/nXomxJytoje9trP0NDLvw4bZ/Z/XCQ==} + dependencies: + micromark: 2.11.4 + transitivePeerDependencies: + - supports-color + dev: false + + /micromark-extension-gfm@0.3.3: + resolution: {integrity: sha512-oVN4zv5/tAIA+l3GbMi7lWeYpJ14oQyJ3uEim20ktYFAcfX1x3LNlFGGlmrZHt7u9YlKExmyJdDGaTt6cMSR/A==} + dependencies: + micromark: 2.11.4 + micromark-extension-gfm-autolink-literal: 0.5.7 + micromark-extension-gfm-strikethrough: 0.6.5 + micromark-extension-gfm-table: 0.4.3 + micromark-extension-gfm-tagfilter: 0.3.0 + micromark-extension-gfm-task-list-item: 0.3.3 + transitivePeerDependencies: + - supports-color + dev: false + + /micromark@2.11.4: + resolution: {integrity: sha512-+WoovN/ppKolQOFIAajxi7Lu9kInbPxFuTBVEavFcL8eAfVstoc5MocPmqBeAdBOJV00uaVjegzH4+MA0DN/uA==} + dependencies: + debug: 4.3.4 + parse-entities: 2.0.0 + transitivePeerDependencies: + - supports-color + dev: false + /micromatch@4.0.4: resolution: {integrity: sha512-pRmzw/XUcwXGpD9aI9q/0XOwLNygjETJ8y0ao0wdqprrzDa4YnxLcz7fQRZr8voh8V10kGhABbNcHVk5wHgWwg==} engines: {node: '>=8.6'} @@ -191,6 +543,25 @@ packages: picomatch: 2.3.1 dev: false + /minimist@1.2.8: + resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==} + dev: false + + /ms@2.1.2: + resolution: {integrity: sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==} + dev: false + + /parse-entities@2.0.0: + resolution: {integrity: sha512-kkywGpCcRYhqQIchaWqZ875wzpS/bMKhz5HnN3p7wveJTkTtyAB/AlnS0f8DFSqYW1T82t6yEAkEcB+A1I3MbQ==} + dependencies: + character-entities: 1.2.4 + character-entities-legacy: 1.1.4 + character-reference-invalid: 1.1.4 + is-alphanumerical: 1.0.4 + is-decimal: 1.0.4 + is-hexadecimal: 1.0.4 + dev: false + /path-type@4.0.0: resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==} engines: {node: '>=8'} @@ -205,6 +576,44 @@ packages: resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==} dev: false + /remark-footnotes@3.0.0: + resolution: {integrity: sha512-ZssAvH9FjGYlJ/PBVKdSmfyPc3Cz4rTWgZLI4iE/SX8Nt5l3o3oEjv3wwG5VD7xOjktzdwp5coac+kJV9l4jgg==} + dependencies: + mdast-util-footnote: 0.1.7 + micromark-extension-footnote: 0.3.2 + transitivePeerDependencies: + - supports-color + dev: false + + /remark-frontmatter@3.0.0: + resolution: {integrity: sha512-mSuDd3svCHs+2PyO29h7iijIZx4plX0fheacJcAoYAASfgzgVIcXGYSq9GFyYocFLftQs8IOmmkgtOovs6d4oA==} + dependencies: + mdast-util-frontmatter: 0.2.0 + micromark-extension-frontmatter: 0.2.2 + dev: false + + /remark-gfm@1.0.0: + resolution: {integrity: sha512-KfexHJCiqvrdBZVbQ6RopMZGwaXz6wFJEfByIuEwGf0arvITHjiKKZ1dpXujjH9KZdm1//XJQwgfnJ3lmXaDPA==} + dependencies: + mdast-util-gfm: 0.1.2 + micromark-extension-gfm: 0.3.3 + transitivePeerDependencies: + - supports-color + dev: false + + /remark-parse@9.0.0: + resolution: {integrity: sha512-geKatMwSzEXKHuzBNU1z676sGcDcFoChMK38TgdHJNAYfFtsfHDQG7MoJAjs6sgYMqyLduCYWDIWZIxiPeafEw==} + dependencies: + mdast-util-from-markdown: 0.8.5 + transitivePeerDependencies: + - supports-color + dev: false + + /repeat-string@1.6.1: + resolution: {integrity: sha512-PV0dzCYDNfRi1jCDbJzpW7jNNDRuCOG/jI5ctQcGKt/clZD+YcPS3yIlWuTJMmESC8aevCFmWJy5wjAFgNqN6w==} + engines: {node: '>=0.10'} + dev: false + /reusify@1.0.4: resolution: {integrity: sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==} engines: {iojs: '>=1.0.0', node: '>=0.10.0'} @@ -233,11 +642,77 @@ packages: is-number: 7.0.0 dev: false + /traverse@0.6.8: + resolution: {integrity: sha512-aXJDbk6SnumuaZSANd21XAo15ucCDE38H4fkqiGsc3MhCK+wOlZvLP9cB/TvpHT0mOyWgC4Z8EwRlzqYSUzdsA==} + engines: {node: '>= 0.4'} + dev: false + + /trough@1.0.5: + resolution: {integrity: sha512-rvuRbTarPXmMb79SmzEp8aqXNKcK+y0XaB298IXueQ8I2PsrATcPBCSPyK/dDNa2iWOhKlfNnOjdAOTBU/nkFA==} + dev: false + /uc.micro@1.0.6: resolution: {integrity: sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==} dev: false + /underscore@1.13.6: + resolution: {integrity: sha512-+A5Sja4HP1M08MaXya7p5LvjuM7K6q/2EaC0+iovj/wOcMsTzMvDFbasi/oSapiwOlt252IqsKqPjCl7huKS0A==} + dev: false + + /unified@9.2.2: + resolution: {integrity: sha512-Sg7j110mtefBD+qunSLO1lqOEKdrwBFBrR6Qd8f4uwkhWNlbkaqwHse6e7QvD3AP/MNoJdEDLaf8OxYyoWgorQ==} + dependencies: + '@types/unist': 2.0.10 + bail: 1.0.5 + extend: 3.0.2 + is-buffer: 2.0.5 + is-plain-obj: 2.1.0 + trough: 1.0.5 + vfile: 4.2.1 + dev: false + + /unist-util-is@4.1.0: + resolution: {integrity: sha512-ZOQSsnce92GrxSqlnEEseX0gi7GH9zTJZ0p9dtu87WRb/37mMPO2Ilx1s/t9vBHrFhbgweUwb+t7cIn5dxPhZg==} + dev: false + + /unist-util-stringify-position@2.0.3: + resolution: {integrity: sha512-3faScn5I+hy9VleOq/qNbAd6pAx7iH5jYBMS9I1HgQVijz/4mv5Bvw5iw1sC/90CODiKo81G/ps8AJrISn687g==} + dependencies: + '@types/unist': 2.0.10 + dev: false + + /unist-util-visit-parents@3.1.1: + resolution: {integrity: sha512-1KROIZWo6bcMrZEwiH2UrXDyalAa0uqzWCxCJj6lPOvTve2WkfgCytoDTPaMnodXh1WrXOq0haVYHj99ynJlsg==} + dependencies: + '@types/unist': 2.0.10 + unist-util-is: 4.1.0 + dev: false + + /update-section@0.3.3: + resolution: {integrity: sha512-BpRZMZpgXLuTiKeiu7kK0nIPwGdyrqrs6EDSaXtjD/aQ2T+qVo9a5hRC3HN3iJjCMxNT/VxoLGQ7E/OzE5ucnw==} + dev: false + + /vfile-message@2.0.4: + resolution: {integrity: sha512-DjssxRGkMvifUOJre00juHoP9DPWuzjxKuMDrhNbk2TdaYYBNMStsNhEOt3idrtI12VQYM/1+iM0KOzXi4pxwQ==} + dependencies: + '@types/unist': 2.0.10 + unist-util-stringify-position: 2.0.3 + dev: false + + /vfile@4.2.1: + resolution: {integrity: sha512-O6AE4OskCG5S1emQ/4gl8zK586RqA3srz3nfK/Viy0UPToBc5Trp9BVFb1u0CjsKrAWwnpr4ifM/KBXPWwJbCA==} + dependencies: + '@types/unist': 2.0.10 + is-buffer: 2.0.5 + unist-util-stringify-position: 2.0.3 + vfile-message: 2.0.4 + dev: false + /yaml@1.10.2: resolution: {integrity: sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==} engines: {node: '>= 6'} dev: false + + /zwitch@1.0.5: + resolution: {integrity: sha512-V50KMwwzqJV0NpZIZFwfOD5/lyny3WlSzRiXgA0G7VUnRlqttta1L6UQIHzd6EuBY/cHGfwTIck7w1yH6Q5zUw==} + dev: false diff --git a/specs/SUMMARY.md b/specs/SUMMARY.md index f8b2d7d70..7b6f650b0 100644 --- a/specs/SUMMARY.md +++ b/specs/SUMMARY.md @@ -1,3 +1,4 @@ + # Summary - [Root](./root.md) diff --git a/specs/experimental/fault-proof/cannon-fault-proof-vm.md b/specs/experimental/fault-proof/cannon-fault-proof-vm.md index 69a69fbb0..8348353e9 100644 --- a/specs/experimental/fault-proof/cannon-fault-proof-vm.md +++ b/specs/experimental/fault-proof/cannon-fault-proof-vm.md @@ -1,8 +1,24 @@ # Cannon Fault Proof Virtual Machine + + **Table of Contents** - +- [Overview](#overview) +- [State](#state) + - [State Hash](#state-hash) +- [Memory](#memory) + - [Heap](#heap) +- [Delay Slots](#delay-slots) +- [Syscalls](#syscalls) +- [I/O](#io) + - [Standard Streams](#standard-streams) + - [Hint Communication](#hint-communication) + - [Pre-image Communication](#pre-image-communication) + - [Pre-image I/O Alignment](#pre-image-io-alignment) +- [Exceptions](#exceptions) + + ## Overview diff --git a/specs/experimental/fault-proof/dispute-game-interface.md b/specs/experimental/fault-proof/dispute-game-interface.md index 7ba4e4d44..74b269eee 100644 --- a/specs/experimental/fault-proof/dispute-game-interface.md +++ b/specs/experimental/fault-proof/dispute-game-interface.md @@ -1,8 +1,15 @@ # Dispute Game Interface + + **Table of Contents** - +- [Overview](#overview) +- [Types](#types) +- [`DisputeGameFactory` Interface](#disputegamefactory-interface) +- [`DisputeGame` Interface](#disputegame-interface) + + ## Overview diff --git a/specs/experimental/fault-proof/fault-dispute-game.md b/specs/experimental/fault-proof/fault-dispute-game.md index d1756b67b..e8c0f52a4 100644 --- a/specs/experimental/fault-proof/fault-dispute-game.md +++ b/specs/experimental/fault-proof/fault-dispute-game.md @@ -1,8 +1,33 @@ # Fault Dispute Game + + **Table of Contents** - +- [Overview](#overview) +- [Definitions](#definitions) + - [Virtual Machine (VM)](#virtual-machine-vm) + - [PreimageOracle](#preimageoracle) + - [Execution Trace](#execution-trace) + - [Claims](#claims) + - [DAG](#dag) + - [Subgame](#subgame) + - [Game Tree](#game-tree) + - [Position](#position) + - [GAME_DURATION](#game_duration) +- [Game Mechanics](#game-mechanics) + - [Actors](#actors) + - [Moves](#moves) + - [Attack](#attack) + - [Defend](#defend) + - [Step](#step) + - [Step Types](#step-types) + - [PreimageOracle Interaction](#preimageoracle-interaction) + - [Team Dynamics](#team-dynamics) + - [Game Clock](#game-clock) + - [Resolution](#resolution) + + diff --git a/specs/experimental/fault-proof/honest-challenger-fdg.md b/specs/experimental/fault-proof/honest-challenger-fdg.md index 351af2130..b93d1d66c 100644 --- a/specs/experimental/fault-proof/honest-challenger-fdg.md +++ b/specs/experimental/fault-proof/honest-challenger-fdg.md @@ -1,8 +1,19 @@ # Honest Challenger (Fault Dispute Game) + + **Table of Contents** - +- [Overview](#overview) +- [FDG Responses](#fdg-responses) + - [Root Claims](#root-claims) + - [Counter Claims](#counter-claims) + - [Steps](#steps) +- [Resolution](#resolution) + + + +## Overview The honest challenger is an agent interacting in the [Fault Dispute Game](fault-dispute-game.md) (FDG) that supports honest claims and disputes false claims. @@ -11,8 +22,6 @@ The honest challenger is also _rational_ as any deviation from its behavior will negative outcomes. This document specifies the expected behavior of an honest challenger. -## Overview - The Honest Challenger has two primary duties: 1. Support valid root claims in Fault Dispute Games. diff --git a/specs/experimental/fault-proof/index.md b/specs/experimental/fault-proof/index.md index e3c709c85..bad32ba94 100644 --- a/specs/experimental/fault-proof/index.md +++ b/specs/experimental/fault-proof/index.md @@ -1,8 +1,38 @@ # Fault Proof + + **Table of Contents** - +- [Overview](#overview) +- [Pre-image Oracle](#pre-image-oracle) + - [Pre-image key types](#pre-image-key-types) + - [Type `0`: Zero key](#type-0-zero-key) + - [Type `1`: Local key](#type-1-local-key) + - [Type `2`: Global keccak256 key](#type-2-global-keccak256-key) + - [Type `3`: Global generic key](#type-3-global-generic-key) + - [Type `4-128`: reserved range](#type-4-128-reserved-range) + - [Type `129-255`: application usage](#type-129-255-application-usage) + - [Bootstrapping](#bootstrapping) + - [Hinting](#hinting) + - [Pre-image communication](#pre-image-communication) +- [Fault Proof Program](#fault-proof-program) + - [Prologue](#prologue) + - [Main content](#main-content) + - [Epilogue](#epilogue) + - [Pre-image hinting routes](#pre-image-hinting-routes) + - [`l1-block-header `](#l1-block-header-blockhash) + - [`l1-transactions `](#l1-transactions-blockhash) + - [`l1-receipts `](#l1-receipts-blockhash) + - [`l2-block-header `](#l2-block-header-blockhash) + - [`l2-transactions `](#l2-transactions-blockhash) + - [`l2-code `](#l2-code-codehash) + - [`l2-state-node `](#l2-state-node-nodehash) + - [`l2-output `](#l2-output-outputroot) +- [Fault Proof VM](#fault-proof-vm) +- [Fault Proof Interactive Dispute Game](#fault-proof-interactive-dispute-game) + + ## Overview diff --git a/specs/glossary.md b/specs/glossary.md index b827b3d59..2d834efff 100644 --- a/specs/glossary.md +++ b/specs/glossary.md @@ -1,8 +1,78 @@ # Glossary + + **Table of Contents** - +- [General Terms](#general-terms) + - [Layer 1 (L1)](#layer-1-l1) + - [Layer 2 (L2)](#layer-2-l2) + - [Block](#block) + - [EOA](#eoa) + - [Merkle Patricia Trie](#merkle-patricia-trie) + - [Chain Re-Organization](#chain-re-organization) + - [Predeployed Contract ("Predeploy")](#predeployed-contract-predeploy) + - [Preinstalled Contract ("Preinstall")](#preinstalled-contract-preinstall) + - [Receipt](#receipt) + - [Transaction Type](#transaction-type) + - [Fork Choice Rule](#fork-choice-rule) + - [Priority Gas Auction](#priority-gas-auction) +- [Sequencing](#sequencing) + - [Sequencer](#sequencer) + - [Sequencing Window](#sequencing-window) + - [Sequencing Epoch](#sequencing-epoch) + - [L1 Origin](#l1-origin) +- [Deposits](#deposits) + - [Deposited Transaction](#deposited-transaction) + - [L1 Attributes Deposited Transaction](#l1-attributes-deposited-transaction) + - [User-Deposited Transaction](#user-deposited-transaction) + - [Depositing Call](#depositing-call) + - [Depositing Transaction](#depositing-transaction) + - [Depositor](#depositor) + - [Deposited Transaction Type](#deposited-transaction-type) + - [Deposit Contract](#deposit-contract) +- [Withdrawals](#withdrawals) + - [Relayer](#relayer) + - [Finalization Period](#finalization-period) +- [Batch Submission](#batch-submission) + - [Data Availability](#data-availability) + - [Data Availability Provider](#data-availability-provider) + - [Sequencer Batch](#sequencer-batch) + - [Channel](#channel) + - [Channel Frame](#channel-frame) + - [Batcher](#batcher) + - [Batcher Transaction](#batcher-transaction) + - [Channel Timeout](#channel-timeout) +- [L2 Output Root Proposals](#l2-output-root-proposals) + - [Proposer](#proposer) +- [L2 Chain Derivation](#l2-chain-derivation) + - [L2 Derivation Inputs](#l2-derivation-inputs) + - [System Configuration](#system-configuration) + - [Payload Attributes](#payload-attributes) + - [L2 Genesis Block](#l2-genesis-block) + - [L2 Chain Inception](#l2-chain-inception) + - [Safe L2 Block](#safe-l2-block) + - [Safe L2 Head](#safe-l2-head) + - [Unsafe L2 Block](#unsafe-l2-block) + - [Unsafe L2 Head](#unsafe-l2-head) + - [Unsafe Block Consolidation](#unsafe-block-consolidation) + - [Finalized L2 Head](#finalized-l2-head) +- [Other L2 Chain Concepts](#other-l2-chain-concepts) + - [Address Aliasing](#address-aliasing) + - [Rollup Node](#rollup-node) + - [Rollup Driver](#rollup-driver) + - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract) + - [L2 Output Root](#l2-output-root) + - [L2 Output Oracle Contract](#l2-output-oracle-contract) + - [Validator](#validator) + - [Fault Proof](#fault-proof) + - [Time Slot](#time-slot) + - [Block Time](#block-time) + - [Unsafe Sync](#unsafe-sync) +- [Execution Engine Concepts](#execution-engine-concepts) + - [Execution Engine](#execution-engine) + + --- diff --git a/specs/introduction.md b/specs/introduction.md index 4909c17ba..4cf930279 100644 --- a/specs/introduction.md +++ b/specs/introduction.md @@ -1,13 +1,30 @@ # Introduction -**Table of Contents** - - - Optimism is an _EVM equivalent_, _optimistic rollup_ protocol designed to _scale Ethereum_ while remaining maximally compatible with existing Ethereum infrastructure. This document provides an overview of the protocol to provide context for the rest of the specification. + + +**Table of Contents** + +- [Foundations](#foundations) + - [What is Ethereum scalability?](#what-is-ethereum-scalability) + - [What is an Optimistic Rollup?](#what-is-an-optimistic-rollup) + - [What is EVM Equivalence?](#what-is-evm-equivalence) + - [🎶 All together now 🎶](#-all-together-now-) +- [Protocol Guarantees](#protocol-guarantees) +- [Network Participants](#network-participants) + - [Users](#users) + - [Sequencers](#sequencers) + - [Verifiers](#verifiers) +- [Key Interaction Diagrams](#key-interaction-diagrams) + - [Depositing and Sending Transactions](#depositing-and-sending-transactions) + - [Withdrawing](#withdrawing) +- [Next Steps](#next-steps) + + + ## Foundations ### What is Ethereum scalability? diff --git a/specs/meta/index.md b/specs/meta/index.md index fcfbdd3dc..7ed98dd19 100644 --- a/specs/meta/index.md +++ b/specs/meta/index.md @@ -1,7 +1,9 @@ # Meta Processes + + + This directory describes processes that we use to lint/test the specification. -- [Linting](linting.md): how to lint source files. - [Markdown Style Guide](markdown-style.md): how to format and structure Markdown files. - [Versioning](versioning.md) diff --git a/specs/meta/linting.md b/specs/meta/linting.md deleted file mode 100644 index 642c1aac4..000000000 --- a/specs/meta/linting.md +++ /dev/null @@ -1,59 +0,0 @@ -# Linting - -**Table of Contents** - - - -## Markdown - -See - -- [markdownlint rule reference](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) -- [example .markdownlint.json file](https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.jsonc) - -Justification for linting rules in -[.markdownlint.json](https://github.com/ethereum-optimism/specs/blob/main/.markdownlint.json): - -- _line_length_ (`!strict && stern`): don't trip up on url lines -- _no-blanks-blockquote_: enable multiple consecutive blockquotes separated by white lines -- _single-title_: enable reusing `

` for content -- _no-emphasis-as-heading_: enable emphasized paragraphs - -```shell -pnpm i # Install dependencies -pnpm lint:specs:check # Run linter -pnpm lint:specs:fix # Fix lint issues - -# Check links -docker run --init -it -v `pwd`:/input lycheeverse/lychee --verbose --no-progress --exclude-loopback --exclude twitter.com --exclude-mail /input/README.md "/input/specs/**/*.md" -``` - -To check links, you'll need to install [lychee]. The [version ran in CI][lychee-ci] is 0.8.1, but -you should install lychee 0.8.2 locally with `cargo install --version 0.8.2 lychee` (there are some -reported build problems with 0.8.1). - -You can install cargo (the Rust package manager) via [rustup]. - -[lychee]: https://github.com/lycheeverse/lychee -[lychee-ci]: https://github.com/lycheeverse/lychee-action/blob/f76b8412c668f78311212d16d33c4784a7d8762c/Dockerfile -[rustup]: https://www.rust-lang.org/tools/install - -# Go - -See - -- [golangci-lint docs](https://golangci-lint.run/usage/install/#local-installation) -- [golangci-lint github](https://github.com/golangci/golangci-lint) -- [github action github](https://github.com/golangci/golangci-lint-action) - -Justification for linting rules: - -- _asciicheck_: no symbol names with invisible unicode and such -- _goimports_: group local and external import - -```shell -# Install linter globally (should not affect go.mod) -go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.48.0 -# run linter, add --fix option to fix problems (where supported) -golangci-lint run -E goimports,sqlclosecheck,bodyclose,asciicheck,misspell,errorlint --timeout 2m -e "errors.As" -e "errors.Is" ./... -``` diff --git a/specs/meta/markdown-style.md b/specs/meta/markdown-style.md index c47fcaf49..81ee837c4 100644 --- a/specs/meta/markdown-style.md +++ b/specs/meta/markdown-style.md @@ -1,8 +1,15 @@ # Markdown Style Guide + + **Table of Contents** - +- [Linting](#linting) +- [Links](#links) + - [Glossary](#glossary) +- [Internal (In-File) Links](#internal-in-file-links) + + ## Linting diff --git a/specs/meta/versioning.md b/specs/meta/versioning.md index 44344bbf3..381a3a5a3 100644 --- a/specs/meta/versioning.md +++ b/specs/meta/versioning.md @@ -1,8 +1,14 @@ # Versioning + + **Table of Contents** - +- [Go modules](#go-modules) + - [versioning process](#versioning-process) +- [Typescript](#typescript) + + ## Go modules diff --git a/specs/protocol/batcher.md b/specs/protocol/batcher.md index 475561c51..761926c0a 100644 --- a/specs/protocol/batcher.md +++ b/specs/protocol/batcher.md @@ -1,10 +1,20 @@ # Batch Submitter -The batch submitter, also referred to as the batcher, is the entity submitting the L2 sequencer data to L1, -to make it available for verifiers. + + +**Table of Contents** + +- [Overview](#overview) + + [derivation spec]: derivation.md +## Overview + +The batch submitter, also referred to as the batcher, is the entity submitting the L2 sequencer data to L1, +to make it available for verifiers. + The format of the data transactions is defined in the [derivation spec]: the data is constructed from L2 blocks in the reverse order as it is derived from data into L2 blocks. diff --git a/specs/protocol/bridges.md b/specs/protocol/bridges.md index e55ded2bd..319b7b0a5 100644 --- a/specs/protocol/bridges.md +++ b/specs/protocol/bridges.md @@ -1,8 +1,16 @@ # Standard Bridges + + **Table of Contents** - +- [Overview](#overview) +- [Token Depositing](#token-depositing) +- [Upgradability](#upgradability) + + + +## Overview The standard bridges are responsible for allowing cross domain ETH and ERC20 token transfers. They are built on top of the cross domain diff --git a/specs/protocol/deposits.md b/specs/protocol/deposits.md index 9044f7a89..8bc206288 100644 --- a/specs/protocol/deposits.md +++ b/specs/protocol/deposits.md @@ -1,5 +1,33 @@ # Deposits + + +**Table of Contents** + +- [Overview](#overview) +- [The Deposited Transaction Type](#the-deposited-transaction-type) + - [Source hash computation](#source-hash-computation) + - [Kinds of Deposited Transactions](#kinds-of-deposited-transactions) + - [Validation and Authorization of Deposited Transactions](#validation-and-authorization-of-deposited-transactions) + - [Execution](#execution) + - [Nonce Handling](#nonce-handling) +- [Deposit Receipt](#deposit-receipt) +- [L1 Attributes Deposited Transaction](#l1-attributes-deposited-transaction) + - [L1 Attributes Deposited Transaction Calldata](#l1-attributes-deposited-transaction-calldata) + - [L1 Attributes - Bedrock, Canyon, Delta](#l1-attributes---bedrock-canyon-delta) + - [L1 Attributes - Ecotone](#l1-attributes---ecotone) +- [Special Accounts on L2](#special-accounts-on-l2) + - [L1 Attributes Depositor Account](#l1-attributes-depositor-account) + - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract) + - [L1 Attributes Predeployed Contract: Reference Implementation](#l1-attributes-predeployed-contract-reference-implementation) + - [Ecotone L1Block upgrade](#ecotone-l1block-upgrade) +- [User-Deposited Transactions](#user-deposited-transactions) + - [Deposit Contract](#deposit-contract) + - [Address Aliasing](#address-aliasing) + - [Deposit Contract Implementation: Optimism Portal](#deposit-contract-implementation-optimism-portal) + + + [g-transaction-type]: ../glossary.md#transaction-type @@ -11,6 +39,8 @@ [g-eoa]: ../glossary.md#eoa [g-exec-engine]: ../glossary.md#execution-engine +## Overview + [Deposited transactions][g-deposited], also known as [deposits][g-deposits] are transactions which are initiated on L1, and executed on L2. This document outlines a new [transaction type][g-transaction-type] for deposits. It also describes how deposits are initiated on L1, along @@ -19,10 +49,6 @@ with the authorization and validation conditions on L2. **Vocabulary note**: _deposited transaction_ refers specifically to an L2 transaction, while _deposit_ can refer to the transaction at various stages (for instance when it is deposited on L1). -**Table of Contents** - - - ## The Deposited Transaction Type [deposited-tx-type]: #the-deposited-transaction-type diff --git a/specs/protocol/derivation.md b/specs/protocol/derivation.md index c446ecf54..f26724961 100644 --- a/specs/protocol/derivation.md +++ b/specs/protocol/derivation.md @@ -1,5 +1,59 @@ # L2 Chain Derivation Specification + + +**Table of Contents** + +- [Overview](#overview) + - [Eager Block Derivation](#eager-block-derivation) +- [Batch Submission](#batch-submission) + - [Sequencing & Batch Submission Overview](#sequencing--batch-submission-overview) + - [Batch Submission Wire Format](#batch-submission-wire-format) + - [Batcher Transaction Format](#batcher-transaction-format) + - [Frame Format](#frame-format) + - [Channel Format](#channel-format) + - [Batch Format](#batch-format) +- [Architecture](#architecture) + - [L2 Chain Derivation Pipeline](#l2-chain-derivation-pipeline) + - [L1 Traversal](#l1-traversal) + - [L1 Retrieval](#l1-retrieval) + - [Ecotone: Blob Retrieval](#ecotone-blob-retrieval) + - [Blob Encoding](#blob-encoding) + - [Frame Queue](#frame-queue) + - [Channel Bank](#channel-bank) + - [Pruning](#pruning) + - [Timeouts](#timeouts) + - [Reading](#reading) + - [Loading frames](#loading-frames) + - [Channel Reader (Batch Decoding)](#channel-reader-batch-decoding) + - [Batch Queue](#batch-queue) + - [Payload Attributes Derivation](#payload-attributes-derivation) + - [Engine Queue](#engine-queue) + - [Engine API usage](#engine-api-usage) + - [Bedrock, Canyon, Delta: API Usage](#bedrock-canyon-delta-api-usage) + - [Ecotone: API Usage](#ecotone-api-usage) + - [Forkchoice synchronization](#forkchoice-synchronization) + - [L1-consolidation: payload attributes matching](#l1-consolidation-payload-attributes-matching) + - [L1-sync: payload attributes processing](#l1-sync-payload-attributes-processing) + - [Processing unsafe payload attributes](#processing-unsafe-payload-attributes) + - [Resetting the Pipeline](#resetting-the-pipeline) + - [Finding the sync starting point](#finding-the-sync-starting-point) + - [Resetting derivation stages](#resetting-derivation-stages) + - [About reorgs Post-Merge](#about-reorgs-post-merge) +- [Deriving Payload Attributes](#deriving-payload-attributes) + - [Deriving the Transaction List](#deriving-the-transaction-list) + - [Network upgrade automation transactions](#network-upgrade-automation-transactions) + - [Ecotone](#ecotone) + - [L1Block Deployment](#l1block-deployment) + - [GasPriceOracle Deployment](#gaspriceoracle-deployment) + - [L1Block Proxy Update](#l1block-proxy-update) + - [GasPriceOracle Proxy Update](#gaspriceoracle-proxy-update) + - [GasPriceOracle Enable Ecotone](#gaspriceoracle-enable-ecotone) + - [Beacon block roots contract deployment (EIP-4788)](#beacon-block-roots-contract-deployment-eip-4788) + - [Building Individual Payload Attributes](#building-individual-payload-attributes) + + + [g-derivation]: ../glossary.md#L2-chain-derivation @@ -49,10 +103,6 @@ [g-finalized-l2-head]: ../glossary.md#finalized-l2-head [g-system-config]: ../glossary.md#system-configuration -**Table of Contents** - - - # Overview > **Note** the following assumes a single sequencer and batcher. In the future, the design will be adapted to diff --git a/specs/protocol/exec-engine.md b/specs/protocol/exec-engine.md index 2610529f8..29d05c831 100644 --- a/specs/protocol/exec-engine.md +++ b/specs/protocol/exec-engine.md @@ -1,8 +1,38 @@ # L2 Execution Engine + + **Table of Contents** - +- [1559 Parameters](#1559-parameters) +- [Deposited transaction processing](#deposited-transaction-processing) + - [Deposited transaction boundaries](#deposited-transaction-boundaries) +- [Fees](#fees) + - [Fee Vaults](#fee-vaults) + - [Priority fees (Sequencer Fee Vault)](#priority-fees-sequencer-fee-vault) + - [Base fees (Base Fee Vault)](#base-fees-base-fee-vault) + - [L1-Cost fees (L1 Fee Vault)](#l1-cost-fees-l1-fee-vault) + - [Pre-Ecotone](#pre-ecotone) + - [Ecotone L1-Cost fee changes (EIP-4844 DA)](#ecotone-l1-cost-fee-changes-eip-4844-da) +- [Engine API](#engine-api) + - [`engine_forkchoiceUpdatedV2`](#engine_forkchoiceupdatedv2) + - [Extended PayloadAttributesV2](#extended-payloadattributesv2) + - [`engine_forkchoiceUpdatedV3`](#engine_forkchoiceupdatedv3) + - [Extended PayloadAttributesV3](#extended-payloadattributesv3) + - [`engine_newPayloadV2`](#engine_newpayloadv2) + - [`engine_newPayloadV3`](#engine_newpayloadv3) + - [`engine_getPayloadV2`](#engine_getpayloadv2) + - [`engine_getPayloadV3`](#engine_getpayloadv3) + - [Extended Response](#extended-response) + - [`engine_signalSuperchainV1`](#engine_signalsuperchainv1) +- [Networking](#networking) +- [Sync](#sync) + - [Happy-path sync](#happy-path-sync) + - [Worst-case sync](#worst-case-sync) +- [Ecotone: disable Blob-transactions](#ecotone-disable-blob-transactions) +- [Ecotone: Beacon Block Root](#ecotone-beacon-block-root) + + This document outlines the modifications, configuration and usage of a L1 execution engine for L2. diff --git a/specs/protocol/guaranteed-gas-market.md b/specs/protocol/guaranteed-gas-market.md index 99e67d4cb..e5bd9a746 100644 --- a/specs/protocol/guaranteed-gas-market.md +++ b/specs/protocol/guaranteed-gas-market.md @@ -1,8 +1,19 @@ # Guaranteed Gas Fee Market + + **Table of Contents** - +- [Overview](#overview) +- [Gas Stipend](#gas-stipend) +- [Default Values](#default-values) +- [Limiting Guaranteed Gas](#limiting-guaranteed-gas) +- [Rationale for burning L1 Gas](#rationale-for-burning-l1-gas) +- [On Preventing Griefing Attacks](#on-preventing-griefing-attacks) + + + +## Overview [Deposited transactions](../glossary.md#deposited-transaction) are transactions on L2 that are initiated on L1. The gas that they use on L2 is bought on L1 via a gas burn (or a direct payment diff --git a/specs/protocol/messengers.md b/specs/protocol/messengers.md index bea90baa7..142a4e2dd 100644 --- a/specs/protocol/messengers.md +++ b/specs/protocol/messengers.md @@ -1,8 +1,20 @@ # Cross Domain Messengers + + **Table of Contents** - +- [Overview](#overview) +- [Message Passing](#message-passing) +- [Upgradability](#upgradability) +- [Message Versioning](#message-versioning) + - [Message Version 0](#message-version-0) + - [Message Version 1](#message-version-1) +- [Backwards Compatibility Notes](#backwards-compatibility-notes) + + + +## Overview The cross domain messengers are responsible for providing a higher level API for developers who are interested in sending cross domain messages. They allow for diff --git a/specs/protocol/overview.md b/specs/protocol/overview.md index 85b2d684a..1ccd6f4b9 100644 --- a/specs/protocol/overview.md +++ b/specs/protocol/overview.md @@ -1,8 +1,23 @@ # Optimism Overview + + **Table of Contents** - +- [Architecture Design Goals](#architecture-design-goals) +- [Components](#components) + - [L1 Components](#l1-components) + - [L2 Components](#l2-components) + - [Transaction/Block Propagation](#transactionblock-propagation) +- [Key Interactions In Depth](#key-interactions-in-depth) + - [Deposits](#deposits) + - [Block Derivation](#block-derivation) + - [Overview](#overview) + - [Epochs and the Sequencing Window](#epochs-and-the-sequencing-window) + - [Block Derivation Loop](#block-derivation-loop) + - [Engine API](#engine-api) + + This document is a high-level technical overview of the Optimism protocol. It aims to explain how the protocol works in an informal manner, and direct readers to other parts of the specification so that they may learn more. diff --git a/specs/protocol/predeploys.md b/specs/protocol/predeploys.md index bc19da197..f12d50b1c 100644 --- a/specs/protocol/predeploys.md +++ b/specs/protocol/predeploys.md @@ -1,8 +1,31 @@ # Predeploys + + **Table of Contents** - +- [Overview](#overview) +- [LegacyMessagePasser](#legacymessagepasser) +- [L2ToL1MessagePasser](#l2tol1messagepasser) +- [DeployerWhitelist](#deployerwhitelist) +- [LegacyERC20ETH](#legacyerc20eth) +- [WETH9](#weth9) +- [L2CrossDomainMessenger](#l2crossdomainmessenger) +- [L2StandardBridge](#l2standardbridge) +- [L1BlockNumber](#l1blocknumber) +- [GasPriceOracle](#gaspriceoracle) +- [L1Block](#l1block) +- [ProxyAdmin](#proxyadmin) +- [SequencerFeeVault](#sequencerfeevault) +- [OptimismMintableERC20Factory](#optimismmintableerc20factory) +- [OptimismMintableERC721Factory](#optimismmintableerc721factory) +- [BaseFeeVault](#basefeevault) +- [L1FeeVault](#l1feevault) +- [SchemaRegistry](#schemaregistry) +- [EAS](#eas) +- [create2Deployer](#create2deployer) + + ## Overview diff --git a/specs/protocol/preinstalls.md b/specs/protocol/preinstalls.md index a8d8208c4..1136b9662 100644 --- a/specs/protocol/preinstalls.md +++ b/specs/protocol/preinstalls.md @@ -1,8 +1,22 @@ # Preinstalls + + **Table of Contents** - +- [Overview](#overview) +- [Safe](#safe) +- [SafeL2](#safel2) +- [MultiSend](#multisend) +- [MultiSendCallOnly](#multisendcallonly) +- [SafeSingletonFactory](#safesingletonfactory) +- [Multicall3](#multicall3) +- [Arachnid's Deterministic Deployment Proxy](#arachnids-deterministic-deployment-proxy) +- [Permit2](#permit2) +- [ERC-4337 EntryPoint](#erc-4337-entrypoint) +- [ERC-4337 SenderCreator](#erc-4337-sendercreator) + + ## Overview diff --git a/specs/protocol/proposals.md b/specs/protocol/proposals.md index da04c77dc..0d05d3ab8 100644 --- a/specs/protocol/proposals.md +++ b/specs/protocol/proposals.md @@ -1,13 +1,26 @@ # L2 Output Root Proposals Specification + + +**Table of Contents** + +- [Overview](#overview) +- [Proposing L2 Output Commitments](#proposing-l2-output-commitments) + - [L2OutputOracle v1.0.0](#l2outputoracle-v100) +- [L2 Output Commitment Construction](#l2-output-commitment-construction) +- [L2 Output Oracle Smart Contract](#l2-output-oracle-smart-contract) + - [Configuration](#configuration) +- [Security Considerations](#security-considerations) + - [L1 Reorgs](#l1-reorgs) + + + [g-rollup-node]: ../glossary.md#rollup-node [g-mpt]: ../glossary.md#merkle-patricia-trie -**Table of Contents** - - +## Overview After processing one or more blocks the outputs will need to be synchronized with the settlement layer (L1) for trustless execution of L2-to-L1 messaging, such as withdrawals. diff --git a/specs/protocol/rollup-node-p2p.md b/specs/protocol/rollup-node-p2p.md index ba9b2ce65..521db11dd 100644 --- a/specs/protocol/rollup-node-p2p.md +++ b/specs/protocol/rollup-node-p2p.md @@ -1,5 +1,47 @@ # Rollup-node P2P interface + + +**Table of Contents** + +- [Overview](#overview) +- [P2P configuration](#p2p-configuration) + - [Identification](#identification) + - [Discv5](#discv5) + - [Structure](#structure) + - [LibP2P](#libp2p) + - [Transport](#transport) + - [Dialing](#dialing) + - [NAT](#nat) + - [Peer management](#peer-management) + - [Transport security](#transport-security) + - [Protocol negotiation](#protocol-negotiation) + - [Identify](#identify) + - [Ping](#ping) + - [Multiplexing](#multiplexing) + - [GossipSub](#gossipsub) + - [Content-based message identification](#content-based-message-identification) + - [Message compression and limits](#message-compression-and-limits) + - [Message ID computation](#message-id-computation) + - [Heartbeat and parameters](#heartbeat-and-parameters) + - [Topic configuration](#topic-configuration) + - [Topic validation](#topic-validation) +- [Gossip Topics](#gossip-topics) + - [`blocksv1`](#blocksv1) + - [`blocksv2`](#blocksv2) + - [`blocksv3`](#blocksv3) + - [Block encoding](#block-encoding) + - [Block signatures](#block-signatures) + - [Block validation](#block-validation) + - [Block processing](#block-processing) + - [Block topic scoring parameters](#block-topic-scoring-parameters) +- [Req-Resp](#req-resp) + - [`payload_by_number`](#payload_by_number) + + + +## Overview + The [rollup node](rollup-node.md) has an optional peer-to-peer (P2P) network service to improve the latency between the view of sequencers and the rest of the network by bypassing the L1 in the happy case, without relying on a single centralized endpoint. @@ -25,10 +67,6 @@ This document only specifies the composition and configuration of these network These components have their own standards, implementations in Go/Rust/Java/Nim/JS/more, and are adopted by several other blockchains, most notably the [L1 consensus layer (Eth2)][eth2-p2p]. -**Table of Contents** - - - ## P2P configuration ### Identification diff --git a/specs/protocol/rollup-node.md b/specs/protocol/rollup-node.md index e5ff3dee4..f1d5bcbf1 100644 --- a/specs/protocol/rollup-node.md +++ b/specs/protocol/rollup-node.md @@ -1,5 +1,23 @@ # Rollup Node Specification + + +**Table of Contents** + +- [Overview](#overview) +- [Driver](#driver) + - [Derivation](#derivation) +- [L2 Output RPC method](#l2-output-rpc-method) + - [Structures](#structures) + - [BlockID](#blockid) + - [L1BlockRef](#l1blockref) + - [L2BlockRef](#l2blockref) + - [SyncStatus](#syncstatus) + - [Output Method API](#output-method-api) +- [Protocol Version tracking](#protocol-version-tracking) + + + [g-rollup-node]: ../glossary.md#rollup-node @@ -11,16 +29,14 @@ [g-rollup-driver]: ../glossary.md#rollup-driver [g-receipts]: ../glossary.md#receipt +## Overview + The [rollup node][g-rollup-node] is the component responsible for [deriving the L2 chain][g-derivation] from L1 blocks (and their associated [receipts][g-receipts]). The part of the rollup node that derives the L2 chain is called the [rollup driver][g-rollup-driver]. This document is currently only concerned with the specification of the rollup driver. -**Table of Contents** - - - ## Driver The task of the [driver][g-rollup-driver] in the [rollup node][g-rollup-node] diff --git a/specs/protocol/safe-liveness-checking.md b/specs/protocol/safe-liveness-checking.md index 7a7a927c7..0167bfb10 100644 --- a/specs/protocol/safe-liveness-checking.md +++ b/specs/protocol/safe-liveness-checking.md @@ -1,8 +1,27 @@ # Safe Liveness Checking + + **Table of Contents** - +- [Liveness checking Mechanism](#liveness-checking-mechanism) +- [Liveness checking methodology](#liveness-checking-methodology) + - [The liveness guard](#the-liveness-guard) + - [The liveness module](#the-liveness-module) + - [Owner removal call flow](#owner-removal-call-flow) + - [Shutdown](#shutdown) + - [Security Properties](#security-properties) + - [In the guard](#in-the-guard) + - [In the module](#in-the-module) + - [Interdependency between the guard and module](#interdependency-between-the-guard-and-module) +- [Operational considerations](#operational-considerations) + - [Manual validation of new owner liveness](#manual-validation-of-new-owner-liveness) + - [Deploying the liveness checking system](#deploying-the-liveness-checking-system) + - [Modify the liveness checking system](#modify-the-liveness-checking-system) + - [Replacing the module](#replacing-the-module) + - [Replacing the guard](#replacing-the-guard) + + ## Liveness checking Mechanism diff --git a/specs/protocol/span-batches.md b/specs/protocol/span-batches.md index 731fcef47..1aabf0044 100644 --- a/specs/protocol/span-batches.md +++ b/specs/protocol/span-batches.md @@ -1,12 +1,34 @@ # Span-batches - + + +**Table of Contents** -[g-deposit-tx-type]: ../glossary.md#deposited-transaction-type +- [Introduction](#introduction) +- [Span batch format](#span-batch-format) + - [Max span-batch size](#max-span-batch-size) + - [Future batch-format extension](#future-batch-format-extension) +- [Span batch Activation Rule](#span-batch-activation-rule) +- [Optimization Strategies](#optimization-strategies) + - [Truncating information and storing only necessary data](#truncating-information-and-storing-only-necessary-data) + - [`tx_data_headers` removal from initial specs](#tx_data_headers-removal-from-initial-specs) + - [`Chain ID` removal from initial specs](#chain-id-removal-from-initial-specs) + - [Reorganization of constant length transaction fields](#reorganization-of-constant-length-transaction-fields) + - [RLP encoding for only variable length fields](#rlp-encoding-for-only-variable-length-fields) + - [Store `y_parity` and `protected_bit` instead of `v`](#store-y_parity-and-protected_bit-instead-of-v) + - [Adjust `txs` Data Layout for Better Compression](#adjust-txs-data-layout-for-better-compression) + - [`fee_recipients` Encoding Scheme](#fee_recipients-encoding-scheme) +- [How derivation works with Span Batch?](#how-derivation-works-with-span-batch) +- [Integration](#integration) + - [Channel Reader (Batch Decoding)](#channel-reader-batch-decoding) + - [Batch Queue](#batch-queue) + - [Batcher](#batcher) + + -**Table of Contents** + - +[g-deposit-tx-type]: ../glossary.md#deposited-transaction-type > The span-batches spec is experimental :shipit: > diff --git a/specs/protocol/superchain-configuration.md b/specs/protocol/superchain-configuration.md index e2b389972..000b7cb34 100644 --- a/specs/protocol/superchain-configuration.md +++ b/specs/protocol/superchain-configuration.md @@ -1,11 +1,22 @@ # Superchain Configuration -The SuperchainConfig contract is used to manage global configuration values for multiple OP Chains within -a single Superchain network. - + + **Table of Contents** - +- [Overview](#overview) +- [Configurable values](#configurable-values) +- [Configuration data flow](#configuration-data-flow) + - [Pausability](#pausability) + - [Paused identifiers](#paused-identifiers) + - [Scope of pausability](#scope-of-pausability) + + + +## Overview + +The SuperchainConfig contract is used to manage global configuration values for multiple OP Chains within +a single Superchain network. ## Configurable values diff --git a/specs/protocol/superchain-upgrades.md b/specs/protocol/superchain-upgrades.md index ca12b1dff..8f35f6449 100644 --- a/specs/protocol/superchain-upgrades.md +++ b/specs/protocol/superchain-upgrades.md @@ -1,5 +1,36 @@ # Superchain Upgrades + + +**Table of Contents** + +- [Overview](#overview) +- [Protocol Version](#protocol-version) + - [Protocol Version Format](#protocol-version-format) + - [Build identifier](#build-identifier) + - [Major versions](#major-versions) + - [Minor versions](#minor-versions) + - [Patch versions](#patch-versions) + - [Pre-releases](#pre-releases) + - [Protocol Version Exposure](#protocol-version-exposure) +- [Superchain Target](#superchain-target) + - [Superchain Version signaling](#superchain-version-signaling) + - [`ProtocolVersions` L1 contract](#protocolversions-l1-contract) +- [Activation rules](#activation-rules) + - [L2 Block-number based activation (deprecated)](#l2-block-number-based-activation-deprecated) + - [L2 Block-timestamp based activation](#l2-block-timestamp-based-activation) +- [OP-Stack Protocol versions](#op-stack-protocol-versions) +- [Post-Bedrock Network upgrades](#post-bedrock-network-upgrades) + - [Regolith](#regolith) +- [Canyon](#canyon) +- [Delta](#delta) +- [Ecotone](#ecotone) +- [Fjord](#fjord) + + + +## Overview + Superchain upgrades, also known as forks or hardforks, implement consensus-breaking changes. A Superchain upgrade requires the node software to support up to a given Protocol Version. @@ -11,10 +42,6 @@ as well as the default Superchain Targets. Activation rule parameters of network upgrades are configured as part of the Superchain Target specification: chains following the same Superchain Target upgrade synchronously. -**Table of Contents** - - - ## Protocol Version The Protocol Version documents the progression of the total set of canonical OP-Stack specifications. diff --git a/specs/protocol/system_config.md b/specs/protocol/system_config.md index 4279cef47..f5b67c599 100644 --- a/specs/protocol/system_config.md +++ b/specs/protocol/system_config.md @@ -1,8 +1,23 @@ # System Config + + **Table of Contents** - +- [Overview](#overview) +- [System config contents (version 0)](#system-config-contents-version-0) + - [`batcherHash` (`bytes32`)](#batcherhash-bytes32) + - [Scalars](#scalars) + - [Pre-Ecotone `scalar`, `overhead` (`uint256,uint256`)](#pre-ecotone-scalar-overhead-uint256uint256) + - [Ecotone `scalar`, `overhead` (`uint256,uint256`) change](#ecotone-scalar-overhead-uint256uint256-change) + - [`gasLimit` (`uint64`)](#gaslimit-uint64) + - [`unsafeBlockSigner` (`address`)](#unsafeblocksigner-address) +- [Writing the system config](#writing-the-system-config) +- [Reading the system config](#reading-the-system-config) + + + +## Overview The `SystemConfig` is a contract on L1 that can emit rollup configuration changes as log events. The rollup [block derivation process](derivation.md) picks up on these log events and applies the changes. diff --git a/specs/protocol/withdrawals.md b/specs/protocol/withdrawals.md index 4c5a99e63..86fd54f8f 100644 --- a/specs/protocol/withdrawals.md +++ b/specs/protocol/withdrawals.md @@ -1,5 +1,24 @@ # Withdrawals + + +**Table of Contents** + +- [Overview](#overview) +- [Withdrawal Flow](#withdrawal-flow) + - [On L2](#on-l2) + - [On L1](#on-l1) +- [The L2ToL1MessagePasser Contract](#the-l2tol1messagepasser-contract) + - [Addresses are not Aliased on Withdrawals](#addresses-are-not-aliased-on-withdrawals) +- [The Optimism Portal Contract](#the-optimism-portal-contract) +- [Withdrawal Verification and Finalization](#withdrawal-verification-and-finalization) +- [Security Considerations](#security-considerations) + - [Key Properties of Withdrawal Verification](#key-properties-of-withdrawal-verification) + - [Handling Successfully Verified Messages That Fail When Relayed](#handling-successfully-verified-messages-that-fail-when-relayed) + - [OptimismPortal can send arbitrary messages on L1](#optimismportal-can-send-arbitrary-messages-on-l1) + + + [g-deposits]: ../glossary.md#deposits @@ -10,6 +29,8 @@ [g-relayer]: ../glossary.md#withdrawals [g-execution-engine]: ../glossary.md#execution-engine +## Overview + [Withdrawals][g-withdrawal] are cross domain transactions which are initiated on L2, and finalized by a transaction executed on L1. Notably, withdrawals may be used by an L2 account to call an L1 contract, or to transfer ETH from an L2 account to an L1 account. @@ -34,10 +55,6 @@ In this way, withdrawals are different from [deposits][g-deposits] which make us [execution engine][g-execution-engine] client. Rather, withdrawals transaction must use smart contracts on L1 for finalization. -**Table of Contents** - - - ## Withdrawal Flow We first describe the end to end flow of initiating and finalizing a withdrawal: diff --git a/specs/root.md b/specs/root.md index 935312f95..3972aa108 100644 --- a/specs/root.md +++ b/specs/root.md @@ -3,6 +3,16 @@ This directory contains the plain english specs for Optimism, a minimal optimistic rollup protocol that maintains 1:1 compatibility with Ethereum. + + +**Table of Contents** + +- [Specification Contents](#specification-contents) + - [Experimental](#experimental) +- [Design Goals](#design-goals) + + + ## Specification Contents - [Introduction](introduction.md)