Skip to content

Commit 86b1a0d

Browse files
authored
Merge pull request #13 from ipsilon/add-hugo
Add hugo static site generator and FAQs
2 parents 2915da0 + 993736e commit 86b1a0d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+587
-396
lines changed

.github/workflows/hugo.yaml

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Sample workflow for building and deploying a Hugo site to GitHub Pages
2+
name: Deploy Hugo site to Pages
3+
4+
on:
5+
# Runs on pushes targeting the default branch
6+
push:
7+
branches:
8+
- main
9+
10+
# Allows you to run this workflow manually from the Actions tab
11+
workflow_dispatch:
12+
13+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
20+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
21+
concurrency:
22+
group: "pages"
23+
cancel-in-progress: false
24+
25+
# Default to bash
26+
defaults:
27+
run:
28+
shell: bash
29+
30+
jobs:
31+
# Build job
32+
build:
33+
runs-on: ubuntu-latest
34+
env:
35+
HUGO_VERSION: 0.146.0
36+
HUGO_ENVIRONMENT: production
37+
TZ: America/Los_Angeles
38+
steps:
39+
- name: Install Hugo CLI
40+
run: |
41+
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
42+
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
43+
- name: Install Dart Sass
44+
run: sudo snap install dart-sass
45+
- name: Checkout
46+
uses: actions/checkout@v4
47+
with:
48+
submodules: recursive
49+
fetch-depth: 0
50+
- name: Setup Pages
51+
id: pages
52+
uses: actions/configure-pages@v5
53+
- name: Install Node.js dependencies
54+
run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
55+
- name: Cache Restore
56+
id: cache-restore
57+
uses: actions/cache/restore@v4
58+
with:
59+
path: |
60+
${{ runner.temp }}/hugo_cache
61+
key: hugo-${{ github.run_id }}
62+
restore-keys:
63+
hugo-
64+
- name: Build with Hugo
65+
run: |
66+
hugo \
67+
--gc \
68+
--minify \
69+
--baseURL "${{ steps.pages.outputs.base_url }}/" \
70+
--cacheDir "${{ runner.temp }}/hugo_cache"
71+
- name: Cache Save
72+
id: cache-save
73+
uses: actions/cache/save@v4
74+
with:
75+
path: |
76+
${{ runner.temp }}/hugo_cache
77+
key: ${{ steps.cache-restore.outputs.cache-primary-key }}
78+
- name: Upload artifact
79+
uses: actions/upload-pages-artifact@v3
80+
with:
81+
path: ./public
82+
83+
# Deployment job
84+
deploy:
85+
environment:
86+
name: github-pages
87+
url: ${{ steps.deployment.outputs.page_url }}
88+
runs-on: ubuntu-latest
89+
needs: build
90+
steps:
91+
- name: Deploy to GitHub Pages
92+
id: deployment
93+
uses: actions/deploy-pages@v4

archetypes/default.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
+++
2+
date = '{{ .Date }}'
3+
draft = true
4+
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
5+
+++

assets/css/main.css

+17-4
Original file line numberDiff line numberDiff line change
@@ -100,10 +100,10 @@ input, select, textarea {
100100

101101
body {
102102
background-color: #e6e6fa;
103-
background-image: url("images/overlay.png"), -moz-linear-gradient(45deg, #8e8eff 15%, #F0F0F1 85%);
104-
background-image: url("images/overlay.png"), -webkit-linear-gradient(45deg, #8e8eff 15%, #F0F0F1 85%);
105-
background-image: url("images/overlay.png"), -ms-linear-gradient(45deg, #8e8eff 15%, #F0F0F1 85%);
106-
background-image: url("images/overlay.png"), linear-gradient(45deg, #8e8eff 15%, #F0F0F1 85%);
103+
background-image: url("/images/overlay.png"), -moz-linear-gradient(45deg, #8e8eff 15%, #F0F0F1 85%);
104+
background-image: url("/images/overlay.png"), -webkit-linear-gradient(45deg, #8e8eff 15%, #F0F0F1 85%);
105+
background-image: url("/images/overlay.png"), -ms-linear-gradient(45deg, #8e8eff 15%, #F0F0F1 85%);
106+
background-image: url("/images/overlay.png"), linear-gradient(45deg, #8e8eff 15%, #F0F0F1 85%);
107107
}
108108

109109
body.is-preload *, body.is-preload *:before, body.is-preload *:after {
@@ -2630,6 +2630,19 @@ input, select, textarea {
26302630
padding-right: 0 !important;
26312631
}
26322632

2633+
section.normal {
2634+
text-align: left;
2635+
}
2636+
2637+
section.normal header.major h2:after, article.special header.major h2:after {
2638+
margin-left: auto;
2639+
margin-right: auto;
2640+
}
2641+
2642+
2643+
section.normal h2 {
2644+
text-align: center;
2645+
}
26332646
/* Section/Article */
26342647

26352648
section.special, article.special {

content/_index.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
+++
2+
title = 'Home'
3+
date = 2023-01-01T08:00:00-07:00
4+
draft = false
5+
+++
6+
7+
The EVM Object Format (EOF) is an important upgrade for the Ethereum Virtual
8+
Machine, comprising [a series of
9+
EIPs](https://eips.ethereum.org/EIPS/eip-7692). It introduces an extensible and versioned container format for EVM bytecode
10+
with a once-off validation at deploy time, focusing on separating code and
11+
data, enhancing code validation, and improving overall efficiency.

content/faq.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
type: faq
3+
order: 1
4+
---
5+
6+
<details>
7+
<summary><strong>Q: Is EOF a brand-new EVM replacing the old legacy EVM? </strong></summary>
8+
9+
No, EOF updates only a small part of the EVM. EOF is first and foremost a container format for EVM code.
10+
11+
Most of the EVM — opcodes, operand stack, storage, accounts, memory, and more — stays the same. In that sense the "Legacy EVM" here only means the 16 opcodes not accessible to EOF code and the patterns they enable. Some new opcodes (like `EXTCALL` and `EOFCREATE`) reuse old logic, so the effective change is even smaller.
12+
13+
</details>
14+
15+
<details>
16+
<summary><strong>Q: Why does EOF seem so complex?</strong></summary>
17+
18+
EOF is often **perceived** to be more complex than it is.
19+
20+
People think it’s complex because it involves many EIPs and opcodes. The large number of EIPs is because EOF’s parts were debated separately in the past, but now they are all part of one cohesive change. Because of that the total number of opcode changes is bigger than usual since EOF implements many features (static jumps, code and data separation, banning code introspection, etc.) in one step. Still, it only affects a small fraction of opcodes, and much of the logic within those opcodes is shared with the opcodes they are replacing.
21+
22+
However, EOF is admittedly a complex EVM change. Emphasis is being put on proper testing (with the modern testing machinery provided by [EEST](https://github.com/ethereum/execution-spec-tests)), fuzzing, and explicit specification clarity in order to carry it through. The EVM ecosystem is today mature enough to deliver on such a complex EVM upgrade, which has also itself matured over the years having been analyzed and investigated by many independent contributors.
23+
24+
</details>
25+
26+
<details>
27+
<summary><strong>Q: Couldn’t we split EOF into smaller
28+
changes?</strong></summary>
29+
30+
No, breaking it into pieces makes it more complex long-term. Multiple updates would force clients to support multiple different EVM versions forever, which gets messy. EOF bundles all the breaking changes that would be done in multiple steps into one step.
31+
32+
Piecemeal changes can also clash. For example, an old versioning idea ([EIP-1702](https://eips.ethereum.org/EIPS/eip-1702)) becomes more complicated with other peacemeal changes like [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702), causing increasing complexity. One big update reduces these unexpected interactions and avoids risky in-between states.
33+
34+
Piecemeal changes were also tried in the past (see [EIP-2315](https://eips.ethereum.org/EIPS/eip-2315), [EIP-1702](https://eips.ethereum.org/EIPS/eip-1702), [EIP-663](https://eips.ethereum.org/EIPS/eip-663), and [EIP-615](https://eips.ethereum.org/EIPS/eip-615)), but these changes were also rejected for not providing enough impact and not integrating well with other parts of the EVM. Feedback such as this led us to present EOF in one large change.
35+
36+
</details>
37+
38+
<details>
39+
<summary><strong>Q: Why not do [Feature X] by itself?</strong></summary>
40+
41+
Each EOF feature needs a breaking change or relies on another feature to work safely. Here’s why some can’t stand alone:
42+
43+
- **Opcodes with Immediates (RJUMP/RJUMPI, DUPN/SWAPN)**: Need versioning to avoid breaking old code or adding complexity. Past tries (like earlier versions of EIP-663) failed without EOF’s structure.
44+
45+
- **Code Validation**: Needs versioning and separating code and data, too. Without it, you’d track versions separately (tried and dropped in EIP-1702). New features like EIP-7702 make this harder. EOF puts versioning in the code itself and adds data sections naturally.
46+
47+
- **Removing Gas Introspection**: Bundling this with EOFv1 avoids needing an EOFv2 later, keeping EVM versions low.
48+
49+
- **Removing Code Introspection**: A halfway change that doesn't include this adds more versions.
50+
51+
- **Subroutines**: An earlier proposal (EIP-2315) was rejected as too weak. EOF’s approach has support from the Solidity team. The supported solution is also tightly integrated with the container format.
52+
53+
- **Address Space Expansion**: Needs versioning to protect old contracts.
54+
55+
- **Removing Dynamic Jumps (e.g., `JUMP`/`JUMPI`)**: Alternative without immediates requires more complicated validation rules checked during every opcode evaluation.
56+
57+
Piecemeal changes mean more EVM versions, confusing rules, and harder upgrades. EOF keeps it to one new version.
58+
59+
</details>
60+
61+
<details>
62+
<summary><strong>Q: Why not drop codesize limits and use EIP-3860
63+
metering?</strong></summary>
64+
65+
[EIP-3860](https://eips.ethereum.org/EIPS/eip-3860) fixed missing gas charge for JUMPDEST analysis during contract deployment, but it doesn’t cover loading contracts during regular execution. JUMPDEST analysis still needs to happen every time a contract runs, or the results need to be cached. EOF's advantage is that it validates code just once, when it’s added to the blockchain. After that, no extra checks are needed for execution or contract creation. This makes EOF simpler and faster in practice.
66+
67+
</details>
68+
69+
<details>
70+
<summary><strong>Q: Can’t we just remove the need for JUMPDESTs and jump analysis?</strong></summary>
71+
72+
No, removing JUMPDESTs produces more problems that it solves. `JUMPDEST`s fix analysis issues with dynamic jumps, making compilation (like via LLVM) and static analysis a tractable problem. Without them, zkEVMs and control flow analysis get much harder. Plus, it risks running data as code, a security issue. [This article](https://ethereum-magicians.org/t/why-evm-has-jumpdest/23288) explains more.
73+
74+
</details>
75+
76+
<details>
77+
<summary><strong>Q: Can't we fix Solidity's "stack too deep" without DUPN/SWAPN?</strong></summary>
78+
79+
Compilers indeed can solve the “stack too deep” problem with register allocation but they cannot guarantee an optimal solution. Even when they do determine an optimal solution the use of stack/register spilling is very cost ineffective without reliable access to cheap memory. The EVM’s non-linear gas cost for memory makes access to larger variable pools more expensive and fragile than a paged memory model like one in typical silicon processors.
80+
81+
With this in mind, solving this problem on the compiler level is just a trade-off, rather than a direct improvement. Efficient and safe upgrade to EVM’s stack management is important, [EIP-663](https://eips.ethereum.org/EIPS/eip-663) achieves that. Because it relies on immediate arguments to the opcode it requires the versioned container EOF provides.
82+
83+
</details>
84+
85+
<details>
86+
<summary><strong>Q: How much does EOF help the Solidity
87+
compiler?</strong></summary>
88+
89+
The Solidity team has expressed multiple times that EOF is their preferred solution "by orders of magnitude," and that it enables many Developer Experience (Devex) improvements. [You can read about it in their own words](https://notes.ethereum.org/@solidity/the-case-for-eof).
90+
91+
</details>

content/implementation.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
type: implementation
3+
order: 1
4+
---
5+
## Implementation
6+
7+
EOF has been implemented in the following clients and projects.
8+
9+
| |[3540](https://eips.ethereum.org/EIPS/eip-3540)|[3670](https://eips.ethereum.org/EIPS/eip-3670)|[4200](https://eips.ethereum.org/EIPS/eip-4200)|[4750](https://eips.ethereum.org/EIPS/eip-4750)|[5450](https://eips.ethereum.org/EIPS/eip-5450)|[6206](https://eips.ethereum.org/EIPS/eip-6206)|[7480](https://eips.ethereum.org/EIPS/eip-7480)|[7069](https://eips.ethereum.org/EIPS/eip-7069)|[7620](https://eips.ethereum.org/EIPS/eip-7620)|[7698](https://eips.ethereum.org/EIPS/eip-7698)|[663](https://eips.ethereum.org/EIPS/eip-663)|
10+
|--------------------------------------------------------------------------------------------|:---|:-----|:---|:---|:----|:---|:---|:---|:---|:---|:---|
11+
| [Megaspec](https://github.com/ipsilon/eof/blob/main/spec/eof.md) ||||||||||||
12+
| EIP ||||||||||||
13+
| Testing ||||||| 🚧 | 🚧 | 🚧 | ||
14+
| [besu](https://github.com/hyperledger/besu/tree/mega-eof) ||||||||||||
15+
| erigon | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | | | | 🚧 |
16+
| [ethereumjs](https://github.com/ethereumjs/ethereumjs-monorepo/pull/3440) | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 |
17+
| [evmone](https://github.com/ethereum/evmone) ||||||||||||
18+
| [geth](https://github.com/ethereum/go-ethereum/pull/29518) | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | 🚧 | | 🚧 |
19+
| [nethermind](https://github.com/NethermindEth/nethermind/commits/feature/evm/eof) ||||||||||||
20+
| revm ||||||||||||
21+
| [solidity (experimental)](https://github.com/ethereum/solidity/releases/tag/v0.8.29) || N/A ||| N/A |||||||
22+

content/motivation/motivation_1.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
type: motivation
3+
order: 1
4+
---
5+
6+
### Code validation at deploy time
7+
8+
Instead of having the interpreter validate instructions repeatedly at runtime,
9+
EVM bytecode is validated only once during contract creation, providing
10+
a faster, cheaper, and more secure execution.
11+

content/motivation/motivation_2.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
### Code-data separation
2+
3+
EOF separates EVM bytecode from data, making it easier for static analysis
4+
tools, formal verification, and L2s to process executable code.
5+

content/motivation/motivation_3.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### Removal of dynamic JUMPs
2+
3+
EOF bytecode uses only [static relative
4+
jumps](https://eips.ethereum.org/EIPS/eip-4200), which is very desirable for
5+
tools involving static analysis, formal verification, compilation to native
6+
code, zero-knowledge circuits, as well as L2 EVMs.
7+

content/motivation/motivation_4.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
### Code and gas non-observability
2+
3+
Lack of code and gas observability is a [long-sought trait of the
4+
EVM](https://ethereum-magicians.org/t/eof-proposal-ban-code-introspection-of-eof-accounts/12113)
5+
allowing a more maintainable and upgradeable protocol.
6+

content/motivation/motivation_5.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### Removal of JUMPDEST-analysis
2+
3+
By obsoleting JUMPDEST-analysis done at contract runtime, EOF simplifies
4+
reasoning about EVM bytecode, as well as other changes, like
5+
[EVMMAX](https://eips.ethereum.org/EIPS/eip-6690), [Verkle](https://verkle.info)
6+
or bytecode size increase.
7+

content/motivation/motivation_6.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### First-class support for EVM functions
2+
3+
[Functions in EOF](https://eips.ethereum.org/EIPS/eip-4750) are a subroutine
4+
mechanism not relying on dynamic jumps. It improves analysis opportunities by
5+
encoding the number of inputs and outputs for each given function, and
6+
isolating the stack of each function.
7+

content/motivation/motivation_7.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
### Code versioning
2+
3+
Introducing versioning will make backwards-incompatible upgrades much easier. Backwards compatible changes can be done without bumping the EOF version, even if new instructions are introduced.
4+

content/motivation/motivation_8.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
### Addressing EVM pain points
2+
3+
EOF proposals address many long-standing issues and quirks of the EVM, streamlining compiler development, providing new compiler optimization opportunities, and ultimately improving developer experience. An example of this are the new improved stack management instructions.
4+

content/resources/resources.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
type: resources
3+
order: 1
4+
---
5+
6+
## Resources
7+
8+
[eof.wtf](https://eof.wtf): EOF Parser and Visualizer.
9+
10+
[evm.codes](https://www.evm.codes/?fork=EOF): EVM Opcode Reference
11+
(Deprecated opcodes have yet to be removed).
12+
13+
[EOF taxonomy infographic](https://x.com/rakitadragan/status/1825174503548178843) by Dragan Rakita.

content/resources/talks.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
type: resources
3+
order: 2
4+
---
5+
6+
## Talks/Videos
7+
8+
[EOF Explanation](https://www.youtube.com/watch?v=3-bAWOBemyc) by Uttam Singh
9+
10+
[EOF - History and Motivation](https://www.youtube.com/watch?v=X2mlptWzphc) by Danno Ferrin (Devcon 7)
11+
12+
[EOF - Managing the bytecode chaos](https://www.youtube.com/watch?v=WKVgCoNp39g) by Alex Murashkin (Devcon 7)
13+
14+
[Zoom in on EOF stack validation](https://www.youtube.com/watch?v=80szRrNW0MM) by Andrei Maiboroda (Devcon 7)
15+
16+
[The Future of EOF: Layer 1, Layer 2, and Beyond!](https://www.youtube.com/watch?v=NeKMerFPJoM) by Danno Ferrin (Devcon 7)

hugo.toml

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
baseURL = 'https://evmobjectformat.org/'
2+
languageCode = 'en-us'
3+
title = 'EOF - EVM Object Format'
4+
5+
disableKinds = ["taxonomy"]
6+
ignoreErrors = ["error-disable-taxonomy"]
7+
8+
[markup.goldmark.renderer]
9+
unsafe = true
10+
11+
[caches]
12+
[caches.images]
13+
dir = ':cacheDir/images'

0 commit comments

Comments
 (0)