Fix broken links

.github/workflows/lint.yml

@@ -39,3 +39,14 @@ jobs:
 
       - name: Lint
         run: yarn lint:check
+
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Link Checker
+        uses: lycheeverse/lychee-action@v1.2.0
+        with:
+          args: --verbose --no-progress --exclude twitter.com --exclude-mail README.md "./specs/**/*.md" "./meta/**/*.md" "./opnode/**/*.md"
+          fail: true

package.json

@@ -9,8 +9,10 @@
     "markdownlint-cli2": "^0.3.2"
   },
   "scripts": {
+    "setup": "yarn install && cargo install lychee",
     "lint": "yarn lint:fix && yarn lint:check",
     "lint:fix": "markdownlint-cli2-fix \"./specs/**/*.md\" \"#node_modules\"",
-    "lint:check": "markdownlint-cli2 \"./specs/**/*.md\" \"#node_modules\""
+    "lint:check": "markdownlint-cli2 \"./specs/**/*.md\" \"#node_modules\"",
+    "lint:links": "lychee --exclude twitter.com --exclude-mail README.md \"./specs/**/*.md\" \"./meta/**/*.md\" \"./opnode/**/*.md\""
   }
 }

specs/deposits.md

@@ -1,12 +1,12 @@
 # Deposits
 
 <!-- All glossary references in this file. -->
-[transaction-type]: /glossary.md#transaction-type
-[derivation]:  /glossary.md#L2-chain-derivation
-[execution-engine]: /glossary.md#execution-engine
-[deposits]: /glossary.md#deposits
-[L1 attributes deposit]: /glossary.md#l1-attributes-deposit
-[transaction deposits]: /glossary.md#transaction-deposits
+[transaction-type]: glossary.md#transaction-type
+[derivation]:  glossary.md#L2-chain-derivation
+[execution-engine]: glossary.md#execution-engine
+[deposits]: glossary.md#deposits
+[L1 attributes deposit]: glossary.md#l1-attributes-deposit
+[transaction deposits]: glossary.md#transaction-deposits
 
 [Deposits] are transactions which are initiated on L1, and executed on L2. This document outlines a
 new [transaction type][transaction-type] for deposits. It also describes how deposits are initiated
@@ -146,7 +146,7 @@ certain block variables from the corresponding L1 block in storage, so that they
 during the execution of the subsequent deposited transactions.
 
 The contract implements an authorization scheme, such that it only accepts state-changing calls from
-the [depositor account].
+the [depositor account][depositor-account].
 
 The contract has the following solidity interface, and can be interacted with according to the
 [contract ABI specification][ABI].
@@ -159,12 +159,11 @@ The contract has the following solidity interface, and can be interacted with ac
 
 A reference implementation of the L1 Attributes predeploy contract can be found in [L1Block.sol].
 
-[L1Block.sol]: /packages/contracts/contracts/L1Block.sol
+[L1Block.sol]: ../packages/contracts/contracts/L2/L1Block.sol
 
-The bytecode to add to the genesis file will be located in the `deployedBytecode` of the
-[JSON artifact file][l1-block-artifacts] corresponding to L1Block.sol.
-
-[l1-block-artifacts]: /packages/contracts/artifacts/contracts/L2/L1Block.sol/L1Block.json
+After running `yarn build` in the `packages/contracts` directory, the bytecode to add to the genesis
+file will be located in the `deployedBytecode` field of the build artifacts file at
+`/packages/contracts/artifacts/contracts/L2/L1Block.sol/L1Block.json`.
 
 ## L1 Transaction Deposits
 
@@ -206,14 +205,14 @@ The deposit feed handles two special cases:
 
 [address-aliasing]: #address-aliasing
 
-If the caller is not a contract, the address will be ed by adding
-`0x1111000000000000000000000000000000001111`. This prevents attacks in which a contract on L1 has
-the same address as a contract on L2 but doesn't have the same code. We can safely ignore this for
-EOAs because they're guaranteed to have the same "code" (i.e. no code at all). This also makes it
-possible for users to interact with contracts on L2 even when the Sequencer is down.
+If the caller is not a contract, the address will be transformed by adding
+`0x1111000000000000000000000000000000001111` to it. This prevents attacks in which a contract on L1
+has the same address as a contract on L2 but doesn't have the same code. We can safely ignore this
+for EOAs because they're guaranteed to have the same "code" (i.e. no code at all). This also makes
+it possible for users to interact with contracts on L2 even when the Sequencer is down.
 
 #### Deposit Feed: Reference Implementation
 
 A reference implementation of the Deposit Feed contract can be found in [DepositFeed.sol].
 
-[DepositFeed.sol]: /packages/contracts/contracts/DepositFeed.sol
+[DepositFeed.sol]: ../packages/contracts/contracts/L1/DepositFeed.sol

specs/exec-engine.md

@@ -7,12 +7,12 @@ This document outlines the modifications, configuration and usage of a L1 execut
 The Engine interfaces abstract away transaction types with [EIP-2718][eip-2718].
 
 To support rollup functionality, processing of a new Deposit [`TransactionType`][eip-2718-transactions]
-is implemented by the engine, see the [deposit specification][deposit-spec].
+is implemented by the engine, see the [deposits specification][deposit-spec].
 
 This type of transaction can mint L2 ETH, run EVM,
 and introduce L1 information to enshrined contracts in the execution state.
 
-[deposit-spec]: ./deposits#deposit-transaction-type
+[deposit-spec]: deposits.md
 
 ### Deposit boundaries
 
@@ -62,7 +62,7 @@ This `transactions` field is an optional JSON field:
 
 > **TODO**: derivation function spec in rollup node doc or separate driver doc
 
-[rollup-driver]: ./rollup-driver.md
+[rollup-driver]: rollup-node.md
 
 ### `engine_executePayloadV1`
 

specs/glossary.md

@@ -12,6 +12,7 @@
   - [Predeployed Contract ("Predeploy")](#predeployed-contract-predeploy)
   - [Receipt](#receipt)
   - [Transaction Type](#transaction-type)
+  - [Fork Choice Rule](#fork-choice-rule)
 - [L2 Chain Concepts](#l2-chain-concepts)
       - [Address Aliasing](#address-aliasing)
   - [L2 Chain Inception](#l2-chain-inception)
@@ -33,20 +34,20 @@
 
 ## Layer 1 (L1)
 
-[L1]: /glossary.md#layer-1-L1
+[L1]: glossary.md#layer-1-L1
 
 Refers the Ethereum blockchain, used in contrast to [layer 2][L2], which refers to Optimism.
 
 ## Layer 2 (L2)
 
-[L2]: /glossary.md#layer-2-L2
+[L2]: glossary.md#layer-2-L2
 
 Refers to the Optimism blockchain (specified in this repository), used in contrast to [layer 1][L1], which
 refers to the Ethereum blockchain.
 
 ## Block
 
-[block]: /glossary.md#block
+[block]: glossary.md#block
 
 Can refer to an [L1] block, or to an [L2] block, which are structured similarly.
 
@@ -60,13 +61,13 @@ block, and output block properties, which are derived after executing the block'
 
 ## EOA
 
-[EOA]: /glossary.md#EOA
+[EOA]: glossary.md#EOA
 
 "Externally Owned Account", an Ethereum term to designate addresses operated by users, as opposed to contract addresses.
 
 ## Merkle Root
 
-[Merkle root]: /glossary.md#merkle-roots
+[Merkle root]: glossary.md#merkle-roots
 
 The Merkle root is the root hash of a [Merkle Patricia tree] (MPT). A MPT is a sparse [trie], which is a tree-like
 structure that maps keys to values. The root hash of a MPT is a commitment to the contents of the tree, which allows a
@@ -75,17 +76,17 @@ verified against the Merkle root.
 
 ## Chain Re-Organization
 
-[reorg]: /glossary.md#chain-re-organization
+[reorg]: glossary.md#chain-re-organization
 
 A re-organization, or re-org for short, is whenever the head of a blockchain (its last block) changes (as dictated by
-the [fork choice rule]) to a block that is not a child of the previous head.
+the [fork choice rule][fork-choice-rule]) to a block that is not a child of the previous head.
 
 L1 re-orgs can happen because of network conditions or attacks. L2 re-orgs are a consequence of L1 re-orgs, mediated via
 [L2 chain derivation][derivation].
 
 ## Predeployed Contract ("Predeploy")
 
-[predeploy]: /glossary.md#predeployed-contract-predeploy
+[predeploy]: glossary.md#predeployed-contract-predeploy
 
 A contract placed in the L2 genesis state (i.e. at the start of the chain).
 
@@ -95,7 +96,7 @@ Optimism has the following predeploys:
 
 ## Receipt
 
-[receipt]: /glossary.md#receipt
+[receipt]: glossary.md#receipt
 
 A receipt is an output generated by a transaction, comprising a status code, the amount of gas used, a list of log
 entries, and a [bloom filter] indexing these entries. Log entries are most notably used to encode [Solidity events].
@@ -107,60 +108,72 @@ Receipts are specified in the [yellow paper (pdf)][yellow] section 4.3.1.
 
 ## Transaction Type
 
-[transaction-type]: /glossary.md#transaction-type
+[transaction-type]: glossary.md#transaction-type
 
 Ethereum provides a mechanism (as described in [EIP-2718]) for defining different transaction types.
 Different transaction types can contain different payloads, and be handled differently by the protocol.
 
 [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
 
+## Fork Choice Rule
+
+[fork-choice-rule]: glossary.md#fork-choice-rule
+
+The fork choice rule is the rule used to determined which block is to be considered as the head of a blockchain. On L1,
+this is determined by the proof of stake rules.
+
+L2 also has a fork choice rule, although the rules vary depending on wether we want the sequencer-confirmed head, the
+on-chain-confirmed head, or the on-chain-finalized head.
+
+> TODO: define and link to those concepts
+
 ------------------------------------------------------------------------------------------------------------------------
 
 # L2 Chain Concepts
 
 ## Address Aliasing
 
-[address-aliasing]: /glossary.md#address-aliasing
+[address-aliasing]: glossary.md#address-aliasing
 
-When a contract submits a [deposit] from L1 to L2, it's address (as returned by `ORIGIN` and `CALLER`)
- will be aliased with a modified representation of the address of a contract.
+When a contract submits a [deposit][deposits] from L1 to L2, it's address (as returned by `ORIGIN` and `CALLER`) will be
+aliased with a modified representation of the address of a contract.
 
-- cf. [Deposit Specification](/deposits.md#address-aliasing)
+- cf. [Deposit Specification](deposits.md#address-aliasing)
 
 ## L2 Chain Inception
 
-[L2 chain inception]: /glossary.md#L2-chain-inception
+[L2 chain inception]: glossary.md#L2-chain-inception
 
 The L1 block number for which the first block of the L2 chain was generated.
 
 ## Rollup Node
 
-[rollup node]: /glossary.md#rollup-node
+[rollup node]: glossary.md#rollup-node
 
 The rollup node is responsible for [deriving the L2 chain][derivation] from the L1 chain (L1 [blocks][block] and their
 associated [receipts][receipt]). This is done by its [rollup driver] component.
 
-- cf. [Rollup Node Specification](/rollup-node.md)
+- cf. [Rollup Node Specification](rollup-node.md)
 
 ## Rollup Driver
 
-[rollup driver]: /glossary.md#rollup-driver
+[rollup driver]: glossary.md#rollup-driver
 
 The rollup driver is the [rollup node] component responsible for [deriving the L2 chain][derivation] from the L1 chain
 (L1 [blocks][block] and their associated [receipts][receipt]).
 
 ## L2 Chain Derivation
 
-[derivation]:  /glossary.md#L2-chain-derivation
+[derivation]: glossary.md#L2-chain-derivation
 
 A process that reads [L2 derivation inputs][deriv-inputs] from L1 in order to derive the L2 chain.
 
 cf. [L2 Chain Derivation (in Rollup Node
-Specification)](/rollup-node.md#l2-chain-derivation)
+Specification)](rollup-node.md#l2-chain-derivation)
 
 ## L2 Derivation Inputs
 
-[deriv-inputs]: /glossary.md#l2-chain-derivation-inputs
+[deriv-inputs]: glossary.md#l2-chain-derivation-inputs
 
 This term refers to data that is found in L1 blocks and is read by the [rollup node] to construct [payload attributes].
 
@@ -174,10 +187,10 @@ Chain derivation attributes include:
 
 ## Payload Attributes
 
-[payload attributes]: /glossary.md#payload-attributes
+[payload attributes]: glossary.md#payload-attributes
 
 This term refers to data that can be derived from [L2 chain derivation inputs][deriv-inputs] found on L1, which are then
-passed to the [execution engine] to construct L2 blocks.
+passed to the [execution engine][execution-engine] to construct L2 blocks.
 
 "Payload attributes" is a term that originates and is specified in the [Ethereum Engine API specification][engine-api],
 which we extend in this specification.
@@ -189,14 +202,14 @@ this term.
 
 ## Deposits
 
-[deposits]: /glossary.md#deposits
+[deposits]: glossary.md#deposits
 
 A deposit is an L2 transaction derived from an L1 block.
 
 There are two kinds of deposits:
 
-- [L1 Attributes Deposit][l1-attribute-tx], which submit the L1 block's attributes to the [L1 Attributes Predeployed
-  Contract][l1-attr-predeploy].
+- [L1 Attributes Deposit][l1-attributes-deposit], which submits the L1 block's attributes to the [L1 Attributes
+  Predeployed Contract][l1-attr-predeploy].
 - [Transaction Deposits][tx-deposits], which are transaction that have been submitted on L1, via a transaction sent to
 the [deposit feed contract][deposit-feed].
 
@@ -206,7 +219,7 @@ While transaction deposits are notably (but not only) used to "deposit" (bridge)
 The term *deposit* performs the double duty of referring to both:
 
 1. The transaction information submitted on L1 to the [deposit feed contract][deposit-feed]. This is a kind of [L2
-   derivation input][deriv-input].
+   derivation input][deriv-inputs].
 2. The actual L2 transaction derived from this L1 input.
 
 Deposits are specified in the [deposits specification][deposits-spec].
@@ -215,7 +228,7 @@ Deposits are specified in the [deposits specification][deposits-spec].
 
 ## L1 Attributes Deposit
 
-[l1-attributes-deposit]: /glossary.md#l1-attributes-deposit
+[l1-attributes-deposit]: glossary.md#l1-attributes-deposit
 
 A [deposit][deposits] that is used to register the L1 block attributes (number, timestamp, ...) on L2 via a call to the
 [L1 Attributes Predeployed Contract][l1-attr-predeploy]. That contract can then be used to read the the attributes of
@@ -240,25 +253,23 @@ specification.
 
 ## L1 Attributes Predeployed Contract
 
-[l1-attr-predeploy]: /glossary.md#l1-attributes-predeployed-contract
+[l1-attr-predeploy]: glossary.md#l1-attributes-predeployed-contract
 
 A [predeployed contract][predeploy] on L2 that can be used to retrieve the L1 block attributes of L1 blocks with a given
 block number or a given block hash.
 
-cf. [L1 Attributes Predeployed Contract Specification](TODO)
-
-> **TODO LINK** L1 attributes predeployed contract spec
+cf. [L1 Attributes Predeployed Contract Specification](#l1-attributes--reference-implementation)
 
 ## Deposit Transaction Type
 
-[deposit-tx-type]: /glossary.md#deposit-transaction-type
+[deposit-tx-type]: glossary.md#deposit-transaction-type
 
 The deposit transaction type is an [EIP-2718] [transaction type][transaction-type], which specifies
 the input fields and correct handling of a [deposit][deposits].
 
 ## Deposit Feed Contract
 
-[deposit-feed]: /glossary.md#deposit-feed-contract
+[deposit-feed]: glossary.md#deposit-feed-contract
 
 An [L1] contract to which [EOAs][EOA] and contracts may send [deposits]. The deposits are emitted as log records (in
 Solidity, these are called *events*) for consumption by [rollup nodes][rollup node].
@@ -275,7 +286,7 @@ cf. [Deposits Specification](deposits.md)
 
 ## Execution Engine
 
-[execution-engine]: /glossary.md#execution-engine
+[execution-engine]: glossary.md#execution-engine
 
 The execution engine is responsible for executing transactions in blocks and computing the resulting state roots,
 receipts roots and block hash.
@@ -286,11 +297,11 @@ On L1, the executed blocks can come from L1 block synchronization; or from a blo
 engine (using transactions from the L1 [mempool]), at the request of the L1 consensus layer.
 
 On L2, the executed blocks are freshly minted by the execution engine at the request of the [rollup node], using
-transactions [derived from L1 blocks][derivations].
+transactions [derived from L1 blocks][derivation].
 
 In these specifications, "execution engine" always refer to the L2 execution engine, unless otherwise specified.
 
-- cf. [Execution Engine Specification](/exec-engine.md)
+- cf. [Execution Engine Specification](exec-engine.md)
 
 <!-- External Links -->
 [Merkle Patricia tree]: https://github.com/norswap/nanoeth/blob/d4c0c89cc774d4225d16970aa44c74114c1cfa63/src/com/norswap/nanoeth/trees/patricia/README.md