### Copy Upgrade Config Example

Source: https://github.com/ethereum-optimism/specs/blob/main/scripts/README.md

Use this command to create a new upgrade configuration file by copying an existing example.

```bash
cp scripts/upgrades/gen_interop_upgrade_tx_specs.sh scripts/upgrades/gen_<yourfork>_upgrade_tx_specs.sh
```

--------------------------------

### Install Just

Source: https://github.com/ethereum-optimism/specs/blob/main/README.md

Installs 'just', a command runner that simplifies running project tasks. Follow the provided link for detailed installation instructions specific to your operating system.

```sh
brew install just
```

--------------------------------

### Install Dependencies with Mise

Source: https://github.com/ethereum-optimism/specs/blob/main/README.md

Use this command after installing mise to fetch all project dependencies. Ensure mise is installed and configured for the project directory.

```sh
mise install
```

--------------------------------

### Install mdbook and Plugins

Source: https://github.com/ethereum-optimism/specs/blob/main/README.md

Installs mdbook, a command-line utility for creating beautiful, themeable, and interactive documentation websites, along with its plugins for LaTeX, link checking, and Mermaid diagrams.

```sh
cargo install mdbook mdbook-katex mdbook-linkcheck mdbook-mermaid
```

--------------------------------

### Install Rust Toolchain

Source: https://github.com/ethereum-optimism/specs/blob/main/README.md

Installs the Rust programming language toolchain using the official installation script. This is a prerequisite for building and running Rust-based tools.

```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Initialization and Configuration

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/stage-one/anchor-state-registry.md

Functions related to the initial setup and configuration of the Anchor State Registry.

```APIDOC
## POST /initialize

### Description
Initializes the Anchor State Registry contract. This function can only be called once by the ProxyAdmin or its owner.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Request Body
- **systemConfig** (address) - Required - The address of the SystemConfig contract.
- **disputeGameFactory** (address) - Required - The address of the DisputeGameFactory contract.
- **startingAnchorState** (bytes32) - Required - The initial anchor state.
- **initialRespectedGameType** (uint8) - Required - The initial respected game type.
- **retirementTimestamp** (uint64) - Required - The initial retirement timestamp.

### Request Example
{
  "systemConfig": "0x...",
  "disputeGameFactory": "0x...",
  "startingAnchorState": "0x...",
  "initialRespectedGameType": 1,
  "retirementTimestamp": 1678886400
}

### Response
#### Success Response (200)
- **message** (string) - Initialization successful.
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/ethereum-optimism/specs/blob/main/README.md

Starts a local development server to preview the documentation. This command uses 'just' to execute the serving task defined in the Justfile.

```sh
just serve
```

--------------------------------

### Execute Proposal with Module

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Execute a proposal created with a module. It calls the module's formatExecuteParams function to get execution data and emits ProposalExecuted.

```Solidity
function executeWithModule(address _module, bytes memory _proposalData, bytes32 _descriptionHash) external payable returns (uint256)
```

--------------------------------

### executeWithModule

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Executes a proposal created with a module. Calls the module's formatExecuteParams function to get execution data.

```APIDOC
## executeWithModule

### Description
Similar to [`execute`](#execute), but for proposals that were created with a module. This MUST only be possible when the proposal has reached quorum and is considered successful in terms of votes.

This function must call the `formatExecuteParams` function of the module passing the proposal ID and data to receive the formatted `targets`, `values`, and `calldatas` for execution. This MUST adhere to the [module's interface](#interface-1).

### Method
External

### Endpoint
N/A (Smart Contract Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **proposalId** (uint256) - The ID of the executed proposal.

#### Response Example
None

### Events
- `ProposalExecuted`
```

--------------------------------

### Get Function Signature for setFjord()

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/fjord/derivation.md

Retrieves the function signature for the `setFjord()` function, which is used to inform the GasPriceOracle to start using the Fjord gas calculation formula.

```bash
cast sig "setFjord()"
```

--------------------------------

### Get Voting Delay

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Returns the number of blocks that must pass between a proposal's creation and the start of its voting period. This delay ensures sufficient time for review.

```solidity
function votingDelay() external view returns (uint256);
```

--------------------------------

### constructor

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/mint-manager.md

Initializes the MintManager contract with the specified upgrader and governance token addresses.

```APIDOC
### constructor

```solidity
constructor(address _upgrader, address _governanceToken)
```

Initializes the `MintManager` contract with the specified owner and governance token.

**Parameters:**
- `_upgrader` (address) - The address that will become the owner of this contract
- `_governanceToken` (address) - The address of the `GovernanceToken` contract that this manager will control

**Behavior:**
- MUST call `transferOwnership(_upgrader)` to set the contract owner
- MUST set `governanceToken` to the provided `_governanceToken` address
- MUST initialize `mintPermittedAfter` to enable immediate first mint while enforcing restrictions on subsequent mints
- MUST NOT validate that `_upgrader` or `_governanceToken` are non-zero addresses (caller responsibility)
```

--------------------------------

### clock_gettime

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/cannon-fault-proof-vm.md

Gets the current time from a specified clock.

```APIDOC
## clock_gettime

### Description
Supports `clock_id`'s `REALTIME`(0) and `MONOTONIC`(1). For other `clock_id`'s, sets errno to `0x16`. Calculates a deterministic time value based on the state's `step` field and a constant `HZ` (10,000,000) where `HZ` represents the approximate clock rate (steps / second) of the FPVM:

`seconds = step/HZ`
`nsecs = (step % HZ) * 10^9/HZ`

Seconds are set at memory address `addr` and nsecs are set at `addr + WordSize`.

### Method
N/A (System Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **clock_id** (uint64) - The ID of the clock to query (0 for REALTIME, 1 for MONOTONIC).
- **addr** (uint64) - The memory address to store the seconds value.

### Request Example
N/A

### Response
#### Success Response (200)
N/A (Time is written to the provided address)

#### Response Example
N/A
```

--------------------------------

### Bootstrapping Pre-image Key Type

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/index.md

The initial inputs for bootstrapping the program are requested from the VM using pre-image key type '1'.

```plaintext
1
```

--------------------------------

### Pre-image Hinting Routes

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/index.md

Exposes hint handling for the VM and external program testing via CLI or inter-process API. Blockhashes are 0x-prefixed, lowercase hex.

```APIDOC
## Pre-image Hinting Routes

### `l1-block-header <blockhash>`

#### Description

Requests the host to prepare the L1 block header RLP pre-image of the block `<blockhash>`.

### `l1-transactions <blockhash>`

#### Description

Requests the host to prepare the list of transactions of the L1 block with `<blockhash>`, including MPT nodes.

### `l1-receipts <blockhash>`

#### Description

Requests the host to prepare the list of receipts of the L1 block with `<blockhash>`, including MPT nodes.

### `l1-blob <blobhash ++ metadata>`

#### Description

Requests the host to prepare EIP-4844 blob data for fault proof verification.

#### Hint Data Format

- Bytes 0-31: Blob version hash (32 bytes)
- Bytes 32-39: L1 block timestamp (8-byte big-endian uint64)

#### Host Actions

1. Fetch blob from L1 beacon chain.
2. Compute KZG commitment and prepare as SHA256 preimage.
3. Prepare all 4096 field elements of the blob as Blob-type preimages.

### `l1-precompile-v2 <address ++ requiredGas ++ inputbytes>`

#### Description

Requests the host to prepare the result of an L1 precompile call with gas validation.

#### Hint Data Format

- Bytes 0-19: Precompile address (20 bytes)
- Bytes 20-27: Required gas (8-byte big-endian uint64)
- Bytes 28+:
  Input bytes

#### Host Actions

Validates the precompile address against an allowlist and prepares a precompile-type preimage of the execution result. `requiredGas` enforces complete precompile execution.

### `l2-block-header <blockhash> [chainID]?`

#### Description

Requests the host to prepare the L2 block header RLP pre-image of the block `<blockhash>`.

#### Parameters

- **chainID** (uint64, optional): Big-endian uint64 value to specify L2 chain. Required when interop hard fork is active.

### `l2-transactions <blockhash> [chainID]?`

#### Description

Requests the host to prepare the list of transactions of the L2 block with `<blockhash>`, including MPT nodes.

#### Parameters

- **chainID** (uint64, optional): Big-endian uint64 value to specify L2 chain. Required when interop hard fork is active.

### `l2-receipts <blockhash> <chainID>`

#### Description

Requests the host to prepare the list of receipts of the L2 block with `<blockhash>` for the specified `<chainID>`, including MPT nodes.

#### Parameters

- **chainID** (uint64): Big-endian uint64 value to specify L2 chain. Required when interop hard fork is active.

#### Note

This hint is used only when the interop hard fork is active.
```

--------------------------------

### Get Recipient Address

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/revshare/predeploys.md

Returns the current recipient address stored in the contract.

```solidity
function recipient() external view returns (address)
```

--------------------------------

### Example Upgrade Configuration Variables

Source: https://github.com/ethereum-optimism/specs/blob/main/scripts/README.md

These variables define the parameters for an upgrade transaction specification. Ensure GIT_COMMIT_HASH points to the correct Optimism repo commit and contracts are listed with their respective proxy addresses.

```bash
GIT_COMMIT_HASH=71c460ec7c7c05791ddd841b97bcb664a1f0c753
FROM_ADDRESS_NONCE=0
FROM_ADDRESS=0x4220000000000000000000000000000000000000
FORK_NAME=Interop

declare -a contracts=(
    "CrossL2Inbox:0x4200000000000000000000000000000000000022"
    "L2ToL2CrossDomainMessenger:0x4200000000000000000000000000000000000023"
)
```

--------------------------------

### Get Withdrawal Network

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/revshare/predeploys.md

Returns the current withdrawal network configuration stored in the contract.

```solidity
function withdrawalNetwork() external view returns (WithdrawalNetwork)
```

--------------------------------

### Get EIP-1559 Denominator Function

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/holocene/system-config.md

Returns the currently configured EIP-1559 denominator value.

```solidity
function eip1559Denominator()(uint32)
```

--------------------------------

### Get EIP-1559 Elasticity Function

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/holocene/system-config.md

Returns the currently configured EIP-1559 elasticity value.

```solidity
function eip1559Elasticity()(uint32)
```

--------------------------------

### L2 Output Hint

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/index.md

Requests the host to prepare the L2 Output at the given l2 output root. The optional chainID specifies the L2 chain.

```APIDOC
## l2-output <outputroot> <chainID>?

Requests the host to prepare the L2 Output at the l2 output root `<outputroot>`.
The L2 Output is the preimage of a
[computed output root](../protocol/proposals.md#l2-output-commitment-construction).

The `<chainID>` is optionally concatenated after the `<blockHash>` as a big endian uint64 value to specify which L2
chain to retrieve data from. `<chainID>` must be specified when the interop hard fork is active.
```

--------------------------------

### Get Minimum Withdrawal Amount

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/revshare/predeploys.md

Returns the current minimum withdrawal amount stored in the contract.

```solidity
function minWithdrawalAmount() external view returns (uint256)
```

--------------------------------

### Initialization and Upgrade

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/superchain-config.md

Details on how the pause mechanism is initialized and upgraded, including access control and event emission.

```APIDOC
## initialize

### Description
Initializes the pause mechanism. This function is restricted to the ProxyAdmin or its owner and can only be called once.

### Method
(Not specified, likely a constructor or initialization function)

### Endpoint
(Not specified)

### Parameters
#### Request Body
- **guardian** (address) - Required - The address of the Guardian role.

### Response
#### Success Response (200)
(No specific response details provided, but an event is emitted)
- **ConfigUpdate** - Emitted with the Guardian address.

## upgrade

### Description
Upgrades the pause mechanism, migrating guardian data and clearing old storage slots while maintaining contract version information. This function is restricted to the ProxyAdmin or its owner.

### Method
(Not specified, likely an upgrade function)

### Endpoint
(Not specified)

### Parameters
(No specific parameters mentioned for upgrade)

### Response
#### Success Response (200)
(No specific response details provided)
```

--------------------------------

### Get Quorum Denominator

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Returns the denominator used in the quorum calculation. This value is part of the quorum configuration.

```solidity
function quorumDenominator() external view returns (uint256);
```

--------------------------------

### Usage in `prove()`

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/stage-one/zk/zk-interface.md

Demonstrates how the ZKDisputeGame contract uses the IZKVerifier interface to verify proofs.

```APIDOC
## Usage in `prove()`

### Description
This section illustrates how the `ZKDisputeGame.prove()` function constructs `publicValues` from on-chain game state and forwards them, along with the proof, to the `IZKVerifier` interface for verification.

### Method
`prove(bytes calldata _proofBytes)`

### Endpoint
`ZKDisputeGame.prove()`

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **`_proofBytes`** (bytes calldata) - The raw proof blob submitted by the prover.

### Request Example
```solidity
function prove(bytes calldata _proofBytes) external {
    bytes memory publicValues = abi.encode(
        l1Head(),
        startingOutputRoot(),
        rootClaim(),
        l2SequenceNumber(),
        l2ChainId()
    );

    IZKVerifier(verifier()).verify(
        absolutePrestate(),
        publicValues,
        _proofBytes
    );

    // record proof submission and set game over
}
```

### Response

#### Success Response (200)
Upon successful verification by `IZKVerifier.verify()`, the game state transitions to `UnchallengedAndValidProofProvided` or `ChallengedAndValidProofProvided`, and the game is marked as over.

#### Response Example
None
```

--------------------------------

### Get Governor Contract Name

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Returns the name of the Governor contract. Useful for identification and logging purposes.

```solidity
function name() external view returns (string memory);
```

--------------------------------

### mmap Syscall

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/cannon-fault-proof-vm.md

Allocates a page from the heap.

```APIDOC
## mmap Syscall

### Description
Allocates a page from the heap. See [heap](#heap) for details.

### Method
SYSCALL

### Endpoint
5009

### Parameters
#### Path Parameters
- **addr** (uint64) - Required - The starting address for the allocation.
- **len** (uint64) - Required - The length of the memory to allocate.

### Request Example
```json
{
  "syscall_id": 5009,
  "args": {
    "addr": "0x1000",
    "len": "0x1000"
  }
}
```

### Response
#### Success Response (200)
- **allocated_address** (uint64) - The address of the allocated memory page.

#### Response Example
```json
{
  "status": "success",
  "allocated_address": "0x1000"
}
```
```

--------------------------------

### Get Governor Manager Address

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Retrieves the address of the current manager for the Governor contract. This is essential for administrative operations.

```solidity
function manager() external view returns (address);
```

--------------------------------

### Build and Extract GasPriceOracle Bytecode

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/fjord/derivation.md

This sequence of commands checks out a specific git commit, builds the project, and then extracts the bytecode for the GasPriceOracle contract using `jq`.

```bash
git checkout 52abfb507342191ae1f960b443ae8aec7598755c
pnpm clean && pnpm install && pnpm build
jq -r ".bytecode.object" packages/contracts-bedrock/forge-artifacts/GasPriceOracle.sol/GasPriceOracle.json
```

--------------------------------

### Initialize Contract

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/revshare/predeploys.md

Initializes the contract with the shares calculator and sets the default disbursement interval.

```APIDOC
## POST /initialize

### Description
Initializes the contract with the shares calculator and sets disbursement interval to `1 days` as default.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Request Body
- **_sharesCalculator** (ISharesCalculator) - Required - The address of the shares calculator.

### Request Example
```json
{
  "_sharesCalculator": "0x..."
}
```

### Response
#### Success Response (200)
- **message** (string) - Initialization successful.

#### Response Example
```json
{
  "message": "Contract initialized successfully."
}
```
```

--------------------------------

### Get current voting power

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Returns the current voting power of an account, which is determined by the amount of `GovernanceToken` delegated to it.

```Solidity
function getVotes(uint256 _account) external view returns (uint256);
```

--------------------------------

### Run Upgrade Transaction Spec Generator

Source: https://github.com/ethereum-optimism/specs/blob/main/scripts/README.md

Execute the main script to generate upgrade transaction specifications. The output can be printed to stdout or captured to a file using tee.

```bash
bash generate_upgrade_tx_specs.sh ./upgrades/interop.sh
```

```bash
bash generate_upgrade_tx_specs.sh ./upgrades/interop.sh | tee /tmp/<yourfork>-gen.md
```

--------------------------------

### New `DeployConfig` Variables

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/stage-one/bridge-integration.md

Details on new configuration variables introduced for deployment.

```APIDOC
## New `DeployConfig` Variables

### Description
These variables are part of the `DeployConfig` and affect the behavior and security of the Optimism Portal.

### Variables

- **`DISPUTE_GAME_FINALITY_DELAY_SECONDS`** (integer) - The time delay for the `Guardian` role to blacklist a resolved dispute game before withdrawals can be finalized, in case of system failure.
- **`PROOF_MATURITY_DELAY_SECONDS`** (integer) - Defines the duration that must pass between proving and finalizing a withdrawal. This is a successor to `FINALIZATION_PERIOD_SECONDS` in the `L2OutputOracle`.
- **`RESPECTED_GAME_TYPE`** (enum) - Specifies the dispute game type that the portal utilizes for the withdrawal path.
```

--------------------------------

### Get ProxyAdmin Owner Address

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/interop/optimism-portal.md

Returns the address of the ProxyAdmin owner responsible for managing the ETHLockbox. This is a view function.

```solidity
function proxyAdminOwner() external view returns (address);
```

--------------------------------

### Deploy OptimismSuperchainERC20 Contract

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/interop/predeploys.md

Creates an instance of the OptimismSuperchainERC20 contract using CREATE3. The salt for deployment is derived from the input parameters to ensure address consistency across chains. Stores the remote token address in a deployments mapping.

```solidity
function deploy(address _remoteToken, string memory _name, string memory _symbol, uint8 _decimals) returns (address)
```

--------------------------------

### Get Message Nonce with Version

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/interop/predeploys.md

Retrieves the current message nonce combined with the message version. This is used for message versioning.

```solidity
function messageNonce() public view returns (uint256) {
    return Encoding.encodeVersionedNonce(nonce, MESSAGE_VERSION);
}
```

--------------------------------

### FeeSplitter Get Recipients and Amounts

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/revshare/predeploys.md

Calculates and returns the recipients and their corresponding amounts based on vault balances and a shares calculator.

```solidity
function getRecipientsAndAmounts(
        uint256 _sequencerFeeVaultBalance,
        uint256 _baseFeeVaultBalance,
        uint256 _operatorFeeVaultBalance,
        uint256 _l1FeeVaultBalance)
        external
        view
        returns (ShareInfo[] memory shareInfo);
```

--------------------------------

### L2 Account Proof Hint

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/fault-proof/index.md

Requests the host to send account proof for a certain block hash and address. The chain ID must be included.

```APIDOC
## l2-account-proof <blockhash_and_address>

Requests the host send account proof for a certain block hash and address. `<blockhash_and_address>` is hex
encoded: 32-byte block hash + 20-byte address + 8 byte big endian chain ID.
```

--------------------------------

### Retrieve CrossL2Inbox Bytecode

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/interop/derivation.md

Fetch the deployment bytecode for the CrossL2Inbox contract by checking out a specific git commit and using `make build-contracts` followed by `jq`.

```bash
git checkout 71c460ec7c7c05791ddd841b97bcb664a1f0c753
make build-contracts
jq -r ".bytecode.object" packages/contracts-bedrock/forge-artifacts/CrossL2Inbox.sol/CrossL2Inbox.json
```

--------------------------------

### Get Proposal Type Data

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Getter function to retrieve the proposal type data for a given ID. This is a view function.

```solidity
function proposalTypes(uint256 _proposalTypeId) external view returns (ProposalType memory);
```

--------------------------------

### Get Weight Cast for Proposal

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/governance/governor.md

Returns the total number of votes an account has cast for a specific proposal. This is a view function.

```solidity
function weightCast(uint256 _proposalId, uint256 _account) external view returns (uint256);
```

--------------------------------

### Flashblock Construction Sequence Diagram

Source: https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/flashblocks.md

Illustrates the interaction between the External Block Builder, Rollup Boost, Execution Engine, and Mempool during Flashblock construction.

```mermaid
sequenceDiagram
    participant BB as External Block Builder
    participant RB as Rollup Boost
    participant EE as Execution Engine (local)
    participant M as Mempool

    loop Every FLASHBLOCKS_TIME
        BB->>M: Retrieve and Prioritize Transactions
        M-->>BB: Transactions batch
        Note over BB: Execute transactions sequentially
        BB->>EE: Execute transactions and compute state root
        EE-->>BB: Execution results (state root, receipts, gas used)

        Note over BB: Construct Flashblock Delta
        BB->>BB: Assemble FlashblocksPayloadV1 (state_root, receipts_root, logs_bloom, gas_used, block_hash, txs,
withdrawals, metadata)

        BB->>RB: Submit FlashblocksPayloadV1
        RB-->>BB: Acknowledge reception (async)
        Note over BB: Increment index, prepare next Flashblock
    end
```