
- [Stylus build instructions (MacOS)](#stylus-build-instructions-macos)
  - [CommandLineTools](#commandlinetools)
  - [Go](#go)
  - [Rust](#rust)
  - [Installing Rust](#installing-rust)
  - [Docker](#docker)
  - [Stylus](#stylus)

# Stylus build instructions (MacOS)

## CommandLineTools

`CommandLineTools` must be installed. If these are already installed, the following command should output the path to CLT.

```
$ xcode-select -p
/Library/Developer/CommandLineTools
```

In order to install these, run.

```
xcode-select --install
```

## Go

Go installation instructions: https://go.dev/doc/install

```
$ go version
go version go1.21.9 darwin/arm64
```

If using brew, make sure the latest version (go@1.21) is installed and linked.

```
brew install go@1.21
brew unlink go@X.XX # if any previous version is installed
brew link go@1.21
```

## Rust

Rust installation instructions: https://www.rust-lang.org/tools/install

Update Rust, install nightly, default to stable and add the wasm targets.

```
rustup update
rustup toolchain update nightly
rustup default stable
rustup target add wasm32-wasi
rustup target add wasm32-unknown-unknown
```

## Installing Rust

At some point, I had to default to nightly for the installation.

```
$ rustup show

Default host: aarch64-apple-darwin
rustup home:  /Users/lain/.rustup

installed toolchains
--------------------

stable-aarch64-apple-darwin
nightly-2022-12-16-aarch64-apple-darwin
nightly-2023-01-01-aarch64-apple-darwin
nightly-aarch64-apple-darwin (default)
1.63-aarch64-apple-darwin
solana

installed targets for active toolchain
--------------------------------------

aarch64-apple-darwin
wasm32-unknown-unknown
wasm32-wasi

active toolchain
----------------

nightly-aarch64-apple-darwin (default)
rustc 1.78.0-nightly (a84bb95a1 2024-02-13)
```

## Docker

In order to run the tests, Docker must be installed and running.
Docker installation instructions: https://docs.docker.com/get-docker/

## Stylus

```
git clone https://github.com/OffchainLabs/stylus
cd stylus
git submodule update --init --recursive --checkout
make clean && make wasm-ci-build
```

Optional? For running tests
LLVM

```
brew install llvm
brew link llvm
```


An auditor's guide to Arbitrum Stylus

First steps to running Arbitrum Stylus

# Testing

## Prover: Stylus

The native interpreter for Stylus programs is located in `arbitrator/stylus`. The main Rust struct that handles execution is `NativeInstance` located in `arbitrator/stylus/src/native.rs`.

```rust arbitrator/stylus/src/native.rs
pub struct NativeInstance<D: DataReader, E: EvmApi<D>> {
 pub instance: Instance,
 pub store: Store,
 pub env: FunctionEnv<WasmEnv<D, E>>,
}
```

Generics:

- `DataReader` trait: Handles copying data from Go to Rust (in normal execution).
- `EvmApi` trait: Handles communication from the WASM program to the EVM environment.

Struct fields:

- `instance`: A wasmer execution runtime instance.
- `store`: All parameters that are modifiable by a WASM program.
- `env`: A wasmer function environment.

In native execution, when a user program is loaded from storage and called, a `NativeInstance` is created first. After creating the instance, the program can be run by calling `instance.run_main`.

`run_main` is executed with `args` (bytes slice), `config` (`version`, `max_depth`, `pricing`) and the `ink` amount available to the program.

After con

```rust https://github.com/OffchainLabs/stylus/blob/5dd3050506d4dd12d5c7bdc7c42f7f26ddf62c25/arbitrator/stylus/src/run.rs#L67-L123
impl<D: DataReader, E: EvmApi<D>> RunProgram for NativeInstance<D, E> {
 fn run_main(&mut self, args: &[u8], config: StylusConfig, ink: u64) -> Result<UserOutcome> {
 use UserOutcome::*;

 // Configure global variables.
 self.set_ink(ink);
 self.set_stack(config.max_depth);

 // ...

 // Run main.
 let status = match main.call(store, args.len() as u32) {
 // ...
 };

 // ...

 // Return result.
 let outs = env.outs.clone();
 Ok(match status {
 0 => UserOutcome::Success(outs),
 _ => UserOutcome::Revert(outs),
 })
 }
}
```


# Nitro

```
brew link go@1.20
make build
make wasm-ci-build
```

- Builds `brotli` (`cmake`, `cc`)
- Builds `jit` (`cargo`)
- Compiles `contracts` (`yarn`, `forge`, `solc`)
- Builds `nitro` (`go`)

The `make all` command in Nitro's Makefile triggers a sequence of build and test processes. Specifically, it executes the following high-level tasks:

1. **Build Executables and Components (`build`)**:

   - This is a complex step involving multiple executables and components. The rule targets several binaries including `nitro`, `deploy`, `relay`, `daserver`, `datool`, `seq-coordinator-invalidate`, `nitro-val`, and `seq-coordinator-manager`. These are all built from their respective Go source files (`$(go_source)`) located in various directories (`$(repo_dirs)`). It is likely that Go’s cross-compilation is leveraged for building specific architectures. This step utilizes conditional linking flags (`$(GOLANG_PARAMS)`) potentially defined by the environment to embed versioning or other metadata into the binaries.

2. **Set Up the Replay Environment (`build-replay-env`)**:

   - Constructs the necessary environment for replaying blockchain transactions or similar events. This step compiles a WebAssembly binary (`$(replay_wasm)`) using Go, targeting the JavaScript/WebAssembly architecture. Additional components included are various `.wasm` libraries and a compressed machine representation (`machine.wavm.br`). These components are likely used for simulating or analyzing blockchain behavior in a controlled environment.

3. **Generate Proof Tests (`test-gen-proofs`)**:
   - Generates proofs based on test cases written in WebAssembly text format (`.wat`) and Rust (`.rs`). This step transforms test cases into JSON formatted proof outputs that likely represent transaction validations or other proof verifications crucial for blockchain operations. This utilizes the prover executable (`$(arbitrator_prover_bin)`) to handle the transformation and proof generation.

Each of these primary tasks has detailed dependencies which are handled by other rules in the Makefile:

- **Dependency Management**:
  - Uses variables like `$(DEP_PREDICATE)` and `$(ORDER_ONLY_PREDICATE)` to manage dependencies especially in environments where Docker might affect file timestamps. The conditional setting of these variables controls whether dependencies are considered as order-only (ignoring timestamp changes).
- **Dynamic Linking Flags**:

  - Conditional rules add flags to `GOLANG_LDFLAGS` based on environment variables, affecting how Go binaries are linked during the build process. This could include embedding the build version, date, and whether the source code has been modified.

- **Auxiliary Build Processes**:

  - Other targets in the Makefile handle building WebAssembly libraries, managing Rust dependencies, formatting code, and running linters. These support the main build and testing processes.

- **Environment and Configuration**:
  - Various environment variables (like `WASI_SYSROOT`) and configuration settings influence how binaries and libraries are built, particularly for targeting different platforms like WebAssembly.

Finally, after completing these primary tasks (`all` target), a file named `.make/all` is touched to signify that the `all` target has successfully completed, serving as a marker for dependency management in future builds.

Overall, the `make all` command coordinates building the software, setting up necessary environments for transaction replay, and generating test proofs crucial for ensuring the correctness and reliability of blockchain-related operations managed by this software.

# Testing

## Arbitrator



- [What is shared sequencing?](#what-is-shared-sequencing)
  - [What is a rollup?](#what-is-a-rollup)
  - [What is the sequencer's role?](#what-is-the-sequencers-role)
  - [Why should we care about decentralizing the sequencer?](#why-should-we-care-about-decentralizing-the-sequencer)
- [Overview of the shared sequencer stack](#overview-of-the-shared-sequencer-stack)
  - [The sequencing layer](#the-sequencing-layer)
    - [A rollup agnostic super block](#a-rollup-agnostic-super-block)
    - [Lazy sequencing](#lazy-sequencing)
    - [Atomic composability](#atomic-composability)
  - [Consensus algorithm](#consensus-algorithm)
  - [Based rollups](#based-rollups)
  - [Proposer builder separation](#proposer-builder-separation)
  - [Data Availability](#data-availability)
  - [Encryption](#encryption)
- [Current state of shared sequencing](#current-state-of-shared-sequencing)
  - [Overview of different platforms](#overview-of-different-platforms)
  - [Rollup alignment](#rollup-alignment)
- [Research questions and outlooks](#research-questions-and-outlooks)
- [Conclusion](#conclusion)

# What is shared sequencing?

## What is a rollup?

A rollup chain—a layer 2 blockchain—is a blockchain that builds on top of another host blockchain—the layer 1 blockchain. It can be characterized by a few key points:

1. Builds on top of L1.
2. Inherits L1 security: Objective finality (fraud proofs or validity proofs).
3. Liveness guarantees from L1: L1 chain is unlikely to go offline.
4. Data availability guaranteed through L1: Transactions are posted as calldata or blobs.
5. Cheaper due to transaction compression, off-chain execution, and small state commits.

The L2 chain inherits the L1 chain's finality guarantees. Once a fraud proof window has passed or a validity proof has been included in a finalized L1 block, it is automatically finalized as seen by the L2. A double spending attack would require an L1 chain block reorganization.

The L2 chain also benefits from the host chain's decentralized validator set and economic security in terms of liveness. The L1 chain is unlikely to go offline and censor transactions. In principle, the rollup should be able to continue advancing its state and produce blocks as long as the L1 chain is online.

The layer 2 blockchain will likely run a layer 1 node in parallel. Since all the relevant layer 2 transaction data is available when syncing the layer 1 node—either through L1 calldata or EIP-4844 data blobs—the state of the layer 2 blockchain can be recomputed entirely by only relying on data from the host blockchain.

Rollups benefit from cheaper transaction costs. This is because layer 2 transaction data can be compressed and decompressed off-chain. Also, costly updates to the state database and execution do not happen on the more expensive layer 1 chain. Only every N block/state commits are required to be stored in the host chain's rollup contract.

A big challenge that most rollups face today is meeting the demand for faster finality than L1 for improved user experience. This forces the rollup to use a centralized and trusted sequencer.

## What is the sequencer's role?

When a user sends a layer 2 transaction, it is first picked up by the sequencer. The sequencer's job is to commit to a transaction ordering such that the new rollup state can be determined reliably. Once the ordering is set, all other node operators can compute the rollup's new state by applying the deterministic state transition function iteratively producing layer 2 blocks.

![Arbitrum's transaction lifecycle](../../public/data/blog/2023/arbitrum/arbitrum-nitro-whitepaper-transaction.png)

1.  Sequencer receives multiple user transactions
2.  Sequencer orders these
3.  Sequencer sends out an ordering promise (feed)
4.  Batched and compressed transactions are committed to L1 chain
5.  The L2 transactions are executed off-chain
6.  The new L2 blocks are confirmed to the L1 chain

The new state can be computed by running the Nitro Geth fork which also fetches the transaction data from the layer 1 blockchain. The transaction data itself does not necessarily need to be committed to persistent state. It is often only included as transaction calldata to the sequencers ordering commitment such that layer 1 operators are able to fetch and process the transactions. An alternative that has been made possible recently through EIP-4844 is to use data blobs for the transaction data availability.

While fraud proving an invalid block is less permissioned, the sequencer is arguably the most centralized component of today's layer 2 rollups.

The reason that the shared sequencer often is a centralized component today is that it is quite an engineering feat to implement. All other rollup components work deterministic and are clear to compute, whereas decentralizing the sequencer requires an additional consensus algorithm or auctioning mechanism. Along with this come a plethora of fairness, economic security and decentralized coordination questions and concerns. Similar to the advantages of being able to produce the block on a layer 1 blockchain, being able to determine the transaction ordering comes with the ability of extracting user value and transaction censorship.

## Why should we care about decentralizing the sequencer?

Building a shared sequencer that is fast, incorruptible and decentralized might seem like a **big engineering undertaking** that probably will come with a slightly **worse user experience**, **additional security risks** and a **loss in autonomy and fees for rollups**. _Why would we even want and care for decentralizing the sequencer?_

As with many blockchain components, a **central point of failure** is not desirable. The goal is to build censorship resistant and resilient infrastructure that cannot be corrupted in the moment when it counts. Having a centralized component inevitably means that a party with enough influence might be able to corrupt the component if the desire is high enough. This can in the form of a government decree that aims to censor certain users and protocols or by any actor with a shared interest. **Censorship and inclusion delays** can even come from the rollup's sequencer themselves. Further, an accidental server crash or data breach can occur leading to protocol **liveness** issues. Or worse, a sequencer might not fulfill its promise to include pre-committed transactions opening up the possibility of **double spend attacks**.

Currently, most centralized sequencers handle incoming user transactions via a private transaction mem-pool on a first come first serve basis. Having complete control over the sequencer also means that there is a monopoly on inclusion and ordering pricing. In principle, the sequencer stands to benefit from performing MEV (front and back-running, delaying or including its own transactions) or from selling the block building rights.

In summary, the following reasons highlight why we would want to move away from a centralized sequencer:

- Censorship resistance
- Robustness: Liveness
- Trust requirements
- Block building rights for all

If a sequencer is decentralized, there is no need for it to only server one rollup. A decentralized sequencing protocol might as well act as a shared sequencing abstraction layer that multiple rollups can plug into. This opens up the door to the possibility of atomic composability between rollups. Outsourcing the sequencer role for rollups to a shared sequencer service can come with the added benefits of:

- Decentralized sequencing
- Outsourced development cost
- Higher code security guarantees
- Atomic composability
- Batch posting cost amortization

Further, some shared sequencer services want to provide even more value, such as:

- Pre-execution privacy (encrypted mem-pool)
- Subsidized transactions & MEV revenue share
- Block builder auctions
- Reduced costs: Integration with Data Availability layer
- Guaranteed pre-commits
- Restaking ability

It is unclear whether most rollups will be interested in sharing a sequencer. As block building rights can be auctioned off at high prices and can lead to bad user experience, most bigger rollup chains will likely employ their own solutions and either capture and redistribute or use a fair ordering mechanism. Decentralizing the sequencer is currently part of Arbitrum's and Optimism's roadmap. Smaller blockchains with less engineering manpower will be happy to plug in a modular component that offers a decentralized sequencing solution with some added benefit.

# Overview of the shared sequencer stack

## The sequencing layer

When talking about integrating a shared/decentralized sequencer into a rollup protocol the idea is to abstract and outsource the entire sequencing process into a "sequencing layer".

![Shared sequencing layer](shared-sequencing-layer.svg)

1.  Multiple transactions from multiple rollups are processed by the sequencing layer
2.  The sequencing layer produces a "super block" by some mechanism
3.  The individual transactions are processed by the respective rollup chains

A _shared sequencer_ can be shared by multiple rollups. Once the infrastructure for a decentralized sequencer has been built it can, at least in theory, easily be plugged into other rollups as well.

### A rollup agnostic super block

A shared sequencer can produce a block containing transactions for multiple rollups. This is sometimes referred to as a "super block". A super block is technically not a block, but more of a list of transactions, since the transactions are not actually executed in the sequencing layer. In order to abstract the sequencing layer, it has to be decoupled from the execution layer. If a shared sequencer should be able to handle the ordering of transactions from any kind of rollup, then it inevitably must be agnostic to the rollup's executing virtual machine.

### Lazy sequencing

This also has the added benefit that the sequencing layer now can solely focus on one thing—the sequencing. Any sequencing mechanism that is dependent on the execution machine will suffer from potential Denial-of-service attack vectors. This is because the sequencers now must also be able to execute and produce blocks from various different rollups requiring running multiple different blockchain node programs in parallel.

### Atomic composability

A desirable property for super blocks is **atomic intra-rollup composability**. For example, a bridging transaction typically involves burning tokens on the source chain and minting them on the target chain. If a shared sequencer has the ability to atomically include transactions from various rollups, then it is also possible to include both a burn and a mint transaction atomically greatly enhancing the bridging experience.

Unfortunately, atomic inclusion does not guarantee atomic execution. This is because of the desired requirement of decoupling the sequencing from the execution layer. A shared sequencer can guarantee the inclusion of both transactions in their respective chains, however it cannot guarantee that these transactions will not fail.

Previously valid transactions can revert upon actual execution due to state changes in the blockchain. A user might have transferred the tokens out of their wallet or simply increased their account's nonce in the meantime. It would be a serious issue if the burn transaction failed, but the mint transaction succeeded.

## Consensus algorithm

Decentralizing the sequencer comes with the added challenge of reaching consensus in an adversarial setting. A set of distributed nodes needs to be able to agree on the next set of transactions in the presence of faulty and malicious nodes. This is called byzantine fault tolerance (BFT) and remains a core problem to solve for layer one blockchains.

The previous transaction lifecycle diagram makes it clear that our newly computed state is dependent on the ordered set of transaction inputs. Given these inputs, the rollup's state transition function will deterministically produce L2 blocks and other nodes will always arrive at the same L2 state root. This is also largely much how L1 blockchains work today. Given a list of ordered transactions, a L1 block is executed deterministically to arrive at a new state root.

The only non-deterministic part of a blockchain's state machine is the list of transactions that make up a block. The challenge lies in coordinating who gets to elect the new block.

## Based rollups

With all the additional complications that decentralizing the sequencer brings forth, is there no simpler way to reach consensus? There is.. A _based rollup_ simply uses the host chain's consensus mechanism to determine the rollup chain's transaction ordering. This can be achieved by allowing anyone to propose and submit a new block in the rollup's sequencing smart contract. This way, once the host chain's blocks are finalized, a transaction ordering will be determined.

_Why would we still want to consider alternative solutions to based rollups?_

The transaction confirmation speed of based rollups will always be limited to the host chain's confirmation speed. A centralized sequencer can give out instant pre-commitment confirmations of the transaction ordering, because it is the only leader and it knows it can fulfill the promise. Although this is not implemented by most rollups with a centralized sequencer, these pre-commitments could be accompanied by a verifiable signature and a slashing mechanism in the case that the sequencer breaks its promise. This makes for a great user experience as the confirmation speed is increased at the expense of decentralization.

_Why should we even build on top of an L1 at all?_

Using a host chain as a base settlement layer can still provide benefits. By leveraging the host chain's execution layer, a rollup's entire fraud proving system can be secured or validity proofs can be verified immediately. Further mechanisms such as slashing can be integrated and benefit from the embedded environment's economic security. Data availability and liveness are still strong arguments for building on top of a well-established layer one chain, although this might change if another consensus mechanism is implemented and data availability services are integrated.

## Proposer builder separation

As the challenges of decentralizing the sequencer are similar to those of the
_Why should we care about fair builder markets?_

When aiming to decentralize the sequencer, we face similar consensus problems as with a layer one blockchain. This is unless we use the host blockchain itself to determine a transaction ordering

## Data Availability

## Encryption

# Current state of shared sequencing

## Overview of different platforms

## Rollup alignment

# Research questions and outlooks

# Conclusion


Shared Sequencing


- [Intro](#intro)

# Intro

![alt text](0xsettler-flow-1.png)


0x Protocol Settler bug


- [Intro](#intro)
- [Overview](#overview)
- [The sequencer](#the-sequencer)
- [Before the malicious transaction](#before-the-malicious-transaction)

# Intro

```mermaid
flowchart TD;
    A[User Transaction] -->|Submits to| B[Arbitrum Network];
    B --> C{Sequencer Active?};
    C -- Yes --> D[Sequencer];
    D --> E{Processed Within Timeframe?};
    E -- Yes --> F[Included in Next Layer-2 Block];
    E -- No --> G[Delayed Inbox];
    C -- No --> G;
    G --> F;
    F --> H[Finalized on Ethereum Mainnet];

    classDef default fill:#f9f,stroke:#333,stroke-width:2px;
    classDef decision fill:#f96,stroke:#333,stroke-width:2px;
    class C,D,E decision;

```

Arbitrum is an optimistic rollup on Ethereum. An optimistic rollup is a layer 2 scaling solution where transactions are posted in batches to a base layer—Ethereum. Ignoring the problem of decentralized sequencing—Rollup solutions build on some of Ethereum's safety guarantees through its consensus mechanism, data availability and finality. In an optimistic scenario where every node participant is honest the optimistic rollup protocol requires minimal work and intervention, since every proposed rollup block can simply be accepted as canonical after passing its confirmation delay. However, in the case that a malicious actor is involved, the protocol must be prepared to efficiently determine the correct state all the while protecting itself from DoS attacks and finally punishing bad actors and reward the good. We will inspect this fraud proof mechanism in detail while looking at the source code.

So what happens exactly when, for example, Eve proposes a block that ends with her balance having increased by 100 Ether coming out of thin air? How does Arbitrum Nitro catch such an act and punish Eve?

It's clear that any deviation resulting in the processing of transaction outcomes should be caught. Since computing the transaction results happens in [Arbitrum Nitro](https://github.com/OffchainLabs/nitro)—which builds on top of [Go-Ethereum](https://github.com/ethereum/go-ethereum)—another approach is to simply punish any deviation from running the Nitro node client. One problem to address for this approach is that the exact instructions being executed in the compiled binaries will vary depending on the target architectures (x86, ARM, ...). For this reason we need another layer of abstraction that will produce consistent outcomes independent of the machine. This is where WebAssembly (WASM) comes into play.

[rec][./recommendations.md]

I always wanted to write a book with [markdown][mkdnlink].

[mkdnlink]: http://daringfireball.net/projects/markdown

# Overview

Github repositories:

Deployed to Ethereum:

| Description                                                | Nitro                                                              | Stylus                                                               |
| ---------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- |
|                                                            | [nitro](https://github.com/OffchainLabs/nitro)                     | [stylus](https://github.com/OffchainLabs/stylus)                     |
| Core rollup contracts in _Solidity_ deployed to _Ethereum_ | [nitro-contracts](https://github.com/OffchainLabs/nitro-contracts) | [stylus-contracts](https://github.com/OffchainLabs/stylus-contracts) |

- Nitro's core rollup contracts (Solidity)
- [token-bridge-contracts](https://github.com/OffchainLabs/token-bridge-contracts): ERC20 token bridge contracts (Solidity)

Run by validators:

- (fork of ):

# The sequencer

The sequencer is the currently centralized entity that determines an order for incoming L2 transactions into L2 blocks. This order is committed to the parent chain (Ethereum) to ensure data availability and finality of the ordering. From here on, the state transition of the rollup is determined deterministically. This means that anyone can process and simulate the sequencer transactions locally to calculate the future state of the rollup without waiting the full 7 day finality period for proposed L2 blocks. This also means that it's not required for Arbitrum nodes to communicate with each other, since the sequencer is the only entity that is able to influence the L2 end state.

Questions:

- How even include a malicious transaction? The node doesn't provide apis for malicious actions, and invalid transactions will be discarded.
- What parts of the protocol are involved?
- How does fraud proving work?

# Before the malicious transaction

In this section we'll briefly describe the protocol in its optimistic workings—when all transactions are valid.

Alice sends a signed transaction to the sequencer that will end up paying Bob 1 Ether. Currently, there is only a single sequencer controlled by Arbitrum (active work is being put in to change this in the future with systems such as [Espresso Systems](https://twitter.com/sgoldfed/status/1740109895494693334) working on a shared, decentralized sequencer).

TODO: sequencing mechanics in ArbOS and sequence posting + feed.

Once the sequence is committed with finality and readily available to everyone, the future state of Arbitrum's rollup is known, since it's a deterministic process from here on. Arbitrum validators can create new attestations to the new rollup block state. This is done in

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X


A deep dive into Arbitrum's fraud proving system

An auditors guide to Arbitrum Stylus


- [Intro](#intro)
- [Overview](#overview)
- [The sequencer](#the-sequencer)
- [Before the malicious transaction](#before-the-malicious-transaction)

# Intro

Arbitrum is an optimistic rollup on Ethereum. An optimistic rollup is a layer 2 scaling solution where transactions are posted in batches to a base layer—Ethereum. Ignoring the problem of decentralized sequencing—Rollup solutions build on some of Ethereum's safety guarantees through its consensus mechanism, data availability and finality. In an optimistic scenario where every node participant is honest the optimistic rollup protocol requires minimal work and intervention, since every proposed rollup block can simply be accepted as canonical after passing its confirmation delay. However, in the case that a malicious actor is involved, the protocol must be prepared to efficiently determine the correct state all the while protecting itself from DoS attacks and finally punishing bad actors and reward the good. We will inspect this fraud proof mechanism in detail while looking at the source code.

So what happens exactly when, for example, Eve proposes a block that ends with her balance having increased by 100 Ether coming out of thin air? How does Arbitrum Nitro catch such an act and punish Eve?

It's clear that any deviation resulting in the processing of transaction outcomes should be caught. Since computing the transaction results happens in [Arbitrum Nitro](https://github.com/OffchainLabs/nitro)—which builds on top of [Go-Ethereum](https://github.com/ethereum/go-ethereum)—another approach is to simply punish any deviation from running the Nitro node client. One problem to address for this approach is that the exact instructions being executed in the compiled binaries will vary depending on the target architectures (x86, ARM, ...). For this reason we need another layer of abstraction that will produce consistent outcomes independent of the machine. This is where WebAssembly (WASM) comes into play.

[rec][./recommendations.md]

I always wanted to write a book with [markdown][mkdnlink].

[mkdnlink]: http://daringfireball.net/projects/markdown

# Overview

Github repositories:

Deployed to Ethereum:

| Description                                                | Nitro                                                              | Stylus                                                               |
| ---------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- |
|                                                            | [nitro](https://github.com/OffchainLabs/nitro)                     | [stylus](https://github.com/OffchainLabs/stylus)                     |
| Core rollup contracts in _Solidity_ deployed to _Ethereum_ | [nitro-contracts](https://github.com/OffchainLabs/nitro-contracts) | [stylus-contracts](https://github.com/OffchainLabs/stylus-contracts) |

- Nitro's core rollup contracts (Solidity)
- [token-bridge-contracts](https://github.com/OffchainLabs/token-bridge-contracts): ERC20 token bridge contracts (Solidity)

Run by validators:

- (fork of ):

# The sequencer

The sequencer is the currently centralized entity that determines an order for incoming L2 transactions into L2 blocks. This order is committed to the parent chain (Ethereum) to ensure data availability and finality of the ordering. From here on, the state transition of the rollup is determined deterministically. This means that anyone can process and simulate the sequencer transactions locally to calculate the future state of the rollup without waiting the full 7 day finality period for proposed L2 blocks. This also means that it's not required for Arbitrum nodes to communicate with each other, since the sequencer is the only entity that is able to influence the L2 end state.

Questions:

- How even include a malicious transaction? The node doesn't provide apis for malicious actions, and invalid transactions will be discarded.
- What parts of the protocol are involved?
- How does fraud proving work?

# Before the malicious transaction

In this section we'll briefly describe the protocol in its optimistic workings—when all transactions are valid.

Alice sends a signed transaction to the sequencer that will end up paying Bob 1 Ether. Currently, there is only a single sequencer controlled by Arbitrum (active work is being put in to change this in the future with systems such as [Espresso Systems](https://twitter.com/sgoldfed/status/1740109895494693334) working on a shared, decentralized sequencer).

TODO: sequencing mechanics in ArbOS and sequence posting + feed.

Once the sequence is committed with finality and readily available to everyone, the future state of Arbitrum's rollup is known, since it's a deterministic process from here on. Arbitrum validators can create new attestations to the new rollup block state. This is done in

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X


What happens when proving fraud in Arbitrum


- [Intro](#intro)
- [General Token Bridge Design](#general-token-bridge-design)

# Intro

In XX 2023 we started a review of the Fuel protocol. In particular I was to look at the message portal and the token bridge. For the most part, cross-chain messaging protocols work very similar. The general procedure is that there is a singleton smart contract on the sending chain (Ethereum) dedicated to emitting arbitrary messages. Protocol validators listen to these messages and then broadcasted them to the receiving chain.

The message can be relayed through a smart contract on the receiving chain, but often is also relayed by a very specific address (e.g. the zero address on Polygon) or an aliased address (e.g. Arbitrum, Optimism add a fixed offset to any message sender's address).

As transmitting messages is often left very general, the specifics of a cross-chain token bridge require additional logic and validation.

In the case of Fuel

# General Token Bridge Design

```mermaid
flowchart LR;
    Validators([Validators])
    Validators -.->|relay msg| PortalReceiver;
    subgraph Fuel
      PortalReceiver -.->|call| receiver;
    end

    User([User])
    User -.->|send tx| PortalSender;
    subgraph Ethereum
      PortalSender -.->|emit msg| PortalSender;
    end
```

Ignoring other transaction message values such as `gas`, `gasLimit`, `value` and nonce validation.

```mermaid
classDiagram
    class Message {
        address sender
        address receiver
        bytes data
    }
```

A token bridge requires extra validation logic to be handled by a `TokenBridgeSender` and a `TokenBridgeReceiver` contract.

```mermaid
flowchart LR;
    Validators([Validators])
    Validators -.->|relay msg| PortalReceiver;
    subgraph Fuel
      PortalReceiver -->|call| TokenBridgeReceiver;
      TokenBridgeReceiver -.->|transfer token| receiver;
    end

    User([User])
    User -.->|send tx| TokenBridgeSender;
    subgraph Ethereum
      TokenBridgeSender -->|call| PortalSender;
      PortalSender -.->|emit msg| PortalSender;
    end
```

```mermaid
classDiagram
    class Message {
        address sender : TokenBridgeSender
        address receiver :  TokenBridgeReceiver
        bytes data : enc(user, receiver, token, value)
    }
```


Fuel message portal

The Dos and Don'ts of testing

Test Your Tests!

UniswapV3

Jeffrey Hoffstein

An Introduction to Mathematical Cryptography

A Guide on Performing Arithmetic Checks in the EVM

What makes a good and a bad test

Test Your Tests

[Clones with immutable args](https://github.com/wighawag/clones-with-immutable-args) (CWIA) aim to save gas by avoiding storage reads and writes. 


Clones - and proxies alike - usually contain a initializer function to set parameters specific to the clone. This is due to the nature of contracts that function as proxies. Typically they use standardized and optimized implementations that contain minimal logic and forward all calls to an contract that handles the implementation logic. 

Immutable variables are useful, because instead of writing these variables into the contract's storage space, they are directly included in the contract's runtime bytecode. They work in a similar way as variables that are declared to be constant, but they are evaluated and inserted during contract creation - in the constructor.

Since solidity does not allow for dynamic type immutable variables, it's not that straightforward to write a clone/proxy contract that will just take in a immutable string of bytes to be easily accessed in the implementation contract.

Another reason for the slow adoption of clones that use immutable args is that they are often heavily optimized. [EIP-1167](https://eips.ethereum.org/EIPS/eip-1167) formalizes the specs for minimal proxy clones. 

```ERC1167Clone.evm
0x363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3
```

Because EIP-1667 clones can easily be identified by checking their bytecode, services such as [etherscan](https://etherscan.io) are able to detect these. 
If the contract were to include immutable args however, this would require more rules in order to identify such contracts, because the immutable args must be included in the contract's runtime code.




# Clones with immutable args - via `CALL`

To illustrate some of the ideas behind clones with immutable args, we 
can think of a minimal clone contract that takes in an immutable arg as a parameter.

```CloneWithImmutableArgsVer1.sol
contract CloneWithImmutableArgsVer1 {
 address private immutable logic;
 uint256 public immutable immutableArg0;

 constructor(address logic_, uint256 immutableArg0_) payable {
 logic = logic_;
 immutableArg0 = immutableArg0_;
 }

 fallback() external payable {
 address logic_ = logic;

 assembly {
 calldatacopy(0, 0, calldatasize())

 let success := delegatecall(gas(), logic_, 0, calldatasize(), 0, 0)

 returndatacopy(0, 0, returndatasize())

 if success {
 return(0, returndatasize())
 }

 revert(0, returndatasize())
 }
 }
}
```

This contract takes in a `address logic_` to which all calls are delegated to and a `uint256 immutableArg0_` that is accessible to the clone as a public function.



There is still one problem, however. We usually will want to access `immutableArg0` from within the logic contract. Since the logic contract does not know about `immutableArg0` - let alone the clone contract itself - it is not directly available to the implementation.
Although, since we know that we will be calling the logic contract via `delegatecall`, we can call back into the clone contract via `CloneWithImmutableArgsVer1(address(this)).immutableArg0()` to access the variable.

> Essentially this method will result in an additional `call` operation and a `codecopy` operation once the context is set back to the clone contract. `staticcall` could also be used instead to ensure that no persistent changes are being made.

Another problem is that the current contract only works for one fixed 32 bytes word. 
Ideally, we would be able to store and access arbitrary byte strings.
A way to get around this is shown in the next possible method that uses `extcodecopy`.


# Clones with immutable args - via `EXTCODECOPY`

Instead of calling back into the clone contract, we could also directly access the bytes via `extcodecopy` while remaining in the context of the implementation contract.
This example will work with immutable args that can be bytes of arbitrary lengths.

```ClonesWithImmutableArgsVer2.sol
contract CloneBase {
 fallback() external payable {
 address logic = ImmutableArgsVer2Lib.getLogicAddress();

 assembly {
 calldatacopy(0, 0, calldatasize())

 let success := delegatecall(gas(), logic, 0, calldatasize(), 0, 0)

 returndatacopy(0, 0, returndatasize())

 if success {
 return(0, returndatasize())
 }

 revert(0, returndatasize())
 }
 }
}

contract ClonesWithImmutableArgsVer2 {
 constructor(address logic, bytes memory immutableArgs) payable {
 bytes memory code = abi.encodePacked(
 type(CloneBase).runtimeCode,
 immutableArgs,
 uint16(immutableArgs.length),
 logic
 );

 assembly {
 return(add(code, 0x20), mload(code))
 }
 }
}
```

The delegatecall logic in the fallback function remains the same, except that we are now reading the address of the logic contract using a library function `ImmutableArgsVer2Lib.getLogicAddress()` - which we'll get into in a bit. 
 
Out goal is to append additional data - the immutable args - to the contract bytecode so that we can cheaply access these later. 
`ClonesWithImmutableArgsVer2` acts as a kind of "wrapper" contract that returns the code of the underlying contract - `CloneBase` - with additional data appended - the immutable args, the length of the immutable args and the logic contract. 

Since we're accessing `type(CloneBase).runtimeCode` we need to avoid any `immutable` keywords, because these would not be available in the runtime code. That's why we also append the `logic` address to the contract code to be able to access this in the fallback function of the clone.

We now need to write the functions that will make it possible to retrieve `address logic` and `bytes immutableArgs` from the contract code.

```ImmutableArgsVer2Lib.sol
 library ImmutableArgsVer2Lib {
 function getLogicAddress() internal returns (address logic) {
 assembly {
 // `address logic` is encoded into bytecode at last position.
 // Load 20 bytes (0x14) starting from end - 20 bytes.
 let offsetLogic := sub(codesize(), 0x14)
 // Store in scratch space in first slot at 12 bytes (0x0c = 32 - 20) offset.
 codecopy(0x0c, offsetLogic, 0x14)
 // Load first memory slot to retrieve the address.
 logic := mload(0)
 }
 }

 function getImmutableArgs() internal returns (bytes memory args) {
 assembly {
 // Clear dirty scratch space.
 mstore(0, 0)

 let codeSize := extcodesize(address())
 // The offset for the length of the args is stored
 // at `codeSize - 20 - 2` (20 bytes address + 2 bytes length)
 let argsLenOffset := sub(codeSize, 0x16)

 // Load length of immutable args from contract bytecode.
 extcodecopy(address(), 0x1e, argsLenOffset, 0x02)

 let argsLen := mload(0)
 let argsOffset := sub(argsLenOffset, argsLen)

 // Place `args` at free memory position.
 args := mload(0x40)
 // Store length of `args` bytes-array.
 mstore(args, argsLen)

 // Copy immutable args to `args` memory offset.
 extcodecopy(address(), add(args, 0x20), argsOffset, argsLen)

 // Advance the `memPtr` by `argsLen + 0x20`,
 // rounded up to the next multiple of 32.
 mstore(0x40, shl(5, shr(5, add(add(args, argsLen), 0x3f))))
 }
 }
}
```

Notice how `getLogicAddress()` uses `codecopy` and how `getImmutableArgs()` uses `extcodecopy`.
This is because `getLogicAddress()` will be executed in the context of the clone - meaning the address is stored in the current runtime code - whereas `getImmutableArgs()` will be executed in the context of the logic contract, which is unable to access the immutable args stored in the runtime code and thus must use `extcodecopy`.

# Clones with immutable args - via `CALLDATA`

The [original clones with immutable args](https://github.com/wighawag/clones-with-immutable-args) uses another trick. The immutable args are directly appended to the calldata of the delegatecall in the clone's fallback function.

`CloneWithImmutableArgsVer3`'s constructor code remains the same as `CloneWithImmutableArgsVer2`.

```CloneWithImmutableArgsVer3.sol
contract CloneWithImmutableArgsVer3 {
 constructor(address logic, bytes memory immutableArgs) payable {
 bytes memory code = abi.encodePacked(
 type(CloneBaseVer3).runtimeCode,
 immutableArgs,
 uint16(immutableArgs.length),
 logic
 );

 assembly {
 return(add(code, 0x20), mload(code))
 }
 }
}
```

Now when we make the delegatecall, we need to concatenate the the following data in memory: calldata + immutable args + uint16 length of immutable args. Retrieving and copying the immutable args works exactly the same as with the previous version, except that, since we're in the clone's context, we can use `codesize` and `codecopy` instead of `extcodesize` and `extcodecopy`.

```CloneWithImmutableArgsVer3.sol
contract CloneBaseVer3 {
 fallback() external payable {
 address logic = ImmutableArgsVer2Lib.getLogicAddress();

 assembly {
 // Clear dirty scratch space.
 mstore(0, 0)

 // Get length and offset of immutable args.
 let argsLenOffset := sub(codesize(), 0x16)
 codecopy(0x1e, argsLenOffset, 0x02)

 let argsLen := mload(0)
 let argsOffset := sub(argsLenOffset, argsLen)

 calldatacopy(0, 0, calldatasize())

 // Copy immutable args to end of calldata in memory.
 codecopy(calldatasize(), argsOffset, argsLen)
 // Append the length of the immutable args to the end.
 mstore8(add(calldatasize(), argsLen), shr(8, argsLen))
 mstore8(add(add(calldatasize(), argsLen), 1), argsLen)

 let success := delegatecall(gas(), logic, 0, add(add(calldatasize(), argsLen), 2), 0, 0)

 returndatacopy(0, 0, returndatasize())

 if success {
 return(0, returndatasize())
 }

 revert(0, returndatasize()) 
 }
 }
}
```

Now the implementation contract will have direct access to the immutable args via calldata. This part is left out, because it works in pretty much the same way as retrieving immutable args from the contract code.

This method has the benefit that it doesn't need to make another external call or copy external code (since it uses `codecopy` instead). 
Accessing the immutable args via calldata is cheap and almost practically negligible - except for when this is run on rollups that commit calldata to the root chain (here calldata makes up for over 50% of the transaction cost). Yet, unlike before, where we only access the immutable args when needed, these are always appended to any function call - no matter if they are required or not.


# Tradeoffs and Gas Comparisons

The full code for all comparisons can be found here https://github.com/0xPhaze/clones-with-immutable-args-comparison (though method 1 and method 3 are swapped here).
The clone implementations are written in pure bytecode to better understand the limits.
The methods that use `codecopy` could however, still be further optimized to not use `codecopy` at all, but to loop over `push` opcodes that push the data directly onto the stack and store it in memory.

| | Relevant Opcodes | Notes |
|:--: | :--: | :--: 
| Method 1 | `call` + `codecopy` | Calls back into clone contract to retrieve immutable arg. |
| Method 2 | `extcodecopy` | Loads external code from clone contract. |
| Method 3 | `codecopy` + `calldataload` | Adds a gas overhead to EVERY function call |

I ran multiple tests and plotted the results to get a better feel for the behavior of the gas costs. Below is a comparison between method 2 and method 3. Method 1 was left out, as it behaved much like method 2, but slightly worse.

![gas-cost-comparison](/data/blog/2022/clones-with-immutable-args-comparison/gas-cost-comparison.png)

The plot shows the gas costs for reading x bytes from the immutable args from immutable args with varying lengths. In most cases, using method 3, i.e. reading args from calldata will be cheaper. Using `extcodecopy` (method 2) becomes cheaper after a certain amount of bytes (1.5k-2k).

The aforementioned gas overhead (for method 3) can be seen for the purple line - reading 0 bytes is the overhead added to any other call that does not need to read immutable bytes. Here, method 2 is cheaper and stays pretty much constant, while it increases linearly with the length of the stored immutable args for method 3 - when the args are appended to the calldata.

Gas Comparisons

Clones With Immutable Args

`abi.decode(data, (type))` can be used to decode abi-encoded bytes located in memory and calldata. Currently, it's only possible to assign dynamic types to memory. Decoding to calldata is not supported yet, however, this can still be achieved manually.

Say we wanted to send a NFT cross-chain. For this we have have to encode a message that could look like this.

```FxERC721Root.sol
bytes4 constant REGISTER_ERC721_IDS_SELECTOR = 
 bytes4(keccak256("registerERC721IdsWithChild(address,uint256[])"));

 function _registerERC721IdsWithChild(address to, uint256[] calldata ids) internal virtual {
 bytes memory message = abi.encodeWithSelector(REGISTER_ERC721_IDS_SELECTOR, to, ids); // highlight-line

 _sendMessageToChild(message);
 }
```

The child chain can receive the full message as `calldata`, run some security checks and then process it in another function.


```FxERC721Child.sol
 function processMessageFromRoot(
 uint256 stateId,
 address rootMessageSender,
 bytes calldata message // highlight-line
 ) external {
 if (msg.sender != fxChild) revert CallerNotFxChild();
 if (rootMessageSender == address(0) || rootMessageSender != s().fxRootTunnel) revert InvalidRootSender();

 _processMessageFromRoot(stateId, rootMessageSender, message);
 }
```

Solidity does not allow us to decode the ids as a `uint256[] calldata` array directly yet. I.e. the following 
```solidity
 (address to, uint256[] calldata ids) = abi.decode(message[4:], (address, uint256[]));
```
would fail with the message:
`"TypeError: Type uint256[] memory is not implicitly convertible to expected type uint256[] calldata."`

However, by declaring `uint256[] calldata ids;` and manually setting `ids.offset` and `ids.length` via assembly, we can manually decode the data.
For more on the abi encoding spec, read up on the [docs](https://docs.soliditylang.org/en/v0.8.17/abi-spec.html#argument-encoding).

```FxERC721Child.sol
 function _processMessageFromRoot(
 uint256,
 address,
 bytes calldata message
 ) internal virtual override {
 bytes4 selector = bytes4(message);

 if (selector != REGISTER_ERC721_IDS_SELECTOR) revert InvalidSelector();

 address to = address(uint160(uint256(bytes32(message[4:36]))));

 uint256[] calldata ids;
 // abi-decode `ids` directly in calldata.
 assembly {
 // Skip bytes4 selector + bytes32 encoded address
 // starting from message's offset in calldata
 // to get the relative offset of the uint256[] encoded array's size.
 let idsLenOffset := add(add(message.offset, 0x04), calldataload(add(message.offset, 0x24)))
 ids.length := calldataload(idsLenOffset)
 ids.offset := add(idsLenOffset, 0x20)
 }

 _registerIds(to, ids);
 }

 function _registerIds(address to, uint256[] calldata ids) internal virtual {
 for (uint256 i; i < ids.length; ++i) {
 _registerId(to, ids[i]);
 }
 }
```

Here's an example of a call to the function `processMessageFromRoot()`.

```sol
 child.processMessageFromRoot(
 1,
 address(this),
 abi.encodeWithSelector(REGISTER_ERC721_IDS_SELECTOR, address(0xbabe), 31.range(34))
 );
```

In this case, the calldata would look like this.

```sol
 [selector] 0x9a7c4b71 // processMessageFromRoot.selector
 [0x00] 0000000000000000000000000000000000000000000000000000000000000001 // stateId
 [0x20] 000000000000000000000000b4c79dab8f259c7aee6e5b2aa729821864227e84 // rootMessageSender
 [0x40] 0000000000000000000000000000000000000000000000000000000000000060 // message.length offset
 [0x60] 00000000000000000000000000000000000000000000000000000000000000c4 // message.length
 [0x80] 4d26d408000000000000000000000000000000000000000000000000000000000000babe00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000001f0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002100000000000000000000000000000000000000000000000000000000 // encoded message
```

> Note: Even though the message length is located at message[0x64:0x84] the offset (of message.length) is set to 0x60, since the selector is not counted.

Because the message is abi-encoded separately, the offsets in the encoded bytes are relative to the start of the message after the selector.

```sol
 [selector] 0x4d26d408 // REGISTER_ERC721_IDS_SELECTOR
 [0x00] 000000000000000000000000000000000000000000000000000000000000babe // address to
 [0x20] 0000000000000000000000000000000000000000000000000000000000000040 // ids.length relative offset
 [0x40] 0000000000000000000000000000000000000000000000000000000000000003 // ids.length
 [0x60] 000000000000000000000000000000000000000000000000000000000000001f // ids[0]
 [0x80] 0000000000000000000000000000000000000000000000000000000000000020 // ids[1]
 [0xa0] 0000000000000000000000000000000000000000000000000000000000000021 // ids[2]
 [0xc0] 00000000000000000000000000000000000000000000000000000000 // padded zeros
```

This means that, if we want to get the correct calldata offset for `ids.offset`, we need
to load the word located at 0x20 in the encoded message. In order to get the absolute position in the calldata, we thus need to add the offset of the message in the calldata to 0x24 - the 4 bytes selector from the message must be taken into account, since the message is embedded into the calldata as bytes.

```sol
 let idsOffsetRel := calldataload(add(message.offset, 0x24))
```

Now to get the absolute offset of `ids.length` we need to add the position of where the relative offset in the message starts: `message.offset + 0x04` - the starting location of the message + the encoded selector.

```sol
 let idsLenOffset := add(add(message.offset, 0x04), idsOffsetRel)
```

Now that we have the offset of the length, we just need to load it from the calldata. By looking at the encoding we can also see that we simply need to add one word (0x20) to find the start of the `uint256[]` data - `ids.offset`.

```sol
 ids.length := calldataload(idsLenOffset)
 ids.offset := add(idsLenOffset, 0x20)
```

## Why not just hardcode the offset?

We could also simply hardcode the values for `ids.length` and `ids.offset` after we have calculated them once. 

```sol
 ids.offset := 0xe8
 ids.length := calldataload(sub(ids.offset, 0x20))
```

This works as long as the function signature won't change (so that the offset of `message` doesn't change) and the calldata is encoded in a standard way.

We can create a non-standard encoding by adding useless filler data for example and we quickly see why the hardcoded version will not work anymore.

```sol
 address(child).call(
 hex"9a7c4b71" // processMessageFromRoot.selector
 hex"0000000000000000000000000000000000000000000000000000000000000001" // stateId
 hex"000000000000000000000000b4c79dab8f259c7aee6e5b2aa729821864227e84" // rootMessageSender
 hex"0000000000000000000000000000000000000000000000000000000000000080" // message.length offset
 hex"ccaaffeeccaaffeeccaaffeeccaaffeeccaaffeeccaaffeeccaaffeeccaaffee" // ??
 hex"00000000000000000000000000000000000000000000000000000000000000e4" // message.length
 hex"4d26d408" // REGISTER_ERC721_IDS_SELECTOR
 hex"000000000000000000000000000000000000000000000000000000000000babe" // address to
 hex"0000000000000000000000000000000000000000000000000000000000000060" // ids.length relative offset
 hex"ccaaffeeccaaffeeccaaffeeccaaffeeccaaffeeccaaffeeccaaffeeccaaffee" // ??
 hex"0000000000000000000000000000000000000000000000000000000000000003" // ids.length
 hex"000000000000000000000000000000000000000000000000000000000000001f" // ids[0]
 hex"0000000000000000000000000000000000000000000000000000000000000020" // ids[1]
 hex"0000000000000000000000000000000000000000000000000000000000000021" // ids[2]
 hex"00000000000000000000000000000000000000000000000000000000" // padded zeros
 );
```

Without hardcoding the offsets, reading the `uint256[] calldata` from the above encoding will still be possible.




# Gas Savings

Abi-decoding directly to calldata can avoid copying data to memory.
This saves us a few `mstore` and `mload` operations.
Below is a comparison of the gas savings for encoding a certain number of ids.


| #ids | Calldata | Memory | Difference |
| --- | --- | --- | ---- |
| 0 | 1125 |1552 | 427 |
| 1 | 2271 |2775 | 504 |
| 2 | 3197 |3781 | 584 |
| 3 | 4126 |4790 | 664 |
| 4 | 5050 |5794 | 744 |
| 5 | 5977 |6801 | 824 |
| 6 | 6904 |7809 | 905 |
| 7 | 7835 |8820 | 985 |
| 8 | 8760 |9825 | 1065 |
| 9 | 9694 |10839 | 1145 |


In this case, using calldata over memory can save us 427 gas + roughly an additional 80 gas per extra word.

ABI-Decoding Calldata


# Table of Contents

# Context

The audit was performed as a "non-extensive review".
This means that solely the code is reviewed as is
and no further tests have been prepared for this review.
Unit-tests are essential for ensuring correct behavior and calculations.

This audit is a review of the [Haki staking contracts](https://github.com/rekttdoteth/haki-staking-contract)
(private)
and was performed at commit
[77865daafe1311dd45ad29bb8087f55fdc660c54](https://github.com/rekttdoteth/haki-staking-contract/commit/77865daafe1311dd45ad29bb8087f55fdc660c54).

The given repository itself contains no tests.

**Focus:**

Gas optimizations (specifically storage accesses)
on `TheShrine.sol` (to be deployed on Ethereum) are highlighted, whereas they are largely ignored for `ShrineToken.sol` (to be deployed on Polygon).

Special attention was given to unauthorized access-control and exploitability. Logical errors were covered as best as possible,
although these require extensive unit-testing to cover appropriately.

# Overview

The client has designed contracts that allow for staking of ERC721 NFTs.
While the staking itself will be performed on Ethereum,
staking rewards are emitted as ERC20 tokens on Polygon.
The communication between the chains is done using Polygon's
[flexible portal contracts](https://github.com/fx-portal/contracts).
Staking on Ethereum is handled by
`TheShrine.sol` which is designed to be able to handle multiple ERC721 contracts.
`ShrineToken.sol` is an ERC20 token on Polygon that contains logic
to handle state updates from the root contract `TheShrine.sol`.
`SekiraVerifier.sol` acts as a simple "proxy" that allows counting owned and staked NFT balances for the _Sekira_ contract.

# Scope

The repository contains the following contracts

```ml
└── contracts
    ├── ERC20.sol
    ├── ExitPayloadReader.sol
    ├── FxBaseChildTunnel.sol
    ├── FxBaseRootTunnel.sol
    ├── Merkle.sol
    ├── MerklePatriciaProof.sol
    ├── RLPReader.sol
    ├── SekiraVerifier.sol
    ├── ShrineToken.sol
    └── TheShrine.sol
```

As a basis for the ERC20 contract, `ShrineToken.sol` uses Rari-Capital solmate's [ERC20 implementation](https://github.com/Rari-Capital/solmate/blob/main/src/tokens/ERC20.sol) `ERC20.sol`.
No noteworthy differences to the [latest commit](https://github.com/Rari-Capital/solmate/commit/25015a1d18e75921f8cb1bacd4beb9f364e788a9) exist.

Polygon's [flexible portal contracts](https://github.com/fx-portal/contracts)
are being used for message passing between Ethereum and Polygon.
No noteworthy differences to the [latest commit](https://github.com/fx-portal/contracts/commit/baed24d22178201bca33140c303e0925661ec0ac) exist.

These external contracts are out of scope.
The focus of the review is narrowed down to the following contracts.

```ml
└── contracts
    ├── SekiraVerifier.sol
    ├── ShrineToken.sol
    └── TheShrine.sol
```

# Summary

No critical errors were identified.

The contracts could benefit from simplification
to reduce complexity, computation and storage access.
Furthermore, although not explicitly detailed,
repetition of contract logic/functions can be avoided.
This would also help validate logic and improve readability.
It is further noted that the use of custom errors vs. require-statements could chosen consistently and docstring comments could be standardized.

# Audit Findings Classifications

# Medium Findings

## :zap: [ShrineToken.sol] State-Desync Possible

Currently `ShrineToken.sol` gets relative balance updates from the root contract `TheShrine.sol` on Ethereum.
A complete synchronization between the two chains is not guaranteed and incoming tokens are not validated to be uniquely counted in
`userInfo.stakedBalance` and `userInfo.stakedIds`.

Setting the child contract `ShrineToken.sol` to be paused
would lead to failed transactions and a state-desync when `_processMessageFromRoot` is called.
This would mean that, for example, unstaking on Ethereum L1
would not be updated on L2.

The results of this effect, however, are minimized due to the way
rewards are being calculated.
When claiming rewards, the ids found in `userInfo.stakedIds`
are iterated over and the reward is calculated based on the
`record` found for each individual id. The individual id is immediately "marked" as claimed by updating `stakeRecord.lastClaimed`.

This does, however, still mean that it could be possible for a user to claim
rewards for an NFT no longer owned, even if it is currently being
staked by someone else. Additionally, this could lead to a higher `multipleStakedBoostThreshold`.

**Mitigation:**
New token ids being registered in the `ShrineToken` contract could
check whether they are currently still attributed to someone else
in the system. If they are, they should be removed from that user's
balance/stake.

## :zap: [TheShrine.sol] Hardcoded Testnet Address

```TheShrine.sol
    function balanceOf(address owner) external view returns (uint256) {
        address hakiContract = 0xd053b4FdbC3470E6aAF9f65ED13AFDaA5af0d7E5; //highlight-line
        return
            addressToContractStakedIds[owner][hakiContract].length +
            ERC721(hakiContract).balanceOf(owner);
    }
```

`TheShrine.sol` contains a hardcoded `address hakiContract` which does not correspond to `address hakiERC721` of the constructor. This address currently only contains code on test-nets.

**Mitigation:**
Update address pointing to the correct ERC721 contract on Ethereum or declare a variable that is set
by the constructor parameter.

**Update:**
The client has responded that this address will be updated accordingly.

# Minor Findings

## :zap: [FxBaseRootTunnel.sol] Unprotected Function

_Note: Originally declared as out of scope._

```FxBaseRootTunnel.sol
    function setFxChildTunnel(address _fxChildTunnel) public virtual { //highlight-line
        require(fxChildTunnel == address(0x0), "FxBaseRootTunnel: CHILD_TUNNEL_ALREADY_SET");
        fxChildTunnel = _fxChildTunnel;
    }
```

`setFxChildTunnel` does not contain any access-control. Anyone is able to call this function. Although, once set, it cannot be changed due to the contract logic. Any malicious address is able to call this and essentially void the full contract if accidentally left unset.
This generally should be seen as bad practice, even if introduced by the Matic-Team.

**Mitigation:**
Override function in inheriting contract `TheShrine.sol` and add the `onlyOwner` modifier.
A check for whether it has been set already is not strictly necessary, otherwise this could be marked as immutable, furthermore ensuring that it is set and reducing gas costs.

```TheShrine.sol
    function setFxChildTunnel(address _fxChildTunnel) public override onlyOwner { //highlight-line
        fxChildTunnel = _fxChildTunnel;
    }
```

_Note:_
The same holds for `setFxRootTunnel` in `FxBaseChildTunnel.sol`.

## :recycle: [ShrineToken.sol] Reduce Use of Permits

`gaslessHarvest` and `gaslessHarvestByNFT` allow an authorized party
to distribute pending rewards to a user.
These function are currently guarded by the `onlyHarvester` modifier
only allowing calls by previously authorized accounts.

**Mitigation:**
Since `_harvestReward` does not contain any security-critical
logic, this extra authorization could be foregone to increase simplicity.

## :recycle: [ShrineToken.sol] Reduce Logic for Tracking Staked Contracts

`_processMessageFromRoot` keeps track contracts a user
has any staked balances separately through the use of an 'enumerable set'
structure. This is done via the mapping `addressToContractIndex`
that keeps track of multiple values, including an index to `userInfo.stakedContract`. There are multiple variables that are being tracked
that could be redundant.

**Mitigation:**
To reduce complexity, `addressToContractIndex` and `userInfo.stakedContract` could be removed and logic could be simplified:
Instead of iterating over the `userInfo.stakedContract` array,
looping over both contracts and checking `userInfo.stakedIds[collection].length` would reduce complexity.

A lot of the "messy" logic for enumerable sets can be hidden by using
trusted libraries, like [OpenZeppelin's Enumerable Set](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/structs/EnumerableSet.sol).

## :recycle: [TheShrine.sol] Nearly Identical Logic

`stake` & `stakeMultiple` (and `unstake` & `unstakeMultiple`) largely contain the same code.
There is very little gas overhead involved when simply using `stakeMultiple`, `unstakeMultiple`,
as these would likely involve only a few more stack-operations.
Removing duplicate code, reduces maintenance work and
simplifies interfacing the contract on a frontend
due to multiple choices of functions being considered.

**Mitigation:**
Consider removing `stake` and `unstake` functions.

## :recycle: [TheShrine.sol] Reduce External Calls

`_sendMessageToChild` is being called in a loop requiring multiple external calls (& memory accesses, event emissions).

**Mitigation:**
Consider directly encoding an array of token ids thus only requiring one message to be sent.

```TheShrine.sol
    _sendMessageToChild(
        abi.encode(
            msg.sender,
            collection,
            tokenIds[i], //del-line
            tokenIds, //add-line
            lockupDelta,
            true
        )
    );
```

## :recycle: [TheShrine.sol] Optimize Storage Reads/Writes

Currently `TheShrine.sol` keeps track of token ownerships through the use of 3 mappings:

- `contractToTokenStaker` (tracks token ownership)
- `addressToContractStakedIds` (enumerable list of ids per user)
- `contractToTokenIndex` (tracks indices in enumerable list)

This is comparable to `ERC721Enumerable` vs. `ERC721` (logic-wise and storage cost-wise). Reducing these mappings to one would simplify logic
and lower gas costs.

**Mitigation:**
The contract could simply track `contractToTokenStaker` (token ownerships) and balances.

_Note:_
Because `contractToTokenIndex` is a mapping to a list, keeping track of ownerships
in the `stake` function update involves 4 distinct storage slots,
whereas, if optimized, it would only involve one.
This would also remove the complexity of keeping track of and re-arranging indices.

_Further Note:_
Because `contractToTokenIndex` and `unlockOn` share the same mapping keys, these
could further be combined into one packed storage slot instead of taking up 2 separate slots.

## :recycle: [SekiraVerifier.sol] Remove Unused Logic

`SekiraVerifier.sol`'s code size can be significantly reduced. This contract acts as a simple proxy that propagates owned balances and staked balances of the _Sekira_ ERC721. It does not require any of the existing ERC721 logic, as it is never expected to be called (there exists no logic for minting tokens).
The only function that is necessary (for collab.land) is `balanceOf`.

**Mitigation:**
Consider removing the ERC721 logic in order to save gas costs for deployment.

**Update:**
The client has noted that they will be using _Whop_ which requires some additional logic.

## ️️:recycle: [FxBaseRootTunnel.sol] Make Non-Changing Variables Immutable

_Note: Originally declared as out of scope._

```FxBaseRootTunnel.sol
    // state sender contract
    IFxStateSender public fxRoot; //delete-line
    IFxStateSender public immutable fxRoot; //add-line
    // root chain manager
    ICheckpointManager public checkpointManager; //delete-line
    ICheckpointManager public immutable checkpointManager; //add-line
    // child tunnel contract which receives and sends messages
    address public fxChildTunnel;
```

`IFxStateSender fxRoot` and `ICheckpointManager checkpointManager`
are declared as storage variables that do not contain logic to be changed/updated in any form.

**Mitigation:**
These variables can be declared _immutable_ saving roughly 4200 gas.

_Note_: `address fxChildTunnel` is not part of the constructor variables, as it requires the address of the child contract on Polygon to be set.
It is, however, possible to first deploy the child contract or to
pre-compute the address. This way `fxChildTunnel` could also be declared
_immutable_ saving a total of 6300 gas.

# Audit Disclaimer


Haki/Sekira Contract Audit

Update: Added gas savings comparison.

## Table of contents


Secure hashing functions are pretty cool.
Some of the properties of [cryptographic hashing functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) are:

- **deterministic output** (the same input yields the same output)
- **pre-image resistance** (given $y$, it's infeasible to find an input $x$, s.t. $y = hash(x)$)
- **second pre-image resistance** (given $x_1$, it's infeasible to find an input $x_2$ , s.t. $hash(x_1) = hash(x_2)$)
- **collision-resistance** (it's infeasible to find two inputs $x_1$, $x_2$ s.t. $hash(x_1) = hash(x_2)$)

The deterministic property and the second pre-image resistance is what makes them pretty cool to use for designing smart contracts.

## Building a Marketplace Contract

For Mad Mouse Circus I built a [Marketplace Contract](https://github.com/0xPhaze/Gachapon/blob/gachapon/src/Marketplace.sol).
The idea behind this market place contract was designed to let users purchase off-chain items, such as whitelist entries or merch.

The main reason for including a smart contract in the whole process is to a) ensure that the correct amount of tokens is burned/transferred and
b) that we don't end up over-allocating and selling too many items.
We can also impose further restrictions such as a valid time-window and a maximum number of purchases per user.

A naive implementation would require an _ownable_ contract and adding market items
to some kind of list with all their info (presumably defined in a MarketItem struct).
This however, requires the owner to make on-chain transactions for every new item to be listed.
And users will have to load an items information from the contract storage when making a purchase to ensure that all requirements are fulfilled.

Another way of handling things is by letting the user input all of the items information and requirements for us (calldata is cheap) and making use of some of the cryptographic hash function's properties.
Namely, the **deterministic output** and the **second pre-image resistance**.

```Marketplace.sol
contract Marketplace {
 event PurchaseItem(address indexed user, bytes32 indexed id);

 mapping(bytes32 => uint256) public marketItemSupply;
 mapping(bytes32 => mapping(address => uint256)) public marketItemPurchases;

 function purchaseMarketItem(
 uint256 start,
 uint256 end,
 uint256 price,
 uint256 maxPurchases,
 uint256 maxSupply
 ) external {
 bytes32 hash = keccak256(abi.encode(start, end, price, maxPurchases, maxSupply)); // highlight-line

 if (block.timestamp < start || end < block.timestamp) revert NotActive(); // highlight-line
 if (++marketItemSupply[hash] > maxSupply) revert NoWhitelistRemaining(); // highlight-line
 if (++marketItemPurchases[hash][msg.sender] > maxPurchases) revert MaxPurchasesReached(); // highlight-line

 token.burnFrom(msg.sender, price);
 emit PurchaseItem(msg.sender, hash);
 }
}
```

All the item's properties (price, supply) are directly input by the user as parameters to the function call.
Now you may ask yourself whether it is unsafe to require certain conditions that are provided by the user. What stops a user from simply bypassing the frontend and directly modifying any of the function arguments?. Well.. nothing.

Nothing will stop them from taking an existing item's information and increasing the supply, for example.
Each market item is, however, uniquely identified by a `bytes32` hash deterministically generated from all of the function's inputs (assuming unique inputs for every item).
If any of the inputs is change, so will the hash identifier and the malicious user ends up purchasing a non-existent item.
Through the use of a secure hashing function we are (almost) guaranteed that different inputs will result in different outputs.

## Gas Savings

Below is a table of how much gas it would cost to run `abi.encode` and `keccak256` with the number of `uint256` parameters.
Alongside is also the storage load costs for reading those amount of `uint256`s from storage (these could be packed if less bytes are needed).

| # of inputs | keccak256 gas cost | sload gas cost |
| ----------- | ------------------ | -------------- |
| 1 | 79 | 2100 |
| 2 | 91 | 4200 |
| 3 | 112 | 6300 |
| 4 | 133 | 8400 |
| 5 | 154 | 10500 |

Using keccak256 does indeed save a lot of gas compared to naively storing data that needs to be used for validation in the contract.

## Frontend Interaction

The result of implementing the contract in this way is the owner can simply list a new
market item on their website with the desired properties without having to interact with
the smart contract.

On the frontend we can fetch valuable information to the user,
such as the remaining supply by accessing `marketItemSupply[hash]`
and how many items the user has purchased through `marketItemPurchases[hash][user]`.
If we don't care about limiting the amount of purchases per wallet address we can even get rid of this last variable.

In order to fetch the list of users who have purchased an item, we can query past events. This would look somewhat like this.

```js
const hash = ethers.utils.keccak256(
 ethers.utils.defaultAbiCoder.encode(
 ["uint256", "uint256", "uint256", "uint256", "uint256"],
 [start, end, price, maxPurchases, maxSupply]
 )
);
const filter = marketplace.filters.PurchaseItem(null, hash);
const blockNumber = await provider.getBlockNumber();
const purchases = await marketplace.queryFilter(filter, blockNumber - 5000, blockNumber);
```

(Providers often have a limit of 5000 blocks, we can however query multiple times in a loop until a desired timestamp or have a backend-server listening to events).

This same idea can be taken further for handling on-chain items.

## Permits for On-Chain Items

Take the [on-chain raffling system](https://github.com/0xPhaze/Gachapon/blob/gachapon/src/Gachapon.sol) for example. Here users are able to win prize NFTs in a raffle if they are one of the lucky winners. The current implementation requires the owner to make an on-chain transaction for every new raffle. And when a user buys a raffle ticket, they provide an id to the raffle they want to participate in. The data is then loaded from the chain and validated.

Instead of making the user pay for costly storage loads (and the owner with storage writes) we could apply the same idea from before.

Although, compared to before, we have to take extra care and since we do not want to accept arbitrary user input that could lead to unwanted behavior. For example, they could make up a raffle (with a ticket supply of 1 and a prize NFT that was meant for another raffle), which they could immediately win.

This case can be guarded against by using permits/signatures. We can simply hash the information just as before, but now also let the user provide a signature that will be validated on-chain to prove that all the information given was indeed authorized by the owner (OpenSea's order book works in a very similar way; listing an item does not cost the owner a transaction).

A simpler application than an orderbook is sometimes seen when validating users for **whitelisted ERC721 mints**.

```MyNFT.sol
contract MyNFT is ERC721A, Ownable {

 ...

 address public signerAddress = address(0xb0b);

 function whitelistMint(
 uint256 amount,
 uint256 limit, // highlight-line
 bytes calldata permit
 ) external payable {
 uint256 numMinted = numMinted(msg.sender);

 if (numMinted + amount > limit) revert ExceedsLimit(); // highlight-line
 if (!validSignature(permit, limit)) revert InvalidSignature();// highlight-line
 if (msg.value != whitelistPrice * amount) revert IncorrectValue();

 _mint(msg.sender, amount);
 }

 function validSignature(bytes calldata permit, uint256 limit) private view returns (bool) {
 bytes32 msgHash = keccak256(abi.encode(address(this), msg.sender, limit));
 return msgHash.toEthSignedMessageHash().recover(permit) == signerAddress;
 }
}
```

Here as well, the actual `limit` (restricting how many NFTs a certain wallet is able to mint), as well as the permit is being provided by the user. This information (the user and their limit) is hashed, signed and validated on-chain. If the `limit` is tampered with, the hash would change and the recovered signer would become invalid.

for Gas Savings

Cryptographic Hashing Functions


*Notes taken from the [RSA paper](https://people.csail.mit.edu/rivest/Rsapaper.pdf)*.

## Table of Contents

## RSA

$$
dec(enc(M)) = M
$$


A *trap-door one-way function* allows a message $M$ to be encrypted as cyphertext $C$
given a public (known) key / encryption method ($enc$).
$C$ is only able to be deciphered in a reasonable time if the private key ($dec$) is known.

First, assume that $M$ can be represented as an integer $\in [0, n-1]$ (if not, break it into blocks).
Encrypting/Decrypting $M$ with the public key ($e$, $n$) $\in \mathbb N^+$ works by:

### Encrypting $M$
$$
C = enc(M) = M ^e \quad (\text {mod} \; n)
$$

### Decrypting $C$
$$
dec(C) = C ^d \quad (\text {mod} \; n)
$$

### Steps
| Steps                                      | Variables                   |
| ------------------------------------------ | --------------------------- |
| find $p$ and $q$ two large prime numbers   | $p$, $q$ prime              |
| calculate $n=pq$                           | $n = pq$                    |
| calculate $\phi (n) = (p - 1)(q - 1)$      | $\phi (n) = (p - 1)(q - 1)$ |
| pick $e$ relatively prime to $\phi (n)$    | $e$                         |
| pick $d$ mul inverse of $e$ mod $\phi (n)$ | $d$                         |

To use RSA, one must find $p$ and $q$, two very large, random prime numbers.

Theorem states

The security of the scheme relies on the fact that it is computationally infeasible to derive $p$ and $q$ from $n$.

*Public key*: $[e, n]$
*Private key*: $[d, n]$


## Why does this work?

$$
dec(enc(M)) = (M^e)^d = M ^{ed} \quad (\text {mod} \; n)
$$

We would like to show that $M^{ed} \; (\text {mod} \; n) \overset ! = M$.
We know that $e$ and $d$ are multiplicative inverses ($\text {mod} \; \phi (n)$):
$$
ed \equiv 1 \quad (\text{mod} \; \phi (n))
$$

This means that there exists some $k \in \mathbb N^+$ s.t.
$$
ed = k \phi(n) + 1
$$

This leads us to
$$
\begin{equation}
\begin{align*}
M^{ed} = M^{k \phi(n) + 1} 
&= M^{k (p - 1)(q -1 ) + 1} \\
&= M(M^{k(q - 1)})^{(p - 1)}
\end{align*}
\end{equation}
$$


### Fermat's little theoreom

[Fermat's little theoreom](https://en.wikipedia.org/wiki/Fermat%27s_little_theorem) states that 
$$
a^p \equiv a \quad (\text {mod} \; p)
$$
for any integer $a$ and prime $p$.

If $a \not\equiv 0 \ (\text {mod} \; p)$, then
$$
a^{(p - 1)} \equiv 1 \quad (\text {mod} \; p)
$$

Using Fermat's little theorem in equation $(1)$, we can conclude that

$$
\begin{align*}
M^{ed} 
&= M(M^{k(q - 1)})^{(p - 1)} \\
&\equiv M \quad (\text{mod} \; p)
\end{align*}
$$

Using the same logic, we can show that 

$$
M^{ed} \equiv M \quad (\text{mod} \; q)
$$

### Chinese remainder theoreom

The [Chinese remainder theorem](https://en.wikipedia.org/wiki/Chinese_remainder_theorem) (adapted to this case) states that:

If 
$x \equiv M \; (\text{mod} \; p)$
and
$x \equiv M \; (\text{mod} \; q)$
for two co-prime integers $p$, $q$
then
$x \equiv M \; (\text{mod} \; pq)$

Using these two theorems, we conclude that 
$$
M^{ed} \equiv M \; (\text{mod} \; n)
$$


Questions:
- why $\phi$
- Why $e$ relatively prime

$$
\phi(n) = n \prod _{p | n}(1 - \frac 1 p) 
= n ( 1 - \frac 1 p)(1 - \frac 1 q)
= n ( \frac {p - 1}  p)(\frac {q - 1} q)
= (p - 1)(q - 1)
$$


https://eli.thegreenplace.net/2019/rsa-theory-and-implementation/

"The era of 'electronic mail' may soon be upon us"



Update: Check out [this repo](https://github.com/0xphaze/ERC721M) for an implementation.

We've come a long way since the development on [MadMouse](https://madmousecircus.io/) started back in November.

Initially, our contract was based on [ERC721A](https://www.erc721a.org/).
While being extremely happy about new form of optimization that is brought to the NFT-space,
we immediately had [some suggestions to make](https://github.com/chiru-labs/ERC721A/issues/18).
However, it quickly became clear, that because of all its features and special needs,
the MadMouse contract would need its own unique implementation.

What we especially noticed was how inneficiently most staking contracts were implemented.
We definitely did not want to follow suit.
The worst thing for us would be if people had to pay
unnecessarily high gas fees when interacting with our contracts.
That's why our top priority has always been to
keep the implementation as gas-efficient as possible,
so not to exclude anyone from taking part in our ecosystem.

To be able to fit all of our auxilliary information into the contract
without wasting extra storage slots (which ultimately are the main driver
for gas costs), we decided to pack all information using bitmaps.

This means that while our contract has all this extra functionality,
the storage costs (and thus all basic operation) remain the same as ERC721A's.
**In fact, for some operations gas costs are even less.**

Staking in batches, for example, occurs by transferring in batches while minimizing storage reads and writes.
There is even the possibility to mint and stake at the same time, drastically reducing costs.
The token data in this case is implicitly stored, just like in ERC721A.

## ERC721M comparisons

What does all this mean for the end-user?
Let's have a look at some gas comparisons.
For starters, here is a comparison with [Azuki](https://www.azuki.com/garden) (the ones behind ERC721A).

![azuki-comparison](/data/blog/2022/madmouse/azuki.png)

ERC721M still holds up to ERC721A. The comparison is based on 5 mints.
For all comparisons we use 100 gwei as a baseline and the first token is pre-minted.

One of ERC721M's special features is that it comes with a **'mint & stake'** functionality.
Just recently, [Metroverse](https://metroverse.com/) launched, also with the same ability.
Although their contract isn't based on ERC721A's implicit storage,
their contract is still pretty optimized.

![metroverse-comparison](/data/blog/2022/madmouse/metroverse.png)

Again, the data is based on a mint quantity of 5. We see that ERC721M extends the idea
of ERC721A to allow direct staking without any overhead cost.
**MadMouse's 'mint & stake' is about 5x cheaper than Metroverse**.

We tried hard to find a better comparison and to look for any
implementation that was based on ERC721A and allowed for staking.
In that regard, we found [WabiSabi](https://www.wabisabicollective.io/),
a collection that just launched this month.

![wabisabi-comparison](/data/blog/2022/madmouse/wabisabi.png)

Here, we showed what it would be like, if we didn't use the 'mint & stake' feature, but
first had minted 5 NFTs and then in-turn staked those.

Staking with ERC721A means that (like with a transfer), implicit token data has to be
explicitly set. That's why staking can seem more expensive at first.
However, ERC721M still tries to optimize as much as possible under the hood.
Staking is done similarly to a batch transfer, where state reads and writes are
minimized as much as possible.
**MadMouse is about 4x more efficient than Wabisabi**.
Comparing with the 'mint & stake' feature, **this turns out to be 8x as cheap**
(not even taking into account the extra approval transaction).

WabiSabi keeps track of staked token ids in a list (as seen with many other
collections as well). Because of this, unstaking gas costs
can quickly explode with higher numbers, due to the worst-case complexity being O(N^2).

If you know of any cheaper staking implementation that we could compare ours against, let us know!

## What's next?

So, what's next for MadMouse? Does this become a community-standard?
In its current form, we had to rely on some heavy engineering work
in order to fit in all the features while keeping costs cheap.
Mistakes are likely to happen if not handled with care.

That's why our plan is to release a simpler, lighter build in the near future
as an ERC721A extension, so that other projects can also make use of
an efficient staking contract.


Staking with ERC721A

ERC721M


I just heard about the [2022 Underhanded Solidity Contest](https://underhanded.soliditylang.org/)
and submissions are due in a day.

## About the Contest

From the website: "The goal of the Underhanded Soldity Contest is to write seemingly innocent and straightforward-looking Solidity code which actually contains malicious behavior or backdoors."

I have recently started getting into Solidity CTF challenges and wanted to give it a go.
Designing smart-contract challenges sounds like a fun task.
There have been times while coding a contract where I had to shudder,
because I realized a terrible mistake in my code.
I thought some of these could end up being interesting CTF Challenges.

This years theme for the challenge is about decentralized exchanges. Any kind, orderbook or AMM.
And, "simplicity is key" is emphasized.

I came up with two challenges that I [uploaded to Github](https://github.com/willisk/SmartContract-Challenges) if you want to give them a try!

I was first going to go with submitting the bitmap challenge ["ExclusiveExchange.sol"](https://github.com/willisk/SmartContract-Challenges/blob/master/contracts/ExclusiveExchange.sol),
because it came across as unique (albeit also a bit of a niche setting).
Although, after stripping away any unnecessary, distracting fluff from the contract,
the vulnerability seemed too obvious.
And, especially after hearing that @samczsun from paradigm will be on the board
(famous for [his pinball machine](https://samczsun.com/hiding-in-plain-sight/) - probably one of the hardest challenges regarding bitmaps),
I decided to come up with another one.

So, I wrote the second challenge ["NFTOrderBook.sol"](https://github.com/willisk/SmartContract-Challenges/blob/master/contracts/NFTOrderBook.sol).
The setup for this one is a bit more realistic and the bug is more common, although a bit simple.
I still have not seen any other CTF challenge revolve around this vulnerability/error,
so it could be a good fit.

I might have a small write-up, after I have some people test them out
and give me feedback.


Underhanded Solidity Contest

My [last post](/blog/2022/unexpected-input), which was about an exploit allowing
unlimited minting of an ERC20 token got me thinking about whether any counter-measures
could be implemented if such an exploit were to happen.

Below is the contract of the MadMouse utility token Gouda, which I'm currently developing.
It's a standard ERC20 token combined with OpenZeppelin's AccessControl contract.

```Gouda.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import '@openzeppelin/contracts/access/AccessControl.sol';
import '@openzeppelin/contracts/token/ERC20/ERC20.sol';

import './lib/ERC721MStaking.sol';

error ExceedsMaxSupply();

contract Gouda is ERC20, AccessControl, IERC20Reward {
 bytes32 private constant MINT_AUTHORITY = keccak256('MINT_AUTHORITY');
 bytes32 private constant BURN_AUTHORITY = keccak256('BURN_AUTHORITY');

 constructor(address madmouse, address treasury) ERC20('Gouda', 'GOUDA') {
 _setupRole(DEFAULT_ADMIN_ROLE, msg.sender);

 _setupRole(MINT_AUTHORITY, madmouse);
 _setupRole(BURN_AUTHORITY, madmouse);

 _mint(treasury, 100_000 * 1e18);
 }

 // ------------- Restricted -------------

 function mint(address user, uint256 amount) external onlyRole(MINT_AUTHORITY) {
 _mint(user, amount);
 }

 function burn(address user, uint256 amount) external onlyRole(BURN_AUTHORITY) {
 _burn(user, amount);
 }
}
```

# A counter-measure to an attack

In the case of an attacker being able to exploit the staking contract,
they would likely mint a high number of tokens not achievable by normal staking.

What if we restrict the mint function to revert in such a case?

```Gouda.sol
contract Gouda is ERC20, AccessControl, IERC20Reward {

 ...

 function mint(address user, uint256 amount) external onlyRole(MINT_AUTHORITY) {
 require(amount > 500_000 * 1e18, 'UNDER_ATTACK');
 _mint(user, amount);
 }
}
```

This would be too noticeable for an attacker. They would most likely realise the revert when testing locally
and if the first attack failed, they could simply launch many more, smaller ones to bypass the limit.

What if we instead let the call go through and then revoke the `MINT_AUTHORITY` role of the
staking contract? That way, the funds could remain safe until a solution has been found.

```Gouda.sol
contract Gouda is ERC20, AccessControl, IERC20Reward {

 ...

 function mint(address user, uint256 amount) external onlyRole(MINT_AUTHORITY) {
 if (amount < 500_000 * 1e18) _mint(user, amount);
 else _revokeRole(MINT_AUTHORITY, madmouse); // emergency shutdown
 }
}
```

Hm.. so far so good. Although, they would likely run
tests on a local network first to check whether their attack was successful
and their token balance increased.

[EIP-1344](https://eips.ethereum.org/EIPS/eip-1344) introduced the ChainID opcode
which can now be accessed through `block.chainid`.
This way, we could have our fail-safe code run only when the chain
is on mainnet (chain id 1).
We can also add further checks, since some providers will set `tx.origin = address(0)`
when running 'call' methods (i.e. calls that are not sent to the blockchain to be mined).

```Gouda.sol
contract Gouda is ERC20, AccessControl, IERC20Reward {

 ...

 function mint(address user, uint256 amount) external onlyRole(MINT_AUTHORITY) {
 if (amount < 500_000 * 1e18 // highlight-line
 || block.chainid != 1 // highlight-line
 || tx.origin == address(0)) { // highlight-line
 _mint(user, amount); // highlight-line
 } // highlight-line
 else _revokeRole(MINT_AUTHORITY, madmouse);
 }
}
```

Ok, getting there..
Now, if the attacker tests out their exploit locally, they would be able to mint the
tokens, and if it were to execute on mainnet, the emergency shutdown code would be called.

Still, any quick peak at the contract will directly expose this counter-measure.
So, how can we hide it?

Hiding it in the ERC20.sol contract directly would seem infeasible, because we are trying
to access `_revokeRole` from AccessControl to automatically trigger the emergency shutdown.
ERC20's implementation comes with the hooks `_beforeTokenTransfer` and `_afterTokenTransfer`.
Perhaps these could be used in some form..

I tried modifying '@openzeppelin/contracts/access/AccessControl.sol'
to inherit from ERC20.sol.
That way, AccessControl could be implementing the special hooks.
The only problem with this is that we're now inheriting from two contracts that implement an
`_afterTokenTransfer` and thus are required to override it again in our ERC20 contract.
This, in turn would look suspicious again,
because "wth is AccessControl doing implementing an `_afterTokenTransfer`?"

```Gouda.sol
contract Gouda is ERC20, AccessControl, IERC20Reward {

 ...

 function _afterTokenTransfer(
 address from,
 address to,
 uint256 amount
 ) internal override(ERC20, AccessControl) {
 super._afterTokenTransfer(from, to, amount);
 }
}
```

What if... we kept this piece of code in the ERC20.sol implementation and directly modified storage slots?
For that, we would have to figure out what storage slot is being used to grant the staking contract the authority.

```AccessControl.sol
abstract contract AccessControl is Context, IAccessControl, ERC165 {
 struct RoleData {
 mapping(address => bool) members;
 bytes32 adminRole;
 }

 mapping(bytes32 => RoleData) private _roles;

 ...
}
```

AccessControl's roles are stored in the `mapping(bytes32 => RoleData) _roles`
and since we want to modify the `RoleData` for the `MINT_AUTHORITY` role,
we should be looking at `_roles[MINT_AUTHORITY]`
or `_roles[0x2835a7a5b84b6b14021f9bc9694ea8ba57b01e33d0984ae2c6ac566c9cb317dd]`.
Then, we want to access `members`, specifically `members[madmouse]`.

To get the final storage slot of `_roles[MINT_AUTHORITY].members[madmouse]`,
we will have to compute

```sol
bytes32 slot_roleData = keccak256(abi.encode(MINT_AUTHORITY, slot_roles));
bytes32 slot_members = slot_roleData + 0;
bytes32 slot_data = keccak256(abi.encode(madmouse, slot_members));
```

We don't need to add an offset to `slot_roleData` when calculating `slot_members`,
because it is in storage slot 0 in the `RoleData` struct and thus `slot_roleData == slot_members`.
You can read more on storage layout [here](https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html).

The only missing part now is `slot_roles`.
This slot is dependent on the internal storage slots of the contract.
We can use a script to iterate over all stora slots and read out the storage
to find this slot quickly.

```js
for (let slot_roles = 0; slot_roles < 10; slot_roles++) {
 let slot_members = ethers.utils.keccak256(
 ethers.utils.defaultAbiCoder.encode(
 ['bytes32', 'uint'],
 ['0x2835a7a5b84b6b14021f9bc9694ea8ba57b01e33d0984ae2c6ac566c9cb317dd', slot_roles]
 )
 );

 let slot_data = ethers.utils.keccak256(
 ethers.utils.defaultAbiCoder.encode(['address', 'bytes32'], [nft.address, slot_members])
 );

 let data = await network.provider.send('eth_getStorageAt', [gouda.address, slot_data, 'latest']);

 console.log(slot_roles, slot_members, slot_data, data);
}
```

The result:

```js
0 0x15cbcc7ee8b33517d87e628a3ab5fdc484a6b34f5ade2092ebc08dd9cb0ca324 0xf381069cc17fc400a04f9af5041ad36e197e835f2d29ad6a9ef5436dcfc08316 0x0000000000000000000000000000000000000000000000000000000000000000
1 0x0edbf5ca4965338dd62f75ba1de83eaaaac30e60abb11286d503c3974881165c 0x27fce0b43dd82ae221013e6954fc2adf28c02e3e6e96093620b75f1a6cd70b57 0x0000000000000000000000000000000000000000000000000000000000000000
2 0xcee27263ce9ad7070e2cdbf5b3f11082a9b1a281ddb83f41a7eefde673a5adca 0x1f1a1876d0dd3e2d2ddbeecb460a9091173ce9f2a40563816e0244b934cf2be0 0x0000000000000000000000000000000000000000000000000000000000000000
3 0xb32bb3ba356143f7ad5c637479f06883217ad3d5b85f7cf3f8c30152cbb6364a 0x6fc5d456201c9606ecb4c83e0bdea733d5ddc704ee75a0e9684da0e610b1b292 0x0000000000000000000000000000000000000000000000000000000000000000
4 0xd9191642a20cbd464db6d25f40b03b7fc59b571d399a359b9ac38134c83e856a 0xa7f91fd2efb5a47686a7fd60162f86f05679850a3469c8274b51aee21c94cd6b 0x0000000000000000000000000000000000000000000000000000000000000000
5 0x4f431056f30038a4630700c6ce70dd8770865fbb61b08a774f29ed79a8e58129 0x1d74f4cfcf55a4866d5f7e8565274daa8a310ebb98a84bdf29b1e6e8631a7380 0x0000000000000000000000000000000000000000000000000000000000001337 // highlight-line
6 0x8cdef33328e7cad47ce15a7fe2205f3924fe77c37f2fa5061a73a1d1a85ecd96 0x2d7d9aec18f3786f6dd7a826144db7f518eb4d6d5f4121dc714bc5af105b2f35 0x0000000000000000000000000000000000000000000000000000000000000000
7 0xbc8fbf2aa6164f00cf2f22757f1de06f71959b8b9d75dcf0beef9c7e6b6e00e7 0x6ba2813f222dd1dfbfc978039655edf7bf5e63233313f28c047caf3629b41af6 0x0000000000000000000000000000000000000000000000000000000000000000
8 0x10f605896b2ef49244aeafc0c06c364831ebe47381f4c06a98bc6e906861c852 0xddd9db65cdfbd0127590dd5a3bc56caf338ca2fc43ca09da72317763b36a327a 0x0000000000000000000000000000000000000000000000000000000000000000
9 0xc1a5536b2498b1ba1e7da4ff40e87f1b068e232026c46ac078ebf98c7f51f6fa 0x75b2f0ce94d3ebd5d90cdfd41f3a3ddcfaf908a8ef896b7e9516c7bb33c6f9d1 0x0000000000000000000000000000000000000000000000000000000000000000
```

I had changed the mapping in `RoleData` to `mapping(address => bytes32) members`
and set `_roles[MINT_AUTHORITY].members[madmouse] = 0x1337` to make it more obvious.
Now we know that the storage slot for `_roles` is 5! Although, we can simply
use the pre-computed `slot_members`, since that won't change. Note: depending on additional
variables in the contract's storage, the storage slot might be located somewhere else.

We can finally implement our `_afterTokentransfer`:

```@openzeppelin/contracts/token/ERC20/ERC20.sol
// this part is to be hidden in '@openzeppelin/contracts/token/ERC20/ERC20.sol'
function _afterTokenTransfer(
 address from,
 address to,
 uint256 amount
) internal virtual override {
 if (from == address(0) && amount > 500_000 * 1e18 && block.chainid == 1 && tx.orign != address(0)) {
 // 0x4f431056f30038a4630700c6ce70dd8770865fbb61b08a774f29ed79a8e58129
 // is the storage slot of _roles[MINT_AUTHORITY].members in AccessControl
 // s is the storage slot of the authorisation flag for msg.sender _roles[MINT_AUTHORITY].members[msg.sender]
 bytes32 slot = keccak256(
 abi.encode(msg.sender, 0x4f431056f30038a4630700c6ce70dd8770865fbb61b08a774f29ed79a8e58129)
 );

 // same as: _roles[MINT_AUTHORITY].members[msg.sender] = 0
 assembly {
 sstore(slot, 0)
 }

 // burn an equivalent amount of tokens to counter the amount of tokens minted
 _burn(to, amount);
 }
}
```

Thankfully, we don't have to think of ways to somehow pass in the staking contract's address
to ERC20 unnoticed, since we know that the staking contract will be `msg.sender`.

Some final checks make sure that this only gets triggered when minting and not when
initialising the contract. Because we can't modify the amount of tokens that the attacker receives
through the hooks, we can simply `_burn` an equivalent amount of tokens in return.

## In summary

- counter-measure is hidden in `@openzeppelin/contracts/token/ERC20/ERC20.sol`
- if an unrealistic amount of tokens is to be minted, they are immediately burned
- the staking contract also gets the `MINT_AUTHORITY` role removed
- the transaction does not revert
- only activated when running on mainnet
- funds are safu?

This trick should be fairly hard to notice and could prove useful in some cases.

aka "Hackers hate this one weird trick"

Counter-Attack to the Attack

There's a bug that seems to occur fairly frequently in the NFT projects venturing
into the DeFi-space.
My guess is that this is because there have not been
fully audited ERC721 and trusted staking contracts,
like the Synthetix staking contract.
I first got to know this bug through Mutant Cats' [FishFarm](https://etherscan.io/address/0xb2f43262fc23d253538ca5f7b4890f89f0ee95d9#code)
and
Stacked Toadz' [ERC721Farm](https://etherscan.io/address/0x4d1de90bca7a38c556c356c0b802b5102cea032d#code).

Mutant Cats were lucky enough to get notified by the community about the vulerability
and began migrating to a new staking contract in time.
Stacked Toadz [were not so lucky](https://twitter.com/stacked_toadz/status/1448953720348102660)
with the hacker making off with 43 ETH from the looted $STACKS.

Because of a project I'm working on, I wanted to make sure that all of the tokens that will be
able to interact with our eco-system follow the ERC20 standard
(and don't resort to a O(N) balanceOf implementation).
And just out of curiosity I went ahead and looked at some of their implementations.

I was able to find the same bug in [UniQuest](https://etherscan.io/address/0x3a6d70e7989ba6e7d5958d7c1eea487082681698/advanced#code), the staking contract for Uninterested Unicorns.
The Unicandy UCD-ETH pool maximally allowed for swapping out around 100 ETH.

# The code

The relevant code to claim ERC20 rewards for Mutant Cats is shown below.

```FishFarm.sol
contract FishFarm {

 ...

 function calculateRewards(address account, uint256[] memory tokenIds)
 public
 view
 returns (uint256[] memory rewards)
 {
 rewards = new uint256[](tokenIds.length);

 for (uint256 i; i < tokenIds.length; i++) {
 uint256 tokenId = tokenIds[i];

 rewards[i] =
 RATE *
 (_deposits[account].contains(tokenId) ? 1 : 0) *
 (Math.min(block.number, EXPIRATION) -
 depositBlocks[account][tokenId]);
 }
 }

 function claimRewards(uint256[] calldata tokenIds) public {
 uint256 reward;
 uint256 block = Math.min(block.number, EXPIRATION);

 uint256[] memory rewards = calculateRewards(msg.sender, tokenIds);

 for (uint256 i; i < tokenIds.length; i++) {
 reward += rewards[i];
 depositBlocks[msg.sender][tokenIds[i]] = block;
 }

 if (reward > 0) {
 try IERC20(FISH).transfer(msg.sender, reward) returns (bool v) {
 } catch Error(string memory) {}
 }
 }
}
```

The `claimHODLRewards` is part of the
[UniQuest](https://etherscan.io/address/0x3a6d70e7989ba6e7d5958d7c1eea487082681698/advanced#code)
staking contract for Uninterested Unicorns NFT.

```UniQuest.sol
contract UniQuest {

 ...

 function claimHODLRewards(uint256[] memory tokenIds) public nonReentrant {
 for (uint256 i = 0; i < tokenIds.length; i++) {
 require(
 UU.ownerOf(tokenIds[i]) == msg.sender,
 "UniQuest: Not Owner of token"
 );
 }

 uint256 rewards = calculateHODLRewards(tokenIds);

 for (uint256 i = 0; i < tokenIds.length; i++) {
 HODLLastClaim[tokenIds[i]] = block.timestamp;
 }

 UCD.mint(msg.sender, rewards);
 }


 function calculateHODLRewards(uint256[] memory tokenIds)
 public
 view
 returns (uint256 HODLRewards)
 {
 HODLRewards = 0;
 for (uint256 i = 0; i < tokenIds.length; i++) {
 HODLRewards = ...
 }
 }
}
```

# The bug

The bug is possible because in both contracts, the rewards calculation is separated from the
state-update to the blockchain and because they allow for unchecked user input.
The reward is calculated by first looping over the user-inputted token ids.
And only afterwards the claimed timestamp for each token id is set in another loop.

The problem is that the user is able to input a token id they own
as many times as they want. There is nothing stopping them
from inputting `claimRewards([3, 3, 3, 3, ...])` for example.
This allows the attacker to mint an unlimited amount of tokens from
the staking contract.

# The solution

A checks-effects-interactions pattern - well known for guarding
against reentrancy bugs - would have prevented these exploits from being possible.
Instead of using two-loops, the correct way would be to use one loop
and to set the timestamp for the last claim directly after checking
the rewards for a certain token id.

Also, in general it makes sense to limit the degree-of-freedom a user has
while interacting with a contract. **Fishfarm** had direct access to `_deposits`
and **Uninterested Unicorns** is an _ERC721Enumerable_, so both contracts
could have implemented a function `claimRewards()` instead that
directly claims the rewards for all token ids, thereby
limiting attack vectors through malicious user-input.

After getting into contact with the Uninterested Unicorns team, they were able to
upgrade their proxy contract's implementation - no unicorns hurt.

Uninterested Unicorns

Bug Report

[ABI Playground](/abi-playground)
is a tool that allows for quick and easy interacting with deployed contracts
without a verified source.

This is what the interface looks like:

![demo](/data/blog/2022/abi-playground/demo.png)

You can click on the **?-symbol** next to the title to **fill in the example** for you.
It enters in the contract address of TheDAO and a few functions as an example.

![demo](/data/blog/2022/abi-playground/demo2.png)

The ABI-section allows you to **fetch the ABI from etherscan** if it's available or import common ABIs.

![demo](/data/blog/2022/abi-playground/demo3.png)

You can either enter a full ABI in JSON format, or **you can simply write function declarations yourself,
like in the example**.

![demo](/data/blog/2022/abi-playground/demo4.png)

The _Functions_ section is generated automatically from the ABI.
To send a request, click on the function name.
The function's arguments are in between the parentheses along with their variable names if given.
If a variable is of type `address`, the \*-symbol can be used to insert
your own address.

Once the ABI and an address has been entered, **the contract (along with the ethers library) can also be accessed by opening up the
developer console**.

![demo](/data/blog/2022/abi-playground/demo5.png)

The variables after the arrow are the returned variables.
Note that, **only constant (i.e. non-state-modifying/view) functions will return data**.

- _View_ functions are marked blue
- _State-modifying_ functions are marked orange
- _Payable_ functions are in red

In order to receive an output from a state-modifying function (orange and red) they need to be called as a static request.
This can be achieved by either changing the definition in the ABI, i.e. adding the _view_ declaration.
Or this can be done in the Low-Level Call section.
The Low-Level Call data is automatically updated by modifying function arguments, or by clicking
on the icon to the left of a function.

![demo](/data/blog/2022/abi-playground/demo6.png)

This section shows the full transaction data that is submitted
and can be directly modified. **It can therefore also be used for deploying contracts
by copying the deployment bytecode or it can be used to directly execute raw bytecode**.
This can come in handy for some of the [Ethernaut challenges](https://ethernaut.openzeppelin.com/).

![demo](/data/blog/2022/abi-playground/demo7.png)

The response is decoded if any return values were specified.
Individual values can be copied by clicking on the types to the left.

![demo](/data/blog/2022/abi-playground/demo8.png)

The full response (broken up in 32 bytes chunks) can be inspected in the Low-Level Call section.
The raw data can be copied by clicking on 'data' on the top.

[Try it out!](/abi-playground) I'm happy for any feed-back.

Special thanks to the team developing the [ethersjs](https://docs.ethers.io/).
This is just a fancy interface built on-top of it.

ABI Playground


So you want to add a commenting-system to your blog, but you've become tired of legacy Web 2.0 tech?
Are you sick of having capitalist commenting-services like **DisqusJS** litter your blog with corporate ads?
Why not give the money to hard-working miners insted?
Why not leverage the benefits of censorship-resistant, decentralized blockchain today?
It's permission-less, fast and effectively gates opinions voiced in the comment section.
Anti-Bot protection? - Just deploy on Eth Mainnet.

# The contract

The basic functionality we need is for a user to register under a unique user name.
For that we'll be looking up the address stored under given a names hash.
This is accomplished via the `userNameRegistry` a mapping `bytes32 => address`.

The `Account` struct stores the name as a string and the date the account was created on.

```SolDisc.sol
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.12;

contract SolDisc {
    struct Account {
        string name;
        uint256 creationDate;
    }

    mapping(address => Account) public accounts;
    mapping(bytes32 => address) public userNameRegistry;

    function createAccount(string calldata name) external {
        require(isValidUserName(name, 4, 20), 'INVALID_NAME');

        // enforce unique user-names by storing the hash in a registry
        bytes32 userNameHash = keccak256(abi.encodePacked(name));
        address userNameOwner = userNameRegistry[userNameHash];

        require(userNameOwner == address(0));
        userNameRegistry[userNameHash] = msg.sender;

        // create user profile
        Account storage account = accounts[msg.sender];
        account.name = name;
        account.creationDate = block.timestamp;
    }
}
```

`isValidUserName` is simply a function that checks for invalid characters and makes sure it fits the minimum and maximum length
requirements.

We can now add the functionality to enable commenting on a specific post.

```SolDisc.sol
contract SolDisc {
    struct Account {
        string name;
        uint256 creationDate;
    }

    struct Comment { //add-line
        address user; //add-line
        uint256 creationDate; //add-line
        string text; //add-line
    } //add-line

    mapping(address => Account) public accounts;
    mapping(bytes32 => address) public userNameRegistry;

    mapping(bytes32 => Comment) public commentRegistry; // add-line
    mapping(bytes32 => bytes32[]) commentHashesByPostHash; // add-line

    function createAccount(string calldata name) public {
        ...
    }

    function commentOnPost(bytes32 postHash, string calldata text) external requiresAccount { // add-line
        require(isValidComment(text), 'INVALID_COMMENT'); //add-line
 //add-line
        uint256 commentId = commentHashesByPostHash[postHash].length; //add-line
        bytes32 commentHash = keccak256(abi.encode(postHash, commentId)); //add-line
 //add-line
        // add comment to registry //add-line
        Comment storage comment = commentRegistry[commentHash]; //add-line
        comment.user = msg.sender; //add-line
        comment.creationDate = block.timestamp; //add-line
        comment.text = text; //add-line
 //add-line
        // register comment to post //add-line
        commentHashesByPostHash[postHash].push(commentHash); //add-line
 //add-line
        // link comment to user account //add-line
        accounts[msg.sender].commentHashes.push(commentHash); //add-line
    } // add-line
 // add-line
    modifier requiresAccount() { // add-line
        require(accounts[msg.sender].creationDate > 0, 'USER_ACCOUNT_REQUIRED'); // add-line
        _; // add-line
    } // add-line
 // add-line
}
```

Since comments can be seen as arrays tied to a certain post,
the function `commentOnPost` takes in a bytes32 hash `postHash` unique to a post/page
and the string `text` which is to be added as a comment.

We could structure the mapping as `bytes32 => Comment[]`, however, as might become clearer later,
it is practical to have a single unique hash to index each comment (i.e. `bytes32 => Comment`).
Like before, the Comment is indexed in a mapping `bytes32 => Comment` `commentRegistry`.

`commentHashesByPostHash`, a mapping `bytes32 => bytes32[]` is used to index and register
comments (by their hashes) given a post hash.

And that's pretty much it to make it work! There are a few extra features that we could add,
such as liking posts and editing them.

## Extra Features

No commenting-system is complete without being able to like comments.
The number of likes a comment receives will be implemented as a `uint256 numLikes` stored in the `Comment` struct.
Furthermore (in order to make sure a user can only like a comment once), we'll need to keep track of a user's likes.
This is done in the mapping `bytes32 => bool likedComments` available in each user's account
to keep track of which comments they have already liked.

In order to like (and un-like) a comment, we'll add a function `toggleLikeComment` that takes in
the post hash and the comment index/id.

```SolDisc.sol
contract SolDisc {
    struct Account {
        string name;
        uint256 creationDate;
        mapping(bytes32 => bool) likedComments; // add-line
    }

    struct Comment {
        address user;
        uint256 creationDate;
        uint256 numLikes;   // add-line
        string text;
    }

    ...

    function toggleLikeComment(bytes32 postHash, uint256 commentId) external requiresAccount { // add-line
        bytes32 commentHash = keccak256(abi.encode(postHash, commentId)); // add-line
        Comment storage comment = commentRegistry[commentHash]; // add-line
 // add-line
        require(comment.user != msg.sender, 'CANNOT_LIKE_OWN_COMMENT'); // add-line
 // add-line
        Account storage account = accounts[msg.sender]; // add-line
        bool like = !account.likedComments[commentHash]; // add-line
        account.likedComments[commentHash] = like; // add-line
 // add-line
        if (like) comment.numLikes++; // add-line
        else comment.numLikes--; // add-line
    } // add-line
}
```

Finally, on the front-end, we can then generate a hash from a post's using **ethers.js**:

```js
const encoded = ethers.utils.defaultAbiCoder.encode(['string'], [pageSlug]);
const postHash = ethers.utils.keccak256(encoded);
```

where `pageSlug` is '2021/soldisc' in this case.

In order to make the whole experience more complete, a bunch of helper functions
that enable us to more quickly and efficiently fetch the data from the chain are needed.
You can view the final implementation on [Github](https://github.com/willisk/SolDisc/blob/master/contracts/SolDisc.sol).
Please do try it out and leave a comment! Next versions will include comments as ERC721s and likes as ERC20s.

Edit: Is it 2022 already?
