You are going to do a large scale refactor as a zig bot. Your goal is to only focus on idiomatic language usage as well as optimal performance. │
│ I will share the entire language spec so you can play role as language expert. I will also share std lib context[Pasted text #1 │
│ +11852 lines]https://ziglang.org/documentation/master/std/visit the docs here and casually explore the std docs to become │
│ familiarread src/evm/README.md to become familiar with project. Note we are only interested in src/evm/**/*.zigmake a │
│ markdown todo list of every file in the evm packagegrab next item on listAudit that file and fix │
│ any idiomatic zig things regarding more idiomatic use of language, better use of standard library, or more performant codemake sure no regressions │
│ via running all tests `zig build test-all`You should use git submodules. make a branch. Then check it out in g/ │
│ wwork on isolation. Commit as you work. Once your job is complete and you deleted the todo file please squash all your commits together into a single commit │
│ with message aggregating the stylestic changes you made as well as including this original prompt. You may want to include original prompt in your todo file so │
│ you don't forget it.every file in src/evm/**/*.zig is audited for idiomatic performant zig code making great use of standard │
│ library<>standard lib https://ziglang.org/documentation/master/std/><>language │
│ https://ziglang.org/documentation/master/>
Zig Language Reference
Zig Version
0.1.1 | 0.2.0 | 0.3.0 | 0.4.0 | 0.5.0 | 0.6.0 | 0.7.1 | 0.8.1 | 0.9.1 | 0.10.1 | 0.11.0 | 0.12.0 | 0.13.0 | 0.14.1 | master
Table of Contents
Introduction
Zig Standard Library
Hello World
Comments
Doc Comments
Top-Level Doc Comments
Values
Primitive Types
Primitive Values
String Literals and Unicode Code Point Literals
Escape Sequences
Multiline String Literals
Assignment
undefined
Destructuring
Zig Test
Test Declarations
Doctests
Test Failure
Skip Tests
Report Memory Leaks
Detecting Test Build
Test Output and Logging
The Testing Namespace
Test Tool Documentation
Variables
Identifiers
Container Level Variables
Static Local Variables
Thread Local Variables
Local Variables
Integers
Integer Literals
Runtime Integer Values
Floats
Float Literals
Floating Point Operations
Operators
Table of Operators
Precedence
Arrays
Multidimensional Arrays
Sentinel-Terminated Arrays
Destructuring Arrays
Vectors
Destructuring Vectors
Pointers
volatile
Alignment
allowzero
Sentinel-Terminated Pointers
Slices
Sentinel-Terminated Slices
struct
Default Field Values
Faulty Default Field Values
extern struct
packed struct
Struct Naming
Anonymous Struct Literals
Tuples
Destructuring Tuples
enum
extern enum
Enum Literals
Non-exhaustive enum
union
Tagged union
extern union
packed union
Anonymous Union Literals
opaque
Blocks
Shadowing
Empty Blocks
switch
Exhaustive Switching
Switching with Enum Literals
Labeled switch
Inline Switch Prongs
while
Labeled while
while with Optionals
while with Error Unions
inline while
for
Labeled for
inline for
if
if with Optionals
defer
unreachable
Basics
At Compile-Time
noreturn
Functions
Pass-by-value Parameters
Function Parameter Type Inference
inline fn
Function Reflection
Errors
Error Set Type
The Global Error Set
Error Union Type
catch
try
errdefer
Merging Error Sets
Inferred Error Sets
Error Return Traces
Implementation Details
Optionals
Optional Type
null
Optional Pointers
Casting
Type Coercion
Type Coercion: Stricter Qualification
Type Coercion: Integer and Float Widening
Type Coercion: Float to Int
Type Coercion: Slices, Arrays and Pointers
Type Coercion: Optionals
Type Coercion: Error Unions
Type Coercion: Compile-Time Known Numbers
Type Coercion: Unions and Enums
Type Coercion: undefined
Type Coercion: Tuples to Arrays
Explicit Casts
Peer Type Resolution
Zero Bit Types
void
Result Location Semantics
Result Types
Result Locations
usingnamespace
comptime
Introducing the Compile-Time Concept
Compile-Time Parameters
Compile-Time Variables
Compile-Time Expressions
Generic Data Structures
Case Study: print in Zig
Assembly
Output Constraints
Input Constraints
Clobbers
Global Assembly
Atomics
Async Functions
Builtin Functions
@addrSpaceCast
@addWithOverflow
@alignCast
@alignOf
@as
@atomicLoad
@atomicRmw
@atomicStore
@bitCast
@bitOffsetOf
@bitSizeOf
@branchHint
@breakpoint
@mulAdd
@byteSwap
@bitReverse
@offsetOf
@call
@cDefine
@cImport
@cInclude
@clz
@cmpxchgStrong
@cmpxchgWeak
@compileError
@compileLog
@constCast
@ctz
@cUndef
@cVaArg
@cVaCopy
@cVaEnd
@cVaStart
@divExact
@divFloor
@divTrunc
@embedFile
@enumFromInt
@errorFromInt
@errorName
@errorReturnTrace
@errorCast
@export
@extern
@field
@fieldParentPtr
@FieldType
@floatCast
@floatFromInt
@frameAddress
@hasDecl
@hasField
@import
@inComptime
@intCast
@intFromBool
@intFromEnum
@intFromError
@intFromFloat
@intFromPtr
@max
@memcpy
@memset
@memmove
@min
@wasmMemorySize
@wasmMemoryGrow
@mod
@mulWithOverflow
@panic
@popCount
@prefetch
@ptrCast
@ptrFromInt
@rem
@returnAddress
@select
@setEvalBranchQuota
@setFloatMode
@setRuntimeSafety
@shlExact
@shlWithOverflow
@shrExact
@shuffle
@sizeOf
@splat
@reduce
@src
@sqrt
@sin
@cos
@tan
@exp
@exp2
@log
@log2
@log10
@abs
@floor
@ceil
@trunc
@round
@subWithOverflow
@tagName
@This
@trap
@truncate
@Type
@typeInfo
@typeName
@TypeOf
@unionInit
@Vector
@volatileCast
@workGroupId
@workGroupSize
@workItemId
Build Mode
Debug
ReleaseFast
ReleaseSafe
ReleaseSmall
Single Threaded Builds
Illegal Behavior
Reaching Unreachable Code
Index out of Bounds
Cast Negative Number to Unsigned Integer
Cast Truncates Data
Integer Overflow
Default Operations
Standard Library Math Functions
Builtin Overflow Functions
Wrapping Operations
Exact Left Shift Overflow
Exact Right Shift Overflow
Division by Zero
Remainder Division by Zero
Exact Division Remainder
Attempt to Unwrap Null
Attempt to Unwrap Error
Invalid Error Code
Invalid Enum Cast
Invalid Error Set Cast
Incorrect Pointer Alignment
Wrong Union Field Access
Out of Bounds Float to Integer Cast
Pointer Cast Invalid Null
Memory
Choosing an Allocator
Where are the bytes?
Implementing an Allocator
Heap Allocation Failure
Recursion
Lifetime and Ownership
Compile Variables
Compilation Model
Source File Structs
File and Declaration Discovery
Special Root Declarations
Entry Point
Standard Library Options
Panic Handler
Zig Build System
C
C Type Primitives
Import from C Header File
C Translation CLI
Command line flags
Using -target and -cflags
@cImport vs translate-c
C Translation Caching
Translation failures
C Macros
C Pointers
C Variadic Functions
Exporting a C Library
Mixing Object Files
WebAssembly
Freestanding
WASI
Targets
Style Guide
Avoid Redundancy in Names
Avoid Redundant Names in Fully-Qualified Namespaces
Whitespace
Names
Examples
Doc Comment Guidance
Source Encoding
Keyword Reference
Appendix
Containers
Grammar
Zen
Introduction
Zig is a general-purpose programming language and toolchain for maintaining robust, optimal, and reusable software.
Robust
Behavior is correct even for edge cases such as out of memory.
Optimal
Write programs the best way they can behave and perform.
Reusable
The same code works in many environments which have different constraints.
Maintainable
Precisely communicate intent to the compiler and other programmers. The language imposes a low overhead to reading code and is resilient to changing requirements and environments.
Often the most efficient way to learn something new is to see examples, so this documentation shows how to use each of Zig's features. It is all on one page so you can search with your browser's search tool.
The code samples in this document are compiled and tested as part of the main test suite of Zig.
This HTML document depends on no external files, so you can use it offline.
Zig Standard Library
The Zig Standard Library has its own documentation.
Zig's Standard Library contains commonly used algorithms, data structures, and definitions to help you build programs or libraries. You will see many examples of Zig's Standard Library used in this documentation. To learn more about the Zig Standard Library, visit the link above.
Alternatively, the Zig Standard Library documentation is provided with each Zig distribution. It can be rendered via a local webserver with:
Shell
zig std
Hello World
hello.zig
const std = @import("std");
pub fn main() !void {
const stdout = std.io.getStdOut().writer();
try stdout.print("Hello, {s}!\n", .{"world"});
}
Shell
$ zig build-exe hello.zig
$ ./hello
Hello, world!
Most of the time, it is more appropriate to write to stderr rather than stdout, and whether or not the message is successfully written to the stream is irrelevant. For this common case, there is a simpler API:
hello_again.zig
const std = @import("std");
pub fn main() void {
std.debug.print("Hello, world!\n", .{});
}
Shell
$ zig build-exe hello_again.zig
$ ./hello_again
Hello, world!
In this case, the ! may be omitted from the return type of main because no errors are returned from the function.
See also:
Values
Tuples
@import
Errors
Entry Point
Source Encoding
try
Comments
Zig supports 3 types of comments. Normal comments are ignored, but doc comments and top-level doc comments are used by the compiler to generate the package documentation.
The generated documentation is still experimental, and can be produced with:
Shell
zig test -femit-docs main.zig
comments.zig
const print = @import("std").debug.print;
pub fn main() void {
// Comments in Zig start with "//" and end at the next LF byte (end of line).
// The line below is a comment and won't be executed.
//print("Hello?", .{});
print("Hello, world!\n", .{}); // another comment
}
Shell
$ zig build-exe comments.zig
$ ./comments
Hello, world!
There are no multiline comments in Zig (e.g. like /* */ comments in C). This allows Zig to have the property that each line of code can be tokenized out of context.
Doc Comments
A doc comment is one that begins with exactly three slashes (i.e. /// but not ////); multiple doc comments in a row are merged together to form a multiline doc comment. The doc comment documents whatever immediately follows it.
doc_comments.zig
/// A structure for storing a timestamp, with nanosecond precision (this is a
/// multiline doc comment).
const Timestamp = struct {
/// The number of seconds since the epoch (this is also a doc comment).
seconds: i64, // signed so we can represent pre-1970 (not a doc comment)
/// The number of nanoseconds past the second (doc comment again).
nanos: u32,
/// Returns a `Timestamp` struct representing the Unix epoch; that is, the
/// moment of 1970 Jan 1 00:00:00 UTC (this is a doc comment too).
pub fn unixEpoch() Timestamp {
return Timestamp{
.seconds = 0,
.nanos = 0,
};
}
};
Doc comments are only allowed in certain places; it is a compile error to have a doc comment in an unexpected place, such as in the middle of an expression, or just before a non-doc comment.
invalid_doc-comment.zig
/// doc-comment
//! top-level doc-comment
const std = @import("std");
Shell
$ zig build-obj invalid_doc-comment.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/invalid_doc-comment.zig:1:16: error: expected type expression, found 'a document comment'
/// doc-comment
^
unattached_doc-comment.zig
pub fn main() void {}
/// End of file
Shell
$ zig build-obj unattached_doc-comment.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/unattached_doc-comment.zig:3:1: error: unattached documentation comment
/// End of file
^~~~~~~~~~~~~~~
Doc comments can be interleaved with normal comments. Currently, when producing the package documentation, normal comments are merged with doc comments.
Top-Level Doc Comments
A top-level doc comment is one that begins with two slashes and an exclamation point: //!; it documents the current module.
It is a compile error if a top-level doc comment is not placed at the start of a container, before any expressions.
tldoc_comments.zig
//! This module provides functions for retrieving the current date and
//! time with varying degrees of precision and accuracy. It does not
//! depend on libc, but will use functions from it if available.
const S = struct {
//! Top level comments are allowed inside a container other than a module,
//! but it is not very useful. Currently, when producing the package
//! documentation, these comments are ignored.
};
Values
values.zig
// Top-level declarations are order-independent:
const print = std.debug.print;
const std = @import("std");
const os = std.os;
const assert = std.debug.assert;
pub fn main() void {
// integers
const one_plus_one: i32 = 1 + 1;
print("1 + 1 = {}\n", .{one_plus_one});
// floats
const seven_div_three: f32 = 7.0 / 3.0;
print("7.0 / 3.0 = {}\n", .{seven_div_three});
// boolean
print("{}\n{}\n{}\n", .{
true and false,
true or false,
!true,
});
// optional
var optional_value: ?[]const u8 = null;
assert(optional_value == null);
print("\noptional 1\ntype: {}\nvalue: {?s}\n", .{
@TypeOf(optional_value), optional_value,
});
optional_value = "hi";
assert(optional_value != null);
print("\noptional 2\ntype: {}\nvalue: {?s}\n", .{
@TypeOf(optional_value), optional_value,
});
// error union
var number_or_error: anyerror!i32 = error.ArgNotFound;
print("\nerror union 1\ntype: {}\nvalue: {!}\n", .{
@TypeOf(number_or_error),
number_or_error,
});
number_or_error = 1234;
print("\nerror union 2\ntype: {}\nvalue: {!}\n", .{
@TypeOf(number_or_error), number_or_error,
});
}
Shell
$ zig build-exe values.zig
$ ./values
1 + 1 = 2
7.0 / 3.0 = 2.3333333e0
false
true
false
optional 1
type: ?[]const u8
value: null
optional 2
type: ?[]const u8
value: hi
error union 1
type: anyerror!i32
value: error.ArgNotFound
error union 2
type: anyerror!i32
value: 1234
Primitive Types
Primitive Types
Type C Equivalent Description
i8 int8_t signed 8-bit integer
u8 uint8_t unsigned 8-bit integer
i16 int16_t signed 16-bit integer
u16 uint16_t unsigned 16-bit integer
i32 int32_t signed 32-bit integer
u32 uint32_t unsigned 32-bit integer
i64 int64_t signed 64-bit integer
u64 uint64_t unsigned 64-bit integer
i128 __int128 signed 128-bit integer
u128 unsigned __int128 unsigned 128-bit integer
isize intptr_t signed pointer sized integer
usize uintptr_t, size_t unsigned pointer sized integer. Also see #5185
c_char char for ABI compatibility with C
c_short short for ABI compatibility with C
c_ushort unsigned short for ABI compatibility with C
c_int int for ABI compatibility with C
c_uint unsigned int for ABI compatibility with C
c_long long for ABI compatibility with C
c_ulong unsigned long for ABI compatibility with C
c_longlong long long for ABI compatibility with C
c_ulonglong unsigned long long for ABI compatibility with C
c_longdouble long double for ABI compatibility with C
f16 _Float16 16-bit floating point (10-bit mantissa) IEEE-754-2008 binary16
f32 float 32-bit floating point (23-bit mantissa) IEEE-754-2008 binary32
f64 double 64-bit floating point (52-bit mantissa) IEEE-754-2008 binary64
f80 long double 80-bit floating point (64-bit mantissa) IEEE-754-2008 80-bit extended precision
f128 _Float128 128-bit floating point (112-bit mantissa) IEEE-754-2008 binary128
bool bool true or false
anyopaque void Used for type-erased pointers.
void (none) Always the value void{}
noreturn (none) the type of break, continue, return, unreachable, and while (true) {}
type (none) the type of types
anyerror (none) an error code
comptime_int (none) Only allowed for comptime-known values. The type of integer literals.
comptime_float (none) Only allowed for comptime-known values. The type of float literals.
In addition to the integer types above, arbitrary bit-width integers can be referenced by using an identifier of i or u followed by digits. For example, the identifier i7 refers to a signed 7-bit integer. The maximum allowed bit-width of an integer type is 65535.
See also:
Integers
Floats
void
Errors
@Type
Primitive Values
Primitive Values
Name Description
true and false bool values
null used to set an optional type to null
undefined used to leave a value unspecified
See also:
Optionals
undefined
String Literals and Unicode Code Point Literals
String literals are constant single-item Pointers to null-terminated byte arrays. The type of string literals encodes both the length, and the fact that they are null-terminated, and thus they can be coerced to both Slices and Null-Terminated Pointers. Dereferencing string literals converts them to Arrays.
Because Zig source code is UTF-8 encoded, any non-ASCII bytes appearing within a string literal in source code carry their UTF-8 meaning into the content of the string in the Zig program; the bytes are not modified by the compiler. It is possible to embed non-UTF-8 bytes into a string literal using \xNN notation.
Indexing into a string containing non-ASCII bytes returns individual bytes, whether valid UTF-8 or not.
Unicode code point literals have type comptime_int, the same as Integer Literals. All Escape Sequences are valid in both string literals and Unicode code point literals.
string_literals.zig
const print = @import("std").debug.print;
const mem = @import("std").mem; // will be used to compare bytes
pub fn main() void {
const bytes = "hello";
print("{}\n", .{@TypeOf(bytes)}); // *const [5:0]u8
print("{d}\n", .{bytes.len}); // 5
print("{c}\n", .{bytes[1]}); // 'e'
print("{d}\n", .{bytes[5]}); // 0
print("{}\n", .{'e' == '\x65'}); // true
print("{d}\n", .{'\u{1f4a9}'}); // 128169
print("{d}\n", .{'💯'}); // 128175
print("{u}\n", .{'⚡'});
print("{}\n", .{mem.eql(u8, "hello", "h\x65llo")}); // true
print("{}\n", .{mem.eql(u8, "💯", "\xf0\x9f\x92\xaf")}); // also true
const invalid_utf8 = "\xff\xfe"; // non-UTF-8 strings are possible with \xNN notation.
print("0x{x}\n", .{invalid_utf8[1]}); // indexing them returns individual bytes...
print("0x{x}\n", .{"💯"[1]}); // ...as does indexing part-way through non-ASCII characters
}
Shell
$ zig build-exe string_literals.zig
$ ./string_literals
*const [5:0]u8
5
e
0
true
128169
128175
⚡
true
true
0xfe
0x9f
See also:
Arrays
Source Encoding
Escape Sequences
Escape Sequences
Escape Sequence Name
\n Newline
\r Carriage Return
\t Tab
\\ Backslash
\' Single Quote
\" Double Quote
\xNN hexadecimal 8-bit byte value (2 digits)
\u{NNNNNN} hexadecimal Unicode scalar value UTF-8 encoded (1 or more digits)
Note that the maximum valid Unicode scalar value is 0x10ffff.
Multiline String Literals
Multiline string literals have no escapes and can span across multiple lines. To start a multiline string literal, use the \\ token. Just like a comment, the string literal goes until the end of the line. The end of the line is not included in the string literal. However, if the next line begins with \\ then a newline is appended and the string literal continues.
multiline_string_literals.zig
const hello_world_in_c =
\\#include
\\
\\int main(int argc, char **argv) {
\\ printf("hello world\n");
\\ return 0;
\\}
;
See also:
@embedFile
Assignment
Use the const keyword to assign a value to an identifier:
constant_identifier_cannot_change.zig
const x = 1234;
fn foo() void {
// It works at file scope as well as inside functions.
const y = 5678;
// Once assigned, an identifier cannot be changed.
y += 1;
}
pub fn main() void {
foo();
}
Shell
$ zig build-exe constant_identifier_cannot_change.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/constant_identifier_cannot_change.zig:8:5: error: cannot assign to constant
y += 1;
^
referenced by:
main: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/constant_identifier_cannot_change.zig:12:8
callMain [inlined]: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22
callMainWithArgs [inlined]: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:635:20
posixCallMainAndExit: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:590:36
2 reference(s) hidden; use '-freference-trace=6' to see all references
const applies to all of the bytes that the identifier immediately addresses. Pointers have their own const-ness.
If you need a variable that you can modify, use the var keyword:
mutable_var.zig
const print = @import("std").debug.print;
pub fn main() void {
var y: i32 = 5678;
y += 1;
print("{d}", .{y});
}
Shell
$ zig build-exe mutable_var.zig
$ ./mutable_var
5679
Variables must be initialized:
var_must_be_initialized.zig
pub fn main() void {
var x: i32;
x = 1;
}
Shell
$ zig build-exe var_must_be_initialized.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/var_must_be_initialized.zig:2:15: error: expected '=', found ';'
var x: i32;
^
undefined
Use undefined to leave variables uninitialized:
assign_undefined.zig
const print = @import("std").debug.print;
pub fn main() void {
var x: i32 = undefined;
x = 1;
print("{d}", .{x});
}
Shell
$ zig build-exe assign_undefined.zig
$ ./assign_undefined
1
undefined can be coerced to any type. Once this happens, it is no longer possible to detect that the value is undefined. undefined means the value could be anything, even something that is nonsense according to the type. Translated into English, undefined means "Not a meaningful value. Using this value would be a bug. The value will be unused, or overwritten before being used."
In Debug and ReleaseSafe mode, Zig writes 0xaa bytes to undefined memory. This is to catch bugs early, and to help detect use of undefined memory in a debugger. However, this behavior is only an implementation feature, not a language semantic, so it is not guaranteed to be observable to code.
Destructuring
A destructuring assignment can separate elements of indexable aggregate types (Tuples, Arrays, Vectors):
destructuring_to_existing.zig
const print = @import("std").debug.print;
pub fn main() void {
var x: u32 = undefined;
var y: u32 = undefined;
var z: u32 = undefined;
const tuple = .{ 1, 2, 3 };
x, y, z = tuple;
print("tuple: x = {}, y = {}, z = {}\n", .{x, y, z});
const array = [_]u32{ 4, 5, 6 };
x, y, z = array;
print("array: x = {}, y = {}, z = {}\n", .{x, y, z});
const vector: @Vector(3, u32) = .{ 7, 8, 9 };
x, y, z = vector;
print("vector: x = {}, y = {}, z = {}\n", .{x, y, z});
}
Shell
$ zig build-exe destructuring_to_existing.zig
$ ./destructuring_to_existing
tuple: x = 1, y = 2, z = 3
array: x = 4, y = 5, z = 6
vector: x = 7, y = 8, z = 9
A destructuring expression may only appear within a block (i.e. not at container scope). The left hand side of the assignment must consist of a comma separated list, each element of which may be either an lvalue (for instance, an existing `var`) or a variable declaration:
destructuring_mixed.zig
const print = @import("std").debug.print;
pub fn main() void {
var x: u32 = undefined;
const tuple = .{ 1, 2, 3 };
x, var y : u32, const z = tuple;
print("x = {}, y = {}, z = {}\n", .{x, y, z});
// y is mutable
y = 100;
// You can use _ to throw away unwanted values.
_, x, _ = tuple;
print("x = {}", .{x});
}
Shell
$ zig build-exe destructuring_mixed.zig
$ ./destructuring_mixed
x = 1, y = 2, z = 3
x = 2
A destructure may be prefixed with the comptime keyword, in which case the entire destructure expression is evaluated at comptime. All vars declared would be comptime vars and all expressions (both result locations and the assignee expression) are evaluated at comptime.
See also:
Destructuring Tuples
Destructuring Arrays
Destructuring Vectors
Zig Test
Code written within one or more test declarations can be used to ensure behavior meets expectations:
testing_introduction.zig
const std = @import("std");
test "expect addOne adds one to 41" {
// The Standard Library contains useful functions to help create tests.
// `expect` is a function that verifies its argument is true.
// It will return an error if its argument is false to indicate a failure.
// `try` is used to return an error to the test runner to notify it that the test failed.
try std.testing.expect(addOne(41) == 42);
}
test addOne {
// A test name can also be written using an identifier.
// This is a doctest, and serves as documentation for `addOne`.
try std.testing.expect(addOne(41) == 42);
}
/// The function `addOne` adds one to the number given as its argument.
fn addOne(number: i32) i32 {
return number + 1;
}
Shell
$ zig test testing_introduction.zig
1/2 testing_introduction.test.expect addOne adds one to 41...OK
2/2 testing_introduction.decltest.addOne...OK
All 2 tests passed.
The testing_introduction.zig code sample tests the function addOne to ensure that it returns 42 given the input 41. From this test's perspective, the addOne function is said to be code under test.
zig test is a tool that creates and runs a test build. By default, it builds and runs an executable program using the default test runner provided by the Zig Standard Library as its main entry point. During the build, test declarations found while resolving the given Zig source file are included for the default test runner to run and report on.
This documentation discusses the features of the default test runner as provided by the Zig Standard Library. Its source code is located in lib/compiler/test_runner.zig.
The shell output shown above displays two lines after the zig test command. These lines are printed to standard error by the default test runner:
1/2 testing_introduction.test.expect addOne adds one to 41...
Lines like this indicate which test, out of the total number of tests, is being run. In this case, 1/2 indicates that the first test, out of a total of two tests, is being run. Note that, when the test runner program's standard error is output to the terminal, these lines are cleared when a test succeeds.
2/2 testing_introduction.decltest.addOne...
When the test name is an identifier, the default test runner uses the text decltest instead of test.
All 2 tests passed.
This line indicates the total number of tests that have passed.
Test Declarations
Test declarations contain the keyword test, followed by an optional name written as a string literal or an identifier, followed by a block containing any valid Zig code that is allowed in a function.
Non-named test blocks always run during test builds and are exempt from Skip Tests.
Test declarations are similar to Functions: they have a return type and a block of code. The implicit return type of test is the Error Union Type anyerror!void, and it cannot be changed. When a Zig source file is not built using the zig test tool, the test declarations are omitted from the build.
Test declarations can be written in the same file, where code under test is written, or in a separate Zig source file. Since test declarations are top-level declarations, they are order-independent and can be written before or after the code under test.
See also:
The Global Error Set
Grammar
Doctests
Test declarations named using an identifier are doctests. The identifier must refer to another declaration in scope. A doctest, like a doc comment, serves as documentation for the associated declaration, and will appear in the generated documentation for the declaration.
An effective doctest should be self-contained and focused on the declaration being tested, answering questions a new user might have about its interface or intended usage, while avoiding unnecessary or confusing details. A doctest is not a substitute for a doc comment, but rather a supplement and companion providing a testable, code-driven example, verified by zig test.
Test Failure
The default test runner checks for an error returned from a test. When a test returns an error, the test is considered a failure and its error return trace is output to standard error. The total number of failures will be reported after all tests have run.
testing_failure.zig
const std = @import("std");
test "expect this to fail" {
try std.testing.expect(false);
}
test "expect this to succeed" {
try std.testing.expect(true);
}
Shell
$ zig test testing_failure.zig
1/2 testing_failure.test.expect this to fail...FAIL (TestUnexpectedResult)
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/testing.zig:586:14: 0x1032019 in expect (std.zig)
if (!ok) return error.TestUnexpectedResult;
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/testing_failure.zig:4:5: 0x1032076 in test.expect this to fail (testing_failure.zig)
try std.testing.expect(false);
^
2/2 testing_failure.test.expect this to succeed...OK
1 passed; 0 skipped; 1 failed.
error: the following test command failed with exit code 1:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/48f3ff852a8460792ceab1420717ec5e/test --seed=0x444ba11e
Skip Tests
One way to skip tests is to filter them out by using the zig test command line parameter --test-filter [text]. This makes the test build only include tests whose name contains the supplied filter text. Note that non-named tests are run even when using the --test-filter [text] command line parameter.
To programmatically skip a test, make a test return the error error.SkipZigTest and the default test runner will consider the test as being skipped. The total number of skipped tests will be reported after all tests have run.
testing_skip.zig
test "this will be skipped" {
return error.SkipZigTest;
}
Shell
$ zig test testing_skip.zig
1/1 testing_skip.test.this will be skipped...SKIP
0 passed; 1 skipped; 0 failed.
Report Memory Leaks
When code allocates Memory using the Zig Standard Library's testing allocator, std.testing.allocator, the default test runner will report any leaks that are found from using the testing allocator:
testing_detect_leak.zig
const std = @import("std");
test "detect leak" {
var list = std.ArrayList(u21).init(std.testing.allocator);
// missing `defer list.deinit();`
try list.append('☔');
try std.testing.expect(list.items.len == 1);
}
Shell
$ zig test testing_detect_leak.zig
1/1 testing_detect_leak.test.detect leak...OK
[gpa] (err): memory address 0x7f5738ba0000 leaked:
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/array_list.zig:474:67: 0x1097ead in ensureTotalCapacityPrecise (std.zig)
const new_memory = try self.allocator.alignedAlloc(T, alignment, new_capacity);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/array_list.zig:450:51: 0x105c787 in ensureTotalCapacity (std.zig)
return self.ensureTotalCapacityPrecise(better_capacity);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/array_list.zig:500:41: 0x103dee8 in addOne (std.zig)
try self.ensureTotalCapacity(newlen);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/array_list.zig:261:49: 0x103974c in append (std.zig)
const new_item_ptr = try self.addOne();
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/testing_detect_leak.zig:6:20: 0x10360a7 in test.detect leak (testing_detect_leak.zig)
try list.append('☔');
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x1193c58 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:64:28: 0x118d0e7 in main (test_runner.zig)
return mainTerminal();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x118621d in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x1185af3 in _start (std.zig)
asm volatile (switch (native_arch) {
^
All 1 tests passed.
1 errors were logged.
1 tests leaked memory.
error: the following test command failed with exit code 1:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/feba8548ab6b404d64d13c35f0abd4c0/test --seed=0x71d34d97
See also:
defer
Memory
Detecting Test Build
Use the compile variable @import("builtin").is_test to detect a test build:
testing_detect_test.zig
const std = @import("std");
const builtin = @import("builtin");
const expect = std.testing.expect;
test "builtin.is_test" {
try expect(isATest());
}
fn isATest() bool {
return builtin.is_test;
}
Shell
$ zig test testing_detect_test.zig
1/1 testing_detect_test.test.builtin.is_test...OK
All 1 tests passed.
Test Output and Logging
The default test runner and the Zig Standard Library's testing namespace output messages to standard error.
The Testing Namespace
The Zig Standard Library's testing namespace contains useful functions to help you create tests. In addition to the expect function, this document uses a couple of more functions as exemplified here:
testing_namespace.zig
const std = @import("std");
test "expectEqual demo" {
const expected: i32 = 42;
const actual = 42;
// The first argument to `expectEqual` is the known, expected, result.
// The second argument is the result of some expression.
// The actual's type is casted to the type of expected.
try std.testing.expectEqual(expected, actual);
}
test "expectError demo" {
const expected_error = error.DemoError;
const actual_error_union: anyerror!void = error.DemoError;
// `expectError` will fail when the actual error is different than
// the expected error.
try std.testing.expectError(expected_error, actual_error_union);
}
Shell
$ zig test testing_namespace.zig
1/2 testing_namespace.test.expectEqual demo...OK
2/2 testing_namespace.test.expectError demo...OK
All 2 tests passed.
The Zig Standard Library also contains functions to compare Slices, strings, and more. See the rest of the std.testing namespace in the Zig Standard Library for more available functions.
Test Tool Documentation
zig test has a few command line parameters which affect the compilation. See zig test --help for a full list.
Variables
A variable is a unit of Memory storage.
It is generally preferable to use const rather than var when declaring a variable. This causes less work for both humans and computers to do when reading code, and creates more optimization opportunities.
The extern keyword or @extern builtin function can be used to link against a variable that is exported from another object. The export keyword or @export builtin function can be used to make a variable available to other objects at link time. In both cases, the type of the variable must be C ABI compatible.
See also:
Exporting a C Library
Identifiers
Variable identifiers are never allowed to shadow identifiers from an outer scope.
Identifiers must start with an alphabetic character or underscore and may be followed by any number of alphanumeric characters or underscores. They must not overlap with any keywords. See Keyword Reference.
If a name that does not fit these requirements is needed, such as for linking with external libraries, the @"" syntax may be used.
identifiers.zig
const @"identifier with spaces in it" = 0xff;
const @"1SmallStep4Man" = 112358;
const c = @import("std").c;
pub extern "c" fn @"error"() void;
pub extern "c" fn @"fstat$INODE64"(fd: c.fd_t, buf: *c.Stat) c_int;
const Color = enum {
red,
@"really red",
};
const color: Color = .@"really red";
Container Level Variables
Container level variables have static lifetime and are order-independent and lazily analyzed. The initialization value of container level variables is implicitly comptime. If a container level variable is const then its value is comptime-known, otherwise it is runtime-known.
test_container_level_variables.zig
var y: i32 = add(10, x);
const x: i32 = add(12, 34);
test "container level variables" {
try expect(x == 46);
try expect(y == 56);
}
fn add(a: i32, b: i32) i32 {
return a + b;
}
const std = @import("std");
const expect = std.testing.expect;
Shell
$ zig test test_container_level_variables.zig
1/1 test_container_level_variables.test.container level variables...OK
All 1 tests passed.
Container level variables may be declared inside a struct, union, enum, or opaque:
test_namespaced_container_level_variable.zig
const std = @import("std");
const expect = std.testing.expect;
test "namespaced container level variable" {
try expect(foo() == 1235);
try expect(foo() == 1236);
}
const S = struct {
var x: i32 = 1234;
};
fn foo() i32 {
S.x += 1;
return S.x;
}
Shell
$ zig test test_namespaced_container_level_variable.zig
1/1 test_namespaced_container_level_variable.test.namespaced container level variable...OK
All 1 tests passed.
Static Local Variables
It is also possible to have local variables with static lifetime by using containers inside functions.
test_static_local_variable.zig
const std = @import("std");
const expect = std.testing.expect;
test "static local variable" {
try expect(foo() == 1235);
try expect(foo() == 1236);
}
fn foo() i32 {
const S = struct {
var x: i32 = 1234;
};
S.x += 1;
return S.x;
}
Shell
$ zig test test_static_local_variable.zig
1/1 test_static_local_variable.test.static local variable...OK
All 1 tests passed.
Thread Local Variables
A variable may be specified to be a thread-local variable using the threadlocal keyword, which makes each thread work with a separate instance of the variable:
test_thread_local_variables.zig
const std = @import("std");
const assert = std.debug.assert;
threadlocal var x: i32 = 1234;
test "thread local storage" {
const thread1 = try std.Thread.spawn(.{}, testTls, .{});
const thread2 = try std.Thread.spawn(.{}, testTls, .{});
testTls();
thread1.join();
thread2.join();
}
fn testTls() void {
assert(x == 1234);
x += 1;
assert(x == 1235);
}
Shell
$ zig test test_thread_local_variables.zig
1/1 test_thread_local_variables.test.thread local storage...OK
All 1 tests passed.
For Single Threaded Builds, all thread local variables are treated as regular Container Level Variables.
Thread local variables may not be const.
Local Variables
Local variables occur inside Functions, comptime blocks, and @cImport blocks.
When a local variable is const, it means that after initialization, the variable's value will not change. If the initialization value of a const variable is comptime-known, then the variable is also comptime-known.
A local variable may be qualified with the comptime keyword. This causes the variable's value to be comptime-known, and all loads and stores of the variable to happen during semantic analysis of the program, rather than at runtime. All variables declared in a comptime expression are implicitly comptime variables.
test_comptime_variables.zig
const std = @import("std");
const expect = std.testing.expect;
test "comptime vars" {
var x: i32 = 1;
comptime var y: i32 = 1;
x += 1;
y += 1;
try expect(x == 2);
try expect(y == 2);
if (y != 2) {
// This compile error never triggers because y is a comptime variable,
// and so `y != 2` is a comptime value, and this if is statically evaluated.
@compileError("wrong y value");
}
}
Shell
$ zig test test_comptime_variables.zig
1/1 test_comptime_variables.test.comptime vars...OK
All 1 tests passed.
Integers
Integer Literals
integer_literals.zig
const decimal_int = 98222;
const hex_int = 0xff;
const another_hex_int = 0xFF;
const octal_int = 0o755;
const binary_int = 0b11110000;
// underscores may be placed between two digits as a visual separator
const one_billion = 1_000_000_000;
const binary_mask = 0b1_1111_1111;
const permissions = 0o7_5_5;
const big_address = 0xFF80_0000_0000_0000;
Runtime Integer Values
Integer literals have no size limitation, and if any Illegal Behavior occurs, the compiler catches it.
However, once an integer value is no longer known at compile-time, it must have a known size, and is vulnerable to safety-checked Illegal Behavior.
runtime_vs_comptime.zig
fn divide(a: i32, b: i32) i32 {
return a / b;
}
In this function, values a and b are known only at runtime, and thus this division operation is vulnerable to both Integer Overflow and Division by Zero.
Operators such as + and - cause Illegal Behavior on integer overflow. Alternative operators are provided for wrapping and saturating arithmetic on all targets. +% and -% perform wrapping arithmetic while +| and -| perform saturating arithmetic.
Zig supports arbitrary bit-width integers, referenced by using an identifier of i or u followed by digits. For example, the identifier i7 refers to a signed 7-bit integer. The maximum allowed bit-width of an integer type is 65535. For signed integer types, Zig uses a two's complement representation.
See also:
Wrapping Operations
Floats
Zig has the following floating point types:
f16 - IEEE-754-2008 binary16
f32 - IEEE-754-2008 binary32
f64 - IEEE-754-2008 binary64
f80 - IEEE-754-2008 80-bit extended precision
f128 - IEEE-754-2008 binary128
c_longdouble - matches long double for the target C ABI
Float Literals
Float literals have type comptime_float which is guaranteed to have the same precision and operations of the largest other floating point type, which is f128.
Float literals coerce to any floating point type, and to any integer type when there is no fractional component.
float_literals.zig
const floating_point = 123.0E+77;
const another_float = 123.0;
const yet_another = 123.0e+77;
const hex_floating_point = 0x103.70p-5;
const another_hex_float = 0x103.70;
const yet_another_hex_float = 0x103.70P-5;
// underscores may be placed between two digits as a visual separator
const lightspeed = 299_792_458.000_000;
const nanosecond = 0.000_000_001;
const more_hex = 0x1234_5678.9ABC_CDEFp-10;
There is no syntax for NaN, infinity, or negative infinity. For these special values, one must use the standard library:
float_special_values.zig
const std = @import("std");
const inf = std.math.inf(f32);
const negative_inf = -std.math.inf(f64);
const nan = std.math.nan(f128);
Floating Point Operations
By default floating point operations use Strict mode, but you can switch to Optimized mode on a per-block basis:
float_mode_obj.zig
const std = @import("std");
const big = @as(f64, 1 << 40);
export fn foo_strict(x: f64) f64 {
return x + big - big;
}
export fn foo_optimized(x: f64) f64 {
@setFloatMode(.optimized);
return x + big - big;
}
Shell
$ zig build-obj float_mode_obj.zig -O ReleaseFast
For this test we have to separate code into two object files - otherwise the optimizer figures out all the values at compile-time, which operates in strict mode.
float_mode_exe.zig
const print = @import("std").debug.print;
extern fn foo_strict(x: f64) f64;
extern fn foo_optimized(x: f64) f64;
pub fn main() void {
const x = 0.001;
print("optimized = {}\n", .{foo_optimized(x)});
print("strict = {}\n", .{foo_strict(x)});
}
See also:
@setFloatMode
Division by Zero
Operators
There is no operator overloading. When you see an operator in Zig, you know that it is doing something from this table, and nothing else.
Table of Operators
Name Syntax Types Remarks Example
Addition
a + b
a += b
Integers
Floats
Can cause overflow for integers.
Invokes Peer Type Resolution for the operands.
See also @addWithOverflow.
2 + 5 == 7
Wrapping Addition
a +% b
a +%= b
Integers
Twos-complement wrapping behavior.
Invokes Peer Type Resolution for the operands.
See also @addWithOverflow.
@as(u32, 0xffffffff) +% 1 == 0
Saturating Addition
a +| b
a +|= b
Integers
Invokes Peer Type Resolution for the operands.
@as(u8, 255) +| 1 == @as(u8, 255)
Subtraction
a - b
a -= b
Integers
Floats
Can cause overflow for integers.
Invokes Peer Type Resolution for the operands.
See also @subWithOverflow.
2 - 5 == -3
Wrapping Subtraction
a -% b
a -%= b
Integers
Twos-complement wrapping behavior.
Invokes Peer Type Resolution for the operands.
See also @subWithOverflow.
@as(u8, 0) -% 1 == 255
Saturating Subtraction
a -| b
a -|= b
Integers
Invokes Peer Type Resolution for the operands.
@as(u32, 0) -| 1 == 0
Negation
-a
Integers
Floats
Can cause overflow for integers.
-1 == 0 - 1
Wrapping Negation
-%a
Integers
Twos-complement wrapping behavior.
-%@as(i8, -128) == -128
Multiplication
a * b
a *= b
Integers
Floats
Can cause overflow for integers.
Invokes Peer Type Resolution for the operands.
See also @mulWithOverflow.
2 * 5 == 10
Wrapping Multiplication
a *% b
a *%= b
Integers
Twos-complement wrapping behavior.
Invokes Peer Type Resolution for the operands.
See also @mulWithOverflow.
@as(u8, 200) *% 2 == 144
Saturating Multiplication
a *| b
a *|= b
Integers
Invokes Peer Type Resolution for the operands.
@as(u8, 200) *| 2 == 255
Division
a / b
a /= b
Integers
Floats
Can cause overflow for integers.
Can cause Division by Zero for integers.
Can cause Division by Zero for floats in FloatMode.Optimized Mode.
Signed integer operands must be comptime-known and positive. In other cases, use @divTrunc, @divFloor, or @divExact instead.
Invokes Peer Type Resolution for the operands.
10 / 5 == 2
Remainder Division
a % b
a %= b
Integers
Floats
Can cause Division by Zero for integers.
Can cause Division by Zero for floats in FloatMode.Optimized Mode.
Signed or floating-point operands must be comptime-known and positive. In other cases, use @rem or @mod instead.
Invokes Peer Type Resolution for the operands.
10 % 3 == 1
Bit Shift Left
a << b
a <<= b
Integers
Moves all bits to the left, inserting new zeroes at the least-significant bit.
b must be comptime-known or have a type with log2 number of bits as a.
See also @shlExact.
See also @shlWithOverflow.
0b1 << 8 == 0b100000000
Saturating Bit Shift Left
a <<| b
a <<|= b
Integers
See also @shlExact.
See also @shlWithOverflow.
@as(u8, 1) <<| 8 == 255
Bit Shift Right
a >> b
a >>= b
Integers
Moves all bits to the right, inserting zeroes at the most-significant bit.
b must be comptime-known or have a type with log2 number of bits as a.
See also @shrExact.
0b1010 >> 1 == 0b101
Bitwise And
a & b
a &= b
Integers
Invokes Peer Type Resolution for the operands.
0b011 & 0b101 == 0b001
Bitwise Or
a | b
a |= b
Integers
Invokes Peer Type Resolution for the operands.
0b010 | 0b100 == 0b110
Bitwise Xor
a ^ b
a ^= b
Integers
Invokes Peer Type Resolution for the operands.
0b011 ^ 0b101 == 0b110
Bitwise Not
~a
Integers
~@as(u8, 0b10101111) == 0b01010000
Defaulting Optional Unwrap
a orelse b
Optionals
If a is null, returns b ("default value"), otherwise returns the unwrapped value of a. Note that b may be a value of type noreturn.
const value: ?u32 = null;
const unwrapped = value orelse 1234;
unwrapped == 1234
Optional Unwrap
a.?
Optionals
Equivalent to:
a orelse unreachable
const value: ?u32 = 5678;
value.? == 5678
Defaulting Error Unwrap
a catch b
a catch |err| b
Error Unions
If a is an error, returns b ("default value"), otherwise returns the unwrapped value of a. Note that b may be a value of type noreturn. err is the error and is in scope of the expression b.
const value: anyerror!u32 = error.Broken;
const unwrapped = value catch 1234;
unwrapped == 1234
Logical And
a and b
bool
If a is false, returns false without evaluating b. Otherwise, returns b.
(false and true) == false
Logical Or
a or b
bool
If a is true, returns true without evaluating b. Otherwise, returns b.
(false or true) == true
Boolean Not
!a
bool
!false == true
Equality
a == b
Integers
Floats
bool
type
packed struct
Returns true if a and b are equal, otherwise returns false. Invokes Peer Type Resolution for the operands.
(1 == 1) == true
Null Check
a == null
Optionals
Returns true if a is null, otherwise returns false.
const value: ?u32 = null;
(value == null) == true
Inequality
a != b
Integers
Floats
bool
type
Returns false if a and b are equal, otherwise returns true. Invokes Peer Type Resolution for the operands.
(1 != 1) == false
Non-Null Check
a != null
Optionals
Returns false if a is null, otherwise returns true.
const value: ?u32 = null;
(value != null) == false
Greater Than
a > b
Integers
Floats
Returns true if a is greater than b, otherwise returns false. Invokes Peer Type Resolution for the operands.
(2 > 1) == true
Greater or Equal
a >= b
Integers
Floats
Returns true if a is greater than or equal to b, otherwise returns false. Invokes Peer Type Resolution for the operands.
(2 >= 1) == true
Less Than
a < b
Integers
Floats
Returns true if a is less than b, otherwise returns false. Invokes Peer Type Resolution for the operands.
(1 < 2) == true
Lesser or Equal
a <= b
Integers
Floats
Returns true if a is less than or equal to b, otherwise returns false. Invokes Peer Type Resolution for the operands.
(1 <= 2) == true
Array Concatenation
a ++ b
Arrays
Only available when the lengths of both a and b are compile-time known.
const mem = @import("std").mem;
const array1 = [_]u32{1,2};
const array2 = [_]u32{3,4};
const together = array1 ++ array2;
mem.eql(u32, &together, &[_]u32{1,2,3,4})
Array Multiplication
a ** b
Arrays
Only available when the length of a and b are compile-time known.
const mem = @import("std").mem;
const pattern = "ab" ** 3;
mem.eql(u8, pattern, "ababab")
Pointer Dereference
a.*
Pointers
Pointer dereference.
const x: u32 = 1234;
const ptr = &x;
ptr.* == 1234
Address Of
&a
All types
const x: u32 = 1234;
const ptr = &x;
ptr.* == 1234
Error Set Merge
a || b
Error Set Type
Merging Error Sets
const A = error{One};
const B = error{Two};
(A || B) == error{One, Two}
Precedence
x() x[] x.y x.* x.?
a!b
x{}
!x -x -%x ~x &x ?x
* / % ** *% *| ||
+ - ++ +% -% +| -|
<< >> <<|
& ^ | orelse catch
== != < > <= >=
and
or
= *= *%= *|= /= %= += +%= +|= -= -%= -|= <<= <<|= >>= &= ^= |=
Arrays
test_arrays.zig
const expect = @import("std").testing.expect;
const assert = @import("std").debug.assert;
const mem = @import("std").mem;
// array literal
const message = [_]u8{ 'h', 'e', 'l', 'l', 'o' };
// alternative initialization using result location
const alt_message: [5]u8 = .{ 'h', 'e', 'l', 'l', 'o' };
comptime {
assert(mem.eql(u8, &message, &alt_message));
}
// get the size of an array
comptime {
assert(message.len == 5);
}
// A string literal is a single-item pointer to an array.
const same_message = "hello";
comptime {
assert(mem.eql(u8, &message, same_message));
}
test "iterate over an array" {
var sum: usize = 0;
for (message) |byte| {
sum += byte;
}
try expect(sum == 'h' + 'e' + 'l' * 2 + 'o');
}
// modifiable array
var some_integers: [100]i32 = undefined;
test "modify an array" {
for (&some_integers, 0..) |*item, i| {
item.* = @intCast(i);
}
try expect(some_integers[10] == 10);
try expect(some_integers[99] == 99);
}
// array concatenation works if the values are known
// at compile time
const part_one = [_]i32{ 1, 2, 3, 4 };
const part_two = [_]i32{ 5, 6, 7, 8 };
const all_of_it = part_one ++ part_two;
comptime {
assert(mem.eql(i32, &all_of_it, &[_]i32{ 1, 2, 3, 4, 5, 6, 7, 8 }));
}
// remember that string literals are arrays
const hello = "hello";
const world = "world";
const hello_world = hello ++ " " ++ world;
comptime {
assert(mem.eql(u8, hello_world, "hello world"));
}
// ** does repeating patterns
const pattern = "ab" ** 3;
comptime {
assert(mem.eql(u8, pattern, "ababab"));
}
// initialize an array to zero
const all_zero = [_]u16{0} ** 10;
comptime {
assert(all_zero.len == 10);
assert(all_zero[5] == 0);
}
// use compile-time code to initialize an array
var fancy_array = init: {
var initial_value: [10]Point = undefined;
for (&initial_value, 0..) |*pt, i| {
pt.* = Point{
.x = @intCast(i),
.y = @intCast(i * 2),
};
}
break :init initial_value;
};
const Point = struct {
x: i32,
y: i32,
};
test "compile-time array initialization" {
try expect(fancy_array[4].x == 4);
try expect(fancy_array[4].y == 8);
}
// call a function to initialize an array
var more_points = [_]Point{makePoint(3)} ** 10;
fn makePoint(x: i32) Point {
return Point{
.x = x,
.y = x * 2,
};
}
test "array initialization with function calls" {
try expect(more_points[4].x == 3);
try expect(more_points[4].y == 6);
try expect(more_points.len == 10);
}
Shell
$ zig test test_arrays.zig
1/4 test_arrays.test.iterate over an array...OK
2/4 test_arrays.test.modify an array...OK
3/4 test_arrays.test.compile-time array initialization...OK
4/4 test_arrays.test.array initialization with function calls...OK
All 4 tests passed.
See also:
for
Slices
Multidimensional Arrays
Multidimensional arrays can be created by nesting arrays:
test_multidimensional_arrays.zig
const std = @import("std");
const expect = std.testing.expect;
const expectEqual = std.testing.expectEqual;
const mat4x5 = [4][5]f32{
[_]f32{ 1.0, 0.0, 0.0, 0.0, 0.0 },
[_]f32{ 0.0, 1.0, 0.0, 1.0, 0.0 },
[_]f32{ 0.0, 0.0, 1.0, 0.0, 0.0 },
[_]f32{ 0.0, 0.0, 0.0, 1.0, 9.9 },
};
test "multidimensional arrays" {
// mat4x5 itself is a one-dimensional array of arrays.
try expectEqual(mat4x5[1], [_]f32{ 0.0, 1.0, 0.0, 1.0, 0.0 });
// Access the 2D array by indexing the outer array, and then the inner array.
try expect(mat4x5[3][4] == 9.9);
// Here we iterate with for loops.
for (mat4x5, 0..) |row, row_index| {
for (row, 0..) |cell, column_index| {
if (row_index == column_index) {
try expect(cell == 1.0);
}
}
}
// Initialize a multidimensional array to zeros.
const all_zero: [4][5]f32 = .{.{0} ** 5} ** 4;
try expect(all_zero[0][0] == 0);
}
Shell
$ zig test test_multidimensional_arrays.zig
1/1 test_multidimensional_arrays.test.multidimensional arrays...OK
All 1 tests passed.
Sentinel-Terminated Arrays
The syntax [N:x]T describes an array which has a sentinel element of value x at the index corresponding to the length N.
test_null_terminated_array.zig
const std = @import("std");
const expect = std.testing.expect;
test "0-terminated sentinel array" {
const array = [_:0]u8{ 1, 2, 3, 4 };
try expect(@TypeOf(array) == [4:0]u8);
try expect(array.len == 4);
try expect(array[4] == 0);
}
test "extra 0s in 0-terminated sentinel array" {
// The sentinel value may appear earlier, but does not influence the compile-time 'len'.
const array = [_:0]u8{ 1, 0, 0, 4 };
try expect(@TypeOf(array) == [4:0]u8);
try expect(array.len == 4);
try expect(array[4] == 0);
}
Shell
$ zig test test_null_terminated_array.zig
1/2 test_null_terminated_array.test.0-terminated sentinel array...OK
2/2 test_null_terminated_array.test.extra 0s in 0-terminated sentinel array...OK
All 2 tests passed.
See also:
Sentinel-Terminated Pointers
Sentinel-Terminated Slices
Destructuring Arrays
Arrays can be destructured:
destructuring_arrays.zig
const print = @import("std").debug.print;
fn swizzleRgbaToBgra(rgba: [4]u8) [4]u8 {
// readable swizzling by destructuring
const r, const g, const b, const a = rgba;
return .{ b, g, r, a };
}
pub fn main() void {
const pos = [_]i32{ 1, 2 };
const x, const y = pos;
print("x = {}, y = {}\n", .{x, y});
const orange: [4]u8 = .{ 255, 165, 0, 255 };
print("{any}\n", .{swizzleRgbaToBgra(orange)});
}
Shell
$ zig build-exe destructuring_arrays.zig
$ ./destructuring_arrays
x = 1, y = 2
{ 0, 165, 255, 255 }
See also:
Destructuring
Destructuring Tuples
Destructuring Vectors
Vectors
A vector is a group of booleans, Integers, Floats, or Pointers which are operated on in parallel, using SIMD instructions if possible. Vector types are created with the builtin function @Vector.
Vectors support the same builtin operators as their underlying base types. These operations are performed element-wise, and return a vector of the same length as the input vectors. This includes:
Arithmetic (+, -, /, *, @divFloor, @sqrt, @ceil, @log, etc.)
Bitwise operators (>>, <<, &, |, ~, etc.)
Comparison operators (<, >, ==, etc.)
It is prohibited to use a math operator on a mixture of scalars (individual numbers) and vectors. Zig provides the @splat builtin to easily convert from scalars to vectors, and it supports @reduce and array indexing syntax to convert from vectors to scalars. Vectors also support assignment to and from fixed-length arrays with comptime-known length.
For rearranging elements within and between vectors, Zig provides the @shuffle and @select functions.
Operations on vectors shorter than the target machine's native SIMD size will typically compile to single SIMD instructions, while vectors longer than the target machine's native SIMD size will compile to multiple SIMD instructions. If a given operation doesn't have SIMD support on the target architecture, the compiler will default to operating on each vector element one at a time. Zig supports any comptime-known vector length up to 2^32-1, although small powers of two (2-64) are most typical. Note that excessively long vector lengths (e.g. 2^20) may result in compiler crashes on current versions of Zig.
test_vector.zig
const std = @import("std");
const expectEqual = std.testing.expectEqual;
test "Basic vector usage" {
// Vectors have a compile-time known length and base type.
const a = @Vector(4, i32){ 1, 2, 3, 4 };
const b = @Vector(4, i32){ 5, 6, 7, 8 };
// Math operations take place element-wise.
const c = a + b;
// Individual vector elements can be accessed using array indexing syntax.
try expectEqual(6, c[0]);
try expectEqual(8, c[1]);
try expectEqual(10, c[2]);
try expectEqual(12, c[3]);
}
test "Conversion between vectors, arrays, and slices" {
// Vectors and fixed-length arrays can be automatically assigned back and forth
const arr1: [4]f32 = [_]f32{ 1.1, 3.2, 4.5, 5.6 };
const vec: @Vector(4, f32) = arr1;
const arr2: [4]f32 = vec;
try expectEqual(arr1, arr2);
// You can also assign from a slice with comptime-known length to a vector using .*
const vec2: @Vector(2, f32) = arr1[1..3].*;
const slice: []const f32 = &arr1;
var offset: u32 = 1; // var to make it runtime-known
_ = &offset; // suppress 'var is never mutated' error
// To extract a comptime-known length from a runtime-known offset,
// first extract a new slice from the starting offset, then an array of
// comptime-known length
const vec3: @Vector(2, f32) = slice[offset..][0..2].*;
try expectEqual(slice[offset], vec2[0]);
try expectEqual(slice[offset + 1], vec2[1]);
try expectEqual(vec2, vec3);
}
Shell
$ zig test test_vector.zig
1/2 test_vector.test.Basic vector usage...OK
2/2 test_vector.test.Conversion between vectors, arrays, and slices...OK
All 2 tests passed.
TODO talk about C ABI interop
TODO consider suggesting std.MultiArrayList
See also:
@splat
@shuffle
@select
@reduce
Destructuring Vectors
Vectors can be destructured:
destructuring_vectors.zig
const print = @import("std").debug.print;
// emulate punpckldq
pub fn unpack(x: @Vector(4, f32), y: @Vector(4, f32)) @Vector(4, f32) {
const a, const c, _, _ = x;
const b, const d, _, _ = y;
return .{ a, b, c, d };
}
pub fn main() void {
const x: @Vector(4, f32) = .{ 1.0, 2.0, 3.0, 4.0 };
const y: @Vector(4, f32) = .{ 5.0, 6.0, 7.0, 8.0 };
print("{}", .{unpack(x, y)});
}
Shell
$ zig build-exe destructuring_vectors.zig
$ ./destructuring_vectors
{ 1e0, 5e0, 2e0, 6e0 }
See also:
Destructuring
Destructuring Tuples
Destructuring Arrays
Pointers
Zig has two kinds of pointers: single-item and many-item.
*T - single-item pointer to exactly one item.
Supports deref syntax: ptr.*
Supports slice syntax: ptr[0..1]
Supports pointer subtraction: ptr - ptr
[*]T - many-item pointer to unknown number of items.
Supports index syntax: ptr[i]
Supports slice syntax: ptr[start..end] and ptr[start..]
Supports pointer-integer arithmetic: ptr + int, ptr - int
Supports pointer subtraction: ptr - ptr
T must have a known size, which means that it cannot be anyopaque or any other opaque type.
These types are closely related to Arrays and Slices:
*[N]T - pointer to N items, same as single-item pointer to an array.
Supports index syntax: array_ptr[i]
Supports slice syntax: array_ptr[start..end]
Supports len property: array_ptr.len
Supports pointer subtraction: array_ptr - array_ptr
[]T - is a slice (a fat pointer, which contains a pointer of type [*]T and a length).
Supports index syntax: slice[i]
Supports slice syntax: slice[start..end]
Supports len property: slice.len
Use &x to obtain a single-item pointer:
test_single_item_pointer.zig
const expect = @import("std").testing.expect;
test "address of syntax" {
// Get the address of a variable:
const x: i32 = 1234;
const x_ptr = &x;
// Dereference a pointer:
try expect(x_ptr.* == 1234);
// When you get the address of a const variable, you get a const single-item pointer.
try expect(@TypeOf(x_ptr) == *const i32);
// If you want to mutate the value, you'd need an address of a mutable variable:
var y: i32 = 5678;
const y_ptr = &y;
try expect(@TypeOf(y_ptr) == *i32);
y_ptr.* += 1;
try expect(y_ptr.* == 5679);
}
test "pointer array access" {
// Taking an address of an individual element gives a
// single-item pointer. This kind of pointer
// does not support pointer arithmetic.
var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
const ptr = &array[2];
try expect(@TypeOf(ptr) == *u8);
try expect(array[2] == 3);
ptr.* += 1;
try expect(array[2] == 4);
}
test "slice syntax" {
// Get a pointer to a variable:
var x: i32 = 1234;
const x_ptr = &x;
// Convert to array pointer using slice syntax:
const x_array_ptr = x_ptr[0..1];
try expect(@TypeOf(x_array_ptr) == *[1]i32);
// Coerce to many-item pointer:
const x_many_ptr: [*]i32 = x_array_ptr;
try expect(x_many_ptr[0] == 1234);
}
Shell
$ zig test test_single_item_pointer.zig
1/3 test_single_item_pointer.test.address of syntax...OK
2/3 test_single_item_pointer.test.pointer array access...OK
3/3 test_single_item_pointer.test.slice syntax...OK
All 3 tests passed.
Zig supports pointer arithmetic. It's better to assign the pointer to [*]T and increment that variable. For example, directly incrementing the pointer from a slice will corrupt it.
test_pointer_arithmetic.zig
const expect = @import("std").testing.expect;
test "pointer arithmetic with many-item pointer" {
const array = [_]i32{ 1, 2, 3, 4 };
var ptr: [*]const i32 = &array;
try expect(ptr[0] == 1);
ptr += 1;
try expect(ptr[0] == 2);
// slicing a many-item pointer without an end is equivalent to
// pointer arithmetic: `ptr[start..] == ptr + start`
try expect(ptr[1..] == ptr + 1);
// subtraction between any two pointers except slices based on element size is supported
try expect(&ptr[1] - &ptr[0] == 1);
}
test "pointer arithmetic with slices" {
var array = [_]i32{ 1, 2, 3, 4 };
var length: usize = 0; // var to make it runtime-known
_ = &length; // suppress 'var is never mutated' error
var slice = array[length..array.len];
try expect(slice[0] == 1);
try expect(slice.len == 4);
slice.ptr += 1;
// now the slice is in an bad state since len has not been updated
try expect(slice[0] == 2);
try expect(slice.len == 4);
}
Shell
$ zig test test_pointer_arithmetic.zig
1/2 test_pointer_arithmetic.test.pointer arithmetic with many-item pointer...OK
2/2 test_pointer_arithmetic.test.pointer arithmetic with slices...OK
All 2 tests passed.
In Zig, we generally prefer Slices rather than Sentinel-Terminated Pointers. You can turn an array or pointer into a slice using slice syntax.
Slices have bounds checking and are therefore protected against this kind of Illegal Behavior. This is one reason we prefer slices to pointers.
test_slice_bounds.zig
const expect = @import("std").testing.expect;
test "pointer slicing" {
var array = [_]u8{ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
var start: usize = 2; // var to make it runtime-known
_ = &start; // suppress 'var is never mutated' error
const slice = array[start..4];
try expect(slice.len == 2);
try expect(array[3] == 4);
slice[1] += 1;
try expect(array[3] == 5);
}
Shell
$ zig test test_slice_bounds.zig
1/1 test_slice_bounds.test.pointer slicing...OK
All 1 tests passed.
Pointers work at compile-time too, as long as the code does not depend on an undefined memory layout:
test_comptime_pointers.zig
const expect = @import("std").testing.expect;
test "comptime pointers" {
comptime {
var x: i32 = 1;
const ptr = &x;
ptr.* += 1;
x += 1;
try expect(ptr.* == 3);
}
}
Shell
$ zig test test_comptime_pointers.zig
1/1 test_comptime_pointers.test.comptime pointers...OK
All 1 tests passed.
To convert an integer address into a pointer, use @ptrFromInt. To convert a pointer to an integer, use @intFromPtr:
test_integer_pointer_conversion.zig
const expect = @import("std").testing.expect;
test "@intFromPtr and @ptrFromInt" {
const ptr: *i32 = @ptrFromInt(0xdeadbee0);
const addr = @intFromPtr(ptr);
try expect(@TypeOf(addr) == usize);
try expect(addr == 0xdeadbee0);
}
Shell
$ zig test test_integer_pointer_conversion.zig
1/1 test_integer_pointer_conversion.test.@intFromPtr and @ptrFromInt...OK
All 1 tests passed.
Zig is able to preserve memory addresses in comptime code, as long as the pointer is never dereferenced:
test_comptime_pointer_conversion.zig
const expect = @import("std").testing.expect;
test "comptime @ptrFromInt" {
comptime {
// Zig is able to do this at compile-time, as long as
// ptr is never dereferenced.
const ptr: *i32 = @ptrFromInt(0xdeadbee0);
const addr = @intFromPtr(ptr);
try expect(@TypeOf(addr) == usize);
try expect(addr == 0xdeadbee0);
}
}
Shell
$ zig test test_comptime_pointer_conversion.zig
1/1 test_comptime_pointer_conversion.test.comptime @ptrFromInt...OK
All 1 tests passed.
@ptrCast converts a pointer's element type to another. This creates a new pointer that can cause undetectable Illegal Behavior depending on the loads and stores that pass through it. Generally, other kinds of type conversions are preferable to @ptrCast if possible.
test_pointer_casting.zig
const std = @import("std");
const expect = std.testing.expect;
test "pointer casting" {
const bytes align(@alignOf(u32)) = [_]u8{ 0x12, 0x12, 0x12, 0x12 };
const u32_ptr: *const u32 = @ptrCast(&bytes);
try expect(u32_ptr.* == 0x12121212);
// Even this example is contrived - there are better ways to do the above than
// pointer casting. For example, using a slice narrowing cast:
const u32_value = std.mem.bytesAsSlice(u32, bytes[0..])[0];
try expect(u32_value == 0x12121212);
// And even another way, the most straightforward way to do it:
try expect(@as(u32, @bitCast(bytes)) == 0x12121212);
}
test "pointer child type" {
// pointer types have a `child` field which tells you the type they point to.
try expect(@typeInfo(*u32).pointer.child == u32);
}
Shell
$ zig test test_pointer_casting.zig
1/2 test_pointer_casting.test.pointer casting...OK
2/2 test_pointer_casting.test.pointer child type...OK
All 2 tests passed.
See also:
Optional Pointers
@ptrFromInt
@intFromPtr
C Pointers
volatile
Loads and stores are assumed to not have side effects. If a given load or store should have side effects, such as Memory Mapped Input/Output (MMIO), use volatile. In the following code, loads and stores with mmio_ptr are guaranteed to all happen and in the same order as in source code:
test_volatile.zig
const expect = @import("std").testing.expect;
test "volatile" {
const mmio_ptr: *volatile u8 = @ptrFromInt(0x12345678);
try expect(@TypeOf(mmio_ptr) == *volatile u8);
}
Shell
$ zig test test_volatile.zig
1/1 test_volatile.test.volatile...OK
All 1 tests passed.
Note that volatile is unrelated to concurrency and Atomics. If you see code that is using volatile for something other than Memory Mapped Input/Output, it is probably a bug.
Alignment
Each type has an alignment - a number of bytes such that, when a value of the type is loaded from or stored to memory, the memory address must be evenly divisible by this number. You can use @alignOf to find out this value for any type.
Alignment depends on the CPU architecture, but is always a power of two, and less than 1 << 29.
In Zig, a pointer type has an alignment value. If the value is equal to the alignment of the underlying type, it can be omitted from the type:
test_variable_alignment.zig
const std = @import("std");
const builtin = @import("builtin");
const expect = std.testing.expect;
test "variable alignment" {
var x: i32 = 1234;
const align_of_i32 = @alignOf(@TypeOf(x));
try expect(@TypeOf(&x) == *i32);
try expect(*i32 == *align(align_of_i32) i32);
if (builtin.target.cpu.arch == .x86_64) {
try expect(@typeInfo(*i32).pointer.alignment == 4);
}
}
Shell
$ zig test test_variable_alignment.zig
1/1 test_variable_alignment.test.variable alignment...OK
All 1 tests passed.
In the same way that a *i32 can be coerced to a *const i32, a pointer with a larger alignment can be implicitly cast to a pointer with a smaller alignment, but not vice versa.
You can specify alignment on variables and functions. If you do this, then pointers to them get the specified alignment:
test_variable_func_alignment.zig
const expect = @import("std").testing.expect;
var foo: u8 align(4) = 100;
test "global variable alignment" {
try expect(@typeInfo(@TypeOf(&foo)).pointer.alignment == 4);
try expect(@TypeOf(&foo) == *align(4) u8);
const as_pointer_to_array: *align(4) [1]u8 = &foo;
const as_slice: []align(4) u8 = as_pointer_to_array;
const as_unaligned_slice: []u8 = as_slice;
try expect(as_unaligned_slice[0] == 100);
}
fn derp() align(@sizeOf(usize) * 2) i32 {
return 1234;
}
fn noop1() align(1) void {}
fn noop4() align(4) void {}
test "function alignment" {
try expect(derp() == 1234);
try expect(@TypeOf(derp) == fn () i32);
try expect(@TypeOf(&derp) == *align(@sizeOf(usize) * 2) const fn () i32);
noop1();
try expect(@TypeOf(noop1) == fn () void);
try expect(@TypeOf(&noop1) == *align(1) const fn () void);
noop4();
try expect(@TypeOf(noop4) == fn () void);
try expect(@TypeOf(&noop4) == *align(4) const fn () void);
}
Shell
$ zig test test_variable_func_alignment.zig
1/2 test_variable_func_alignment.test.global variable alignment...OK
2/2 test_variable_func_alignment.test.function alignment...OK
All 2 tests passed.
If you have a pointer or a slice that has a small alignment, but you know that it actually has a bigger alignment, use @alignCast to change the pointer into a more aligned pointer. This is a no-op at runtime, but inserts a safety check:
test_incorrect_pointer_alignment.zig
const std = @import("std");
test "pointer alignment safety" {
var array align(4) = [_]u32{ 0x11111111, 0x11111111 };
const bytes = std.mem.sliceAsBytes(array[0..]);
try std.testing.expect(foo(bytes) == 0x11111111);
}
fn foo(bytes: []u8) u32 {
const slice4 = bytes[1..5];
const int_slice = std.mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
return int_slice[0];
}
Shell
$ zig test test_incorrect_pointer_alignment.zig
1/1 test_incorrect_pointer_alignment.test.pointer alignment safety...thread 3521392 panic: incorrect alignment
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_incorrect_pointer_alignment.zig:10:68: 0x102d292 in foo (test_incorrect_pointer_alignment.zig)
const int_slice = std.mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_incorrect_pointer_alignment.zig:6:31: 0x102d0d0 in test.pointer alignment safety (test_incorrect_pointer_alignment.zig)
try std.testing.expect(foo(bytes) == 0x11111111);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x1176193 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:64:28: 0x116c237 in main (test_runner.zig)
return mainTerminal();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x116536d in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x1164c43 in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/6895bed73767ab72cb423b3708410e3d/test --seed=0x754e4fc4
allowzero
This pointer attribute allows a pointer to have address zero. This is only ever needed on the freestanding OS target, where the address zero is mappable. If you want to represent null pointers, use Optional Pointers instead. Optional Pointers with allowzero are not the same size as pointers. In this code example, if the pointer did not have the allowzero attribute, this would be a Pointer Cast Invalid Null panic:
test_allowzero.zig
const std = @import("std");
const expect = std.testing.expect;
test "allowzero" {
var zero: usize = 0; // var to make to runtime-known
_ = &zero; // suppress 'var is never mutated' error
const ptr: *allowzero i32 = @ptrFromInt(zero);
try expect(@intFromPtr(ptr) == 0);
}
Shell
$ zig test test_allowzero.zig
1/1 test_allowzero.test.allowzero...OK
All 1 tests passed.
Sentinel-Terminated Pointers
The syntax [*:x]T describes a pointer that has a length determined by a sentinel value. This provides protection against buffer overflow and overreads.
sentinel-terminated_pointer.zig
const std = @import("std");
// This is also available as `std.c.printf`.
pub extern "c" fn printf(format: [*:0]const u8, ...) c_int;
pub fn main() anyerror!void {
_ = printf("Hello, world!\n"); // OK
const msg = "Hello, world!\n";
const non_null_terminated_msg: [msg.len]u8 = msg.*;
_ = printf(&non_null_terminated_msg);
}
Shell
$ zig build-exe sentinel-terminated_pointer.zig -lc
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/sentinel-terminated_pointer.zig:11:16: error: expected type '[*:0]const u8', found '*const [14]u8'
_ = printf(&non_null_terminated_msg);
^~~~~~~~~~~~~~~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/sentinel-terminated_pointer.zig:11:16: note: destination pointer requires '0' sentinel
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/sentinel-terminated_pointer.zig:4:34: note: parameter type declared here
pub extern "c" fn printf(format: [*:0]const u8, ...) c_int;
^~~~~~~~~~~~~
referenced by:
callMain [inlined]: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:675:37
callMainWithArgs [inlined]: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:635:20
main: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:650:28
1 reference(s) hidden; use '-freference-trace=4' to see all references
See also:
Sentinel-Terminated Slices
Sentinel-Terminated Arrays
Slices
A slice is a pointer and a length. The difference between an array and a slice is that the array's length is part of the type and known at compile-time, whereas the slice's length is known at runtime. Both can be accessed with the len field.
test_basic_slices.zig
const expect = @import("std").testing.expect;
const expectEqualSlices = @import("std").testing.expectEqualSlices;
test "basic slices" {
var array = [_]i32{ 1, 2, 3, 4 };
var known_at_runtime_zero: usize = 0;
_ = &known_at_runtime_zero;
const slice = array[known_at_runtime_zero..array.len];
// alternative initialization using result location
const alt_slice: []const i32 = &.{ 1, 2, 3, 4 };
try expectEqualSlices(i32, slice, alt_slice);
try expect(@TypeOf(slice) == []i32);
try expect(&slice[0] == &array[0]);
try expect(slice.len == array.len);
// If you slice with comptime-known start and end positions, the result is
// a pointer to an array, rather than a slice.
const array_ptr = array[0..array.len];
try expect(@TypeOf(array_ptr) == *[array.len]i32);
// You can perform a slice-by-length by slicing twice. This allows the compiler
// to perform some optimisations like recognising a comptime-known length when
// the start position is only known at runtime.
var runtime_start: usize = 1;
_ = &runtime_start;
const length = 2;
const array_ptr_len = array[runtime_start..][0..length];
try expect(@TypeOf(array_ptr_len) == *[length]i32);
// Using the address-of operator on a slice gives a single-item pointer.
try expect(@TypeOf(&slice[0]) == *i32);
// Using the `ptr` field gives a many-item pointer.
try expect(@TypeOf(slice.ptr) == [*]i32);
try expect(@intFromPtr(slice.ptr) == @intFromPtr(&slice[0]));
// Slices have array bounds checking. If you try to access something out
// of bounds, you'll get a safety check failure:
slice[10] += 1;
// Note that `slice.ptr` does not invoke safety checking, while `&slice[0]`
// asserts that the slice has len > 0.
// Empty slices can be created like this:
const empty1 = &[0]u8{};
// If the type is known you can use this short hand:
const empty2: []u8 = &.{};
try expect(empty1.len == 0);
try expect(empty2.len == 0);
// A zero-length initialization can always be used to create an empty slice, even if the slice is mutable.
// This is because the pointed-to data is zero bits long, so its immutability is irrelevant.
}
Shell
$ zig test test_basic_slices.zig
1/1 test_basic_slices.test.basic slices...thread 3518990 panic: index out of bounds: index 10, len 4
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_basic_slices.zig:41:10: 0x10302c6 in test.basic slices (test_basic_slices.zig)
slice[10] += 1;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x117cb7b in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:64:28: 0x1172c1f in main (test_runner.zig)
return mainTerminal();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x116bd55 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x116b62b in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/8f94028ed29ea361af29f00dd94bbe1f/test --seed=0xf833652c
This is one reason we prefer slices to pointers.
test_slices.zig
const std = @import("std");
const expect = std.testing.expect;
const mem = std.mem;
const fmt = std.fmt;
test "using slices for strings" {
// Zig has no concept of strings. String literals are const pointers
// to null-terminated arrays of u8, and by convention parameters
// that are "strings" are expected to be UTF-8 encoded slices of u8.
// Here we coerce *const [5:0]u8 and *const [6:0]u8 to []const u8
const hello: []const u8 = "hello";
const world: []const u8 = "世界";
var all_together: [100]u8 = undefined;
// You can use slice syntax with at least one runtime-known index on an
// array to convert an array into a slice.
var start: usize = 0;
_ = &start;
const all_together_slice = all_together[start..];
// String concatenation example.
const hello_world = try fmt.bufPrint(all_together_slice, "{s} {s}", .{ hello, world });
// Generally, you can use UTF-8 and not worry about whether something is a
// string. If you don't need to deal with individual characters, no need
// to decode.
try expect(mem.eql(u8, hello_world, "hello 世界"));
}
test "slice pointer" {
var array: [10]u8 = undefined;
const ptr = &array;
try expect(@TypeOf(ptr) == *[10]u8);
// A pointer to an array can be sliced just like an array:
var start: usize = 0;
var end: usize = 5;
_ = .{ &start, &end };
const slice = ptr[start..end];
// The slice is mutable because we sliced a mutable pointer.
try expect(@TypeOf(slice) == []u8);
slice[2] = 3;
try expect(array[2] == 3);
// Again, slicing with comptime-known indexes will produce another pointer
// to an array:
const ptr2 = slice[2..3];
try expect(ptr2.len == 1);
try expect(ptr2[0] == 3);
try expect(@TypeOf(ptr2) == *[1]u8);
}
Shell
$ zig test test_slices.zig
1/2 test_slices.test.using slices for strings...OK
2/2 test_slices.test.slice pointer...OK
All 2 tests passed.
See also:
Pointers
for
Arrays
Sentinel-Terminated Slices
The syntax [:x]T is a slice which has a runtime-known length and also guarantees a sentinel value at the element indexed by the length. The type does not guarantee that there are no sentinel elements before that. Sentinel-terminated slices allow element access to the len index.
test_null_terminated_slice.zig
const std = @import("std");
const expect = std.testing.expect;
test "0-terminated slice" {
const slice: [:0]const u8 = "hello";
try expect(slice.len == 5);
try expect(slice[5] == 0);
}
Shell
$ zig test test_null_terminated_slice.zig
1/1 test_null_terminated_slice.test.0-terminated slice...OK
All 1 tests passed.
Sentinel-terminated slices can also be created using a variation of the slice syntax data[start..end :x], where data is a many-item pointer, array or slice and x is the sentinel value.
test_null_terminated_slicing.zig
const std = @import("std");
const expect = std.testing.expect;
test "0-terminated slicing" {
var array = [_]u8{ 3, 2, 1, 0, 3, 2, 1, 0 };
var runtime_length: usize = 3;
_ = &runtime_length;
const slice = array[0..runtime_length :0];
try expect(@TypeOf(slice) == [:0]u8);
try expect(slice.len == 3);
}
Shell
$ zig test test_null_terminated_slicing.zig
1/1 test_null_terminated_slicing.test.0-terminated slicing...OK
All 1 tests passed.
Sentinel-terminated slicing asserts that the element in the sentinel position of the backing data is actually the sentinel value. If this is not the case, safety-checked Illegal Behavior results.
test_sentinel_mismatch.zig
const std = @import("std");
const expect = std.testing.expect;
test "sentinel mismatch" {
var array = [_]u8{ 3, 2, 1, 0 };
// Creating a sentinel-terminated slice from the array with a length of 2
// will result in the value `1` occupying the sentinel element position.
// This does not match the indicated sentinel value of `0` and will lead
// to a runtime panic.
var runtime_length: usize = 2;
_ = &runtime_length;
const slice = array[0..runtime_length :0];
_ = slice;
}
Shell
$ zig test test_sentinel_mismatch.zig
1/1 test_sentinel_mismatch.test.sentinel mismatch...thread 3521485 panic: sentinel mismatch: expected 0, found 1
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_sentinel_mismatch.zig:13:24: 0x102d117 in test.sentinel mismatch (test_sentinel_mismatch.zig)
const slice = array[0..runtime_length :0];
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x1175f13 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:64:28: 0x116bfb7 in main (test_runner.zig)
return mainTerminal();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x11650ed in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x11649c3 in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/052d806297c956feba13c0139dca61ef/test --seed=0x5de9a2
See also:
Sentinel-Terminated Pointers
Sentinel-Terminated Arrays
struct
test_structs.zig
// Declare a struct.
// Zig gives no guarantees about the order of fields and the size of
// the struct but the fields are guaranteed to be ABI-aligned.
const Point = struct {
x: f32,
y: f32,
};
// Declare an instance of a struct.
const p: Point = .{
.x = 0.12,
.y = 0.34,
};
// Functions in the struct's namespace can be called with dot syntax.
const Vec3 = struct {
x: f32,
y: f32,
z: f32,
pub fn init(x: f32, y: f32, z: f32) Vec3 {
return Vec3{
.x = x,
.y = y,
.z = z,
};
}
pub fn dot(self: Vec3, other: Vec3) f32 {
return self.x * other.x + self.y * other.y + self.z * other.z;
}
};
test "dot product" {
const v1 = Vec3.init(1.0, 0.0, 0.0);
const v2 = Vec3.init(0.0, 1.0, 0.0);
try expect(v1.dot(v2) == 0.0);
// Other than being available to call with dot syntax, struct methods are
// not special. You can reference them as any other declaration inside
// the struct:
try expect(Vec3.dot(v1, v2) == 0.0);
}
// Structs can have declarations.
// Structs can have 0 fields.
const Empty = struct {
pub const PI = 3.14;
};
test "struct namespaced variable" {
try expect(Empty.PI == 3.14);
try expect(@sizeOf(Empty) == 0);
// Empty structs can be instantiated the same as usual.
const does_nothing: Empty = .{};
_ = does_nothing;
}
// Struct field order is determined by the compiler, however, a base pointer
// can be computed from a field pointer:
fn setYBasedOnX(x: *f32, y: f32) void {
const point: *Point = @fieldParentPtr("x", x);
point.y = y;
}
test "field parent pointer" {
var point = Point{
.x = 0.1234,
.y = 0.5678,
};
setYBasedOnX(&point.x, 0.9);
try expect(point.y == 0.9);
}
// Structs can be returned from functions.
fn LinkedList(comptime T: type) type {
return struct {
pub const Node = struct {
prev: ?*Node,
next: ?*Node,
data: T,
};
first: ?*Node,
last: ?*Node,
len: usize,
};
}
test "linked list" {
// Functions called at compile-time are memoized.
try expect(LinkedList(i32) == LinkedList(i32));
const list = LinkedList(i32){
.first = null,
.last = null,
.len = 0,
};
try expect(list.len == 0);
// Since types are first class values you can instantiate the type
// by assigning it to a variable:
const ListOfInts = LinkedList(i32);
try expect(ListOfInts == LinkedList(i32));
var node = ListOfInts.Node{
.prev = null,
.next = null,
.data = 1234,
};
const list2 = LinkedList(i32){
.first = &node,
.last = &node,
.len = 1,
};
// When using a pointer to a struct, fields can be accessed directly,
// without explicitly dereferencing the pointer.
// So you can do
try expect(list2.first.?.data == 1234);
// instead of try expect(list2.first.?.*.data == 1234);
}
const expect = @import("std").testing.expect;
Shell
$ zig test test_structs.zig
1/4 test_structs.test.dot product...OK
2/4 test_structs.test.struct namespaced variable...OK
3/4 test_structs.test.field parent pointer...OK
4/4 test_structs.test.linked list...OK
All 4 tests passed.
Default Field Values
Each struct field may have an expression indicating the default field value. Such expressions are executed at comptime, and allow the field to be omitted in a struct literal expression:
struct_default_field_values.zig
const Foo = struct {
a: i32 = 1234,
b: i32,
};
test "default struct initialization fields" {
const x: Foo = .{
.b = 5,
};
if (x.a + x.b != 1239) {
comptime unreachable;
}
}
Shell
$ zig test struct_default_field_values.zig
1/1 struct_default_field_values.test.default struct initialization fields...OK
All 1 tests passed.
Faulty Default Field Values
Default field values are only appropriate when the data invariants of a struct cannot be violated by omitting that field from an initialization.
For example, here is an inappropriate use of default struct field initialization:
bad_default_value.zig
const Threshold = struct {
minimum: f32 = 0.25,
maximum: f32 = 0.75,
const Category = enum { low, medium, high };
fn categorize(t: Threshold, value: f32) Category {
assert(t.maximum >= t.minimum);
if (value < t.minimum) return .low;
if (value > t.maximum) return .high;
return .medium;
}
};
pub fn main() !void {
var threshold: Threshold = .{
.maximum = 0.20,
};
const category = threshold.categorize(0.90);
try std.io.getStdOut().writeAll(@tagName(category));
}
const std = @import("std");
const assert = std.debug.assert;
Shell
$ zig build-exe bad_default_value.zig
$ ./bad_default_value
thread 3521087 panic: reached unreachable code
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/debug.zig:548:14: 0x10307c9 in assert (std.zig)
if (!ok) unreachable; // assertion failure
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/bad_default_value.zig:8:15: 0x11540b5 in categorize (bad_default_value.zig)
assert(t.maximum >= t.minimum);
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/bad_default_value.zig:19:42: 0x11528f8 in main (bad_default_value.zig)
const category = threshold.categorize(0.90);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:675:37: 0x115310d in posixCallMainAndExit (std.zig)
const result = root.main() catch |err| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Above you can see the danger of ignoring this principle. The default field values caused the data invariant to be violated, causing illegal behavior.
To fix this, remove the default values from all the struct fields, and provide a named default value:
struct_default_value.zig
const Threshold = struct {
minimum: f32,
maximum: f32,
const default: Threshold = .{
.minimum = 0.25,
.maximum = 0.75,
};
};
If a struct value requires a runtime-known value in order to be initialized without violating data invariants, then use an initialization method that accepts those runtime values, and populates the remaining fields.
extern struct
An extern struct has in-memory layout matching the C ABI for the target.
If well-defined in-memory layout is not required, struct is a better choice because it places fewer restrictions on the compiler.
See packed struct for a struct that has the ABI of its backing integer, which can be useful for modeling flags.
See also:
extern union
extern enum
packed struct
packed structs, like enum, are based on the concept of interpreting integers differently. All packed structs have a backing integer, which is implicitly determined by the total bit count of fields, or explicitly specified. Packed structs have well-defined memory layout - exactly the same ABI as their backing integer.
Each field of a packed struct is interpreted as a logical sequence of bits, arranged from least to most significant. Allowed field types:
An integer field uses exactly as many bits as its bit width. For example, a u5 will use 5 bits of the backing integer.
A bool field uses exactly 1 bit.
An enum field uses exactly the bit width of its integer tag type.
A packed union field uses exactly the bit width of the union field with the largest bit width.
A packed struct field uses the bits of its backing integer.
This means that a packed struct can participate in a @bitCast or a @ptrCast to reinterpret memory. This even works at comptime:
test_packed_structs.zig
const std = @import("std");
const native_endian = @import("builtin").target.cpu.arch.endian();
const expect = std.testing.expect;
const Full = packed struct {
number: u16,
};
const Divided = packed struct {
half1: u8,
quarter3: u4,
quarter4: u4,
};
test "@bitCast between packed structs" {
try doTheTest();
try comptime doTheTest();
}
fn doTheTest() !void {
try expect(@sizeOf(Full) == 2);
try expect(@sizeOf(Divided) == 2);
const full = Full{ .number = 0x1234 };
const divided: Divided = @bitCast(full);
try expect(divided.half1 == 0x34);
try expect(divided.quarter3 == 0x2);
try expect(divided.quarter4 == 0x1);
const ordered: [2]u8 = @bitCast(full);
switch (native_endian) {
.big => {
try expect(ordered[0] == 0x12);
try expect(ordered[1] == 0x34);
},
.little => {
try expect(ordered[0] == 0x34);
try expect(ordered[1] == 0x12);
},
}
}
Shell
$ zig test test_packed_structs.zig
1/1 test_packed_structs.test.@bitCast between packed structs...OK
All 1 tests passed.
The backing integer can be inferred or explicitly provided. When inferred, it will be unsigned. When explicitly provided, its bit width will be enforced at compile time to exactly match the total bit width of the fields:
test_missized_packed_struct.zig
test "missized packed struct" {
const S = packed struct(u32) { a: u16, b: u8 };
_ = S{ .a = 4, .b = 2 };
}
Shell
$ zig test test_missized_packed_struct.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_missized_packed_struct.zig:2:29: error: backing integer type 'u32' has bit size 32 but the struct fields have a total bit size of 24
const S = packed struct(u32) { a: u16, b: u8 };
^~~
referenced by:
test.missized packed struct: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_missized_packed_struct.zig:2:22
Zig allows the address to be taken of a non-byte-aligned field:
test_pointer_to_non-byte_aligned_field.zig
const std = @import("std");
const expect = std.testing.expect;
const BitField = packed struct {
a: u3,
b: u3,
c: u2,
};
var foo = BitField{
.a = 1,
.b = 2,
.c = 3,
};
test "pointer to non-byte-aligned field" {
const ptr = &foo.b;
try expect(ptr.* == 2);
}
Shell
$ zig test test_pointer_to_non-byte_aligned_field.zig
1/1 test_pointer_to_non-byte_aligned_field.test.pointer to non-byte-aligned field...OK
All 1 tests passed.
However, the pointer to a non-byte-aligned field has special properties and cannot be passed when a normal pointer is expected:
test_misaligned_pointer.zig
const std = @import("std");
const expect = std.testing.expect;
const BitField = packed struct {
a: u3,
b: u3,
c: u2,
};
var bit_field = BitField{
.a = 1,
.b = 2,
.c = 3,
};
test "pointer to non-byte-aligned field" {
try expect(bar(&bit_field.b) == 2);
}
fn bar(x: *const u3) u3 {
return x.*;
}
Shell
$ zig test test_misaligned_pointer.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_misaligned_pointer.zig:17:20: error: expected type '*const u3', found '*align(1:3:1) u3'
try expect(bar(&bit_field.b) == 2);
^~~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_misaligned_pointer.zig:17:20: note: pointer host size '1' cannot cast into pointer host size '0'
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_misaligned_pointer.zig:17:20: note: pointer bit offset '3' cannot cast into pointer bit offset '0'
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_misaligned_pointer.zig:20:11: note: parameter type declared here
fn bar(x: *const u3) u3 {
^~~~~~~~~
In this case, the function bar cannot be called because the pointer to the non-ABI-aligned field mentions the bit offset, but the function expects an ABI-aligned pointer.
Pointers to non-ABI-aligned fields share the same address as the other fields within their host integer:
test_packed_struct_field_address.zig
const std = @import("std");
const expect = std.testing.expect;
const BitField = packed struct {
a: u3,
b: u3,
c: u2,
};
var bit_field = BitField{
.a = 1,
.b = 2,
.c = 3,
};
test "pointers of sub-byte-aligned fields share addresses" {
try expect(@intFromPtr(&bit_field.a) == @intFromPtr(&bit_field.b));
try expect(@intFromPtr(&bit_field.a) == @intFromPtr(&bit_field.c));
}
Shell
$ zig test test_packed_struct_field_address.zig
1/1 test_packed_struct_field_address.test.pointers of sub-byte-aligned fields share addresses...OK
All 1 tests passed.
This can be observed with @bitOffsetOf and offsetOf:
test_bitOffsetOf_offsetOf.zig
const std = @import("std");
const expect = std.testing.expect;
const BitField = packed struct {
a: u3,
b: u3,
c: u2,
};
test "offsets of non-byte-aligned fields" {
comptime {
try expect(@bitOffsetOf(BitField, "a") == 0);
try expect(@bitOffsetOf(BitField, "b") == 3);
try expect(@bitOffsetOf(BitField, "c") == 6);
try expect(@offsetOf(BitField, "a") == 0);
try expect(@offsetOf(BitField, "b") == 0);
try expect(@offsetOf(BitField, "c") == 0);
}
}
Shell
$ zig test test_bitOffsetOf_offsetOf.zig
1/1 test_bitOffsetOf_offsetOf.test.offsets of non-byte-aligned fields...OK
All 1 tests passed.
Packed structs have the same alignment as their backing integer, however, overaligned pointers to packed structs can override this:
test_overaligned_packed_struct.zig
const std = @import("std");
const expect = std.testing.expect;
const S = packed struct {
a: u32,
b: u32,
};
test "overaligned pointer to packed struct" {
var foo: S align(4) = .{ .a = 1, .b = 2 };
const ptr: *align(4) S = &foo;
const ptr_to_b: *u32 = &ptr.b;
try expect(ptr_to_b.* == 2);
}
Shell
$ zig test test_overaligned_packed_struct.zig
1/1 test_overaligned_packed_struct.test.overaligned pointer to packed struct...OK
All 1 tests passed.
It's also possible to set alignment of struct fields:
test_aligned_struct_fields.zig
const std = @import("std");
const expectEqual = std.testing.expectEqual;
test "aligned struct fields" {
const S = struct {
a: u32 align(2),
b: u32 align(64),
};
var foo = S{ .a = 1, .b = 2 };
try expectEqual(64, @alignOf(S));
try expectEqual(*align(2) u32, @TypeOf(&foo.a));
try expectEqual(*align(64) u32, @TypeOf(&foo.b));
}
Shell
$ zig test test_aligned_struct_fields.zig
1/1 test_aligned_struct_fields.test.aligned struct fields...OK
All 1 tests passed.
Equating packed structs results in a comparison of the backing integer, and only works for the == and != Operators.
test_packed_struct_equality.zig
const std = @import("std");
const expect = std.testing.expect;
test "packed struct equality" {
const S = packed struct {
a: u4,
b: u4,
};
const x: S = .{ .a = 1, .b = 2 };
const y: S = .{ .b = 2, .a = 1 };
try expect(x == y);
}
Shell
$ zig test test_packed_struct_equality.zig
1/1 test_packed_struct_equality.test.packed struct equality...OK
All 1 tests passed.
Field access and assignment can be understood as shorthand for bitshifts on the backing integer. These operations are not atomic, so beware using field access syntax when combined with memory-mapped input-output (MMIO). Instead of field access on volatile Pointers, construct a fully-formed new value first, then write that value to the volatile pointer.
packed_struct_mmio.zig
pub const GpioRegister = packed struct(u8) {
GPIO0: bool,
GPIO1: bool,
GPIO2: bool,
GPIO3: bool,
reserved: u4 = 0,
};
const gpio: *volatile GpioRegister = @ptrFromInt(0x0123);
pub fn writeToGpio(new_states: GpioRegister) void {
// Example of what not to do:
// BAD! gpio.GPIO0 = true; BAD!
// Instead, do this:
gpio.* = new_states;
}
Struct Naming
Since all structs are anonymous, Zig infers the type name based on a few rules.
If the struct is in the initialization expression of a variable, it gets named after that variable.
If the struct is in the return expression, it gets named after the function it is returning from, with the parameter values serialized.
Otherwise, the struct gets a name such as (filename.funcname__struct_ID).
If the struct is declared inside another struct, it gets named after both the parent struct and the name inferred by the previous rules, separated by a dot.
struct_name.zig
const std = @import("std");
pub fn main() void {
const Foo = struct {};
std.debug.print("variable: {s}\n", .{@typeName(Foo)});
std.debug.print("anonymous: {s}\n", .{@typeName(struct {})});
std.debug.print("function: {s}\n", .{@typeName(List(i32))});
}
fn List(comptime T: type) type {
return struct {
x: T,
};
}
Shell
$ zig build-exe struct_name.zig
$ ./struct_name
variable: struct_name.main.Foo
anonymous: struct_name.main__struct_23311
function: struct_name.List(i32)
Anonymous Struct Literals
Zig allows omitting the struct type of a literal. When the result is coerced, the struct literal will directly instantiate the result location, with no copy:
test_struct_result.zig
const std = @import("std");
const expect = std.testing.expect;
const Point = struct { x: i32, y: i32 };
test "anonymous struct literal" {
const pt: Point = .{
.x = 13,
.y = 67,
};
try expect(pt.x == 13);
try expect(pt.y == 67);
}
Shell
$ zig test test_struct_result.zig
1/1 test_struct_result.test.anonymous struct literal...OK
All 1 tests passed.
The struct type can be inferred. Here the result location does not include a type, and so Zig infers the type:
test_anonymous_struct.zig
const std = @import("std");
const expect = std.testing.expect;
test "fully anonymous struct" {
try check(.{
.int = @as(u32, 1234),
.float = @as(f64, 12.34),
.b = true,
.s = "hi",
});
}
fn check(args: anytype) !void {
try expect(args.int == 1234);
try expect(args.float == 12.34);
try expect(args.b);
try expect(args.s[0] == 'h');
try expect(args.s[1] == 'i');
}
Shell
$ zig test test_anonymous_struct.zig
1/1 test_anonymous_struct.test.fully anonymous struct...OK
All 1 tests passed.
Tuples
Anonymous structs can be created without specifying field names, and are referred to as "tuples". An empty tuple looks like .{} and can be seen in one of the Hello World examples.
The fields are implicitly named using numbers starting from 0. Because their names are integers, they cannot be accessed with . syntax without also wrapping them in @"". Names inside @"" are always recognised as identifiers.
Like arrays, tuples have a .len field, can be indexed (provided the index is comptime-known) and work with the ++ and ** operators. They can also be iterated over with inline for.
test_tuples.zig
const std = @import("std");
const expect = std.testing.expect;
test "tuple" {
const values = .{
@as(u32, 1234),
@as(f64, 12.34),
true,
"hi",
} ++ .{false} ** 2;
try expect(values[0] == 1234);
try expect(values[4] == false);
inline for (values, 0..) |v, i| {
if (i != 2) continue;
try expect(v);
}
try expect(values.len == 6);
try expect(values.@"3"[0] == 'h');
}
Shell
$ zig test test_tuples.zig
1/1 test_tuples.test.tuple...OK
All 1 tests passed.
Destructuring Tuples
Tuples can be destructured.
Tuple destructuring is helpful for returning multiple values from a block:
destructuring_block.zig
const print = @import("std").debug.print;
pub fn main() void {
const digits = [_]i8 { 3, 8, 9, 0, 7, 4, 1 };
const min, const max = blk: {
var min: i8 = 127;
var max: i8 = -128;
for (digits) |digit| {
if (digit < min) min = digit;
if (digit > max) max = digit;
}
break :blk .{ min, max };
};
print("min = {}", .{ min });
print("max = {}", .{ max });
}
Shell
$ zig build-exe destructuring_block.zig
$ ./destructuring_block
min = 0max = 9
Tuple destructuring is helpful for dealing with functions and built-ins that return multiple values as a tuple:
destructuring_return_value.zig
const print = @import("std").debug.print;
fn divmod(numerator: u32, denominator: u32) struct { u32, u32 } {
return .{ numerator / denominator, numerator % denominator };
}
pub fn main() void {
const div, const mod = divmod(10, 3);
print("10 / 3 = {}\n", .{div});
print("10 % 3 = {}\n", .{mod});
}
Shell
$ zig build-exe destructuring_return_value.zig
$ ./destructuring_return_value
10 / 3 = 3
10 % 3 = 1
See also:
Destructuring
Destructuring Arrays
Destructuring Vectors
See also:
comptime
@fieldParentPtr
enum
test_enums.zig
const expect = @import("std").testing.expect;
const mem = @import("std").mem;
// Declare an enum.
const Type = enum {
ok,
not_ok,
};
// Declare a specific enum field.
const c = Type.ok;
// If you want access to the ordinal value of an enum, you
// can specify the tag type.
const Value = enum(u2) {
zero,
one,
two,
};
// Now you can cast between u2 and Value.
// The ordinal value starts from 0, counting up by 1 from the previous member.
test "enum ordinal value" {
try expect(@intFromEnum(Value.zero) == 0);
try expect(@intFromEnum(Value.one) == 1);
try expect(@intFromEnum(Value.two) == 2);
}
// You can override the ordinal value for an enum.
const Value2 = enum(u32) {
hundred = 100,
thousand = 1000,
million = 1000000,
};
test "set enum ordinal value" {
try expect(@intFromEnum(Value2.hundred) == 100);
try expect(@intFromEnum(Value2.thousand) == 1000);
try expect(@intFromEnum(Value2.million) == 1000000);
}
// You can also override only some values.
const Value3 = enum(u4) {
a,
b = 8,
c,
d = 4,
e,
};
test "enum implicit ordinal values and overridden values" {
try expect(@intFromEnum(Value3.a) == 0);
try expect(@intFromEnum(Value3.b) == 8);
try expect(@intFromEnum(Value3.c) == 9);
try expect(@intFromEnum(Value3.d) == 4);
try expect(@intFromEnum(Value3.e) == 5);
}
// Enums can have methods, the same as structs and unions.
// Enum methods are not special, they are only namespaced
// functions that you can call with dot syntax.
const Suit = enum {
clubs,
spades,
diamonds,
hearts,
pub fn isClubs(self: Suit) bool {
return self == Suit.clubs;
}
};
test "enum method" {
const p = Suit.spades;
try expect(!p.isClubs());
}
// An enum can be switched upon.
const Foo = enum {
string,
number,
none,
};
test "enum switch" {
const p = Foo.number;
const what_is_it = switch (p) {
Foo.string => "this is a string",
Foo.number => "this is a number",
Foo.none => "this is a none",
};
try expect(mem.eql(u8, what_is_it, "this is a number"));
}
// @typeInfo can be used to access the integer tag type of an enum.
const Small = enum {
one,
two,
three,
four,
};
test "std.meta.Tag" {
try expect(@typeInfo(Small).@"enum".tag_type == u2);
}
// @typeInfo tells us the field count and the fields names:
test "@typeInfo" {
try expect(@typeInfo(Small).@"enum".fields.len == 4);
try expect(mem.eql(u8, @typeInfo(Small).@"enum".fields[1].name, "two"));
}
// @tagName gives a [:0]const u8 representation of an enum value:
test "@tagName" {
try expect(mem.eql(u8, @tagName(Small.three), "three"));
}
Shell
$ zig test test_enums.zig
1/8 test_enums.test.enum ordinal value...OK
2/8 test_enums.test.set enum ordinal value...OK
3/8 test_enums.test.enum implicit ordinal values and overridden values...OK
4/8 test_enums.test.enum method...OK
5/8 test_enums.test.enum switch...OK
6/8 test_enums.test.std.meta.Tag...OK
7/8 test_enums.test.@typeInfo...OK
8/8 test_enums.test.@tagName...OK
All 8 tests passed.
See also:
@typeInfo
@tagName
@sizeOf
extern enum
By default, enums are not guaranteed to be compatible with the C ABI:
enum_export_error.zig
const Foo = enum { a, b, c };
export fn entry(foo: Foo) void {
_ = foo;
}
Shell
$ zig build-obj enum_export_error.zig -target x86_64-linux
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/enum_export_error.zig:2:17: error: parameter of type 'enum_export_error.Foo' not allowed in function with calling convention 'x86_64_sysv'
export fn entry(foo: Foo) void {
^~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/enum_export_error.zig:2:17: note: enum tag type 'u2' is not extern compatible
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/enum_export_error.zig:2:17: note: only integers with 0, 8, 16, 32, 64 and 128 bits are extern compatible
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/enum_export_error.zig:1:13: note: enum declared here
const Foo = enum { a, b, c };
^~~~~~~~~~~~~~~~
referenced by:
root: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:3:22
comptime: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:31:9
2 reference(s) hidden; use '-freference-trace=4' to see all references
For a C-ABI-compatible enum, provide an explicit tag type to the enum:
enum_export.zig
const Foo = enum(c_int) { a, b, c };
export fn entry(foo: Foo) void {
_ = foo;
}
Shell
$ zig build-obj enum_export.zig
Enum Literals
Enum literals allow specifying the name of an enum field without specifying the enum type:
test_enum_literals.zig
const std = @import("std");
const expect = std.testing.expect;
const Color = enum {
auto,
off,
on,
};
test "enum literals" {
const color1: Color = .auto;
const color2 = Color.auto;
try expect(color1 == color2);
}
test "switch using enum literals" {
const color = Color.on;
const result = switch (color) {
.auto => false,
.on => true,
.off => false,
};
try expect(result);
}
Shell
$ zig test test_enum_literals.zig
1/2 test_enum_literals.test.enum literals...OK
2/2 test_enum_literals.test.switch using enum literals...OK
All 2 tests passed.
Non-exhaustive enum
A non-exhaustive enum can be created by adding a trailing _ field. The enum must specify a tag type and cannot consume every enumeration value.
@enumFromInt on a non-exhaustive enum involves the safety semantics of @intCast to the integer tag type, but beyond that always results in a well-defined enum value.
A switch on a non-exhaustive enum can include a _ prong as an alternative to an else prong. With a _ prong the compiler errors if all the known tag names are not handled by the switch.
test_switch_non-exhaustive.zig
const std = @import("std");
const expect = std.testing.expect;
const Number = enum(u8) {
one,
two,
three,
_,
};
test "switch on non-exhaustive enum" {
const number = Number.one;
const result = switch (number) {
.one => true,
.two, .three => false,
_ => false,
};
try expect(result);
const is_one = switch (number) {
.one => true,
else => false,
};
try expect(is_one);
}
Shell
$ zig test test_switch_non-exhaustive.zig
1/1 test_switch_non-exhaustive.test.switch on non-exhaustive enum...OK
All 1 tests passed.
union
A bare union defines a set of possible types that a value can be as a list of fields. Only one field can be active at a time. The in-memory representation of bare unions is not guaranteed. Bare unions cannot be used to reinterpret memory. For that, use @ptrCast, or use an extern union or a packed union which have guaranteed in-memory layout. Accessing the non-active field is safety-checked Illegal Behavior:
test_wrong_union_access.zig
const Payload = union {
int: i64,
float: f64,
boolean: bool,
};
test "simple union" {
var payload = Payload{ .int = 1234 };
payload.float = 12.34;
}
Shell
$ zig test test_wrong_union_access.zig
1/1 test_wrong_union_access.test.simple union...thread 3522146 panic: access of union field 'float' while field 'int' is active
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_wrong_union_access.zig:8:12: 0x102d083 in test.simple union (test_wrong_union_access.zig)
payload.float = 12.34;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x1176023 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:64:28: 0x116c0c7 in main (test_runner.zig)
return mainTerminal();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x11651fd in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x1164ad3 in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/d84c909152a51c7143e80c061415ea41/test --seed=0xb9d96e9
You can activate another field by assigning the entire union:
test_simple_union.zig
const std = @import("std");
const expect = std.testing.expect;
const Payload = union {
int: i64,
float: f64,
boolean: bool,
};
test "simple union" {
var payload = Payload{ .int = 1234 };
try expect(payload.int == 1234);
payload = Payload{ .float = 12.34 };
try expect(payload.float == 12.34);
}
Shell
$ zig test test_simple_union.zig
1/1 test_simple_union.test.simple union...OK
All 1 tests passed.
In order to use switch with a union, it must be a Tagged union.
To initialize a union when the tag is a comptime-known name, see @unionInit.
Tagged union
Unions can be declared with an enum tag type. This turns the union into a tagged union, which makes it eligible to use with switch expressions. Tagged unions coerce to their tag type: Type Coercion: Unions and Enums.
test_tagged_union.zig
const std = @import("std");
const expect = std.testing.expect;
const ComplexTypeTag = enum {
ok,
not_ok,
};
const ComplexType = union(ComplexTypeTag) {
ok: u8,
not_ok: void,
};
test "switch on tagged union" {
const c = ComplexType{ .ok = 42 };
try expect(@as(ComplexTypeTag, c) == ComplexTypeTag.ok);
switch (c) {
.ok => |value| try expect(value == 42),
.not_ok => unreachable,
}
}
test "get tag type" {
try expect(std.meta.Tag(ComplexType) == ComplexTypeTag);
}
Shell
$ zig test test_tagged_union.zig
1/2 test_tagged_union.test.switch on tagged union...OK
2/2 test_tagged_union.test.get tag type...OK
All 2 tests passed.
In order to modify the payload of a tagged union in a switch expression, place a * before the variable name to make it a pointer:
test_switch_modify_tagged_union.zig
const std = @import("std");
const expect = std.testing.expect;
const ComplexTypeTag = enum {
ok,
not_ok,
};
const ComplexType = union(ComplexTypeTag) {
ok: u8,
not_ok: void,
};
test "modify tagged union in switch" {
var c = ComplexType{ .ok = 42 };
switch (c) {
ComplexTypeTag.ok => |*value| value.* += 1,
ComplexTypeTag.not_ok => unreachable,
}
try expect(c.ok == 43);
}
Shell
$ zig test test_switch_modify_tagged_union.zig
1/1 test_switch_modify_tagged_union.test.modify tagged union in switch...OK
All 1 tests passed.
Unions can be made to infer the enum tag type. Further, unions can have methods just like structs and enums.
test_union_method.zig
const std = @import("std");
const expect = std.testing.expect;
const Variant = union(enum) {
int: i32,
boolean: bool,
// void can be omitted when inferring enum tag type.
none,
fn truthy(self: Variant) bool {
return switch (self) {
Variant.int => |x_int| x_int != 0,
Variant.boolean => |x_bool| x_bool,
Variant.none => false,
};
}
};
test "union method" {
var v1: Variant = .{ .int = 1 };
var v2: Variant = .{ .boolean = false };
var v3: Variant = .none;
try expect(v1.truthy());
try expect(!v2.truthy());
try expect(!v3.truthy());
}
Shell
$ zig test test_union_method.zig
1/1 test_union_method.test.union method...OK
All 1 tests passed.
@tagName can be used to return a comptime [:0]const u8 value representing the field name:
test_tagName.zig
const std = @import("std");
const expect = std.testing.expect;
const Small2 = union(enum) {
a: i32,
b: bool,
c: u8,
};
test "@tagName" {
try expect(std.mem.eql(u8, @tagName(Small2.a), "a"));
}
Shell
$ zig test test_tagName.zig
1/1 test_tagName.test.@tagName...OK
All 1 tests passed.
extern union
An extern union has memory layout guaranteed to be compatible with the target C ABI.
See also:
extern struct
packed union
A packed union has well-defined in-memory layout and is eligible to be in a packed struct.
Anonymous Union Literals
Anonymous Struct Literals syntax can be used to initialize unions without specifying the type:
test_anonymous_union.zig
const std = @import("std");
const expect = std.testing.expect;
const Number = union {
int: i32,
float: f64,
};
test "anonymous union literal syntax" {
const i: Number = .{ .int = 42 };
const f = makeNumber();
try expect(i.int == 42);
try expect(f.float == 12.34);
}
fn makeNumber() Number {
return .{ .float = 12.34 };
}
Shell
$ zig test test_anonymous_union.zig
1/1 test_anonymous_union.test.anonymous union literal syntax...OK
All 1 tests passed.
opaque
opaque {} declares a new type with an unknown (but non-zero) size and alignment. It can contain declarations the same as structs, unions, and enums.
This is typically used for type safety when interacting with C code that does not expose struct details. Example:
test_opaque.zig
const Derp = opaque {};
const Wat = opaque {};
extern fn bar(d: *Derp) void;
fn foo(w: *Wat) callconv(.c) void {
bar(w);
}
test "call foo" {
foo(undefined);
}
Shell
$ zig test test_opaque.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_opaque.zig:6:9: error: expected type '*test_opaque.Derp', found '*test_opaque.Wat'
bar(w);
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_opaque.zig:6:9: note: pointer type child 'test_opaque.Wat' cannot cast into pointer type child 'test_opaque.Derp'
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_opaque.zig:2:13: note: opaque declared here
const Wat = opaque {};
^~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_opaque.zig:1:14: note: opaque declared here
const Derp = opaque {};
^~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_opaque.zig:4:18: note: parameter type declared here
extern fn bar(d: *Derp) void;
^~~~~
referenced by:
test.call foo: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_opaque.zig:10:8
Blocks
Blocks are used to limit the scope of variable declarations:
test_blocks.zig
test "access variable after block scope" {
{
var x: i32 = 1;
_ = &x;
}
x += 1;
}
Shell
$ zig test test_blocks.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_blocks.zig:6:5: error: use of undeclared identifier 'x'
x += 1;
^
Blocks are expressions. When labeled, break can be used to return a value from the block:
test_labeled_break.zig
const std = @import("std");
const expect = std.testing.expect;
test "labeled break from labeled block expression" {
var y: i32 = 123;
const x = blk: {
y += 1;
break :blk y;
};
try expect(x == 124);
try expect(y == 124);
}
Shell
$ zig test test_labeled_break.zig
1/1 test_labeled_break.test.labeled break from labeled block expression...OK
All 1 tests passed.
Here, blk can be any name.
See also:
Labeled while
Labeled for
Shadowing
Identifiers are never allowed to "hide" other identifiers by using the same name:
test_shadowing.zig
const pi = 3.14;
test "inside test block" {
// Let's even go inside another block
{
var pi: i32 = 1234;
}
}
Shell
$ zig test test_shadowing.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_shadowing.zig:6:13: error: local variable shadows declaration of 'pi'
var pi: i32 = 1234;
^~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_shadowing.zig:1:1: note: declared here
const pi = 3.14;
^~~~~~~~~~~~~~~
Because of this, when you read Zig code you can always rely on an identifier to consistently mean the same thing within the scope it is defined. Note that you can, however, use the same name if the scopes are separate:
test_scopes.zig
test "separate scopes" {
{
const pi = 3.14;
_ = pi;
}
{
var pi: bool = true;
_ = π
}
}
Shell
$ zig test test_scopes.zig
1/1 test_scopes.test.separate scopes...OK
All 1 tests passed.
Empty Blocks
An empty block is equivalent to void{}:
test_empty_block.zig
const std = @import("std");
const expect = std.testing.expect;
test {
const a = {};
const b = void{};
try expect(@TypeOf(a) == void);
try expect(@TypeOf(b) == void);
try expect(a == b);
}
Shell
$ zig test test_empty_block.zig
1/1 test_empty_block.test_0...OK
All 1 tests passed.
switch
test_switch.zig
const std = @import("std");
const builtin = @import("builtin");
const expect = std.testing.expect;
test "switch simple" {
const a: u64 = 10;
const zz: u64 = 103;
// All branches of a switch expression must be able to be coerced to a
// common type.
//
// Branches cannot fallthrough. If fallthrough behavior is desired, combine
// the cases and use an if.
const b = switch (a) {
// Multiple cases can be combined via a ','
1, 2, 3 => 0,
// Ranges can be specified using the ... syntax. These are inclusive
// of both ends.
5...100 => 1,
// Branches can be arbitrarily complex.
101 => blk: {
const c: u64 = 5;
break :blk c * 2 + 1;
},
// Switching on arbitrary expressions is allowed as long as the
// expression is known at compile-time.
zz => zz,
blk: {
const d: u32 = 5;
const e: u32 = 100;
break :blk d + e;
} => 107,
// The else branch catches everything not already captured.
// Else branches are mandatory unless the entire range of values
// is handled.
else => 9,
};
try expect(b == 1);
}
// Switch expressions can be used outside a function:
const os_msg = switch (builtin.target.os.tag) {
.linux => "we found a linux user",
else => "not a linux user",
};
// Inside a function, switch statements implicitly are compile-time
// evaluated if the target expression is compile-time known.
test "switch inside function" {
switch (builtin.target.os.tag) {
.fuchsia => {
// On an OS other than fuchsia, block is not even analyzed,
// so this compile error is not triggered.
// On fuchsia this compile error would be triggered.
@compileError("fuchsia not supported");
},
else => {},
}
}
Shell
$ zig test test_switch.zig
1/2 test_switch.test.switch simple...OK
2/2 test_switch.test.switch inside function...OK
All 2 tests passed.
switch can be used to capture the field values of a Tagged union. Modifications to the field values can be done by placing a * before the capture variable name, turning it into a pointer.
test_switch_tagged_union.zig
const expect = @import("std").testing.expect;
test "switch on tagged union" {
const Point = struct {
x: u8,
y: u8,
};
const Item = union(enum) {
a: u32,
c: Point,
d,
e: u32,
};
var a = Item{ .c = Point{ .x = 1, .y = 2 } };
// Switching on more complex enums is allowed.
const b = switch (a) {
// A capture group is allowed on a match, and will return the enum
// value matched. If the payload types of both cases are the same
// they can be put into the same switch prong.
Item.a, Item.e => |item| item,
// A reference to the matched value can be obtained using `*` syntax.
Item.c => |*item| blk: {
item.*.x += 1;
break :blk 6;
},
// No else is required if the types cases was exhaustively handled
Item.d => 8,
};
try expect(b == 6);
try expect(a.c.x == 2);
}
Shell
$ zig test test_switch_tagged_union.zig
1/1 test_switch_tagged_union.test.switch on tagged union...OK
All 1 tests passed.
See also:
comptime
enum
@compileError
Compile Variables
Exhaustive Switching
When a switch expression does not have an else clause, it must exhaustively list all the possible values. Failure to do so is a compile error:
test_unhandled_enumeration_value.zig
const Color = enum {
auto,
off,
on,
};
test "exhaustive switching" {
const color = Color.off;
switch (color) {
Color.auto => {},
Color.on => {},
}
}
Shell
$ zig test test_unhandled_enumeration_value.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unhandled_enumeration_value.zig:9:5: error: switch must handle all possibilities
switch (color) {
^~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unhandled_enumeration_value.zig:3:5: note: unhandled enumeration value: 'off'
off,
^~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unhandled_enumeration_value.zig:1:15: note: enum 'test_unhandled_enumeration_value.Color' declared here
const Color = enum {
^~~~
Switching with Enum Literals
Enum Literals can be useful to use with switch to avoid repetitively specifying enum or union types:
test_exhaustive_switch.zig
const std = @import("std");
const expect = std.testing.expect;
const Color = enum {
auto,
off,
on,
};
test "enum literals with switch" {
const color = Color.off;
const result = switch (color) {
.auto => false,
.on => false,
.off => true,
};
try expect(result);
}
Shell
$ zig test test_exhaustive_switch.zig
1/1 test_exhaustive_switch.test.enum literals with switch...OK
All 1 tests passed.
Labeled switch
When a switch statement is labeled, it can be referenced from a break or continue. break will return a value from the switch.
A continue targeting a switch must have an operand. When executed, it will jump to the matching prong, as if the switch were executed again with the continue's operand replacing the initial switch value.
test_switch_continue.zig
const std = @import("std");
test "switch continue" {
sw: switch (@as(i32, 5)) {
5 => continue :sw 4,
// `continue` can occur multiple times within a single switch prong.
2...4 => |v| {
if (v > 3) {
continue :sw 2;
} else if (v == 3) {
// `break` can target labeled loops.
break :sw;
}
continue :sw 1;
},
1 => return,
else => unreachable,
}
}
Shell
$ zig test test_switch_continue.zig
1/1 test_switch_continue.test.switch continue...OK
All 1 tests passed.
Semantically, this is equivalent to the following loop:
test_switch_continue_equivalent.zig
const std = @import("std");
test "switch continue, equivalent loop" {
var sw: i32 = 5;
while (true) {
switch (sw) {
5 => {
sw = 4;
continue;
},
2...4 => |v| {
if (v > 3) {
sw = 2;
continue;
} else if (v == 3) {
break;
}
sw = 1;
continue;
},
1 => return,
else => unreachable,
}
}
}
Shell
$ zig test test_switch_continue_equivalent.zig
1/1 test_switch_continue_equivalent.test.switch continue, equivalent loop...OK
All 1 tests passed.
This can improve clarity of (for example) state machines, where the syntax continue :sw .next_state is unambiguous, explicit, and immediately understandable.
However, the motivating example is a switch on each element of an array, where using a single switch can improve clarity and performance:
test_switch_dispatch_loop.zig
const std = @import("std");
const expectEqual = std.testing.expectEqual;
const Instruction = enum {
add,
mul,
end,
};
fn evaluate(initial_stack: []const i32, code: []const Instruction) !i32 {
var stack = try std.BoundedArray(i32, 8).fromSlice(initial_stack);
var ip: usize = 0;
return vm: switch (code[ip]) {
// Because all code after `continue` is unreachable, this branch does
// not provide a result.
.add => {
try stack.append(stack.pop().? + stack.pop().?);
ip += 1;
continue :vm code[ip];
},
.mul => {
try stack.append(stack.pop().? * stack.pop().?);
ip += 1;
continue :vm code[ip];
},
.end => stack.pop().?,
};
}
test "evaluate" {
const result = try evaluate(&.{ 7, 2, -3 }, &.{ .mul, .add, .end });
try expectEqual(1, result);
}
Shell
$ zig test test_switch_dispatch_loop.zig
1/1 test_switch_dispatch_loop.test.evaluate...OK
All 1 tests passed.
If the operand to continue is comptime-known, then it can be lowered to an unconditional branch to the relevant case. Such a branch is perfectly predicted, and hence typically very fast to execute.
If the operand is runtime-known, each continue can embed a conditional branch inline (ideally through a jump table), which allows a CPU to predict its target independently of any other prong. A loop-based lowering would force every branch through the same dispatch point, hindering branch prediction.
Inline Switch Prongs
Switch prongs can be marked as inline to generate the prong's body for each possible value it could have, making the captured value comptime.
test_inline_switch.zig
const std = @import("std");
const expect = std.testing.expect;
const expectError = std.testing.expectError;
fn isFieldOptional(comptime T: type, field_index: usize) !bool {
const fields = @typeInfo(T).@"struct".fields;
return switch (field_index) {
// This prong is analyzed twice with `idx` being a
// comptime-known value each time.
inline 0, 1 => |idx| @typeInfo(fields[idx].type) == .optional,
else => return error.IndexOutOfBounds,
};
}
const Struct1 = struct { a: u32, b: ?u32 };
test "using @typeInfo with runtime values" {
var index: usize = 0;
try expect(!try isFieldOptional(Struct1, index));
index += 1;
try expect(try isFieldOptional(Struct1, index));
index += 1;
try expectError(error.IndexOutOfBounds, isFieldOptional(Struct1, index));
}
// Calls to `isFieldOptional` on `Struct1` get unrolled to an equivalent
// of this function:
fn isFieldOptionalUnrolled(field_index: usize) !bool {
return switch (field_index) {
0 => false,
1 => true,
else => return error.IndexOutOfBounds,
};
}
Shell
$ zig test test_inline_switch.zig
1/1 test_inline_switch.test.using @typeInfo with runtime values...OK
All 1 tests passed.
The inline keyword may also be combined with ranges:
inline_prong_range.zig
fn isFieldOptional(comptime T: type, field_index: usize) !bool {
const fields = @typeInfo(T).@"struct".fields;
return switch (field_index) {
inline 0...fields.len - 1 => |idx| @typeInfo(fields[idx].type) == .optional,
else => return error.IndexOutOfBounds,
};
}
inline else prongs can be used as a type safe alternative to inline for loops:
test_inline_else.zig
const std = @import("std");
const expect = std.testing.expect;
const SliceTypeA = extern struct {
len: usize,
ptr: [*]u32,
};
const SliceTypeB = extern struct {
ptr: [*]SliceTypeA,
len: usize,
};
const AnySlice = union(enum) {
a: SliceTypeA,
b: SliceTypeB,
c: []const u8,
d: []AnySlice,
};
fn withFor(any: AnySlice) usize {
const Tag = @typeInfo(AnySlice).@"union".tag_type.?;
inline for (@typeInfo(Tag).@"enum".fields) |field| {
// With `inline for` the function gets generated as
// a series of `if` statements relying on the optimizer
// to convert it to a switch.
if (field.value == @intFromEnum(any)) {
return @field(any, field.name).len;
}
}
// When using `inline for` the compiler doesn't know that every
// possible case has been handled requiring an explicit `unreachable`.
unreachable;
}
fn withSwitch(any: AnySlice) usize {
return switch (any) {
// With `inline else` the function is explicitly generated
// as the desired switch and the compiler can check that
// every possible case is handled.
inline else => |slice| slice.len,
};
}
test "inline for and inline else similarity" {
const any = AnySlice{ .c = "hello" };
try expect(withFor(any) == 5);
try expect(withSwitch(any) == 5);
}
Shell
$ zig test test_inline_else.zig
1/1 test_inline_else.test.inline for and inline else similarity...OK
All 1 tests passed.
When using an inline prong switching on an union an additional capture can be used to obtain the union's enum tag value.
test_inline_switch_union_tag.zig
const std = @import("std");
const expect = std.testing.expect;
const U = union(enum) {
a: u32,
b: f32,
};
fn getNum(u: U) u32 {
switch (u) {
// Here `num` is a runtime-known value that is either
// `u.a` or `u.b` and `tag` is `u`'s comptime-known tag value.
inline else => |num, tag| {
if (tag == .b) {
return @intFromFloat(num);
}
return num;
},
}
}
test "test" {
const u = U{ .b = 42 };
try expect(getNum(u) == 42);
}
Shell
$ zig test test_inline_switch_union_tag.zig
1/1 test_inline_switch_union_tag.test.test...OK
All 1 tests passed.
See also:
inline while
inline for
while
A while loop is used to repeatedly execute an expression until some condition is no longer true.
test_while.zig
const expect = @import("std").testing.expect;
test "while basic" {
var i: usize = 0;
while (i < 10) {
i += 1;
}
try expect(i == 10);
}
Shell
$ zig test test_while.zig
1/1 test_while.test.while basic...OK
All 1 tests passed.
Use break to exit a while loop early.
test_while_break.zig
const expect = @import("std").testing.expect;
test "while break" {
var i: usize = 0;
while (true) {
if (i == 10)
break;
i += 1;
}
try expect(i == 10);
}
Shell
$ zig test test_while_break.zig
1/1 test_while_break.test.while break...OK
All 1 tests passed.
Use continue to jump back to the beginning of the loop.
test_while_continue.zig
const expect = @import("std").testing.expect;
test "while continue" {
var i: usize = 0;
while (true) {
i += 1;
if (i < 10)
continue;
break;
}
try expect(i == 10);
}
Shell
$ zig test test_while_continue.zig
1/1 test_while_continue.test.while continue...OK
All 1 tests passed.
While loops support a continue expression which is executed when the loop is continued. The continue keyword respects this expression.
test_while_continue_expression.zig
const expect = @import("std").testing.expect;
test "while loop continue expression" {
var i: usize = 0;
while (i < 10) : (i += 1) {}
try expect(i == 10);
}
test "while loop continue expression, more complicated" {
var i: usize = 1;
var j: usize = 1;
while (i * j < 2000) : ({
i *= 2;
j *= 3;
}) {
const my_ij = i * j;
try expect(my_ij < 2000);
}
}
Shell
$ zig test test_while_continue_expression.zig
1/2 test_while_continue_expression.test.while loop continue expression...OK
2/2 test_while_continue_expression.test.while loop continue expression, more complicated...OK
All 2 tests passed.
While loops are expressions. The result of the expression is the result of the else clause of a while loop, which is executed when the condition of the while loop is tested as false.
break, like return, accepts a value parameter. This is the result of the while expression. When you break from a while loop, the else branch is not evaluated.
test_while_else.zig
const expect = @import("std").testing.expect;
test "while else" {
try expect(rangeHasNumber(0, 10, 5));
try expect(!rangeHasNumber(0, 10, 15));
}
fn rangeHasNumber(begin: usize, end: usize, number: usize) bool {
var i = begin;
return while (i < end) : (i += 1) {
if (i == number) {
break true;
}
} else false;
}
Shell
$ zig test test_while_else.zig
1/1 test_while_else.test.while else...OK
All 1 tests passed.
Labeled while
When a while loop is labeled, it can be referenced from a break or continue from within a nested loop:
test_while_nested_break.zig
test "nested break" {
outer: while (true) {
while (true) {
break :outer;
}
}
}
test "nested continue" {
var i: usize = 0;
outer: while (i < 10) : (i += 1) {
while (true) {
continue :outer;
}
}
}
Shell
$ zig test test_while_nested_break.zig
1/2 test_while_nested_break.test.nested break...OK
2/2 test_while_nested_break.test.nested continue...OK
All 2 tests passed.
while with Optionals
Just like if expressions, while loops can take an optional as the condition and capture the payload. When null is encountered the loop exits.
When the |x| syntax is present on a while expression, the while condition must have an Optional Type.
The else branch is allowed on optional iteration. In this case, it will be executed on the first null value encountered.
test_while_null_capture.zig
const expect = @import("std").testing.expect;
test "while null capture" {
var sum1: u32 = 0;
numbers_left = 3;
while (eventuallyNullSequence()) |value| {
sum1 += value;
}
try expect(sum1 == 3);
// null capture with an else block
var sum2: u32 = 0;
numbers_left = 3;
while (eventuallyNullSequence()) |value| {
sum2 += value;
} else {
try expect(sum2 == 3);
}
// null capture with a continue expression
var i: u32 = 0;
var sum3: u32 = 0;
numbers_left = 3;
while (eventuallyNullSequence()) |value| : (i += 1) {
sum3 += value;
}
try expect(i == 3);
}
var numbers_left: u32 = undefined;
fn eventuallyNullSequence() ?u32 {
return if (numbers_left == 0) null else blk: {
numbers_left -= 1;
break :blk numbers_left;
};
}
Shell
$ zig test test_while_null_capture.zig
1/1 test_while_null_capture.test.while null capture...OK
All 1 tests passed.
while with Error Unions
Just like if expressions, while loops can take an error union as the condition and capture the payload or the error code. When the condition results in an error code the else branch is evaluated and the loop is finished.
When the else |x| syntax is present on a while expression, the while condition must have an Error Union Type.
test_while_error_capture.zig
const expect = @import("std").testing.expect;
test "while error union capture" {
var sum1: u32 = 0;
numbers_left = 3;
while (eventuallyErrorSequence()) |value| {
sum1 += value;
} else |err| {
try expect(err == error.ReachedZero);
}
}
var numbers_left: u32 = undefined;
fn eventuallyErrorSequence() anyerror!u32 {
return if (numbers_left == 0) error.ReachedZero else blk: {
numbers_left -= 1;
break :blk numbers_left;
};
}
Shell
$ zig test test_while_error_capture.zig
1/1 test_while_error_capture.test.while error union capture...OK
All 1 tests passed.
inline while
While loops can be inlined. This causes the loop to be unrolled, which allows the code to do some things which only work at compile time, such as use types as first class values.
test_inline_while.zig
const expect = @import("std").testing.expect;
test "inline while loop" {
comptime var i = 0;
var sum: usize = 0;
inline while (i < 3) : (i += 1) {
const T = switch (i) {
0 => f32,
1 => i8,
2 => bool,
else => unreachable,
};
sum += typeNameLength(T);
}
try expect(sum == 9);
}
fn typeNameLength(comptime T: type) usize {
return @typeName(T).len;
}
Shell
$ zig test test_inline_while.zig
1/1 test_inline_while.test.inline while loop...OK
All 1 tests passed.
It is recommended to use inline loops only for one of these reasons:
You need the loop to execute at comptime for the semantics to work.
You have a benchmark to prove that forcibly unrolling the loop in this way is measurably faster.
See also:
if
Optionals
Errors
comptime
unreachable
for
test_for.zig
const expect = @import("std").testing.expect;
test "for basics" {
const items = [_]i32{ 4, 5, 3, 4, 0 };
var sum: i32 = 0;
// For loops iterate over slices and arrays.
for (items) |value| {
// Break and continue are supported.
if (value == 0) {
continue;
}
sum += value;
}
try expect(sum == 16);
// To iterate over a portion of a slice, reslice.
for (items[0..1]) |value| {
sum += value;
}
try expect(sum == 20);
// To access the index of iteration, specify a second condition as well
// as a second capture value.
var sum2: i32 = 0;
for (items, 0..) |_, i| {
try expect(@TypeOf(i) == usize);
sum2 += @as(i32, @intCast(i));
}
try expect(sum2 == 10);
// To iterate over consecutive integers, use the range syntax.
// Unbounded range is always a compile error.
var sum3: usize = 0;
for (0..5) |i| {
sum3 += i;
}
try expect(sum3 == 10);
}
test "multi object for" {
const items = [_]usize{ 1, 2, 3 };
const items2 = [_]usize{ 4, 5, 6 };
var count: usize = 0;
// Iterate over multiple objects.
// All lengths must be equal at the start of the loop, otherwise detectable
// illegal behavior occurs.
for (items, items2) |i, j| {
count += i + j;
}
try expect(count == 21);
}
test "for reference" {
var items = [_]i32{ 3, 4, 2 };
// Iterate over the slice by reference by
// specifying that the capture value is a pointer.
for (&items) |*value| {
value.* += 1;
}
try expect(items[0] == 4);
try expect(items[1] == 5);
try expect(items[2] == 3);
}
test "for else" {
// For allows an else attached to it, the same as a while loop.
const items = [_]?i32{ 3, 4, null, 5 };
// For loops can also be used as expressions.
// Similar to while loops, when you break from a for loop, the else branch is not evaluated.
var sum: i32 = 0;
const result = for (items) |value| {
if (value != null) {
sum += value.?;
}
} else blk: {
try expect(sum == 12);
break :blk sum;
};
try expect(result == 12);
}
Shell
$ zig test test_for.zig
1/4 test_for.test.for basics...OK
2/4 test_for.test.multi object for...OK
3/4 test_for.test.for reference...OK
4/4 test_for.test.for else...OK
All 4 tests passed.
Labeled for
When a for loop is labeled, it can be referenced from a break or continue from within a nested loop:
test_for_nested_break.zig
const std = @import("std");
const expect = std.testing.expect;
test "nested break" {
var count: usize = 0;
outer: for (1..6) |_| {
for (1..6) |_| {
count += 1;
break :outer;
}
}
try expect(count == 1);
}
test "nested continue" {
var count: usize = 0;
outer: for (1..9) |_| {
for (1..6) |_| {
count += 1;
continue :outer;
}
}
try expect(count == 8);
}
Shell
$ zig test test_for_nested_break.zig
1/2 test_for_nested_break.test.nested break...OK
2/2 test_for_nested_break.test.nested continue...OK
All 2 tests passed.
inline for
For loops can be inlined. This causes the loop to be unrolled, which allows the code to do some things which only work at compile time, such as use types as first class values. The capture value and iterator value of inlined for loops are compile-time known.
test_inline_for.zig
const expect = @import("std").testing.expect;
test "inline for loop" {
const nums = [_]i32{ 2, 4, 6 };
var sum: usize = 0;
inline for (nums) |i| {
const T = switch (i) {
2 => f32,
4 => i8,
6 => bool,
else => unreachable,
};
sum += typeNameLength(T);
}
try expect(sum == 9);
}
fn typeNameLength(comptime T: type) usize {
return @typeName(T).len;
}
Shell
$ zig test test_inline_for.zig
1/1 test_inline_for.test.inline for loop...OK
All 1 tests passed.
It is recommended to use inline loops only for one of these reasons:
You need the loop to execute at comptime for the semantics to work.
You have a benchmark to prove that forcibly unrolling the loop in this way is measurably faster.
See also:
while
comptime
Arrays
Slices
if
test_if.zig
// If expressions have three uses, corresponding to the three types:
// * bool
// * ?T
// * anyerror!T
const expect = @import("std").testing.expect;
test "if expression" {
// If expressions are used instead of a ternary expression.
const a: u32 = 5;
const b: u32 = 4;
const result = if (a != b) 47 else 3089;
try expect(result == 47);
}
test "if boolean" {
// If expressions test boolean conditions.
const a: u32 = 5;
const b: u32 = 4;
if (a != b) {
try expect(true);
} else if (a == 9) {
unreachable;
} else {
unreachable;
}
}
test "if error union" {
// If expressions test for errors.
// Note the |err| capture on the else.
const a: anyerror!u32 = 0;
if (a) |value| {
try expect(value == 0);
} else |err| {
_ = err;
unreachable;
}
const b: anyerror!u32 = error.BadValue;
if (b) |value| {
_ = value;
unreachable;
} else |err| {
try expect(err == error.BadValue);
}
// The else and |err| capture is strictly required.
if (a) |value| {
try expect(value == 0);
} else |_| {}
// To check only the error value, use an empty block expression.
if (b) |_| {} else |err| {
try expect(err == error.BadValue);
}
// Access the value by reference using a pointer capture.
var c: anyerror!u32 = 3;
if (c) |*value| {
value.* = 9;
} else |_| {
unreachable;
}
if (c) |value| {
try expect(value == 9);
} else |_| {
unreachable;
}
}
Shell
$ zig test test_if.zig
1/3 test_if.test.if expression...OK
2/3 test_if.test.if boolean...OK
3/3 test_if.test.if error union...OK
All 3 tests passed.
if with Optionals
test_if_optionals.zig
const expect = @import("std").testing.expect;
test "if optional" {
// If expressions test for null.
const a: ?u32 = 0;
if (a) |value| {
try expect(value == 0);
} else {
unreachable;
}
const b: ?u32 = null;
if (b) |_| {
unreachable;
} else {
try expect(true);
}
// The else is not required.
if (a) |value| {
try expect(value == 0);
}
// To test against null only, use the binary equality operator.
if (b == null) {
try expect(true);
}
// Access the value by reference using a pointer capture.
var c: ?u32 = 3;
if (c) |*value| {
value.* = 2;
}
if (c) |value| {
try expect(value == 2);
} else {
unreachable;
}
}
test "if error union with optional" {
// If expressions test for errors before unwrapping optionals.
// The |optional_value| capture's type is ?u32.
const a: anyerror!?u32 = 0;
if (a) |optional_value| {
try expect(optional_value.? == 0);
} else |err| {
_ = err;
unreachable;
}
const b: anyerror!?u32 = null;
if (b) |optional_value| {
try expect(optional_value == null);
} else |_| {
unreachable;
}
const c: anyerror!?u32 = error.BadValue;
if (c) |optional_value| {
_ = optional_value;
unreachable;
} else |err| {
try expect(err == error.BadValue);
}
// Access the value by reference by using a pointer capture each time.
var d: anyerror!?u32 = 3;
if (d) |*optional_value| {
if (optional_value.*) |*value| {
value.* = 9;
}
} else |_| {
unreachable;
}
if (d) |optional_value| {
try expect(optional_value.? == 9);
} else |_| {
unreachable;
}
}
Shell
$ zig test test_if_optionals.zig
1/2 test_if_optionals.test.if optional...OK
2/2 test_if_optionals.test.if error union with optional...OK
All 2 tests passed.
See also:
Optionals
Errors
defer
Executes an expression unconditionally at scope exit.
test_defer.zig
const std = @import("std");
const expect = std.testing.expect;
const print = std.debug.print;
fn deferExample() !usize {
var a: usize = 1;
{
defer a = 2;
a = 1;
}
try expect(a == 2);
a = 5;
return a;
}
test "defer basics" {
try expect((try deferExample()) == 5);
}
Shell
$ zig test test_defer.zig
1/1 test_defer.test.defer basics...OK
All 1 tests passed.
Defer expressions are evaluated in reverse order.
defer_unwind.zig
const std = @import("std");
const expect = std.testing.expect;
const print = std.debug.print;
test "defer unwinding" {
print("\n", .{});
defer {
print("1 ", .{});
}
defer {
print("2 ", .{});
}
if (false) {
// defers are not run if they are never executed.
defer {
print("3 ", .{});
}
}
}
Shell
$ zig test defer_unwind.zig
1/1 defer_unwind.test.defer unwinding...
2 1 OK
All 1 tests passed.
Inside a defer expression the return statement is not allowed.
test_invalid_defer.zig
fn deferInvalidExample() !void {
defer {
return error.DeferError;
}
return error.DeferError;
}
Shell
$ zig test test_invalid_defer.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_invalid_defer.zig:3:9: error: cannot return from defer expression
return error.DeferError;
^~~~~~~~~~~~~~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_invalid_defer.zig:2:5: note: defer expression here
defer {
^~~~~
See also:
Errors
unreachable
In Debug and ReleaseSafe mode unreachable emits a call to panic with the message reached unreachable code.
In ReleaseFast and ReleaseSmall mode, the optimizer uses the assumption that unreachable code will never be hit to perform optimizations.
Basics
test_unreachable.zig
// unreachable is used to assert that control flow will never reach a
// particular location:
test "basic math" {
const x = 1;
const y = 2;
if (x + y != 3) {
unreachable;
}
}
Shell
$ zig test test_unreachable.zig
1/1 test_unreachable.test.basic math...OK
All 1 tests passed.
In fact, this is how std.debug.assert is implemented:
test_assertion_failure.zig
// This is how std.debug.assert is implemented
fn assert(ok: bool) void {
if (!ok) unreachable; // assertion failure
}
// This test will fail because we hit unreachable.
test "this will fail" {
assert(false);
}
Shell
$ zig test test_assertion_failure.zig
1/1 test_assertion_failure.test.this will fail...thread 3520263 panic: reached unreachable code
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_assertion_failure.zig:3:14: 0x102d036 in assert (test_assertion_failure.zig)
if (!ok) unreachable; // assertion failure
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_assertion_failure.zig:8:11: 0x102d00e in test.this will fail (test_assertion_failure.zig)
assert(false);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x1175dc3 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:64:28: 0x116be67 in main (test_runner.zig)
return mainTerminal();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1164f9d in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x1164873 in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/add3a625f9569b070979afb805f20fb5/test --seed=0xc5d84b99
At Compile-Time
test_comptime_unreachable.zig
const assert = @import("std").debug.assert;
test "type of unreachable" {
comptime {
// The type of unreachable is noreturn.
// However this assertion will still fail to compile because
// unreachable expressions are compile errors.
assert(@TypeOf(unreachable) == noreturn);
}
}
Shell
$ zig test test_comptime_unreachable.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_unreachable.zig:10:16: error: unreachable code
assert(@TypeOf(unreachable) == noreturn);
^~~~~~~~~~~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_unreachable.zig:10:24: note: control flow is diverted here
assert(@TypeOf(unreachable) == noreturn);
^~~~~~~~~~~
See also:
Zig Test
Build Mode
comptime
noreturn
noreturn is the type of:
break
continue
return
unreachable
while (true) {}
When resolving types together, such as if clauses or switch prongs, the noreturn type is compatible with every other type. Consider:
test_noreturn.zig
fn foo(condition: bool, b: u32) void {
const a = if (condition) b else return;
_ = a;
@panic("do something with a");
}
test "noreturn" {
foo(false, 1);
}
Shell
$ zig test test_noreturn.zig
1/1 test_noreturn.test.noreturn...OK
All 1 tests passed.
Another use case for noreturn is the exit function:
test_noreturn_from_exit.zig
const std = @import("std");
const builtin = @import("builtin");
const native_arch = builtin.cpu.arch;
const expect = std.testing.expect;
const WINAPI: std.builtin.CallingConvention = if (native_arch == .x86) .Stdcall else .C;
extern "kernel32" fn ExitProcess(exit_code: c_uint) callconv(WINAPI) noreturn;
test "foo" {
const value = bar() catch ExitProcess(1);
try expect(value == 1234);
}
fn bar() anyerror!u32 {
return 1234;
}
Shell
$ zig test test_noreturn_from_exit.zig -target x86_64-windows --test-no-exec
Functions
test_functions.zig
const std = @import("std");
const builtin = @import("builtin");
const native_arch = builtin.cpu.arch;
const expect = std.testing.expect;
// Functions are declared like this
fn add(a: i8, b: i8) i8 {
if (a == 0) {
return b;
}
return a + b;
}
// The export specifier makes a function externally visible in the generated
// object file, and makes it use the C ABI.
export fn sub(a: i8, b: i8) i8 {
return a - b;
}
// The extern specifier is used to declare a function that will be resolved
// at link time, when linking statically, or at runtime, when linking
// dynamically. The quoted identifier after the extern keyword specifies
// the library that has the function. (e.g. "c" -> libc.so)
// The callconv specifier changes the calling convention of the function.
extern "kernel32" fn ExitProcess(exit_code: u32) callconv(.winapi) noreturn;
extern "c" fn atan2(a: f64, b: f64) f64;
// The @branchHint builtin can be used to tell the optimizer that a function is rarely called ("cold").
fn abort() noreturn {
@branchHint(.cold);
while (true) {}
}
// The naked calling convention makes a function not have any function prologue or epilogue.
// This can be useful when integrating with assembly.
fn _start() callconv(.naked) noreturn {
abort();
}
// The inline calling convention forces a function to be inlined at all call sites.
// If the function cannot be inlined, it is a compile-time error.
inline fn shiftLeftOne(a: u32) u32 {
return a << 1;
}
// The pub specifier allows the function to be visible when importing.
// Another file can use @import and call sub2
pub fn sub2(a: i8, b: i8) i8 {
return a - b;
}
// Function pointers are prefixed with `*const `.
const Call2Op = *const fn (a: i8, b: i8) i8;
fn doOp(fnCall: Call2Op, op1: i8, op2: i8) i8 {
return fnCall(op1, op2);
}
test "function" {
try expect(doOp(add, 5, 6) == 11);
try expect(doOp(sub2, 5, 6) == -1);
}
Shell
$ zig test test_functions.zig
1/1 test_functions.test.function...OK
All 1 tests passed.
There is a difference between a function body and a function pointer. Function bodies are comptime-only types while function Pointers may be runtime-known.
Pass-by-value Parameters
Primitive types such as Integers and Floats passed as parameters are copied, and then the copy is available in the function body. This is called "passing by value". Copying a primitive type is essentially free and typically involves nothing more than setting a register.
Structs, unions, and arrays can sometimes be more efficiently passed as a reference, since a copy could be arbitrarily expensive depending on the size. When these types are passed as parameters, Zig may choose to copy and pass by value, or pass by reference, whichever way Zig decides will be faster. This is made possible, in part, by the fact that parameters are immutable.
test_pass_by_reference_or_value.zig
const Point = struct {
x: i32,
y: i32,
};
fn foo(point: Point) i32 {
// Here, `point` could be a reference, or a copy. The function body
// can ignore the difference and treat it as a value. Be very careful
// taking the address of the parameter - it should be treated as if
// the address will become invalid when the function returns.
return point.x + point.y;
}
const expect = @import("std").testing.expect;
test "pass struct to function" {
try expect(foo(Point{ .x = 1, .y = 2 }) == 3);
}
Shell
$ zig test test_pass_by_reference_or_value.zig
1/1 test_pass_by_reference_or_value.test.pass struct to function...OK
All 1 tests passed.
For extern functions, Zig follows the C ABI for passing structs and unions by value.
Function Parameter Type Inference
Function parameters can be declared with anytype in place of the type. In this case the parameter types will be inferred when the function is called. Use @TypeOf and @typeInfo to get information about the inferred type.
test_fn_type_inference.zig
const expect = @import("std").testing.expect;
fn addFortyTwo(x: anytype) @TypeOf(x) {
return x + 42;
}
test "fn type inference" {
try expect(addFortyTwo(1) == 43);
try expect(@TypeOf(addFortyTwo(1)) == comptime_int);
const y: i64 = 2;
try expect(addFortyTwo(y) == 44);
try expect(@TypeOf(addFortyTwo(y)) == i64);
}
Shell
$ zig test test_fn_type_inference.zig
1/1 test_fn_type_inference.test.fn type inference...OK
All 1 tests passed.
inline fn
Adding the inline keyword to a function definition makes that function become semantically inlined at the callsite. This is not a hint to be possibly observed by optimization passes, but has implications on the types and values involved in the function call.
Unlike normal function calls, arguments at an inline function callsite which are compile-time known are treated as Compile Time Parameters. This can potentially propagate all the way to the return value:
inline_call.zig
test "inline function call" {
if (foo(1200, 34) != 1234) {
@compileError("bad");
}
}
inline fn foo(a: i32, b: i32) i32 {
return a + b;
}
Shell
$ zig test inline_call.zig
1/1 inline_call.test.inline function call...OK
All 1 tests passed.
If inline is removed, the test fails with the compile error instead of passing.
It is generally better to let the compiler decide when to inline a function, except for these scenarios:
To change how many stack frames are in the call stack, for debugging purposes.
To force comptime-ness of the arguments to propagate to the return value of the function, as in the above example.
Real world performance measurements demand it.
Note that inline actually restricts what the compiler is allowed to do. This can harm binary size, compilation speed, and even runtime performance.
Function Reflection
test_fn_reflection.zig
const std = @import("std");
const math = std.math;
const testing = std.testing;
test "fn reflection" {
try testing.expect(@typeInfo(@TypeOf(testing.expect)).@"fn".params[0].type.? == bool);
try testing.expect(@typeInfo(@TypeOf(testing.tmpDir)).@"fn".return_type.? == testing.TmpDir);
try testing.expect(@typeInfo(@TypeOf(math.Log2Int)).@"fn".is_generic);
}
Shell
$ zig test test_fn_reflection.zig
1/1 test_fn_reflection.test.fn reflection...OK
All 1 tests passed.
Errors
Error Set Type
An error set is like an enum. However, each error name across the entire compilation gets assigned an unsigned integer greater than 0. You are allowed to declare the same error name more than once, and if you do, it gets assigned the same integer value.
The error set type defaults to a u16, though if the maximum number of distinct error values is provided via the --error-limit [num] command line parameter an integer type with the minimum number of bits required to represent all of the error values will be used.
You can coerce an error from a subset to a superset:
test_coerce_error_subset_to_superset.zig
const std = @import("std");
const FileOpenError = error{
AccessDenied,
OutOfMemory,
FileNotFound,
};
const AllocationError = error{
OutOfMemory,
};
test "coerce subset to superset" {
const err = foo(AllocationError.OutOfMemory);
try std.testing.expect(err == FileOpenError.OutOfMemory);
}
fn foo(err: AllocationError) FileOpenError {
return err;
}
Shell
$ zig test test_coerce_error_subset_to_superset.zig
1/1 test_coerce_error_subset_to_superset.test.coerce subset to superset...OK
All 1 tests passed.
But you cannot coerce an error from a superset to a subset:
test_coerce_error_superset_to_subset.zig
const FileOpenError = error{
AccessDenied,
OutOfMemory,
FileNotFound,
};
const AllocationError = error{
OutOfMemory,
};
test "coerce superset to subset" {
foo(FileOpenError.OutOfMemory) catch {};
}
fn foo(err: FileOpenError) AllocationError {
return err;
}
Shell
$ zig test test_coerce_error_superset_to_subset.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: error: expected type 'error{OutOfMemory}', found 'error{AccessDenied,OutOfMemory,FileNotFound}'
return err;
^~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: note: 'error.AccessDenied' not a member of destination error set
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:16:12: note: 'error.FileNotFound' not a member of destination error set
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:15:28: note: function return type declared here
fn foo(err: FileOpenError) AllocationError {
^~~~~~~~~~~~~~~
referenced by:
test.coerce superset to subset: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_coerce_error_superset_to_subset.zig:12:8
There is a shortcut for declaring an error set with only 1 value, and then getting that value:
single_value_error_set_shortcut.zig
const err = error.FileNotFound;
This is equivalent to:
single_value_error_set.zig
const err = (error{FileNotFound}).FileNotFound;
This becomes useful when using Inferred Error Sets.
The Global Error Set
anyerror refers to the global error set. This is the error set that contains all errors in the entire compilation unit, i.e. it is the union of all other error sets.
You can coerce any error set to the global one, and you can explicitly cast an error of the global error set to a non-global one. This inserts a language-level assert to make sure the error value is in fact in the destination error set.
The global error set should generally be avoided because it prevents the compiler from knowing what errors are possible at compile-time. Knowing the error set at compile-time is better for generated documentation and helpful error messages, such as forgetting a possible error value in a switch.
Error Union Type
An error set type and normal type can be combined with the ! binary operator to form an error union type. You are likely to use an error union type more often than an error set type by itself.
Here is a function to parse a string into a 64-bit integer:
error_union_parsing_u64.zig
const std = @import("std");
const maxInt = std.math.maxInt;
pub fn parseU64(buf: []const u8, radix: u8) !u64 {
var x: u64 = 0;
for (buf) |c| {
const digit = charToDigit(c);
if (digit >= radix) {
return error.InvalidChar;
}
// x *= radix
var ov = @mulWithOverflow(x, radix);
if (ov[1] != 0) return error.OverFlow;
// x += digit
ov = @addWithOverflow(ov[0], digit);
if (ov[1] != 0) return error.OverFlow;
x = ov[0];
}
return x;
}
fn charToDigit(c: u8) u8 {
return switch (c) {
'0'...'9' => c - '0',
'A'...'Z' => c - 'A' + 10,
'a'...'z' => c - 'a' + 10,
else => maxInt(u8),
};
}
test "parse u64" {
const result = try parseU64("1234", 10);
try std.testing.expect(result == 1234);
}
Shell
$ zig test error_union_parsing_u64.zig
1/1 error_union_parsing_u64.test.parse u64...OK
All 1 tests passed.
Notice the return type is !u64. This means that the function either returns an unsigned 64 bit integer, or an error. We left off the error set to the left of the !, so the error set is inferred.
Within the function definition, you can see some return statements that return an error, and at the bottom a return statement that returns a u64. Both types coerce to anyerror!u64.
What it looks like to use this function varies depending on what you're trying to do. One of the following:
You want to provide a default value if it returned an error.
If it returned an error then you want to return the same error.
You know with complete certainty it will not return an error, so want to unconditionally unwrap it.
You want to take a different action for each possible error.
catch
If you want to provide a default value, you can use the catch binary operator:
catch.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) void {
const number = parseU64(str, 10) catch 13;
_ = number; // ...
}
In this code, number will be equal to the successfully parsed string, or a default value of 13. The type of the right hand side of the binary catch operator must match the unwrapped error union type, or be of type noreturn.
If you want to provide a default value with catch after performing some logic, you can combine catch with named Blocks:
handle_error_with_catch_block.zig.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) void {
const number = parseU64(str, 10) catch blk: {
// do things
break :blk 13;
};
_ = number; // number is now initialized
}
try
Let's say you wanted to return the error if you got one, otherwise continue with the function logic:
catch_err_return.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) !void {
const number = parseU64(str, 10) catch |err| return err;
_ = number; // ...
}
There is a shortcut for this. The try expression:
try.zig
const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) !void {
const number = try parseU64(str, 10);
_ = number; // ...
}
try evaluates an error union expression. If it is an error, it returns from the current function with the same error. Otherwise, the expression results in the unwrapped value.
Maybe you know with complete certainty that an expression will never be an error. In this case you can do this:
const number = parseU64("1234", 10) catch unreachable;
Here we know for sure that "1234" will parse successfully. So we put the unreachable value on the right hand side. unreachable invokes safety-checked Illegal Behavior, so in Debug and ReleaseSafe, triggers a safety panic by default. So, while we're debugging the application, if there was a surprise error here, the application would crash appropriately.
You may want to take a different action for every situation. For that, we combine the if and switch expression:
handle_all_error_scenarios.zig
fn doAThing(str: []u8) void {
if (parseU64(str, 10)) |number| {
doSomethingWithNumber(number);
} else |err| switch (err) {
error.Overflow => {
// handle overflow...
},
// we promise that InvalidChar won't happen (or crash in debug mode if it does)
error.InvalidChar => unreachable,
}
}
Finally, you may want to handle only some errors. For that, you can capture the unhandled errors in the else case, which now contains a narrower error set:
handle_some_error_scenarios.zig
fn doAnotherThing(str: []u8) error{InvalidChar}!void {
if (parseU64(str, 10)) |number| {
doSomethingWithNumber(number);
} else |err| switch (err) {
error.Overflow => {
// handle overflow...
},
else => |leftover_err| return leftover_err,
}
}
You must use the variable capture syntax. If you don't need the variable, you can capture with _ and avoid the switch.
handle_no_error_scenarios.zig
fn doADifferentThing(str: []u8) void {
if (parseU64(str, 10)) |number| {
doSomethingWithNumber(number);
} else |_| {
// do as you'd like
}
}
errdefer
The other component to error handling is defer statements. In addition to an unconditional defer, Zig has errdefer, which evaluates the deferred expression on block exit path if and only if the function returned with an error from the block.
Example:
errdefer_example.zig
fn createFoo(param: i32) !Foo {
const foo = try tryToAllocateFoo();
// now we have allocated foo. we need to free it if the function fails.
// but we want to return it if the function succeeds.
errdefer deallocateFoo(foo);
const tmp_buf = allocateTmpBuffer() orelse return error.OutOfMemory;
// tmp_buf is truly a temporary resource, and we for sure want to clean it up
// before this block leaves scope
defer deallocateTmpBuffer(tmp_buf);
if (param > 1337) return error.InvalidParam;
// here the errdefer will not run since we're returning success from the function.
// but the defer will run!
return foo;
}
The neat thing about this is that you get robust error handling without the verbosity and cognitive overhead of trying to make sure every exit path is covered. The deallocation code is always directly following the allocation code.
The errdefer statement can optionally capture the error:
test_errdefer_capture.zig
const std = @import("std");
fn captureError(captured: *?anyerror) !void {
errdefer |err| {
captured.* = err;
}
return error.GeneralFailure;
}
test "errdefer capture" {
var captured: ?anyerror = null;
if (captureError(&captured)) unreachable else |err| {
try std.testing.expectEqual(error.GeneralFailure, captured.?);
try std.testing.expectEqual(error.GeneralFailure, err);
}
}
Shell
$ zig test test_errdefer_capture.zig
1/1 test_errdefer_capture.test.errdefer capture...OK
All 1 tests passed.
A couple of other tidbits about error handling:
These primitives give enough expressiveness that it's completely practical to have failing to check for an error be a compile error. If you really want to ignore the error, you can add catch unreachable and get the added benefit of crashing in Debug and ReleaseSafe modes if your assumption was wrong.
Since Zig understands error types, it can pre-weight branches in favor of errors not occurring. Just a small optimization benefit that is not available in other languages.
See also:
defer
if
switch
An error union is created with the ! binary operator. You can use compile-time reflection to access the child type of an error union:
test_error_union.zig
const expect = @import("std").testing.expect;
test "error union" {
var foo: anyerror!i32 = undefined;
// Coerce from child type of an error union:
foo = 1234;
// Coerce from an error set:
foo = error.SomeError;
// Use compile-time reflection to access the payload type of an error union:
try comptime expect(@typeInfo(@TypeOf(foo)).error_union.payload == i32);
// Use compile-time reflection to access the error set type of an error union:
try comptime expect(@typeInfo(@TypeOf(foo)).error_union.error_set == anyerror);
}
Shell
$ zig test test_error_union.zig
1/1 test_error_union.test.error union...OK
All 1 tests passed.
Merging Error Sets
Use the || operator to merge two error sets together. The resulting error set contains the errors of both error sets. Doc comments from the left-hand side override doc comments from the right-hand side. In this example, the doc comments for C.PathNotFound is A doc comment.
This is especially useful for functions which return different error sets depending on comptime branches. For example, the Zig standard library uses LinuxFileOpenError || WindowsFileOpenError for the error set of opening files.
test_merging_error_sets.zig
const A = error{
NotDir,
/// A doc comment
PathNotFound,
};
const B = error{
OutOfMemory,
/// B doc comment
PathNotFound,
};
const C = A || B;
fn foo() C!void {
return error.NotDir;
}
test "merge error sets" {
if (foo()) {
@panic("unexpected");
} else |err| switch (err) {
error.OutOfMemory => @panic("unexpected"),
error.PathNotFound => @panic("unexpected"),
error.NotDir => {},
}
}
Shell
$ zig test test_merging_error_sets.zig
1/1 test_merging_error_sets.test.merge error sets...OK
All 1 tests passed.
Inferred Error Sets
Because many functions in Zig return a possible error, Zig supports inferring the error set. To infer the error set for a function, prepend the ! operator to the function’s return type, like !T:
test_inferred_error_sets.zig
// With an inferred error set
pub fn add_inferred(comptime T: type, a: T, b: T) !T {
const ov = @addWithOverflow(a, b);
if (ov[1] != 0) return error.Overflow;
return ov[0];
}
// With an explicit error set
pub fn add_explicit(comptime T: type, a: T, b: T) Error!T {
const ov = @addWithOverflow(a, b);
if (ov[1] != 0) return error.Overflow;
return ov[0];
}
const Error = error{
Overflow,
};
const std = @import("std");
test "inferred error set" {
if (add_inferred(u8, 255, 1)) |_| unreachable else |err| switch (err) {
error.Overflow => {}, // ok
}
}
Shell
$ zig test test_inferred_error_sets.zig
1/1 test_inferred_error_sets.test.inferred error set...OK
All 1 tests passed.
When a function has an inferred error set, that function becomes generic and thus it becomes trickier to do certain things with it, such as obtain a function pointer, or have an error set that is consistent across different build targets. Additionally, inferred error sets are incompatible with recursion.
In these situations, it is recommended to use an explicit error set. You can generally start with an empty error set and let compile errors guide you toward completing the set.
These limitations may be overcome in a future version of Zig.
Error Return Traces
Error Return Traces show all the points in the code that an error was returned to the calling function. This makes it practical to use try everywhere and then still be able to know what happened if an error ends up bubbling all the way out of your application.
error_return_trace.zig
pub fn main() !void {
try foo(12);
}
fn foo(x: i32) !void {
if (x >= 5) {
try bar();
} else {
try bang2();
}
}
fn bar() !void {
if (baz()) {
try quux();
} else |err| switch (err) {
error.FileNotFound => try hello(),
}
}
fn baz() !void {
try bang1();
}
fn quux() !void {
try bang2();
}
fn hello() !void {
try bang2();
}
fn bang1() !void {
return error.FileNotFound;
}
fn bang2() !void {
return error.PermissionDenied;
}
Shell
$ zig build-exe error_return_trace.zig
$ ./error_return_trace
error: PermissionDenied
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:34:5: 0x115384f in bang1 (error_return_trace.zig)
return error.FileNotFound;
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:22:5: 0x1153896 in baz (error_return_trace.zig)
try bang1();
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:38:5: 0x11538cc in bang2 (error_return_trace.zig)
return error.PermissionDenied;
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:30:5: 0x1153973 in hello (error_return_trace.zig)
try bang2();
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:17:31: 0x1153a4b in bar (error_return_trace.zig)
error.FileNotFound => try hello(),
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:7:9: 0x1153b27 in foo (error_return_trace.zig)
try bar();
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/error_return_trace.zig:2:5: 0x1153bec in main (error_return_trace.zig)
try foo(12);
^
Look closely at this example. This is no stack trace.
You can see that the final error bubbled up was PermissionDenied, but the original error that started this whole thing was FileNotFound. In the bar function, the code handles the original error code, and then returns another one, from the switch statement. Error Return Traces make this clear, whereas a stack trace would look like this:
stack_trace.zig
pub fn main() void {
foo(12);
}
fn foo(x: i32) void {
if (x >= 5) {
bar();
} else {
bang2();
}
}
fn bar() void {
if (baz()) {
quux();
} else {
hello();
}
}
fn baz() bool {
return bang1();
}
fn quux() void {
bang2();
}
fn hello() void {
bang2();
}
fn bang1() bool {
return false;
}
fn bang2() void {
@panic("PermissionDenied");
}
Shell
$ zig build-exe stack_trace.zig
$ ./stack_trace
thread 3518529 panic: PermissionDenied
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:38:5: 0x115629d in bang2 (stack_trace.zig)
@panic("PermissionDenied");
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:30:10: 0x1157525 in hello (stack_trace.zig)
bang2();
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:17:14: 0x1156257 in bar (stack_trace.zig)
hello();
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:7:12: 0x1155f13 in foo (stack_trace.zig)
bar();
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/stack_trace.zig:2:8: 0x1154d14 in main (stack_trace.zig)
foo(12);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1153f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115383a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Here, the stack trace does not explain how the control flow in bar got to the hello() call. One would have to open a debugger or further instrument the application in order to find out. The error return trace, on the other hand, shows exactly how the error bubbled up.
This debugging feature makes it easier to iterate quickly on code that robustly handles all error conditions. This means that Zig developers will naturally find themselves writing correct, robust code in order to increase their development pace.
Error Return Traces are enabled by default in Debug and ReleaseSafe builds and disabled by default in ReleaseFast and ReleaseSmall builds.
There are a few ways to activate this error return tracing feature:
Return an error from main
An error makes its way to catch unreachable and you have not overridden the default panic handler
Use errorReturnTrace to access the current return trace. You can use std.debug.dumpStackTrace to print it. This function returns comptime-known null when building without error return tracing support.
Implementation Details
To analyze performance cost, there are two cases:
when no errors are returned
when returning errors
For the case when no errors are returned, the cost is a single memory write operation, only in the first non-failable function in the call graph that calls a failable function, i.e. when a function returning void calls a function returning error. This is to initialize this struct in the stack memory:
stack_trace_struct.zig
pub const StackTrace = struct {
index: usize,
instruction_addresses: [N]usize,
};
Here, N is the maximum function call depth as determined by call graph analysis. Recursion is ignored and counts for 2.
A pointer to StackTrace is passed as a secret parameter to every function that can return an error, but it's always the first parameter, so it can likely sit in a register and stay there.
That's it for the path when no errors occur. It's practically free in terms of performance.
When generating the code for a function that returns an error, just before the return statement (only for the return statements that return errors), Zig generates a call to this function:
zig_return_error_fn.zig
// marked as "no-inline" in LLVM IR
fn __zig_return_error(stack_trace: *StackTrace) void {
stack_trace.instruction_addresses[stack_trace.index] = @returnAddress();
stack_trace.index = (stack_trace.index + 1) % N;
}
The cost is 2 math operations plus some memory reads and writes. The memory accessed is constrained and should remain cached for the duration of the error return bubbling.
As for code size cost, 1 function call before a return statement is no big deal. Even so, I have a plan to make the call to __zig_return_error a tail call, which brings the code size cost down to actually zero. What is a return statement in code without error return tracing can become a jump instruction in code with error return tracing.
Optionals
One area that Zig provides safety without compromising efficiency or readability is with the optional type.
The question mark symbolizes the optional type. You can convert a type to an optional type by putting a question mark in front of it, like this:
optional_integer.zig
// normal integer
const normal_int: i32 = 1234;
// optional integer
const optional_int: ?i32 = 5678;
Now the variable optional_int could be an i32, or null.
Instead of integers, let's talk about pointers. Null references are the source of many runtime exceptions, and even stand accused of being the worst mistake of computer science.
Zig does not have them.
Instead, you can use an optional pointer. This secretly compiles down to a normal pointer, since we know we can use 0 as the null value for the optional type. But the compiler can check your work and make sure you don't assign null to something that can't be null.
Typically the downside of not having null is that it makes the code more verbose to write. But, let's compare some equivalent C code and Zig code.
Task: call malloc, if the result is null, return null.
C code
call_malloc_in_c.c
// malloc prototype included for reference
void *malloc(size_t size);
struct Foo *do_a_thing(void) {
char *ptr = malloc(1234);
if (!ptr) return NULL;
// ...
}
Zig code
call_malloc_from_zig.zig
// malloc prototype included for reference
extern fn malloc(size: usize) ?[*]u8;
fn doAThing() ?*Foo {
const ptr = malloc(1234) orelse return null;
_ = ptr; // ...
}
Here, Zig is at least as convenient, if not more, than C. And, the type of "ptr" is [*]u8 not ?[*]u8. The orelse keyword unwrapped the optional type and therefore ptr is guaranteed to be non-null everywhere it is used in the function.
The other form of checking against NULL you might see looks like this:
checking_null_in_c.c
void do_a_thing(struct Foo *foo) {
// do some stuff
if (foo) {
do_something_with_foo(foo);
}
// do some stuff
}
In Zig you can accomplish the same thing:
checking_null_in_zig.zig
const Foo = struct {};
fn doSomethingWithFoo(foo: *Foo) void {
_ = foo;
}
fn doAThing(optional_foo: ?*Foo) void {
// do some stuff
if (optional_foo) |foo| {
doSomethingWithFoo(foo);
}
// do some stuff
}
Once again, the notable thing here is that inside the if block, foo is no longer an optional pointer, it is a pointer, which cannot be null.
One benefit to this is that functions which take pointers as arguments can be annotated with the "nonnull" attribute - __attribute__((nonnull)) in GCC. The optimizer can sometimes make better decisions knowing that pointer arguments cannot be null.
Optional Type
An optional is created by putting ? in front of a type. You can use compile-time reflection to access the child type of an optional:
test_optional_type.zig
const expect = @import("std").testing.expect;
test "optional type" {
// Declare an optional and coerce from null:
var foo: ?i32 = null;
// Coerce from child type of an optional
foo = 1234;
// Use compile-time reflection to access the child type of the optional:
try comptime expect(@typeInfo(@TypeOf(foo)).optional.child == i32);
}
Shell
$ zig test test_optional_type.zig
1/1 test_optional_type.test.optional type...OK
All 1 tests passed.
null
Just like undefined, null has its own type, and the only way to use it is to cast it to a different type:
null.zig
const optional_value: ?i32 = null;
Optional Pointers
An optional pointer is guaranteed to be the same size as a pointer. The null of the optional is guaranteed to be address 0.
test_optional_pointer.zig
const expect = @import("std").testing.expect;
test "optional pointers" {
// Pointers cannot be null. If you want a null pointer, use the optional
// prefix `?` to make the pointer type optional.
var ptr: ?*i32 = null;
var x: i32 = 1;
ptr = &x;
try expect(ptr.?.* == 1);
// Optional pointers are the same size as normal pointers, because pointer
// value 0 is used as the null value.
try expect(@sizeOf(?*i32) == @sizeOf(*i32));
}
Shell
$ zig test test_optional_pointer.zig
1/1 test_optional_pointer.test.optional pointers...OK
All 1 tests passed.
See also:
while with Optionals
if with Optionals
Casting
A type cast converts a value of one type to another. Zig has Type Coercion for conversions that are known to be completely safe and unambiguous, and Explicit Casts for conversions that one would not want to happen on accident. There is also a third kind of type conversion called Peer Type Resolution for the case when a result type must be decided given multiple operand types.
Type Coercion
Type coercion occurs when one type is expected, but different type is provided:
test_type_coercion.zig
test "type coercion - variable declaration" {
const a: u8 = 1;
const b: u16 = a;
_ = b;
}
test "type coercion - function call" {
const a: u8 = 1;
foo(a);
}
fn foo(b: u16) void {
_ = b;
}
test "type coercion - @as builtin" {
const a: u8 = 1;
const b = @as(u16, a);
_ = b;
}
Shell
$ zig test test_type_coercion.zig
1/3 test_type_coercion.test.type coercion - variable declaration...OK
2/3 test_type_coercion.test.type coercion - function call...OK
3/3 test_type_coercion.test.type coercion - @as builtin...OK
All 3 tests passed.
Type coercions are only allowed when it is completely unambiguous how to get from one type to another, and the transformation is guaranteed to be safe. There is one exception, which is C Pointers.
Type Coercion: Stricter Qualification
Values which have the same representation at runtime can be cast to increase the strictness of the qualifiers, no matter how nested the qualifiers are:
const - non-const to const is allowed
volatile - non-volatile to volatile is allowed
align - bigger to smaller alignment is allowed
error sets to supersets is allowed
These casts are no-ops at runtime since the value representation does not change.
test_no_op_casts.zig
test "type coercion - const qualification" {
var a: i32 = 1;
const b: *i32 = &a;
foo(b);
}
fn foo(_: *const i32) void {}
Shell
$ zig test test_no_op_casts.zig
1/1 test_no_op_casts.test.type coercion - const qualification...OK
All 1 tests passed.
In addition, pointers coerce to const optional pointers:
test_pointer_coerce_const_optional.zig
const std = @import("std");
const expect = std.testing.expect;
const mem = std.mem;
test "cast *[1][*:0]const u8 to []const ?[*:0]const u8" {
const window_name = [1][*:0]const u8{"window name"};
const x: []const ?[*:0]const u8 = &window_name;
try expect(mem.eql(u8, mem.span(x[0].?), "window name"));
}
Shell
$ zig test test_pointer_coerce_const_optional.zig
1/1 test_pointer_coerce_const_optional.test.cast *[1][*:0]const u8 to []const ?[*:0]const u8...OK
All 1 tests passed.
Type Coercion: Integer and Float Widening
Integers coerce to integer types which can represent every value of the old type, and likewise Floats coerce to float types which can represent every value of the old type.
test_integer_widening.zig
const std = @import("std");
const builtin = @import("builtin");
const expect = std.testing.expect;
const mem = std.mem;
test "integer widening" {
const a: u8 = 250;
const b: u16 = a;
const c: u32 = b;
const d: u64 = c;
const e: u64 = d;
const f: u128 = e;
try expect(f == a);
}
test "implicit unsigned integer to signed integer" {
const a: u8 = 250;
const b: i16 = a;
try expect(b == 250);
}
test "float widening" {
const a: f16 = 12.34;
const b: f32 = a;
const c: f64 = b;
const d: f128 = c;
try expect(d == a);
}
Shell
$ zig test test_integer_widening.zig
1/3 test_integer_widening.test.integer widening...OK
2/3 test_integer_widening.test.implicit unsigned integer to signed integer...OK
3/3 test_integer_widening.test.float widening...OK
All 3 tests passed.
Type Coercion: Float to Int
A compiler error is appropriate because this ambiguous expression leaves the compiler two choices about the coercion.
Cast 54.0 to comptime_int resulting in @as(comptime_int, 10), which is casted to @as(f32, 10)
Cast 5 to comptime_float resulting in @as(comptime_float, 10.8), which is casted to @as(f32, 10.8)
test_ambiguous_coercion.zig
// Compile time coercion of float to int
test "implicit cast to comptime_int" {
const f: f32 = 54.0 / 5;
_ = f;
}
Shell
$ zig test test_ambiguous_coercion.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_ambiguous_coercion.zig:3:25: error: ambiguous coercion of division operands 'comptime_float' and 'comptime_int'; non-zero remainder '4'
const f: f32 = 54.0 / 5;
~~~~~^~~
Type Coercion: Slices, Arrays and Pointers
test_coerce_slices_arrays_and_pointers.zig
const std = @import("std");
const expect = std.testing.expect;
// You can assign constant pointers to arrays to a slice with
// const modifier on the element type. Useful in particular for
// String literals.
test "*const [N]T to []const T" {
const x1: []const u8 = "hello";
const x2: []const u8 = &[5]u8{ 'h', 'e', 'l', 'l', 111 };
try expect(std.mem.eql(u8, x1, x2));
const y: []const f32 = &[2]f32{ 1.2, 3.4 };
try expect(y[0] == 1.2);
}
// Likewise, it works when the destination type is an error union.
test "*const [N]T to E![]const T" {
const x1: anyerror![]const u8 = "hello";
const x2: anyerror![]const u8 = &[5]u8{ 'h', 'e', 'l', 'l', 111 };
try expect(std.mem.eql(u8, try x1, try x2));
const y: anyerror![]const f32 = &[2]f32{ 1.2, 3.4 };
try expect((try y)[0] == 1.2);
}
// Likewise, it works when the destination type is an optional.
test "*const [N]T to ?[]const T" {
const x1: ?[]const u8 = "hello";
const x2: ?[]const u8 = &[5]u8{ 'h', 'e', 'l', 'l', 111 };
try expect(std.mem.eql(u8, x1.?, x2.?));
const y: ?[]const f32 = &[2]f32{ 1.2, 3.4 };
try expect(y.?[0] == 1.2);
}
// In this cast, the array length becomes the slice length.
test "*[N]T to []T" {
var buf: [5]u8 = "hello".*;
const x: []u8 = &buf;
try expect(std.mem.eql(u8, x, "hello"));
const buf2 = [2]f32{ 1.2, 3.4 };
const x2: []const f32 = &buf2;
try expect(std.mem.eql(f32, x2, &[2]f32{ 1.2, 3.4 }));
}
// Single-item pointers to arrays can be coerced to many-item pointers.
test "*[N]T to [*]T" {
var buf: [5]u8 = "hello".*;
const x: [*]u8 = &buf;
try expect(x[4] == 'o');
// x[5] would be an uncaught out of bounds pointer dereference!
}
// Likewise, it works when the destination type is an optional.
test "*[N]T to ?[*]T" {
var buf: [5]u8 = "hello".*;
const x: ?[*]u8 = &buf;
try expect(x.?[4] == 'o');
}
// Single-item pointers can be cast to len-1 single-item arrays.
test "*T to *[1]T" {
var x: i32 = 1234;
const y: *[1]i32 = &x;
const z: [*]i32 = y;
try expect(z[0] == 1234);
}
Shell
$ zig test test_coerce_slices_arrays_and_pointers.zig
1/7 test_coerce_slices_arrays_and_pointers.test.*const [N]T to []const T...OK
2/7 test_coerce_slices_arrays_and_pointers.test.*const [N]T to E![]const T...OK
3/7 test_coerce_slices_arrays_and_pointers.test.*const [N]T to ?[]const T...OK
4/7 test_coerce_slices_arrays_and_pointers.test.*[N]T to []T...OK
5/7 test_coerce_slices_arrays_and_pointers.test.*[N]T to [*]T...OK
6/7 test_coerce_slices_arrays_and_pointers.test.*[N]T to ?[*]T...OK
7/7 test_coerce_slices_arrays_and_pointers.test.*T to *[1]T...OK
All 7 tests passed.
See also:
C Pointers
Type Coercion: Optionals
The payload type of Optionals, as well as null, coerce to the optional type.
test_coerce_optionals.zig
const std = @import("std");
const expect = std.testing.expect;
test "coerce to optionals" {
const x: ?i32 = 1234;
const y: ?i32 = null;
try expect(x.? == 1234);
try expect(y == null);
}
Shell
$ zig test test_coerce_optionals.zig
1/1 test_coerce_optionals.test.coerce to optionals...OK
All 1 tests passed.
Optionals work nested inside the Error Union Type, too:
test_coerce_optional_wrapped_error_union.zig
const std = @import("std");
const expect = std.testing.expect;
test "coerce to optionals wrapped in error union" {
const x: anyerror!?i32 = 1234;
const y: anyerror!?i32 = null;
try expect((try x).? == 1234);
try expect((try y) == null);
}
Shell
$ zig test test_coerce_optional_wrapped_error_union.zig
1/1 test_coerce_optional_wrapped_error_union.test.coerce to optionals wrapped in error union...OK
All 1 tests passed.
Type Coercion: Error Unions
The payload type of an Error Union Type as well as the Error Set Type coerce to the error union type:
test_coerce_to_error_union.zig
const std = @import("std");
const expect = std.testing.expect;
test "coercion to error unions" {
const x: anyerror!i32 = 1234;
const y: anyerror!i32 = error.Failure;
try expect((try x) == 1234);
try std.testing.expectError(error.Failure, y);
}
Shell
$ zig test test_coerce_to_error_union.zig
1/1 test_coerce_to_error_union.test.coercion to error unions...OK
All 1 tests passed.
Type Coercion: Compile-Time Known Numbers
When a number is comptime-known to be representable in the destination type, it may be coerced:
test_coerce_large_to_small.zig
const std = @import("std");
const expect = std.testing.expect;
test "coercing large integer type to smaller one when value is comptime-known to fit" {
const x: u64 = 255;
const y: u8 = x;
try expect(y == 255);
}
Shell
$ zig test test_coerce_large_to_small.zig
1/1 test_coerce_large_to_small.test.coercing large integer type to smaller one when value is comptime-known to fit...OK
All 1 tests passed.
Type Coercion: Unions and Enums
Tagged unions can be coerced to enums, and enums can be coerced to tagged unions when they are comptime-known to be a field of the union that has only one possible value, such as void:
test_coerce_unions_enums.zig
const std = @import("std");
const expect = std.testing.expect;
const E = enum {
one,
two,
three,
};
const U = union(E) {
one: i32,
two: f32,
three,
};
const U2 = union(enum) {
a: void,
b: f32,
fn tag(self: U2) usize {
switch (self) {
.a => return 1,
.b => return 2,
}
}
};
test "coercion between unions and enums" {
const u = U{ .two = 12.34 };
const e: E = u; // coerce union to enum
try expect(e == E.two);
const three = E.three;
const u_2: U = three; // coerce enum to union
try expect(u_2 == E.three);
const u_3: U = .three; // coerce enum literal to union
try expect(u_3 == E.three);
const u_4: U2 = .a; // coerce enum literal to union with inferred enum tag type.
try expect(u_4.tag() == 1);
// The following example is invalid.
// error: coercion from enum '@TypeOf(.enum_literal)' to union 'test_coerce_unions_enum.U2' must initialize 'f32' field 'b'
//var u_5: U2 = .b;
//try expect(u_5.tag() == 2);
}
Shell
$ zig test test_coerce_unions_enums.zig
1/1 test_coerce_unions_enums.test.coercion between unions and enums...OK
All 1 tests passed.
See also:
union
enum
Type Coercion: undefined
undefined can be coerced to any type.
Type Coercion: Tuples to Arrays
Tuples can be coerced to arrays, if all of the fields have the same type.
test_coerce_tuples_arrays.zig
const std = @import("std");
const expect = std.testing.expect;
const Tuple = struct { u8, u8 };
test "coercion from homogeneous tuple to array" {
const tuple: Tuple = .{ 5, 6 };
const array: [2]u8 = tuple;
_ = array;
}
Shell
$ zig test test_coerce_tuples_arrays.zig
1/1 test_coerce_tuples_arrays.test.coercion from homogeneous tuple to array...OK
All 1 tests passed.
Explicit Casts
Explicit casts are performed via Builtin Functions. Some explicit casts are safe; some are not. Some explicit casts perform language-level assertions; some do not. Some explicit casts are no-ops at runtime; some are not.
@bitCast - change type but maintain bit representation
@alignCast - make a pointer have more alignment
@enumFromInt - obtain an enum value based on its integer tag value
@errorFromInt - obtain an error code based on its integer value
@errorCast - convert to a smaller error set
@floatCast - convert a larger float to a smaller float
@floatFromInt - convert an integer to a float value
@intCast - convert between integer types
@intFromBool - convert true to 1 and false to 0
@intFromEnum - obtain the integer tag value of an enum or tagged union
@intFromError - obtain the integer value of an error code
@intFromFloat - obtain the integer part of a float value
@intFromPtr - obtain the address of a pointer
@ptrFromInt - convert an address to a pointer
@ptrCast - convert between pointer types
@truncate - convert between integer types, chopping off bits
Peer Type Resolution
Peer Type Resolution occurs in these places:
switch expressions
if expressions
while expressions
for expressions
Multiple break statements in a block
Some binary operations
This kind of type resolution chooses a type that all peer types can coerce into. Here are some examples:
test_peer_type_resolution.zig
const std = @import("std");
const expect = std.testing.expect;
const mem = std.mem;
test "peer resolve int widening" {
const a: i8 = 12;
const b: i16 = 34;
const c = a + b;
try expect(c == 46);
try expect(@TypeOf(c) == i16);
}
test "peer resolve arrays of different size to const slice" {
try expect(mem.eql(u8, boolToStr(true), "true"));
try expect(mem.eql(u8, boolToStr(false), "false"));
try comptime expect(mem.eql(u8, boolToStr(true), "true"));
try comptime expect(mem.eql(u8, boolToStr(false), "false"));
}
fn boolToStr(b: bool) []const u8 {
return if (b) "true" else "false";
}
test "peer resolve array and const slice" {
try testPeerResolveArrayConstSlice(true);
try comptime testPeerResolveArrayConstSlice(true);
}
fn testPeerResolveArrayConstSlice(b: bool) !void {
const value1 = if (b) "aoeu" else @as([]const u8, "zz");
const value2 = if (b) @as([]const u8, "zz") else "aoeu";
try expect(mem.eql(u8, value1, "aoeu"));
try expect(mem.eql(u8, value2, "zz"));
}
test "peer type resolution: ?T and T" {
try expect(peerTypeTAndOptionalT(true, false).? == 0);
try expect(peerTypeTAndOptionalT(false, false).? == 3);
comptime {
try expect(peerTypeTAndOptionalT(true, false).? == 0);
try expect(peerTypeTAndOptionalT(false, false).? == 3);
}
}
fn peerTypeTAndOptionalT(c: bool, b: bool) ?usize {
if (c) {
return if (b) null else @as(usize, 0);
}
return @as(usize, 3);
}
test "peer type resolution: *[0]u8 and []const u8" {
try expect(peerTypeEmptyArrayAndSlice(true, "hi").len == 0);
try expect(peerTypeEmptyArrayAndSlice(false, "hi").len == 1);
comptime {
try expect(peerTypeEmptyArrayAndSlice(true, "hi").len == 0);
try expect(peerTypeEmptyArrayAndSlice(false, "hi").len == 1);
}
}
fn peerTypeEmptyArrayAndSlice(a: bool, slice: []const u8) []const u8 {
if (a) {
return &[_]u8{};
}
return slice[0..1];
}
test "peer type resolution: *[0]u8, []const u8, and anyerror![]u8" {
{
var data = "hi".*;
const slice = data[0..];
try expect((try peerTypeEmptyArrayAndSliceAndError(true, slice)).len == 0);
try expect((try peerTypeEmptyArrayAndSliceAndError(false, slice)).len == 1);
}
comptime {
var data = "hi".*;
const slice = data[0..];
try expect((try peerTypeEmptyArrayAndSliceAndError(true, slice)).len == 0);
try expect((try peerTypeEmptyArrayAndSliceAndError(false, slice)).len == 1);
}
}
fn peerTypeEmptyArrayAndSliceAndError(a: bool, slice: []u8) anyerror![]u8 {
if (a) {
return &[_]u8{};
}
return slice[0..1];
}
test "peer type resolution: *const T and ?*T" {
const a: *const usize = @ptrFromInt(0x123456780);
const b: ?*usize = @ptrFromInt(0x123456780);
try expect(a == b);
try expect(b == a);
}
test "peer type resolution: error union switch" {
// The non-error and error cases are only peers if the error case is just a switch expression;
// the pattern `if (x) {...} else |err| blk: { switch (err) {...} }` does not consider the
// non-error and error case to be peers.
var a: error{ A, B, C }!u32 = 0;
_ = &a;
const b = if (a) |x|
x + 3
else |err| switch (err) {
error.A => 0,
error.B => 1,
error.C => null,
};
try expect(@TypeOf(b) == ?u32);
// The non-error and error cases are only peers if the error case is just a switch expression;
// the pattern `x catch |err| blk: { switch (err) {...} }` does not consider the unwrapped `x`
// and error case to be peers.
const c = a catch |err| switch (err) {
error.A => 0,
error.B => 1,
error.C => null,
};
try expect(@TypeOf(c) == ?u32);
}
Shell
$ zig test test_peer_type_resolution.zig
1/8 test_peer_type_resolution.test.peer resolve int widening...OK
2/8 test_peer_type_resolution.test.peer resolve arrays of different size to const slice...OK
3/8 test_peer_type_resolution.test.peer resolve array and const slice...OK
4/8 test_peer_type_resolution.test.peer type resolution: ?T and T...OK
5/8 test_peer_type_resolution.test.peer type resolution: *[0]u8 and []const u8...OK
6/8 test_peer_type_resolution.test.peer type resolution: *[0]u8, []const u8, and anyerror![]u8...OK
7/8 test_peer_type_resolution.test.peer type resolution: *const T and ?*T...OK
8/8 test_peer_type_resolution.test.peer type resolution: error union switch...OK
All 8 tests passed.
Zero Bit Types
For some types, @sizeOf is 0:
void
The Integers u0 and i0.
Arrays and Vectors with len 0, or with an element type that is a zero bit type.
An enum with only 1 tag.
A struct with all fields being zero bit types.
A union with only 1 field which is a zero bit type.
These types can only ever have one possible value, and thus require 0 bits to represent. Code that makes use of these types is not included in the final generated code:
zero_bit_types.zig
export fn entry() void {
var x: void = {};
var y: void = {};
x = y;
y = x;
}
When this turns into machine code, there is no code generated in the body of entry, even in Debug mode. For example, on x86_64:
0000000000000010 :
10: 55 push %rbp
11: 48 89 e5 mov %rsp,%rbp
14: 5d pop %rbp
15: c3 retq
These assembly instructions do not have any code associated with the void values - they only perform the function call prologue and epilogue.
void
void can be useful for instantiating generic types. For example, given a Map(Key, Value), one can pass void for the Value type to make it into a Set:
test_void_in_hashmap.zig
const std = @import("std");
const expect = std.testing.expect;
test "turn HashMap into a set with void" {
var map = std.AutoHashMap(i32, void).init(std.testing.allocator);
defer map.deinit();
try map.put(1, {});
try map.put(2, {});
try expect(map.contains(2));
try expect(!map.contains(3));
_ = map.remove(2);
try expect(!map.contains(2));
}
Shell
$ zig test test_void_in_hashmap.zig
1/1 test_void_in_hashmap.test.turn HashMap into a set with void...OK
All 1 tests passed.
Note that this is different from using a dummy value for the hash map value. By using void as the type of the value, the hash map entry type has no value field, and thus the hash map takes up less space. Further, all the code that deals with storing and loading the value is deleted, as seen above.
void is distinct from anyopaque. void has a known size of 0 bytes, and anyopaque has an unknown, but non-zero, size.
Expressions of type void are the only ones whose value can be ignored. For example, ignoring a non-void expression is a compile error:
test_expression_ignored.zig
test "ignoring expression value" {
foo();
}
fn foo() i32 {
return 1234;
}
Shell
$ zig test test_expression_ignored.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_expression_ignored.zig:2:8: error: value of type 'i32' ignored
foo();
~~~^~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_expression_ignored.zig:2:8: note: all non-void values must be used
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_expression_ignored.zig:2:8: note: to discard the value, assign it to '_'
However, if the expression has type void, there will be no error. Expression results can be explicitly ignored by assigning them to _.
test_void_ignored.zig
test "void is ignored" {
returnsVoid();
}
test "explicitly ignoring expression value" {
_ = foo();
}
fn returnsVoid() void {}
fn foo() i32 {
return 1234;
}
Shell
$ zig test test_void_ignored.zig
1/2 test_void_ignored.test.void is ignored...OK
2/2 test_void_ignored.test.explicitly ignoring expression value...OK
All 2 tests passed.
Result Location Semantics
During compilation, every Zig expression and sub-expression is assigned optional result location information. This information dictates what type the expression should have (its result type), and where the resulting value should be placed in memory (its result location). The information is optional in the sense that not every expression has this information: assignment to _, for instance, does not provide any information about the type of an expression, nor does it provide a concrete memory location to place it in.
As a motivating example, consider the statement const x: u32 = 42;. The type annotation here provides a result type of u32 to the initialization expression 42, instructing the compiler to coerce this integer (initially of type comptime_int) to this type. We will see more examples shortly.
This is not an implementation detail: the logic outlined above is codified into the Zig language specification, and is the primary mechanism of type inference in the language. This system is collectively referred to as "Result Location Semantics".
Result Types
Result types are propagated recursively through expressions where possible. For instance, if the expression &e has result type *u32, then e is given a result type of u32, allowing the language to perform this coercion before taking a reference.
The result type mechanism is utilized by casting builtins such as @intCast. Rather than taking as an argument the type to cast to, these builtins use their result type to determine this information. The result type is often known from context; where it is not, the @as builtin can be used to explicitly provide a result type.
We can break down the result types for each component of a simple expression as follows:
result_type_propagation.zig
const expectEqual = @import("std").testing.expectEqual;
test "result type propagates through struct initializer" {
const S = struct { x: u32 };
const val: u64 = 123;
const s: S = .{ .x = @intCast(val) };
// .{ .x = @intCast(val) } has result type `S` due to the type annotation
// @intCast(val) has result type `u32` due to the type of the field `S.x`
// val has no result type, as it is permitted to be any integer type
try expectEqual(@as(u32, 123), s.x);
}
Shell
$ zig test result_type_propagation.zig
1/1 result_type_propagation.test.result type propagates through struct initializer...OK
All 1 tests passed.
This result type information is useful for the aforementioned cast builtins, as well as to avoid the construction of pre-coercion values, and to avoid the need for explicit type coercions in some cases. The following table details how some common expressions propagate result types, where x and y are arbitrary sub-expressions.
Expression Parent Result Type Sub-expression Result Type
const val: T = x - x is a T
var val: T = x - x is a T
val = x - x is a @TypeOf(val)
@as(T, x) - x is a T
&x *T x is a T
&x []T x is some array of T
f(x) - x has the type of the first parameter of f
.{x} T x is a @FieldType(T, "0")
.{ .a = x } T x is a @FieldType(T, "a")
T{x} - x is a @FieldType(T, "0")
T{ .a = x } - x is a @FieldType(T, "a")
@Type(x) - x is a std.builtin.Type
@typeInfo(x) - x is a type
x << y - y is a std.math.Log2IntCeil(@TypeOf(x))
Result Locations
In addition to result type information, every expression may be optionally assigned a result location: a pointer to which the value must be directly written. This system can be used to prevent intermediate copies when initializing data structures, which can be important for types which must have a fixed memory address ("pinned" types).
When compiling the simple assignment expression x = e, many languages would create the temporary value e on the stack, and then assign it to x, potentially performing a type coercion in the process. Zig approaches this differently. The expression e is given a result type matching the type of x, and a result location of &x. For many syntactic forms of e, this has no practical impact. However, it can have important semantic effects when working with more complex syntax forms.
For instance, if the expression .{ .a = x, .b = y } has a result location of ptr, then x is given a result location of &ptr.a, and y a result location of &ptr.b. Without this system, this expression would construct a temporary struct value entirely on the stack, and only then copy it to the destination address. In essence, Zig desugars the assignment foo = .{ .a = x, .b = y } to the two statements foo.a = x; foo.b = y;.
This can sometimes be important when assigning an aggregate value where the initialization expression depends on the previous value of the aggregate. The easiest way to demonstrate this is by attempting to swap fields of a struct or array - the following logic looks sound, but in fact is not:
result_location_interfering_with_swap.zig
const expect = @import("std").testing.expect;
test "attempt to swap array elements with array initializer" {
var arr: [2]u32 = .{ 1, 2 };
arr = .{ arr[1], arr[0] };
// The previous line is equivalent to the following two lines:
// arr[0] = arr[1];
// arr[1] = arr[0];
// So this fails!
try expect(arr[0] == 2); // succeeds
try expect(arr[1] == 1); // fails
}
Shell
$ zig test result_location_interfering_with_swap.zig
1/1 result_location_interfering_with_swap.test.attempt to swap array elements with array initializer...FAIL (TestUnexpectedResult)
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/testing.zig:586:14: 0x1032019 in expect (std.zig)
if (!ok) return error.TestUnexpectedResult;
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/result_location_interfering_with_swap.zig:10:5: 0x103214c in test.attempt to swap array elements with array initializer (result_location_interfering_with_swap.zig)
try expect(arr[1] == 1); // fails
^
0 passed; 0 skipped; 1 failed.
error: the following test command failed with exit code 1:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/a73bf3b545ef0014e2bacb229b14c99b/test --seed=0x9b3eb00a
The following table details how some common expressions propagate result locations, where x and y are arbitrary sub-expressions. Note that some expressions cannot provide meaningful result locations to sub-expressions, even if they themselves have a result location.
Expression Result Location Sub-expression Result Locations
const val: T = x - x has result location &val
var val: T = x - x has result location &val
val = x - x has result location &val
@as(T, x) ptr x has no result location
&x ptr x has no result location
f(x) ptr x has no result location
.{x} ptr x has result location &ptr[0]
.{ .a = x } ptr x has result location &ptr.a
T{x} ptr x has no result location (typed initializers do not propagate result locations)
T{ .a = x } ptr x has no result location (typed initializers do not propagate result locations)
@Type(x) ptr x has no result location
@typeInfo(x) ptr x has no result location
x << y ptr x and y do not have result locations
usingnamespace
usingnamespace is a declaration that mixes all the public declarations of the operand, which must be a struct, union, enum, or opaque, into the namespace:
test_usingnamespace.zig
test "using std namespace" {
const S = struct {
usingnamespace @import("std");
};
try S.testing.expect(true);
}
Shell
$ zig test test_usingnamespace.zig
1/1 test_usingnamespace.test.using std namespace...OK
All 1 tests passed.
usingnamespace has an important use case when organizing the public API of a file or package. For example, one might have c.zig with all of the C imports:
c.zig
pub usingnamespace @cImport({
@cInclude("epoxy/gl.h");
@cInclude("GLFW/glfw3.h");
@cDefine("STBI_ONLY_PNG", "");
@cDefine("STBI_NO_STDIO", "");
@cInclude("stb_image.h");
});
The above example demonstrates using pub to qualify the usingnamespace additionally makes the imported declarations pub. This can be used to forward declarations, giving precise control over what declarations a given file exposes.
comptime
Zig places importance on the concept of whether an expression is known at compile-time. There are a few different places this concept is used, and these building blocks are used to keep the language small, readable, and powerful.
Introducing the Compile-Time Concept
Compile-Time Parameters
Compile-time parameters is how Zig implements generics. It is compile-time duck typing.
compile-time_duck_typing.zig
fn max(comptime T: type, a: T, b: T) T {
return if (a > b) a else b;
}
fn gimmeTheBiggerFloat(a: f32, b: f32) f32 {
return max(f32, a, b);
}
fn gimmeTheBiggerInteger(a: u64, b: u64) u64 {
return max(u64, a, b);
}
In Zig, types are first-class citizens. They can be assigned to variables, passed as parameters to functions, and returned from functions. However, they can only be used in expressions which are known at compile-time, which is why the parameter T in the above snippet must be marked with comptime.
A comptime parameter means that:
At the callsite, the value must be known at compile-time, or it is a compile error.
In the function definition, the value is known at compile-time.
For example, if we were to introduce another function to the above snippet:
test_unresolved_comptime_value.zig
fn max(comptime T: type, a: T, b: T) T {
return if (a > b) a else b;
}
test "try to pass a runtime type" {
foo(false);
}
fn foo(condition: bool) void {
const result = max(if (condition) f32 else u64, 1234, 5678);
_ = result;
}
Shell
$ zig test test_unresolved_comptime_value.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unresolved_comptime_value.zig:8:28: error: unable to resolve comptime value
const result = max(if (condition) f32 else u64, 1234, 5678);
^~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unresolved_comptime_value.zig:8:24: note: argument to comptime parameter must be comptime-known
const result = max(if (condition) f32 else u64, 1234, 5678);
^~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unresolved_comptime_value.zig:1:8: note: parameter declared comptime here
fn max(comptime T: type, a: T, b: T) T {
^~~~~~~~
referenced by:
test.try to pass a runtime type: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_unresolved_comptime_value.zig:5:8
This is an error because the programmer attempted to pass a value only known at run-time to a function which expects a value known at compile-time.
Another way to get an error is if we pass a type that violates the type checker when the function is analyzed. This is what it means to have compile-time duck typing.
For example:
test_comptime_mismatched_type.zig
fn max(comptime T: type, a: T, b: T) T {
return if (a > b) a else b;
}
test "try to compare bools" {
_ = max(bool, true, false);
}
Shell
$ zig test test_comptime_mismatched_type.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_mismatched_type.zig:2:18: error: operator > not allowed for type 'bool'
return if (a > b) a else b;
~~^~~
referenced by:
test.try to compare bools: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_mismatched_type.zig:5:12
On the flip side, inside the function definition with the comptime parameter, the value is known at compile-time. This means that we actually could make this work for the bool type if we wanted to:
test_comptime_max_with_bool.zig
fn max(comptime T: type, a: T, b: T) T {
if (T == bool) {
return a or b;
} else if (a > b) {
return a;
} else {
return b;
}
}
test "try to compare bools" {
try @import("std").testing.expect(max(bool, false, true) == true);
}
Shell
$ zig test test_comptime_max_with_bool.zig
1/1 test_comptime_max_with_bool.test.try to compare bools...OK
All 1 tests passed.
This works because Zig implicitly inlines if expressions when the condition is known at compile-time, and the compiler guarantees that it will skip analysis of the branch not taken.
This means that the actual function generated for max in this situation looks like this:
compiler_generated_function.zig
fn max(a: bool, b: bool) bool {
{
return a or b;
}
}
All the code that dealt with compile-time known values is eliminated and we are left with only the necessary run-time code to accomplish the task.
This works the same way for switch expressions - they are implicitly inlined when the target expression is compile-time known.
Compile-Time Variables
In Zig, the programmer can label variables as comptime. This guarantees to the compiler that every load and store of the variable is performed at compile-time. Any violation of this results in a compile error.
This combined with the fact that we can inline loops allows us to write a function which is partially evaluated at compile-time and partially at run-time.
For example:
test_comptime_evaluation.zig
const expect = @import("std").testing.expect;
const CmdFn = struct {
name: []const u8,
func: fn (i32) i32,
};
const cmd_fns = [_]CmdFn{
CmdFn{ .name = "one", .func = one },
CmdFn{ .name = "two", .func = two },
CmdFn{ .name = "three", .func = three },
};
fn one(value: i32) i32 {
return value + 1;
}
fn two(value: i32) i32 {
return value + 2;
}
fn three(value: i32) i32 {
return value + 3;
}
fn performFn(comptime prefix_char: u8, start_value: i32) i32 {
var result: i32 = start_value;
comptime var i = 0;
inline while (i < cmd_fns.len) : (i += 1) {
if (cmd_fns[i].name[0] == prefix_char) {
result = cmd_fns[i].func(result);
}
}
return result;
}
test "perform fn" {
try expect(performFn('t', 1) == 6);
try expect(performFn('o', 0) == 1);
try expect(performFn('w', 99) == 99);
}
Shell
$ zig test test_comptime_evaluation.zig
1/1 test_comptime_evaluation.test.perform fn...OK
All 1 tests passed.
This example is a bit contrived, because the compile-time evaluation component is unnecessary; this code would work fine if it was all done at run-time. But it does end up generating different code. In this example, the function performFn is generated three different times, for the different values of prefix_char provided:
performFn_1
// From the line:
// expect(performFn('t', 1) == 6);
fn performFn(start_value: i32) i32 {
var result: i32 = start_value;
result = two(result);
result = three(result);
return result;
}
performFn_2
// From the line:
// expect(performFn('o', 0) == 1);
fn performFn(start_value: i32) i32 {
var result: i32 = start_value;
result = one(result);
return result;
}
performFn_3
// From the line:
// expect(performFn('w', 99) == 99);
fn performFn(start_value: i32) i32 {
var result: i32 = start_value;
_ = &result;
return result;
}
Note that this happens even in a debug build. This is not a way to write more optimized code, but it is a way to make sure that what should happen at compile-time, does happen at compile-time. This catches more errors and allows expressiveness that in other languages requires using macros, generated code, or a preprocessor to accomplish.
Compile-Time Expressions
In Zig, it matters whether a given expression is known at compile-time or run-time. A programmer can use a comptime expression to guarantee that the expression will be evaluated at compile-time. If this cannot be accomplished, the compiler will emit an error. For example:
test_comptime_call_extern_function.zig
extern fn exit() noreturn;
test "foo" {
comptime {
exit();
}
}
Shell
$ zig test test_comptime_call_extern_function.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_call_extern_function.zig:5:13: error: comptime call of extern function
exit();
~~~~^~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_call_extern_function.zig:4:5: note: 'comptime' keyword forces comptime evaluation
comptime {
^~~~~~~~
It doesn't make sense that a program could call exit() (or any other external function) at compile-time, so this is a compile error. However, a comptime expression does much more than sometimes cause a compile error.
Within a comptime expression:
All variables are comptime variables.
All if, while, for, and switch expressions are evaluated at compile-time, or emit a compile error if this is not possible.
All return and try expressions are invalid (unless the function itself is called at compile-time).
All code with runtime side effects or depending on runtime values emits a compile error.
All function calls cause the compiler to interpret the function at compile-time, emitting a compile error if the function tries to do something that has global runtime side effects.
This means that a programmer can create a function which is called both at compile-time and run-time, with no modification to the function required.
Let's look at an example:
test_fibonacci_recursion.zig
const expect = @import("std").testing.expect;
fn fibonacci(index: u32) u32 {
if (index < 2) return index;
return fibonacci(index - 1) + fibonacci(index - 2);
}
test "fibonacci" {
// test fibonacci at run-time
try expect(fibonacci(7) == 13);
// test fibonacci at compile-time
try comptime expect(fibonacci(7) == 13);
}
Shell
$ zig test test_fibonacci_recursion.zig
1/1 test_fibonacci_recursion.test.fibonacci...OK
All 1 tests passed.
Imagine if we had forgotten the base case of the recursive function and tried to run the tests:
test_fibonacci_comptime_overflow.zig
const expect = @import("std").testing.expect;
fn fibonacci(index: u32) u32 {
//if (index < 2) return index;
return fibonacci(index - 1) + fibonacci(index - 2);
}
test "fibonacci" {
try comptime expect(fibonacci(7) == 13);
}
Shell
$ zig test test_fibonacci_comptime_overflow.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_fibonacci_comptime_overflow.zig:5:28: error: overflow of integer type 'u32' with value '-1'
return fibonacci(index - 1) + fibonacci(index - 2);
~~~~~~^~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_fibonacci_comptime_overflow.zig:5:21: note: called at comptime here (7 times)
return fibonacci(index - 1) + fibonacci(index - 2);
~~~~~~~~~^~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_fibonacci_comptime_overflow.zig:9:34: note: called at comptime here
try comptime expect(fibonacci(7) == 13);
~~~~~~~~~^~~
The compiler produces an error which is a stack trace from trying to evaluate the function at compile-time.
Luckily, we used an unsigned integer, and so when we tried to subtract 1 from 0, it triggered Illegal Behavior, which is always a compile error if the compiler knows it happened. But what would have happened if we used a signed integer?
fibonacci_comptime_infinite_recursion.zig
const assert = @import("std").debug.assert;
fn fibonacci(index: i32) i32 {
//if (index < 2) return index;
return fibonacci(index - 1) + fibonacci(index - 2);
}
test "fibonacci" {
try comptime assert(fibonacci(7) == 13);
}
The compiler is supposed to notice that evaluating this function at compile-time took more than 1000 branches, and thus emits an error and gives up. If the programmer wants to increase the budget for compile-time computation, they can use a built-in function called @setEvalBranchQuota to change the default number 1000 to something else.
However, there is a design flaw in the compiler causing it to stack overflow instead of having the proper behavior here. I'm terribly sorry about that. I hope to get this resolved before the next release.
What if we fix the base case, but put the wrong value in the expect line?
test_fibonacci_comptime_unreachable.zig
const assert = @import("std").debug.assert;
fn fibonacci(index: i32) i32 {
if (index < 2) return index;
return fibonacci(index - 1) + fibonacci(index - 2);
}
test "fibonacci" {
try comptime assert(fibonacci(7) == 99999);
}
Shell
$ zig test test_fibonacci_comptime_unreachable.zig
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/debug.zig:548:14: error: reached unreachable code
if (!ok) unreachable; // assertion failure
^~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_fibonacci_comptime_unreachable.zig:9:24: note: called at comptime here
try comptime assert(fibonacci(7) == 99999);
~~~~~~^~~~~~~~~~~~~~~~~~~~~~~
At container level (outside of any function), all expressions are implicitly comptime expressions. This means that we can use functions to initialize complex static data. For example:
test_container-level_comptime_expressions.zig
const first_25_primes = firstNPrimes(25);
const sum_of_first_25_primes = sum(&first_25_primes);
fn firstNPrimes(comptime n: usize) [n]i32 {
var prime_list: [n]i32 = undefined;
var next_index: usize = 0;
var test_number: i32 = 2;
while (next_index < prime_list.len) : (test_number += 1) {
var test_prime_index: usize = 0;
var is_prime = true;
while (test_prime_index < next_index) : (test_prime_index += 1) {
if (test_number % prime_list[test_prime_index] == 0) {
is_prime = false;
break;
}
}
if (is_prime) {
prime_list[next_index] = test_number;
next_index += 1;
}
}
return prime_list;
}
fn sum(numbers: []const i32) i32 {
var result: i32 = 0;
for (numbers) |x| {
result += x;
}
return result;
}
test "variable values" {
try @import("std").testing.expect(sum_of_first_25_primes == 1060);
}
Shell
$ zig test test_container-level_comptime_expressions.zig
1/1 test_container-level_comptime_expressions.test.variable values...OK
All 1 tests passed.
When we compile this program, Zig generates the constants with the answer pre-computed. Here are the lines from the generated LLVM IR:
@0 = internal unnamed_addr constant [25 x i32] [i32 2, i32 3, i32 5, i32 7, i32 11, i32 13, i32 17, i32 19, i32 23, i32 29, i32 31, i32 37, i32 41, i32 43, i32 47, i32 53, i32 59, i32 61, i32 67, i32 71, i32 73, i32 79, i32 83, i32 89, i32 97]
@1 = internal unnamed_addr constant i32 1060
Note that we did not have to do anything special with the syntax of these functions. For example, we could call the sum function as is with a slice of numbers whose length and values were only known at run-time.
Generic Data Structures
Zig uses comptime capabilities to implement generic data structures without introducing any special-case syntax.
Here is an example of a generic List data structure.
generic_data_structure.zig
fn List(comptime T: type) type {
return struct {
items: []T,
len: usize,
};
}
// The generic List data structure can be instantiated by passing in a type:
var buffer: [10]i32 = undefined;
var list = List(i32){
.items = &buffer,
.len = 0,
};
That's it. It's a function that returns an anonymous struct. For the purposes of error messages and debugging, Zig infers the name "List(i32)" from the function name and parameters invoked when creating the anonymous struct.
To explicitly give a type a name, we assign it to a constant.
anonymous_struct_name.zig
const Node = struct {
next: ?*Node,
name: []const u8,
};
var node_a = Node{
.next = null,
.name = "Node A",
};
var node_b = Node{
.next = &node_a,
.name = "Node B",
};
In this example, the Node struct refers to itself. This works because all top level declarations are order-independent. As long as the compiler can determine the size of the struct, it is free to refer to itself. In this case, Node refers to itself as a pointer, which has a well-defined size at compile time, so it works fine.
Case Study: print in Zig
Putting all of this together, let's see how print works in Zig.
print.zig
const print = @import("std").debug.print;
const a_number: i32 = 1234;
const a_string = "foobar";
pub fn main() void {
print("here is a string: '{s}' here is a number: {}\n", .{ a_string, a_number });
}
Shell
$ zig build-exe print.zig
$ ./print
here is a string: 'foobar' here is a number: 1234
Let's crack open the implementation of this and see how it works:
poc_print_fn.zig
const Writer = struct {
/// Calls print and then flushes the buffer.
pub fn print(self: *Writer, comptime format: []const u8, args: anytype) anyerror!void {
const State = enum {
start,
open_brace,
close_brace,
};
comptime var start_index: usize = 0;
comptime var state = State.start;
comptime var next_arg: usize = 0;
inline for (format, 0..) |c, i| {
switch (state) {
State.start => switch (c) {
'{' => {
if (start_index < i) try self.write(format[start_index..i]);
state = State.open_brace;
},
'}' => {
if (start_index < i) try self.write(format[start_index..i]);
state = State.close_brace;
},
else => {},
},
State.open_brace => switch (c) {
'{' => {
state = State.start;
start_index = i;
},
'}' => {
try self.printValue(args[next_arg]);
next_arg += 1;
state = State.start;
start_index = i + 1;
},
's' => {
continue;
},
else => @compileError("Unknown format character: " ++ [1]u8{c}),
},
State.close_brace => switch (c) {
'}' => {
state = State.start;
start_index = i;
},
else => @compileError("Single '}' encountered in format string"),
},
}
}
comptime {
if (args.len != next_arg) {
@compileError("Unused arguments");
}
if (state != State.start) {
@compileError("Incomplete format string: " ++ format);
}
}
if (start_index < format.len) {
try self.write(format[start_index..format.len]);
}
try self.flush();
}
fn write(self: *Writer, value: []const u8) !void {
_ = self;
_ = value;
}
pub fn printValue(self: *Writer, value: anytype) !void {
_ = self;
_ = value;
}
fn flush(self: *Writer) !void {
_ = self;
}
};
This is a proof of concept implementation; the actual function in the standard library has more formatting capabilities.
Note that this is not hard-coded into the Zig compiler; this is userland code in the standard library.
When this function is analyzed from our example code above, Zig partially evaluates the function and emits a function that actually looks like this:
Emitted print Function
pub fn print(self: *Writer, arg0: []const u8, arg1: i32) !void {
try self.write("here is a string: '");
try self.printValue(arg0);
try self.write("' here is a number: ");
try self.printValue(arg1);
try self.write("\n");
try self.flush();
}
printValue is a function that takes a parameter of any type, and does different things depending on the type:
poc_printValue_fn.zig
const Writer = struct {
pub fn printValue(self: *Writer, value: anytype) !void {
switch (@typeInfo(@TypeOf(value))) {
.int => {
return self.writeInt(value);
},
.float => {
return self.writeFloat(value);
},
.pointer => {
return self.write(value);
},
else => {
@compileError("Unable to print type '" ++ @typeName(@TypeOf(value)) ++ "'");
},
}
}
fn write(self: *Writer, value: []const u8) !void {
_ = self;
_ = value;
}
fn writeInt(self: *Writer, value: anytype) !void {
_ = self;
_ = value;
}
fn writeFloat(self: *Writer, value: anytype) !void {
_ = self;
_ = value;
}
};
And now, what happens if we give too many arguments to print?
test_print_too_many_args.zig
const print = @import("std").debug.print;
const a_number: i32 = 1234;
const a_string = "foobar";
test "print too many arguments" {
print("here is a string: '{s}' here is a number: {}\n", .{
a_string,
a_number,
a_number,
});
}
Shell
$ zig test test_print_too_many_args.zig
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/fmt.zig:211:18: error: unused argument in 'here is a string: '{s}' here is a number: {}
'
1 => @compileError("unused argument in '" ++ fmt ++ "'"),
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
referenced by:
print__anon_711: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/io/Writer.zig:24:26
print [inlined]: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/io.zig:312:47
print__anon_455: /home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/debug.zig:213:27
Zig gives programmers the tools needed to protect themselves against their own mistakes.
Zig doesn't care whether the format argument is a string literal, only that it is a compile-time known value that can be coerced to a []const u8:
print_comptime-known_format.zig
const print = @import("std").debug.print;
const a_number: i32 = 1234;
const a_string = "foobar";
const fmt = "here is a string: '{s}' here is a number: {}\n";
pub fn main() void {
print(fmt, .{ a_string, a_number });
}
Shell
$ zig build-exe print_comptime-known_format.zig
$ ./print_comptime-known_format
here is a string: 'foobar' here is a number: 1234
This works fine.
Zig does not special case string formatting in the compiler and instead exposes enough power to accomplish this task in userland. It does so without introducing another language on top of Zig, such as a macro language or a preprocessor language. It's Zig all the way down.
See also:
inline while
inline for
Assembly
For some use cases, it may be necessary to directly control the machine code generated by Zig programs, rather than relying on Zig's code generation. For these cases, one can use inline assembly. Here is an example of implementing Hello, World on x86_64 Linux using inline assembly:
inline_assembly.zig
pub fn main() noreturn {
const msg = "hello world\n";
_ = syscall3(SYS_write, STDOUT_FILENO, @intFromPtr(msg), msg.len);
_ = syscall1(SYS_exit, 0);
unreachable;
}
pub const SYS_write = 1;
pub const SYS_exit = 60;
pub const STDOUT_FILENO = 1;
pub fn syscall1(number: usize, arg1: usize) usize {
return asm volatile ("syscall"
: [ret] "={rax}" (-> usize),
: [number] "{rax}" (number),
[arg1] "{rdi}" (arg1),
: "rcx", "r11"
);
}
pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {
return asm volatile ("syscall"
: [ret] "={rax}" (-> usize),
: [number] "{rax}" (number),
[arg1] "{rdi}" (arg1),
[arg2] "{rsi}" (arg2),
[arg3] "{rdx}" (arg3),
: "rcx", "r11"
);
}
Shell
$ zig build-exe inline_assembly.zig -target x86_64-linux
$ ./inline_assembly
hello world
Dissecting the syntax:
Assembly Syntax Explained.zig
pub fn syscall1(number: usize, arg1: usize) usize {
// Inline assembly is an expression which returns a value.
// the `asm` keyword begins the expression.
return asm
// `volatile` is an optional modifier that tells Zig this
// inline assembly expression has side-effects. Without
// `volatile`, Zig is allowed to delete the inline assembly
// code if the result is unused.
volatile (
// Next is a comptime string which is the assembly code.
// Inside this string one may use `%[ret]`, `%[number]`,
// or `%[arg1]` where a register is expected, to specify
// the register that Zig uses for the argument or return value,
// if the register constraint strings are used. However in
// the below code, this is not used. A literal `%` can be
// obtained by escaping it with a double percent: `%%`.
// Often multiline string syntax comes in handy here.
\\syscall
// Next is the output. It is possible in the future Zig will
// support multiple outputs, depending on how
// https://github.com/ziglang/zig/issues/215 is resolved.
// It is allowed for there to be no outputs, in which case
// this colon would be directly followed by the colon for the inputs.
:
// This specifies the name to be used in `%[ret]` syntax in
// the above assembly string. This example does not use it,
// but the syntax is mandatory.
[ret]
// Next is the output constraint string. This feature is still
// considered unstable in Zig, and so LLVM/GCC documentation
// must be used to understand the semantics.
// http://releases.llvm.org/10.0.0/docs/LangRef.html#inline-asm-constraint-string
// https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html
// In this example, the constraint string means "the result value of
// this inline assembly instruction is whatever is in $rax".
"={rax}"
// Next is either a value binding, or `->` and then a type. The
// type is the result type of the inline assembly expression.
// If it is a value binding, then `%[ret]` syntax would be used
// to refer to the register bound to the value.
(-> usize),
// Next is the list of inputs.
// The constraint for these inputs means, "when the assembly code is
// executed, $rax shall have the value of `number` and $rdi shall have
// the value of `arg1`". Any number of input parameters is allowed,
// including none.
: [number] "{rax}" (number),
[arg1] "{rdi}" (arg1),
// Next is the list of clobbers. These declare a set of registers whose
// values will not be preserved by the execution of this assembly code.
// These do not include output or input registers. The special clobber
// value of "memory" means that the assembly writes to arbitrary undeclared
// memory locations - not only the memory pointed to by a declared indirect
// output. In this example we list $rcx and $r11 because it is known the
// kernel syscall does not preserve these registers.
: "rcx", "r11"
);
}
For x86 and x86_64 targets, the syntax is AT&T syntax, rather than the more popular Intel syntax. This is due to technical constraints; assembly parsing is provided by LLVM and its support for Intel syntax is buggy and not well tested.
Some day Zig may have its own assembler. This would allow it to integrate more seamlessly into the language, as well as be compatible with the popular NASM syntax. This documentation section will be updated before 1.0.0 is released, with a conclusive statement about the status of AT&T vs Intel/NASM syntax.
Output Constraints
Output constraints are still considered to be unstable in Zig, and so LLVM documentation and GCC documentation must be used to understand the semantics.
Note that some breaking changes to output constraints are planned with issue #215.
Input Constraints
Input constraints are still considered to be unstable in Zig, and so LLVM documentation and GCC documentation must be used to understand the semantics.
Note that some breaking changes to input constraints are planned with issue #215.
Clobbers
Clobbers are the set of registers whose values will not be preserved by the execution of the assembly code. These do not include output or input registers. The special clobber value of "memory" means that the assembly causes writes to arbitrary undeclared memory locations - not only the memory pointed to by a declared indirect output.
Failure to declare the full set of clobbers for a given inline assembly expression is unchecked Illegal Behavior.
Global Assembly
When an assembly expression occurs in a container level comptime block, this is global assembly.
This kind of assembly has different rules than inline assembly. First, volatile is not valid because all global assembly is unconditionally included. Second, there are no inputs, outputs, or clobbers. All global assembly is concatenated verbatim into one long string and assembled together. There are no template substitution rules regarding % as there are in inline assembly expressions.
test_global_assembly.zig
const std = @import("std");
const expect = std.testing.expect;
comptime {
asm (
\\.global my_func;
\\.type my_func, @function;
\\my_func:
\\ lea (%rdi,%rsi,1),%eax
\\ retq
);
}
extern fn my_func(a: i32, b: i32) i32;
test "global assembly" {
try expect(my_func(12, 34) == 46);
}
Shell
$ zig test test_global_assembly.zig -target x86_64-linux -fllvm
1/1 test_global_assembly.test.global assembly...OK
All 1 tests passed.
Atomics
TODO: @atomic rmw
TODO: builtin atomic memory ordering enum
See also:
@atomicLoad
@atomicStore
@atomicRmw
@cmpxchgWeak
@cmpxchgStrong
Async Functions
Async functions regressed with the release of 0.11.0. Their future in the Zig language is unclear due to multiple unsolved problems:
LLVM's lack of ability to optimize them.
Third-party debuggers' lack of ability to debug them.
The cancellation problem.
Async function pointers preventing the stack size from being known.
These problems are surmountable, but it will take time. The Zig team is currently focused on other priorities.
Builtin Functions
Builtin functions are provided by the compiler and are prefixed with @. The comptime keyword on a parameter means that the parameter must be known at compile time.
@addrSpaceCast
@addrSpaceCast(ptr: anytype) anytype
Converts a pointer from one address space to another. The new address space is inferred based on the result type. Depending on the current target and address spaces, this cast may be a no-op, a complex operation, or illegal. If the cast is legal, then the resulting pointer points to the same memory location as the pointer operand. It is always valid to cast a pointer between the same address spaces.
@addWithOverflow
@addWithOverflow(a: anytype, b: anytype) struct { @TypeOf(a, b), u1 }
Performs a + b and returns a tuple with the result and a possible overflow bit.
@alignCast
@alignCast(ptr: anytype) anytype
ptr can be *T, ?*T, or []T. Changes the alignment of a pointer. The alignment to use is inferred based on the result type.
A pointer alignment safety check is added to the generated code to make sure the pointer is aligned as promised.
@alignOf
@alignOf(comptime T: type) comptime_int
This function returns the number of bytes that this type should be aligned to for the current target to match the C ABI. When the child type of a pointer has this alignment, the alignment can be omitted from the type.
const assert = @import("std").debug.assert;
comptime {
assert(*u32 == *align(@alignOf(u32)) u32);
}
The result is a target-specific compile time constant. It is guaranteed to be less than or equal to @sizeOf(T).
See also:
Alignment
@as
@as(comptime T: type, expression) T
Performs Type Coercion. This cast is allowed when the conversion is unambiguous and safe, and is the preferred way to convert between types, whenever possible.
@atomicLoad
@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: AtomicOrder) T
This builtin function atomically dereferences a pointer to a T and returns the value.
T must be a pointer, a bool, a float, an integer or an enum.
AtomicOrder can be found with @import("std").builtin.AtomicOrder.
See also:
@atomicStore
@atomicRmw
@cmpxchgWeak
@cmpxchgStrong
@atomicRmw
@atomicRmw(comptime T: type, ptr: *T, comptime op: AtomicRmwOp, operand: T, comptime ordering: AtomicOrder) T
This builtin function dereferences a pointer to a T and atomically modifies the value and returns the previous value.
T must be a pointer, a bool, a float, an integer or an enum.
AtomicOrder can be found with @import("std").builtin.AtomicOrder.
AtomicRmwOp can be found with @import("std").builtin.AtomicRmwOp.
See also:
@atomicStore
@atomicLoad
@cmpxchgWeak
@cmpxchgStrong
@atomicStore
@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: AtomicOrder) void
This builtin function dereferences a pointer to a T and atomically stores the given value.
T must be a pointer, a bool, a float, an integer or an enum.
AtomicOrder can be found with @import("std").builtin.AtomicOrder.
See also:
@atomicLoad
@atomicRmw
@cmpxchgWeak
@cmpxchgStrong
@bitCast
@bitCast(value: anytype) anytype
Converts a value of one type to another type. The return type is the inferred result type.
Asserts that @sizeOf(@TypeOf(value)) == @sizeOf(DestType).
Asserts that @typeInfo(DestType) != .pointer. Use @ptrCast or @ptrFromInt if you need this.
Can be used for these things for example:
Convert f32 to u32 bits
Convert i32 to u32 preserving twos complement
Works at compile-time if value is known at compile time. It's a compile error to bitcast a value of undefined layout; this means that, besides the restriction from types which possess dedicated casting builtins (enums, pointers, error sets), bare structs, error unions, slices, optionals, and any other type without a well-defined memory layout, also cannot be used in this operation.
@bitOffsetOf
@bitOffsetOf(comptime T: type, comptime field_name: []const u8) comptime_int
Returns the bit offset of a field relative to its containing struct.
For non packed structs, this will always be divisible by 8. For packed structs, non-byte-aligned fields will share a byte offset, but they will have different bit offsets.
See also:
@offsetOf
@bitSizeOf
@bitSizeOf(comptime T: type) comptime_int
This function returns the number of bits it takes to store T in memory if the type were a field in a packed struct/union. The result is a target-specific compile time constant.
This function measures the size at runtime. For types that are disallowed at runtime, such as comptime_int and type, the result is 0.
See also:
@sizeOf
@typeInfo
@branchHint
@branchHint(hint: BranchHint) void
Hints to the optimizer how likely a given branch of control flow is to be reached.
BranchHint can be found with @import("std").builtin.BranchHint.
This function is only valid as the first statement in a control flow branch, or the first statement in a function.
@breakpoint
@breakpoint() void
This function inserts a platform-specific debug trap instruction which causes debuggers to break there. Unlike for @trap(), execution may continue after this point if the program is resumed.
This function is only valid within function scope.
See also:
@trap
@mulAdd
@mulAdd(comptime T: type, a: T, b: T, c: T) T
Fused multiply-add, similar to (a * b) + c, except only rounds once, and is thus more accurate.
Supports Floats and Vectors of floats.
@byteSwap
@byteSwap(operand: anytype) T
@TypeOf(operand) must be an integer type or an integer vector type with bit count evenly divisible by 8.
operand may be an integer or vector.
Swaps the byte order of the integer. This converts a big endian integer to a little endian integer, and converts a little endian integer to a big endian integer.
Note that for the purposes of memory layout with respect to endianness, the integer type should be related to the number of bytes reported by @sizeOf bytes. This is demonstrated with u24. @sizeOf(u24) == 4, which means that a u24 stored in memory takes 4 bytes, and those 4 bytes are what are swapped on a little vs big endian system. On the other hand, if T is specified to be u24, then only 3 bytes are reversed.
@bitReverse
@bitReverse(integer: anytype) T
@TypeOf(anytype) accepts any integer type or integer vector type.
Reverses the bitpattern of an integer value, including the sign bit if applicable.
For example 0b10110110 (u8 = 182, i8 = -74) becomes 0b01101101 (u8 = 109, i8 = 109).
@offsetOf
@offsetOf(comptime T: type, comptime field_name: []const u8) comptime_int
Returns the byte offset of a field relative to its containing struct.
See also:
@bitOffsetOf
@call
@call(modifier: std.builtin.CallModifier, function: anytype, args: anytype) anytype
Calls a function, in the same way that invoking an expression with parentheses does:
test_call_builtin.zig
const expect = @import("std").testing.expect;
test "noinline function call" {
try expect(@call(.auto, add, .{ 3, 9 }) == 12);
}
fn add(a: i32, b: i32) i32 {
return a + b;
}
Shell
$ zig test test_call_builtin.zig
1/1 test_call_builtin.test.noinline function call...OK
All 1 tests passed.
@call allows more flexibility than normal function call syntax does. The CallModifier enum is reproduced here:
builtin.CallModifier struct.zig
pub const CallModifier = enum {
/// Equivalent to function call syntax.
auto,
/// Equivalent to async keyword used with function call syntax.
async_kw,
/// Prevents tail call optimization. This guarantees that the return
/// address will point to the callsite, as opposed to the callsite's
/// callsite. If the call is otherwise required to be tail-called
/// or inlined, a compile error is emitted instead.
never_tail,
/// Guarantees that the call will not be inlined. If the call is
/// otherwise required to be inlined, a compile error is emitted instead.
never_inline,
/// Asserts that the function call will not suspend. This allows a
/// non-async function to call an async function.
no_async,
/// Guarantees that the call will be generated with tail call optimization.
/// If this is not possible, a compile error is emitted instead.
always_tail,
/// Guarantees that the call will be inlined at the callsite.
/// If this is not possible, a compile error is emitted instead.
always_inline,
/// Evaluates the call at compile-time. If the call cannot be completed at
/// compile-time, a compile error is emitted instead.
compile_time,
};
@cDefine
@cDefine(comptime name: []const u8, value) void
This function can only occur inside @cImport.
This appends #define $name $value to the @cImport temporary buffer.
To define without a value, like this:
#define _GNU_SOURCE
Use the void value, like this:
@cDefine("_GNU_SOURCE", {})
See also:
Import from C Header File
@cInclude
@cImport
@cUndef
void
@cImport
@cImport(expression) type
This function parses C code and imports the functions, types, variables, and compatible macro definitions into a new empty struct type, and then returns that type.
expression is interpreted at compile time. The builtin functions @cInclude, @cDefine, and @cUndef work within this expression, appending to a temporary buffer which is then parsed as C code.
Usually you should only have one @cImport in your entire application, because it saves the compiler from invoking clang multiple times, and prevents inline functions from being duplicated.
Reasons for having multiple @cImport expressions would be:
To avoid a symbol collision, for example if foo.h and bar.h both #define CONNECTION_COUNT
To analyze the C code with different preprocessor defines
See also:
Import from C Header File
@cInclude
@cDefine
@cUndef
@cInclude
@cInclude(comptime path: []const u8) void
This function can only occur inside @cImport.
This appends #include <$path>\n to the c_import temporary buffer.
See also:
Import from C Header File
@cImport
@cDefine
@cUndef
@clz
@clz(operand: anytype) anytype
@TypeOf(operand) must be an integer type or an integer vector type.
operand may be an integer or vector.
Counts the number of most-significant (leading in a big-endian sense) zeroes in an integer - "count leading zeroes".
The return type is an unsigned integer or vector of unsigned integers with the minimum number of bits that can represent the bit count of the integer type.
If operand is zero, @clz returns the bit width of integer type T.
See also:
@ctz
@popCount
@cmpxchgStrong
@cmpxchgStrong(comptime T: type, ptr: *T, expected_value: T, new_value: T, success_order: AtomicOrder, fail_order: AtomicOrder) ?T
This function performs a strong atomic compare-and-exchange operation, returning null if the current value is the given expected value. It's the equivalent of this code, except atomic:
not_atomic_cmpxchgStrong.zig
fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_value: T) ?T {
const old_value = ptr.*;
if (old_value == expected_value) {
ptr.* = new_value;
return null;
} else {
return old_value;
}
}
If you are using cmpxchg in a retry loop, @cmpxchgWeak is the better choice, because it can be implemented more efficiently in machine instructions.
T must be a pointer, a bool, a float, an integer or an enum.
@typeInfo(@TypeOf(ptr)).pointer.alignment must be >= @sizeOf(T).
AtomicOrder can be found with @import("std").builtin.AtomicOrder.
See also:
@atomicStore
@atomicLoad
@atomicRmw
@cmpxchgWeak
@cmpxchgWeak
@cmpxchgWeak(comptime T: type, ptr: *T, expected_value: T, new_value: T, success_order: AtomicOrder, fail_order: AtomicOrder) ?T
This function performs a weak atomic compare-and-exchange operation, returning null if the current value is the given expected value. It's the equivalent of this code, except atomic:
cmpxchgWeakButNotAtomic
fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_value: T) ?T {
const old_value = ptr.*;
if (old_value == expected_value and usuallyTrueButSometimesFalse()) {
ptr.* = new_value;
return null;
} else {
return old_value;
}
}
If you are using cmpxchg in a retry loop, the sporadic failure will be no problem, and cmpxchgWeak is the better choice, because it can be implemented more efficiently in machine instructions. However if you need a stronger guarantee, use @cmpxchgStrong.
T must be a pointer, a bool, a float, an integer or an enum.
@typeInfo(@TypeOf(ptr)).pointer.alignment must be >= @sizeOf(T).
AtomicOrder can be found with @import("std").builtin.AtomicOrder.
See also:
@atomicStore
@atomicLoad
@atomicRmw
@cmpxchgStrong
@compileError
@compileError(comptime msg: []const u8) noreturn
This function, when semantically analyzed, causes a compile error with the message msg.
There are several ways that code avoids being semantically checked, such as using if or switch with compile time constants, and comptime functions.
@compileLog
@compileLog(...) void
This function prints the arguments passed to it at compile-time.
To prevent accidentally leaving compile log statements in a codebase, a compilation error is added to the build, pointing to the compile log statement. This error prevents code from being generated, but does not otherwise interfere with analysis.
This function can be used to do "printf debugging" on compile-time executing code.
test_compileLog_builtin.zig
const print = @import("std").debug.print;
const num1 = blk: {
var val1: i32 = 99;
@compileLog("comptime val1 = ", val1);
val1 = val1 + 1;
break :blk val1;
};
test "main" {
@compileLog("comptime in main");
print("Runtime in main, num1 = {}.\n", .{num1});
}
Shell
$ zig test test_compileLog_builtin.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_compileLog_builtin.zig:5:5: error: found compile log statement
@compileLog("comptime val1 = ", val1);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_compileLog_builtin.zig:11:5: note: also here
@compileLog("comptime in main");
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
referenced by:
test.main: /home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_compileLog_builtin.zig:13:46
Compile Log Output:
@as(*const [16:0]u8, "comptime val1 = "), @as(i32, 99)
@as(*const [16:0]u8, "comptime in main")
@constCast
@constCast(value: anytype) DestType
Remove const qualifier from a pointer.
@ctz
@ctz(operand: anytype) anytype
@TypeOf(operand) must be an integer type or an integer vector type.
operand may be an integer or vector.
Counts the number of least-significant (trailing in a big-endian sense) zeroes in an integer - "count trailing zeroes".
The return type is an unsigned integer or vector of unsigned integers with the minimum number of bits that can represent the bit count of the integer type.
If operand is zero, @ctz returns the bit width of integer type T.
See also:
@clz
@popCount
@cUndef
@cUndef(comptime name: []const u8) void
This function can only occur inside @cImport.
This appends #undef $name to the @cImport temporary buffer.
See also:
Import from C Header File
@cImport
@cDefine
@cInclude
@cVaArg
@cVaArg(operand: *std.builtin.VaList, comptime T: type) T
Implements the C macro va_arg.
See also:
@cVaCopy
@cVaEnd
@cVaStart
@cVaCopy
@cVaCopy(src: *std.builtin.VaList) std.builtin.VaList
Implements the C macro va_copy.
See also:
@cVaArg
@cVaEnd
@cVaStart
@cVaEnd
@cVaEnd(src: *std.builtin.VaList) void
Implements the C macro va_end.
See also:
@cVaArg
@cVaCopy
@cVaStart
@cVaStart
@cVaStart() std.builtin.VaList
Implements the C macro va_start. Only valid inside a variadic function.
See also:
@cVaArg
@cVaCopy
@cVaEnd
@divExact
@divExact(numerator: T, denominator: T) T
Exact division. Caller guarantees denominator != 0 and @divTrunc(numerator, denominator) * denominator == numerator.
@divExact(6, 3) == 2
@divExact(a, b) * b == a
For a function that returns a possible error code, use @import("std").math.divExact.
See also:
@divTrunc
@divFloor
@divFloor
@divFloor(numerator: T, denominator: T) T
Floored division. Rounds toward negative infinity. For unsigned integers it is the same as numerator / denominator. Caller guarantees denominator != 0 and !(@typeInfo(T) == .int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1).
@divFloor(-5, 3) == -2
(@divFloor(a, b) * b) + @mod(a, b) == a
For a function that returns a possible error code, use @import("std").math.divFloor.
See also:
@divTrunc
@divExact
@divTrunc
@divTrunc(numerator: T, denominator: T) T
Truncated division. Rounds toward zero. For unsigned integers it is the same as numerator / denominator. Caller guarantees denominator != 0 and !(@typeInfo(T) == .int and T.is_signed and numerator == std.math.minInt(T) and denominator == -1).
@divTrunc(-5, 3) == -1
(@divTrunc(a, b) * b) + @rem(a, b) == a
For a function that returns a possible error code, use @import("std").math.divTrunc.
See also:
@divFloor
@divExact
@embedFile
@embedFile(comptime path: []const u8) *const [N:0]u8
This function returns a compile time constant pointer to null-terminated, fixed-size array with length equal to the byte count of the file given by path. The contents of the array are the contents of the file. This is equivalent to a string literal with the file contents.
path is absolute or relative to the current file, just like @import.
See also:
@import
@enumFromInt
@enumFromInt(integer: anytype) anytype
Converts an integer into an enum value. The return type is the inferred result type.
Attempting to convert an integer with no corresponding value in the enum invokes safety-checked Illegal Behavior. Note that a non-exhaustive enum has corresponding values for all integers in the enum's integer tag type: the _ value represents all the remaining unnamed integers in the enum's tag type.
See also:
@intFromEnum
@errorFromInt
@errorFromInt(value: std.meta.Int(.unsigned, @bitSizeOf(anyerror))) anyerror
Converts from the integer representation of an error into The Global Error Set type.
It is generally recommended to avoid this cast, as the integer representation of an error is not stable across source code changes.
Attempting to convert an integer that does not correspond to any error results in safety-checked Illegal Behavior.
See also:
@intFromError
@errorName
@errorName(err: anyerror) [:0]const u8
This function returns the string representation of an error. The string representation of error.OutOfMem is "OutOfMem".
If there are no calls to @errorName in an entire application, or all calls have a compile-time known value for err, then no error name table will be generated.
@errorReturnTrace
@errorReturnTrace() ?*builtin.StackTrace
If the binary is built with error return tracing, and this function is invoked in a function that calls a function with an error or error union return type, returns a stack trace object. Otherwise returns null.
@errorCast
@errorCast(value: anytype) anytype
Converts an error set or error union value from one error set to another error set. The return type is the inferred result type. Attempting to convert an error which is not in the destination error set results in safety-checked Illegal Behavior.
@export
@export(comptime ptr: *const anyopaque, comptime options: std.builtin.ExportOptions) void
Creates a symbol in the output object file which refers to the target of ptr.
ptr must point to a global variable or a comptime-known constant.
This builtin can be called from a comptime block to conditionally export symbols. When ptr points to a function with the C calling convention and options.linkage is .Strong, this is equivalent to the export keyword used on a function:
export_builtin.zig
comptime {
@export(&internalName, .{ .name = "foo", .linkage = .strong });
}
fn internalName() callconv(.c) void {}
Shell
$ zig build-obj export_builtin.zig
This is equivalent to:
export_builtin_equivalent_code.zig
export fn foo() void {}
Shell
$ zig build-obj export_builtin_equivalent_code.zig
Note that even when using export, the @"foo" syntax for identifiers can be used to choose any string for the symbol name:
export_any_symbol_name.zig
export fn @"A function name that is a complete sentence."() void {}
Shell
$ zig build-obj export_any_symbol_name.zig
When looking at the resulting object, you can see the symbol is used verbatim:
00000000000001f0 T A function name that is a complete sentence.
See also:
Exporting a C Library
@extern
@extern(T: type, comptime options: std.builtin.ExternOptions) T
Creates a reference to an external symbol in the output object file. T must be a pointer type.
See also:
@export
@field
@field(lhs: anytype, comptime field_name: []const u8) (field)
Performs field access by a compile-time string. Works on both fields and declarations.
test_field_builtin.zig
const std = @import("std");
const Point = struct {
x: u32,
y: u32,
pub var z: u32 = 1;
};
test "field access by string" {
const expect = std.testing.expect;
var p = Point{ .x = 0, .y = 0 };
@field(p, "x") = 4;
@field(p, "y") = @field(p, "x") + 1;
try expect(@field(p, "x") == 4);
try expect(@field(p, "y") == 5);
}
test "decl access by string" {
const expect = std.testing.expect;
try expect(@field(Point, "z") == 1);
@field(Point, "z") = 2;
try expect(@field(Point, "z") == 2);
}
Shell
$ zig test test_field_builtin.zig
1/2 test_field_builtin.test.field access by string...OK
2/2 test_field_builtin.test.decl access by string...OK
All 2 tests passed.
@fieldParentPtr
@fieldParentPtr(comptime field_name: []const u8, field_ptr: *T) anytype
Given a pointer to a struct field, returns a pointer to the struct containing that field. The return type (and struct in question) is the inferred result type.
If field_ptr does not point to the field_name field of an instance of the result type, and the result type has ill-defined layout, invokes unchecked Illegal Behavior.
@FieldType
@FieldType(comptime Type: type, comptime field_name: []const u8) type
Given a type and the name of one of its fields, returns the type of that field.
@floatCast
@floatCast(value: anytype) anytype
Convert from one float type to another. This cast is safe, but may cause the numeric value to lose precision. The return type is the inferred result type.
@floatFromInt
@floatFromInt(int: anytype) anytype
Converts an integer to the closest floating point representation. The return type is the inferred result type. To convert the other way, use @intFromFloat. This operation is legal for all values of all integer types.
@frameAddress
@frameAddress() usize
This function returns the base pointer of the current stack frame.
The implications of this are target-specific and not consistent across all platforms. The frame address may not be available in release mode due to aggressive optimizations.
This function is only valid within function scope.
@hasDecl
@hasDecl(comptime Container: type, comptime name: []const u8) bool
Returns whether or not a container has a declaration matching name.
test_hasDecl_builtin.zig
const std = @import("std");
const expect = std.testing.expect;
const Foo = struct {
nope: i32,
pub var blah = "xxx";
const hi = 1;
};
test "@hasDecl" {
try expect(@hasDecl(Foo, "blah"));
// Even though `hi` is private, @hasDecl returns true because this test is
// in the same file scope as Foo. It would return false if Foo was declared
// in a different file.
try expect(@hasDecl(Foo, "hi"));
// @hasDecl is for declarations; not fields.
try expect(!@hasDecl(Foo, "nope"));
try expect(!@hasDecl(Foo, "nope1234"));
}
Shell
$ zig test test_hasDecl_builtin.zig
1/1 test_hasDecl_builtin.test.@hasDecl...OK
All 1 tests passed.
See also:
@hasField
@hasField
@hasField(comptime Container: type, comptime name: []const u8) bool
Returns whether the field name of a struct, union, or enum exists.
The result is a compile time constant.
It does not include functions, variables, or constants.
See also:
@hasDecl
@import
@import(comptime path: []const u8) type
This function finds a zig file corresponding to path and adds it to the build, if it is not already added.
Zig source files are implicitly structs, with a name equal to the file's basename with the extension truncated. @import returns the struct type corresponding to the file.
Declarations which have the pub keyword may be referenced from a different source file than the one they are declared in.
path can be a relative path or it can be the name of a package. If it is a relative path, it is relative to the file that contains the @import function call.
The following packages are always available:
@import("std") - Zig Standard Library
@import("builtin") - Target-specific information The command zig build-exe --show-builtin outputs the source to stdout for reference.
@import("root") - Root source file This is usually src/main.zig but depends on what file is built.
See also:
Compile Variables
@embedFile
@inComptime
@inComptime() bool
Returns whether the builtin was run in a comptime context. The result is a compile-time constant.
This can be used to provide alternative, comptime-friendly implementations of functions. It should not be used, for instance, to exclude certain functions from being evaluated at comptime.
See also:
comptime
@intCast
@intCast(int: anytype) anytype
Converts an integer to another integer while keeping the same numerical value. The return type is the inferred result type. Attempting to convert a number which is out of range of the destination type results in safety-checked Illegal Behavior.
test_intCast_builtin.zig
test "integer cast panic" {
var a: u16 = 0xabcd; // runtime-known
_ = &a;
const b: u8 = @intCast(a);
_ = b;
}
Shell
$ zig test test_intCast_builtin.zig
1/1 test_intCast_builtin.test.integer cast panic...thread 3521217 panic: integer does not fit in destination type
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_intCast_builtin.zig:4:19: 0x102d020 in test.integer cast panic (test_intCast_builtin.zig)
const b: u8 = @intCast(a);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x1175db3 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:64:28: 0x116be57 in main (test_runner.zig)
return mainTerminal();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1164f8d in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x1164863 in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/42175105b1664cf54a6dcb11952d99d3/test --seed=0xa40b7fe
To truncate the significant bits of a number out of range of the destination type, use @truncate.
If T is comptime_int, then this is semantically equivalent to Type Coercion.
@intFromBool
@intFromBool(value: bool) u1
Converts true to @as(u1, 1) and false to @as(u1, 0).
@intFromEnum
@intFromEnum(enum_or_tagged_union: anytype) anytype
Converts an enumeration value into its integer tag type. When a tagged union is passed, the tag value is used as the enumeration value.
If there is only one possible enum value, the result is a comptime_int known at comptime.
See also:
@enumFromInt
@intFromError
@intFromError(err: anytype) std.meta.Int(.unsigned, @bitSizeOf(anyerror))
Supports the following types:
The Global Error Set
Error Set Type
Error Union Type
Converts an error to the integer representation of an error.
It is generally recommended to avoid this cast, as the integer representation of an error is not stable across source code changes.
See also:
@errorFromInt
@intFromFloat
@intFromFloat(float: anytype) anytype
Converts the integer part of a floating point number to the inferred result type.
If the integer part of the floating point number cannot fit in the destination type, it invokes safety-checked Illegal Behavior.
See also:
@floatFromInt
@intFromPtr
@intFromPtr(value: anytype) usize
Converts value to a usize which is the address of the pointer. value can be *T or ?*T.
To convert the other way, use @ptrFromInt
@max
@max(...) T
Takes two or more arguments and returns the biggest value included (the maximum). This builtin accepts integers, floats, and vectors of either. In the latter case, the operation is performed element wise.
NaNs are handled as follows: return the biggest non-NaN value included. If all operands are NaN, return NaN.
See also:
@min
Vectors
@memcpy
@memcpy(noalias dest, noalias source) void
This function copies bytes from one region of memory to another.
dest must be a mutable slice, a mutable pointer to an array, or a mutable many-item pointer. It may have any alignment, and it may have any element type.
source must be a slice, a pointer to an array, or a many-item pointer. It may have any alignment, and it may have any element type.
The source element type must have the same in-memory representation as the dest element type.
Similar to for loops, at least one of source and dest must provide a length, and if two lengths are provided, they must be equal.
Finally, the two memory regions must not overlap.
@memset
@memset(dest, elem) void
This function sets all the elements of a memory region to elem.
dest must be a mutable slice or a mutable pointer to an array. It may have any alignment, and it may have any element type.
elem is coerced to the element type of dest.
For securely zeroing out sensitive contents from memory, you should use std.crypto.secureZero
@memmove
@memmove(dest, source) void
This function copies bytes from one region of memory to another, but unlike @memcpy the regions may overlap.
dest must be a mutable slice, a mutable pointer to an array, or a mutable many-item pointer. It may have any alignment, and it may have any element type.
source must be a slice, a pointer to an array, or a many-item pointer. It may have any alignment, and it may have any element type.
The source element type must have the same in-memory representation as the dest element type.
Similar to for loops, at least one of source and dest must provide a length, and if two lengths are provided, they must be equal.
@min
@min(...) T
Takes two or more arguments and returns the smallest value included (the minimum). This builtin accepts integers, floats, and vectors of either. In the latter case, the operation is performed element wise.
NaNs are handled as follows: return the smallest non-NaN value included. If all operands are NaN, return NaN.
See also:
@max
Vectors
@wasmMemorySize
@wasmMemorySize(index: u32) usize
This function returns the size of the Wasm memory identified by index as an unsigned value in units of Wasm pages. Note that each Wasm page is 64KB in size.
This function is a low level intrinsic with no safety mechanisms usually useful for allocator designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use something like @import("std").heap.WasmPageAllocator.
See also:
@wasmMemoryGrow
@wasmMemoryGrow
@wasmMemoryGrow(index: u32, delta: usize) isize
This function increases the size of the Wasm memory identified by index by delta in units of unsigned number of Wasm pages. Note that each Wasm page is 64KB in size. On success, returns previous memory size; on failure, if the allocation fails, returns -1.
This function is a low level intrinsic with no safety mechanisms usually useful for allocator designers targeting Wasm. So unless you are writing a new allocator from scratch, you should use something like @import("std").heap.WasmPageAllocator.
test_wasmMemoryGrow_builtin.zig
const std = @import("std");
const native_arch = @import("builtin").target.cpu.arch;
const expect = std.testing.expect;
test "@wasmMemoryGrow" {
if (native_arch != .wasm32) return error.SkipZigTest;
const prev = @wasmMemorySize(0);
try expect(prev == @wasmMemoryGrow(0, 1));
try expect(prev + 1 == @wasmMemorySize(0));
}
Shell
$ zig test test_wasmMemoryGrow_builtin.zig
1/1 test_wasmMemoryGrow_builtin.test.@wasmMemoryGrow...SKIP
0 passed; 1 skipped; 0 failed.
See also:
@wasmMemorySize
@mod
@mod(numerator: T, denominator: T) T
Modulus division. For unsigned integers this is the same as numerator % denominator. Caller guarantees denominator > 0, otherwise the operation will result in a Remainder Division by Zero when runtime safety checks are enabled.
@mod(-5, 3) == 1
(@divFloor(a, b) * b) + @mod(a, b) == a
For a function that returns an error code, see @import("std").math.mod.
See also:
@rem
@mulWithOverflow
@mulWithOverflow(a: anytype, b: anytype) struct { @TypeOf(a, b), u1 }
Performs a * b and returns a tuple with the result and a possible overflow bit.
@panic
@panic(message: []const u8) noreturn
Invokes the panic handler function. By default the panic handler function calls the public panic function exposed in the root source file, or if there is not one specified, the std.builtin.default_panic function from std/builtin.zig.
Generally it is better to use @import("std").debug.panic. However, @panic can be useful for 2 scenarios:
From library code, calling the programmer's panic function if they exposed one in the root source file.
When mixing C and Zig code, calling the canonical panic implementation across multiple .o files.
See also:
Panic Handler
@popCount
@popCount(operand: anytype) anytype
@TypeOf(operand) must be an integer type.
operand may be an integer or vector.
Counts the number of bits set in an integer - "population count".
The return type is an unsigned integer or vector of unsigned integers with the minimum number of bits that can represent the bit count of the integer type.
See also:
@ctz
@clz
@prefetch
@prefetch(ptr: anytype, comptime options: PrefetchOptions) void
This builtin tells the compiler to emit a prefetch instruction if supported by the target CPU. If the target CPU does not support the requested prefetch instruction, this builtin is a no-op. This function has no effect on the behavior of the program, only on the performance characteristics.
The ptr argument may be any pointer type and determines the memory address to prefetch. This function does not dereference the pointer, it is perfectly legal to pass a pointer to invalid memory to this function and no Illegal Behavior will result.
PrefetchOptions can be found with @import("std").builtin.PrefetchOptions.
@ptrCast
@ptrCast(value: anytype) anytype
Converts a pointer of one type to a pointer of another type. The return type is the inferred result type.
Optional Pointers are allowed. Casting an optional pointer which is null to a non-optional pointer invokes safety-checked Illegal Behavior.
@ptrCast cannot be used for:
Removing const qualifier, use @constCast.
Removing volatile qualifier, use @volatileCast.
Changing pointer address space, use @addrSpaceCast.
Increasing pointer alignment, use @alignCast.
Casting a non-slice pointer to a slice, use slicing syntax ptr[start..end].
@ptrFromInt
@ptrFromInt(address: usize) anytype
Converts an integer to a pointer. The return type is the inferred result type. To convert the other way, use @intFromPtr. Casting an address of 0 to a destination type which in not optional and does not have the allowzero attribute will result in a Pointer Cast Invalid Null panic when runtime safety checks are enabled.
If the destination pointer type does not allow address zero and address is zero, this invokes safety-checked Illegal Behavior.
@rem
@rem(numerator: T, denominator: T) T
Remainder division. For unsigned integers this is the same as numerator % denominator. Caller guarantees denominator > 0, otherwise the operation will result in a Remainder Division by Zero when runtime safety checks are enabled.
@rem(-5, 3) == -2
(@divTrunc(a, b) * b) + @rem(a, b) == a
For a function that returns an error code, see @import("std").math.rem.
See also:
@mod
@returnAddress
@returnAddress() usize
This function returns the address of the next machine code instruction that will be executed when the current function returns.
The implications of this are target-specific and not consistent across all platforms.
This function is only valid within function scope. If the function gets inlined into a calling function, the returned address will apply to the calling function.
@select
@select(comptime T: type, pred: @Vector(len, bool), a: @Vector(len, T), b: @Vector(len, T)) @Vector(len, T)
Selects values element-wise from a or b based on pred. If pred[i] is true, the corresponding element in the result will be a[i] and otherwise b[i].
See also:
Vectors
@setEvalBranchQuota
@setEvalBranchQuota(comptime new_quota: u32) void
Increase the maximum number of backwards branches that compile-time code execution can use before giving up and making a compile error.
If the new_quota is smaller than the default quota (1000) or a previously explicitly set quota, it is ignored.
Example:
test_without_setEvalBranchQuota_builtin.zig
test "foo" {
comptime {
var i = 0;
while (i < 1001) : (i += 1) {}
}
}
Shell
$ zig test test_without_setEvalBranchQuota_builtin.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_without_setEvalBranchQuota_builtin.zig:4:9: error: evaluation exceeded 1000 backwards branches
while (i < 1001) : (i += 1) {}
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_without_setEvalBranchQuota_builtin.zig:4:9: note: use @setEvalBranchQuota() to raise the branch limit from 1000
Now we use @setEvalBranchQuota:
test_setEvalBranchQuota_builtin.zig
test "foo" {
comptime {
@setEvalBranchQuota(1001);
var i = 0;
while (i < 1001) : (i += 1) {}
}
}
Shell
$ zig test test_setEvalBranchQuota_builtin.zig
1/1 test_setEvalBranchQuota_builtin.test.foo...OK
All 1 tests passed.
See also:
comptime
@setFloatMode
@setFloatMode(comptime mode: FloatMode) void
Changes the current scope's rules about how floating point operations are defined.
Strict (default) - Floating point operations follow strict IEEE compliance.
Optimized - Floating point operations may do all of the following:
Assume the arguments and result are not NaN. Optimizations are required to retain legal behavior over NaNs, but the value of the result is undefined.
Assume the arguments and result are not +/-Inf. Optimizations are required to retain legal behavior over +/-Inf, but the value of the result is undefined.
Treat the sign of a zero argument or result as insignificant.
Use the reciprocal of an argument rather than perform division.
Perform floating-point contraction (e.g. fusing a multiply followed by an addition into a fused multiply-add).
Perform algebraically equivalent transformations that may change results in floating point (e.g. reassociate).
This is equivalent to -ffast-math in GCC.
The floating point mode is inherited by child scopes, and can be overridden in any scope. You can set the floating point mode in a struct or module scope by using a comptime block.
FloatMode can be found with @import("std").builtin.FloatMode.
See also:
Floating Point Operations
@setRuntimeSafety
@setRuntimeSafety(comptime safety_on: bool) void
Sets whether runtime safety checks are enabled for the scope that contains the function call.
test_setRuntimeSafety_builtin.zig
test "@setRuntimeSafety" {
// The builtin applies to the scope that it is called in. So here, integer overflow
// will not be caught in ReleaseFast and ReleaseSmall modes:
// var x: u8 = 255;
// x += 1; // Unchecked Illegal Behavior in ReleaseFast/ReleaseSmall modes.
{
// However this block has safety enabled, so safety checks happen here,
// even in ReleaseFast and ReleaseSmall modes.
@setRuntimeSafety(true);
var x: u8 = 255;
x += 1;
{
// The value can be overridden at any scope. So here integer overflow
// would not be caught in any build mode.
@setRuntimeSafety(false);
// var x: u8 = 255;
// x += 1; // Unchecked Illegal Behavior in all build modes.
}
}
}
Shell
$ zig test test_setRuntimeSafety_builtin.zig -OReleaseFast
1/1 test_setRuntimeSafety_builtin.test.@setRuntimeSafety...thread 3522332 panic: integer overflow
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_setRuntimeSafety_builtin.zig:11:11: 0x10362f8 in test.@setRuntimeSafety (test)
x += 1;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x1030b82 in main (test)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x102f32d in posixCallMainAndExit (test)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x102f01d in _start (test)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/b88d578192c07164966e53e7013075b3/test --seed=0x4679a8bf
Note: it is planned to replace @setRuntimeSafety with @optimizeFor
@shlExact
@shlExact(value: T, shift_amt: Log2T) T
Performs the left shift operation (<<). For unsigned integers, the result is undefined if any 1 bits are shifted out. For signed integers, the result is undefined if any bits that disagree with the resultant sign bit are shifted out.
The type of shift_amt is an unsigned integer with log2(@typeInfo(T).int.bits) bits. This is because shift_amt >= @typeInfo(T).int.bits triggers safety-checked Illegal Behavior.
comptime_int is modeled as an integer with an infinite number of bits, meaning that in such case, @shlExact always produces a result and cannot produce a compile error.
See also:
@shrExact
@shlWithOverflow
@shlWithOverflow
@shlWithOverflow(a: anytype, shift_amt: Log2T) struct { @TypeOf(a), u1 }
Performs a << b and returns a tuple with the result and a possible overflow bit.
The type of shift_amt is an unsigned integer with log2(@typeInfo(@TypeOf(a)).int.bits) bits. This is because shift_amt >= @typeInfo(@TypeOf(a)).int.bits triggers safety-checked Illegal Behavior.
See also:
@shlExact
@shrExact
@shrExact
@shrExact(value: T, shift_amt: Log2T) T
Performs the right shift operation (>>). Caller guarantees that the shift will not shift any 1 bits out.
The type of shift_amt is an unsigned integer with log2(@typeInfo(T).int.bits) bits. This is because shift_amt >= @typeInfo(T).int.bits triggers safety-checked Illegal Behavior.
See also:
@shlExact
@shlWithOverflow
@shuffle
@shuffle(comptime E: type, a: @Vector(a_len, E), b: @Vector(b_len, E), comptime mask: @Vector(mask_len, i32)) @Vector(mask_len, E)
Constructs a new vector by selecting elements from a and b based on mask.
Each element in mask selects an element from either a or b. Positive numbers select from a starting at 0. Negative values select from b, starting at -1 and going down. It is recommended to use the ~ operator for indexes from b so that both indexes can start from 0 (i.e. ~@as(i32, 0) is -1).
For each element of mask, if it or the selected value from a or b is undefined, then the resulting element is undefined.
a_len and b_len may differ in length. Out-of-bounds element indexes in mask result in compile errors.
If a or b is undefined, it is equivalent to a vector of all undefined with the same length as the other vector. If both vectors are undefined, @shuffle returns a vector with all elements undefined.
E must be an integer, float, pointer, or bool. The mask may be any vector length, and its length determines the result length.
test_shuffle_builtin.zig
const std = @import("std");
const expect = std.testing.expect;
test "vector @shuffle" {
const a = @Vector(7, u8){ 'o', 'l', 'h', 'e', 'r', 'z', 'w' };
const b = @Vector(4, u8){ 'w', 'd', '!', 'x' };
// To shuffle within a single vector, pass undefined as the second argument.
// Notice that we can re-order, duplicate, or omit elements of the input vector
const mask1 = @Vector(5, i32){ 2, 3, 1, 1, 0 };
const res1: @Vector(5, u8) = @shuffle(u8, a, undefined, mask1);
try expect(std.mem.eql(u8, &@as([5]u8, res1), "hello"));
// Combining two vectors
const mask2 = @Vector(6, i32){ -1, 0, 4, 1, -2, -3 };
const res2: @Vector(6, u8) = @shuffle(u8, a, b, mask2);
try expect(std.mem.eql(u8, &@as([6]u8, res2), "world!"));
}
Shell
$ zig test test_shuffle_builtin.zig
1/1 test_shuffle_builtin.test.vector @shuffle...OK
All 1 tests passed.
See also:
Vectors
@sizeOf
@sizeOf(comptime T: type) comptime_int
This function returns the number of bytes it takes to store T in memory. The result is a target-specific compile time constant.
This size may contain padding bytes. If there were two consecutive T in memory, the padding would be the offset in bytes between element at index 0 and the element at index 1. For integer, consider whether you want to use @sizeOf(T) or @typeInfo(T).int.bits.
This function measures the size at runtime. For types that are disallowed at runtime, such as comptime_int and type, the result is 0.
See also:
@bitSizeOf
@typeInfo
@splat
@splat(scalar: anytype) anytype
Produces an array or vector where each element is the value scalar. The return type and thus the length of the vector is inferred.
test_splat_builtin.zig
const std = @import("std");
const expect = std.testing.expect;
test "vector @splat" {
const scalar: u32 = 5;
const result: @Vector(4, u32) = @splat(scalar);
try expect(std.mem.eql(u32, &@as([4]u32, result), &[_]u32{ 5, 5, 5, 5 }));
}
test "array @splat" {
const scalar: u32 = 5;
const result: [4]u32 = @splat(scalar);
try expect(std.mem.eql(u32, &@as([4]u32, result), &[_]u32{ 5, 5, 5, 5 }));
}
Shell
$ zig test test_splat_builtin.zig
1/2 test_splat_builtin.test.vector @splat...OK
2/2 test_splat_builtin.test.array @splat...OK
All 2 tests passed.
scalar must be an integer, bool, float, or pointer.
See also:
Vectors
@shuffle
@reduce
@reduce(comptime op: std.builtin.ReduceOp, value: anytype) E
Transforms a vector into a scalar value (of type E) by performing a sequential horizontal reduction of its elements using the specified operator op.
Not every operator is available for every vector element type:
Every operator is available for integer vectors.
.And, .Or, .Xor are additionally available for bool vectors,
.Min, .Max, .Add, .Mul are additionally available for floating point vectors,
Note that .Add and .Mul reductions on integral types are wrapping; when applied on floating point types the operation associativity is preserved, unless the float mode is set to Optimized.
test_reduce_builtin.zig
const std = @import("std");
const expect = std.testing.expect;
test "vector @reduce" {
const V = @Vector(4, i32);
const value = V{ 1, -1, 1, -1 };
const result = value > @as(V, @splat(0));
// result is { true, false, true, false };
try comptime expect(@TypeOf(result) == @Vector(4, bool));
const is_all_true = @reduce(.And, result);
try comptime expect(@TypeOf(is_all_true) == bool);
try expect(is_all_true == false);
}
Shell
$ zig test test_reduce_builtin.zig
1/1 test_reduce_builtin.test.vector @reduce...OK
All 1 tests passed.
See also:
Vectors
@setFloatMode
@src
@src() std.builtin.SourceLocation
Returns a SourceLocation struct representing the function's name and location in the source code. This must be called in a function.
test_src_builtin.zig
const std = @import("std");
const expect = std.testing.expect;
test "@src" {
try doTheTest();
}
fn doTheTest() !void {
const src = @src();
try expect(src.line == 9);
try expect(src.column == 17);
try expect(std.mem.endsWith(u8, src.fn_name, "doTheTest"));
try expect(std.mem.endsWith(u8, src.file, "test_src_builtin.zig"));
}
Shell
$ zig test test_src_builtin.zig
1/1 test_src_builtin.test.@src...OK
All 1 tests passed.
@sqrt
@sqrt(value: anytype) @TypeOf(value)
Performs the square root of a floating point number. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@sin
@sin(value: anytype) @TypeOf(value)
Sine trigonometric function on a floating point number in radians. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@cos
@cos(value: anytype) @TypeOf(value)
Cosine trigonometric function on a floating point number in radians. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@tan
@tan(value: anytype) @TypeOf(value)
Tangent trigonometric function on a floating point number in radians. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@exp
@exp(value: anytype) @TypeOf(value)
Base-e exponential function on a floating point number. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@exp2
@exp2(value: anytype) @TypeOf(value)
Base-2 exponential function on a floating point number. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@log
@log(value: anytype) @TypeOf(value)
Returns the natural logarithm of a floating point number. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@log2
@log2(value: anytype) @TypeOf(value)
Returns the logarithm to the base 2 of a floating point number. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@log10
@log10(value: anytype) @TypeOf(value)
Returns the logarithm to the base 10 of a floating point number. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@abs
@abs(value: anytype) anytype
Returns the absolute value of an integer or a floating point number. Uses a dedicated hardware instruction when available. The return type is always an unsigned integer of the same bit width as the operand if the operand is an integer. Unsigned integer operands are supported. The builtin cannot overflow for signed integer operands.
Supports Floats, Integers and Vectors of floats or integers.
@floor
@floor(value: anytype) @TypeOf(value)
Returns the largest integral value not greater than the given floating point number. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@ceil
@ceil(value: anytype) @TypeOf(value)
Returns the smallest integral value not less than the given floating point number. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@trunc
@trunc(value: anytype) @TypeOf(value)
Rounds the given floating point number to an integer, towards zero. Uses a dedicated hardware instruction when available.
Supports Floats and Vectors of floats.
@round
@round(value: anytype) @TypeOf(value)
Rounds the given floating point number to the nearest integer. If two integers are equally close, rounds away from zero. Uses a dedicated hardware instruction when available.
test_round_builtin.zig
const expect = @import("std").testing.expect;
test "@round" {
try expect(@round(1.4) == 1);
try expect(@round(1.5) == 2);
try expect(@round(-1.4) == -1);
try expect(@round(-2.5) == -3);
}
Shell
$ zig test test_round_builtin.zig
1/1 test_round_builtin.test.@round...OK
All 1 tests passed.
Supports Floats and Vectors of floats.
@subWithOverflow
@subWithOverflow(a: anytype, b: anytype) struct { @TypeOf(a, b), u1 }
Performs a - b and returns a tuple with the result and a possible overflow bit.
@tagName
@tagName(value: anytype) [:0]const u8
Converts an enum value or union value to a string literal representing the name.
If the enum is non-exhaustive and the tag value does not map to a name, it invokes safety-checked Illegal Behavior.
@This
@This() type
Returns the innermost struct, enum, or union that this function call is inside. This can be useful for an anonymous struct that needs to refer to itself:
test_this_builtin.zig
const std = @import("std");
const expect = std.testing.expect;
test "@This()" {
var items = [_]i32{ 1, 2, 3, 4 };
const list = List(i32){ .items = items[0..] };
try expect(list.length() == 4);
}
fn List(comptime T: type) type {
return struct {
const Self = @This();
items: []T,
fn length(self: Self) usize {
return self.items.len;
}
};
}
Shell
$ zig test test_this_builtin.zig
1/1 test_this_builtin.test.@This()...OK
All 1 tests passed.
When @This() is used at file scope, it returns a reference to the struct that corresponds to the current file.
@trap
@trap() noreturn
This function inserts a platform-specific trap/jam instruction which can be used to exit the program abnormally. This may be implemented by explicitly emitting an invalid instruction which may cause an illegal instruction exception of some sort. Unlike for @breakpoint(), execution does not continue after this point.
Outside function scope, this builtin causes a compile error.
See also:
@breakpoint
@truncate
@truncate(integer: anytype) anytype
This function truncates bits from an integer type, resulting in a smaller or same-sized integer type. The return type is the inferred result type.
This function always truncates the significant bits of the integer, regardless of endianness on the target platform.
Calling @truncate on a number out of range of the destination type is well defined and working code:
test_truncate_builtin.zig
const std = @import("std");
const expect = std.testing.expect;
test "integer truncation" {
const a: u16 = 0xabcd;
const b: u8 = @truncate(a);
try expect(b == 0xcd);
}
Shell
$ zig test test_truncate_builtin.zig
1/1 test_truncate_builtin.test.integer truncation...OK
All 1 tests passed.
Use @intCast to convert numbers guaranteed to fit the destination type.
@Type
@Type(comptime info: std.builtin.Type) type
This function is the inverse of @typeInfo. It reifies type information into a type.
It is available for the following types:
type
noreturn
void
bool
Integers - The maximum bit count for an integer type is 65535.
Floats
Pointers
comptime_int
comptime_float
@TypeOf(undefined)
@TypeOf(null)
Arrays
Optionals
Error Set Type
Error Union Type
Vectors
opaque
anyframe
struct
enum
Enum Literals
union
Functions
@typeInfo
@typeInfo(comptime T: type) std.builtin.Type
Provides type reflection.
Type information of structs, unions, enums, and error sets has fields which are guaranteed to be in the same order as appearance in the source file.
Type information of structs, unions, enums, and opaques has declarations, which are also guaranteed to be in the same order as appearance in the source file.
@typeName
@typeName(T: type) *const [N:0]u8
This function returns the string representation of a type, as an array. It is equivalent to a string literal of the type name. The returned type name is fully qualified with the parent namespace included as part of the type name with a series of dots.
@TypeOf
@TypeOf(...) type
@TypeOf is a special builtin function that takes any (non-zero) number of expressions as parameters and returns the type of the result, using Peer Type Resolution.
The expressions are evaluated, however they are guaranteed to have no runtime side-effects:
test_TypeOf_builtin.zig
const std = @import("std");
const expect = std.testing.expect;
test "no runtime side effects" {
var data: i32 = 0;
const T = @TypeOf(foo(i32, &data));
try comptime expect(T == i32);
try expect(data == 0);
}
fn foo(comptime T: type, ptr: *T) T {
ptr.* += 1;
return ptr.*;
}
Shell
$ zig test test_TypeOf_builtin.zig
1/1 test_TypeOf_builtin.test.no runtime side effects...OK
All 1 tests passed.
@unionInit
@unionInit(comptime Union: type, comptime active_field_name: []const u8, init_expr) Union
This is the same thing as union initialization syntax, except that the field name is a comptime-known value rather than an identifier token.
@unionInit forwards its result location to init_expr.
@Vector
@Vector(len: comptime_int, Element: type) type
Creates Vectors.
@volatileCast
@volatileCast(value: anytype) DestType
Remove volatile qualifier from a pointer.
@workGroupId
@workGroupId(comptime dimension: u32) u32
Returns the index of the work group in the current kernel invocation in dimension dimension.
@workGroupSize
@workGroupSize(comptime dimension: u32) u32
Returns the number of work items that a work group has in dimension dimension.
@workItemId
@workItemId(comptime dimension: u32) u32
Returns the index of the work item in the work group in dimension dimension. This function returns values between 0 (inclusive) and @workGroupSize(dimension) (exclusive).
Build Mode
Zig has four build modes:
Debug (default)
ReleaseFast
ReleaseSafe
ReleaseSmall
To add standard build options to a build.zig file:
build.zig
const std = @import("std");
pub fn build(b: *std.Build) void {
const optimize = b.standardOptimizeOption(.{});
const exe = b.addExecutable(.{
.name = "example",
.root_source_file = b.path("example.zig"),
.optimize = optimize,
});
b.default_step.dependOn(&exe.step);
}
This causes these options to be available:
-Doptimize=Debug
Optimizations off and safety on (default)
-Doptimize=ReleaseSafe
Optimizations on and safety on
-Doptimize=ReleaseFast
Optimizations on and safety off
-Doptimize=ReleaseSmall
Size optimizations on and safety off
Debug
Shell
$ zig build-exe example.zig
Fast compilation speed
Safety checks enabled
Slow runtime performance
Large binary size
No reproducible build requirement
ReleaseFast
Shell
$ zig build-exe example.zig -O ReleaseFast
Fast runtime performance
Safety checks disabled
Slow compilation speed
Large binary size
Reproducible build
ReleaseSafe
Shell
$ zig build-exe example.zig -O ReleaseSafe
Medium runtime performance
Safety checks enabled
Slow compilation speed
Large binary size
Reproducible build
ReleaseSmall
Shell
$ zig build-exe example.zig -O ReleaseSmall
Medium runtime performance
Safety checks disabled
Slow compilation speed
Small binary size
Reproducible build
See also:
Compile Variables
Zig Build System
Illegal Behavior
Single Threaded Builds
Zig has a compile option -fsingle-threaded which has the following effects:
All Thread Local Variables are treated as regular Container Level Variables.
The overhead of Async Functions becomes equivalent to function call overhead.
The @import("builtin").single_threaded becomes true and therefore various userland APIs which read this variable become more efficient. For example std.Mutex becomes an empty data structure and all of its functions become no-ops.
Illegal Behavior
Many operations in Zig trigger what is known as "Illegal Behavior" (IB). If Illegal Behavior is detected at compile-time, Zig emits a compile error and refuses to continue. Otherwise, when Illegal Behavior is not caught at compile-time, it falls into one of two categories.
Some Illegal Behavior is safety-checked: this means that the compiler will insert "safety checks" anywhere that the Illegal Behavior may occur at runtime, to determine whether it is about to happen. If it is, the safety check "fails", which triggers a panic.
All other Illegal Behavior is unchecked, meaning the compiler is unable to insert safety checks for it. If Unchecked Illegal Behavior is invoked at runtime, anything can happen: usually that will be some kind of crash, but the optimizer is free to make Unchecked Illegal Behavior do anything, such as calling arbitrary functions or clobbering arbitrary data. This is similar to the concept of "undefined behavior" in some other languages. Note that Unchecked Illegal Behavior still always results in a compile error if evaluated at comptime, because the Zig compiler is able to perform more sophisticated checks at compile-time than at runtime.
Most Illegal Behavior is safety-checked. However, to facilitate optimizations, safety checks are disabled by default in the ReleaseFast and ReleaseSmall optimization modes. Safety checks can also be enabled or disabled on a per-block basis, overriding the default for the current optimization mode, using @setRuntimeSafety. When safety checks are disabled, Safety-Checked Illegal Behavior behaves like Unchecked Illegal Behavior; that is, any behavior may result from invoking it.
When a safety check fails, Zig's default panic handler crashes with a stack trace, like this:
test_illegal_behavior.zig
test "safety check" {
unreachable;
}
Shell
$ zig test test_illegal_behavior.zig
1/1 test_illegal_behavior.test.safety check...thread 3521468 panic: reached unreachable code
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_illegal_behavior.zig:2:5: 0x102d00c in test.safety check (test_illegal_behavior.zig)
unreachable;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:216:25: 0x1175d83 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/compiler/test_runner.zig:64:28: 0x116be27 in main (test_runner.zig)
return mainTerminal();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1164f5d in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x1164833 in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
error: the following test command crashed:
/home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/0664fee98116754e7caccc13c16fedf6/test --seed=0x8ab6545a
Reaching Unreachable Code
At compile-time:
test_comptime_reaching_unreachable.zig
comptime {
assert(false);
}
fn assert(ok: bool) void {
if (!ok) unreachable; // assertion failure
}
Shell
$ zig test test_comptime_reaching_unreachable.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_reaching_unreachable.zig:5:14: error: reached unreachable code
if (!ok) unreachable; // assertion failure
^~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_reaching_unreachable.zig:2:11: note: called at comptime here
assert(false);
~~~~~~^~~~~~~
At runtime:
runtime_reaching_unreachable.zig
const std = @import("std");
pub fn main() void {
std.debug.assert(false);
}
Shell
$ zig build-exe runtime_reaching_unreachable.zig
$ ./runtime_reaching_unreachable
thread 3518357 panic: reached unreachable code
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/debug.zig:548:14: 0x10307c9 in assert (std.zig)
if (!ok) unreachable; // assertion failure
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_reaching_unreachable.zig:4:21: 0x1153d11 in main (runtime_reaching_unreachable.zig)
std.debug.assert(false);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Index out of Bounds
At compile-time:
test_comptime_index_out_of_bounds.zig
comptime {
const array: [5]u8 = "hello".*;
const garbage = array[5];
_ = garbage;
}
Shell
$ zig test test_comptime_index_out_of_bounds.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_index_out_of_bounds.zig:3:27: error: index 5 outside array of length 5
const garbage = array[5];
^
At runtime:
runtime_index_out_of_bounds.zig
pub fn main() void {
const x = foo("hello");
_ = x;
}
fn foo(x: []const u8) u8 {
return x[5];
}
Shell
$ zig build-exe runtime_index_out_of_bounds.zig
$ ./runtime_index_out_of_bounds
thread 3521671 panic: index out of bounds: index 5, len 5
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_index_out_of_bounds.zig:7:13: 0x1154f41 in foo (runtime_index_out_of_bounds.zig)
return x[5];
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_index_out_of_bounds.zig:2:18: 0x1153d1d in main (runtime_index_out_of_bounds.zig)
const x = foo("hello");
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Cast Negative Number to Unsigned Integer
At compile-time:
test_comptime_invalid_cast.zig
comptime {
const value: i32 = -1;
const unsigned: u32 = @intCast(value);
_ = unsigned;
}
Shell
$ zig test test_comptime_invalid_cast.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_invalid_cast.zig:3:36: error: type 'u32' cannot represent integer value '-1'
const unsigned: u32 = @intCast(value);
^~~~~
At runtime:
runtime_invalid_cast.zig
const std = @import("std");
pub fn main() void {
var value: i32 = -1; // runtime-known
_ = &value;
const unsigned: u32 = @intCast(value);
std.debug.print("value: {}\n", .{unsigned});
}
Shell
$ zig build-exe runtime_invalid_cast.zig
$ ./runtime_invalid_cast
thread 3521135 panic: integer does not fit in destination type
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_invalid_cast.zig:6:27: 0x1153d22 in main (runtime_invalid_cast.zig)
const unsigned: u32 = @intCast(value);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
To obtain the maximum value of an unsigned integer, use std.math.maxInt.
Cast Truncates Data
At compile-time:
test_comptime_invalid_cast_truncate.zig
comptime {
const spartan_count: u16 = 300;
const byte: u8 = @intCast(spartan_count);
_ = byte;
}
Shell
$ zig test test_comptime_invalid_cast_truncate.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_invalid_cast_truncate.zig:3:31: error: type 'u8' cannot represent integer value '300'
const byte: u8 = @intCast(spartan_count);
^~~~~~~~~~~~~
At runtime:
runtime_invalid_cast_truncate.zig
const std = @import("std");
pub fn main() void {
var spartan_count: u16 = 300; // runtime-known
_ = &spartan_count;
const byte: u8 = @intCast(spartan_count);
std.debug.print("value: {}\n", .{byte});
}
Shell
$ zig build-exe runtime_invalid_cast_truncate.zig
$ ./runtime_invalid_cast_truncate
thread 3518251 panic: integer does not fit in destination type
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_invalid_cast_truncate.zig:6:22: 0x1153d23 in main (runtime_invalid_cast_truncate.zig)
const byte: u8 = @intCast(spartan_count);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
To truncate bits, use @truncate.
Integer Overflow
Default Operations
The following operators can cause integer overflow:
+ (addition)
- (subtraction)
- (negation)
* (multiplication)
/ (division)
@divTrunc (division)
@divFloor (division)
@divExact (division)
Example with addition at compile-time:
test_comptime_overflow.zig
comptime {
var byte: u8 = 255;
byte += 1;
}
Shell
$ zig test test_comptime_overflow.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_overflow.zig:3:10: error: overflow of integer type 'u8' with value '256'
byte += 1;
~~~~~^~~~
At runtime:
runtime_overflow.zig
const std = @import("std");
pub fn main() void {
var byte: u8 = 255;
byte += 1;
std.debug.print("value: {}\n", .{byte});
}
Shell
$ zig build-exe runtime_overflow.zig
$ ./runtime_overflow
thread 3520992 panic: integer overflow
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_overflow.zig:5:10: 0x1153d38 in main (runtime_overflow.zig)
byte += 1;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Standard Library Math Functions
These functions provided by the standard library return possible errors.
@import("std").math.add
@import("std").math.sub
@import("std").math.mul
@import("std").math.divTrunc
@import("std").math.divFloor
@import("std").math.divExact
@import("std").math.shl
Example of catching an overflow for addition:
math_add.zig
const math = @import("std").math;
const print = @import("std").debug.print;
pub fn main() !void {
var byte: u8 = 255;
byte = if (math.add(u8, byte, 1)) |result| result else |err| {
print("unable to add one: {s}\n", .{@errorName(err)});
return err;
};
print("result: {}\n", .{byte});
}
Shell
$ zig build-exe math_add.zig
$ ./math_add
unable to add one: Overflow
error: Overflow
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/math.zig:568:21: 0x1154048 in add__anon_23202 (std.zig)
if (ov[1] != 0) return error.Overflow;
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/math_add.zig:8:9: 0x1152905 in main (math_add.zig)
return err;
^
Builtin Overflow Functions
These builtins return a tuple containing whether there was an overflow (as a u1) and the possibly overflowed bits of the operation:
@addWithOverflow
@subWithOverflow
@mulWithOverflow
@shlWithOverflow
Example of @addWithOverflow:
addWithOverflow_builtin.zig
const print = @import("std").debug.print;
pub fn main() void {
const byte: u8 = 255;
const ov = @addWithOverflow(byte, 10);
if (ov[1] != 0) {
print("overflowed result: {}\n", .{ov[0]});
} else {
print("result: {}\n", .{ov[0]});
}
}
Shell
$ zig build-exe addWithOverflow_builtin.zig
$ ./addWithOverflow_builtin
overflowed result: 9
Wrapping Operations
These operations have guaranteed wraparound semantics.
+% (wraparound addition)
-% (wraparound subtraction)
-% (wraparound negation)
*% (wraparound multiplication)
test_wraparound_semantics.zig
const std = @import("std");
const expect = std.testing.expect;
const minInt = std.math.minInt;
const maxInt = std.math.maxInt;
test "wraparound addition and subtraction" {
const x: i32 = maxInt(i32);
const min_val = x +% 1;
try expect(min_val == minInt(i32));
const max_val = min_val -% 1;
try expect(max_val == maxInt(i32));
}
Shell
$ zig test test_wraparound_semantics.zig
1/1 test_wraparound_semantics.test.wraparound addition and subtraction...OK
All 1 tests passed.
Exact Left Shift Overflow
At compile-time:
test_comptime_shlExact_overwlow.zig
comptime {
const x = @shlExact(@as(u8, 0b01010101), 2);
_ = x;
}
Shell
$ zig test test_comptime_shlExact_overwlow.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_shlExact_overwlow.zig:2:15: error: operation caused overflow
const x = @shlExact(@as(u8, 0b01010101), 2);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At runtime:
runtime_shlExact_overflow.zig
const std = @import("std");
pub fn main() void {
var x: u8 = 0b01010101; // runtime-known
_ = &x;
const y = @shlExact(x, 2);
std.debug.print("value: {}\n", .{y});
}
Shell
$ zig build-exe runtime_shlExact_overflow.zig
$ ./runtime_shlExact_overflow
thread 3520402 panic: left shift overflowed bits
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_shlExact_overflow.zig:6:5: 0x1153d44 in main (runtime_shlExact_overflow.zig)
const y = @shlExact(x, 2);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Exact Right Shift Overflow
At compile-time:
test_comptime_shrExact_overflow.zig
comptime {
const x = @shrExact(@as(u8, 0b10101010), 2);
_ = x;
}
Shell
$ zig test test_comptime_shrExact_overflow.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_shrExact_overflow.zig:2:15: error: exact shift shifted out 1 bits
const x = @shrExact(@as(u8, 0b10101010), 2);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At runtime:
runtime_shrExact_overflow.zig
const std = @import("std");
pub fn main() void {
var x: u8 = 0b10101010; // runtime-known
_ = &x;
const y = @shrExact(x, 2);
std.debug.print("value: {}\n", .{y});
}
Shell
$ zig build-exe runtime_shrExact_overflow.zig
$ ./runtime_shrExact_overflow
thread 3521133 panic: right shift overflowed bits
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_shrExact_overflow.zig:6:5: 0x1153d2d in main (runtime_shrExact_overflow.zig)
const y = @shrExact(x, 2);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Division by Zero
At compile-time:
test_comptime_division_by_zero.zig
comptime {
const a: i32 = 1;
const b: i32 = 0;
const c = a / b;
_ = c;
}
Shell
$ zig test test_comptime_division_by_zero.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_division_by_zero.zig:4:19: error: division by zero here causes illegal behavior
const c = a / b;
^
At runtime:
runtime_division_by_zero.zig
const std = @import("std");
pub fn main() void {
var a: u32 = 1;
var b: u32 = 0;
_ = .{ &a, &b };
const c = a / b;
std.debug.print("value: {}\n", .{c});
}
Shell
$ zig build-exe runtime_division_by_zero.zig
$ ./runtime_division_by_zero
thread 3518297 panic: division by zero
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_division_by_zero.zig:7:17: 0x1153d33 in main (runtime_division_by_zero.zig)
const c = a / b;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Remainder Division by Zero
At compile-time:
test_comptime_remainder_division_by_zero.zig
comptime {
const a: i32 = 10;
const b: i32 = 0;
const c = a % b;
_ = c;
}
Shell
$ zig test test_comptime_remainder_division_by_zero.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_remainder_division_by_zero.zig:4:19: error: division by zero here causes illegal behavior
const c = a % b;
^
At runtime:
runtime_remainder_division_by_zero.zig
const std = @import("std");
pub fn main() void {
var a: u32 = 10;
var b: u32 = 0;
_ = .{ &a, &b };
const c = a % b;
std.debug.print("value: {}\n", .{c});
}
Shell
$ zig build-exe runtime_remainder_division_by_zero.zig
$ ./runtime_remainder_division_by_zero
thread 3521949 panic: division by zero
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_remainder_division_by_zero.zig:7:17: 0x1153d33 in main (runtime_remainder_division_by_zero.zig)
const c = a % b;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Exact Division Remainder
At compile-time:
test_comptime_divExact_remainder.zig
comptime {
const a: u32 = 10;
const b: u32 = 3;
const c = @divExact(a, b);
_ = c;
}
Shell
$ zig test test_comptime_divExact_remainder.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_divExact_remainder.zig:4:15: error: exact division produced remainder
const c = @divExact(a, b);
^~~~~~~~~~~~~~~
At runtime:
runtime_divExact_remainder.zig
const std = @import("std");
pub fn main() void {
var a: u32 = 10;
var b: u32 = 3;
_ = .{ &a, &b };
const c = @divExact(a, b);
std.debug.print("value: {}\n", .{c});
}
Shell
$ zig build-exe runtime_divExact_remainder.zig
$ ./runtime_divExact_remainder
thread 3521134 panic: exact division produced remainder
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_divExact_remainder.zig:7:15: 0x1153d6a in main (runtime_divExact_remainder.zig)
const c = @divExact(a, b);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Attempt to Unwrap Null
At compile-time:
test_comptime_unwrap_null.zig
comptime {
const optional_number: ?i32 = null;
const number = optional_number.?;
_ = number;
}
Shell
$ zig test test_comptime_unwrap_null.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_unwrap_null.zig:3:35: error: unable to unwrap null
const number = optional_number.?;
~~~~~~~~~~~~~~~^~
At runtime:
runtime_unwrap_null.zig
const std = @import("std");
pub fn main() void {
var optional_number: ?i32 = null;
_ = &optional_number;
const number = optional_number.?;
std.debug.print("value: {}\n", .{number});
}
Shell
$ zig build-exe runtime_unwrap_null.zig
$ ./runtime_unwrap_null
thread 3518111 panic: attempt to use null value
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_unwrap_null.zig:6:35: 0x1153d57 in main (runtime_unwrap_null.zig)
const number = optional_number.?;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
One way to avoid this crash is to test for null instead of assuming non-null, with the if expression:
testing_null_with_if.zig
const print = @import("std").debug.print;
pub fn main() void {
const optional_number: ?i32 = null;
if (optional_number) |number| {
print("got number: {}\n", .{number});
} else {
print("it's null\n", .{});
}
}
Shell
$ zig build-exe testing_null_with_if.zig
$ ./testing_null_with_if
it's null
See also:
Optionals
Attempt to Unwrap Error
At compile-time:
test_comptime_unwrap_error.zig
comptime {
const number = getNumberOrFail() catch unreachable;
_ = number;
}
fn getNumberOrFail() !i32 {
return error.UnableToReturnNumber;
}
Shell
$ zig test test_comptime_unwrap_error.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_unwrap_error.zig:2:44: error: caught unexpected error 'UnableToReturnNumber'
const number = getNumberOrFail() catch unreachable;
^~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_unwrap_error.zig:7:18: note: error returned here
return error.UnableToReturnNumber;
^~~~~~~~~~~~~~~~~~~~
At runtime:
runtime_unwrap_error.zig
const std = @import("std");
pub fn main() void {
const number = getNumberOrFail() catch unreachable;
std.debug.print("value: {}\n", .{number});
}
fn getNumberOrFail() !i32 {
return error.UnableToReturnNumber;
}
Shell
$ zig build-exe runtime_unwrap_error.zig
$ ./runtime_unwrap_error
thread 3519250 panic: attempt to unwrap error: UnableToReturnNumber
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_unwrap_error.zig:9:5: 0x1154d0f in getNumberOrFail (runtime_unwrap_error.zig)
return error.UnableToReturnNumber;
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_unwrap_error.zig:4:44: 0x1154d68 in main (runtime_unwrap_error.zig)
const number = getNumberOrFail() catch unreachable;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1153f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115383a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
One way to avoid this crash is to test for an error instead of assuming a successful result, with the if expression:
testing_error_with_if.zig
const print = @import("std").debug.print;
pub fn main() void {
const result = getNumberOrFail();
if (result) |number| {
print("got number: {}\n", .{number});
} else |err| {
print("got error: {s}\n", .{@errorName(err)});
}
}
fn getNumberOrFail() !i32 {
return error.UnableToReturnNumber;
}
Shell
$ zig build-exe testing_error_with_if.zig
$ ./testing_error_with_if
got error: UnableToReturnNumber
See also:
Errors
Invalid Error Code
At compile-time:
test_comptime_invalid_error_code.zig
comptime {
const err = error.AnError;
const number = @intFromError(err) + 10;
const invalid_err = @errorFromInt(number);
_ = invalid_err;
}
Shell
$ zig test test_comptime_invalid_error_code.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_invalid_error_code.zig:4:39: error: integer value '11' represents no error
const invalid_err = @errorFromInt(number);
^~~~~~
At runtime:
runtime_invalid_error_code.zig
const std = @import("std");
pub fn main() void {
const err = error.AnError;
var number = @intFromError(err) + 500;
_ = &number;
const invalid_err = @errorFromInt(number);
std.debug.print("value: {}\n", .{invalid_err});
}
Shell
$ zig build-exe runtime_invalid_error_code.zig
$ ./runtime_invalid_error_code
thread 3520498 panic: invalid error code
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_invalid_error_code.zig:7:5: 0x1153d4a in main (runtime_invalid_error_code.zig)
const invalid_err = @errorFromInt(number);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Invalid Enum Cast
At compile-time:
test_comptime_invalid_enum_cast.zig
const Foo = enum {
a,
b,
c,
};
comptime {
const a: u2 = 3;
const b: Foo = @enumFromInt(a);
_ = b;
}
Shell
$ zig test test_comptime_invalid_enum_cast.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_invalid_enum_cast.zig:8:20: error: enum 'test_comptime_invalid_enum_cast.Foo' has no tag with value '3'
const b: Foo = @enumFromInt(a);
^~~~~~~~~~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_invalid_enum_cast.zig:1:13: note: enum declared here
const Foo = enum {
^~~~
At runtime:
runtime_invalid_enum_cast.zig
const std = @import("std");
const Foo = enum {
a,
b,
c,
};
pub fn main() void {
var a: u2 = 3;
_ = &a;
const b: Foo = @enumFromInt(a);
std.debug.print("value: {s}\n", .{@tagName(b)});
}
Shell
$ zig build-exe runtime_invalid_enum_cast.zig
$ ./runtime_invalid_enum_cast
thread 3519406 panic: invalid enum value
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_invalid_enum_cast.zig:12:20: 0x1153d94 in main (runtime_invalid_enum_cast.zig)
const b: Foo = @enumFromInt(a);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Invalid Error Set Cast
At compile-time:
test_comptime_invalid_error_set_cast.zig
const Set1 = error{
A,
B,
};
const Set2 = error{
A,
C,
};
comptime {
_ = @as(Set2, @errorCast(Set1.B));
}
Shell
$ zig test test_comptime_invalid_error_set_cast.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_invalid_error_set_cast.zig:10:19: error: 'error.B' not a member of error set 'error{A,C}'
_ = @as(Set2, @errorCast(Set1.B));
^~~~~~~~~~~~~~~~~~
At runtime:
runtime_invalid_error_set_cast.zig
const std = @import("std");
const Set1 = error{
A,
B,
};
const Set2 = error{
A,
C,
};
pub fn main() void {
foo(Set1.B);
}
fn foo(set1: Set1) void {
const x: Set2 = @errorCast(set1);
std.debug.print("value: {}\n", .{x});
}
Shell
$ zig build-exe runtime_invalid_error_set_cast.zig
$ ./runtime_invalid_error_set_cast
thread 3519699 panic: invalid error code
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_invalid_error_set_cast.zig:15:21: 0x1155f9a in foo (runtime_invalid_error_set_cast.zig)
const x: Set2 = @errorCast(set1);
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_invalid_error_set_cast.zig:12:8: 0x1154d1a in main (runtime_invalid_error_set_cast.zig)
foo(Set1.B);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1153f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115383a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Incorrect Pointer Alignment
At compile-time:
test_comptime_incorrect_pointer_alignment.zig
comptime {
const ptr: *align(1) i32 = @ptrFromInt(0x1);
const aligned: *align(4) i32 = @alignCast(ptr);
_ = aligned;
}
Shell
$ zig test test_comptime_incorrect_pointer_alignment.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_incorrect_pointer_alignment.zig:3:47: error: pointer address 0x1 is not aligned to 4 bytes
const aligned: *align(4) i32 = @alignCast(ptr);
^~~
At runtime:
runtime_incorrect_pointer_alignment.zig
const mem = @import("std").mem;
pub fn main() !void {
var array align(4) = [_]u32{ 0x11111111, 0x11111111 };
const bytes = mem.sliceAsBytes(array[0..]);
if (foo(bytes) != 0x11111111) return error.Wrong;
}
fn foo(bytes: []u8) u32 {
const slice4 = bytes[1..5];
const int_slice = mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
return int_slice[0];
}
Shell
$ zig build-exe runtime_incorrect_pointer_alignment.zig
$ ./runtime_incorrect_pointer_alignment
thread 3519173 panic: incorrect alignment
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_incorrect_pointer_alignment.zig:9:64: 0x1154092 in foo (runtime_incorrect_pointer_alignment.zig)
const int_slice = mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_incorrect_pointer_alignment.zig:5:12: 0x11528d5 in main (runtime_incorrect_pointer_alignment.zig)
if (foo(bytes) != 0x11111111) return error.Wrong;
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:675:37: 0x1153065 in posixCallMainAndExit (std.zig)
const result = root.main() catch |err| {
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Wrong Union Field Access
At compile-time:
test_comptime_wrong_union_field_access.zig
comptime {
var f = Foo{ .int = 42 };
f.float = 12.34;
}
const Foo = union {
float: f32,
int: u32,
};
Shell
$ zig test test_comptime_wrong_union_field_access.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_wrong_union_field_access.zig:3:6: error: access of union field 'float' while field 'int' is active
f.float = 12.34;
~^~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_wrong_union_field_access.zig:6:13: note: union declared here
const Foo = union {
^~~~~
At runtime:
runtime_wrong_union_field_access.zig
const std = @import("std");
const Foo = union {
float: f32,
int: u32,
};
pub fn main() void {
var f = Foo{ .int = 42 };
bar(&f);
}
fn bar(f: *Foo) void {
f.float = 12.34;
std.debug.print("value: {}\n", .{f.float});
}
Shell
$ zig build-exe runtime_wrong_union_field_access.zig
$ ./runtime_wrong_union_field_access
thread 3520106 panic: access of union field 'float' while field 'int' is active
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_wrong_union_field_access.zig:14:6: 0x1155f77 in bar (runtime_wrong_union_field_access.zig)
f.float = 12.34;
^
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_wrong_union_field_access.zig:10:8: 0x1154d42 in main (runtime_wrong_union_field_access.zig)
bar(&f);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1153f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115383a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
This safety is not available for extern or packed unions.
To change the active field of a union, assign the entire union, like this:
change_active_union_field.zig
const std = @import("std");
const Foo = union {
float: f32,
int: u32,
};
pub fn main() void {
var f = Foo{ .int = 42 };
bar(&f);
}
fn bar(f: *Foo) void {
f.* = Foo{ .float = 12.34 };
std.debug.print("value: {}\n", .{f.float});
}
Shell
$ zig build-exe change_active_union_field.zig
$ ./change_active_union_field
value: 1.234e1
To change the active field of a union when a meaningful value for the field is not known, use undefined, like this:
undefined_active_union_field.zig
const std = @import("std");
const Foo = union {
float: f32,
int: u32,
};
pub fn main() void {
var f = Foo{ .int = 42 };
f = Foo{ .float = undefined };
bar(&f);
std.debug.print("value: {}\n", .{f.float});
}
fn bar(f: *Foo) void {
f.float = 12.34;
}
Shell
$ zig build-exe undefined_active_union_field.zig
$ ./undefined_active_union_field
value: 1.234e1
See also:
union
extern union
Out of Bounds Float to Integer Cast
This happens when casting a float to an integer where the float has a value outside the integer type's range.
At compile-time:
test_comptime_out_of_bounds_float_to_integer_cast.zig
comptime {
const float: f32 = 4294967296;
const int: i32 = @intFromFloat(float);
_ = int;
}
Shell
$ zig test test_comptime_out_of_bounds_float_to_integer_cast.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_out_of_bounds_float_to_integer_cast.zig:3:36: error: float value '4294967296' cannot be stored in integer type 'i32'
const int: i32 = @intFromFloat(float);
^~~~~
At runtime:
runtime_out_of_bounds_float_to_integer_cast.zig
pub fn main() void {
var float: f32 = 4294967296; // runtime-known
_ = &float;
const int: i32 = @intFromFloat(float);
_ = int;
}
Shell
$ zig build-exe runtime_out_of_bounds_float_to_integer_cast.zig
$ ./runtime_out_of_bounds_float_to_integer_cast
thread 3518374 panic: integer part of floating point value out of bounds
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_out_of_bounds_float_to_integer_cast.zig:4:22: 0x1153d8b in main (runtime_out_of_bounds_float_to_integer_cast.zig)
const int: i32 = @intFromFloat(float);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Pointer Cast Invalid Null
This happens when casting a pointer with the address 0 to a pointer which may not have the address 0. For example, C Pointers, Optional Pointers, and allowzero pointers allow address zero, but normal Pointers do not.
At compile-time:
test_comptime_invalid_null_pointer_cast.zig
comptime {
const opt_ptr: ?*i32 = null;
const ptr: *i32 = @ptrCast(opt_ptr);
_ = ptr;
}
Shell
$ zig test test_comptime_invalid_null_pointer_cast.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_comptime_invalid_null_pointer_cast.zig:3:32: error: null pointer casted to type '*i32'
const ptr: *i32 = @ptrCast(opt_ptr);
^~~~~~~
At runtime:
runtime_invalid_null_pointer_cast.zig
pub fn main() void {
var opt_ptr: ?*i32 = null;
_ = &opt_ptr;
const ptr: *i32 = @ptrCast(opt_ptr);
_ = ptr;
}
Shell
$ zig build-exe runtime_invalid_null_pointer_cast.zig
$ ./runtime_invalid_null_pointer_cast
thread 3522288 panic: cast causes pointer to be null
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/runtime_invalid_null_pointer_cast.zig:4:23: 0x1153d2d in main (runtime_invalid_null_pointer_cast.zig)
const ptr: *i32 = @ptrCast(opt_ptr);
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:666:22: 0x1152f64 in posixCallMainAndExit (std.zig)
root.main();
^
/home/ci/actions-runner/_work/zig-bootstrap/out/host/lib/zig/std/start.zig:286:5: 0x115283a in _start (std.zig)
asm volatile (switch (native_arch) {
^
???:?:?: 0x0 in ??? (???)
(process terminated by signal)
Memory
The Zig language performs no memory management on behalf of the programmer. This is why Zig has no runtime, and why Zig code works seamlessly in so many environments, including real-time software, operating system kernels, embedded devices, and low latency servers. As a consequence, Zig programmers must always be able to answer the question:
Where are the bytes?
Like Zig, the C programming language has manual memory management. However, unlike Zig, C has a default allocator - malloc, realloc, and free. When linking against libc, Zig exposes this allocator with std.heap.c_allocator. However, by convention, there is no default allocator in Zig. Instead, functions which need to allocate accept an Allocator parameter. Likewise, data structures such as std.ArrayList accept an Allocator parameter in their initialization functions:
test_allocator.zig
const std = @import("std");
const Allocator = std.mem.Allocator;
const expect = std.testing.expect;
test "using an allocator" {
var buffer: [100]u8 = undefined;
var fba = std.heap.FixedBufferAllocator.init(&buffer);
const allocator = fba.allocator();
const result = try concat(allocator, "foo", "bar");
try expect(std.mem.eql(u8, "foobar", result));
}
fn concat(allocator: Allocator, a: []const u8, b: []const u8) ![]u8 {
const result = try allocator.alloc(u8, a.len + b.len);
@memcpy(result[0..a.len], a);
@memcpy(result[a.len..], b);
return result;
}
Shell
$ zig test test_allocator.zig
1/1 test_allocator.test.using an allocator...OK
All 1 tests passed.
In the above example, 100 bytes of stack memory are used to initialize a FixedBufferAllocator, which is then passed to a function. As a convenience there is a global FixedBufferAllocator available for quick tests at std.testing.allocator, which will also perform basic leak detection.
Zig has a general purpose allocator available to be imported with std.heap.GeneralPurposeAllocator. However, it is still recommended to follow the Choosing an Allocator guide.
Choosing an Allocator
What allocator to use depends on a number of factors. Here is a flow chart to help you decide:
Are you making a library? In this case, best to accept an Allocator as a parameter and allow your library's users to decide what allocator to use.
Are you linking libc? In this case, std.heap.c_allocator is likely the right choice, at least for your main allocator.
Need to use the same allocator in multiple threads? Use one of your choice wrapped around std.heap.ThreadSafeAllocator
Is the maximum number of bytes that you will need bounded by a number known at comptime? In this case, use std.heap.FixedBufferAllocator.
Is your program a command line application which runs from start to end without any fundamental cyclical pattern (such as a video game main loop, or a web server request handler), such that it would make sense to free everything at once at the end? In this case, it is recommended to follow this pattern:
cli_allocation.zig
const std = @import("std");
pub fn main() !void {
var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
defer arena.deinit();
const allocator = arena.allocator();
const ptr = try allocator.create(i32);
std.debug.print("ptr={*}\n", .{ptr});
}
Shell
$ zig build-exe cli_allocation.zig
$ ./cli_allocation
ptr=i32@7f0e1b319010
When using this kind of allocator, there is no need to free anything manually. Everything gets freed at once with the call to arena.deinit().
Are the allocations part of a cyclical pattern such as a video game main loop, or a web server request handler? If the allocations can all be freed at once, at the end of the cycle, for example once the video game frame has been fully rendered, or the web server request has been served, then std.heap.ArenaAllocator is a great candidate. As demonstrated in the previous bullet point, this allows you to free entire arenas at once. Note also that if an upper bound of memory can be established, then std.heap.FixedBufferAllocator can be used as a further optimization.
Are you writing a test, and you want to make sure error.OutOfMemory is handled correctly? In this case, use std.testing.FailingAllocator.
Are you writing a test? In this case, use std.testing.allocator.
Finally, if none of the above apply, you need a general purpose allocator. Zig's general purpose allocator is available as a function that takes a comptime struct of configuration options and returns a type. Generally, you will set up one std.heap.GeneralPurposeAllocator in your main function, and then pass it or sub-allocators around to various parts of your application.
You can also consider Implementing an Allocator.
Where are the bytes?
String literals such as "hello" are in the global constant data section. This is why it is an error to pass a string literal to a mutable slice, like this:
test_string_literal_to_slice.zig
fn foo(s: []u8) void {
_ = s;
}
test "string literal to mutable slice" {
foo("hello");
}
Shell
$ zig test test_string_literal_to_slice.zig
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_string_literal_to_slice.zig:6:9: error: expected type '[]u8', found '*const [5:0]u8'
foo("hello");
^~~~~~~
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_string_literal_to_slice.zig:6:9: note: cast discards const qualifier
/home/ci/actions-runner/_work/zig-bootstrap/zig/doc/langref/test_string_literal_to_slice.zig:1:11: note: parameter type declared here
fn foo(s: []u8) void {
^~~~
However if you make the slice constant, then it works:
test_string_literal_to_const_slice.zig
fn foo(s: []const u8) void {
_ = s;
}
test "string literal to constant slice" {
foo("hello");
}
Shell
$ zig test test_string_literal_to_const_slice.zig
1/1 test_string_literal_to_const_slice.test.string literal to constant slice...OK
All 1 tests passed.
Just like string literals, const declarations, when the value is known at comptime, are stored in the global constant data section. Also Compile Time Variables are stored in the global constant data section.
var declarations inside functions are stored in the function's stack frame. Once a function returns, any Pointers to variables in the function's stack frame become invalid references, and dereferencing them becomes unchecked Illegal Behavior.
var declarations at the top level or in struct declarations are stored in the global data section.
The location of memory allocated with allocator.alloc or allocator.create is determined by the allocator's implementation.
TODO: thread local variables
Implementing an Allocator
Zig programmers can implement their own allocators by fulfilling the Allocator interface. In order to do this one must read carefully the documentation comments in std/mem.zig and then supply a allocFn and a resizeFn.
There are many example allocators to look at for inspiration. Look at std/heap.zig and std.heap.GeneralPurposeAllocator.
Heap Allocation Failure
Many programming languages choose to handle the possibility of heap allocation failure by unconditionally crashing. By convention, Zig programmers do not consider this to be a satisfactory solution. Instead, error.OutOfMemory represents heap allocation failure, and Zig libraries return this error code whenever heap allocation failure prevented an operation from completing successfully.
Some have argued that because some operating systems such as Linux have memory overcommit enabled by default, it is pointless to handle heap allocation failure. There are many problems with this reasoning:
Only some operating systems have an overcommit feature.
Linux has it enabled by default, but it is configurable.
Windows does not overcommit.
Embedded systems do not have overcommit.
Hobby operating systems may or may not have overcommit.
For real-time systems, not only is there no overcommit, but typically the maximum amount of memory per application is determined ahead of time.
When writing a library, one of the main goals is code reuse. By making code handle allocation failure correctly, a library becomes eligible to be reused in more contexts.
Although some software has grown to depend on overcommit being enabled, its existence is the source of countless user experience disasters. When a system with overcommit enabled, such as Linux on default settings, comes close to memory exhaustion, the system locks up and becomes unusable. At this point, the OOM Killer selects an application to kill based on heuristics. This non-deterministic decision often results in an important process being killed, and often fails to return the system back to working order.
Recursion
Recursion is a fundamental tool in modeling software. However it has an often-overlooked problem: unbounded memory allocation.
Recursion is an area of active experimentation in Zig and so the documentation here is not final. You can read a summary of recursion status in the 0.3.0 release notes.
The short summary is that currently recursion works normally as you would expect. Although Zig code is not yet protected from stack overflow, it is planned that a future version of Zig will provide such protection, with some degree of cooperation from Zig code required.
Lifetime and Ownership
It is the Zig programmer's responsibility to ensure that a pointer is not accessed when the memory pointed to is no longer available. Note that a slice is a form of pointer, in that it references other memory.
In order to prevent bugs, there are some helpful conventions to follow when dealing with pointers. In general, when a function returns a pointer, the documentation for the function should explain who "owns" the pointer. This concept helps the programmer decide when it is appropriate, if ever, to free the pointer.
For example, the function's documentation may say "caller owns the returned memory", in which case the code that calls the function must have a plan for when to free that memory. Probably in this situation, the function will accept an Allocator parameter.
Sometimes the lifetime of a pointer may be more complicated. For example, the std.ArrayList(T).items slice has a lifetime that remains valid until the next time the list is resized, such as by appending new elements.
The API documentation for functions and data structures should take great care to explain the ownership and lifetime semantics of pointers. Ownership determines whose responsibility it is to free the memory referenced by the pointer, and lifetime determines the point at which the memory becomes inaccessible (lest Illegal Behavior occur).
Compile Variables
Compile variables are accessible by importing the "builtin" package, which the compiler makes available to every Zig source file. It contains compile-time constants such as the current target, endianness, and release mode.
compile_variables.zig
const builtin = @import("builtin");
const separator = if (builtin.os.tag == .windows) '\\' else '/';
Example of what is imported with @import("builtin"):
@import("builtin")
const std = @import("std");
/// Zig version. When writing code that supports multiple versions of Zig, prefer
/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
pub const zig_version = std.SemanticVersion.parse(zig_version_string) catch unreachable;
pub const zig_version_string = "0.15.0-dev.764+2e3154428";
pub const zig_backend = std.builtin.CompilerBackend.stage2_x86_64;
pub const output_mode: std.builtin.OutputMode = .Exe;
pub const link_mode: std.builtin.LinkMode = .static;
pub const unwind_tables: std.builtin.UnwindTables = .@"async";
pub const is_test = false;
pub const single_threaded = false;
pub const abi: std.Target.Abi = .gnu;
pub const cpu: std.Target.Cpu = .{
.arch = .x86_64,
.model = &std.Target.x86.cpu.znver2,
.features = std.Target.x86.featureSet(&.{
.@"64bit",
.adx,
.aes,
.allow_light_256_bit,
.avx,
.avx2,
.bmi,
.bmi2,
.branchfusion,
.clflushopt,
.clwb,
.clzero,
.cmov,
.crc32,
.cx16,
.cx8,
.f16c,
.fast_15bytenop,
.fast_bextr,
.fast_imm16,
.fast_lzcnt,
.fast_movbe,
.fast_scalar_fsqrt,
.fast_scalar_shift_masks,
.fast_variable_perlane_shuffle,
.fast_vector_fsqrt,
.fma,
.fsgsbase,
.fxsr,
.idivq_to_divl,
.lzcnt,
.mmx,
.movbe,
.mwaitx,
.nopl,
.pclmul,
.popcnt,
.prfchw,
.rdpid,
.rdpru,
.rdrnd,
.rdseed,
.sahf,
.sbb_dep_breaking,
.sha,
.slow_shld,
.smap,
.smep,
.sse,
.sse2,
.sse3,
.sse4_1,
.sse4_2,
.sse4a,
.ssse3,
.vzeroupper,
.wbnoinvd,
.x87,
.xsave,
.xsavec,
.xsaveopt,
.xsaves,
}),
};
pub const os: std.Target.Os = .{
.tag = .linux,
.version_range = .{ .linux = .{
.range = .{
.min = .{
.major = 5,
.minor = 10,
.patch = 0,
},
.max = .{
.major = 5,
.minor = 10,
.patch = 0,
},
},
.glibc = .{
.major = 2,
.minor = 31,
.patch = 0,
},
.android = 24,
}},
};
pub const target: std.Target = .{
.cpu = cpu,
.os = os,
.abi = abi,
.ofmt = object_format,
.dynamic_linker = .init("/lib64/ld-linux-x86-64.so.2"),
};
pub const object_format: std.Target.ObjectFormat = .elf;
pub const mode: std.builtin.OptimizeMode = .Debug;
pub const link_libc = false;
pub const link_libcpp = false;
pub const have_error_return_tracing = true;
pub const valgrind_support = true;
pub const sanitize_thread = false;
pub const fuzz = false;
pub const position_independent_code = false;
pub const position_independent_executable = false;
pub const strip_debug_info = false;
pub const code_model: std.builtin.CodeModel = .default;
pub const omit_frame_pointer = false;
See also:
Build Mode
Compilation Model
A Zig compilation is separated into modules. Each module is a collection of Zig source files, one of which is the module's root source file. Each module can depend on any number of other modules, forming a directed graph (dependency loops between modules are allowed). If module A depends on module B, then any Zig source file in module A can import the root source file of module B using @import with the module's name. In essence, a module acts as an alias to import a Zig source file (which might exist in a completely separate part of the filesystem).
A simple Zig program compiled with zig build-exe has two key modules: the one containing your code, known as the "main" or "root" module, and the standard library. Your module depends on the standard library module under the name "std", which is what allows you to write @import("std")! In fact, every single module in a Zig compilation — including the standard library itself — implicitly depends on the standard library module under the name "std".
The "root module" (the one provided by you in the zig build-exe example) has a special property. Like the standard library, it is implicitly made available to all modules (including itself), this time under the name "root". So, @import("root") will always be equivalent to @import of your "main" source file (often, but not necessarily, named main.zig).
Source File Structs
Every Zig source file is implicitly a struct declaration; you can imagine that the file's contents are literally surrounded by struct { ... }. This means that as well as declarations, the top level of a file is permitted to contain fields:
TopLevelFields.zig
//! Because this file contains fields, it is a type which is intended to be instantiated, and so
//! is named in TitleCase instead of snake_case by convention.
foo: u32,
bar: u64,
/// `@This()` can be used to refer to this struct type. In files with fields, it is quite common to
/// name the type here, so it can be easily referenced by other declarations in this file.
const TopLevelFields = @This();
pub fn init(val: u32) TopLevelFields {
return .{
.foo = val,
.bar = val * 10,
};
}
Such files can be instantiated just like any other struct type. A file's "root struct type" can be referred to within that file using @This.
File and Declaration Discovery
Zig places importance on the concept of whether any piece of code is semantically analyzed; in essence, whether the compiler "looks at" it. What code is analyzed is based on what files and declarations are "discovered" from a certain point. This process of "discovery" is based on a simple set of recursive rules:
If a call to @import is analyzed, the file being imported is analyzed.
If a type (including a file) is analyzed, all comptime, usingnamespace, and export declarations within it are analyzed.
If a type (including a file) is analyzed, and the compilation is for a test, and the module the type is within is the root module of the compilation, then all test declarations within it are also analyzed.
If a reference to a named declaration (i.e. a usage of it) is analyzed, the declaration being referenced is analyzed. Declarations are order-independent, so this reference may be above or below the declaration being referenced, or even in another file entirely.
That's it! Those rules define how Zig files and declarations are discovered. All that remains is to understand where this process starts.
The answer to that is the root of the standard library: every Zig compilation begins by analyzing the file lib/std/std.zig. This file contains a comptime declaration which imports lib/std/start.zig, and that file in turn uses @import("root") to reference the "root module"; so, the file you provide as your main module's root source file is effectively also a root, because the standard library will always reference it.
It is often desirable to make sure that certain declarations — particularly test or export declarations — are discovered. Based on the above rules, a common strategy for this is to use @import within a comptime or test block:
force_file_discovery.zig
comptime {
// This will ensure that the file 'api.zig' is always discovered (as long as this file is discovered).
// It is useful if 'api.zig' contains important exported declarations.
_ = @import("api.zig");
// We could also have a file which contains declarations we only want to export depending on a comptime
// condition. In that case, we can use an `if` statement here:
if (builtin.os.tag == .windows) {
_ = @import("windows_api.zig");
}
}
test {
// This will ensure that the file 'tests.zig' is always discovered (as long as this file is discovered),
// if this compilation is a test. It is useful if 'tests.zig' contains tests we want to ensure are run.
_ = @import("tests.zig");
// We could also have a file which contains tests we only want to run depending on a comptime condition.
// In that case, we can use an `if` statement here:
if (builtin.os.tag == .windows) {
_ = @import("windows_tests.zig");
}
}
const builtin = @import("builtin");
Special Root Declarations
Because the root module's root source file is always accessible using @import("root"), is is sometimes used by libraries — including the Zig Standard Library — as a place for the program to expose some "global" information to that library. The Zig Standard Library will look for several declarations in this file.
Entry Point
When building an executable, the most important thing to be looked up in this file is the program's entry point. Most commonly, this is a function named main, which std.start will call just after performing important initialization work.
Alternatively, the presence of a declaration named _start (for instance, pub const _start = {};) will disable the default std.start logic, allowing your root source file to export a low-level entry point as needed.
entry_point.zig
/// `std.start` imports this file using `@import("root")`, and uses this declaration as the program's
/// user-provided entry point. It can return any of the following types:
/// * `void`
/// * `E!void`, for any error set `E`
/// * `u8`
/// * `E!u8`, for any error set `E`
/// Returning a `void` value from this function will exit with code 0.
/// Returning a `u8` value from this function will exit with the given status code.
/// Returning an error value from this function will print an Error Return Trace and exit with code 1.
pub fn main() void {
std.debug.print("Hello, World!\n", .{});
}
// If uncommented, this declaration would suppress the usual std.start logic, causing
// the `main` declaration above to be ignored.
//pub const _start = {};
const std = @import("std");
Shell
$ zig build-exe entry_point.zig
$ ./entry_point
Hello, World!
If the Zig compilation links libc, the main function can optionally be an export fn which matches the signature of the C main function:
libc_export_entry_point.zig
pub export fn main(argc: c_int, argv: [*]const [*:0]const u8) c_int {
const args = argv[0..@intCast(argc)];
std.debug.print("Hello! argv[0] is '{s}'\n", .{args[0]});
return 0;
}
const std = @import("std");
Shell
$ zig build-exe libc_export_entry_point.zig -lc
$ ./libc_export_entry_point
Hello! argv[0] is './libc_export_entry_point'
std.start may also use other entry point declarations in certain situations, such as wWinMain or EfiMain. Refer to the lib/std/start.zig logic for details of these declarations.
Standard Library Options
The standard library also looks for a declaration in the root module's root source file named std_options. If present, this declaration is expected to be a struct of type std.Options, and allows the program to customize some standard library functionality, such as the std.log implementation.
std_options.zig
/// The presence of this declaration allows the program to override certain behaviors of the standard library.
/// For a full list of available options, see the documentation for `std.Options`.
pub const std_options: std.Options = .{
// By default, in safe build modes, the standard library will attach a segfault handler to the program to
// print a helpful stack trace if a segmentation fault occurs. Here, we can disable this, or even enable
// it in unsafe build modes.
.enable_segfault_handler = true,
// This is the logging function used by `std.log`.
.logFn = myLogFn,
};
fn myLogFn(
comptime level: std.log.Level,
comptime scope: @Type(.enum_literal),
comptime format: []const u8,
args: anytype,
) void {
// We could do anything we want here!
// ...but actually, let's just call the default implementation.
std.log.defaultLog(level, scope, format, args);
}
const std = @import("std");
Panic Handler
The Zig Standard Library looks for a declaration named panic in the root module's root source file. If present, it is expected to be a namespace (container type) with declarations providing different panic handlers.
See std.debug.simple_panic for a basic implementation of this namespace.
Overriding how the panic handler actually outputs messages, but keeping the formatted safety panics which are enabled by default, can be easily achieved with std.debug.FullPanic:
panic_handler.zig
pub fn main() void {
@setRuntimeSafety(true);
var x: u8 = 255;
// Let's overflow this integer!
x += 1;
}
pub const panic = std.debug.FullPanic(myPanic);
fn myPanic(msg: []const u8, first_trace_addr: ?usize) noreturn {
_ = first_trace_addr;
std.debug.print("Panic! {s}\n", .{msg});
std.process.exit(1);
}
const std = @import("std");
Shell
$ zig build-exe panic_handler.zig
$ ./panic_handler
Panic! integer overflow
Zig Build System
The Zig Build System provides a cross-platform, dependency-free way to declare the logic required to build a project. With this system, the logic to build a project is written in a build.zig file, using the Zig Build System API to declare and configure build artifacts and other tasks.
Some examples of tasks the build system can help with:
Performing tasks in parallel and caching the results.
Depending on other projects.
Providing a package for other projects to depend on.
Creating build artifacts by executing the Zig compiler. This includes building Zig source code as well as C and C++ source code.
Capturing user-configured options and using those options to configure the build.
Surfacing build configuration as comptime values by providing a file that can be imported by Zig code.
Caching build artifacts to avoid unnecessarily repeating steps.
Executing build artifacts or system-installed tools.
Running tests and verifying the output of executing a build artifact matches the expected value.
Running zig fmt on a codebase or a subset of it.
Custom tasks.
To use the build system, run zig build --help to see a command-line usage help menu. This will include project-specific options that were declared in the build.zig script.
For the time being, the build system documentation is hosted externally: Build System Documentation
C
Although Zig is independent of C, and, unlike most other languages, does not depend on libc, Zig acknowledges the importance of interacting with existing C code.
There are a few ways that Zig facilitates C interop.
C Type Primitives
These have guaranteed C ABI compatibility and can be used like any other type.
c_char
c_short
c_ushort
c_int
c_uint
c_long
c_ulong
c_longlong
c_ulonglong
c_longdouble
To interop with the C void type, use anyopaque.
See also:
Primitive Types
Import from C Header File
The @cImport builtin function can be used to directly import symbols from .h files:
cImport_builtin.zig
const c = @cImport({
// See https://github.com/ziglang/zig/issues/515
@cDefine("_NO_CRT_STDIO_INLINE", "1");
@cInclude("stdio.h");
});
pub fn main() void {
_ = c.printf("hello\n");
}
Shell
$ zig build-exe cImport_builtin.zig -lc
$ ./cImport_builtin
hello
The @cImport function takes an expression as a parameter. This expression is evaluated at compile-time and is used to control preprocessor directives and include multiple .h files:
@cImport Expression
const builtin = @import("builtin");
const c = @cImport({
@cDefine("NDEBUG", builtin.mode == .ReleaseFast);
if (something) {
@cDefine("_GNU_SOURCE", {});
}
@cInclude("stdlib.h");
if (something) {
@cUndef("_GNU_SOURCE");
}
@cInclude("soundio.h");
});
See also:
@cImport
@cInclude
@cDefine
@cUndef
@import
C Translation CLI
Zig's C translation capability is available as a CLI tool via zig translate-c. It requires a single filename as an argument. It may also take a set of optional flags that are forwarded to clang. It writes the translated file to stdout.
Command line flags
-I: Specify a search directory for include files. May be used multiple times. Equivalent to clang's -I flag. The current directory is not included by default; use -I. to include it.
-D: Define a preprocessor macro. Equivalent to clang's -D flag.
-cflags [flags] --: Pass arbitrary additional command line flags to clang. Note: the list of flags must end with --
-target: The target triple for the translated Zig code. If no target is specified, the current host target will be used.
Using -target and -cflags
Important! When translating C code with zig translate-c, you must use the same -target triple that you will use when compiling the translated code. In addition, you must ensure that the -cflags used, if any, match the cflags used by code on the target system. Using the incorrect -target or -cflags could result in clang or Zig parse failures, or subtle ABI incompatibilities when linking with C code.
varytarget.h
long FOO = __LONG_MAX__;
Shell
$ zig translate-c -target thumb-freestanding-gnueabihf varytarget.h|grep FOO
pub export var FOO: c_long = 2147483647;
$ zig translate-c -target x86_64-macos-gnu varytarget.h|grep FOO
pub export var FOO: c_long = 9223372036854775807;
varycflags.h
enum FOO { BAR };
int do_something(enum FOO foo);
Shell
$ zig translate-c varycflags.h|grep -B1 do_something
pub const enum_FOO = c_uint;
pub extern fn do_something(foo: enum_FOO) c_int;
$ zig translate-c -cflags -fshort-enums -- varycflags.h|grep -B1 do_something
pub const enum_FOO = u8;
pub extern fn do_something(foo: enum_FOO) c_int;
@cImport vs translate-c
@cImport and zig translate-c use the same underlying C translation functionality, so on a technical level they are equivalent. In practice, @cImport is useful as a way to quickly and easily access numeric constants, typedefs, and record types without needing any extra setup. If you need to pass cflags to clang, or if you would like to edit the translated code, it is recommended to use zig translate-c and save the results to a file. Common reasons for editing the generated code include: changing anytype parameters in function-like macros to more specific types; changing [*c]T pointers to [*]T or *T pointers for improved type safety; and enabling or disabling runtime safety within specific functions.
See also:
Targets
C Type Primitives
Pointers
C Pointers
Import from C Header File
@cInclude
@cImport
@setRuntimeSafety
C Translation Caching
The C translation feature (whether used via zig translate-c or @cImport) integrates with the Zig caching system. Subsequent runs with the same source file, target, and cflags will use the cache instead of repeatedly translating the same code.
To see where the cached files are stored when compiling code that uses @cImport, use the --verbose-cimport flag:
verbose_cimport_flag.zig
const c = @cImport({
@cDefine("_NO_CRT_STDIO_INLINE", "1");
@cInclude("stdio.h");
});
pub fn main() void {
_ = c;
}
Shell
$ zig build-exe verbose_cimport_flag.zig -lc --verbose-cimport
info(compilation): C import source: /home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/a9dade369e12a8c90b55d7f3e444f0ce/cimport.h
info(compilation): C import .d file: /home/ci/actions-runner/_work/zig-bootstrap/out/zig-local-cache/o/a9dade369e12a8c90b55d7f3e444f0ce/cimport.h.d
$ ./verbose_cimport_flag
cimport.h contains the file to translate (constructed from calls to @cInclude, @cDefine, and @cUndef), cimport.h.d is the list of file dependencies, and cimport.zig contains the translated output.
See also:
Import from C Header File
C Translation CLI
@cInclude
@cImport
Translation failures
Some C constructs cannot be translated to Zig - for example, goto, structs with bitfields, and token-pasting macros. Zig employs demotion to allow translation to continue in the face of non-translatable entities.
Demotion comes in three varieties - opaque, extern, and @compileError. C structs and unions that cannot be translated correctly will be translated as opaque{}. Functions that contain opaque types or code constructs that cannot be translated will be demoted to extern declarations. Thus, non-translatable types can still be used as pointers, and non-translatable functions can be called so long as the linker is aware of the compiled function.
@compileError is used when top-level definitions (global variables, function prototypes, macros) cannot be translated or demoted. Since Zig uses lazy analysis for top-level declarations, untranslatable entities will not cause a compile error in your code unless you actually use them.
See also:
opaque
extern
@compileError
C Macros
C Translation makes a best-effort attempt to translate function-like macros into equivalent Zig functions. Since C macros operate at the level of lexical tokens, not all C macros can be translated to Zig. Macros that cannot be translated will be demoted to @compileError. Note that C code which uses macros will be translated without any additional issues (since Zig operates on the pre-processed source with macros expanded). It is merely the macros themselves which may not be translatable to Zig.
Consider the following example:
macro.c
#define MAKELOCAL(NAME, INIT) int NAME = INIT
int foo(void) {
MAKELOCAL(a, 1);
MAKELOCAL(b, 2);
return a + b;
}
Shell
$ zig translate-c macro.c > macro.zig
macro.zig
pub export fn foo() c_int {
var a: c_int = 1;
_ = &a;
var b: c_int = 2;
_ = &b;
return a + b;
}
pub const MAKELOCAL = @compileError("unable to translate C expr: unexpected token .Equal"); // macro.c:1:9
Note that foo was translated correctly despite using a non-translatable macro. MAKELOCAL was demoted to @compileError since it cannot be expressed as a Zig function; this simply means that you cannot directly use MAKELOCAL from Zig.
See also:
@compileError
C Pointers
This type is to be avoided whenever possible. The only valid reason for using a C pointer is in auto-generated code from translating C code.
When importing C header files, it is ambiguous whether pointers should be translated as single-item pointers (*T) or many-item pointers ([*]T). C pointers are a compromise so that Zig code can utilize translated header files directly.
[*c]T - C pointer.
Supports all the syntax of the other two pointer types (*T) and ([*]T).
Coerces to other pointer types, as well as Optional Pointers. When a C pointer is coerced to a non-optional pointer, safety-checked Illegal Behavior occurs if the address is 0.
Allows address 0. On non-freestanding targets, dereferencing address 0 is safety-checked Illegal Behavior. Optional C pointers introduce another bit to keep track of null, just like ?usize. Note that creating an optional C pointer is unnecessary as one can use normal Optional Pointers.
Supports Type Coercion to and from integers.
Supports comparison with integers.
Does not support Zig-only pointer attributes such as alignment. Use normal Pointers please!
When a C pointer is pointing to a single struct (not an array), dereference the C pointer to access the struct's fields or member data. That syntax looks like this:
ptr_to_struct.*.struct_member
This is comparable to doing -> in C.
When a C pointer is pointing to an array of structs, the syntax reverts to this:
ptr_to_struct_array[index].struct_member
C Variadic Functions
Zig supports extern variadic functions.
test_variadic_function.zig
const std = @import("std");
const testing = std.testing;
pub extern "c" fn printf(format: [*:0]const u8, ...) c_int;
test "variadic function" {
try testing.expect(printf("Hello, world!\n") == 14);
try testing.expect(@typeInfo(@TypeOf(printf)).@"fn".is_var_args);
}
Shell
$ zig test test_variadic_function.zig -lc
1/1 test_variadic_function.test.variadic function...OK
All 1 tests passed.
Hello, world!
Variadic functions can be implemented using @cVaStart, @cVaEnd, @cVaArg and @cVaCopy.
test_defining_variadic_function.zig
const std = @import("std");
const testing = std.testing;
const builtin = @import("builtin");
fn add(count: c_int, ...) callconv(.c) c_int {
var ap = @cVaStart();
defer @cVaEnd(&ap);
var i: usize = 0;
var sum: c_int = 0;
while (i < count) : (i += 1) {
sum += @cVaArg(&ap, c_int);
}
return sum;
}
test "defining a variadic function" {
if (builtin.cpu.arch == .aarch64 and builtin.os.tag != .macos) {
// https://github.com/ziglang/zig/issues/14096
return error.SkipZigTest;
}
if (builtin.cpu.arch == .x86_64 and builtin.os.tag == .windows) {
// https://github.com/ziglang/zig/issues/16961
return error.SkipZigTest;
}
try std.testing.expectEqual(@as(c_int, 0), add(0));
try std.testing.expectEqual(@as(c_int, 1), add(1, @as(c_int, 1)));
try std.testing.expectEqual(@as(c_int, 3), add(2, @as(c_int, 1), @as(c_int, 2)));
}
Shell
$ zig test test_defining_variadic_function.zig
1/1 test_defining_variadic_function.test.defining a variadic function...OK
All 1 tests passed.
Exporting a C Library
One of the primary use cases for Zig is exporting a library with the C ABI for other programming languages to call into. The export keyword in front of functions, variables, and types causes them to be part of the library API:
mathtest.zig
export fn add(a: i32, b: i32) i32 {
return a + b;
}
To make a static library:
Shell
$ zig build-lib mathtest.zig
To make a shared library:
Shell
$ zig build-lib mathtest.zig -dynamic
Here is an example with the Zig Build System:
test.c
// This header is generated by zig from mathtest.zig
#include "mathtest.h"
#include
int main(int argc, char **argv) {
int32_t result = add(42, 1337);
printf("%d\n", result);
return 0;
}
build_c.zig
const std = @import("std");
pub fn build(b: *std.Build) void {
const lib = b.addSharedLibrary(.{
.name = "mathtest",
.root_source_file = b.path("mathtest.zig"),
.version = .{ .major = 1, .minor = 0, .patch = 0 },
});
const exe = b.addExecutable(.{
.name = "test",
});
exe.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
exe.linkLibrary(lib);
exe.linkSystemLibrary("c");
b.default_step.dependOn(&exe.step);
const run_cmd = exe.run();
const test_step = b.step("test", "Test the program");
test_step.dependOn(&run_cmd.step);
}
Shell
$ zig build test
1379
See also:
export
Mixing Object Files
You can mix Zig object files with any other object files that respect the C ABI. Example:
base64.zig
const base64 = @import("std").base64;
export fn decode_base_64(
dest_ptr: [*]u8,
dest_len: usize,
source_ptr: [*]const u8,
source_len: usize,
) usize {
const src = source_ptr[0..source_len];
const dest = dest_ptr[0..dest_len];
const base64_decoder = base64.standard.Decoder;
const decoded_size = base64_decoder.calcSizeForSlice(src) catch unreachable;
base64_decoder.decode(dest[0..decoded_size], src) catch unreachable;
return decoded_size;
}
test.c
// This header is generated by zig from base64.zig
#include "base64.h"
#include
#include
int main(int argc, char **argv) {
const char *encoded = "YWxsIHlvdXIgYmFzZSBhcmUgYmVsb25nIHRvIHVz";
char buf[200];
size_t len = decode_base_64(buf, 200, encoded, strlen(encoded));
buf[len] = 0;
puts(buf);
return 0;
}
build_object.zig
const std = @import("std");
pub fn build(b: *std.Build) void {
const obj = b.addObject(.{
.name = "base64",
.root_source_file = b.path("base64.zig"),
});
const exe = b.addExecutable(.{
.name = "test",
});
exe.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
exe.addObject(obj);
exe.linkSystemLibrary("c");
b.installArtifact(exe);
}
Shell
$ zig build
$ ./zig-out/bin/test
all your base are belong to us
See also:
Targets
Zig Build System
WebAssembly
Zig supports building for WebAssembly out of the box.
Freestanding
For host environments like the web browser and nodejs, build as an executable using the freestanding OS target. Here's an example of running Zig code compiled to WebAssembly with nodejs.
math.zig
extern fn print(i32) void;
export fn add(a: i32, b: i32) void {
print(a + b);
}
Shell
$ zig build-exe math.zig -target wasm32-freestanding -fno-entry --export=add
test.js
const fs = require('fs');
const source = fs.readFileSync("./math.wasm");
const typedArray = new Uint8Array(source);
WebAssembly.instantiate(typedArray, {
env: {
print: (result) => { console.log(`The result is ${result}`); }
}}).then(result => {
const add = result.instance.exports.add;
add(1, 2);
});
Shell
$ node test.js
The result is 3
WASI
Zig's support for WebAssembly System Interface (WASI) is under active development. Example of using the standard library and reading command line arguments:
wasi_args.zig
const std = @import("std");
pub fn main() !void {
var general_purpose_allocator: std.heap.GeneralPurposeAllocator(.{}) = .init;
const gpa = general_purpose_allocator.allocator();
const args = try std.process.argsAlloc(gpa);
defer std.process.argsFree(gpa, args);
for (args, 0..) |arg, i| {
std.debug.print("{}: {s}\n", .{ i, arg });
}
}
Shell
$ zig build-exe wasi_args.zig -target wasm32-wasi
Shell
$ wasmtime wasi_args.wasm 123 hello
0: wasi_args.wasm
1: 123
2: hello
A more interesting example would be extracting the list of preopens from the runtime. This is now supported in the standard library via std.fs.wasi.Preopens:
wasi_preopens.zig
const std = @import("std");
const fs = std.fs;
pub fn main() !void {
var general_purpose_allocator: std.heap.GeneralPurposeAllocator(.{}) = .init;
const gpa = general_purpose_allocator.allocator();
var arena_instance = std.heap.ArenaAllocator.init(gpa);
defer arena_instance.deinit();
const arena = arena_instance.allocator();
const preopens = try fs.wasi.preopensAlloc(arena);
for (preopens.names, 0..) |preopen, i| {
std.debug.print("{}: {s}\n", .{ i, preopen });
}
}
Shell
$ zig build-exe wasi_preopens.zig -target wasm32-wasi
Shell
$ wasmtime --dir=. wasi_preopens.wasm
0: stdin
1: stdout
2: stderr
3: .
Targets
Target refers to the computer that will be used to run an executable. It is composed of the CPU architecture, the set of enabled CPU features, operating system, minimum and maximum operating system version, ABI, and ABI version.
Zig is a general-purpose programming language which means that it is designed to generate optimal code for a large set of targets. The command zig targets provides information about all of the targets the compiler is aware of.
When no target option is provided to the compiler, the default choice is to target the host computer, meaning that the resulting executable will be unsuitable for copying to a different computer. In order to copy an executable to another computer, the compiler needs to know about the target requirements via the -target option.
The Zig Standard Library (@import("std")) has cross-platform abstractions, making the same source code viable on many targets. Some code is more portable than other code. In general, Zig code is extremely portable compared to other programming languages.
Each platform requires its own implementations to make Zig's cross-platform abstractions work. These implementations are at various degrees of completion. Each tagged release of the compiler comes with release notes that provide the full support table for each target.
Style Guide
These coding conventions are not enforced by the compiler, but they are shipped in this documentation along with the compiler in order to provide a point of reference, should anyone wish to point to an authority on agreed upon Zig coding style.
Avoid Redundancy in Names
Avoid these words in type names:
Value
Data
Context
Manager
utils, misc, or somebody's initials
Everything is a value, all types are data, everything is context, all logic manages state. Nothing is communicated by using a word that applies to all types.
Temptation to use "utilities", "miscellaneous", or somebody's initials is a failure to categorize, or more commonly, overcategorization. Such declarations can live at the root of a module that needs them with no namespace needed.
Avoid Redundant Names in Fully-Qualified Namespaces
Every declaration is assigned a fully qualified namespace by the compiler, creating a tree structure. Choose names based on the fully-qualified namespace, and avoid redundant name segments.
redundant_fqn.zig
const std = @import("std");
pub const json = struct {
pub const JsonValue = union(enum) {
number: f64,
boolean: bool,
// ...
};
};
pub fn main() void {
std.debug.print("{s}\n", .{@typeName(json.JsonValue)});
}
Shell
$ zig build-exe redundant_fqn.zig
$ ./redundant_fqn
redundant_fqn.json.JsonValue
In this example, "json" is repeated in the fully-qualified namespace. The solution is to delete Json from JsonValue. In this example we have an empty struct named json but remember that files also act as part of the fully-qualified namespace.
This example is an exception to the rule specified in Avoid Redundancy in Names. The meaning of the type has been reduced to its core: it is a json value. The name cannot be any more specific without being incorrect.
Whitespace
4 space indentation
Open braces on same line, unless you need to wrap.
If a list of things is longer than 2, put each item on its own line and exercise the ability to put an extra comma at the end.
Line length: aim for 100; use common sense.
Names
Roughly speaking: camelCaseFunctionName, TitleCaseTypeName, snake_case_variable_name. More precisely:
If x is a type then x should be TitleCase, unless it is a struct with 0 fields and is never meant to be instantiated, in which case it is considered to be a "namespace" and uses snake_case.
If x is callable, and x's return type is type, then x should be TitleCase.
If x is otherwise callable, then x should be camelCase.
Otherwise, x should be snake_case.
Acronyms, initialisms, proper nouns, or any other word that has capitalization rules in written English are subject to naming conventions just like any other word. Even acronyms that are only 2 letters long are subject to these conventions.
File names fall into two categories: types and namespaces. If the file (implicitly a struct) has top level fields, it should be named like any other struct with fields using TitleCase. Otherwise, it should use snake_case. Directory names should be snake_case.
These are general rules of thumb; if it makes sense to do something different, do what makes sense. For example, if there is an established convention such as ENOENT, follow the established convention.
Examples
style_example.zig
const namespace_name = @import("dir_name/file_name.zig");
const TypeName = @import("dir_name/TypeName.zig");
var global_var: i32 = undefined;
const const_name = 42;
const primitive_type_alias = f32;
const string_alias = []u8;
const StructName = struct {
field: i32,
};
const StructAlias = StructName;
fn functionName(param_name: TypeName) void {
var functionPointer = functionName;
functionPointer();
functionPointer = otherFunction;
functionPointer();
}
const functionAlias = functionName;
fn ListTemplateFunction(comptime ChildType: type, comptime fixed_size: usize) type {
return List(ChildType, fixed_size);
}
fn ShortList(comptime T: type, comptime n: usize) type {
return struct {
field_name: [n]T,
fn methodName() void {}
};
}
// The word XML loses its casing when used in Zig identifiers.
const xml_document =
\\
\\
\\
;
const XmlParser = struct {
field: i32,
};
// The initials BE (Big Endian) are just another word in Zig identifier names.
fn readU32Be() u32 {}
See the Zig Standard Library for more examples.
Doc Comment Guidance
Omit any information that is redundant based on the name of the thing being documented.
Duplicating information onto multiple similar functions is encouraged because it helps IDEs and other tools provide better help text.
Use the word assume to indicate invariants that cause unchecked Illegal Behavior when violated.
Use the word assert to indicate invariants that cause safety-checked Illegal Behavior when violated.
Source Encoding
Zig source code is encoded in UTF-8. An invalid UTF-8 byte sequence results in a compile error.
Throughout all zig source code (including in comments), some code points are never allowed:
Ascii control characters, except for U+000a (LF), U+000d (CR), and U+0009 (HT): U+0000 - U+0008, U+000b - U+000c, U+000e - U+0001f, U+007f.
Non-Ascii Unicode line endings: U+0085 (NEL), U+2028 (LS), U+2029 (PS).
LF (byte value 0x0a, code point U+000a, '\n') is the line terminator in Zig source code. This byte value terminates every line of zig source code except the last line of the file. It is recommended that non-empty source files end with an empty line, which means the last byte would be 0x0a (LF).
Each LF may be immediately preceded by a single CR (byte value 0x0d, code point U+000d, '\r') to form a Windows style line ending, but this is discouraged. Note that in multiline strings, CRLF sequences will be encoded as LF when compiled into a zig program. A CR in any other context is not allowed.
HT hard tabs (byte value 0x09, code point U+0009, '\t') are interchangeable with SP spaces (byte value 0x20, code point U+0020, ' ') as a token separator, but use of hard tabs is discouraged. See Grammar.
For compatibility with other tools, the compiler ignores a UTF-8-encoded byte order mark (U+FEFF) if it is the first Unicode code point in the source text. A byte order mark is not allowed anywhere else in the source.
Note that running zig fmt on a source file will implement all recommendations mentioned here.
Note that a tool reading Zig source code can make assumptions if the source code is assumed to be correct Zig code. For example, when identifying the ends of lines, a tool can use a naive search such as /\n/, or an advanced search such as /\r\n?|[\n\u0085\u2028\u2029]/, and in either case line endings will be correctly identified. For another example, when identifying the whitespace before the first token on a line, a tool can either use a naive search such as /[ \t]/, or an advanced search such as /\s/, and in either case whitespace will be correctly identified.
Keyword Reference
Keyword Description
addrspace
The addrspace keyword.
TODO add documentation for addrspace
align
align can be used to specify the alignment of a pointer. It can also be used after a variable or function declaration to specify the alignment of pointers to that variable or function.
See also Alignment
allowzero
The pointer attribute allowzero allows a pointer to have address zero.
See also allowzero
and
The boolean operator and.
See also Operators
anyframe
anyframe can be used as a type for variables which hold pointers to function frames.
See also Async Functions
anytype
Function parameters can be declared with anytype in place of the type. The type will be inferred where the function is called.
See also Function Parameter Type Inference
asm
asm begins an inline assembly expression. This allows for directly controlling the machine code generated on compilation.
See also Assembly
async
async can be used before a function call to get a pointer to the function's frame when it suspends.
See also Async Functions
await
await can be used to suspend the current function until the frame provided after the await completes. await copies the value returned from the target function's frame to the caller.
See also Async Functions
break
break can be used with a block label to return a value from the block. It can also be used to exit a loop before iteration completes naturally.
See also Blocks, while, for
callconv
callconv can be used to specify the calling convention in a function type.
See also Functions
catch
catch can be used to evaluate an expression if the expression before it evaluates to an error. The expression after the catch can optionally capture the error value.
See also catch, Operators
comptime
comptime before a declaration can be used to label variables or function parameters as known at compile time. It can also be used to guarantee an expression is run at compile time.
See also comptime
const
const declares a variable that can not be modified. Used as a pointer attribute, it denotes the value referenced by the pointer cannot be modified.
See also Variables
continue
continue can be used in a loop to jump back to the beginning of the loop.
See also while, for
defer
defer will execute an expression when control flow leaves the current block.
See also defer
else
else can be used to provide an alternate branch for if, switch, while, and for expressions.
If used after an if expression, the else branch will be executed if the test value returns false, null, or an error.
If used within a switch expression, the else branch will be executed if the test value matches no other cases.
If used after a loop expression, the else branch will be executed if the loop finishes without breaking.
See also if, switch, while, for
enum
enum defines an enum type.
See also enum
errdefer
errdefer will execute an expression when control flow leaves the current block if the function returns an error, the errdefer expression can capture the unwrapped value.
See also errdefer
error
error defines an error type.
See also Errors
export
export makes a function or variable externally visible in the generated object file. Exported functions default to the C calling convention.
See also Functions
extern
extern can be used to declare a function or variable that will be resolved at link time, when linking statically or at runtime, when linking dynamically.
See also Functions
fn
fn declares a function.
See also Functions
for
A for expression can be used to iterate over the elements of a slice, array, or tuple.
See also for
if
An if expression can test boolean expressions, optional values, or error unions. For optional values or error unions, the if expression can capture the unwrapped value.
See also if
inline
inline can be used to label a loop expression such that it will be unrolled at compile time. It can also be used to force a function to be inlined at all call sites.
See also inline while, inline for, Functions
linksection
The linksection keyword can be used to specify what section the function or global variable will be put into (e.g. .text).
noalias
The noalias keyword.
TODO add documentation for noalias
noinline
noinline disallows function to be inlined in all call sites.
See also Functions
nosuspend
The nosuspend keyword can be used in front of a block, statement or expression, to mark a scope where no suspension points are reached. In particular, inside a nosuspend scope:
Using the suspend keyword results in a compile error.
Using await on a function frame which hasn't completed yet results in safety-checked Illegal Behavior.
Calling an async function may result in safety-checked Illegal Behavior, because it's equivalent to await async some_async_fn(), which contains an await.
Code inside a nosuspend scope does not cause the enclosing function to become an async function.
See also Async Functions
opaque
opaque defines an opaque type.
See also opaque
or
The boolean operator or.
See also Operators
orelse
orelse can be used to evaluate an expression if the expression before it evaluates to null.
See also Optionals, Operators
packed
The packed keyword before a struct definition changes the struct's in-memory layout to the guaranteed packed layout.
See also packed struct
pub
The pub in front of a top level declaration makes the declaration available to reference from a different file than the one it is declared in.
See also import
resume
resume will continue execution of a function frame after the point the function was suspended.
return
return exits a function with a value.
See also Functions
struct
struct defines a struct.
See also struct
suspend
suspend will cause control flow to return to the call site or resumer of the function. suspend can also be used before a block within a function, to allow the function access to its frame before control flow returns to the call site.
switch
A switch expression can be used to test values of a common type. switch cases can capture field values of a Tagged union.
See also switch
test
The test keyword can be used to denote a top-level block of code used to make sure behavior meets expectations.
See also Zig Test
threadlocal
threadlocal can be used to specify a variable as thread-local.
See also Thread Local Variables
try
try evaluates an error union expression. If it is an error, it returns from the current function with the same error. Otherwise, the expression results in the unwrapped value.
See also try
union
union defines a union.
See also union
unreachable
unreachable can be used to assert that control flow will never happen upon a particular location. Depending on the build mode, unreachable may emit a panic.
Emits a panic in Debug and ReleaseSafe mode, or when using zig test.
Does not emit a panic in ReleaseFast and ReleaseSmall mode.
See also unreachable
usingnamespace
usingnamespace is a top-level declaration that imports all the public declarations of the operand, which must be a struct, union, or enum, into the current scope.
See also usingnamespace
var
var declares a variable that may be modified.
See also Variables
volatile
volatile can be used to denote loads or stores of a pointer have side effects. It can also modify an inline assembly expression to denote it has side effects.
See also volatile, Assembly
while
A while expression can be used to repeatedly test a boolean, optional, or error union expression, and cease looping when that expression evaluates to false, null, or an error, respectively.
See also while
Appendix
Containers
A container in Zig is any syntactical construct that acts as a namespace to hold variable and function declarations. Containers are also type definitions which can be instantiated. Structs, enums, unions, opaques, and even Zig source files themselves are containers.
Although containers (except Zig source files) use curly braces to surround their definition, they should not be confused with blocks or functions. Containers do not contain statements.
Grammar
grammar.y
Root <- skip container_doc_comment? ContainerMembers eof
# *** Top level ***
ContainerMembers <- ContainerDeclaration* (ContainerField COMMA)* (ContainerField / ContainerDeclaration*)
ContainerDeclaration <- TestDecl / ComptimeDecl / doc_comment? KEYWORD_pub? Decl
TestDecl <- KEYWORD_test (STRINGLITERALSINGLE / IDENTIFIER)? Block
ComptimeDecl <- KEYWORD_comptime Block
Decl
<- (KEYWORD_export / KEYWORD_extern STRINGLITERALSINGLE? / KEYWORD_inline / KEYWORD_noinline)? FnProto (SEMICOLON / Block)
/ (KEYWORD_export / KEYWORD_extern STRINGLITERALSINGLE?)? KEYWORD_threadlocal? GlobalVarDecl
/ KEYWORD_usingnamespace Expr SEMICOLON
FnProto <- KEYWORD_fn IDENTIFIER? LPAREN ParamDeclList RPAREN ByteAlign? AddrSpace? LinkSection? CallConv? EXCLAMATIONMARK? TypeExpr
VarDeclProto <- (KEYWORD_const / KEYWORD_var) IDENTIFIER (COLON TypeExpr)? ByteAlign? AddrSpace? LinkSection?
GlobalVarDecl <- VarDeclProto (EQUAL Expr)? SEMICOLON
ContainerField <- doc_comment? KEYWORD_comptime? !KEYWORD_fn (IDENTIFIER COLON)? TypeExpr ByteAlign? (EQUAL Expr)?
# *** Block Level ***
Statement
<- KEYWORD_comptime ComptimeStatement
/ KEYWORD_nosuspend BlockExprStatement
/ KEYWORD_suspend BlockExprStatement
/ KEYWORD_defer BlockExprStatement
/ KEYWORD_errdefer Payload? BlockExprStatement
/ IfStatement
/ LabeledStatement
/ SwitchExpr
/ VarDeclExprStatement
ComptimeStatement
<- BlockExpr
/ VarDeclExprStatement
IfStatement
<- IfPrefix BlockExpr ( KEYWORD_else Payload? Statement )?
/ IfPrefix AssignExpr ( SEMICOLON / KEYWORD_else Payload? Statement )
LabeledStatement <- BlockLabel? (Block / LoopStatement)
LoopStatement <- KEYWORD_inline? (ForStatement / WhileStatement)
ForStatement
<- ForPrefix BlockExpr ( KEYWORD_else Statement )?
/ ForPrefix AssignExpr ( SEMICOLON / KEYWORD_else Statement )
WhileStatement
<- WhilePrefix BlockExpr ( KEYWORD_else Payload? Statement )?
/ WhilePrefix AssignExpr ( SEMICOLON / KEYWORD_else Payload? Statement )
BlockExprStatement
<- BlockExpr
/ AssignExpr SEMICOLON
BlockExpr <- BlockLabel? Block
# An expression, assignment, or any destructure, as a statement.
VarDeclExprStatement
<- VarDeclProto (COMMA (VarDeclProto / Expr))* EQUAL Expr SEMICOLON
/ Expr (AssignOp Expr / (COMMA (VarDeclProto / Expr))+ EQUAL Expr)? SEMICOLON
# *** Expression Level ***
# An assignment or a destructure whose LHS are all lvalue expressions.
AssignExpr <- Expr (AssignOp Expr / (COMMA Expr)+ EQUAL Expr)?
SingleAssignExpr <- Expr (AssignOp Expr)?
Expr <- BoolOrExpr
BoolOrExpr <- BoolAndExpr (KEYWORD_or BoolAndExpr)*
BoolAndExpr <- CompareExpr (KEYWORD_and CompareExpr)*
CompareExpr <- BitwiseExpr (CompareOp BitwiseExpr)?
BitwiseExpr <- BitShiftExpr (BitwiseOp BitShiftExpr)*
BitShiftExpr <- AdditionExpr (BitShiftOp AdditionExpr)*
AdditionExpr <- MultiplyExpr (AdditionOp MultiplyExpr)*
MultiplyExpr <- PrefixExpr (MultiplyOp PrefixExpr)*
PrefixExpr <- PrefixOp* PrimaryExpr
PrimaryExpr
<- AsmExpr
/ IfExpr
/ KEYWORD_break BreakLabel? Expr?
/ KEYWORD_comptime Expr
/ KEYWORD_nosuspend Expr
/ KEYWORD_continue BreakLabel?
/ KEYWORD_resume Expr
/ KEYWORD_return Expr?
/ BlockLabel? LoopExpr
/ Block
/ CurlySuffixExpr
IfExpr <- IfPrefix Expr (KEYWORD_else Payload? Expr)?
Block <- LBRACE Statement* RBRACE
LoopExpr <- KEYWORD_inline? (ForExpr / WhileExpr)
ForExpr <- ForPrefix Expr (KEYWORD_else Expr)?
WhileExpr <- WhilePrefix Expr (KEYWORD_else Payload? Expr)?
CurlySuffixExpr <- TypeExpr InitList?
InitList
<- LBRACE FieldInit (COMMA FieldInit)* COMMA? RBRACE
/ LBRACE Expr (COMMA Expr)* COMMA? RBRACE
/ LBRACE RBRACE
TypeExpr <- PrefixTypeOp* ErrorUnionExpr
ErrorUnionExpr <- SuffixExpr (EXCLAMATIONMARK TypeExpr)?
SuffixExpr
<- KEYWORD_async PrimaryTypeExpr SuffixOp* FnCallArguments
/ PrimaryTypeExpr (SuffixOp / FnCallArguments)*
PrimaryTypeExpr
<- BUILTINIDENTIFIER FnCallArguments
/ CHAR_LITERAL
/ ContainerDecl
/ DOT IDENTIFIER
/ DOT InitList
/ ErrorSetDecl
/ FLOAT
/ FnProto
/ GroupedExpr
/ LabeledTypeExpr
/ IDENTIFIER
/ IfTypeExpr
/ INTEGER
/ KEYWORD_comptime TypeExpr
/ KEYWORD_error DOT IDENTIFIER
/ KEYWORD_anyframe
/ KEYWORD_unreachable
/ STRINGLITERAL
/ SwitchExpr
ContainerDecl <- (KEYWORD_extern / KEYWORD_packed)? ContainerDeclAuto
ErrorSetDecl <- KEYWORD_error LBRACE IdentifierList RBRACE
GroupedExpr <- LPAREN Expr RPAREN
IfTypeExpr <- IfPrefix TypeExpr (KEYWORD_else Payload? TypeExpr)?
LabeledTypeExpr
<- BlockLabel Block
/ BlockLabel? LoopTypeExpr
LoopTypeExpr <- KEYWORD_inline? (ForTypeExpr / WhileTypeExpr)
ForTypeExpr <- ForPrefix TypeExpr (KEYWORD_else TypeExpr)?
WhileTypeExpr <- WhilePrefix TypeExpr (KEYWORD_else Payload? TypeExpr)?
SwitchExpr <- KEYWORD_switch LPAREN Expr RPAREN LBRACE SwitchProngList RBRACE
# *** Assembly ***
AsmExpr <- KEYWORD_asm KEYWORD_volatile? LPAREN Expr AsmOutput? RPAREN
AsmOutput <- COLON AsmOutputList AsmInput?
AsmOutputItem <- LBRACKET IDENTIFIER RBRACKET STRINGLITERAL LPAREN (MINUSRARROW TypeExpr / IDENTIFIER) RPAREN
AsmInput <- COLON AsmInputList AsmClobbers?
AsmInputItem <- LBRACKET IDENTIFIER RBRACKET STRINGLITERAL LPAREN Expr RPAREN
AsmClobbers <- COLON StringList
# *** Helper grammar ***
BreakLabel <- COLON IDENTIFIER
BlockLabel <- IDENTIFIER COLON
FieldInit <- DOT IDENTIFIER EQUAL Expr
WhileContinueExpr <- COLON LPAREN AssignExpr RPAREN
LinkSection <- KEYWORD_linksection LPAREN Expr RPAREN
AddrSpace <- KEYWORD_addrspace LPAREN Expr RPAREN
# Fn specific
CallConv <- KEYWORD_callconv LPAREN Expr RPAREN
ParamDecl
<- doc_comment? (KEYWORD_noalias / KEYWORD_comptime)? (IDENTIFIER COLON)? ParamType
/ DOT3
ParamType
<- KEYWORD_anytype
/ TypeExpr
# Control flow prefixes
IfPrefix <- KEYWORD_if LPAREN Expr RPAREN PtrPayload?
WhilePrefix <- KEYWORD_while LPAREN Expr RPAREN PtrPayload? WhileContinueExpr?
ForPrefix <- KEYWORD_for LPAREN ForArgumentsList RPAREN PtrListPayload
# Payloads
Payload <- PIPE IDENTIFIER PIPE
PtrPayload <- PIPE ASTERISK? IDENTIFIER PIPE
PtrIndexPayload <- PIPE ASTERISK? IDENTIFIER (COMMA IDENTIFIER)? PIPE
PtrListPayload <- PIPE ASTERISK? IDENTIFIER (COMMA ASTERISK? IDENTIFIER)* COMMA? PIPE
# Switch specific
SwitchProng <- KEYWORD_inline? SwitchCase EQUALRARROW PtrIndexPayload? SingleAssignExpr
SwitchCase
<- SwitchItem (COMMA SwitchItem)* COMMA?
/ KEYWORD_else
SwitchItem <- Expr (DOT3 Expr)?
# For specific
ForArgumentsList <- ForItem (COMMA ForItem)* COMMA?
ForItem <- Expr (DOT2 Expr?)?
# Operators
AssignOp
<- ASTERISKEQUAL
/ ASTERISKPIPEEQUAL
/ SLASHEQUAL
/ PERCENTEQUAL
/ PLUSEQUAL
/ PLUSPIPEEQUAL
/ MINUSEQUAL
/ MINUSPIPEEQUAL
/ LARROW2EQUAL
/ LARROW2PIPEEQUAL
/ RARROW2EQUAL
/ AMPERSANDEQUAL
/ CARETEQUAL
/ PIPEEQUAL
/ ASTERISKPERCENTEQUAL
/ PLUSPERCENTEQUAL
/ MINUSPERCENTEQUAL
/ EQUAL
CompareOp
<- EQUALEQUAL
/ EXCLAMATIONMARKEQUAL
/ LARROW
/ RARROW
/ LARROWEQUAL
/ RARROWEQUAL
BitwiseOp
<- AMPERSAND
/ CARET
/ PIPE
/ KEYWORD_orelse
/ KEYWORD_catch Payload?
BitShiftOp
<- LARROW2
/ RARROW2
/ LARROW2PIPE
AdditionOp
<- PLUS
/ MINUS
/ PLUS2
/ PLUSPERCENT
/ MINUSPERCENT
/ PLUSPIPE
/ MINUSPIPE
MultiplyOp
<- PIPE2
/ ASTERISK
/ SLASH
/ PERCENT
/ ASTERISK2
/ ASTERISKPERCENT
/ ASTERISKPIPE
PrefixOp
<- EXCLAMATIONMARK
/ MINUS
/ TILDE
/ MINUSPERCENT
/ AMPERSAND
/ KEYWORD_try
/ KEYWORD_await
PrefixTypeOp
<- QUESTIONMARK
/ KEYWORD_anyframe MINUSRARROW
/ SliceTypeStart (ByteAlign / AddrSpace / KEYWORD_const / KEYWORD_volatile / KEYWORD_allowzero)*
/ PtrTypeStart (AddrSpace / KEYWORD_align LPAREN Expr (COLON Expr COLON Expr)? RPAREN / KEYWORD_const / KEYWORD_volatile / KEYWORD_allowzero)*
/ ArrayTypeStart
SuffixOp
<- LBRACKET Expr (DOT2 (Expr? (COLON Expr)?)?)? RBRACKET
/ DOT IDENTIFIER
/ DOTASTERISK
/ DOTQUESTIONMARK
FnCallArguments <- LPAREN ExprList RPAREN
# Ptr specific
SliceTypeStart <- LBRACKET (COLON Expr)? RBRACKET
PtrTypeStart
<- ASTERISK
/ ASTERISK2
/ LBRACKET ASTERISK (LETTERC / COLON Expr)? RBRACKET
ArrayTypeStart <- LBRACKET Expr (COLON Expr)? RBRACKET
# ContainerDecl specific
ContainerDeclAuto <- ContainerDeclType LBRACE container_doc_comment? ContainerMembers RBRACE
ContainerDeclType
<- KEYWORD_struct (LPAREN Expr RPAREN)?
/ KEYWORD_opaque
/ KEYWORD_enum (LPAREN Expr RPAREN)?
/ KEYWORD_union (LPAREN (KEYWORD_enum (LPAREN Expr RPAREN)? / Expr) RPAREN)?
# Alignment
ByteAlign <- KEYWORD_align LPAREN Expr RPAREN
# Lists
IdentifierList <- (doc_comment? IDENTIFIER COMMA)* (doc_comment? IDENTIFIER)?
SwitchProngList <- (SwitchProng COMMA)* SwitchProng?
AsmOutputList <- (AsmOutputItem COMMA)* AsmOutputItem?
AsmInputList <- (AsmInputItem COMMA)* AsmInputItem?
StringList <- (STRINGLITERAL COMMA)* STRINGLITERAL?
ParamDeclList <- (ParamDecl COMMA)* ParamDecl?
ExprList <- (Expr COMMA)* Expr?
# *** Tokens ***
eof <- !.
bin <- [01]
bin_ <- '_'? bin
oct <- [0-7]
oct_ <- '_'? oct
hex <- [0-9a-fA-F]
hex_ <- '_'? hex
dec <- [0-9]
dec_ <- '_'? dec
bin_int <- bin bin_*
oct_int <- oct oct_*
dec_int <- dec dec_*
hex_int <- hex hex_*
ox80_oxBF <- [\200-\277]
oxF4 <- '\364'
ox80_ox8F <- [\200-\217]
oxF1_oxF3 <- [\361-\363]
oxF0 <- '\360'
ox90_0xBF <- [\220-\277]
oxEE_oxEF <- [\356-\357]
oxED <- '\355'
ox80_ox9F <- [\200-\237]
oxE1_oxEC <- [\341-\354]
oxE0 <- '\340'
oxA0_oxBF <- [\240-\277]
oxC2_oxDF <- [\302-\337]
# From https://lemire.me/blog/2018/05/09/how-quickly-can-you-check-that-a-string-is-valid-unicode-utf-8/
# First Byte Second Byte Third Byte Fourth Byte
# [0x00,0x7F]
# [0xC2,0xDF] [0x80,0xBF]
# 0xE0 [0xA0,0xBF] [0x80,0xBF]
# [0xE1,0xEC] [0x80,0xBF] [0x80,0xBF]
# 0xED [0x80,0x9F] [0x80,0xBF]
# [0xEE,0xEF] [0x80,0xBF] [0x80,0xBF]
# 0xF0 [0x90,0xBF] [0x80,0xBF] [0x80,0xBF]
# [0xF1,0xF3] [0x80,0xBF] [0x80,0xBF] [0x80,0xBF]
# 0xF4 [0x80,0x8F] [0x80,0xBF] [0x80,0xBF]
mb_utf8_literal <-
oxF4 ox80_ox8F ox80_oxBF ox80_oxBF
/ oxF1_oxF3 ox80_oxBF ox80_oxBF ox80_oxBF
/ oxF0 ox90_0xBF ox80_oxBF ox80_oxBF
/ oxEE_oxEF ox80_oxBF ox80_oxBF
/ oxED ox80_ox9F ox80_oxBF
/ oxE1_oxEC ox80_oxBF ox80_oxBF
/ oxE0 oxA0_oxBF ox80_oxBF
/ oxC2_oxDF ox80_oxBF
ascii_char_not_nl_slash_squote <- [\000-\011\013-\046\050-\133\135-\177]
char_escape
<- "\\x" hex hex
/ "\\u{" hex+ "}"
/ "\\" [nr\\t'"]
char_char
<- mb_utf8_literal
/ char_escape
/ ascii_char_not_nl_slash_squote
string_char
<- char_escape
/ [^\\"\n]
container_doc_comment <- ('//!' [^\n]* [ \n]* skip)+
doc_comment <- ('///' [^\n]* [ \n]* skip)+
line_comment <- '//' ![!/][^\n]* / '////' [^\n]*
line_string <- ("\\\\" [^\n]* [ \n]*)+
skip <- ([ \n] / line_comment)*
CHAR_LITERAL <- "'" char_char "'" skip
FLOAT
<- "0x" hex_int "." hex_int ([pP] [-+]? dec_int)? skip
/ dec_int "." dec_int ([eE] [-+]? dec_int)? skip
/ "0x" hex_int [pP] [-+]? dec_int skip
/ dec_int [eE] [-+]? dec_int skip
INTEGER
<- "0b" bin_int skip
/ "0o" oct_int skip
/ "0x" hex_int skip
/ dec_int skip
STRINGLITERALSINGLE <- "\"" string_char* "\"" skip
STRINGLITERAL
<- STRINGLITERALSINGLE
/ (line_string skip)+
IDENTIFIER
<- !keyword [A-Za-z_] [A-Za-z0-9_]* skip
/ "@" STRINGLITERALSINGLE
BUILTINIDENTIFIER <- "@"[A-Za-z_][A-Za-z0-9_]* skip
AMPERSAND <- '&' ![=] skip
AMPERSANDEQUAL <- '&=' skip
ASTERISK <- '*' ![*%=|] skip
ASTERISK2 <- '**' skip
ASTERISKEQUAL <- '*=' skip
ASTERISKPERCENT <- '*%' ![=] skip
ASTERISKPERCENTEQUAL <- '*%=' skip
ASTERISKPIPE <- '*|' ![=] skip
ASTERISKPIPEEQUAL <- '*|=' skip
CARET <- '^' ![=] skip
CARETEQUAL <- '^=' skip
COLON <- ':' skip
COMMA <- ',' skip
DOT <- '.' ![*.?] skip
DOT2 <- '..' ![.] skip
DOT3 <- '...' skip
DOTASTERISK <- '.*' skip
DOTQUESTIONMARK <- '.?' skip
EQUAL <- '=' ![>=] skip
EQUALEQUAL <- '==' skip
EQUALRARROW <- '=>' skip
EXCLAMATIONMARK <- '!' ![=] skip
EXCLAMATIONMARKEQUAL <- '!=' skip
LARROW <- '<' ![<=] skip
LARROW2 <- '<<' ![=|] skip
LARROW2EQUAL <- '<<=' skip
LARROW2PIPE <- '<<|' ![=] skip
LARROW2PIPEEQUAL <- '<<|=' skip
LARROWEQUAL <- '<=' skip
LBRACE <- '{' skip
LBRACKET <- '[' skip
LPAREN <- '(' skip
MINUS <- '-' ![%=>|] skip
MINUSEQUAL <- '-=' skip
MINUSPERCENT <- '-%' ![=] skip
MINUSPERCENTEQUAL <- '-%=' skip
MINUSPIPE <- '-|' ![=] skip
MINUSPIPEEQUAL <- '-|=' skip
MINUSRARROW <- '->' skip
PERCENT <- '%' ![=] skip
PERCENTEQUAL <- '%=' skip
PIPE <- '|' ![|=] skip
PIPE2 <- '||' skip
PIPEEQUAL <- '|=' skip
PLUS <- '+' ![%+=|] skip
PLUS2 <- '++' skip
PLUSEQUAL <- '+=' skip
PLUSPERCENT <- '+%' ![=] skip
PLUSPERCENTEQUAL <- '+%=' skip
PLUSPIPE <- '+|' ![=] skip
PLUSPIPEEQUAL <- '+|=' skip
LETTERC <- 'c' skip
QUESTIONMARK <- '?' skip
RARROW <- '>' ![>=] skip
RARROW2 <- '>>' ![=] skip
RARROW2EQUAL <- '>>=' skip
RARROWEQUAL <- '>=' skip
RBRACE <- '}' skip
RBRACKET <- ']' skip
RPAREN <- ')' skip
SEMICOLON <- ';' skip
SLASH <- '/' ![=] skip
SLASHEQUAL <- '/=' skip
TILDE <- '~' skip
end_of_word <- ![a-zA-Z0-9_] skip
KEYWORD_addrspace <- 'addrspace' end_of_word
KEYWORD_align <- 'align' end_of_word
KEYWORD_allowzero <- 'allowzero' end_of_word
KEYWORD_and <- 'and' end_of_word
KEYWORD_anyframe <- 'anyframe' end_of_word
KEYWORD_anytype <- 'anytype' end_of_word
KEYWORD_asm <- 'asm' end_of_word
KEYWORD_async <- 'async' end_of_word
KEYWORD_await <- 'await' end_of_word
KEYWORD_break <- 'break' end_of_word
KEYWORD_callconv <- 'callconv' end_of_word
KEYWORD_catch <- 'catch' end_of_word
KEYWORD_comptime <- 'comptime' end_of_word
KEYWORD_const <- 'const' end_of_word
KEYWORD_continue <- 'continue' end_of_word
KEYWORD_defer <- 'defer' end_of_word
KEYWORD_else <- 'else' end_of_word
KEYWORD_enum <- 'enum' end_of_word
KEYWORD_errdefer <- 'errdefer' end_of_word
KEYWORD_error <- 'error' end_of_word
KEYWORD_export <- 'export' end_of_word
KEYWORD_extern <- 'extern' end_of_word
KEYWORD_fn <- 'fn' end_of_word
KEYWORD_for <- 'for' end_of_word
KEYWORD_if <- 'if' end_of_word
KEYWORD_inline <- 'inline' end_of_word
KEYWORD_noalias <- 'noalias' end_of_word
KEYWORD_nosuspend <- 'nosuspend' end_of_word
KEYWORD_noinline <- 'noinline' end_of_word
KEYWORD_opaque <- 'opaque' end_of_word
KEYWORD_or <- 'or' end_of_word
KEYWORD_orelse <- 'orelse' end_of_word
KEYWORD_packed <- 'packed' end_of_word
KEYWORD_pub <- 'pub' end_of_word
KEYWORD_resume <- 'resume' end_of_word
KEYWORD_return <- 'return' end_of_word
KEYWORD_linksection <- 'linksection' end_of_word
KEYWORD_struct <- 'struct' end_of_word
KEYWORD_suspend <- 'suspend' end_of_word
KEYWORD_switch <- 'switch' end_of_word
KEYWORD_test <- 'test' end_of_word
KEYWORD_threadlocal <- 'threadlocal' end_of_word
KEYWORD_try <- 'try' end_of_word
KEYWORD_union <- 'union' end_of_word
KEYWORD_unreachable <- 'unreachable' end_of_word
KEYWORD_usingnamespace <- 'usingnamespace' end_of_word
KEYWORD_var <- 'var' end_of_word
KEYWORD_volatile <- 'volatile' end_of_word
KEYWORD_while <- 'while' end_of_word
keyword <- KEYWORD_addrspace / KEYWORD_align / KEYWORD_allowzero / KEYWORD_and
/ KEYWORD_anyframe / KEYWORD_anytype / KEYWORD_asm / KEYWORD_async
/ KEYWORD_await / KEYWORD_break / KEYWORD_callconv / KEYWORD_catch
/ KEYWORD_comptime / KEYWORD_const / KEYWORD_continue / KEYWORD_defer
/ KEYWORD_else / KEYWORD_enum / KEYWORD_errdefer / KEYWORD_error / KEYWORD_export
/ KEYWORD_extern / KEYWORD_fn / KEYWORD_for / KEYWORD_if
/ KEYWORD_inline / KEYWORD_noalias / KEYWORD_nosuspend / KEYWORD_noinline
/ KEYWORD_opaque / KEYWORD_or / KEYWORD_orelse / KEYWORD_packed
/ KEYWORD_pub / KEYWORD_resume / KEYWORD_return / KEYWORD_linksection
/ KEYWORD_struct / KEYWORD_suspend / KEYWORD_switch / KEYWORD_test
/ KEYWORD_threadlocal / KEYWORD_try / KEYWORD_union / KEYWORD_unreachable
/ KEYWORD_usingnamespace / KEYWORD_var / KEYWORD_volatile / KEYWORD_while
Zen
Communicate intent precisely.
Edge cases matter.
Favor reading code over writing code.
Only one obvious way to do things.
Runtime crashes are better than bugs.
Compile errors are better than runtime crashes.
Incremental improvements.
Avoid local maximums.
Reduce the amount one must remember.
Focus on code rather than style.
Resource allocation may fail; resource deallocation must succeed.
Memory is a resource.
Together we serve the users.
```zig [src/evm/run_result.zig]
const ExecutionError = @import("execution/execution_error.zig");
/// Result of an EVM execution run.
///
/// RunResult encapsulates the outcome of executing EVM bytecode, including
/// success/failure status, gas consumption, and any output data. This is
/// the primary return type for VM execution functions.
///
/// ## Design Rationale
/// The result combines multiple pieces of information needed after execution:
/// - Status indicates how execution ended (success, revert, error)
/// - Gas tracking for accounting and refunds
/// - Output data for return values or revert messages
/// - Optional error details for debugging
///
/// ## Status Types
/// - Success: Execution completed normally
/// - Revert: Explicit revert (REVERT opcode or require failure)
/// - Invalid: Invalid operation (bad opcode, stack error, etc.)
/// - OutOfGas: Execution ran out of gas
///
/// ## Usage
/// ```zig
/// const result = vm.run(bytecode, gas_limit);
/// switch (result.status) {
/// .Success => {
/// // Process output data
/// const return_data = result.output orelse &[_]u8{};
/// },
/// .Revert => {
/// // Handle revert with reason
/// const revert_reason = result.output orelse &[_]u8{};
/// },
/// .Invalid => {
/// // Handle error
/// std.log.err("Execution failed: {?}", .{result.err});
/// },
/// .OutOfGas => {
/// // Handle out of gas
/// },
/// }
/// ```
const Self = @This();
/// Execution completion status.
///
/// Indicates how the execution ended. This maps to EVM execution outcomes:
/// - Success: Normal completion (STOP, RETURN, or end of code)
/// - Revert: Explicit revert (REVERT opcode)
/// - Invalid: Execution error (invalid opcode, stack error, etc.)
/// - OutOfGas: Gas exhausted during execution
pub const Status = enum {
/// Execution completed successfully
Success,
/// Execution was explicitly reverted
Revert,
/// Execution failed due to invalid operation
Invalid,
/// Execution ran out of gas
OutOfGas,
};
status: Status,
/// Optional execution error details.
///
/// Present when status is Invalid, providing specific error information
/// for debugging and error reporting.
err: ?ExecutionError.Error,
/// Remaining gas after execution.
///
/// For successful execution, this is refunded to the caller.
/// For failed execution, this may be zero or partially consumed.
gas_left: u64,
/// Total gas consumed during execution.
///
/// Calculated as: initial_gas - gas_left
/// Used for:
/// - Transaction receipts
/// - Gas accounting
/// - Performance monitoring
gas_used: u64,
/// Output data from execution.
///
/// Contents depend on execution status:
/// - Success: Return data from RETURN opcode
/// - Revert: Revert reason from REVERT opcode
/// - Invalid/OutOfGas: Usually null
///
/// Note: Empty output is different from null output.
/// Empty means explicit empty return, null means no return.
output: ?[]const u8,
pub fn init(
initial_gas: u64,
gas_left: u64,
status: Status,
err: ?ExecutionError.Error,
output: ?[]const u8,
) Self {
return Self{
.status = status,
.err = err,
.gas_left = gas_left,
.gas_used = initial_gas - gas_left,
.output = output,
};
}
```
```zig [src/evm/create_result.zig]
const Address = @import("Address");
/// Result structure for contract creation operations in the EVM.
///
/// This structure encapsulates the outcome of deploying a new smart contract
/// through CREATE or CREATE2 opcodes. It provides all necessary information
/// about the deployment result, including the new contract's address and any
/// revert data if the deployment failed.
///
/// ## Contract Creation Flow
/// 1. Execute initcode (constructor bytecode)
/// 2. Initcode returns runtime bytecode
/// 3. Runtime bytecode is stored at computed address
/// 4. This result structure is returned
///
/// ## Address Computation
/// - **CREATE**: address = keccak256(rlp([sender, nonce]))[12:]
/// - **CREATE2**: address = keccak256(0xff ++ sender ++ salt ++ keccak256(initcode))[12:]
///
/// ## Success Conditions
/// A creation succeeds when:
/// - Initcode executes without reverting
/// - Sufficient gas remains for code storage
/// - Returned bytecode size ≤ 24,576 bytes (EIP-170)
/// - No address collision occurs
///
/// ## Failure Modes
/// - Initcode reverts (REVERT opcode or error)
/// - Out of gas during execution
/// - Returned bytecode exceeds size limit
/// - Address collision (extremely rare)
/// - Stack depth exceeded
///
/// ## Example Usage
/// ```zig
/// const result = try vm.create_contract(value, initcode, gas, salt);
/// if (result.success) {
/// // Contract deployed at result.address
/// log.info("Deployed to: {}", .{result.address});
/// } else {
/// // Deployment failed, check output for revert reason
/// if (result.output) |revert_data| {
/// log.err("Deployment failed: {}", .{revert_data});
/// }
/// }
/// defer if (result.output) |output| allocator.free(output);
/// ```
const Self = @This();
/// Indicates whether the contract creation succeeded.
///
/// - `true`: Contract successfully deployed and code stored on-chain
/// - `false`: Creation failed due to revert, gas, or other errors
///
/// ## State Changes
/// - Success: All state changes are committed, contract exists at address
/// - Failure: All state changes are reverted, no contract is deployed
success: bool,
/// The address where the contract was (or would have been) deployed.
///
/// This address is computed deterministically before execution begins:
/// - For CREATE: Based on sender address and nonce
/// - For CREATE2: Based on sender, salt, and initcode hash
///
/// ## Important Notes
/// - Address is computed even if creation fails
/// - Can be used to predict addresses before deployment
/// - Useful for counterfactual instantiation patterns
///
/// ## Address Collision
/// If this address already contains a contract, creation fails.
/// The probability of collision is negligible (2^-160).
address: Address.Address,
/// Amount of gas remaining after the creation attempt.
///
/// ## Gas Accounting
/// - Deducted: Initcode execution + code storage (200 per byte)
/// - Refunded: Unused gas returns to caller
/// - Minimum: 32,000 gas for CREATE/CREATE2 base cost
///
/// ## Usage Patterns
/// - Success: Add back to calling context's available gas
/// - Failure with revert: Some gas may remain (unlike out-of-gas)
/// - Failure out-of-gas: Will be 0 or very low
gas_left: u64,
/// Optional data returned by the contract creation.
///
/// ## Success Case
/// - Contains the runtime bytecode to be stored on-chain
/// - Size must be ≤ 24,576 bytes (MAX_CODE_SIZE)
/// - Empty output creates a contract with no code
///
/// ## Failure Case
/// - Contains revert reason if REVERT was used
/// - `null` for out-of-gas or invalid operations
/// - Useful for debugging deployment failures
///
/// ## Memory Management
/// The output buffer is allocated by the VM and ownership transfers
/// to the caller, who must free it when no longer needed.
///
/// ## Examples
/// ```zig
/// // Success: output contains runtime bytecode
/// if (result.success and result.output) |bytecode| {
/// assert(bytecode.len <= MAX_CODE_SIZE);
/// }
///
/// // Failure: output may contain revert message
/// if (!result.success and result.output) |reason| {
/// // Decode revert reason (often ABI-encoded string)
/// }
/// ```
output: ?[]const u8,
pub fn initFailure(gas_left: u64, output: ?[]const u8) Self {
return Self{
.success = false,
.address = Address.zero(),
.gas_left = gas_left,
.output = output,
};
}
```
```zig [src/evm/jump_table/operation_config.zig]
const std = @import("std");
const execution = @import("../execution/package.zig");
const gas_constants = @import("../constants/gas_constants.zig");
const Stack = @import("../stack/stack.zig");
const Operation = @import("../opcodes/operation.zig");
const Hardfork = @import("../hardforks/hardfork.zig").Hardfork;
/// Specification for an EVM operation.
/// This data structure allows us to define all operations in a single place
/// and generate the Operation structs at compile time.
pub const OpSpec = struct {
/// Operation name (e.g., "ADD", "MUL")
name: []const u8,
/// Opcode byte value (0x00-0xFF)
opcode: u8,
/// Execution function
execute: Operation.ExecutionFunc,
/// Base gas cost
gas: u64,
/// Minimum stack items required
min_stack: u32,
/// Maximum stack size allowed (usually Stack.CAPACITY or Stack.CAPACITY - 1)
max_stack: u32,
/// Optional: for hardfork variants, specify which variant this is
variant: ?Hardfork = null,
};
/// Complete specification of all EVM execution.
/// This replaces the scattered Operation definitions across multiple files.
pub const ALL_OPERATIONS = [_]OpSpec{
// 0x00s: Stop and Arithmetic Operations
.{ .name = "STOP", .opcode = 0x00, .execute = execution.control.op_stop, .gas = 0, .min_stack = 0, .max_stack = Stack.CAPACITY },
.{ .name = "ADD", .opcode = 0x01, .execute = execution.arithmetic.op_add, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "MUL", .opcode = 0x02, .execute = execution.arithmetic.op_mul, .gas = gas_constants.GasFastStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "SUB", .opcode = 0x03, .execute = execution.arithmetic.op_sub, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "DIV", .opcode = 0x04, .execute = execution.arithmetic.op_div, .gas = gas_constants.GasFastStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "SDIV", .opcode = 0x05, .execute = execution.arithmetic.op_sdiv, .gas = gas_constants.GasFastStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "MOD", .opcode = 0x06, .execute = execution.arithmetic.op_mod, .gas = gas_constants.GasFastStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "SMOD", .opcode = 0x07, .execute = execution.arithmetic.op_smod, .gas = gas_constants.GasFastStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "ADDMOD", .opcode = 0x08, .execute = execution.arithmetic.op_addmod, .gas = gas_constants.GasMidStep, .min_stack = 3, .max_stack = Stack.CAPACITY },
.{ .name = "MULMOD", .opcode = 0x09, .execute = execution.arithmetic.op_mulmod, .gas = gas_constants.GasMidStep, .min_stack = 3, .max_stack = Stack.CAPACITY },
.{ .name = "EXP", .opcode = 0x0a, .execute = execution.arithmetic.op_exp, .gas = 10, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "SIGNEXTEND", .opcode = 0x0b, .execute = execution.arithmetic.op_signextend, .gas = gas_constants.GasFastStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
// 0x10s: Comparison & Bitwise Logic Operations
.{ .name = "LT", .opcode = 0x10, .execute = execution.comparison.op_lt, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "GT", .opcode = 0x11, .execute = execution.comparison.op_gt, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "SLT", .opcode = 0x12, .execute = execution.comparison.op_slt, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "SGT", .opcode = 0x13, .execute = execution.comparison.op_sgt, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "EQ", .opcode = 0x14, .execute = execution.comparison.op_eq, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "ISZERO", .opcode = 0x15, .execute = execution.comparison.op_iszero, .gas = gas_constants.GasFastestStep, .min_stack = 1, .max_stack = Stack.CAPACITY },
.{ .name = "AND", .opcode = 0x16, .execute = execution.bitwise.op_and, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "OR", .opcode = 0x17, .execute = execution.bitwise.op_or, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "XOR", .opcode = 0x18, .execute = execution.bitwise.op_xor, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "NOT", .opcode = 0x19, .execute = execution.bitwise.op_not, .gas = gas_constants.GasFastestStep, .min_stack = 1, .max_stack = Stack.CAPACITY },
.{ .name = "BYTE", .opcode = 0x1a, .execute = execution.bitwise.op_byte, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "SHL", .opcode = 0x1b, .execute = execution.bitwise.op_shl, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY, .variant = .CONSTANTINOPLE },
.{ .name = "SHR", .opcode = 0x1c, .execute = execution.bitwise.op_shr, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY, .variant = .CONSTANTINOPLE },
.{ .name = "SAR", .opcode = 0x1d, .execute = execution.bitwise.op_sar, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY, .variant = .CONSTANTINOPLE },
// 0x20s: Crypto
.{ .name = "SHA3", .opcode = 0x20, .execute = execution.crypto.op_sha3, .gas = gas_constants.Keccak256Gas, .min_stack = 2, .max_stack = Stack.CAPACITY },
// 0x30s: Environmental Information
.{ .name = "ADDRESS", .opcode = 0x30, .execute = execution.environment.op_address, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "BALANCE_FRONTIER", .opcode = 0x31, .execute = execution.environment.op_balance, .gas = 20, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .FRONTIER },
.{ .name = "BALANCE_TANGERINE", .opcode = 0x31, .execute = execution.environment.op_balance, .gas = 400, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .TANGERINE_WHISTLE },
.{ .name = "BALANCE_ISTANBUL", .opcode = 0x31, .execute = execution.environment.op_balance, .gas = 700, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .ISTANBUL },
.{ .name = "BALANCE_BERLIN", .opcode = 0x31, .execute = execution.environment.op_balance, .gas = 0, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .BERLIN },
.{ .name = "ORIGIN", .opcode = 0x32, .execute = execution.environment.op_origin, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "CALLER", .opcode = 0x33, .execute = execution.environment.op_caller, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "CALLVALUE", .opcode = 0x34, .execute = execution.environment.op_callvalue, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "CALLDATALOAD", .opcode = 0x35, .execute = execution.environment.op_calldataload, .gas = gas_constants.GasFastestStep, .min_stack = 1, .max_stack = Stack.CAPACITY },
.{ .name = "CALLDATASIZE", .opcode = 0x36, .execute = execution.environment.op_calldatasize, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "CALLDATACOPY", .opcode = 0x37, .execute = execution.memory.op_calldatacopy, .gas = gas_constants.GasFastestStep, .min_stack = 3, .max_stack = Stack.CAPACITY },
.{ .name = "CODESIZE", .opcode = 0x38, .execute = execution.environment.op_codesize, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "CODECOPY", .opcode = 0x39, .execute = execution.environment.op_codecopy, .gas = gas_constants.GasFastestStep, .min_stack = 3, .max_stack = Stack.CAPACITY },
.{ .name = "GASPRICE", .opcode = 0x3a, .execute = execution.environment.op_gasprice, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "EXTCODESIZE_FRONTIER", .opcode = 0x3b, .execute = execution.environment.op_extcodesize, .gas = 20, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .FRONTIER },
.{ .name = "EXTCODESIZE_TANGERINE", .opcode = 0x3b, .execute = execution.environment.op_extcodesize, .gas = 700, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .TANGERINE_WHISTLE },
.{ .name = "EXTCODESIZE_ISTANBUL", .opcode = 0x3b, .execute = execution.environment.op_extcodesize, .gas = 700, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .ISTANBUL },
.{ .name = "EXTCODESIZE", .opcode = 0x3b, .execute = execution.environment.op_extcodesize, .gas = 0, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .BERLIN },
.{ .name = "EXTCODECOPY_FRONTIER", .opcode = 0x3c, .execute = execution.environment.op_extcodecopy, .gas = 20, .min_stack = 4, .max_stack = Stack.CAPACITY, .variant = .FRONTIER },
.{ .name = "EXTCODECOPY_TANGERINE", .opcode = 0x3c, .execute = execution.environment.op_extcodecopy, .gas = 700, .min_stack = 4, .max_stack = Stack.CAPACITY, .variant = .TANGERINE_WHISTLE },
.{ .name = "EXTCODECOPY_ISTANBUL", .opcode = 0x3c, .execute = execution.environment.op_extcodecopy, .gas = 700, .min_stack = 4, .max_stack = Stack.CAPACITY, .variant = .ISTANBUL },
.{ .name = "EXTCODECOPY", .opcode = 0x3c, .execute = execution.environment.op_extcodecopy, .gas = 0, .min_stack = 4, .max_stack = Stack.CAPACITY, .variant = .BERLIN },
.{ .name = "RETURNDATASIZE", .opcode = 0x3d, .execute = execution.memory.op_returndatasize, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1, .variant = .BYZANTIUM },
.{ .name = "RETURNDATACOPY", .opcode = 0x3e, .execute = execution.memory.op_returndatacopy, .gas = gas_constants.GasFastestStep, .min_stack = 3, .max_stack = Stack.CAPACITY, .variant = .BYZANTIUM },
.{ .name = "EXTCODEHASH", .opcode = 0x3f, .execute = execution.environment.op_extcodehash, .gas = 0, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .CONSTANTINOPLE },
// 0x40s: Block Information
.{ .name = "BLOCKHASH", .opcode = 0x40, .execute = execution.block.op_blockhash, .gas = 20, .min_stack = 1, .max_stack = Stack.CAPACITY },
.{ .name = "COINBASE", .opcode = 0x41, .execute = execution.block.op_coinbase, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "TIMESTAMP", .opcode = 0x42, .execute = execution.block.op_timestamp, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "NUMBER", .opcode = 0x43, .execute = execution.block.op_number, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "DIFFICULTY", .opcode = 0x44, .execute = execution.block.op_difficulty, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "GASLIMIT", .opcode = 0x45, .execute = execution.block.op_gaslimit, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "CHAINID", .opcode = 0x46, .execute = execution.environment.op_chainid, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1, .variant = .ISTANBUL },
.{ .name = "SELFBALANCE", .opcode = 0x47, .execute = execution.environment.op_selfbalance, .gas = gas_constants.GasFastStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1, .variant = .ISTANBUL },
.{ .name = "BASEFEE", .opcode = 0x48, .execute = execution.block.op_basefee, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1, .variant = .LONDON },
.{ .name = "BLOBHASH", .opcode = 0x49, .execute = execution.block.op_blobhash, .gas = gas_constants.BlobHashGas, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .CANCUN },
.{ .name = "BLOBBASEFEE", .opcode = 0x4a, .execute = execution.block.op_blobbasefee, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1, .variant = .CANCUN },
// 0x50s: Stack, Memory, Storage and Flow Operations
.{ .name = "POP", .opcode = 0x50, .execute = execution.stack.op_pop, .gas = gas_constants.GasQuickStep, .min_stack = 1, .max_stack = Stack.CAPACITY },
.{ .name = "MLOAD", .opcode = 0x51, .execute = execution.memory.op_mload, .gas = gas_constants.GasFastestStep, .min_stack = 1, .max_stack = Stack.CAPACITY },
.{ .name = "MSTORE", .opcode = 0x52, .execute = execution.memory.op_mstore, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "MSTORE8", .opcode = 0x53, .execute = execution.memory.op_mstore8, .gas = gas_constants.GasFastestStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "SLOAD_FRONTIER", .opcode = 0x54, .execute = execution.storage.op_sload, .gas = 50, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .FRONTIER },
.{ .name = "SLOAD_TANGERINE", .opcode = 0x54, .execute = execution.storage.op_sload, .gas = 200, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .TANGERINE_WHISTLE },
.{ .name = "SLOAD_ISTANBUL", .opcode = 0x54, .execute = execution.storage.op_sload, .gas = 800, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .ISTANBUL },
.{ .name = "SLOAD", .opcode = 0x54, .execute = execution.storage.op_sload, .gas = 0, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .BERLIN },
.{ .name = "SSTORE", .opcode = 0x55, .execute = execution.storage.op_sstore, .gas = 0, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "JUMP", .opcode = 0x56, .execute = execution.control.op_jump, .gas = gas_constants.GasMidStep, .min_stack = 1, .max_stack = Stack.CAPACITY },
.{ .name = "JUMPI", .opcode = 0x57, .execute = execution.control.op_jumpi, .gas = gas_constants.GasSlowStep, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "PC", .opcode = 0x58, .execute = execution.control.op_pc, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "MSIZE", .opcode = 0x59, .execute = execution.memory.op_msize, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "GAS", .opcode = 0x5a, .execute = execution.system.gas_op, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "JUMPDEST", .opcode = 0x5b, .execute = execution.control.op_jumpdest, .gas = gas_constants.JumpdestGas, .min_stack = 0, .max_stack = Stack.CAPACITY },
.{ .name = "TLOAD", .opcode = 0x5c, .execute = execution.storage.op_tload, .gas = gas_constants.WarmStorageReadCost, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .CANCUN },
.{ .name = "TSTORE", .opcode = 0x5d, .execute = execution.storage.op_tstore, .gas = gas_constants.WarmStorageReadCost, .min_stack = 2, .max_stack = Stack.CAPACITY, .variant = .CANCUN },
.{ .name = "MCOPY", .opcode = 0x5e, .execute = execution.memory.op_mcopy, .gas = gas_constants.GasFastestStep, .min_stack = 3, .max_stack = Stack.CAPACITY, .variant = .CANCUN },
.{ .name = "PUSH0", .opcode = 0x5f, .execute = execution.stack.op_push0, .gas = gas_constants.GasQuickStep, .min_stack = 0, .max_stack = Stack.CAPACITY - 1, .variant = .SHANGHAI },
// 0x60s & 0x70s: Push operations (generated dynamically in jump table)
// 0x80s: Duplication operations (generated dynamically in jump table)
// 0x90s: Exchange operations (generated dynamically in jump table)
// 0xa0s: Logging operations (generated dynamically in jump table)
// 0xf0s: System operations
.{ .name = "CREATE", .opcode = 0xf0, .execute = execution.system.op_create, .gas = gas_constants.CreateGas, .min_stack = 3, .max_stack = Stack.CAPACITY - 1 },
.{ .name = "CALL_FRONTIER", .opcode = 0xf1, .execute = execution.system.op_call, .gas = 40, .min_stack = 7, .max_stack = Stack.CAPACITY - 1, .variant = .FRONTIER },
.{ .name = "CALL", .opcode = 0xf1, .execute = execution.system.op_call, .gas = 700, .min_stack = 7, .max_stack = Stack.CAPACITY - 1, .variant = .TANGERINE_WHISTLE },
.{ .name = "CALLCODE_FRONTIER", .opcode = 0xf2, .execute = execution.system.op_callcode, .gas = 40, .min_stack = 7, .max_stack = Stack.CAPACITY - 1, .variant = .FRONTIER },
.{ .name = "CALLCODE", .opcode = 0xf2, .execute = execution.system.op_callcode, .gas = 700, .min_stack = 7, .max_stack = Stack.CAPACITY - 1, .variant = .TANGERINE_WHISTLE },
.{ .name = "RETURN", .opcode = 0xf3, .execute = execution.control.op_return, .gas = 0, .min_stack = 2, .max_stack = Stack.CAPACITY },
.{ .name = "DELEGATECALL", .opcode = 0xf4, .execute = execution.system.op_delegatecall, .gas = 40, .min_stack = 6, .max_stack = Stack.CAPACITY - 1, .variant = .HOMESTEAD },
.{ .name = "DELEGATECALL_TANGERINE", .opcode = 0xf4, .execute = execution.system.op_delegatecall, .gas = 700, .min_stack = 6, .max_stack = Stack.CAPACITY - 1, .variant = .TANGERINE_WHISTLE },
.{ .name = "CREATE2", .opcode = 0xf5, .execute = execution.system.op_create2, .gas = gas_constants.CreateGas, .min_stack = 4, .max_stack = Stack.CAPACITY - 1, .variant = .CONSTANTINOPLE },
.{ .name = "STATICCALL", .opcode = 0xfa, .execute = execution.system.op_staticcall, .gas = 700, .min_stack = 6, .max_stack = Stack.CAPACITY - 1, .variant = .BYZANTIUM },
.{ .name = "REVERT", .opcode = 0xfd, .execute = execution.control.op_revert, .gas = 0, .min_stack = 2, .max_stack = Stack.CAPACITY, .variant = .BYZANTIUM },
.{ .name = "INVALID", .opcode = 0xfe, .execute = execution.control.op_invalid, .gas = 0, .min_stack = 0, .max_stack = Stack.CAPACITY },
.{ .name = "SELFDESTRUCT_FRONTIER", .opcode = 0xff, .execute = execution.control.op_selfdestruct, .gas = 0, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .FRONTIER },
.{ .name = "SELFDESTRUCT", .opcode = 0xff, .execute = execution.control.op_selfdestruct, .gas = 5000, .min_stack = 1, .max_stack = Stack.CAPACITY, .variant = .TANGERINE_WHISTLE },
};
/// Generate an Operation struct from an OpSpec.
pub fn generate_operation(spec: OpSpec) Operation {
return Operation{
.execute = spec.execute,
.constant_gas = spec.gas,
.min_stack = spec.min_stack,
.max_stack = spec.max_stack,
};
}
```
```zig [src/evm/jump_table/jump_table.zig]
const std = @import("std");
const Opcode = @import("../opcodes/opcode.zig");
const Operation = @import("../opcodes/operation.zig");
const Hardfork = @import("../hardforks/hardfork.zig").Hardfork;
const ExecutionError = @import("../execution/execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Memory = @import("../memory.zig");
const Frame = @import("../frame.zig");
const Contract = @import("../contract/contract.zig");
const Address = @import("Address");
const Log = @import("../log.zig");
const execution = @import("../execution/package.zig");
const stack_ops = execution.stack;
const log = execution.log;
const operation_config = @import("operation_config.zig");
/// EVM jump table for efficient opcode dispatch.
///
/// The jump table is a critical performance optimization that maps opcodes
/// to their execution handlers. Instead of using a switch statement with
/// 256 cases, the jump table provides O(1) dispatch by indexing directly
/// into an array of function pointers.
///
/// ## Design Rationale
/// - Array indexing is faster than switch statement branching
/// - Cache-line alignment improves memory access patterns
/// - Hardfork-specific tables allow for efficient versioning
/// - Null entries default to UNDEFINED operation
///
/// ## Hardfork Evolution
/// The jump table evolves with each hardfork:
/// - New opcodes are added (e.g., PUSH0 in Shanghai)
/// - Gas costs change (e.g., SLOAD in Berlin)
/// - Opcodes are removed or modified
///
/// ## Performance Considerations
/// - 64-byte cache line alignment reduces cache misses
/// - Direct indexing eliminates branch prediction overhead
/// - Operation structs are immutable for thread safety
///
/// Example:
/// ```zig
/// const table = JumpTable.init_from_hardfork(.CANCUN);
/// const opcode = bytecode[pc];
/// const operation = table.get_operation(opcode);
/// const result = try table.execute(pc, interpreter, state, opcode);
/// ```
const Self = @This();
/// CPU cache line size for optimal memory alignment.
/// Most modern x86/ARM processors use 64-byte cache lines.
const CACHE_LINE_SIZE = 64;
/// Array of operation handlers indexed by opcode value.
/// Aligned to cache line boundaries for optimal performance.
/// Null entries are treated as undefined opcodes.
table: [256]?*const Operation align(CACHE_LINE_SIZE),
/// CANCUN jump table, pre-generated at compile time.
/// This is the latest hardfork configuration.
pub const CANCUN = init_from_hardfork(.CANCUN);
/// Default jump table for the latest hardfork.
/// References CANCUN to avoid generating the same table twice.
/// This is what gets used when no jump table is specified.
pub const DEFAULT = CANCUN;
/// Create an empty jump table with all entries set to null.
///
/// This creates a blank jump table that must be populated with
/// operations before use. Typically, you'll want to use
/// init_from_hardfork() instead to get a pre-configured table.
///
/// @return An empty jump table
pub fn init() Self {
return Self{
.table = [_]?*const Operation{null} ** 256,
};
}
/// Get the operation handler for a given opcode.
///
/// Returns the operation associated with the opcode, or the NULL
/// operation if the opcode is undefined in this jump table.
///
/// @param self The jump table
/// @param opcode The opcode byte value (0x00-0xFF)
/// @return Operation handler (never null)
///
/// Example:
/// ```zig
/// const op = table.get_operation(0x01); // Get ADD operation
/// ```
pub fn get_operation(self: *const Self, opcode: u8) *const Operation {
return self.table[opcode] orelse &Operation.NULL;
}
/// Execute an opcode using the jump table.
///
/// This is the main dispatch function that:
/// 1. Looks up the operation for the opcode
/// 2. Validates stack requirements
/// 3. Consumes gas
/// 4. Executes the operation
///
/// @param self The jump table
/// @param pc Current program counter
/// @param interpreter VM interpreter context
/// @param state Execution state (cast to Frame internally)
/// @param opcode The opcode to execute
/// @return Execution result with gas consumed
/// @throws InvalidOpcode if opcode is undefined
/// @throws StackUnderflow/Overflow if validation fails
/// @throws OutOfGas if insufficient gas
///
/// Example:
/// ```zig
/// const result = try table.execute(pc, &interpreter, &state, bytecode[pc]);
/// ```
pub fn execute(self: *const Self, pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State, opcode: u8) ExecutionError.Error!Operation.ExecutionResult {
@branchHint(.likely);
const operation = self.get_operation(opcode);
// Cast state to Frame to access gas_remaining and stack
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
Log.debug("JumpTable.execute: Executing opcode 0x{x:0>2} at pc={}, gas={}, stack_size={}", .{ opcode, pc, frame.gas_remaining, frame.stack.size });
if (operation.undefined) {
@branchHint(.cold);
Log.debug("JumpTable.execute: Invalid opcode 0x{x:0>2}", .{opcode});
frame.gas_remaining = 0;
return ExecutionError.Error.InvalidOpcode;
}
const stack_validation = @import("../stack/stack_validation.zig");
try stack_validation.validate_stack_requirements(&frame.stack, operation);
if (operation.constant_gas > 0) {
@branchHint(.likely);
Log.debug("JumpTable.execute: Consuming {} gas for opcode 0x{x:0>2}", .{ operation.constant_gas, opcode });
try frame.consume_gas(operation.constant_gas);
}
const res = try operation.execute(pc, interpreter, state);
Log.debug("JumpTable.execute: Opcode 0x{x:0>2} completed, gas_remaining={}", .{ opcode, frame.gas_remaining });
return res;
}
/// Validate and fix the jump table.
///
/// Ensures all entries are valid:
/// - Null entries are replaced with UNDEFINED operation
/// - Operations with memory_size must have dynamic_gas
/// - Invalid operations are logged and replaced
///
/// This should be called after manually constructing a jump table
/// to ensure it's safe for execution.
///
/// @param self The jump table to validate
pub fn validate(self: *Self) void {
for (0..256) |i| {
if (self.table[i] == null) {
@branchHint(.cold);
self.table[i] = &Operation.NULL;
} else if (self.table[i].?.memory_size != null and self.table[i].?.dynamic_gas == null) {
@branchHint(.likely);
// Log error instead of panicking
std.debug.print("Warning: Operation 0x{x} has memory size but no dynamic gas calculation\n", .{i});
// Set to NULL to prevent issues
self.table[i] = &Operation.NULL;
}
}
}
pub fn copy(self: *const Self, allocator: std.mem.Allocator) !Self {
_ = allocator;
return Self{
.table = self.table,
};
}
/// Create a jump table configured for a specific hardfork.
///
/// This is the primary way to create a jump table. It starts with
/// the Frontier base configuration and applies all changes up to
/// the specified hardfork.
///
/// @param hardfork The target hardfork configuration
/// @return A fully configured jump table
///
/// Hardfork progression:
/// - FRONTIER: Base EVM opcodes
/// - HOMESTEAD: DELEGATECALL
/// - TANGERINE_WHISTLE: Gas repricing (EIP-150)
/// - BYZANTIUM: REVERT, RETURNDATASIZE, STATICCALL
/// - CONSTANTINOPLE: CREATE2, SHL/SHR/SAR, EXTCODEHASH
/// - ISTANBUL: CHAINID, SELFBALANCE, more gas changes
/// - BERLIN: Access lists, cold/warm storage
/// - LONDON: BASEFEE
/// - SHANGHAI: PUSH0
/// - CANCUN: BLOBHASH, MCOPY, transient storage
///
/// Example:
/// ```zig
/// const table = JumpTable.init_from_hardfork(.CANCUN);
/// // Table includes all opcodes through Cancun
/// ```
pub fn init_from_hardfork(hardfork: Hardfork) Self {
@setEvalBranchQuota(10000);
var jt = Self.init();
// With ALL_OPERATIONS sorted by hardfork, we can iterate once.
// Each opcode will be set to the latest active version for the target hardfork.
inline for (operation_config.ALL_OPERATIONS) |spec| {
const op_hardfork = spec.variant orelse Hardfork.FRONTIER;
if (@intFromEnum(op_hardfork) <= @intFromEnum(hardfork)) {
const op = struct {
pub const operation = operation_config.generate_operation(spec);
};
jt.table[spec.opcode] = &op.operation;
}
}
// 0x60s & 0x70s: Push operations
inline for (0..32) |i| {
const n = i + 1;
jt.table[0x60 + i] = &Operation{
.execute = stack_ops.make_push(n),
.constant_gas = execution.gas_constants.GasFastestStep,
.min_stack = 0,
.max_stack = Stack.CAPACITY - 1,
};
}
// 0x80s: Duplication Operations
inline for (1..17) |n| {
jt.table[0x80 + n - 1] = &Operation{
.execute = stack_ops.make_dup(n),
.constant_gas = execution.gas_constants.GasFastestStep,
.min_stack = @intCast(n),
.max_stack = Stack.CAPACITY - 1,
};
}
// 0x90s: Exchange Operations
inline for (1..17) |n| {
jt.table[0x90 + n - 1] = &Operation{
.execute = stack_ops.make_swap(n),
.constant_gas = execution.gas_constants.GasFastestStep,
.min_stack = @intCast(n + 1),
.max_stack = Stack.CAPACITY,
};
}
// 0xa0s: Logging Operations
inline for (0..5) |n| {
jt.table[0xa0 + n] = &Operation{
.execute = log.make_log(n),
.constant_gas = execution.gas_constants.LogGas + execution.gas_constants.LogTopicGas * n,
.min_stack = @intCast(n + 2),
.max_stack = Stack.CAPACITY,
};
}
jt.validate();
return jt;
}
```
```zig [src/evm/contract/bitvec.zig]
const std = @import("std");
const constants = @import("../constants/constants.zig");
/// BitVec is a bit vector implementation used for tracking JUMPDEST positions in bytecode
const Self = @This();
/// Bit array stored in u64 chunks
bits: []u64,
/// Total length in bits
size: usize,
/// Whether this bitvec owns its memory (and should free it)
owned: bool,
/// Error types for BitVec operations
pub const BitVecError = error{
/// Position is out of bounds for the bit vector
PositionOutOfBounds,
};
/// Error type for BitVec initialization
pub const BitVecInitError = std.mem.Allocator.Error;
/// Error type for code bitmap creation
pub const CodeBitmapError = BitVecInitError;
/// Create a new BitVec with the given size
pub fn init(allocator: std.mem.Allocator, size: usize) BitVecInitError!Self {
const u64_size = (size + 63) / 64; // Round up to nearest u64
const bits = try allocator.alloc(u64, u64_size);
@memset(bits, 0); // Initialize all bits to 0
return Self{
.bits = bits,
.size = size,
.owned = true,
};
}
/// Create a BitVec from existing memory (not owned)
pub fn from_memory(bits: []u64, size: usize) Self {
return Self{
.bits = bits,
.size = size,
.owned = false,
};
}
/// Free allocated memory if owned
pub fn deinit(self: *Self, allocator: std.mem.Allocator) void {
if (self.owned) {
allocator.free(self.bits);
self.bits = &.{};
self.size = 0;
}
}
/// Set a bit at the given position
pub fn set(self: *Self, pos: usize) BitVecError!void {
if (pos >= self.size) return BitVecError.PositionOutOfBounds;
const idx = pos / 64;
const bit = @as(u64, 1) << @intCast(pos % 64);
self.bits[idx] |= bit;
}
/// Set a bit at the given position without bounds checking
pub fn set_unchecked(self: *Self, pos: usize) void {
const idx = pos / 64;
const bit = @as(u64, 1) << @intCast(pos % 64);
self.bits[idx] |= bit;
}
/// Clear a bit at the given position
pub fn clear(self: *Self, pos: usize) BitVecError!void {
if (pos >= self.size) return BitVecError.PositionOutOfBounds;
const idx = pos / 64;
const bit = @as(u64, 1) << @intCast(pos % 64);
self.bits[idx] &= ~bit;
}
/// Clear a bit at the given position without bounds checking
pub fn clear_unchecked(self: *Self, pos: usize) void {
const idx = pos / 64;
const bit = @as(u64, 1) << @intCast(pos % 64);
self.bits[idx] &= ~bit;
}
/// Check if a bit is set at the given position
pub fn is_set(self: *const Self, pos: usize) BitVecError!bool {
if (pos >= self.size) return BitVecError.PositionOutOfBounds;
const idx = pos / 64;
const bit = @as(u64, 1) << @intCast(pos % 64);
return (self.bits[idx] & bit) != 0;
}
/// Check if a bit is set at the given position without bounds checking
pub fn is_set_unchecked(self: *const Self, pos: usize) bool {
const idx = pos / 64;
const bit = @as(u64, 1) << @intCast(pos % 64);
return (self.bits[idx] & bit) != 0;
}
/// Check if the position represents a valid code segment
pub fn code_segment(self: *const Self, pos: usize) BitVecError!bool {
return self.is_set(pos);
}
/// Check if the position represents a valid code segment without bounds checking
pub fn code_segment_unchecked(self: *const Self, pos: usize) bool {
return self.is_set_unchecked(pos);
}
/// Analyze bytecode to identify valid JUMPDEST locations and code segments
pub fn code_bitmap(allocator: std.mem.Allocator, code: []const u8) CodeBitmapError!Self {
var bitmap = try Self.init(allocator, code.len);
errdefer bitmap.deinit(allocator);
// Mark all positions as valid code initially
for (0..code.len) |i| {
bitmap.set_unchecked(i);
}
var i: usize = 0;
while (i < code.len) {
const op = code[i];
// If the opcode is a PUSH, skip the pushed bytes
if (constants.is_push(op)) {
const push_bytes = constants.get_push_size(op); // Get number of bytes to push
// Mark pushed bytes as data (not code)
var j: usize = 1;
while (j <= push_bytes and i + j < code.len) : (j += 1) {
bitmap.clear_unchecked(i + j);
}
// Skip the pushed bytes
if (i + push_bytes + 1 < code.len) {
i += push_bytes + 1;
} else {
i = code.len;
}
} else {
i += 1;
}
}
return bitmap;
}
```
```zig [src/evm/contract/eip_7702_bytecode.zig]
const Address = @import("Address");
/// Magic bytes that identify EIP-7702 delegated code
///
/// EIP-7702 introduces a new transaction type that allows EOAs (Externally Owned Accounts)
/// to temporarily delegate their code execution to a contract address. This is marked
/// by prepending the contract address with these magic bytes: 0xE7 0x02
pub const EIP7702_MAGIC_BYTES = [2]u8{ 0xE7, 0x02 };
/// EIP-7702 bytecode representation for delegated EOA code
///
/// This struct represents the bytecode format introduced by EIP-7702, which allows
/// EOAs to delegate their code execution to a contract address. The bytecode format
/// consists of the magic bytes (0xE7, 0x02) followed by a 20-byte address.
///
/// ## EIP-7702 Overview
///
/// EIP-7702 enables EOAs to temporarily act like smart contracts by delegating
/// their code execution to an existing contract. This is useful for:
/// - Account abstraction without deploying new contracts
/// - Batched transactions from EOAs
/// - Sponsored transactions
/// - Enhanced wallet functionality
///
/// ## Bytecode Format
///
/// The delegated bytecode format is exactly 22 bytes:
/// - Bytes 0-1: Magic bytes (0xE7, 0x02)
/// - Bytes 2-21: Contract address to delegate to
///
/// When the EVM encounters this bytecode format, it executes the code at the
/// specified contract address in the context of the EOA.
const Self = @This();
/// The contract address that this EOA delegates execution to
address: Address.Address,
/// Creates a new EIP-7702 bytecode representation
///
/// ## Parameters
/// - `address`: The contract address to delegate execution to
///
/// ## Returns
/// A new EIP7702Bytecode instance
///
/// ## Example
/// ```zig
/// const delegate_address = Address.from_hex("0x742d35Cc6634C0532925a3b844Bc9e7595f62d3c");
/// const bytecode = EIP7702Bytecode.new(delegate_address);
/// ```
pub fn new(address: Address.Address) Self {
return .{ .address = address };
}
/// Creates an EIP-7702 bytecode representation from raw bytes
///
/// Parses the bytecode format to extract the delegation address.
/// This function expects the input to include the magic bytes.
///
/// ## Parameters
/// - `bytes`: Raw bytecode bytes, should be at least 22 bytes (2 magic + 20 address)
///
/// ## Returns
/// A new EIP7702Bytecode instance
///
/// ## Errors
/// Currently this function doesn't validate the magic bytes or length,
/// but may return malformed results if the input is invalid.
///
/// ## Example
/// ```zig
/// const raw_bytecode = &[_]u8{0xE7, 0x02} ++ address_bytes;
/// const bytecode = try EIP7702Bytecode.new_raw(raw_bytecode);
/// ```
pub fn new_raw(bytes: []const u8) !Self {
var address: Address.Address = undefined;
if (bytes.len > 20) {
@memcpy(&address, bytes[2..22]);
}
return Self.new(address);
}
/// Returns the raw bytecode representation
///
/// **NOTE**: This function is currently incomplete and returns an empty slice.
/// It should return the full 22-byte bytecode including magic bytes and address.
///
/// ## Parameters
/// - `self`: The EIP7702Bytecode instance
///
/// ## Returns
/// The raw bytecode bytes (currently returns empty slice - TODO: implement properly)
///
/// ## TODO
/// This function should be implemented to return:
/// - Bytes 0-1: EIP7702_MAGIC_BYTES
/// - Bytes 2-21: The delegation address
pub fn raw(self: *const Self) []const u8 {
_ = self;
return &[_]u8{};
}
```
```zig [src/evm/contract/storage_pool.zig]
const std = @import("std");
/// Object pool for EVM storage-related hash maps to reduce allocation pressure.
///
/// The StoragePool manages reusable hash maps for storage slot tracking and access
/// patterns, significantly reducing allocation/deallocation overhead during EVM
/// execution. This is particularly important for contracts that make heavy use
/// of storage operations.
///
/// ## Design Rationale
/// EVM execution frequently creates and destroys hash maps for:
/// - Tracking which storage slots have been accessed (warm/cold for EIP-2929)
/// - Storing original storage values for gas refund calculations
///
/// Rather than allocating new maps for each contract call, this pool maintains
/// a cache of cleared maps ready for reuse.
///
/// ## Usage Pattern
/// ```zig
/// var pool = StoragePool.init(allocator);
/// defer pool.deinit();
///
/// // Borrow a map
/// const map = try pool.borrow_storage_map();
/// defer pool.return_storage_map(map);
///
/// // Use the map for storage operations
/// try map.put(slot, value);
/// ```
///
/// ## Thread Safety
/// This pool is NOT thread-safe. Each thread should maintain its own pool
/// or use external synchronization.
const Self = @This();
/// Pool of reusable access tracking maps (slot -> accessed flag)
access_maps: std.ArrayList(*std.AutoHashMap(u256, bool)),
/// Pool of reusable storage value maps (slot -> value)
storage_maps: std.ArrayList(*std.AutoHashMap(u256, u256)),
/// Allocator used for creating new maps when pool is empty
allocator: std.mem.Allocator,
/// Initialize a new storage pool.
///
/// @param allocator The allocator to use for creating new maps
/// @return A new StoragePool instance
///
/// Example:
/// ```zig
/// var pool = StoragePool.init(allocator);
/// defer pool.deinit();
/// ```
pub fn init(allocator: std.mem.Allocator) Self {
return .{
.access_maps = std.ArrayList(*std.AutoHashMap(u256, bool)).init(allocator),
.storage_maps = std.ArrayList(*std.AutoHashMap(u256, u256)).init(allocator),
.allocator = allocator,
};
}
/// Clean up the storage pool and all contained maps.
///
/// This function destroys all pooled maps and frees their memory.
/// After calling deinit, the pool should not be used.
///
/// Note: Any maps currently borrowed from the pool will become invalid
/// after deinit. Ensure all borrowed maps are returned before calling this.
pub fn deinit(self: *Self) void {
// Clean up any remaining maps
for (self.access_maps.items) |map| {
map.deinit();
self.allocator.destroy(map);
}
for (self.storage_maps.items) |map| {
map.deinit();
self.allocator.destroy(map);
}
self.access_maps.deinit();
self.storage_maps.deinit();
}
/// Error type for access map borrowing operations
pub const BorrowAccessMapError = error{
/// Allocator failed to allocate memory for a new map
OutOfAllocatorMemory,
};
/// Borrow an access tracking map from the pool.
///
/// Access maps track which storage slots have been accessed during execution,
/// used for EIP-2929 warm/cold access gas pricing.
///
/// If the pool has available maps, one is returned immediately.
/// Otherwise, a new map is allocated.
///
/// @return A cleared hash map ready for use
/// @throws OutOfAllocatorMemory if allocation fails
///
/// Example:
/// ```zig
/// const access_map = try pool.borrow_access_map();
/// defer pool.return_access_map(access_map);
///
/// // Track storage slot access
/// try access_map.put(slot, true);
/// const was_accessed = access_map.get(slot) orelse false;
/// ```
pub fn borrow_access_map(self: *Self) BorrowAccessMapError!*std.AutoHashMap(u256, bool) {
if (self.access_maps.items.len > 0) return self.access_maps.pop() orelse unreachable;
const map = self.allocator.create(std.AutoHashMap(u256, bool)) catch {
return BorrowAccessMapError.OutOfAllocatorMemory;
};
map.* = std.AutoHashMap(u256, bool).init(self.allocator);
return map;
}
/// Return an access map to the pool for reuse.
///
/// The map is cleared but its capacity is retained to avoid
/// reallocation on next use. If the pool fails to store the
/// returned map (due to memory pressure), it is silently discarded.
///
/// @param map The map to return to the pool
///
/// Note: The map should not be used after returning it to the pool.
pub fn return_access_map(self: *Self, map: *std.AutoHashMap(u256, bool)) void {
map.clearRetainingCapacity();
self.access_maps.append(map) catch {};
}
/// Error type for storage map borrowing operations
pub const BorrowStorageMapError = error{
/// Allocator failed to allocate memory for a new map
OutOfAllocatorMemory,
};
/// Borrow a storage value map from the pool.
///
/// Storage maps store slot values, typically used for tracking original
/// values to calculate gas refunds or implement storage rollback.
///
/// If the pool has available maps, one is returned immediately.
/// Otherwise, a new map is allocated.
///
/// @return A cleared hash map ready for use
/// @throws OutOfAllocatorMemory if allocation fails
///
/// Example:
/// ```zig
/// const storage_map = try pool.borrow_storage_map();
/// defer pool.return_storage_map(storage_map);
///
/// // Store original value before modification
/// try storage_map.put(slot, original_value);
/// ```
pub fn borrow_storage_map(self: *Self) BorrowStorageMapError!*std.AutoHashMap(u256, u256) {
if (self.storage_maps.pop()) |map| {
return map;
}
const map = self.allocator.create(std.AutoHashMap(u256, u256)) catch {
return BorrowStorageMapError.OutOfAllocatorMemory;
};
map.* = std.AutoHashMap(u256, u256).init(self.allocator);
return map;
}
/// Return a storage map to the pool for reuse.
///
/// The map is cleared but its capacity is retained to avoid
/// reallocation on next use. If the pool fails to store the
/// returned map (due to memory pressure), it is silently discarded.
///
/// @param map The map to return to the pool
///
/// Note: The map should not be used after returning it to the pool.
pub fn return_storage_map(self: *Self, map: *std.AutoHashMap(u256, u256)) void {
map.clearRetainingCapacity();
self.storage_maps.append(map) catch {};
}
```
```zig [src/evm/contract/contract.zig]
//! Production-quality Contract module for EVM execution context.
//!
//! This module provides the core abstraction for contract execution in the EVM,
//! managing bytecode, gas accounting, storage access tracking, and JUMPDEST validation.
//! It incorporates performance optimizations from modern EVM implementations including
//! evmone, revm, and go-ethereum.
//!
//! ## Architecture
//! The Contract structure represents a single execution frame in the EVM call stack.
//! Each contract call (CALL, DELEGATECALL, STATICCALL, CREATE) creates a new Contract
//! instance that tracks its own gas, storage access, and execution state.
//!
//! ## Performance Characteristics
//! - **JUMPDEST validation**: O(log n) using binary search on pre-sorted positions
//! - **Storage access**: O(1) with warm/cold tracking for EIP-2929
//! - **Code analysis**: Cached globally with thread-safe access
//! - **Memory management**: Zero-allocation paths for common operations
//! - **Storage pooling**: Reuses hash maps to reduce allocation pressure
//!
//! ## Key Features
//! 1. **Code Analysis Caching**: Bytecode is analyzed once and cached globally
//! 2. **EIP-2929 Support**: Tracks warm/cold storage slots for gas calculation
//! 3. **Static Call Protection**: Prevents state modifications in read-only contexts
//! 4. **Gas Refund Tracking**: Manages gas refunds with EIP-3529 limits
//! 5. **Deployment Support**: Handles both CREATE and CREATE2 deployment flows
//!
//! ## Thread Safety
//! The global analysis cache uses mutex protection when multi-threaded,
//! automatically degrading to no-op mutexes in single-threaded builds.
//!
//! ## Memory Management
//! Contracts can optionally use a StoragePool to reuse hash maps across
//! multiple contract executions, significantly reducing allocation overhead
//! in high-throughput scenarios.
//!
//! ## Reference Implementations
//! - go-ethereum: https://github.com/ethereum/go-ethereum/blob/master/core/vm/contract.go
//! - revm: https://github.com/bluealloy/revm/blob/main/crates/interpreter/src/contract.rs
//! - evmone: https://github.com/ethereum/evmone/blob/master/lib/evmone/execution_state.hpp
const std = @import("std");
const constants = @import("../constants/constants.zig");
const bitvec = @import("bitvec.zig");
const Address = @import("Address");
const ExecutionError = @import("../execution/execution_error.zig");
const CodeAnalysis = @import("code_analysis.zig");
const StoragePool = @import("storage_pool.zig");
const Log = @import("../log.zig");
/// Maximum gas refund allowed (EIP-3529)
const MAX_REFUND_QUOTIENT = 5;
/// Error types for Contract operations
pub const ContractError = std.mem.Allocator.Error || StorageOperationError;
pub const StorageOperationError = error{
OutOfAllocatorMemory,
InvalidStorageOperation,
};
pub const CodeAnalysisError = std.mem.Allocator.Error;
/// Global analysis cache (simplified version)
var analysis_cache: ?std.AutoHashMap([32]u8, *CodeAnalysis) = null;
// Use conditional compilation for thread safety
const is_single_threaded = @import("builtin").single_threaded;
const Mutex = if (is_single_threaded) struct {
pub fn lock(self: *@This()) void {
_ = self;
}
pub fn unlock(self: *@This()) void {
_ = self;
}
} else std.Thread.Mutex;
var cache_mutex: Mutex = .{};
/// Contract represents the execution context for a single call frame in the EVM.
///
/// Each contract execution (whether from external transaction, internal call,
/// or contract creation) operates within its own Contract instance. This design
/// enables proper isolation, gas accounting, and state management across the
/// call stack.
const Self = @This();
// ============================================================================
// Identity and Context Fields
// ============================================================================
/// The address where this contract's code is deployed.
///
/// - For regular calls: The callee's address
/// - For DELEGATECALL: The current contract's address (code from elsewhere)
/// - For CREATE/CREATE2: Initially zero, set after address calculation
address: Address.Address,
/// The address that initiated this contract execution.
///
/// - For external transactions: The EOA that signed the transaction
/// - For internal calls: The contract that executed CALL/DELEGATECALL/etc
/// - For CREATE/CREATE2: The creating contract's address
///
/// Note: This is msg.sender in Solidity, not tx.origin
caller: Address.Address,
/// The amount of Wei sent with this contract call.
///
/// - Regular calls: Can be any amount (if not static)
/// - DELEGATECALL: Always 0 (uses parent's value)
/// - STATICCALL: Always 0 (no value transfer allowed)
/// - CREATE/CREATE2: Initial balance for new contract
value: u256,
// ============================================================================
// Code and Analysis Fields
// ============================================================================
/// The bytecode being executed in this context.
///
/// - Regular calls: The deployed contract's runtime bytecode
/// - CALLCODE/DELEGATECALL: The external contract's code
/// - CREATE/CREATE2: The initialization bytecode (constructor)
///
/// This slice is a view into existing memory, not owned by Contract.
code: []const u8,
/// Keccak256 hash of the contract bytecode.
///
/// Used for:
/// - Code analysis caching (avoids re-analyzing same bytecode)
/// - EXTCODEHASH opcode implementation
/// - CREATE2 address calculation
///
/// For deployments, this is set to zero as there's no deployed code yet.
code_hash: [32]u8,
/// Cached length of the bytecode for performance.
///
/// Storing this separately avoids repeated slice.len calls in hot paths
/// like bounds checking for PC and CODECOPY operations.
code_size: u64,
/// Optional reference to pre-computed code analysis.
///
/// Contains:
/// - JUMPDEST positions for O(log n) validation
/// - Code vs data segments (bitvector)
/// - Static analysis results (has CREATE, has SELFDESTRUCT, etc)
///
/// This is lazily computed on first jump and cached globally.
analysis: ?*const CodeAnalysis,
// ============================================================================
// Gas Tracking Fields
// ============================================================================
/// Remaining gas available for execution.
///
/// Decremented by each operation according to its gas cost.
/// If this reaches 0, execution halts with out-of-gas error.
///
/// Gas forwarding rules:
/// - CALL: Limited by 63/64 rule (EIP-150)
/// - DELEGATECALL/STATICCALL: Same rules as CALL
/// - CREATE/CREATE2: All remaining gas minus stipend
gas: u64,
/// Accumulated gas refund from storage operations.
///
/// Tracks gas to be refunded at transaction end from:
/// - SSTORE: Clearing storage slots
/// - SELFDESTRUCT: Contract destruction (pre-London)
///
/// Limited to gas_used / 5 by EIP-3529 (London hardfork).
gas_refund: u64,
// ============================================================================
// Input/Output Fields
// ============================================================================
/// Input data passed to this contract execution.
///
/// - External transactions: Transaction data field
/// - CALL/STATICCALL: Data passed in call
/// - DELEGATECALL: Data passed (preserves msg.data)
/// - CREATE/CREATE2: Constructor arguments
///
/// Accessed via CALLDATALOAD, CALLDATASIZE, CALLDATACOPY opcodes.
input: []const u8,
// ============================================================================
// Execution Flags
// ============================================================================
/// Indicates this is a contract deployment (CREATE/CREATE2).
///
/// When true:
/// - Executing initialization code (constructor)
/// - No deployed code exists at the address yet
/// - Result will be stored as contract code if successful
is_deployment: bool,
/// Indicates this is a system-level call.
///
/// System calls bypass certain checks and gas costs.
/// Used for precompiles and protocol-level operations.
is_system_call: bool,
/// Indicates read-only execution context (STATICCALL).
///
/// When true, these operations will fail:
/// - SSTORE (storage modification)
/// - LOG0-LOG4 (event emission)
/// - CREATE/CREATE2 (contract creation)
/// - SELFDESTRUCT (contract destruction)
/// - CALL with value transfer
is_static: bool,
// ============================================================================
// Storage Access Tracking (EIP-2929)
// ============================================================================
/// Tracks which storage slots have been accessed (warm vs cold).
///
/// EIP-2929 charges different gas costs:
/// - Cold access (first time): 2100 gas
/// - Warm access (subsequent): 100 gas
///
/// Key: storage slot, Value: true (accessed)
/// Can be borrowed from StoragePool for efficiency.
storage_access: ?*std.AutoHashMap(u256, bool),
/// Tracks original storage values for gas refund calculations.
///
/// Used by SSTORE to determine gas costs and refunds based on:
/// - Original value (at transaction start)
/// - Current value (in storage)
/// - New value (being set)
///
/// Key: storage slot, Value: original value
original_storage: ?*std.AutoHashMap(u256, u256),
/// Whether this contract address was cold at call start.
///
/// Used for EIP-2929 gas calculations:
/// - Cold contract: Additional 2600 gas for first access
/// - Warm contract: No additional cost
///
/// Contracts become warm after first access in a transaction.
is_cold: bool,
// ============================================================================
// Optimization Fields
// ============================================================================
/// Quick flag indicating if bytecode contains any JUMPDEST opcodes.
///
/// Enables fast-path optimization:
/// - If false, all jumps fail immediately (no valid destinations)
/// - If true, full JUMPDEST analysis is needed
///
/// Set during initialization by scanning bytecode.
has_jumpdests: bool,
/// Flag indicating empty bytecode.
///
/// Empty contracts (no code) are common in Ethereum:
/// - EOAs (externally owned accounts)
/// - Destroyed contracts
/// - Contracts that failed deployment
///
/// Enables fast-path for calls to codeless addresses.
is_empty: bool,
/// Creates a new Contract for executing existing deployed code.
///
/// This is the standard constructor for CALL, CALLCODE, DELEGATECALL,
/// and STATICCALL operations. The contract code must already exist
/// at the specified address.
///
/// ## Parameters
/// - `caller`: The address initiating this call (msg.sender)
/// - `addr`: The address where the code is deployed
/// - `value`: Wei being transferred (0 for DELEGATECALL/STATICCALL)
/// - `gas`: Gas allocated for this execution
/// - `code`: The contract bytecode to execute
/// - `code_hash`: Keccak256 hash of the bytecode
/// - `input`: Call data (function selector + arguments)
/// - `is_static`: Whether this is a read-only context
///
/// ## Example
/// ```zig
/// const contract = Contract.init(
/// caller_address,
/// contract_address,
/// value,
/// gas_limit,
/// bytecode,
/// bytecode_hash,
/// calldata,
/// false, // not static
/// );
/// ```
pub fn init(
caller: Address.Address,
addr: Address.Address,
value: u256,
gas: u64,
code: []const u8,
code_hash: [32]u8,
input: []const u8,
is_static: bool,
) Self {
return Self{
.address = addr,
.caller = caller,
.value = value,
.gas = gas,
.code = code,
.code_hash = code_hash,
.code_size = code.len,
.input = input,
.is_static = is_static,
.analysis = null,
.storage_access = null,
.original_storage = null,
.is_cold = true,
.gas_refund = 0,
.is_deployment = false,
.is_system_call = false,
.has_jumpdests = contains_jumpdest(code),
.is_empty = code.len == 0,
};
}
/// Creates a new Contract for deploying new bytecode.
///
/// Used for CREATE and CREATE2 operations. The contract address
/// is initially zero and will be set by the VM after computing
/// the deployment address.
///
/// ## Parameters
/// - `caller`: The creating contract's address
/// - `value`: Initial balance for the new contract
/// - `gas`: Gas allocated for deployment
/// - `code`: Initialization bytecode (constructor)
/// - `salt`: Optional salt for CREATE2 (null for CREATE)
///
/// ## Address Calculation
/// - CREATE: address = keccak256(rlp([sender, nonce]))[12:]
/// - CREATE2: address = keccak256(0xff ++ sender ++ salt ++ keccak256(code))[12:]
///
/// ## Deployment Flow
/// 1. Execute initialization code
/// 2. Code returns runtime bytecode
/// 3. VM stores runtime bytecode at computed address
/// 4. Contract becomes callable at that address
///
/// ## Example
/// ```zig
/// // CREATE
/// const contract = Contract.init_deployment(
/// deployer_address,
/// initial_balance,
/// gas_limit,
/// init_bytecode,
/// null, // no salt for CREATE
/// );
/// ```
pub fn init_deployment(
caller: Address.Address,
value: u256,
gas: u64,
code: []const u8,
salt: ?[32]u8,
) Self {
const contract = Self{
.address = Address.zero(),
.caller = caller,
.value = value,
.gas = gas,
.code = code,
.code_hash = [_]u8{0} ** 32, // Deployment doesn't have code hash. This could be kekkac256(0) instead of 0
.code_size = code.len,
.input = &[_]u8{},
.is_static = false,
.analysis = null,
.storage_access = null,
.original_storage = null,
.is_cold = false, // Deployment is always warm
.gas_refund = 0,
.is_deployment = true,
.is_system_call = false,
.has_jumpdests = contains_jumpdest(code),
.is_empty = code.len == 0,
};
if (salt == null) return contract;
// Salt is used for CREATE2 address calculation
// The actual address calculation happens in the VM's create2_contract method
return contract;
}
/// Performs a quick scan to check if bytecode contains any JUMPDEST opcodes.
///
/// This is a fast O(n) scan used during contract initialization to set
/// the `has_jumpdests` flag. If no JUMPDESTs exist, we can skip all
/// jump validation as any JUMP/JUMPI will fail.
///
/// ## Note
/// This doesn't account for JUMPDEST bytes inside PUSH data.
/// Full analysis is deferred until actually needed (lazy evaluation).
///
/// ## Returns
/// - `true`: At least one 0x5B byte found
/// - `false`: No JUMPDEST opcodes present
fn contains_jumpdest(code: []const u8) bool {
for (code) |op| {
if (op == constants.JUMPDEST) return true;
}
return false;
}
/// Validates if a jump destination is valid within the contract bytecode.
///
/// A valid jump destination must:
/// 1. Be within code bounds (< code_size)
/// 2. Point to a JUMPDEST opcode (0x5B)
/// 3. Not be inside PUSH data (validated by code analysis)
///
/// ## Parameters
/// - `allocator`: Allocator for lazy code analysis
/// - `dest`: Target program counter from JUMP/JUMPI
///
/// ## Returns
/// - `true`: Valid JUMPDEST at the target position
/// - `false`: Invalid destination (out of bounds, not JUMPDEST, or in data)
///
/// ## Performance
/// - Fast path: Empty code or no JUMPDESTs (immediate false)
/// - Analyzed code: O(log n) binary search
/// - First jump: O(n) analysis then O(log n) search
///
/// ## Example
/// ```zig
/// if (!contract.valid_jumpdest(allocator, jump_target)) {
/// return ExecutionError.InvalidJump;
/// }
/// ```
pub fn valid_jumpdest(self: *Self, allocator: std.mem.Allocator, dest: u256) bool {
// Fast path: empty code or out of bounds
if (self.is_empty or dest >= self.code_size) return false;
// Fast path: no JUMPDESTs in code
if (!self.has_jumpdests) return false;
const pos: u32 = @intCast(@min(dest, std.math.maxInt(u32)));
// Ensure analysis is performed
self.ensure_analysis(allocator);
// Binary search in sorted JUMPDEST positions
if (self.analysis) |analysis| {
if (analysis.jumpdest_positions.len > 0) {
const Context = struct { target: u32 };
const found = std.sort.binarySearch(
u32,
analysis.jumpdest_positions,
Context{ .target = pos },
struct {
fn compare(ctx: Context, item: u32) std.math.Order {
return std.math.order(ctx.target, item);
}
}.compare,
);
return found != null;
}
}
// Fallback to bitvec check
return self.is_code(pos);
}
/// Ensure code analysis is performed
fn ensure_analysis(self: *Self, allocator: std.mem.Allocator) void {
if (self.analysis == null and !self.is_empty) {
self.analysis = analyze_code(allocator, self.code, self.code_hash) catch null;
}
}
/// Check if position is code (not data)
pub fn is_code(self: *const Self, pos: u64) bool {
if (self.analysis) |analysis| {
// We know pos is within bounds if analysis exists, so use unchecked version
return analysis.code_segments.is_set_unchecked(@intCast(pos));
}
return true;
}
/// Attempts to consume gas from the contract's available gas.
///
/// This is the primary gas accounting method, called before every
/// operation to ensure sufficient gas remains. The inline directive
/// ensures this hot-path function has minimal overhead.
///
/// ## Parameters
/// - `amount`: Gas units to consume
///
/// ## Returns
/// - `true`: Gas successfully deducted
/// - `false`: Insufficient gas (triggers out-of-gas error)
///
/// ## Usage
/// ```zig
/// if (!contract.use_gas(operation_cost)) {
/// return ExecutionError.OutOfGas;
/// }
/// ```
///
/// ## Note
/// This method is marked inline for performance as it's called
/// millions of times during contract execution.
pub fn use_gas(self: *Self, amount: u64) bool {
if (self.gas < amount) return false;
self.gas -= amount;
return true;
}
/// Use gas without checking (when known safe)
pub fn use_gas_unchecked(self: *Self, amount: u64) void {
self.gas -= amount;
}
/// Refund gas to contract
pub fn refund_gas(self: *Self, amount: u64) void {
self.gas += amount;
}
/// Add to gas refund counter with clamping
pub fn add_gas_refund(self: *Self, amount: u64) void {
const max_refund = self.gas / MAX_REFUND_QUOTIENT;
self.gas_refund = @min(self.gas_refund + amount, max_refund);
}
/// Subtract from gas refund counter with clamping
pub fn sub_gas_refund(self: *Self, amount: u64) void {
self.gas_refund = if (self.gas_refund > amount) self.gas_refund - amount else 0;
}
pub const MarkStorageSlotWarmError = error{
OutOfAllocatorMemory,
};
/// Mark storage slot as warm with pool support
pub fn mark_storage_slot_warm(self: *Self, allocator: std.mem.Allocator, slot: u256, pool: ?*StoragePool) MarkStorageSlotWarmError!bool {
if (self.storage_access == null) {
if (pool) |p| {
self.storage_access = p.borrow_access_map() catch |err| switch (err) {
StoragePool.BorrowAccessMapError.OutOfAllocatorMemory => {
Log.debug("Contract.mark_storage_slot_warm: failed to borrow access map: {any}", .{err});
return MarkStorageSlotWarmError.OutOfAllocatorMemory;
},
};
} else {
self.storage_access = allocator.create(std.AutoHashMap(u256, bool)) catch |err| {
Log.debug("Contract.mark_storage_slot_warm: allocation failed: {any}", .{err});
return MarkStorageSlotWarmError.OutOfAllocatorMemory;
};
self.storage_access.?.* = std.AutoHashMap(u256, bool).init(allocator);
}
}
const map = self.storage_access.?;
const was_cold = !map.contains(slot);
if (was_cold) {
map.put(slot, true) catch |err| {
Log.debug("Contract.mark_storage_slot_warm: map.put failed: {any}", .{err});
return MarkStorageSlotWarmError.OutOfAllocatorMemory;
};
}
return was_cold;
}
/// Check if storage slot is cold
pub fn is_storage_slot_cold(self: *const Self, slot: u256) bool {
if (self.storage_access) |map| {
return !map.contains(slot);
}
return true;
}
/// Batch mark storage slots as warm
pub fn mark_storage_slots_warm(self: *Self, allocator: std.mem.Allocator, slots: []const u256, pool: ?*StoragePool) ContractError!void {
if (slots.len == 0) return;
if (self.storage_access == null) {
if (pool) |p| {
self.storage_access = p.borrow_access_map() catch |err| {
Log.debug("Failed to borrow access map from pool: {any}", .{err});
return switch (err) {
StoragePool.BorrowAccessMapError.OutOfAllocatorMemory => StorageOperationError.OutOfAllocatorMemory,
};
};
} else {
self.storage_access = allocator.create(std.AutoHashMap(u256, bool)) catch |err| {
Log.debug("Failed to create storage access map: {any}", .{err});
return switch (err) {
std.mem.Allocator.Error.OutOfMemory => std.mem.Allocator.Error.OutOfMemory,
};
};
self.storage_access.?.* = std.AutoHashMap(u256, bool).init(allocator);
}
}
const map = self.storage_access.?;
map.ensureTotalCapacity(@as(u32, @intCast(map.count() + slots.len))) catch |err| {
Log.debug("Failed to ensure capacity for {d} storage slots: {any}", .{ slots.len, err });
return switch (err) {
std.mem.Allocator.Error.OutOfMemory => std.mem.Allocator.Error.OutOfMemory,
};
};
for (slots) |slot| {
map.putAssumeCapacity(slot, true);
}
}
/// Store original storage value
pub fn set_original_storage_value(self: *Self, allocator: std.mem.Allocator, slot: u256, value: u256, pool: ?*StoragePool) ContractError!void {
if (self.original_storage == null) {
if (pool) |p| {
self.original_storage = p.borrow_storage_map() catch |err| {
Log.debug("Failed to borrow storage map from pool: {any}", .{err});
return switch (err) {
StoragePool.BorrowStorageMapError.OutOfAllocatorMemory => StorageOperationError.OutOfAllocatorMemory,
};
};
} else {
self.original_storage = allocator.create(std.AutoHashMap(u256, u256)) catch |err| {
Log.debug("Failed to create original storage map: {any}", .{err});
return switch (err) {
std.mem.Allocator.Error.OutOfMemory => std.mem.Allocator.Error.OutOfMemory,
};
};
self.original_storage.?.* = std.AutoHashMap(u256, u256).init(allocator);
}
}
self.original_storage.?.put(slot, value) catch |err| {
Log.debug("Failed to store original storage value for slot {d}: {any}", .{ slot, err });
return switch (err) {
std.mem.Allocator.Error.OutOfMemory => std.mem.Allocator.Error.OutOfMemory,
};
};
}
/// Get original storage value
pub fn get_original_storage_value(self: *const Self, slot: u256) ?u256 {
if (self.original_storage) |map| {
return map.get(slot);
}
return null;
}
/// Get opcode at position (inline for performance)
pub fn get_op(self: *const Self, n: u64) u8 {
return if (n < self.code_size) self.code[@intCast(n)] else constants.STOP;
}
/// Get opcode at position without bounds check
pub fn get_op_unchecked(self: *const Self, n: u64) u8 {
return self.code[n];
}
/// Set call code (for CALLCODE/DELEGATECALL)
pub fn set_call_code(self: *Self, hash: [32]u8, code: []const u8) void {
self.code = code;
self.code_hash = hash;
self.code_size = code.len;
self.has_jumpdests = contains_jumpdest(code);
self.is_empty = code.len == 0;
self.analysis = null;
}
/// Clean up contract resources
pub fn deinit(self: *Self, allocator: std.mem.Allocator, pool: ?*StoragePool) void {
if (pool) |p| {
if (self.storage_access) |map| {
p.return_access_map(map);
self.storage_access = null;
}
if (self.original_storage) |map| {
p.return_storage_map(map);
self.original_storage = null;
}
} else {
if (self.storage_access) |map| {
map.deinit();
allocator.destroy(map);
self.storage_access = null;
}
if (self.original_storage) |map| {
map.deinit();
allocator.destroy(map);
self.original_storage = null;
}
}
// Analysis is typically cached globally, so don't free
}
/// Analyzes bytecode and caches the results globally for reuse.
///
/// This function performs comprehensive static analysis on EVM bytecode:
/// 1. Identifies code vs data segments (for JUMPDEST validation)
/// 2. Extracts and sorts all JUMPDEST positions
/// 3. Detects special opcodes (CREATE, SELFDESTRUCT, dynamic jumps)
/// 4. Caches results by code hash for reuse
///
/// ## Parameters
/// - `allocator`: Memory allocator for analysis structures
/// - `code`: The bytecode to analyze
/// - `code_hash`: Hash for cache lookup/storage
///
/// ## Returns
/// Pointer to CodeAnalysis (cached or newly created)
///
/// ## Performance
/// - First analysis: O(n) where n is code length
/// - Subsequent calls: O(1) cache lookup
/// - Thread-safe with mutex protection
///
/// ## Caching Strategy
/// Analysis results are cached globally by code hash. This is highly
/// effective as the same contract code is often executed many times
/// across different addresses (e.g., proxy patterns, token contracts).
///
/// ## Example
/// ```zig
/// const analysis = try Contract.analyze_code(
/// allocator,
/// bytecode,
/// bytecode_hash,
/// );
/// // Analysis is now cached for future use
/// ```
pub fn analyze_code(allocator: std.mem.Allocator, code: []const u8, code_hash: [32]u8) CodeAnalysisError!*const CodeAnalysis {
cache_mutex.lock();
defer cache_mutex.unlock();
if (analysis_cache == null) {
analysis_cache = std.AutoHashMap([32]u8, *CodeAnalysis).init(allocator);
}
if (analysis_cache.?.get(code_hash)) |cached| {
return cached;
}
const analysis = allocator.create(CodeAnalysis) catch |err| {
Log.debug("Failed to allocate CodeAnalysis: {any}", .{err});
return err;
};
analysis.code_segments = try bitvec.code_bitmap(allocator, code);
var jumpdests = std.ArrayList(u32).init(allocator);
defer jumpdests.deinit();
var i: usize = 0;
while (i < code.len) {
const op = code[i];
if (op == constants.JUMPDEST and analysis.code_segments.is_set_unchecked(i)) {
jumpdests.append(@as(u32, @intCast(i))) catch |err| {
Log.debug("Failed to append jumpdest position {d}: {any}", .{ i, err });
return err;
};
}
if (constants.is_push(op)) {
const push_size = constants.get_push_size(op);
i += push_size + 1;
} else {
i += 1;
}
}
// Sort for binary search
std.mem.sort(u32, jumpdests.items, {}, comptime std.sort.asc(u32));
analysis.jumpdest_positions = jumpdests.toOwnedSlice() catch |err| {
Log.debug("Failed to convert jumpdests to owned slice: {any}", .{err});
return err;
};
analysis.max_stack_depth = 0;
analysis.block_gas_costs = null;
analysis.has_dynamic_jumps = contains_op(code, &[_]u8{ constants.JUMP, constants.JUMPI });
analysis.has_static_jumps = false;
analysis.has_selfdestruct = contains_op(code, &[_]u8{constants.SELFDESTRUCT});
analysis.has_create = contains_op(code, &[_]u8{ constants.CREATE, constants.CREATE2 });
analysis_cache.?.put(code_hash, analysis) catch |err| {
Log.debug("Failed to cache code analysis: {any}", .{err});
// Continue without caching - return the analysis anyway
};
return analysis;
}
/// Check if code contains any of the given opcodes
pub fn contains_op(code: []const u8, opcodes: []const u8) bool {
for (code) |op| {
for (opcodes) |target| {
if (op == target) return true;
}
}
return false;
}
/// Clear the global analysis cache
pub fn clear_analysis_cache(allocator: std.mem.Allocator) void {
cache_mutex.lock();
defer cache_mutex.unlock();
if (analysis_cache) |*cache| {
var iter = cache.iterator();
while (iter.next()) |entry| {
entry.value_ptr.*.deinit(allocator);
allocator.destroy(entry.value_ptr.*);
}
cache.deinit();
analysis_cache = null;
}
}
/// Analyze jump destinations - public wrapper for ensure_analysis
pub fn analyze_jumpdests(self: *Self, allocator: std.mem.Allocator) void {
self.ensure_analysis(allocator);
}
/// Create a contract to execute bytecode at a specific address
/// This is useful for testing or executing code that should be treated as if it's deployed at an address
/// The caller must separately call vm.state.set_code(address, bytecode) to deploy the code
pub fn init_at_address(
caller: Address.Address,
address: Address.Address,
value: u256,
gas: u64,
bytecode: []const u8,
input: []const u8,
is_static: bool,
) Self {
// Calculate code hash for the bytecode
var hasher = std.crypto.hash.sha3.Keccak256.init(.{});
hasher.update(bytecode);
var code_hash: [32]u8 = undefined;
hasher.final(&code_hash);
return Self{
.address = address,
.caller = caller,
.value = value,
.gas = gas,
.code = bytecode,
.code_hash = code_hash,
.code_size = bytecode.len,
.input = input,
.is_static = is_static,
.analysis = null,
.storage_access = null,
.original_storage = null,
.is_cold = true,
.gas_refund = 0,
.is_deployment = false,
.is_system_call = false,
.has_jumpdests = contains_jumpdest(bytecode),
.is_empty = bytecode.len == 0,
};
}
```
```zig [src/evm/contract/code_analysis.zig]
const std = @import("std");
const bitvec = @import("bitvec.zig");
/// Advanced code analysis for EVM bytecode optimization.
///
/// This structure holds pre-computed analysis results for a contract's bytecode,
/// enabling efficient execution by pre-identifying jump destinations, code segments,
/// and other properties that would otherwise need to be computed at runtime.
///
/// The analysis is performed once when a contract is first loaded and cached for
/// subsequent executions, significantly improving performance for frequently-used
/// contracts.
///
/// ## Fields
/// - `code_segments`: Bit vector marking which bytes are executable code vs data
/// - `jumpdest_positions`: Sorted array of valid JUMPDEST positions for O(log n) validation
/// - `block_gas_costs`: Optional pre-computed gas costs for basic blocks
/// - `max_stack_depth`: Maximum stack depth required by the contract
/// - `has_dynamic_jumps`: Whether the code contains JUMP/JUMPI with dynamic targets
/// - `has_static_jumps`: Whether the code contains JUMP/JUMPI with static targets
/// - `has_selfdestruct`: Whether the code contains SELFDESTRUCT opcode
/// - `has_create`: Whether the code contains CREATE/CREATE2 opcodes
///
/// ## Performance
/// - Jump destination validation: O(log n) using binary search
/// - Code segment checking: O(1) using bit vector
/// - Enables dead code elimination and other optimizations
///
/// ## Memory Management
/// The analysis owns its allocated memory and must be properly cleaned up
/// using the `deinit` method to prevent memory leaks.
const Self = @This();
/// Bit vector marking which bytes in the bytecode are executable code vs data.
///
/// Each bit corresponds to a byte in the contract bytecode:
/// - 1 = executable code byte
/// - 0 = data byte (e.g., PUSH arguments)
///
/// This is critical for JUMPDEST validation since jump destinations
/// must point to actual code, not data bytes within PUSH instructions.
code_segments: bitvec,
/// Sorted array of all valid JUMPDEST positions in the bytecode.
///
/// Pre-sorted to enable O(log n) binary search validation of jump targets.
/// Only positions marked as code (not data) and containing the JUMPDEST
/// opcode (0x5B) are included.
jumpdest_positions: []const u32,
/// Optional pre-computed gas costs for each basic block.
///
/// When present, enables advanced gas optimization by pre-calculating
/// the gas cost of straight-line code sequences between jumps.
/// This is an optional optimization that may not be computed for all contracts.
block_gas_costs: ?[]const u32,
/// Maximum stack depth required by any execution path in the contract.
///
/// Pre-computed through static analysis to enable early detection of
/// stack overflow conditions. A value of 0 indicates the depth wasn't analyzed.
max_stack_depth: u16,
/// Indicates whether the contract contains JUMP/JUMPI opcodes with dynamic targets.
///
/// Dynamic jumps (where the target is computed at runtime) prevent certain
/// optimizations and require full jump destination validation at runtime.
has_dynamic_jumps: bool,
/// Indicates whether the contract contains JUMP/JUMPI opcodes with static targets.
///
/// Static jumps (where the target is a constant) can be pre-validated
/// and optimized during analysis.
has_static_jumps: bool,
/// Indicates whether the contract contains the SELFDESTRUCT opcode (0xFF).
///
/// Contracts with SELFDESTRUCT require special handling for state management
/// and cannot be marked as "pure" or side-effect free.
has_selfdestruct: bool,
/// Indicates whether the contract contains CREATE or CREATE2 opcodes.
///
/// Contracts that can deploy other contracts require additional
/// gas reservation and state management considerations.
has_create: bool,
/// Releases all memory allocated by this code analysis.
///
/// This method must be called when the analysis is no longer needed to prevent
/// memory leaks. It safely handles all owned resources including:
/// - The code segments bit vector
/// - The jumpdest positions array
/// - The optional block gas costs array
///
/// ## Parameters
/// - `self`: The analysis instance to clean up
/// - `allocator`: The same allocator used to create the analysis resources
///
/// ## Safety
/// After calling deinit, the analysis instance should not be used again.
/// All pointers to analysis data become invalid.
///
/// ## Example
/// ```zig
/// var analysis = try analyzeCode(allocator, bytecode);
/// defer analysis.deinit(allocator);
/// ```
pub fn deinit(self: *Self, allocator: std.mem.Allocator) void {
self.code_segments.deinit(allocator);
if (self.jumpdest_positions.len > 0) {
allocator.free(self.jumpdest_positions);
}
if (self.block_gas_costs) |costs| {
allocator.free(costs);
}
}
```
```zig [src/evm/memory_size.zig]
/// Memory access requirements for EVM operations.
///
/// MemorySize encapsulates the memory region that an operation needs to access,
/// defined by an offset and size. This is used for:
/// - Calculating memory expansion costs
/// - Validating memory bounds
/// - Pre-allocating memory before operations
///
/// ## Memory Expansion
/// The EVM charges gas for memory expansion in 32-byte words. When an operation
/// accesses memory beyond the current size, the memory must expand to accommodate
/// it, incurring additional gas costs.
///
/// ## Gas Calculation
/// Memory expansion cost is quadratic:
/// - memory_cost = (memory_size_word ** 2) / 512 + (3 * memory_size_word)
/// - memory_size_word = (offset + size + 31) / 32
///
/// ## Zero-Size Edge Case
/// Operations with size=0 don't access memory and don't trigger expansion,
/// regardless of the offset value. This is important for operations like
/// RETURNDATACOPY with zero length.
///
/// Example:
/// ```zig
/// // MLOAD at offset 0x100 needs 32 bytes
/// const mem_size = MemorySize{ .offset = 0x100, .size = 32 };
///
/// // Calculate required memory size
/// const required = mem_size.offset + mem_size.size; // 0x120
/// ```
const Self = @This();
/// Starting offset in memory where the operation begins.
/// This is typically popped from the stack.
offset: u64,
/// Number of bytes the operation needs to access.
/// A size of 0 means no memory access (and no expansion).
size: u64,
```
```zig [src/evm/wasm_stubs.zig]
// Minimal stubs for WASM/freestanding build
const std = @import("std");
// Thread stub for single-threaded WASM
pub const DummyMutex = struct {
pub fn lock(self: *@This()) void { _ = self; }
pub fn unlock(self: *@This()) void { _ = self; }
};
// Logging stub for WASM
pub fn log(
comptime level: std.log.Level,
comptime scope: @TypeOf(.enum_literal),
comptime format: []const u8,
args: anytype,
) void {
_ = level;
_ = scope;
_ = format;
_ = args;
// No-op in WASM
}
// Panic stub for WASM
pub fn panic(msg: []const u8, error_return_trace: ?*std.builtin.StackTrace, ret_addr: ?usize) noreturn {
_ = msg;
_ = error_return_trace;
_ = ret_addr;
unreachable;
}
```
```zig [src/evm/precompiles/precompile_addresses.zig]
const Address = @import("Address").Address;
/// Precompile addresses as defined by the Ethereum specification
/// These addresses are reserved for built-in precompiled contracts
/// ECRECOVER precompile - signature recovery
pub const ECRECOVER_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x01 };
/// SHA256 precompile - SHA-256 hash function
pub const SHA256_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x02 };
/// RIPEMD160 precompile - RIPEMD-160 hash function
pub const RIPEMD160_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x03 };
/// IDENTITY precompile - returns input data unchanged
pub const IDENTITY_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x04 };
/// MODEXP precompile - modular exponentiation
pub const MODEXP_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x05 };
/// ECADD precompile - elliptic curve addition on alt_bn128
pub const ECADD_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x06 };
/// ECMUL precompile - elliptic curve scalar multiplication on alt_bn128
pub const ECMUL_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x07 };
/// ECPAIRING precompile - elliptic curve pairing check on alt_bn128
pub const ECPAIRING_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x08 };
/// BLAKE2F precompile - BLAKE2b F compression function
pub const BLAKE2F_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x09 };
/// POINT_EVALUATION precompile - KZG point evaluation (EIP-4844)
pub const POINT_EVALUATION_ADDRESS: Address = [_]u8{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x0A };
/// Checks if the given address is a precompile address
/// @param address The address to check
/// @return true if the address is a known precompile, false otherwise
pub fn is_precompile(address: Address) bool {
// Check if the first 19 bytes are zero
for (address[0..19]) |byte| {
if (byte != 0) return false;
}
// Check if the last byte is in the precompile range (1-10)
const last_byte = address[19];
return last_byte >= 1 and last_byte <= 10;
}
/// Gets the precompile ID from an address
/// @param address The precompile address
/// @return The precompile ID (1-10) or 0 if not a precompile
pub fn get_precompile_id(address: Address) u8 {
if (!is_precompile(address)) return 0;
return address[19];
}```
```zig [src/evm/precompiles/precompiles.zig]
const std = @import("std");
const Address = @import("Address").Address;
const addresses = @import("precompile_addresses.zig");
const PrecompileOutput = @import("precompile_result.zig").PrecompileOutput;
const PrecompileError = @import("precompile_result.zig").PrecompileError;
const identity = @import("identity.zig");
const ChainRules = @import("../hardforks/chain_rules.zig");
/// Main precompile dispatcher module
///
/// This module provides the main interface for precompile execution. It handles:
/// - Address-based precompile detection and routing
/// - Hardfork-based availability checks
/// - Unified execution interface for all precompiles
/// - Error handling and result management
///
/// The dispatcher is designed to be easily extensible for future precompiles.
/// Adding a new precompile requires:
/// 1. Adding the address constant to precompile_addresses.zig
/// 2. Implementing the precompile logic in its own module
/// 3. Adding the dispatch case to execute_precompile()
/// 4. Adding availability check to is_available()
/// Checks if the given address is a precompile address
///
/// This function determines whether a given address corresponds to a known precompile.
/// It serves as the entry point for precompile detection during contract calls.
///
/// @param address The address to check
/// @return true if the address is a known precompile, false otherwise
pub fn is_precompile(address: Address) bool {
return addresses.is_precompile(address);
}
/// Checks if a precompile is available in the given chain rules
///
/// Different precompiles were introduced in different hardforks. This function
/// ensures that precompiles are only available when they should be according
/// to the Ethereum specification.
///
/// @param address The precompile address to check
/// @param chain_rules The current chain rules configuration
/// @return true if the precompile is available with these chain rules
pub fn is_available(address: Address, chain_rules: ChainRules) bool {
if (!is_precompile(address)) return false;
const precompile_id = addresses.get_precompile_id(address);
return switch (precompile_id) {
1, 2, 3, 4 => true, // ECRECOVER, SHA256, RIPEMD160, IDENTITY available from Frontier
5 => chain_rules.IsByzantium, // MODEXP from Byzantium
6, 7, 8 => chain_rules.IsByzantium, // ECADD, ECMUL, ECPAIRING from Byzantium
9 => chain_rules.IsIstanbul, // BLAKE2F from Istanbul
10 => chain_rules.IsCancun, // POINT_EVALUATION from Cancun
else => false,
};
}
/// Executes a precompile with the given parameters
///
/// This is the main execution function that routes precompile calls to their
/// specific implementations. It handles:
/// - Precompile address validation
/// - Hardfork availability checks
/// - Routing to specific precompile implementations
/// - Consistent error handling
///
/// @param address The precompile address being called
/// @param input Input data for the precompile
/// @param output Output buffer to write results (must be large enough)
/// @param gas_limit Maximum gas available for execution
/// @param chain_rules Current chain rules for availability checking
/// @return PrecompileOutput containing success/failure and gas usage
pub fn execute_precompile(
address: Address,
input: []const u8,
output: []u8,
gas_limit: u64,
chain_rules: ChainRules
) PrecompileOutput {
// Check if this is a valid precompile address
if (!is_precompile(address)) {
return PrecompileOutput.failure_result(PrecompileError.ExecutionFailed);
}
// Check if this precompile is available with the current chain rules
if (!is_available(address, chain_rules)) {
return PrecompileOutput.failure_result(PrecompileError.ExecutionFailed);
}
const precompile_id = addresses.get_precompile_id(address);
// Route to specific precompile implementation
return switch (precompile_id) {
4 => identity.execute(input, output, gas_limit), // IDENTITY
// Placeholder implementations for future precompiles
1 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // ECRECOVER - TODO
2 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // SHA256 - TODO
3 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // RIPEMD160 - TODO
5 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // MODEXP - TODO
6 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // ECADD - TODO
7 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // ECMUL - TODO
8 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // ECPAIRING - TODO
9 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // BLAKE2F - TODO
10 => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed), // POINT_EVALUATION - TODO
else => PrecompileOutput.failure_result(PrecompileError.ExecutionFailed),
};
}
/// Estimates the gas cost for a precompile call
///
/// This function calculates the gas cost for a precompile call without actually
/// executing it. Useful for gas estimation and transaction validation.
///
/// @param address The precompile address
/// @param input_size Size of the input data
/// @param chain_rules Current chain rules
/// @return Estimated gas cost or error if not available
pub fn estimate_gas(address: Address, input_size: usize, chain_rules: ChainRules) !u64 {
if (!is_precompile(address)) {
return error.InvalidPrecompile;
}
if (!is_available(address, chain_rules)) {
return error.PrecompileNotAvailable;
}
const precompile_id = addresses.get_precompile_id(address);
return switch (precompile_id) {
4 => identity.calculate_gas_checked(input_size), // IDENTITY
// Placeholder gas calculations for future precompiles
1 => error.NotImplemented, // ECRECOVER - TODO
2 => error.NotImplemented, // SHA256 - TODO
3 => error.NotImplemented, // RIPEMD160 - TODO
5 => error.NotImplemented, // MODEXP - TODO
6 => error.NotImplemented, // ECADD - TODO
7 => error.NotImplemented, // ECMUL - TODO
8 => error.NotImplemented, // ECPAIRING - TODO
9 => error.NotImplemented, // BLAKE2F - TODO
10 => error.NotImplemented, // POINT_EVALUATION - TODO
else => error.InvalidPrecompile,
};
}
/// Gets the expected output size for a precompile call
///
/// Some precompiles have fixed output sizes, while others depend on the input.
/// This function provides a way to determine the required output buffer size.
///
/// @param address The precompile address
/// @param input_size Size of the input data
/// @param chain_rules Current chain rules
/// @return Expected output size or error if not available
pub fn get_output_size(address: Address, input_size: usize, chain_rules: ChainRules) !usize {
if (!is_precompile(address)) {
return error.InvalidPrecompile;
}
if (!is_available(address, chain_rules)) {
return error.PrecompileNotAvailable;
}
const precompile_id = addresses.get_precompile_id(address);
return switch (precompile_id) {
4 => identity.get_output_size(input_size), // IDENTITY
// Placeholder output sizes for future precompiles
1 => 32, // ECRECOVER - fixed 32 bytes (address)
2 => 32, // SHA256 - fixed 32 bytes (hash)
3 => 32, // RIPEMD160 - fixed 32 bytes (hash, padded)
5 => error.NotImplemented, // MODEXP - variable size, TODO
6 => 64, // ECADD - fixed 64 bytes (point)
7 => 64, // ECMUL - fixed 64 bytes (point)
8 => 32, // ECPAIRING - fixed 32 bytes (boolean result)
9 => 64, // BLAKE2F - fixed 64 bytes (state)
10 => 64, // POINT_EVALUATION - fixed 64 bytes (proof result)
else => error.InvalidPrecompile,
};
}
/// Validates that a precompile call would succeed
///
/// This function performs all validation checks without executing the precompile.
/// Useful for transaction validation and gas estimation.
///
/// @param address The precompile address
/// @param input_size Size of the input data
/// @param gas_limit Available gas limit
/// @param chain_rules Current chain rules
/// @return true if the call would succeed
pub fn validate_call(address: Address, input_size: usize, gas_limit: u64, chain_rules: ChainRules) bool {
if (!is_precompile(address)) return false;
if (!is_available(address, chain_rules)) return false;
const gas_cost = estimate_gas(address, input_size, chain_rules) catch return false;
return gas_cost <= gas_limit;
}```
```zig [src/evm/precompiles/precompile_result.zig]
const std = @import("std");
/// PrecompileError represents error conditions that can occur during precompile execution
///
/// Precompiles have different error conditions from regular EVM execution:
/// - OutOfGas: Gas limit exceeded during execution
/// - InvalidInput: Input data is malformed or invalid for the precompile
/// - ExecutionFailed: The precompile operation itself failed
pub const PrecompileError = error{
/// Insufficient gas provided to complete the precompile operation
/// This occurs when the calculated gas cost exceeds the provided gas limit
OutOfGas,
/// Input data is invalid for the specific precompile
/// Each precompile has its own input validation requirements
InvalidInput,
/// The precompile operation failed during execution
/// This covers cryptographic failures, computation errors, etc.
ExecutionFailed,
/// Memory allocation failed during precompile execution
/// Not a normal precompile error - indicates system resource exhaustion
OutOfMemory,
};
/// PrecompileResult represents the successful result of a precompile execution
///
/// Contains the gas consumed and the output data produced by the precompile.
/// Output data is owned by the caller and must be managed appropriately.
pub const PrecompileResult = struct {
/// Amount of gas consumed by the precompile execution
gas_used: u64,
/// Length of the output data produced
/// The actual output data is written to the provided output buffer
output_size: usize,
};
/// PrecompileOutput represents the complete result of precompile execution
///
/// This is a union type that represents either success or failure of precompile execution.
/// Success contains gas usage and output size, while failure contains the specific error.
pub const PrecompileOutput = union(enum) {
/// Successful execution with gas usage and output
success: PrecompileResult,
/// Failed execution with specific error
failure: PrecompileError,
/// Creates a successful result
/// @param gas_used The amount of gas consumed
/// @param output_size The size of the output data
/// @return A successful PrecompileOutput
pub fn success_result(gas_used: u64, output_size: usize) PrecompileOutput {
return PrecompileOutput{
.success = PrecompileResult{
.gas_used = gas_used,
.output_size = output_size
}
};
}
/// Creates a failure result
/// @param err The error that occurred
/// @return A failed PrecompileOutput
pub fn failure_result(err: PrecompileError) PrecompileOutput {
return PrecompileOutput{ .failure = err };
}
/// Checks if the result represents success
/// @return true if successful, false if failed
pub fn is_success(self: PrecompileOutput) bool {
return switch (self) {
.success => true,
.failure => false,
};
}
/// Checks if the result represents failure
/// @return true if failed, false if successful
pub fn is_failure(self: PrecompileOutput) bool {
return !self.is_success();
}
/// Gets the gas used from a successful result
/// @return The gas used, or 0 if the result is a failure
pub fn get_gas_used(self: PrecompileOutput) u64 {
return switch (self) {
.success => |result| result.gas_used,
.failure => 0,
};
}
/// Gets the output size from a successful result
/// @return The output size, or 0 if the result is a failure
pub fn get_output_size(self: PrecompileOutput) usize {
return switch (self) {
.success => |result| result.output_size,
.failure => 0,
};
}
/// Gets the error from a failed result
/// @return The error, or null if the result is successful
pub fn get_error(self: PrecompileOutput) ?PrecompileError {
return switch (self) {
.success => null,
.failure => |err| err,
};
}
};
/// Get a human-readable description for a precompile error
///
/// Provides detailed descriptions of what each error means and when it occurs.
/// Useful for debugging, logging, and error reporting.
///
/// @param err The precompile error to describe
/// @return A string slice containing a human-readable description of the error
pub fn get_error_description(err: PrecompileError) []const u8 {
return switch (err) {
PrecompileError.OutOfGas => "Precompile execution ran out of gas",
PrecompileError.InvalidInput => "Invalid input data for precompile",
PrecompileError.ExecutionFailed => "Precompile execution failed",
PrecompileError.OutOfMemory => "Out of memory during precompile execution",
};
}```
```zig [src/evm/precompiles/precompile_gas.zig]
const std = @import("std");
/// Gas calculation utilities for precompiles
///
/// This module provides common gas calculation patterns used by precompiles.
/// Many precompiles use linear gas costs (base + per_word * word_count) or other
/// standard patterns defined here.
/// Calculates linear gas cost: base_cost + per_word_cost * ceil(input_size / 32)
///
/// This is the most common gas calculation pattern for precompiles. The cost consists
/// of a base cost plus a per-word cost for each 32-byte word of input data.
/// Partial words are rounded up to full words.
///
/// @param input_size Size of the input data in bytes
/// @param base_cost Base gas cost regardless of input size
/// @param per_word_cost Gas cost per 32-byte word of input
/// @return Total gas cost for the operation
pub fn calculate_linear_cost(input_size: usize, base_cost: u64, per_word_cost: u64) u64 {
const word_count = (input_size + 31) / 32;
return base_cost + per_word_cost * @as(u64, @intCast(word_count));
}
/// Calculates linear gas cost with checked arithmetic to prevent overflow
///
/// Same as calculate_linear_cost but returns an error if the calculation would overflow.
/// This is important for very large input sizes that could cause integer overflow.
///
/// @param input_size Size of the input data in bytes
/// @param base_cost Base gas cost regardless of input size
/// @param per_word_cost Gas cost per 32-byte word of input
/// @return Total gas cost or error if overflow occurs
pub fn calculate_linear_cost_checked(input_size: usize, base_cost: u64, per_word_cost: u64) !u64 {
const word_count = (input_size + 31) / 32;
const word_count_u64 = std.math.cast(u64, word_count) orelse return error.Overflow;
const word_cost = std.math.mul(u64, per_word_cost, word_count_u64) catch return error.Overflow;
const total_cost = std.math.add(u64, base_cost, word_cost) catch return error.Overflow;
return total_cost;
}
/// Validates that the gas limit is sufficient for the calculated cost
///
/// This is a convenience function that combines gas calculation with validation.
/// It calculates the required gas and checks if the provided limit is sufficient.
///
/// @param input_size Size of the input data in bytes
/// @param base_cost Base gas cost regardless of input size
/// @param per_word_cost Gas cost per 32-byte word of input
/// @param gas_limit Maximum gas available for the operation
/// @return The calculated gas cost if within limit, error otherwise
pub fn validate_gas_limit(input_size: usize, base_cost: u64, per_word_cost: u64, gas_limit: u64) !u64 {
const gas_cost = try calculate_linear_cost_checked(input_size, base_cost, per_word_cost);
if (gas_cost > gas_limit) {
return error.OutOfGas;
}
return gas_cost;
}
/// Calculates the number of 32-byte words for a given byte size
///
/// This is a utility function for converting byte sizes to word counts.
/// Used when precompiles need to know the exact word count for other calculations.
///
/// @param byte_size Size in bytes
/// @return Number of 32-byte words (rounded up)
pub fn bytes_to_words(byte_size: usize) usize {
return (byte_size + 31) / 32;
}
/// Calculates gas cost for dynamic-length operations
///
/// Some precompiles have more complex gas calculations that depend on the
/// content of the input data, not just its size. This provides a framework
/// for such calculations.
///
/// @param input_data The input data to analyze
/// @param base_cost Base gas cost
/// @param calculate_dynamic_cost Function to calculate additional cost based on input
/// @return Total gas cost
pub fn calculate_dynamic_cost(
input_data: []const u8,
base_cost: u64,
calculate_dynamic_cost_fn: fn([]const u8) u64
) u64 {
const dynamic_cost = calculate_dynamic_cost_fn(input_data);
return base_cost + dynamic_cost;
}```
```zig [src/evm/precompiles/identity.zig]
const std = @import("std");
const PrecompileResult = @import("precompile_result.zig").PrecompileResult;
const PrecompileOutput = @import("precompile_result.zig").PrecompileOutput;
const PrecompileError = @import("precompile_result.zig").PrecompileError;
const gas_utils = @import("precompile_gas.zig");
/// IDENTITY precompile implementation (address 0x04)
///
/// The IDENTITY precompile is the simplest of all precompiles. It returns the input
/// data unchanged (identity function). Despite its simplicity, it serves important
/// purposes:
///
/// 1. **Data copying**: Efficiently copy data between different memory contexts
/// 2. **Gas measurement**: Provides predictable gas costs for data operations
/// 3. **Testing**: Simple precompile for testing the precompile infrastructure
/// 4. **Specification compliance**: Required by Ethereum specification
///
/// ## Gas Cost
///
/// The gas cost follows the standard linear formula:
/// - Base cost: 15 gas
/// - Per-word cost: 3 gas per 32-byte word (rounded up)
/// - Total: 15 + 3 * ceil(input_size / 32)
///
/// ## Examples
///
/// ```zig
/// // Empty input: 15 gas, empty output
/// const result1 = execute(&[_]u8{}, &output, 100);
///
/// // 32 bytes input: 15 + 3 = 18 gas, same output as input
/// const result2 = execute(&[_]u8{1, 2, 3, ...}, &output, 100);
///
/// // 33 bytes input: 15 + 3*2 = 21 gas (2 words), same output as input
/// const result3 = execute(&[_]u8{1, 2, 3, ..., 33}, &output, 100);
/// ```
/// Gas constants for IDENTITY precompile
/// These values are defined in the Ethereum specification and must match exactly
pub const IDENTITY_BASE_COST: u64 = 15;
pub const IDENTITY_WORD_COST: u64 = 3;
/// Calculates the gas cost for IDENTITY precompile execution
///
/// Uses the standard linear gas calculation: base + word_cost * word_count
/// Where word_count = ceil(input_size / 32)
///
/// @param input_size Size of the input data in bytes
/// @return Gas cost for processing the given input size
pub fn calculate_gas(input_size: usize) u64 {
return gas_utils.calculate_linear_cost(input_size, IDENTITY_BASE_COST, IDENTITY_WORD_COST);
}
/// Calculates the gas cost with overflow protection
///
/// Same as calculate_gas but returns an error if the calculation would overflow.
/// Important for very large input sizes in adversarial scenarios.
///
/// @param input_size Size of the input data in bytes
/// @return Gas cost or error if calculation overflows
pub fn calculate_gas_checked(input_size: usize) !u64 {
return gas_utils.calculate_linear_cost_checked(input_size, IDENTITY_BASE_COST, IDENTITY_WORD_COST);
}
/// Executes the IDENTITY precompile
///
/// This is the main entry point for IDENTITY precompile execution. It performs
/// the following steps:
///
/// 1. Calculate the required gas cost
/// 2. Validate that the gas limit is sufficient
/// 3. Copy input data to output buffer
/// 4. Return success result with gas used and output size
///
/// The function assumes that the output buffer is large enough to hold the input data.
/// This is the caller's responsibility to ensure.
///
/// @param input Input data to be copied (identity operation)
/// @param output Output buffer to write the result (must be >= input.len)
/// @param gas_limit Maximum gas available for this operation
/// @return PrecompileOutput containing success/failure and gas usage
pub fn execute(input: []const u8, output: []u8, gas_limit: u64) PrecompileOutput {
// Calculate gas cost for this input size
const gas_cost = calculate_gas_checked(input.len) catch {
return PrecompileOutput.failure_result(PrecompileError.OutOfGas);
};
// Check if we have enough gas
if (gas_cost > gas_limit) {
return PrecompileOutput.failure_result(PrecompileError.OutOfGas);
}
// Validate output buffer size
if (output.len < input.len) {
return PrecompileOutput.failure_result(PrecompileError.ExecutionFailed);
}
// Identity operation: copy input to output
// This is the core functionality - simply copy the input unchanged
if (input.len > 0) {
@memcpy(output[0..input.len], input);
}
return PrecompileOutput.success_result(gas_cost, input.len);
}
/// Validates the gas requirement without executing
///
/// This function can be used to check if a call would succeed without actually
/// performing the operation. Useful for gas estimation and validation.
///
/// @param input_size Size of the input data
/// @param gas_limit Available gas limit
/// @return true if the operation would succeed, false if out of gas
pub fn validate_gas_requirement(input_size: usize, gas_limit: u64) bool {
const gas_cost = calculate_gas_checked(input_size) catch return false;
return gas_cost <= gas_limit;
}
/// Gets the expected output size for given input
///
/// For IDENTITY, the output size is always equal to the input size.
/// This function is provided for consistency with other precompiles.
///
/// @param input_size Size of the input data
/// @return Expected output size (same as input for IDENTITY)
pub fn get_output_size(input_size: usize) usize {
return input_size;
}```
```zig [src/evm/constants/memory_limits.zig]
const std = @import("std");
/// EVM Memory Limit Constants
///
/// The EVM doesn't have a hard memory limit in the specification, but practical
/// limits exist due to gas costs. Memory expansion has quadratic gas costs that
/// make extremely large allocations prohibitively expensive.
///
/// Most production EVMs implement practical memory limits to prevent DoS attacks
/// and ensure predictable resource usage.
/// Maximum memory size in bytes (32 MB)
/// This is a reasonable limit that matches many production EVM implementations.
/// At 32 MB, the gas cost would be approximately:
/// - Words: 1,048,576 (32 MB / 32 bytes)
/// - Linear cost: 3 * 1,048,576 = 3,145,728 gas
/// - Quadratic cost: (1,048,576^2) / 512 = 2,147,483,648 gas
/// - Total: ~2.15 billion gas (far exceeding any reasonable block gas limit)
pub const MAX_MEMORY_SIZE: u64 = 32 * 1024 * 1024; // 32 MB
/// Alternative reasonable limits used by other implementations:
/// - 16 MB: More conservative limit
pub const CONSERVATIVE_MEMORY_LIMIT: u64 = 16 * 1024 * 1024;
/// - 64 MB: More permissive limit
pub const PERMISSIVE_MEMORY_LIMIT: u64 = 64 * 1024 * 1024;
/// Calculate the gas cost for a given memory size
pub fn calculate_memory_gas_cost(size_bytes: u64) u64 {
const words = (size_bytes + 31) / 32;
const linear_cost = 3 * words;
const quadratic_cost = (words * words) / 512;
return linear_cost + quadratic_cost;
}
/// Check if a memory size would exceed reasonable gas limits
pub fn is_memory_size_reasonable(size_bytes: u64, available_gas: u64) bool {
const gas_cost = calculate_memory_gas_cost(size_bytes);
return gas_cost <= available_gas;
}
test "memory gas costs" {
const testing = std.testing;
// Test small allocations
try testing.expectEqual(@as(u64, 3), calculate_memory_gas_cost(32)); // 1 word
try testing.expectEqual(@as(u64, 6), calculate_memory_gas_cost(64)); // 2 words
// Test 1 KB
const kb_cost = calculate_memory_gas_cost(1024);
try testing.expect(kb_cost > 96); // Should be more than linear cost alone
// Test 1 MB - should be very expensive
const mb_cost = calculate_memory_gas_cost(1024 * 1024);
try testing.expect(mb_cost > 1_000_000); // Over 1 million gas
// Test 32 MB - should be prohibitively expensive
const limit_cost = calculate_memory_gas_cost(MAX_MEMORY_SIZE);
try testing.expect(limit_cost > 2_000_000_000); // Over 2 billion gas
}
test "reasonable memory sizes" {
const testing = std.testing;
// With 10 million gas (reasonable for a transaction)
const available_gas: u64 = 10_000_000;
// Small sizes should be reasonable
try testing.expect(is_memory_size_reasonable(1024, available_gas)); // 1 KB
try testing.expect(is_memory_size_reasonable(10 * 1024, available_gas)); // 10 KB
// Large sizes should not be reasonable
try testing.expect(!is_memory_size_reasonable(10 * 1024 * 1024, available_gas)); // 10 MB
try testing.expect(!is_memory_size_reasonable(MAX_MEMORY_SIZE, available_gas)); // 32 MB
}
```
```zig [src/evm/constants/constants.zig]
//! EVM opcode constants and bytecode analysis utilities.
//!
//! This module serves as the central definition point for all EVM opcodes
//! and provides utility functions for bytecode analysis. All opcodes are
//! defined as comptime constants for zero-cost abstraction and compile-time
//! verification.
//!
//! ## Organization
//! Opcodes are grouped by their functional categories:
//! - Arithmetic operations (0x00-0x0B)
//! - Comparison & bitwise logic (0x10-0x1D)
//! - Keccak hashing (0x20)
//! - Environmental information (0x30-0x3F)
//! - Block information (0x40-0x4A)
//! - Stack, memory, storage operations (0x50-0x5F)
//! - Push operations (0x60-0x7F)
//! - Duplication operations (0x80-0x8F)
//! - Exchange operations (0x90-0x9F)
//! - Logging operations (0xA0-0xA4)
//! - System operations (0xF0-0xFF)
//!
//! ## Usage
//! ```zig
//! const opcode = bytecode[pc];
//! if (constants.is_push(opcode)) {
//! const push_size = constants.get_push_size(opcode);
//! // Skip over the push data
//! pc += 1 + push_size;
//! }
//! ```
//!
//! ## Hardfork Considerations
//! Some opcodes are only available after specific hardforks:
//! - PUSH0 (0x5F): Shanghai
//! - TLOAD/TSTORE (0x5C/0x5D): Cancun
//! - MCOPY (0x5E): Cancun
//! - BASEFEE (0x48): London
//! - CHAINID (0x46): Istanbul
//!
//! Reference: https://www.evm.codes/
// ============================================================================
// Arithmetic Operations (0x00-0x0B)
// ============================================================================
/// Halts execution of the current context.
/// Stack: [] -> []
/// Gas: 0
pub const STOP: u8 = 0x00;
/// Addition operation with modulo 2^256.
/// Stack: [a, b] -> [a + b]
/// Gas: 3
pub const ADD: u8 = 0x01;
/// Multiplication operation with modulo 2^256.
/// Stack: [a, b] -> [a * b]
/// Gas: 5
pub const MUL: u8 = 0x02;
/// Subtraction operation with modulo 2^256.
/// Stack: [a, b] -> [a - b]
/// Gas: 3
pub const SUB: u8 = 0x03;
/// Integer division operation.
/// Stack: [a, b] -> [a / b] (0 if b == 0)
/// Gas: 5
pub const DIV: u8 = 0x04;
pub const SDIV: u8 = 0x05;
pub const MOD: u8 = 0x06;
pub const SMOD: u8 = 0x07;
pub const ADDMOD: u8 = 0x08;
pub const MULMOD: u8 = 0x09;
/// Exponential operation (a ** b).
/// Stack: [a, b] -> [a ** b]
/// Gas: 10 + 50 per byte in exponent
/// Note: Gas cost increases with size of exponent
pub const EXP: u8 = 0x0A;
/// Sign extension operation.
/// Stack: [b, x] -> [y] where y is sign-extended x from (b+1)*8 bits
/// Gas: 5
pub const SIGNEXTEND: u8 = 0x0B;
// ============================================================================
// Comparison & Bitwise Logic Operations (0x10-0x1D)
// ============================================================================
pub const LT: u8 = 0x10;
pub const GT: u8 = 0x11;
pub const SLT: u8 = 0x12;
pub const SGT: u8 = 0x13;
pub const EQ: u8 = 0x14;
pub const ISZERO: u8 = 0x15;
pub const AND: u8 = 0x16;
pub const OR: u8 = 0x17;
pub const XOR: u8 = 0x18;
pub const NOT: u8 = 0x19;
pub const BYTE: u8 = 0x1A;
pub const SHL: u8 = 0x1B;
pub const SHR: u8 = 0x1C;
pub const SAR: u8 = 0x1D;
// ============================================================================
// Cryptographic Operations (0x20)
// ============================================================================
/// Computes Keccak-256 hash of memory region.
/// Stack: [offset, size] -> [hash]
/// Gas: 30 + 6 per word + memory expansion
pub const KECCAK256: u8 = 0x20;
// ============================================================================
// Environmental Information (0x30-0x3F)
// ============================================================================
pub const ADDRESS: u8 = 0x30;
pub const BALANCE: u8 = 0x31;
pub const ORIGIN: u8 = 0x32;
pub const CALLER: u8 = 0x33;
pub const CALLVALUE: u8 = 0x34;
pub const CALLDATALOAD: u8 = 0x35;
pub const CALLDATASIZE: u8 = 0x36;
pub const CALLDATACOPY: u8 = 0x37;
pub const CODESIZE: u8 = 0x38;
pub const CODECOPY: u8 = 0x39;
pub const GASPRICE: u8 = 0x3A;
pub const EXTCODESIZE: u8 = 0x3B;
pub const EXTCODECOPY: u8 = 0x3C;
pub const RETURNDATASIZE: u8 = 0x3D;
pub const RETURNDATACOPY: u8 = 0x3E;
pub const EXTCODEHASH: u8 = 0x3F;
// ============================================================================
// Block Information (0x40-0x4A)
// ============================================================================
pub const BLOCKHASH: u8 = 0x40;
pub const COINBASE: u8 = 0x41;
pub const TIMESTAMP: u8 = 0x42;
pub const NUMBER: u8 = 0x43;
pub const PREVRANDAO: u8 = 0x44;
pub const GASLIMIT: u8 = 0x45;
pub const CHAINID: u8 = 0x46;
pub const SELFBALANCE: u8 = 0x47;
pub const BASEFEE: u8 = 0x48;
pub const BLOBHASH: u8 = 0x49;
pub const BLOBBASEFEE: u8 = 0x4A;
// ============================================================================
// Stack, Memory, Storage and Flow Operations (0x50-0x5F)
// ============================================================================
pub const POP: u8 = 0x50;
pub const MLOAD: u8 = 0x51;
pub const MSTORE: u8 = 0x52;
pub const MSTORE8: u8 = 0x53;
/// Load value from storage.
/// Stack: [key] -> [value]
/// Gas: 100 (warm) or 2100 (cold) since Berlin
pub const SLOAD: u8 = 0x54;
/// Store value to storage.
/// Stack: [key, value] -> []
/// Gas: Complex - depends on current value and new value
/// Note: Most expensive operation, can cost 20000 gas
pub const SSTORE: u8 = 0x55;
pub const JUMP: u8 = 0x56;
pub const JUMPI: u8 = 0x57;
pub const PC: u8 = 0x58;
pub const MSIZE: u8 = 0x59;
pub const GAS: u8 = 0x5A;
/// Valid jump destination marker.
/// Stack: [] -> []
/// Gas: 1
/// Note: Only opcode that can be jumped to
pub const JUMPDEST: u8 = 0x5B;
pub const TLOAD: u8 = 0x5C;
pub const TSTORE: u8 = 0x5D;
pub const MCOPY: u8 = 0x5E;
/// Push zero onto the stack (Shanghai hardfork).
/// Stack: [] -> [0]
/// Gas: 2
/// Note: More efficient than PUSH1 0x00
pub const PUSH0: u8 = 0x5F;
// ============================================================================
// Push Operations (0x60-0x7F)
// ============================================================================
pub const PUSH1: u8 = 0x60;
pub const PUSH2: u8 = 0x61;
pub const PUSH3: u8 = 0x62;
pub const PUSH4: u8 = 0x63;
pub const PUSH5: u8 = 0x64;
pub const PUSH6: u8 = 0x65;
pub const PUSH7: u8 = 0x66;
pub const PUSH8: u8 = 0x67;
pub const PUSH9: u8 = 0x68;
pub const PUSH10: u8 = 0x69;
pub const PUSH11: u8 = 0x6A;
pub const PUSH12: u8 = 0x6B;
pub const PUSH13: u8 = 0x6C;
pub const PUSH14: u8 = 0x6D;
pub const PUSH15: u8 = 0x6E;
pub const PUSH16: u8 = 0x6F;
pub const PUSH17: u8 = 0x70;
pub const PUSH18: u8 = 0x71;
pub const PUSH19: u8 = 0x72;
pub const PUSH20: u8 = 0x73;
pub const PUSH21: u8 = 0x74;
pub const PUSH22: u8 = 0x75;
pub const PUSH23: u8 = 0x76;
pub const PUSH24: u8 = 0x77;
pub const PUSH25: u8 = 0x78;
pub const PUSH26: u8 = 0x79;
pub const PUSH27: u8 = 0x7A;
pub const PUSH28: u8 = 0x7B;
pub const PUSH29: u8 = 0x7C;
pub const PUSH30: u8 = 0x7D;
pub const PUSH31: u8 = 0x7E;
pub const PUSH32: u8 = 0x7F;
// ============================================================================
// Duplication Operations (0x80-0x8F)
// ============================================================================
pub const DUP1: u8 = 0x80;
pub const DUP2: u8 = 0x81;
pub const DUP3: u8 = 0x82;
pub const DUP4: u8 = 0x83;
pub const DUP5: u8 = 0x84;
pub const DUP6: u8 = 0x85;
pub const DUP7: u8 = 0x86;
pub const DUP8: u8 = 0x87;
pub const DUP9: u8 = 0x88;
pub const DUP10: u8 = 0x89;
pub const DUP11: u8 = 0x8A;
pub const DUP12: u8 = 0x8B;
pub const DUP13: u8 = 0x8C;
pub const DUP14: u8 = 0x8D;
pub const DUP15: u8 = 0x8E;
pub const DUP16: u8 = 0x8F;
// ============================================================================
// Exchange Operations (0x90-0x9F)
// ============================================================================
pub const SWAP1: u8 = 0x90;
pub const SWAP2: u8 = 0x91;
pub const SWAP3: u8 = 0x92;
pub const SWAP4: u8 = 0x93;
pub const SWAP5: u8 = 0x94;
pub const SWAP6: u8 = 0x95;
pub const SWAP7: u8 = 0x96;
pub const SWAP8: u8 = 0x97;
pub const SWAP9: u8 = 0x98;
pub const SWAP10: u8 = 0x99;
pub const SWAP11: u8 = 0x9A;
pub const SWAP12: u8 = 0x9B;
pub const SWAP13: u8 = 0x9C;
pub const SWAP14: u8 = 0x9D;
pub const SWAP15: u8 = 0x9E;
pub const SWAP16: u8 = 0x9F;
// ============================================================================
// Logging Operations (0xA0-0xA4)
// ============================================================================
pub const LOG0: u8 = 0xA0;
pub const LOG1: u8 = 0xA1;
pub const LOG2: u8 = 0xA2;
pub const LOG3: u8 = 0xA3;
pub const LOG4: u8 = 0xA4;
// ============================================================================
// System Operations (0xF0-0xFF)
// ============================================================================
pub const CREATE: u8 = 0xF0;
pub const CALL: u8 = 0xF1;
pub const CALLCODE: u8 = 0xF2;
pub const RETURN: u8 = 0xF3;
pub const DELEGATECALL: u8 = 0xF4;
pub const CREATE2: u8 = 0xF5;
pub const RETURNDATALOAD: u8 = 0xF7;
pub const EXTCALL: u8 = 0xF8;
pub const EXTDELEGATECALL: u8 = 0xF9;
pub const STATICCALL: u8 = 0xFA;
pub const EXTSTATICCALL: u8 = 0xFB;
pub const REVERT: u8 = 0xFD;
pub const INVALID: u8 = 0xFE;
/// Destroy contract and send balance to address.
/// Stack: [address] -> []
/// Gas: 5000 + dynamic costs
/// Note: Deprecated - only works in same transaction (Cancun)
pub const SELFDESTRUCT: u8 = 0xFF;
/// Checks if an opcode is a PUSH operation (PUSH1-PUSH32).
///
/// PUSH operations place N bytes of immediate data onto the stack,
/// where N is determined by the specific PUSH opcode.
///
/// ## Parameters
/// - `op`: The opcode to check
///
/// ## Returns
/// - `true` if the opcode is between PUSH1 (0x60) and PUSH32 (0x7F)
/// - `false` otherwise
///
/// ## Example
/// ```zig
/// if (is_push(opcode)) {
/// const data_size = get_push_size(opcode);
/// // Read `data_size` bytes following the opcode
/// }
/// ```
pub fn is_push(op: u8) bool {
return op >= PUSH1 and op <= PUSH32;
}
/// Returns the number of immediate data bytes for a PUSH opcode.
///
/// PUSH1 pushes 1 byte, PUSH2 pushes 2 bytes, etc., up to PUSH32
/// which pushes 32 bytes of immediate data from the bytecode.
///
/// ## Parameters
/// - `op`: The opcode to analyze
///
/// ## Returns
/// - 1-32 for valid PUSH opcodes (PUSH1-PUSH32)
/// - 0 for non-PUSH opcodes
///
/// ## Algorithm
/// For valid PUSH opcodes: size = opcode - 0x60 + 1
///
/// ## Example
/// ```zig
/// const size = get_push_size(PUSH20); // Returns 20
/// const size2 = get_push_size(ADD); // Returns 0
/// ```
pub fn get_push_size(op: u8) u8 {
if (!is_push(op)) return 0;
return op - PUSH1 + 1;
}
/// Checks if an opcode is a DUP operation (DUP1-DUP16).
///
/// DUP operations duplicate a stack item and push the copy onto the stack.
/// DUP1 duplicates the top item, DUP2 the second item, etc.
///
/// ## Parameters
/// - `op`: The opcode to check
///
/// ## Returns
/// - `true` if the opcode is between DUP1 (0x80) and DUP16 (0x8F)
/// - `false` otherwise
///
/// ## Stack Effect
/// DUPn: [... vn ... v1] -> [... vn ... v1 vn]
pub fn is_dup(op: u8) bool {
return op >= DUP1 and op <= DUP16;
}
/// Get the stack position for a DUP opcode
/// Returns 0 for non-DUP opcodes
pub fn get_dup_position(op: u8) u8 {
if (!is_dup(op)) return 0;
return op - DUP1 + 1;
}
/// Check if an opcode is a SWAP operation
pub fn is_swap(op: u8) bool {
return op >= SWAP1 and op <= SWAP16;
}
/// Get the stack position for a SWAP opcode
/// Returns 0 for non-SWAP opcodes
pub fn get_swap_position(op: u8) u8 {
if (!is_swap(op)) return 0;
return op - SWAP1 + 1;
}
/// Check if an opcode is a LOG operation
pub fn is_log(op: u8) bool {
return op >= LOG0 and op <= LOG4;
}
/// Get the number of topics for a LOG opcode
/// Returns 0 for non-LOG opcodes
pub fn get_log_topic_count(op: u8) u8 {
if (!is_log(op)) return 0;
return op - LOG0;
}
/// Checks if an opcode terminates execution of the current context.
///
/// Terminating operations end the current execution context and cannot
/// be followed by any other operations in the execution flow.
///
/// ## Parameters
/// - `op`: The opcode to check
///
/// ## Returns
/// - `true` for STOP, RETURN, REVERT, SELFDESTRUCT, INVALID
/// - `false` otherwise
///
/// ## Terminating Opcodes
/// - STOP (0x00): Halts execution successfully
/// - RETURN (0xF3): Returns data and halts successfully
/// - REVERT (0xFD): Reverts state changes and returns data
/// - SELFDESTRUCT (0xFF): Destroys contract and sends balance
/// - INVALID (0xFE): Invalid operation, always reverts
///
/// ## Usage
/// ```zig
/// if (is_terminating(opcode)) {
/// // This is the last operation in this context
/// return;
/// }
/// ```
pub fn is_terminating(op: u8) bool {
return op == STOP or op == RETURN or op == REVERT or op == SELFDESTRUCT or op == INVALID;
}
/// Check if an opcode is a call operation
pub fn is_call(op: u8) bool {
return op == CALL or op == CALLCODE or op == DELEGATECALL or op == STATICCALL or
op == EXTCALL or op == EXTDELEGATECALL or op == EXTSTATICCALL;
}
/// Check if an opcode is a create operation
pub fn is_create(op: u8) bool {
return op == CREATE or op == CREATE2;
}
/// Checks if an opcode can modify blockchain state.
///
/// State-modifying operations are restricted in static calls and
/// require special handling for gas accounting and rollback.
///
/// ## Parameters
/// - `op`: The opcode to check
///
/// ## Returns
/// - `true` for operations that modify storage, create contracts, or emit logs
/// - `false` for read-only operations
///
/// ## State-Modifying Opcodes
/// - SSTORE: Modifies contract storage
/// - CREATE/CREATE2: Deploys new contracts
/// - SELFDESTRUCT: Destroys contract and transfers balance
/// - LOG0-LOG4: Emits events (modifies receipts)
///
/// ## Note
/// CALL can also modify state indirectly if it transfers value,
/// but this function only checks direct state modifications.
///
/// ## Static Call Protection
/// These operations will fail with an error if executed within
/// a STATICCALL context.
pub fn modifies_state(op: u8) bool {
return op == SSTORE or op == CREATE or op == CREATE2 or op == SELFDESTRUCT or
op == LOG0 or op == LOG1 or op == LOG2 or op == LOG3 or op == LOG4;
}
/// Check if an opcode is valid
pub fn is_valid(op: u8) bool {
return op != INVALID;
}
// ============================================================================
// Contract Size and Gas Constants
// ============================================================================
/// Maximum allowed size for deployed contract bytecode.
///
/// ## Value
/// 24,576 bytes (24 KB)
///
/// ## Origin
/// Defined by EIP-170 (activated in Spurious Dragon hardfork)
///
/// ## Rationale
/// - Prevents excessive blockchain growth from large contracts
/// - Ensures contracts can be loaded into memory efficiently
/// - Encourages modular contract design
///
/// ## Implications
/// - Contract creation fails if initcode returns bytecode larger than this
/// - Does NOT limit initcode size (see EIP-3860 for that)
/// - Libraries and proxy patterns help work around this limit
///
/// Reference: https://eips.ethereum.org/EIPS/eip-170
pub const MAX_CODE_SIZE: u32 = 24576;
/// Gas cost per byte of deployed contract code.
///
/// ## Value
/// 200 gas per byte
///
/// ## Usage
/// Charged during contract creation (CREATE/CREATE2) based on the
/// size of the returned bytecode that will be stored on-chain.
///
/// ## Calculation
/// `deployment_gas_cost = len(returned_code) * 200`
///
/// ## Example
/// A 1000-byte contract costs an additional 200,000 gas to deploy
/// beyond the execution costs.
///
/// ## Note
/// This is separate from the initcode gas cost introduced in EIP-3860.
pub const DEPLOY_CODE_GAS_PER_BYTE: u64 = 200;
```
```zig [src/evm/constants/gas_constants.zig]
/// EVM gas cost constants for opcode execution
///
/// This module defines all gas cost constants used in EVM execution according
/// to the Ethereum Yellow Paper and various EIPs. Gas costs are critical for
/// preventing denial-of-service attacks and fairly pricing computational resources.
///
/// ## Gas Cost Categories
///
/// Operations are grouped by computational complexity:
/// - **Quick** (2 gas): Trivial operations like PC, MSIZE, GAS
/// - **Fastest** (3 gas): Simple arithmetic like ADD, SUB, NOT, LT, GT
/// - **Fast** (5 gas): More complex arithmetic like MUL, DIV, MOD
/// - **Mid** (8 gas): Advanced arithmetic like ADDMOD, MULMOD, SIGNEXTEND
/// - **Slow** (10 gas): Operations requiring more computation
/// - **Ext** (20+ gas): External operations like BALANCE, EXTCODESIZE
///
/// ## Historical Changes
///
/// Gas costs have evolved through various EIPs:
/// - EIP-150: Increased costs for IO-heavy operations
/// - EIP-2200: SSTORE net gas metering
/// - EIP-2929: Increased costs for cold storage/account access
/// - EIP-3529: Reduced refunds and cold access costs
/// - EIP-3860: Initcode metering
///
/// ## Usage
/// ```zig
/// const gas_cost = switch (opcode) {
/// 0x01 => GasFastestStep, // ADD
/// 0x02 => GasFastStep, // MUL
/// 0x20 => Keccak256Gas + (data_size_words * Keccak256WordGas),
/// else => 0,
/// };
/// ```
/// Gas cost for very cheap operations
/// Operations: ADDRESS, ORIGIN, CALLER, CALLVALUE, CALLDATASIZE, CODESIZE,
/// GASPRICE, RETURNDATASIZE, PC, MSIZE, GAS, CHAINID, SELFBALANCE
pub const GasQuickStep: u64 = 2;
/// Gas cost for simple arithmetic and logic operations
/// Operations: ADD, SUB, NOT, LT, GT, SLT, SGT, EQ, ISZERO, AND, OR, XOR,
/// CALLDATALOAD, MLOAD, MSTORE, MSTORE8, PUSH operations, DUP operations,
/// SWAP operations
pub const GasFastestStep: u64 = 3;
/// Gas cost for multiplication and division operations
/// Operations: MUL, DIV, SDIV, MOD, SMOD, EXP (per byte of exponent)
pub const GasFastStep: u64 = 5;
/// Gas cost for advanced arithmetic operations
/// Operations: ADDMOD, MULMOD, SIGNEXTEND, KECCAK256 (base cost)
pub const GasMidStep: u64 = 8;
/// Gas cost for operations requiring moderate computation
/// Operations: JUMPI
pub const GasSlowStep: u64 = 10;
/// Gas cost for operations that interact with other accounts/contracts
/// Operations: BALANCE, EXTCODESIZE, BLOCKHASH
pub const GasExtStep: u64 = 20;
// ============================================================================
// Hashing Operation Costs
// ============================================================================
/// Base gas cost for KECCAK256 (SHA3) operation
/// This is the fixed cost regardless of input size
pub const Keccak256Gas: u64 = 30;
/// Additional gas cost per 32-byte word for KECCAK256
/// Total cost = Keccak256Gas + (word_count * Keccak256WordGas)
pub const Keccak256WordGas: u64 = 6;
// ============================================================================
// Storage Operation Costs (EIP-2929 & EIP-2200)
// ============================================================================
/// Gas cost for SLOAD on a warm storage slot
/// After EIP-2929, warm access is significantly cheaper than cold
pub const SloadGas: u64 = 100;
/// Gas cost for first-time (cold) SLOAD access in a transaction
/// EIP-2929: Prevents underpriced state access attacks
pub const ColdSloadCost: u64 = 2100;
/// Gas cost for first-time (cold) account access in a transaction
/// EIP-2929: Applied to BALANCE, EXTCODESIZE, EXTCODECOPY, EXTCODEHASH, CALL family
pub const ColdAccountAccessCost: u64 = 2600;
/// Gas cost for warm storage read operations
/// EIP-2929: Subsequent accesses to the same slot/account in a transaction
pub const WarmStorageReadCost: u64 = 100;
/// Minimum gas that must remain for SSTORE to succeed
/// Prevents storage modifications when gas is nearly exhausted
pub const SstoreSentryGas: u64 = 2300;
/// Gas cost for SSTORE when setting a storage slot from zero to non-zero
/// This is the most expensive storage operation as it increases state size
pub const SstoreSetGas: u64 = 20000;
/// Gas cost for SSTORE when changing an existing non-zero value to another non-zero value
/// Cheaper than initial set since slot is already allocated
pub const SstoreResetGas: u64 = 5000;
/// Gas cost for SSTORE when clearing a storage slot (non-zero to zero)
/// Same cost as reset, but eligible for gas refund
pub const SstoreClearGas: u64 = 5000;
/// Gas refund for clearing storage slot to zero
/// EIP-3529: Reduced from 15000 to prevent gas refund abuse
pub const SstoreRefundGas: u64 = 4800;
// ============================================================================
// Control Flow Costs
// ============================================================================
/// Gas cost for JUMPDEST opcode
/// Minimal cost as it's just a marker for valid jump destinations
pub const JumpdestGas: u64 = 1;
// ============================================================================
// Logging Operation Costs
// ============================================================================
/// Base gas cost for LOG operations (LOG0-LOG4)
/// This is the fixed cost before considering data size and topics
pub const LogGas: u64 = 375;
/// Gas cost per byte of data in LOG operations
/// Incentivizes efficient event data usage
pub const LogDataGas: u64 = 8;
/// Gas cost per topic in LOG operations
/// Each additional topic (LOG1, LOG2, etc.) adds this cost
pub const LogTopicGas: u64 = 375;
// ============================================================================
// Contract Creation and Call Costs
// ============================================================================
/// Base gas cost for CREATE opcode
/// High cost reflects the expense of deploying new contracts
pub const CreateGas: u64 = 32000;
/// Base gas cost for CALL operations
/// This is the minimum cost before additional charges
pub const CallGas: u64 = 40;
/// Gas stipend provided to called contract when transferring value
/// Ensures called contract has minimum gas to execute basic operations
pub const CallStipend: u64 = 2300;
/// Additional gas cost when CALL transfers value (ETH)
/// Makes value transfers more expensive to prevent spam
pub const CallValueTransferGas: u64 = 9000;
/// Additional gas cost when CALL creates a new account
/// Reflects the cost of adding a new entry to the state trie
pub const CallNewAccountGas: u64 = 25000;
/// Gas refund for SELFDESTRUCT operation
/// Incentivizes cleaning up unused contracts
pub const SelfdestructRefundGas: u64 = 24000;
// ============================================================================
// Memory Expansion Costs
// ============================================================================
/// Linear coefficient for memory gas calculation
/// Part of the formula: gas = MemoryGas * words + words² / QuadCoeffDiv
pub const MemoryGas: u64 = 3;
/// Quadratic coefficient divisor for memory gas calculation
/// Makes memory expansion quadratically expensive to prevent DoS attacks
pub const QuadCoeffDiv: u64 = 512;
// ============================================================================
// Contract Deployment Costs
// ============================================================================
/// Gas cost per byte of contract deployment code
/// Applied to the bytecode being deployed via CREATE/CREATE2
pub const CreateDataGas: u64 = 200;
/// Gas cost per 32-byte word of initcode
/// EIP-3860: Prevents deploying excessively large contracts
pub const InitcodeWordGas: u64 = 2;
/// Maximum allowed initcode size in bytes
/// EIP-3860: Limit is 49152 bytes (2 * MAX_CODE_SIZE)
pub const MaxInitcodeSize: u64 = 49152;
// ============================================================================
// Transaction Costs
// ============================================================================
/// Base gas cost for a standard transaction
/// Minimum cost for any transaction regardless of data or computation
pub const TxGas: u64 = 21000;
/// Base gas cost for contract creation transaction
/// Higher than standard tx due to contract deployment overhead
pub const TxGasContractCreation: u64 = 53000;
/// Gas cost per zero byte in transaction data
/// Cheaper than non-zero bytes to incentivize data efficiency
pub const TxDataZeroGas: u64 = 4;
/// Gas cost per non-zero byte in transaction data
/// Higher cost reflects increased storage and bandwidth requirements
pub const TxDataNonZeroGas: u64 = 16;
/// Gas cost per word for copy operations
/// Applied to CODECOPY, EXTCODECOPY, RETURNDATACOPY, etc.
pub const CopyGas: u64 = 3;
/// Maximum gas refund as a fraction of gas used
/// EIP-3529: Reduced from 1/2 to 1/5 to prevent refund abuse
pub const MaxRefundQuotient: u64 = 5;
// ============================================================================
// EIP-4844: Shard Blob Transactions
// ============================================================================
/// Gas cost for BLOBHASH opcode
/// Returns the hash of a blob associated with the transaction
pub const BlobHashGas: u64 = 3;
/// Gas cost for BLOBBASEFEE opcode
/// Returns the base fee for blob gas
pub const BlobBaseFeeGas: u64 = 2;
// ============================================================================
// EIP-1153: Transient Storage
// ============================================================================
/// Gas cost for TLOAD (transient storage load)
/// Transient storage is cleared after each transaction
pub const TLoadGas: u64 = 100;
/// Gas cost for TSTORE (transient storage store)
/// Same cost as TLOAD, much cheaper than persistent storage
pub const TStoreGas: u64 = 100;
// ============================================================================
// Precompile Operation Costs
// ============================================================================
/// Base gas cost for IDENTITY precompile (address 0x04)
/// Minimum cost regardless of input size
pub const IDENTITY_BASE_COST: u64 = 15;
/// Gas cost per 32-byte word for IDENTITY precompile
/// Total cost = IDENTITY_BASE_COST + (word_count * IDENTITY_WORD_COST)
pub const IDENTITY_WORD_COST: u64 = 3;
/// Calculate memory expansion gas cost
///
/// Computes the gas cost for expanding EVM memory from current_size to new_size bytes.
/// Memory expansion follows a quadratic cost formula to prevent DoS attacks.
///
/// ## Parameters
/// - `current_size`: Current memory size in bytes
/// - `new_size`: Requested new memory size in bytes
///
/// ## Returns
/// - Gas cost for the expansion (0 if new_size <= current_size)
///
/// ## Formula
/// The total memory cost for n words is: 3n + n²/512
/// Where a word is 32 bytes.
///
/// Pre-computed memory expansion costs for common sizes.
///
/// This lookup table stores the total memory cost for sizes up to 32KB (1024 words).
/// Using a LUT converts runtime calculations to O(1) lookups for common cases.
/// The formula is: 3n + n²/512 where n is the number of 32-byte words.
pub const MEMORY_EXPANSION_LUT = blk: {
@setEvalBranchQuota(10000);
const max_words = 1024; // Pre-compute for up to 32KB of memory
var costs: [max_words]u64 = undefined;
for (0..max_words) |words| {
costs[words] = MemoryGas * words + (words * words) / QuadCoeffDiv;
}
break :blk costs;
};
/// The expansion cost is: total_cost(new_size) - total_cost(current_size)
///
/// ## Examples
/// - Expanding from 0 to 32 bytes (1 word): 3 + 0 = 3 gas
/// - Expanding from 0 to 64 bytes (2 words): 6 + 0 = 6 gas
/// - Expanding from 0 to 1024 bytes (32 words): 96 + 2 = 98 gas
/// - Expanding from 1024 to 2048 bytes: 294 - 98 = 196 gas
///
/// ## Edge Cases
/// - If new_size <= current_size, no expansion needed, returns 0
/// - Sizes are rounded up to the nearest word (32 bytes)
/// - At 32MB, gas cost exceeds 2 billion, effectively preventing larger allocations
///
/// ## Performance
/// - Uses pre-computed lookup table for sizes up to 32KB (O(1) lookup)
/// - Falls back to calculation for larger sizes
pub fn memory_gas_cost(current_size: u64, new_size: u64) u64 {
if (new_size <= current_size) return 0;
const current_words = (current_size + 31) / 32;
const new_words = (new_size + 31) / 32;
// Use lookup table for common cases (up to 32KB)
if (new_words < MEMORY_EXPANSION_LUT.len) {
const current_cost = if (current_words < MEMORY_EXPANSION_LUT.len)
MEMORY_EXPANSION_LUT[current_words]
else
MemoryGas * current_words + (current_words * current_words) / QuadCoeffDiv;
return MEMORY_EXPANSION_LUT[new_words] - current_cost;
}
// Fall back to calculation for larger sizes
const current_cost = MemoryGas * current_words + (current_words * current_words) / QuadCoeffDiv;
const new_cost = MemoryGas * new_words + (new_words * new_words) / QuadCoeffDiv;
return new_cost - current_cost;
}
```
```zig [src/evm/fee_market.zig]
const std = @import("std");
const Log = @import("log.zig");
// FeeMarket implements the EIP-1559 fee market mechanism
///
// The EIP-1559 fee market introduces a base fee per block that moves
// up or down based on how full the previous block was compared to the target.
///
// Key features:
// 1. Base fee per block that is burned (not paid to miners)
// 2. Priority fee (tip) that goes to miners
// 3. Base fee adjustment based on block fullness
/// Helper function to calculate fee delta safely avoiding overflow and division by zero
fn calculate_fee_delta(fee: u64, gas_delta: u64, gas_target: u64, denominator: u64) u64 {
// Using u128 for intermediate calculation to avoid overflow
const intermediate: u128 = @as(u128, fee) * @as(u128, gas_delta);
// Avoid division by zero
const divisor: u128 = @max(1, @as(u128, gas_target) * @as(u128, denominator));
const result: u64 = @intCast(@min(@as(u128, std.math.maxInt(u64)), intermediate / divisor));
// Always return at least 1 to ensure some movement
return @max(1, result);
}
/// Minimum base fee per gas (in wei)
/// This ensures the base fee never goes to zero
pub const MIN_BASE_FEE: u64 = 7;
/// Base fee change denominator
/// The base fee can change by at most 1/BASE_FEE_CHANGE_DENOMINATOR
/// (or 12.5% with the value of 8) between blocks
pub const BASE_FEE_CHANGE_DENOMINATOR: u64 = 8;
/// Initialize base fee for the first EIP-1559 block
///
/// This is used when transitioning from a pre-EIP-1559 chain to
/// an EIP-1559 enabled chain.
///
/// Parameters:
/// - parent_gas_used: Gas used by the parent block
/// - parent_gas_limit: Gas limit of the parent block
///
/// Returns: The initial base fee (in wei)
pub fn initial_base_fee(parent_gas_used: u64, parent_gas_limit: u64) u64 {
Log.debug("Initializing base fee for first EIP-1559 block", .{});
Log.debug("Parent block gas used: {d}, gas limit: {d}", .{ parent_gas_used, parent_gas_limit });
// Initial base fee formula from the EIP-1559 specification
// If the parent block used exactly the target gas, the initial base fee is 1 gwei
// If it used more, the initial base fee is higher
// If it used less, the initial base fee is lower
// Target gas usage is half the block gas limit
const parent_gas_target = parent_gas_limit / 2;
// Initial base fee calculation
var base_fee: u64 = 1_000_000_000; // 1 gwei in wei
// Adjust initial base fee based on parent block's gas usage
if (parent_gas_used > 0) {
const gas_used_delta = if (parent_gas_used > parent_gas_target)
parent_gas_used - parent_gas_target
else
parent_gas_target - parent_gas_used;
const base_fee_delta = calculate_fee_delta(base_fee, gas_used_delta, parent_gas_target, BASE_FEE_CHANGE_DENOMINATOR);
if (parent_gas_used > parent_gas_target) {
base_fee = base_fee + base_fee_delta;
} else if (base_fee > base_fee_delta) {
base_fee = base_fee - base_fee_delta;
}
}
// Ensure base fee is at least the minimum
base_fee = @max(base_fee, MIN_BASE_FEE);
Log.debug("Initial base fee calculated: {d} wei", .{base_fee});
return base_fee;
}
/// Calculate the next block's base fee based on the current block
///
/// This implements the EIP-1559 base fee adjustment algorithm:
/// - If the block used exactly the target gas, the base fee remains the same
/// - If the block used more than the target, the base fee increases
/// - If the block used less than the target, the base fee decreases
/// - The maximum change per block is 12.5% (1/8)
///
/// Parameters:
/// - parent_base_fee: Base fee of the parent block
/// - parent_gas_used: Gas used by the parent block
/// - parent_gas_target: Target gas usage of the parent block
///
/// Returns: The next block's base fee (in wei)
pub fn next_base_fee(parent_base_fee: u64, parent_gas_used: u64, parent_gas_target: u64) u64 {
Log.debug("Calculating next block's base fee", .{});
Log.debug("Parent block base fee: {d} wei", .{parent_base_fee});
Log.debug("Parent block gas used: {d}, gas target: {d}", .{ parent_gas_used, parent_gas_target });
// If parent block is empty, keep the base fee the same
// Skip the delta calculations and just return the parent fee directly
if (parent_gas_used == 0) {
Log.debug("Parent block was empty, keeping base fee the same: {d} wei", .{parent_base_fee});
return parent_base_fee;
}
// Calculate base fee delta
var new_base_fee = parent_base_fee;
if (parent_gas_used == parent_gas_target) {
// If parent block used exactly the target gas, keep the base fee the same
Log.debug("Parent block used exactly the target gas, keeping base fee the same", .{});
} else if (parent_gas_used > parent_gas_target) {
// If parent block used more than the target gas, increase the base fee
// Calculate gas used delta as a fraction of target
const gas_used_delta = parent_gas_used - parent_gas_target;
// Calculate the base fee delta (max 12.5% increase)
const base_fee_delta = calculate_fee_delta(parent_base_fee, gas_used_delta, parent_gas_target, BASE_FEE_CHANGE_DENOMINATOR);
// Increase the base fee
// The overflow check is probably unnecessary given gas limits, but it's a good safety measure
new_base_fee = std.math.add(u64, parent_base_fee, base_fee_delta) catch parent_base_fee;
Log.debug("Parent block used more than target gas, increasing base fee by {d} wei", .{base_fee_delta});
} else {
// If parent block used less than the target gas, decrease the base fee
// Calculate gas used delta as a fraction of target
const gas_used_delta = parent_gas_target - parent_gas_used;
// Calculate the base fee delta (max 12.5% decrease)
const base_fee_delta = calculate_fee_delta(parent_base_fee, gas_used_delta, parent_gas_target, BASE_FEE_CHANGE_DENOMINATOR);
// Decrease the base fee, but don't go below the minimum
new_base_fee = if (parent_base_fee > base_fee_delta)
parent_base_fee - base_fee_delta
else
MIN_BASE_FEE;
Log.debug("Parent block used less than target gas, decreasing base fee by {d} wei", .{base_fee_delta});
}
// Ensure base fee is at least the minimum
new_base_fee = @max(new_base_fee, MIN_BASE_FEE);
Log.debug("Next block base fee calculated: {d} wei", .{new_base_fee});
return new_base_fee;
}
/// Calculate the effective gas price for an EIP-1559 transaction
///
/// The effective gas price is the minimum of:
/// 1. max_fee_per_gas specified by the sender
/// 2. base_fee_per_gas + max_priority_fee_per_gas
///
/// Parameters:
/// - base_fee_per_gas: Current block's base fee
/// - max_fee_per_gas: Maximum fee the sender is willing to pay
/// - max_priority_fee_per_gas: Maximum tip the sender is willing to pay to the miner
///
/// Returns: The effective gas price, and the miner's portion of the fee
pub fn get_effective_gas_price(base_fee_per_gas: u64, max_fee_per_gas: u64, max_priority_fee_per_gas: u64) struct { effective_gas_price: u64, miner_fee: u64 } {
Log.debug("Calculating effective gas price", .{});
Log.debug("Base fee: {d}, max fee: {d}, max priority fee: {d}", .{ base_fee_per_gas, max_fee_per_gas, max_priority_fee_per_gas });
// Ensure the transaction at least pays the base fee
if (max_fee_per_gas < base_fee_per_gas) {
std.log.warn("Transaction's max fee ({d}) is less than base fee ({d})", .{ max_fee_per_gas, base_fee_per_gas });
// In a real implementation, this transaction would be rejected
// For now, just return the max fee and zero miner fee
return .{ .effective_gas_price = max_fee_per_gas, .miner_fee = 0 };
}
// Calculate the priority fee (tip to miner)
// This is limited by both max_priority_fee_per_gas and the leftover after base fee
const max_priority_fee = @min(max_priority_fee_per_gas, max_fee_per_gas - base_fee_per_gas);
// The effective gas price is base fee plus priority fee
const effective_gas_price = base_fee_per_gas + max_priority_fee;
Log.debug("Effective gas price: {d} wei", .{effective_gas_price});
Log.debug("Miner fee (priority fee): {d} wei", .{max_priority_fee});
return .{ .effective_gas_price = effective_gas_price, .miner_fee = max_priority_fee };
}
/// Get the gas target for a block
///
/// The gas target is the desired gas usage per block, which is typically
/// half of the maximum gas limit.
///
/// Parameters:
/// - gas_limit: The block's gas limit
///
/// Returns: The gas target for the block
pub fn get_gas_target(gas_limit: u64) u64 {
return gas_limit / 2;
}
```
```zig [src/evm/state/evm_log.zig]
const Address = @import("Address");
/// EVM event log representation
///
/// This struct represents a log entry emitted by smart contracts using the LOG0-LOG4 opcodes.
/// Logs are a crucial part of the Ethereum event system, allowing contracts to emit indexed
/// data that can be efficiently queried by external applications.
///
/// ## Overview
///
/// Event logs serve multiple purposes in the EVM:
/// - **Event Notification**: Notify external applications about state changes
/// - **Cheaper Storage**: Store data in logs instead of contract storage (much cheaper gas cost)
/// - **Historical Queries**: Enable efficient querying of past events
/// - **Debugging**: Provide insight into contract execution
///
/// ## Log Structure
///
/// Each log entry contains:
/// - **Address**: The contract that emitted the log
/// - **Topics**: Up to 4 indexed 32-byte values for efficient filtering
/// - **Data**: Arbitrary length non-indexed data
///
/// ## Topics vs Data
///
/// The distinction between topics and data is important:
/// - **Topics**: Indexed for efficient filtering, limited to 4 entries of 32 bytes each
/// - **Data**: Not indexed, can be arbitrary length, cheaper to include
///
/// ## Gas Costs
///
/// - LOG0: 375 gas base + 8 gas per byte of data
/// - LOG1-LOG4: 375 gas base + 375 gas per topic + 8 gas per byte of data
///
/// ## Example Usage
///
/// In Solidity:
/// ```solidity
/// event Transfer(address indexed from, address indexed to, uint256 value);
/// emit Transfer(msg.sender, recipient, amount);
/// ```
///
/// This would create a log with:
/// - topics[0]: keccak256("Transfer(address,address,uint256)")
/// - topics[1]: from address (indexed)
/// - topics[2]: to address (indexed)
/// - data: encoded uint256 value
const Self = @This();
/// The address of the contract that emitted this log
address: Address.Address,
/// Indexed topics for efficient log filtering
///
/// - First topic (if any) is typically the event signature hash
/// - Subsequent topics are indexed event parameters
/// - Maximum of 4 topics per log (LOG0 has 0, LOG4 has 4)
topics: []const u256,
/// Non-indexed event data
///
/// Contains ABI-encoded event parameters that were not marked as indexed.
/// This data is not searchable but is cheaper to include than topics.
data: []const u8,
```
```zig [src/evm/state/storage_key.zig]
const std = @import("std");
const Address = @import("Address");
/// Composite key for EVM storage operations combining address and slot.
///
/// The StorageKey uniquely identifies a storage location within the EVM by
/// combining a contract address with a 256-bit storage slot number. This is
/// fundamental to how the EVM organizes persistent contract storage.
///
/// ## Design Rationale
/// Each smart contract has its own isolated storage space addressed by 256-bit
/// slots. To track storage across multiple contracts in a single VM instance,
/// we need a composite key that includes both the contract address and the
/// slot number.
///
/// ## Storage Model
/// In the EVM:
/// - Each contract has 2^256 storage slots
/// - Each slot can store a 256-bit value
/// - Slots are initially zero and only consume gas when first written
///
/// ## Usage
/// ```zig
/// const key = StorageKey{
/// .address = contract_address,
/// .slot = 0x0, // First storage slot
/// };
///
/// // Use in hash maps for storage tracking
/// var storage = std.AutoHashMap(StorageKey, u256).init(allocator);
/// try storage.put(key, value);
/// ```
///
/// ## Hashing Strategy
/// The key implements a generic hash function that works with any hasher
/// implementing the standard update() interface. The address is hashed first,
/// followed by the slot number in big-endian format.
const Self = @This();
/// The contract address that owns this storage slot.
/// Standard 20-byte Ethereum address.
address: Address.Address,
/// The 256-bit storage slot number within the contract's storage space.
/// Slots are sparsely allocated - most remain at zero value.
slot: u256,
/// Compute a hash of this storage key for use in hash maps.
///
/// This function is designed to work with Zig's AutoHashMap and any
/// hasher that implements the standard `update([]const u8)` method.
///
/// The hash combines both the address and slot to ensure unique hashes
/// for different storage locations. The slot is converted to big-endian
/// bytes to ensure consistent hashing across different architectures.
///
/// @param self The storage key to hash
/// @param hasher Any hasher with an update() method
///
/// Example:
/// ```zig
/// var map = std.AutoHashMap(StorageKey, u256).init(allocator);
/// const key = StorageKey{ .address = addr, .slot = slot };
/// try map.put(key, value); // Uses hash() internally
/// ```
pub fn hash(self: Self, hasher: anytype) void {
// Hash the address bytes
hasher.update(&self.address);
// Hash the slot as bytes in big-endian format for consistency
var slot_bytes: [32]u8 = undefined;
std.mem.writeInt(u256, &slot_bytes, self.slot, .big);
hasher.update(&slot_bytes);
}
/// Check equality between two storage keys.
///
/// Two storage keys are equal if and only if both their address and
/// slot number match exactly. This is used by hash maps to resolve
/// collisions and find exact matches.
///
/// @param a First storage key
/// @param b Second storage key
/// @return true if both address and slot match
///
/// Example:
/// ```zig
/// const key1 = StorageKey{ .address = addr, .slot = 0 };
/// const key2 = StorageKey{ .address = addr, .slot = 0 };
/// std.debug.assert(key1.eql(key2));
/// ```
pub fn eql(a: Self, b: Self) bool {
return std.mem.eql(u8, &a.address, &b.address) and a.slot == b.slot;
}
```
```zig [src/evm/state/state.zig]
//! EVM state management module - Tracks blockchain state during execution
//!
//! This module provides the state storage layer for the EVM, managing all
//! mutable blockchain state including account balances, storage, code, nonces,
//! transient storage, and event logs.
//!
//! ## State Components
//!
//! The EVM state consists of:
//! - **Account State**: Balances, nonces, and contract code
//! - **Persistent Storage**: Contract storage slots (SSTORE/SLOAD)
//! - **Transient Storage**: Temporary storage within transactions (TSTORE/TLOAD)
//! - **Event Logs**: Emitted events from LOG0-LOG4 opcodes
//!
//! ## Design Philosophy
//!
//! This implementation uses hash maps for efficient lookups and modifications.
//! All state changes are applied immediately (no journaling in this layer).
//! For transaction rollback support, this should be wrapped in a higher-level
//! state manager that implements checkpointing/journaling.
//!
//! ## Memory Management
//!
//! All state data is heap-allocated using the provided allocator. The state
//! owns all data it stores and properly cleans up in deinit().
//!
//! ## Thread Safety
//!
//! This implementation is NOT thread-safe. Concurrent access must be synchronized
//! externally.
const std = @import("std");
const Address = @import("Address");
const EvmLog = @import("evm_log.zig");
const StorageKey = @import("storage_key.zig");
const Log = @import("../log.zig");
/// EVM state container
///
/// Manages all mutable blockchain state during EVM execution.
/// This includes account data, storage, and transaction artifacts.
const Self = @This();
/// Memory allocator for all state allocations
allocator: std.mem.Allocator,
/// Persistent contract storage (SSTORE/SLOAD)
/// Maps (address, slot) -> value
storage: std.AutoHashMap(StorageKey, u256),
/// Account balances in wei
/// Maps address -> balance
balances: std.AutoHashMap(Address.Address, u256),
/// Contract bytecode
/// Maps address -> code bytes
/// Empty slice for EOAs (Externally Owned Accounts)
code: std.AutoHashMap(Address.Address, []const u8),
/// Account nonces (transaction counters)
/// Maps address -> nonce
/// Incremented on each transaction from the account
nonces: std.AutoHashMap(Address.Address, u64),
/// Transient storage (EIP-1153: TSTORE/TLOAD)
/// Maps (address, slot) -> value
/// Cleared after each transaction
transient_storage: std.AutoHashMap(StorageKey, u256),
/// Event logs emitted during execution
/// Ordered list of all LOG0-LOG4 events
logs: std.ArrayList(EvmLog),
/// Initialize a new EVM state instance
///
/// Creates empty state with the provided allocator. All maps and lists
/// are initialized empty.
///
/// ## Parameters
/// - `allocator`: Memory allocator for all state allocations
///
/// ## Returns
/// - Success: New initialized state instance
/// - Error: OutOfMemory if allocation fails
///
/// ## Example
/// ```zig
/// var state = try EvmState.init(allocator);
/// defer state.deinit();
/// ```
pub fn init(allocator: std.mem.Allocator) std.mem.Allocator.Error!Self {
Log.debug("EvmState.init: Initializing EVM state with allocator", .{});
var storage = std.AutoHashMap(StorageKey, u256).init(allocator);
errdefer storage.deinit();
var balances = std.AutoHashMap(Address.Address, u256).init(allocator);
errdefer balances.deinit();
var code = std.AutoHashMap(Address.Address, []const u8).init(allocator);
errdefer code.deinit();
var nonces = std.AutoHashMap(Address.Address, u64).init(allocator);
errdefer nonces.deinit();
var transient_storage = std.AutoHashMap(StorageKey, u256).init(allocator);
errdefer transient_storage.deinit();
var logs = std.ArrayList(EvmLog).init(allocator);
errdefer logs.deinit();
Log.debug("EvmState.init: EVM state initialization complete", .{});
return Self{
.allocator = allocator,
.storage = storage,
.balances = balances,
.code = code,
.nonces = nonces,
.transient_storage = transient_storage,
.logs = logs,
};
}
/// Clean up all allocated resources
///
/// Frees all memory used by the state, including:
/// - All hash maps
/// - Log data (topics and data arrays)
/// - Any allocated slices
///
/// ## Important
/// After calling deinit(), the state instance is invalid and
/// must not be used.
pub fn deinit(self: *Self) void {
Log.debug("EvmState.deinit: Cleaning up EVM state, storage_count={}, balance_count={}, code_count={}, logs_count={}", .{
self.storage.count(), self.balances.count(), self.code.count(), self.logs.items.len
});
self.storage.deinit();
self.balances.deinit();
self.code.deinit();
self.nonces.deinit();
self.transient_storage.deinit();
// Clean up logs - free allocated memory for topics and data
for (self.logs.items) |log| {
self.allocator.free(log.topics);
self.allocator.free(log.data);
}
self.logs.deinit();
Log.debug("EvmState.deinit: EVM state cleanup complete", .{});
}
// State access methods
/// Get a value from persistent storage
///
/// Reads a storage slot for the given address. Returns 0 for
/// uninitialized slots (EVM default).
///
/// ## Parameters
/// - `address`: Contract address
/// - `slot`: Storage slot number
///
/// ## Returns
/// The stored value, or 0 if not set
///
/// ## Gas Cost
/// In real EVM: 100-2100 gas depending on cold/warm access
pub fn get_storage(self: *const Self, address: Address.Address, slot: u256) u256 {
const key = StorageKey{ .address = address, .slot = slot };
const value = self.storage.get(key) orelse 0;
Log.debug("EvmState.get_storage: addr={x}, slot={}, value={}", .{ Address.to_u256(address), slot, value });
return value;
}
/// Set a value in persistent storage
///
/// Updates a storage slot for the given address. Setting a value
/// to 0 is different from deleting it - it still consumes storage.
///
/// ## Parameters
/// - `address`: Contract address
/// - `slot`: Storage slot number
/// - `value`: Value to store
///
/// ## Returns
/// - Success: void
/// - Error: OutOfMemory if map expansion fails
///
/// ## Gas Cost
/// In real EVM: 2900-20000 gas depending on current/new value
pub fn set_storage(self: *Self, address: Address.Address, slot: u256, value: u256) std.mem.Allocator.Error!void {
const key = StorageKey{ .address = address, .slot = slot };
Log.debug("EvmState.set_storage: addr={x}, slot={}, value={}", .{ Address.to_u256(address), slot, value });
try self.storage.put(key, value);
}
/// Get account balance
///
/// Returns the balance in wei for the given address.
/// Non-existent accounts have balance 0.
///
/// ## Parameters
/// - `address`: Account address
///
/// ## Returns
/// Balance in wei (0 for non-existent accounts)
pub fn get_balance(self: *const Self, address: Address.Address) u256 {
const balance = self.balances.get(address) orelse 0;
Log.debug("EvmState.get_balance: addr={x}, balance={}", .{ Address.to_u256(address), balance });
return balance;
}
/// Set account balance
///
/// Updates the balance for the given address. Setting balance
/// creates the account if it doesn't exist.
///
/// ## Parameters
/// - `address`: Account address
/// - `balance`: New balance in wei
///
/// ## Returns
/// - Success: void
/// - Error: OutOfMemory if map expansion fails
///
/// ## Note
/// Balance can exceed total ETH supply in test scenarios
pub fn set_balance(self: *Self, address: Address.Address, balance: u256) std.mem.Allocator.Error!void {
Log.debug("EvmState.set_balance: addr={x}, balance={}", .{ Address.to_u256(address), balance });
try self.balances.put(address, balance);
}
/// Get contract code
///
/// Returns the bytecode deployed at the given address.
/// EOAs and non-existent accounts return empty slice.
///
/// ## Parameters
/// - `address`: Contract address
///
/// ## Returns
/// Contract bytecode (empty slice for EOAs)
///
/// ## Note
/// The returned slice is owned by the state - do not free
pub fn get_code(self: *const Self, address: Address.Address) []const u8 {
const code = self.code.get(address) orelse &[_]u8{};
Log.debug("EvmState.get_code: addr={x}, code_len={}", .{ Address.to_u256(address), code.len });
return code;
}
/// Set contract code
///
/// Deploys bytecode to the given address. The state takes
/// ownership of the code slice.
///
/// ## Parameters
/// - `address`: Contract address
/// - `code`: Bytecode to deploy
///
/// ## Returns
/// - Success: void
/// - Error: OutOfMemory if map expansion fails
///
/// ## Important
/// The state does NOT copy the code - it takes ownership
/// of the provided slice
pub fn set_code(self: *Self, address: Address.Address, code: []const u8) std.mem.Allocator.Error!void {
Log.debug("EvmState.set_code: addr={x}, code_len={}", .{ Address.to_u256(address), code.len });
try self.code.put(address, code);
}
/// Get account nonce
///
/// Returns the transaction count for the given address.
/// Non-existent accounts have nonce 0.
///
/// ## Parameters
/// - `address`: Account address
///
/// ## Returns
/// Current nonce (0 for new accounts)
///
/// ## Note
/// Nonce prevents transaction replay attacks
pub fn get_nonce(self: *const Self, address: Address.Address) u64 {
const nonce = self.nonces.get(address) orelse 0;
Log.debug("EvmState.get_nonce: addr={x}, nonce={}", .{ Address.to_u256(address), nonce });
return nonce;
}
/// Set account nonce
///
/// Updates the transaction count for the given address.
///
/// ## Parameters
/// - `address`: Account address
/// - `nonce`: New nonce value
///
/// ## Returns
/// - Success: void
/// - Error: OutOfMemory if map expansion fails
///
/// ## Warning
/// Setting nonce below current value can enable replay attacks
pub fn set_nonce(self: *Self, address: Address.Address, nonce: u64) std.mem.Allocator.Error!void {
Log.debug("EvmState.set_nonce: addr={x}, nonce={}", .{ Address.to_u256(address), nonce });
try self.nonces.put(address, nonce);
}
/// Increment account nonce
///
/// Atomically increments the nonce and returns the previous value.
/// Used when processing transactions from an account.
///
/// ## Parameters
/// - `address`: Account address
///
/// ## Returns
/// - Success: Previous nonce value (before increment)
/// - Error: OutOfMemory if map expansion fails
///
/// ## Example
/// ```zig
/// const tx_nonce = try state.increment_nonce(sender);
/// // tx_nonce is used for the transaction
/// // account nonce is now tx_nonce + 1
/// ```
pub fn increment_nonce(self: *Self, address: Address.Address) std.mem.Allocator.Error!u64 {
const current_nonce = self.get_nonce(address);
const new_nonce = current_nonce + 1;
Log.debug("EvmState.increment_nonce: addr={x}, old_nonce={}, new_nonce={}", .{ Address.to_u256(address), current_nonce, new_nonce });
try self.set_nonce(address, new_nonce);
return current_nonce;
}
// Transient storage methods
/// Get a value from transient storage
///
/// Reads a transient storage slot (EIP-1153). Transient storage
/// is cleared after each transaction, making it cheaper than
/// persistent storage for temporary data.
///
/// ## Parameters
/// - `address`: Contract address
/// - `slot`: Storage slot number
///
/// ## Returns
/// The stored value, or 0 if not set
///
/// ## Gas Cost
/// TLOAD: 100 gas (always warm)
pub fn get_transient_storage(self: *const Self, address: Address.Address, slot: u256) u256 {
const key = StorageKey{ .address = address, .slot = slot };
const value = self.transient_storage.get(key) orelse 0;
Log.debug("EvmState.get_transient_storage: addr={x}, slot={}, value={}", .{ Address.to_u256(address), slot, value });
return value;
}
/// Set a value in transient storage
///
/// Updates a transient storage slot (EIP-1153). Values are
/// automatically cleared after the transaction completes.
///
/// ## Parameters
/// - `address`: Contract address
/// - `slot`: Storage slot number
/// - `value`: Value to store temporarily
///
/// ## Returns
/// - Success: void
/// - Error: OutOfMemory if map expansion fails
///
/// ## Gas Cost
/// TSTORE: 100 gas (always warm)
///
/// ## Use Cases
/// - Reentrancy locks
/// - Temporary computation results
/// - Cross-contract communication within a transaction
pub fn set_transient_storage(self: *Self, address: Address.Address, slot: u256, value: u256) std.mem.Allocator.Error!void {
const key = StorageKey{ .address = address, .slot = slot };
Log.debug("EvmState.set_transient_storage: addr={x}, slot={}, value={}", .{ Address.to_u256(address), slot, value });
try self.transient_storage.put(key, value);
}
// Log methods
/// Emit an event log
///
/// Records an event log from LOG0-LOG4 opcodes. The log is added
/// to the transaction's log list and cannot be removed.
///
/// ## Parameters
/// - `address`: Contract emitting the log
/// - `topics`: Indexed topics (0-4 entries)
/// - `data`: Non-indexed log data
///
/// ## Returns
/// - Success: void
/// - Error: OutOfMemory if allocation fails
///
/// ## Memory Management
/// This function copies both topics and data to ensure they
/// persist beyond the current execution context.
///
/// ## Example
/// ```zig
/// // Emit Transfer event
/// const topics = [_]u256{
/// 0x123..., // Transfer event signature
/// from_addr, // indexed from
/// to_addr, // indexed to
/// };
/// const data = encode_u256(amount);
/// try state.emit_log(contract_addr, &topics, data);
/// ```
pub fn emit_log(self: *Self, address: Address.Address, topics: []const u256, data: []const u8) std.mem.Allocator.Error!void {
Log.debug("EvmState.emit_log: addr={x}, topics_len={}, data_len={}", .{ Address.to_u256(address), topics.len, data.len });
// Clone the data to ensure it persists
const data_copy = try self.allocator.alloc(u8, data.len);
@memcpy(data_copy, data);
// Clone the topics to ensure they persist
const topics_copy = try self.allocator.alloc(u256, topics.len);
@memcpy(topics_copy, topics);
const log = EvmLog{
.address = address,
.topics = topics_copy,
.data = data_copy,
};
try self.logs.append(log);
Log.debug("EvmState.emit_log: Log emitted, total_logs={}", .{self.logs.items.len});
}
```
```zig [src/evm/vm.zig]
const std = @import("std");
const Contract = @import("contract/contract.zig");
const Stack = @import("stack/stack.zig");
const JumpTable = @import("jump_table/jump_table.zig");
const Frame = @import("frame.zig");
const Operation = @import("opcodes/operation.zig");
const Address = @import("Address");
const StoragePool = @import("contract/storage_pool.zig");
const AccessList = @import("access_list/access_list.zig");
const ExecutionError = @import("execution/execution_error.zig");
const rlp = @import("Rlp");
const Keccak256 = std.crypto.hash.sha3.Keccak256;
const ChainRules = @import("hardforks/chain_rules.zig");
const gas_constants = @import("constants/gas_constants.zig");
const constants = @import("constants/constants.zig");
const Log = @import("log.zig");
const EvmLog = @import("state/evm_log.zig");
const Context = @import("context.zig");
const EvmState = @import("state/state.zig");
pub const StorageKey = @import("state/storage_key.zig");
pub const CreateResult = @import("create_result.zig");
pub const CallResult = @import("call_result.zig");
pub const RunResult = @import("run_result.zig");
const Hardfork = @import("hardforks/hardfork.zig").Hardfork;
const precompiles = @import("precompiles/precompiles.zig");
/// Virtual Machine for executing Ethereum bytecode.
///
/// Manages contract execution, gas accounting, state access, and protocol enforcement
/// according to the configured hardfork rules. Supports the full EVM instruction set
/// including contract creation, calls, and state modifications.
const Self = @This();
/// Memory allocator for VM operations
allocator: std.mem.Allocator,
/// Return data from the most recent operation
return_data: []u8 = &[_]u8{},
/// Legacy stack field (unused in current implementation)
stack: Stack = .{},
/// Opcode dispatch table for the configured hardfork
table: JumpTable,
/// Protocol rules for the current hardfork
chain_rules: ChainRules,
// TODO should be injected
/// World state including accounts, storage, and code
state: EvmState,
/// Transaction and block context
context: Context,
/// Warm/cold access tracking for EIP-2929 gas costs
access_list: AccessList,
/// Current call depth for overflow protection
depth: u16 = 0,
/// Whether the current context is read-only (STATICCALL)
read_only: bool = false,
/// Initialize VM with a jump table and corresponding chain rules.
///
/// @param allocator Memory allocator for VM operations
/// @param jump_table Optional jump table. If null, uses JumpTable.DEFAULT (latest hardfork)
/// @param chain_rules Optional chain rules. If null, uses ChainRules.DEFAULT (latest hardfork)
/// @return Initialized VM instance
///
/// Example with custom jump table and rules:
/// ```zig
/// const my_table = comptime JumpTable.init_from_hardfork(.BERLIN);
/// const my_rules = ChainRules.for_hardfork(.BERLIN);
/// var vm = try VM.init(allocator, &my_table, &my_rules);
/// ```
///
/// Example with default (latest):
/// ```zig
/// var vm = try VM.init(allocator, null, null);
/// ```
pub fn init(allocator: std.mem.Allocator, jump_table: ?*const JumpTable, chain_rules: ?*const ChainRules) std.mem.Allocator.Error!Self {
Log.debug("VM.init: Initializing VM with allocator", .{});
var state = try EvmState.init(allocator);
errdefer state.deinit();
var access_list = AccessList.init(allocator);
errdefer access_list.deinit();
Log.debug("VM.init: VM initialization complete", .{});
return Self{
.allocator = allocator,
.table = (jump_table orelse &JumpTable.DEFAULT).*,
.chain_rules = (chain_rules orelse &ChainRules.DEFAULT).*,
.state = state,
.context = Context.init(),
.access_list = access_list,
};
}
/// Initialize VM with a specific hardfork.
/// Convenience function that creates the jump table at runtime.
/// For production use, consider pre-generating the jump table at compile time.
pub fn init_with_hardfork(allocator: std.mem.Allocator, hardfork: Hardfork) std.mem.Allocator.Error!Self {
const table = JumpTable.init_from_hardfork(hardfork);
const rules = ChainRules.for_hardfork(hardfork);
return init(allocator, &table, &rules);
}
/// Free all VM resources.
/// Must be called when finished with the VM to prevent memory leaks.
pub fn deinit(self: *Self) void {
self.state.deinit();
self.access_list.deinit();
Contract.clear_analysis_cache(self.allocator);
}
/// Execute contract bytecode and return the result.
///
/// This is the main execution entry point. The contract must be properly initialized
/// with bytecode, gas limit, and input data. The VM executes opcodes sequentially
/// until completion, error, or gas exhaustion.
///
/// Time complexity: O(n) where n is the number of opcodes executed.
/// Memory: May allocate for return data if contract returns output.
///
/// Example:
/// ```zig
/// var contract = Contract.init_at_address(caller, addr, 0, 100000, code, input, false);
/// defer contract.deinit(vm.allocator, null);
/// try vm.state.set_code(addr, code);
/// const result = try vm.interpret(&contract, input);
/// defer if (result.output) |output| vm.allocator.free(output);
/// ```
///
/// See also: interpret_static() for read-only execution
pub fn interpret(self: *Self, contract: *Contract, input: []const u8) ExecutionError.Error!RunResult {
return try self.interpret_with_context(contract, input, false);
}
/// Execute contract bytecode in read-only mode.
/// Identical to interpret() but prevents any state modifications.
/// Used for view functions and static analysis.
pub fn interpret_static(self: *Self, contract: *Contract, input: []const u8) ExecutionError.Error!RunResult {
return try self.interpret_with_context(contract, input, true);
}
/// Core bytecode execution with configurable static context.
/// Runs the main VM loop, executing opcodes sequentially while tracking
/// gas consumption and handling control flow changes.
pub fn interpret_with_context(self: *Self, contract: *Contract, input: []const u8, is_static: bool) ExecutionError.Error!RunResult {
@branchHint(.likely);
Log.debug("VM.interpret_with_context: Starting execution, depth={}, gas={}, static={}", .{ self.depth, contract.gas, is_static });
self.depth += 1;
defer self.depth -= 1;
const prev_read_only = self.read_only;
defer self.read_only = prev_read_only;
self.read_only = self.read_only or is_static;
const initial_gas = contract.gas;
var pc: usize = 0;
var frame = try Frame.init(self.allocator, contract);
defer frame.deinit();
frame.memory.finalize_root();
frame.is_static = self.read_only;
frame.depth = @as(u32, @intCast(self.depth));
frame.input = input;
frame.gas_remaining = contract.gas;
const interpreter_ptr: *Operation.Interpreter = @ptrCast(self);
const state_ptr: *Operation.State = @ptrCast(&frame);
while (pc < contract.code_size) {
@branchHint(.likely);
const opcode = contract.get_op(pc);
frame.pc = pc;
const result = self.table.execute(pc, interpreter_ptr, state_ptr, opcode) catch |err| {
@branchHint(.likely);
contract.gas = frame.gas_remaining;
self.return_data = @constCast(frame.return_data_buffer);
var output: ?[]const u8 = null;
if (frame.return_data_buffer.len > 0) {
output = self.allocator.dupe(u8, frame.return_data_buffer) catch {
// We are out of memory, which is a critical failure. The safest way to
// handle this is to treat it as an OutOfGas error, which consumes
// all gas and stops execution.
return RunResult.init(initial_gas, 0, .OutOfGas, ExecutionError.Error.OutOfMemory, null);
};
}
return switch (err) {
ExecutionError.Error.InvalidOpcode => {
@branchHint(.cold);
// INVALID opcode consumes all remaining gas
frame.gas_remaining = 0;
contract.gas = 0;
return RunResult.init(initial_gas, 0, .Invalid, err, output);
},
ExecutionError.Error.STOP => {
return RunResult.init(initial_gas, frame.gas_remaining, .Success, null, output);
},
ExecutionError.Error.REVERT => {
return RunResult.init(initial_gas, frame.gas_remaining, .Revert, err, output);
},
ExecutionError.Error.OutOfGas => {
return RunResult.init(initial_gas, frame.gas_remaining, .OutOfGas, err, output);
},
ExecutionError.Error.InvalidJump,
ExecutionError.Error.StackUnderflow,
ExecutionError.Error.StackOverflow,
ExecutionError.Error.StaticStateChange,
ExecutionError.Error.WriteProtection,
ExecutionError.Error.DepthLimit,
ExecutionError.Error.MaxCodeSizeExceeded,
ExecutionError.Error.OutOfMemory,
=> {
@branchHint(.cold);
return RunResult.init(initial_gas, frame.gas_remaining, .Invalid, err, output);
},
else => return err, // Unexpected error
};
};
if (frame.pc != pc) {
@branchHint(.likely);
pc = frame.pc;
} else {
pc += result.bytes_consumed;
}
}
contract.gas = frame.gas_remaining;
self.return_data = @constCast(frame.return_data_buffer);
const output: ?[]const u8 = if (frame.return_data_buffer.len > 0) try self.allocator.dupe(u8, frame.return_data_buffer) else null;
return RunResult.init(
initial_gas,
frame.gas_remaining,
.Success,
null,
output,
);
}
fn create_contract_internal(self: *Self, creator: Address.Address, value: u256, init_code: []const u8, gas: u64, new_address: Address.Address) std.mem.Allocator.Error!CreateResult {
if (self.state.get_code(new_address).len > 0) {
@branchHint(.unlikely);
// Contract already exists at this address
return CreateResult.initFailure(gas, null);
}
const creator_balance = self.state.get_balance(creator);
if (creator_balance < value) {
@branchHint(.unlikely);
return CreateResult.initFailure(gas, null);
}
if (value > 0) {
try self.state.set_balance(creator, creator_balance - value);
try self.state.set_balance(new_address, value);
}
if (init_code.len == 0) {
// No init code means empty contract
return CreateResult{
.success = true,
.address = new_address,
.gas_left = gas,
.output = null,
};
}
var hasher = Keccak256.init(.{});
hasher.update(init_code);
var code_hash: [32]u8 = undefined;
hasher.final(&code_hash);
var init_contract = Contract.init(
creator, // caller (who is creating this contract)
new_address, // address (the new contract's address)
value, // value being sent to this contract
gas, // gas available for init code execution
init_code, // the init code to execute
code_hash, // hash of the init code
&[_]u8{}, // no input data for init code
false, // not static
);
defer init_contract.deinit(self.allocator, null);
// Execute the init code - this should return the deployment bytecode
const init_result = self.interpret_with_context(&init_contract, &[_]u8{}, false) catch |err| {
if (err == ExecutionError.Error.REVERT) {
// On revert, we should still consume gas but not all
return CreateResult.initFailure(init_contract.gas, null);
}
// Most initcode failures should return 0 address and consume all gas
return CreateResult.initFailure(0, null);
};
const deployment_code = init_result.output orelse &[_]u8{};
// Check EIP-170 MAX_CODE_SIZE limit on the returned bytecode (24,576 bytes)
if (deployment_code.len > constants.MAX_CODE_SIZE) {
return CreateResult.initFailure(0, null);
}
const deploy_code_gas = @as(u64, @intCast(deployment_code.len)) * constants.DEPLOY_CODE_GAS_PER_BYTE;
if (deploy_code_gas > init_result.gas_left) {
return CreateResult.initFailure(0, null);
}
try self.state.set_code(new_address, deployment_code);
const gas_left = init_result.gas_left - deploy_code_gas;
return CreateResult{
.success = true,
.address = new_address,
.gas_left = gas_left,
.output = deployment_code,
};
}
// Contract creation with CREATE opcode
pub const CreateContractError = std.mem.Allocator.Error || Address.CalculateAddressError;
/// Create a new contract using CREATE opcode semantics.
///
/// Increments creator's nonce, calculates address via keccak256(rlp([sender, nonce])),
/// transfers value if specified, executes init code, and deploys resulting bytecode.
///
/// Parameters:
/// - creator: Account initiating contract creation
/// - value: Wei to transfer to new contract (0 for no transfer)
/// - init_code: Bytecode executed to generate contract code
/// - gas: Maximum gas for entire creation process
///
/// Returns CreateResult with success=false if:
/// - Creator balance < value (insufficient funds)
/// - Contract exists at calculated address (collision)
/// - Init code reverts or runs out of gas
/// - Deployed bytecode > 24,576 bytes (EIP-170)
/// - Insufficient gas for deployment (200 gas/byte)
///
/// Time complexity: O(init_code_length + deployed_code_length)
/// Memory: Allocates space for deployed bytecode
///
/// See also: create2_contract() for deterministic addresses
pub fn create_contract(self: *Self, creator: Address.Address, value: u256, init_code: []const u8, gas: u64) CreateContractError!CreateResult {
const nonce = try self.state.increment_nonce(creator);
const new_address = try Address.calculate_create_address(self.allocator, creator, nonce);
return self.create_contract_internal(creator, value, init_code, gas, new_address);
}
pub const CallContractError = std.mem.Allocator.Error;
/// Execute a CALL operation to another contract or precompile.
///
/// This method handles both regular contract calls and precompile calls.
/// For precompiles, it routes to the appropriate precompile implementation.
/// For regular contracts, it currently returns failure (TODO: implement contract execution).
///
/// @param caller The address initiating the call
/// @param to The address being called (may be a precompile)
/// @param value The amount of ETH being transferred (must be 0 for static calls)
/// @param input Input data for the call
/// @param gas Gas limit available for the call
/// @param is_static Whether this is a static call (no state changes allowed)
/// @return CallResult indicating success/failure and return data
pub fn call_contract(self: *Self, caller: Address.Address, to: Address.Address, value: u256, input: []const u8, gas: u64, is_static: bool) CallContractError!CallResult {
@branchHint(.likely);
Log.debug("VM.call_contract: Call from {any} to {any}, gas={}, static={}", .{ caller, to, gas, is_static });
// Check if this is a precompile call
if (precompiles.is_precompile(to)) {
Log.debug("VM.call_contract: Detected precompile call to {any}", .{to});
return self.execute_precompile_call(to, input, gas, is_static);
}
// Regular contract call - currently not implemented
// TODO: Implement value transfer, gas calculation, recursive execution, and return data handling
Log.debug("VM.call_contract: Regular contract call not implemented yet", .{});
_ = value;
return CallResult{ .success = false, .gas_left = gas, .output = null };
}
/// Execute a precompile call
///
/// This method handles the execution of precompiled contracts. It performs
/// the following steps:
/// 1. Check if the precompile is available in the current hardfork
/// 2. Validate that value transfers are zero (precompiles don't accept ETH)
/// 3. Estimate output buffer size and allocate memory
/// 4. Execute the precompile
/// 5. Handle success/failure and return appropriate CallResult
///
/// @param address The precompile address
/// @param input Input data for the precompile
/// @param gas Gas limit available for execution
/// @param is_static Whether this is a static call (doesn't affect precompiles)
/// @return CallResult with success/failure, gas usage, and output data
fn execute_precompile_call(self: *Self, address: Address.Address, input: []const u8, gas: u64, is_static: bool) CallContractError!CallResult {
_ = is_static; // Precompiles are inherently stateless, so static flag doesn't matter
Log.debug("VM.execute_precompile_call: Executing precompile at {any}, input_size={}, gas={}", .{ address, input.len, gas });
// Get current chain rules
const chain_rules = self.chain_rules;
// Check if this precompile is available with current chain rules
if (!precompiles.is_available(address, chain_rules)) {
Log.debug("VM.execute_precompile_call: Precompile not available with current chain rules", .{});
return CallResult{ .success = false, .gas_left = gas, .output = null };
}
// Estimate required output buffer size
const output_size = precompiles.get_output_size(address, input.len, chain_rules) catch |err| {
Log.debug("VM.execute_precompile_call: Failed to get output size: {}", .{err});
return CallResult{ .success = false, .gas_left = gas, .output = null };
};
// Allocate output buffer
const output_buffer = self.allocator.alloc(u8, output_size) catch |err| {
Log.debug("VM.execute_precompile_call: Failed to allocate output buffer: {}", .{err});
return error.OutOfMemory;
};
// Execute the precompile
const result = precompiles.execute_precompile(address, input, output_buffer, gas, chain_rules);
if (result.is_success()) {
const gas_used = result.get_gas_used();
const actual_output_size = result.get_output_size();
Log.debug("VM.execute_precompile_call: Precompile succeeded, gas_used={}, output_size={}", .{ gas_used, actual_output_size });
// Resize buffer to actual output size if needed
if (actual_output_size < output_size) {
const resized_output = self.allocator.realloc(output_buffer, actual_output_size) catch output_buffer;
return CallResult{
.success = true,
.gas_left = gas - gas_used,
.output = resized_output[0..actual_output_size]
};
}
return CallResult{
.success = true,
.gas_left = gas - gas_used,
.output = output_buffer[0..actual_output_size]
};
} else {
// Free the allocated buffer on failure
self.allocator.free(output_buffer);
if (result.get_error()) |err| {
Log.debug("VM.execute_precompile_call: Precompile failed with error: {any}", .{err});
}
return CallResult{ .success = false, .gas_left = gas, .output = null };
}
}
pub const ConsumeGasError = ExecutionError.Error;
pub const Create2ContractError = std.mem.Allocator.Error || Address.CalculateCreate2AddressError;
/// Create a new contract using CREATE2 opcode semantics.
///
/// Calculates a deterministic address using keccak256(0xff ++ sender ++ salt ++ keccak256(init_code))[12:],
/// transfers value if specified, executes the initialization code, and deploys
/// the resulting bytecode. Unlike CREATE, the address is predictable before deployment.
pub fn create2_contract(self: *Self, creator: Address.Address, value: u256, init_code: []const u8, salt: u256, gas: u64) Create2ContractError!CreateResult {
// Calculate the new contract address using CREATE2 formula:
// address = keccak256(0xff ++ sender ++ salt ++ keccak256(init_code))[12:]
const new_address = try Address.calculate_create2_address(self.allocator, creator, salt, init_code);
return self.create_contract_internal(creator, value, init_code, gas, new_address);
}
pub const CallcodeContractError = std.mem.Allocator.Error;
// TODO
/// Execute a CALLCODE operation.
/// NOT IMPLEMENTED - always returns failure.
/// TODO: Execute target code in current contract's context while preserving caller information.
pub fn callcode_contract(self: *Self, current: Address.Address, code_address: Address.Address, value: u256, input: []const u8, gas: u64, is_static: bool) CallcodeContractError!CallResult {
_ = self;
_ = current;
_ = code_address;
_ = value;
_ = input;
_ = gas;
_ = is_static;
return CallResult{ .success = false, .gas_left = 0, .output = null };
}
pub const DelegatecallContractError = std.mem.Allocator.Error;
/// Execute a DELEGATECALL operation.
/// NOT IMPLEMENTED - always returns failure.
/// TODO: Execute target code with current caller and value context preserved.
pub fn delegatecall_contract(self: *Self, current: Address.Address, code_address: Address.Address, input: []const u8, gas: u64, is_static: bool) DelegatecallContractError!CallResult {
_ = self;
_ = current;
_ = code_address;
_ = input;
_ = gas;
_ = is_static;
return CallResult{ .success = false, .gas_left = 0, .output = null };
}
pub const StaticcallContractError = std.mem.Allocator.Error;
/// Execute a STATICCALL operation.
/// NOT IMPLEMENTED - always returns failure.
/// TODO: Execute target contract in guaranteed read-only mode.
pub fn staticcall_contract(self: *Self, caller: Address.Address, to: Address.Address, input: []const u8, gas: u64) StaticcallContractError!CallResult {
_ = self;
_ = caller;
_ = to;
_ = input;
_ = gas;
return CallResult{ .success = false, .gas_left = 0, .output = null };
}
pub const EmitLogError = std.mem.Allocator.Error;
/// Emit an event log (LOG0-LOG4 opcodes).
/// Records an event that will be included in the transaction receipt.
pub fn emit_log(self: *Self, address: Address.Address, topics: []const u256, data: []const u8) EmitLogError!void {
try self.state.emit_log(address, topics, data);
}
pub const InitTransactionAccessListError = AccessList.InitTransactionError;
/// Initialize the access list for a new transaction (EIP-2929).
/// Must be called at the start of each transaction to set up warm/cold access tracking.
pub fn init_transaction_access_list(self: *Self, to: ?Address.Address) InitTransactionAccessListError!void {
try self.access_list.init_transaction(self.context.tx_origin, self.context.block_coinbase, to);
}
pub const PreWarmAddressesError = AccessList.PreWarmAddressesError;
/// Mark addresses as warm to reduce gas costs for subsequent access.
/// Used with EIP-2930 access lists to pre-warm addresses in transactions.
/// Time complexity: O(n) where n is the number of addresses.
pub fn pre_warm_addresses(self: *Self, addresses: []const Address.Address) PreWarmAddressesError!void {
try self.access_list.pre_warm_addresses(addresses);
}
pub const PreWarmStorageSlotsError = AccessList.PreWarmStorageSlotsError;
/// Mark storage slots as warm to reduce gas costs for subsequent access.
/// Used with EIP-2930 access lists in transactions.
pub fn pre_warm_storage_slots(self: *Self, address: Address.Address, slots: []const u256) PreWarmStorageSlotsError!void {
try self.access_list.pre_warm_storage_slots(address, slots);
}
pub const GetAddressAccessCostError = AccessList.AccessAddressError;
/// Get the gas cost for accessing an address and mark it as warm.
/// Returns higher gas for first access, lower gas for subsequent access per EIP-2929.
/// Time complexity: O(1) with hash table lookup.
pub fn get_address_access_cost(self: *Self, address: Address.Address) GetAddressAccessCostError!u64 {
return self.access_list.access_address(address);
}
pub const GetStorageAccessCostError = AccessList.AccessStorageSlotError;
/// Get the gas cost for accessing a storage slot and mark it as warm.
/// Returns 2100 gas for cold access, 100 gas for warm access (Berlin hardfork).
pub fn get_storage_access_cost(self: *Self, address: Address.Address, slot: u256) GetStorageAccessCostError!u64 {
return self.access_list.access_storage_slot(address, slot);
}
pub const GetCallCostError = AccessList.GetCallCostError;
/// Get the additional gas cost for a CALL operation based on address warmth.
/// Returns extra gas required for calls to cold addresses (EIP-2929).
pub fn get_call_cost(self: *Self, address: Address.Address) GetCallCostError!u64 {
return self.access_list.get_call_cost(address);
}
pub const ValidateStaticContextError = error{WriteProtection};
/// Validate that state modifications are allowed in the current context.
/// Returns WriteProtection error if called within a static (read-only) context.
pub fn validate_static_context(self: *const Self) ValidateStaticContextError!void {
if (self.read_only) return error.WriteProtection;
}
pub const SetStorageProtectedError = ValidateStaticContextError || std.mem.Allocator.Error;
/// Set a storage value with static context protection.
/// Used by the SSTORE opcode to prevent storage modifications in static calls.
pub fn set_storage_protected(self: *Self, address: Address.Address, slot: u256, value: u256) SetStorageProtectedError!void {
try self.validate_static_context();
try self.state.set_storage(address, slot, value);
}
pub const SetTransientStorageProtectedError = ValidateStaticContextError || std.mem.Allocator.Error;
/// Set a transient storage value with static context protection.
/// Transient storage (EIP-1153) is cleared at the end of each transaction.
pub fn set_transient_storage_protected(self: *Self, address: Address.Address, slot: u256, value: u256) SetTransientStorageProtectedError!void {
try self.validate_static_context();
try self.state.set_transient_storage(address, slot, value);
}
pub const SetBalanceProtectedError = ValidateStaticContextError || std.mem.Allocator.Error;
/// Set an account balance with static context protection.
/// Prevents balance modifications during static calls.
pub fn set_balance_protected(self: *Self, address: Address.Address, balance: u256) SetBalanceProtectedError!void {
try self.validate_static_context();
try self.state.set_balance(address, balance);
}
pub const SetCodeProtectedError = ValidateStaticContextError || std.mem.Allocator.Error;
/// Deploy contract code with static context protection.
/// Prevents code deployment during static calls.
pub fn set_code_protected(self: *Self, address: Address.Address, code: []const u8) SetCodeProtectedError!void {
try self.validate_static_context();
try self.state.set_code(address, code);
}
pub const EmitLogProtectedError = ValidateStaticContextError || EmitLogError;
/// Emit a log with static context protection.
/// Prevents log emission during static calls as logs modify the transaction state.
pub fn emit_log_protected(self: *Self, address: Address.Address, topics: []const u256, data: []const u8) EmitLogProtectedError!void {
try self.validate_static_context();
try self.emit_log(address, topics, data);
}
pub const CreateContractProtectedError = ValidateStaticContextError || CreateContractError;
/// Create a contract with static context protection.
/// Prevents contract creation during static calls.
pub fn create_contract_protected(self: *Self, creator: Address.Address, value: u256, init_code: []const u8, gas: u64) CreateContractProtectedError!CreateResult {
try self.validate_static_context();
return self.create_contract(creator, value, init_code, gas);
}
pub const Create2ContractProtectedError = ValidateStaticContextError || Create2ContractError;
/// Create a contract with CREATE2 and static context protection.
/// Prevents contract creation during static calls.
pub fn create2_contract_protected(self: *Self, creator: Address.Address, value: u256, init_code: []const u8, salt: u256, gas: u64) Create2ContractProtectedError!CreateResult {
try self.validate_static_context();
return self.create2_contract(creator, value, init_code, salt, gas);
}
pub const ValidateValueTransferError = error{WriteProtection};
/// Validate that value transfer is allowed in the current context.
/// Static calls cannot transfer value (msg.value must be 0).
pub fn validate_value_transfer(self: *const Self, value: u256) ValidateValueTransferError!void {
if (self.read_only and value != 0) return error.WriteProtection;
}
pub const SelfdestructProtectedError = ValidateStaticContextError;
/// Execute SELFDESTRUCT with static context protection.
/// NOT FULLY IMPLEMENTED - currently only validates static context.
/// TODO: Transfer remaining balance to beneficiary and mark contract for deletion.
pub fn selfdestruct_protected(self: *Self, contract: Address.Address, beneficiary: Address.Address) SelfdestructProtectedError!void {
_ = contract;
_ = beneficiary;
try self.validate_static_context();
}
```
```zig [src/evm/frame.zig]
const std = @import("std");
const Memory = @import("memory.zig");
const Stack = @import("stack/stack.zig");
const Contract = @import("contract/contract.zig");
const ExecutionError = @import("execution/execution_error.zig");
const Log = @import("log.zig");
/// EVM execution frame representing a single call context.
///
/// A Frame encapsulates all the state needed to execute a contract call,
/// including the stack, memory, gas tracking, and execution context.
/// Each contract call or message creates a new frame.
///
/// ## Frame Hierarchy
/// Frames form a call stack during execution:
/// - External transactions create the root frame
/// - CALL/CREATE operations create child frames
/// - Frames are limited by maximum call depth (1024)
///
/// ## Execution Model
/// The frame tracks:
/// - Computational state (stack, memory, PC)
/// - Gas consumption and limits
/// - Input/output data
/// - Static call restrictions
///
/// ## Memory Management
/// Each frame has its own memory space that:
/// - Starts empty and expands as needed
/// - Is cleared when the frame completes
/// - Charges quadratic gas for expansion
///
/// Example:
/// ```zig
/// var frame = try Frame.init(allocator, &contract);
/// defer frame.deinit();
/// frame.gas_remaining = 1000000;
/// try frame.stack.append(42);
/// ```
const Self = @This();
/// Current opcode being executed (for debugging/tracing).
op: []const u8 = undefined,
/// Gas cost of current operation.
cost: u64 = 0,
/// Error that occurred during execution, if any.
err: ?ExecutionError.Error = null,
/// Frame's memory space for temporary data storage.
/// Grows dynamically and charges gas quadratically.
memory: Memory,
/// Operand stack for the stack machine.
/// Limited to 1024 elements per EVM rules.
stack: Stack,
/// Contract being executed in this frame.
/// Contains code, address, and contract metadata.
contract: *Contract,
/// Allocator for dynamic memory allocations.
allocator: std.mem.Allocator,
/// Flag indicating execution should halt.
/// Set by STOP, RETURN, REVERT, or errors.
stop: bool = false,
/// Remaining gas for this execution.
/// Decremented by each operation; execution fails at 0.
gas_remaining: u64 = 0,
/// Whether this is a STATICCALL context.
/// Prohibits state modifications (SSTORE, CREATE, SELFDESTRUCT).
is_static: bool = false,
/// Buffer containing return data from child calls.
/// Used by RETURNDATASIZE and RETURNDATACOPY opcodes.
return_data_buffer: []const u8 = &[_]u8{},
/// Input data for this call (calldata).
/// Accessed by CALLDATALOAD, CALLDATASIZE, CALLDATACOPY.
input: []const u8 = &[_]u8{},
/// Current call depth in the call stack.
/// Limited to 1024 to prevent stack overflow attacks.
depth: u32 = 0,
/// Output data to be returned from this frame.
/// Set by RETURN or REVERT operations.
output: []const u8 = &[_]u8{},
/// Current position in contract bytecode.
/// Incremented by opcode size, modified by JUMP/JUMPI.
pc: usize = 0,
/// Create a new execution frame with default settings.
///
/// Initializes a frame with empty stack and memory, ready for execution.
/// Gas and other parameters must be set after initialization.
///
/// @param allocator Memory allocator for dynamic allocations
/// @param contract The contract to execute
/// @return New frame instance
/// @throws OutOfMemory if memory initialization fails
///
/// Example:
/// ```zig
/// var frame = try Frame.init(allocator, &contract);
/// defer frame.deinit();
/// frame.gas_remaining = gas_limit;
/// frame.input = calldata;
/// ```
pub fn init(allocator: std.mem.Allocator, contract: *Contract) std.mem.Allocator.Error!Self {
return Self{
.allocator = allocator,
.contract = contract,
.memory = try Memory.init_default(allocator),
.stack = .{},
};
}
/// Create a frame with specific initial state.
///
/// Used for creating frames with pre-existing state, such as when
/// resuming execution or creating child frames with inherited state.
/// All parameters are optional and default to sensible values.
///
/// @param allocator Memory allocator
/// @param contract Contract to execute
/// @param op Current opcode (optional)
/// @param cost Gas cost of current op (optional)
/// @param err Existing error state (optional)
/// @param memory Pre-initialized memory (optional)
/// @param stack Pre-initialized stack (optional)
/// @param stop Halt flag (optional)
/// @param gas_remaining Available gas (optional)
/// @param is_static Static call flag (optional)
/// @param return_data_buffer Child return data (optional)
/// @param input Call data (optional)
/// @param depth Call stack depth (optional)
/// @param output Output buffer (optional)
/// @param pc Current PC (optional)
/// @return Configured frame instance
/// @throws OutOfMemory if memory initialization fails
///
/// Example:
/// ```zig
/// // Create child frame inheriting depth and static mode
/// const child_frame = try Frame.init_with_state(
/// allocator,
/// &child_contract,
/// .{ .depth = parent.depth + 1, .is_static = parent.is_static }
/// );
/// ```
pub fn init_with_state(
allocator: std.mem.Allocator,
contract: *Contract,
op: ?[]const u8,
cost: ?u64,
err: ?ExecutionError.Error,
memory: ?Memory,
stack: ?Stack,
stop: ?bool,
gas_remaining: ?u64,
is_static: ?bool,
return_data_buffer: ?[]const u8,
input: ?[]const u8,
depth: ?u32,
output: ?[]const u8,
pc: ?usize,
) std.mem.Allocator.Error!Self {
return Self{
.allocator = allocator,
.contract = contract,
.memory = memory orelse try Memory.init_default(allocator),
.stack = stack orelse .{},
.op = op orelse undefined,
.cost = cost orelse 0,
.err = err,
.stop = stop orelse false,
.gas_remaining = gas_remaining orelse 0,
.is_static = is_static orelse false,
.return_data_buffer = return_data_buffer orelse &[_]u8{},
.input = input orelse &[_]u8{},
.depth = depth orelse 0,
.output = output orelse &[_]u8{},
.pc = pc orelse 0,
};
}
/// Clean up frame resources.
///
/// Releases memory allocated by the frame. Must be called when
/// the frame is no longer needed to prevent memory leaks.
///
/// @param self The frame to clean up
pub fn deinit(self: *Self) void {
self.memory.deinit();
}
/// Error type for gas consumption operations.
pub const ConsumeGasError = error{
/// Insufficient gas to complete operation
OutOfGas,
};
/// Consume gas from the frame's remaining gas.
///
/// Deducts the specified amount from gas_remaining. If insufficient
/// gas is available, returns OutOfGas error and execution should halt.
///
/// @param self The frame consuming gas
/// @param amount Gas units to consume
/// @throws OutOfGas if amount > gas_remaining
///
/// Example:
/// ```zig
/// // Charge gas for operation
/// try frame.consume_gas(operation.constant_gas);
///
/// // Charge dynamic gas
/// const memory_cost = calculate_memory_gas(size);
/// try frame.consume_gas(memory_cost);
/// ```
pub fn consume_gas(self: *Self, amount: u64) ConsumeGasError!void {
@branchHint(.likely);
if (amount > self.gas_remaining) return ConsumeGasError.OutOfGas;
self.gas_remaining -= amount;
}
```
```zig [src/evm/execution/comparison.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
// Helper to convert Stack errors to ExecutionError
// These are redundant and can be removed.
// The op_* functions below use unsafe stack operations,
// so these helpers are unused anyway.
pub fn op_lt(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Pop the top operand (b) unsafely
const b = frame.stack.pop_unsafe();
// Peek the new top operand (a) unsafely
const a = frame.stack.peek_unsafe().*;
// EVM LT computes: a < b (where a was second from top, b was top)
const result: u256 = if (a < b) 1 else 0;
// Modify the current top of the stack in-place with the result
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_gt(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Pop the top operand (b) unsafely
const b = frame.stack.pop_unsafe();
// Peek the new top operand (a) unsafely
const a = frame.stack.peek_unsafe().*;
// EVM GT computes: a > b (where a was second from top, b was top)
const result: u256 = if (a > b) 1 else 0;
// Modify the current top of the stack in-place with the result
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_slt(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Pop the top operand (b) unsafely
const b = frame.stack.pop_unsafe();
// Peek the new top operand (a) unsafely
const a = frame.stack.peek_unsafe().*;
// Signed less than
const a_i256 = @as(i256, @bitCast(a));
const b_i256 = @as(i256, @bitCast(b));
const result: u256 = if (a_i256 < b_i256) 1 else 0;
// Modify the current top of the stack in-place with the result
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_sgt(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Pop the top operand (b) unsafely
const b = frame.stack.pop_unsafe();
// Peek the new top operand (a) unsafely
const a = frame.stack.peek_unsafe().*;
// Signed greater than
const a_i256 = @as(i256, @bitCast(a));
const b_i256 = @as(i256, @bitCast(b));
const result: u256 = if (a_i256 > b_i256) 1 else 0;
// Modify the current top of the stack in-place with the result
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_eq(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Pop the top operand (b) unsafely
const b = frame.stack.pop_unsafe();
// Peek the new top operand (a) unsafely
const a = frame.stack.peek_unsafe().*;
const result: u256 = if (a == b) 1 else 0;
// Modify the current top of the stack in-place with the result
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_iszero(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 1) unreachable;
// Peek the operand unsafely
const a = frame.stack.peek_unsafe().*;
const result: u256 = if (a == 0) 1 else 0;
// Modify the current top of the stack in-place with the result
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
```
```zig [src/evm/execution/system.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Vm = @import("../vm.zig");
const Contract = @import("../contract/contract.zig");
const Address = @import("Address");
const to_u256 = Address.to_u256;
const from_u256 = Address.from_u256;
const gas_constants = @import("../constants/gas_constants.zig");
const AccessList = @import("../access_list/access_list.zig").AccessList;
// Import helper functions from error_mapping
// Gas opcode handler
pub fn gas_op(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
try frame.stack.append( @as(u256, @intCast(frame.gas_remaining)));
return Operation.ExecutionResult{};
}
// Helper to check if u256 fits in usize
fn check_offset_bounds(value: u256) ExecutionError.Error!void {
if (value > std.math.maxInt(usize)) return ExecutionError.Error.InvalidOffset;
}
pub fn op_create(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Check if we're in a static call
if (frame.is_static) return ExecutionError.Error.WriteProtection;
const value = try frame.stack.pop();
const offset = try frame.stack.pop();
const size = try frame.stack.pop();
// Debug: CREATE opcode: value, offset, size
// Check depth
if (frame.depth >= 1024) {
try frame.stack.append( 0);
return Operation.ExecutionResult{};
}
// EIP-3860: Check initcode size limit FIRST (Shanghai and later)
try check_offset_bounds(size);
const size_usize = @as(usize, @intCast(size));
if (vm.chain_rules.IsEIP3860 and size_usize > gas_constants.MaxInitcodeSize) return ExecutionError.Error.MaxCodeSizeExceeded;
// Get init code from memory
var init_code: []const u8 = &[_]u8{};
if (size > 0) {
try check_offset_bounds(offset);
const offset_usize = @as(usize, @intCast(offset));
// Calculate memory expansion gas cost
const current_size = frame.memory.total_size();
const new_size = offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(memory_gas);
// Ensure memory is available and get the slice
_ = try frame.memory.ensure_context_capacity(offset_usize + size_usize);
init_code = try frame.memory.get_slice(offset_usize, size_usize);
}
// Calculate gas for creation
const init_code_cost = @as(u64, @intCast(init_code.len)) * gas_constants.CreateDataGas;
// EIP-3860: Add gas cost for initcode word size (2 gas per 32-byte word) - Shanghai and later
const initcode_word_cost = if (vm.chain_rules.IsEIP3860)
@as(u64, @intCast((init_code.len + 31) / 32)) * gas_constants.InitcodeWordGas
else
0;
try frame.consume_gas(init_code_cost + initcode_word_cost);
// Calculate gas to give to the new contract (all but 1/64th)
const gas_for_call = frame.gas_remaining - (frame.gas_remaining / 64);
// Create the contract
const result = try vm.create_contract(frame.contract.address, value, init_code, gas_for_call);
// Update gas remaining
frame.gas_remaining = frame.gas_remaining / 64 + result.gas_left;
if (!result.success) {
try frame.stack.append( 0);
frame.return_data_buffer = result.output orelse &[_]u8{};
return Operation.ExecutionResult{};
}
// EIP-2929: Mark the newly created address as warm
_ = try vm.access_list.access_address(result.address);
try frame.stack.append( to_u256(result.address));
// Set return data
frame.return_data_buffer = result.output orelse &[_]u8{};
return Operation.ExecutionResult{};
}
/// CREATE2 opcode - Create contract with deterministic address
pub fn op_create2(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
if (frame.is_static) return ExecutionError.Error.WriteProtection;
const value = try frame.stack.pop();
const offset = try frame.stack.pop();
const size = try frame.stack.pop();
const salt = try frame.stack.pop();
if (frame.depth >= 1024) {
try frame.stack.append( 0);
return Operation.ExecutionResult{};
}
// EIP-3860: Check initcode size limit FIRST (Shanghai and later)
try check_offset_bounds(size);
const size_usize = @as(usize, @intCast(size));
if (vm.chain_rules.IsEIP3860 and size_usize > gas_constants.MaxInitcodeSize) return ExecutionError.Error.MaxCodeSizeExceeded;
// Get init code from memory
var init_code: []const u8 = &[_]u8{};
if (size > 0) {
try check_offset_bounds(offset);
const offset_usize = @as(usize, @intCast(offset));
// Calculate memory expansion gas cost
const current_size = frame.memory.total_size();
const new_size = offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(memory_gas);
// Ensure memory is available and get the slice
_ = try frame.memory.ensure_context_capacity(offset_usize + size_usize);
init_code = try frame.memory.get_slice(offset_usize, size_usize);
}
const init_code_cost = @as(u64, @intCast(init_code.len)) * gas_constants.CreateDataGas;
const hash_cost = @as(u64, @intCast((init_code.len + 31) / 32)) * gas_constants.Keccak256WordGas;
// EIP-3860: Add gas cost for initcode word size (2 gas per 32-byte word) - Shanghai and later
const initcode_word_cost = if (vm.chain_rules.IsEIP3860)
@as(u64, @intCast((init_code.len + 31) / 32)) * gas_constants.InitcodeWordGas
else
0;
try frame.consume_gas(init_code_cost + hash_cost + initcode_word_cost);
// Calculate gas to give to the new contract (all but 1/64th)
const gas_for_call = frame.gas_remaining - (frame.gas_remaining / 64);
// Create the contract with CREATE2
const result = try vm.create2_contract(frame.contract.address, value, init_code, salt, gas_for_call);
// Update gas remaining
frame.gas_remaining = frame.gas_remaining / 64 + result.gas_left;
if (!result.success) {
try frame.stack.append( 0);
frame.return_data_buffer = result.output orelse &[_]u8{};
return Operation.ExecutionResult{};
}
// EIP-2929: Mark the newly created address as warm
_ = try vm.access_list.access_address(result.address);
try frame.stack.append( to_u256(result.address));
// Set return data
frame.return_data_buffer = result.output orelse &[_]u8{};
return Operation.ExecutionResult{};
}
pub fn op_call(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const gas = try frame.stack.pop();
const to = try frame.stack.pop();
const value = try frame.stack.pop();
const args_offset = try frame.stack.pop();
const args_size = try frame.stack.pop();
const ret_offset = try frame.stack.pop();
const ret_size = try frame.stack.pop();
// Check depth
if (frame.depth >= 1024) {
try frame.stack.append( 0);
return Operation.ExecutionResult{};
}
// Get call data
var args: []const u8 = &[_]u8{};
if (args_size > 0) {
// Check that offset + size doesn't overflow and fits in usize
if (args_offset > std.math.maxInt(usize) or args_size > std.math.maxInt(usize)) return ExecutionError.Error.InvalidOffset;
const args_offset_usize = @as(usize, @intCast(args_offset));
const args_size_usize = @as(usize, @intCast(args_size));
// Check that offset + size doesn't overflow usize
if (args_offset_usize > std.math.maxInt(usize) - args_size_usize) return ExecutionError.Error.InvalidOffset;
_ = try frame.memory.ensure_context_capacity(args_offset_usize + args_size_usize);
args = try frame.memory.get_slice(args_offset_usize, args_size_usize);
}
// Ensure return memory
if (ret_size > 0) {
// Check that offset + size doesn't overflow and fits in usize
if (ret_offset > std.math.maxInt(usize) or ret_size > std.math.maxInt(usize)) return ExecutionError.Error.InvalidOffset;
const ret_offset_usize = @as(usize, @intCast(ret_offset));
const ret_size_usize = @as(usize, @intCast(ret_size));
// Check that offset + size doesn't overflow usize
if (ret_offset_usize > std.math.maxInt(usize) - ret_size_usize) return ExecutionError.Error.InvalidOffset;
_ = try frame.memory.ensure_context_capacity(ret_offset_usize + ret_size_usize);
}
if (frame.is_static and value != 0) return ExecutionError.Error.WriteProtection;
const to_address = from_u256(to);
const access_cost = try vm.access_list.access_address(to_address);
const is_cold = access_cost == AccessList.COLD_ACCOUNT_ACCESS_COST;
if (is_cold) {
try frame.consume_gas(gas_constants.ColdAccountAccessCost);
}
// Calculate gas to give to the call
var gas_for_call = if (gas > std.math.maxInt(u64)) std.math.maxInt(u64) else @as(u64, @intCast(gas));
gas_for_call = @min(gas_for_call, frame.gas_remaining - (frame.gas_remaining / 64));
if (value != 0) {
gas_for_call += 2300; // Stipend
}
// Execute the call
const result = try vm.call_contract(frame.contract.address, to_address, value, args, gas_for_call, frame.is_static);
// Update gas remaining
frame.gas_remaining = frame.gas_remaining - gas_for_call + result.gas_left;
// Write return data to memory if requested
if (ret_size > 0 and result.output != null) {
const ret_offset_usize = @as(usize, @intCast(ret_offset));
const ret_size_usize = @as(usize, @intCast(ret_size));
const output = result.output.?;
const copy_size = @min(ret_size_usize, output.len);
const memory_slice = frame.memory.slice();
@memcpy(memory_slice[ret_offset_usize .. ret_offset_usize + copy_size], output[0..copy_size]);
// Zero out remaining bytes if output was smaller than requested
if (copy_size < ret_size_usize) {
@memset(memory_slice[ret_offset_usize + copy_size .. ret_offset_usize + ret_size_usize], 0);
}
}
// Set return data
frame.return_data_buffer = result.output orelse &[_]u8{};
// Push success status
try frame.stack.append( if (result.success) 1 else 0);
return Operation.ExecutionResult{};
}
pub fn op_callcode(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const gas = try frame.stack.pop();
const to = try frame.stack.pop();
const value = try frame.stack.pop();
const args_offset = try frame.stack.pop();
const args_size = try frame.stack.pop();
const ret_offset = try frame.stack.pop();
const ret_size = try frame.stack.pop();
// Check depth
if (frame.depth >= 1024) {
try frame.stack.append( 0);
return Operation.ExecutionResult{};
}
// Get call data
var args: []const u8 = &[_]u8{};
if (args_size > 0) {
try check_offset_bounds(args_offset);
try check_offset_bounds(args_size);
const args_offset_usize = @as(usize, @intCast(args_offset));
const args_size_usize = @as(usize, @intCast(args_size));
_ = try frame.memory.ensure_context_capacity(args_offset_usize + args_size_usize);
args = try frame.memory.get_slice(args_offset_usize, args_size_usize);
}
// Ensure return memory
if (ret_size > 0) {
try check_offset_bounds(ret_offset);
try check_offset_bounds(ret_size);
const ret_offset_usize = @as(usize, @intCast(ret_offset));
const ret_size_usize = @as(usize, @intCast(ret_size));
_ = try frame.memory.ensure_context_capacity(ret_offset_usize + ret_size_usize);
}
// Convert to address
const to_address = from_u256(to);
// EIP-2929: Check if address is cold and consume appropriate gas
const access_cost = try vm.access_list.access_address(to_address);
const is_cold = access_cost == AccessList.COLD_ACCOUNT_ACCESS_COST;
if (is_cold) {
// Cold address access costs more (2600 gas)
try frame.consume_gas(gas_constants.ColdAccountAccessCost);
}
// Calculate gas to give to the call
var gas_for_call = if (gas > std.math.maxInt(u64)) std.math.maxInt(u64) else @as(u64, @intCast(gas));
gas_for_call = @min(gas_for_call, frame.gas_remaining - (frame.gas_remaining / 64));
if (value != 0) {
gas_for_call += 2300; // Stipend
}
// Execute the callcode (execute target's code with current storage context)
// For callcode, we use the current contract's address as the execution context
const result = try vm.callcode_contract(frame.contract.address, to_address, value, args, gas_for_call, frame.is_static);
// Update gas remaining
frame.gas_remaining = frame.gas_remaining - gas_for_call + result.gas_left;
// Write return data to memory if requested
if (ret_size > 0 and result.output != null) {
const ret_offset_usize = @as(usize, @intCast(ret_offset));
const ret_size_usize = @as(usize, @intCast(ret_size));
const output = result.output.?;
const copy_size = @min(ret_size_usize, output.len);
const memory_slice = frame.memory.slice();
@memcpy(memory_slice[ret_offset_usize .. ret_offset_usize + copy_size], output[0..copy_size]);
// Zero out remaining bytes if output was smaller than requested
if (copy_size < ret_size_usize) {
@memset(memory_slice[ret_offset_usize + copy_size .. ret_offset_usize + ret_size_usize], 0);
}
}
// Set return data
frame.return_data_buffer = result.output orelse &[_]u8{};
// Push success status
try frame.stack.append( if (result.success) 1 else 0);
return Operation.ExecutionResult{};
}
pub fn op_delegatecall(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const gas = try frame.stack.pop();
const to = try frame.stack.pop();
const args_offset = try frame.stack.pop();
const args_size = try frame.stack.pop();
const ret_offset = try frame.stack.pop();
const ret_size = try frame.stack.pop();
// Check depth
if (frame.depth >= 1024) {
try frame.stack.append( 0);
return Operation.ExecutionResult{};
}
// Get call data
var args: []const u8 = &[_]u8{};
if (args_size > 0) {
try check_offset_bounds(args_offset);
try check_offset_bounds(args_size);
const args_offset_usize = @as(usize, @intCast(args_offset));
const args_size_usize = @as(usize, @intCast(args_size));
_ = try frame.memory.ensure_context_capacity(args_offset_usize + args_size_usize);
args = try frame.memory.get_slice(args_offset_usize, args_size_usize);
}
// Ensure return memory
if (ret_size > 0) {
try check_offset_bounds(ret_offset);
try check_offset_bounds(ret_size);
const ret_offset_usize = @as(usize, @intCast(ret_offset));
const ret_size_usize = @as(usize, @intCast(ret_size));
_ = try frame.memory.ensure_context_capacity(ret_offset_usize + ret_size_usize);
}
// Convert to address
const to_address = from_u256(to);
// EIP-2929: Check if address is cold and consume appropriate gas
const access_cost = try vm.access_list.access_address(to_address);
const is_cold = access_cost == AccessList.COLD_ACCOUNT_ACCESS_COST;
if (is_cold) {
// Cold address access costs more (2600 gas)
try frame.consume_gas(gas_constants.ColdAccountAccessCost);
}
// Calculate gas to give to the call
var gas_for_call = if (gas > std.math.maxInt(u64)) std.math.maxInt(u64) else @as(u64, @intCast(gas));
gas_for_call = @min(gas_for_call, frame.gas_remaining - (frame.gas_remaining / 64));
// Execute the delegatecall (execute target's code with current storage context and msg.sender/value)
// For delegatecall, we preserve the current contract's context
// Note: delegatecall doesn't transfer value, it uses the current contract's value
const result = try vm.delegatecall_contract(frame.contract.address, to_address, args, gas_for_call, frame.is_static);
// Update gas remaining
frame.gas_remaining = frame.gas_remaining - gas_for_call + result.gas_left;
// Write return data to memory if requested
if (ret_size > 0 and result.output != null) {
const ret_offset_usize = @as(usize, @intCast(ret_offset));
const ret_size_usize = @as(usize, @intCast(ret_size));
const output = result.output.?;
const copy_size = @min(ret_size_usize, output.len);
const memory_slice = frame.memory.slice();
@memcpy(memory_slice[ret_offset_usize .. ret_offset_usize + copy_size], output[0..copy_size]);
// Zero out remaining bytes if output was smaller than requested
if (copy_size < ret_size_usize) {
@memset(memory_slice[ret_offset_usize + copy_size .. ret_offset_usize + ret_size_usize], 0);
}
}
// Set return data
frame.return_data_buffer = result.output orelse &[_]u8{};
// Push success status
try frame.stack.append( if (result.success) 1 else 0);
return Operation.ExecutionResult{};
}
pub fn op_staticcall(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const gas = try frame.stack.pop();
const to = try frame.stack.pop();
const args_offset = try frame.stack.pop();
const args_size = try frame.stack.pop();
const ret_offset = try frame.stack.pop();
const ret_size = try frame.stack.pop();
// Check depth
if (frame.depth >= 1024) {
try frame.stack.append( 0);
return Operation.ExecutionResult{};
}
// Get call data
var args: []const u8 = &[_]u8{};
if (args_size > 0) {
try check_offset_bounds(args_offset);
try check_offset_bounds(args_size);
const args_offset_usize = @as(usize, @intCast(args_offset));
const args_size_usize = @as(usize, @intCast(args_size));
_ = try frame.memory.ensure_context_capacity(args_offset_usize + args_size_usize);
args = try frame.memory.get_slice(args_offset_usize, args_size_usize);
}
// Ensure return memory
if (ret_size > 0) {
try check_offset_bounds(ret_offset);
try check_offset_bounds(ret_size);
const ret_offset_usize = @as(usize, @intCast(ret_offset));
const ret_size_usize = @as(usize, @intCast(ret_size));
_ = try frame.memory.ensure_context_capacity(ret_offset_usize + ret_size_usize);
}
// Convert to address
const to_address = from_u256(to);
// EIP-2929: Check if address is cold and consume appropriate gas
const access_cost = try vm.access_list.access_address(to_address);
const is_cold = access_cost == AccessList.COLD_ACCOUNT_ACCESS_COST;
if (is_cold) {
// Cold address access costs more (2600 gas)
try frame.consume_gas(gas_constants.ColdAccountAccessCost);
}
// Calculate gas to give to the call
var gas_for_call = if (gas > std.math.maxInt(u64)) std.math.maxInt(u64) else @as(u64, @intCast(gas));
gas_for_call = @min(gas_for_call, frame.gas_remaining - (frame.gas_remaining / 64));
// Execute the static call (no value transfer, is_static = true)
const result = try vm.call_contract(frame.contract.address, to_address, 0, args, gas_for_call, true);
// Update gas remaining
frame.gas_remaining = frame.gas_remaining - gas_for_call + result.gas_left;
// Write return data to memory if requested
if (ret_size > 0 and result.output != null) {
const ret_offset_usize = @as(usize, @intCast(ret_offset));
const ret_size_usize = @as(usize, @intCast(ret_size));
const output = result.output.?;
const copy_size = @min(ret_size_usize, output.len);
const memory_slice = frame.memory.slice();
@memcpy(memory_slice[ret_offset_usize .. ret_offset_usize + copy_size], output[0..copy_size]);
// Zero out remaining bytes if output was smaller than requested
if (copy_size < ret_size_usize) {
@memset(memory_slice[ret_offset_usize + copy_size .. ret_offset_usize + ret_size_usize], 0);
}
}
// Set return data
frame.return_data_buffer = result.output orelse &[_]u8{};
// Push success status
try frame.stack.append( if (result.success) 1 else 0);
return Operation.ExecutionResult{};
}
/// EXTCALL opcode (0xF8): External call with EOF validation
/// Not implemented - EOF feature
pub fn op_extcall(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
_ = state;
// This is an EOF (EVM Object Format) opcode, not yet implemented
return ExecutionError.Error.EOFNotSupported;
}
/// EXTDELEGATECALL opcode (0xF9): External delegate call with EOF validation
/// Not implemented - EOF feature
pub fn op_extdelegatecall(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
_ = state;
// This is an EOF (EVM Object Format) opcode, not yet implemented
return ExecutionError.Error.EOFNotSupported;
}
/// EXTSTATICCALL opcode (0xFB): External static call with EOF validation
/// Not implemented - EOF feature
pub fn op_extstaticcall(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
_ = state;
// This is an EOF (EVM Object Format) opcode, not yet implemented
return ExecutionError.Error.EOFNotSupported;
}
```
```zig [src/evm/execution/execution_result.zig]
//! ExecutionResult module - Represents the outcome of executing an EVM opcode
//!
//! This module defines the result structure returned by opcode execution functions.
//! Every opcode in the EVM returns an ExecutionResult that indicates:
//! - How many bytes of bytecode were consumed
//! - Whether execution should continue or halt (and if halting, what data to return)
//!
//! ## Design Philosophy
//!
//! The ExecutionResult struct provides a uniform interface for all opcode implementations
//! to communicate their results back to the main execution loop. This design allows for:
//! - Clean separation between opcode logic and control flow
//! - Efficient bytecode parsing without redundant position tracking
//! - Clear signaling of execution termination with associated data
//!
//! ## Usage Pattern
//!
//! ```zig
//! // In an opcode implementation
//! pub fn execute_add(vm: *VM) ExecutionResult {
//! // Perform addition logic...
//! return ExecutionResult{ .bytes_consumed = 1 }; // Continue execution
//! }
//!
//! pub fn execute_return(vm: *VM) ExecutionResult {
//! const data = vm.memory.read_range(offset, size);
//! return ExecutionResult{
//! .bytes_consumed = 1,
//! .output = data // Non-empty output signals halt
//! };
//! }
//! ```
const std = @import("std");
/// ExecutionResult holds the result of executing a single EVM opcode
///
/// This struct is returned by every opcode execution function to indicate:
/// 1. How many bytes of bytecode were consumed (opcode + immediate data)
/// 2. Whether execution should continue or halt (indicated by output)
///
/// The EVM execution loop uses this information to:
/// - Advance the program counter by `bytes_consumed`
/// - Determine whether to continue executing or return control to caller
/// - Pass return data back to the calling context when halting
const Self = @This();
/// Number of bytes consumed by this opcode (including immediate data)
///
/// Most opcodes consume exactly 1 byte (just the opcode itself), but some
/// consume additional bytes for immediate data:
///
/// - **PUSH1-PUSH32**: Consume 1 + n bytes (opcode + n bytes of data)
/// - **All other opcodes**: Consume exactly 1 byte
///
/// The execution loop uses this value to advance the program counter (PC)
/// to the next instruction. Incorrect values here will cause the VM to
/// misinterpret subsequent bytecode.
///
/// ## Examples
/// - ADD opcode (0x01): bytes_consumed = 1
/// - PUSH1 0x42: bytes_consumed = 2 (1 for opcode, 1 for data)
/// - PUSH32 <32 bytes>: bytes_consumed = 33 (1 for opcode, 32 for data)
bytes_consumed: usize = 1,
/// Return data if the execution should halt (empty means continue)
///
/// This field serves a dual purpose:
/// 1. **Empty slice (`""`)**: Execution continues to the next instruction
/// 2. **Non-empty slice**: Execution halts and returns this data
///
/// Opcodes that halt execution include:
/// - **RETURN**: Returns specified data from memory
/// - **REVERT**: Returns revert data and reverts state changes
/// - **STOP**: Halts with empty return data (but still non-empty slice)
/// - **INVALID**: Halts with empty data and consumes all gas
/// - **SELFDESTRUCT**: Halts after scheduling account destruction
///
/// The data in this field is typically:
/// - Memory contents for RETURN/REVERT
/// - Empty (but allocated) slice for STOP/INVALID
/// - Contract creation bytecode for CREATE operations
///
/// ## Memory Management
/// The slice should reference memory owned by the VM's memory system
/// or be a compile-time constant empty slice. The execution loop does
/// not free this memory.
output: []const u8 = "",
```
```zig [src/evm/execution/arithmetic.zig]
/// Arithmetic operations for the Ethereum Virtual Machine
///
/// This module implements all arithmetic opcodes for the EVM, including basic
/// arithmetic (ADD, SUB, MUL, DIV), signed operations (SDIV, SMOD), modular
/// arithmetic (MOD, ADDMOD, MULMOD), exponentiation (EXP), and sign extension
/// (SIGNEXTEND).
///
/// ## Design Philosophy
///
/// All operations follow a consistent pattern:
/// 1. Pop operands from the stack (validated by jump table)
/// 2. Perform the arithmetic operation
/// 3. Push the result back onto the stack
///
/// ## Performance Optimizations
///
/// - **Unsafe Operations**: Stack bounds checking is done by the jump table,
/// allowing opcodes to use unsafe stack operations for maximum performance
/// - **In-Place Updates**: Results are written directly to stack slots to
/// minimize memory operations
/// - **Wrapping Arithmetic**: Uses Zig's wrapping operators (`+%`, `*%`, `-%`)
/// for correct 256-bit overflow behavior
///
/// ## EVM Arithmetic Rules
///
/// - All values are 256-bit unsigned integers (u256)
/// - Overflow wraps around (e.g., MAX_U256 + 1 = 0)
/// - Division by zero returns 0 (not an error)
/// - Modulo by zero returns 0 (not an error)
/// - Signed operations interpret u256 as two's complement i256
///
/// ## Gas Costs
///
/// - ADD, SUB, NOT: 3 gas (GasFastestStep)
/// - MUL, DIV, SDIV, MOD, SMOD: 5 gas (GasFastStep)
/// - ADDMOD, MULMOD, SIGNEXTEND: 8 gas (GasMidStep)
/// - EXP: 10 gas + 50 per byte of exponent
///
/// ## Stack Requirements
///
/// Operation | Stack Input | Stack Output | Description
/// -------------|-------------|--------------|-------------
/// ADD | [a, b] | [a + b] | Addition with overflow
/// MUL | [a, b] | [a * b] | Multiplication with overflow
/// SUB | [a, b] | [a - b] | Subtraction with underflow
/// DIV | [a, b] | [a / b] | Division (b=0 returns 0)
/// SDIV | [a, b] | [a / b] | Signed division
/// MOD | [a, b] | [a % b] | Modulo (b=0 returns 0)
/// SMOD | [a, b] | [a % b] | Signed modulo
/// ADDMOD | [a, b, n] | [(a+b)%n] | Addition modulo n
/// MULMOD | [a, b, n] | [(a*b)%n] | Multiplication modulo n
/// EXP | [a, b] | [a^b] | Exponentiation
/// SIGNEXTEND | [b, x] | [y] | Sign extend x from byte b
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Vm = @import("../vm.zig");
/// ADD opcode (0x01) - Addition operation
///
/// Pops two values from the stack, adds them with wrapping overflow,
/// and pushes the result.
///
/// ## Stack Input
/// - `a`: First operand (second from top)
/// - `b`: Second operand (top)
///
/// ## Stack Output
/// - `a + b`: Sum with 256-bit wrapping overflow
///
/// ## Gas Cost
/// 3 gas (GasFastestStep)
///
/// ## Execution
/// 1. Pop b from stack
/// 2. Pop a from stack
/// 3. Calculate sum = (a + b) mod 2^256
/// 4. Push sum to stack
///
/// ## Example
/// Stack: [10, 20] => [30]
/// Stack: [MAX_U256, 1] => [0] (overflow wraps)
pub fn op_add(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
const sum = a +% b;
frame.stack.set_top_unsafe(sum);
return Operation.ExecutionResult{};
}
/// MUL opcode (0x02) - Multiplication operation
///
/// Pops two values from the stack, multiplies them with wrapping overflow,
/// and pushes the result.
///
/// ## Stack Input
/// - `a`: First operand (second from top)
/// - `b`: Second operand (top)
///
/// ## Stack Output
/// - `a * b`: Product with 256-bit wrapping overflow
///
/// ## Gas Cost
/// 5 gas (GasFastStep)
///
/// ## Execution
/// 1. Pop b from stack
/// 2. Pop a from stack
/// 3. Calculate product = (a * b) mod 2^256
/// 4. Push product to stack
///
/// ## Example
/// Stack: [10, 20] => [200]
/// Stack: [2^128, 2^128] => [0] (overflow wraps)
pub fn op_mul(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
const product = a *% b;
frame.stack.set_top_unsafe(product);
return Operation.ExecutionResult{};
}
/// SUB opcode (0x03) - Subtraction operation
///
/// Pops two values from the stack, subtracts the top from the second,
/// with wrapping underflow, and pushes the result.
///
/// ## Stack Input
/// - `a`: Minuend (second from top)
/// - `b`: Subtrahend (top)
///
/// ## Stack Output
/// - `a - b`: Difference with 256-bit wrapping underflow
///
/// ## Gas Cost
/// 3 gas (GasFastestStep)
///
/// ## Execution
/// 1. Pop b from stack
/// 2. Pop a from stack
/// 3. Calculate result = (a - b) mod 2^256
/// 4. Push result to stack
///
/// ## Example
/// Stack: [30, 10] => [20]
/// Stack: [10, 20] => [2^256 - 10] (underflow wraps)
pub fn op_sub(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
const result = a -% b;
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
/// DIV opcode (0x04) - Unsigned integer division
///
/// Pops two values from the stack, divides the second by the top,
/// and pushes the integer quotient. Division by zero returns 0.
///
/// ## Stack Input
/// - `a`: Dividend (second from top)
/// - `b`: Divisor (top)
///
/// ## Stack Output
/// - `a / b`: Integer quotient, or 0 if b = 0
///
/// ## Gas Cost
/// 5 gas (GasFastStep)
///
/// ## Execution
/// 1. Pop b from stack
/// 2. Pop a from stack
/// 3. If b = 0, result = 0 (no error)
/// 4. Else result = floor(a / b)
/// 5. Push result to stack
///
/// ## Example
/// Stack: [20, 5] => [4]
/// Stack: [7, 3] => [2] (integer division)
/// Stack: [100, 0] => [0] (division by zero)
///
/// ## Note
/// Unlike most programming languages, EVM division by zero does not
/// throw an error but returns 0. This is a deliberate design choice
/// to avoid exceptional halting conditions.
pub fn op_div(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
const result = if (b == 0) 0 else a / b;
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
/// SDIV opcode (0x05) - Signed integer division
///
/// Pops two values from the stack, interprets them as signed integers,
/// divides the second by the top, and pushes the signed quotient.
/// Division by zero returns 0.
///
/// ## Stack Input
/// - `a`: Dividend as signed i256 (second from top)
/// - `b`: Divisor as signed i256 (top)
///
/// ## Stack Output
/// - `a / b`: Signed integer quotient, or 0 if b = 0
///
/// ## Gas Cost
/// 5 gas (GasFastStep)
///
/// ## Execution
/// 1. Pop b from stack
/// 2. Pop a from stack
/// 3. Interpret both as two's complement signed integers
/// 4. If b = 0, result = 0
/// 5. Else if a = -2^255 and b = -1, result = -2^255 (overflow case)
/// 6. Else result = truncated division a / b
/// 7. Push result to stack
///
/// ## Example
/// Stack: [20, 5] => [4]
/// Stack: [-20, 5] => [-4] (0xfff...fec / 5)
/// Stack: [-20, -5] => [4]
/// Stack: [MIN_I256, -1] => [MIN_I256] (overflow protection)
///
/// ## Note
/// The special case for MIN_I256 / -1 prevents integer overflow,
/// as the mathematical result (2^255) cannot be represented in i256.
pub fn op_sdiv(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (b == 0) {
result = 0;
} else {
const a_i256 = @as(i256, @bitCast(a));
const b_i256 = @as(i256, @bitCast(b));
const min_i256 = @as(i256, 1) << 255;
if (a_i256 == min_i256 and b_i256 == -1) {
result = @as(u256, @bitCast(min_i256));
} else {
const result_i256 = @divTrunc(a_i256, b_i256);
result = @as(u256, @bitCast(result_i256));
}
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
/// MOD opcode (0x06) - Modulo remainder operation
///
/// Pops two values from the stack, calculates the remainder of dividing
/// the second by the top, and pushes the result. Modulo by zero returns 0.
///
/// ## Stack Input
/// - `a`: Dividend (second from top)
/// - `b`: Divisor (top)
///
/// ## Stack Output
/// - `a % b`: Remainder of a / b, or 0 if b = 0
///
/// ## Gas Cost
/// 5 gas (GasFastStep)
///
/// ## Execution
/// 1. Pop b from stack
/// 2. Pop a from stack
/// 3. If b = 0, result = 0 (no error)
/// 4. Else result = a modulo b
/// 5. Push result to stack
///
/// ## Example
/// Stack: [17, 5] => [2]
/// Stack: [100, 10] => [0]
/// Stack: [7, 0] => [0] (modulo by zero)
///
/// ## Note
/// The result is always in range [0, b-1] for b > 0.
/// Like DIV, modulo by zero returns 0 rather than throwing an error.
pub fn op_mod(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
const result = if (b == 0) 0 else a % b;
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
/// SMOD opcode (0x07) - Signed modulo remainder operation
///
/// Pops two values from the stack, interprets them as signed integers,
/// calculates the signed remainder, and pushes the result.
/// Modulo by zero returns 0.
///
/// ## Stack Input
/// - `a`: Dividend as signed i256 (second from top)
/// - `b`: Divisor as signed i256 (top)
///
/// ## Stack Output
/// - `a % b`: Signed remainder, or 0 if b = 0
///
/// ## Gas Cost
/// 5 gas (GasFastStep)
///
/// ## Execution
/// 1. Pop b from stack
/// 2. Pop a from stack
/// 3. Interpret both as two's complement signed integers
/// 4. If b = 0, result = 0
/// 5. Else result = signed remainder of a / b
/// 6. Push result to stack
///
/// ## Example
/// Stack: [17, 5] => [2]
/// Stack: [-17, 5] => [-2] (sign follows dividend)
/// Stack: [17, -5] => [2]
/// Stack: [-17, -5] => [-2]
///
/// ## Note
/// In signed modulo, the result has the same sign as the dividend (a).
/// This follows the Euclidean division convention where:
/// a = b * q + r, where |r| < |b| and sign(r) = sign(a)
pub fn op_smod(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (b == 0) {
result = 0;
} else {
const a_i256 = @as(i256, @bitCast(a));
const b_i256 = @as(i256, @bitCast(b));
const result_i256 = @rem(a_i256, b_i256);
result = @as(u256, @bitCast(result_i256));
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
/// ADDMOD opcode (0x08) - Addition modulo n
///
/// Pops three values from the stack, adds the first two, then takes
/// the modulo with the third value. Handles overflow correctly by
/// computing (a + b) mod n, not ((a + b) mod 2^256) mod n.
///
/// ## Stack Input
/// - `a`: First addend (third from top)
/// - `b`: Second addend (second from top)
/// - `n`: Modulus (top)
///
/// ## Stack Output
/// - `(a + b) % n`: Sum modulo n, or 0 if n = 0
///
/// ## Gas Cost
/// 8 gas (GasMidStep)
///
/// ## Execution
/// 1. Pop n from stack (modulus)
/// 2. Pop b from stack (second addend)
/// 3. Pop a from stack (first addend)
/// 4. If n = 0, result = 0
/// 5. Else result = (a + b) mod n
/// 6. Push result to stack
///
/// ## Example
/// Stack: [10, 20, 7] => [2] ((10 + 20) % 7)
/// Stack: [MAX_U256, 5, 10] => [4] (overflow handled)
/// Stack: [50, 50, 0] => [0] (modulo by zero)
///
/// ## Note
/// This operation is atomic - the addition and modulo are
/// performed as one operation to handle cases where a + b
/// exceeds 2^256.
pub fn op_addmod(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 3) unreachable;
const n = frame.stack.pop_unsafe();
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (n == 0) {
result = 0;
} else {
// The EVM ADDMOD operation computes (a + b) % n
// Since we're working with u256, overflow wraps automatically
// So (a +% b) gives us (a + b) mod 2^256
// Then we just need to compute that result mod n
const sum = a +% b; // Wrapping addition
result = sum % n;
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
/// MULMOD opcode (0x09) - Multiplication modulo n
///
/// Pops three values from the stack, multiplies the first two, then
/// takes the modulo with the third value. Correctly handles cases where
/// the product exceeds 2^256.
///
/// ## Stack Input
/// - `a`: First multiplicand (third from top)
/// - `b`: Second multiplicand (second from top)
/// - `n`: Modulus (top)
///
/// ## Stack Output
/// - `(a * b) % n`: Product modulo n, or 0 if n = 0
///
/// ## Gas Cost
/// 8 gas (GasMidStep)
///
/// ## Execution
/// 1. Pop n from stack (modulus)
/// 2. Pop b from stack (second multiplicand)
/// 3. Pop a from stack (first multiplicand)
/// 4. If n = 0, result = 0
/// 5. Else compute (a * b) mod n using Russian peasant algorithm
/// 6. Push result to stack
///
/// ## Algorithm
/// Uses Russian peasant multiplication with modular reduction:
/// - Reduces inputs modulo n first
/// - Builds product bit by bit, reducing modulo n at each step
/// - Avoids need for 512-bit intermediate values
///
/// ## Example
/// Stack: [10, 20, 7] => [4] ((10 * 20) % 7)
/// Stack: [2^128, 2^128, 100] => [0] (handles overflow)
/// Stack: [50, 50, 0] => [0] (modulo by zero)
///
/// ## Note
/// This operation correctly computes (a * b) mod n even when
/// a * b exceeds 2^256, unlike naive (a *% b) % n approach.
pub fn op_mulmod(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 3) unreachable;
const n = frame.stack.pop_unsafe();
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (n == 0) {
result = 0;
} else {
// For MULMOD, we need to compute (a * b) % n where a * b might overflow
// We can't just do (a *% b) % n because that would give us ((a * b) % 2^256) % n
// which is not the same as (a * b) % n when a * b >= 2^256
// We'll use the Russian peasant multiplication algorithm with modular reduction
// This allows us to compute (a * b) % n without needing the full 512-bit product
result = 0;
var x = a % n;
var y = b % n;
while (y > 0) {
// If y is odd, add x to result (mod n)
if ((y & 1) == 1) {
const sum = result +% x;
result = sum % n;
}
x = (x +% x) % n;
y >>= 1;
}
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
/// EXP opcode (0x0A) - Exponentiation
///
/// Pops two values from the stack and raises the second to the power
/// of the top. All operations are modulo 2^256.
///
/// ## Stack Input
/// - `a`: Base (second from top)
/// - `b`: Exponent (top)
///
/// ## Stack Output
/// - `a^b`: Result of a raised to power b, modulo 2^256
///
/// ## Gas Cost
/// - Static: 10 gas
/// - Dynamic: 50 gas per byte of exponent
/// - Total: 10 + 50 * byte_size_of_exponent
///
/// ## Execution
/// 1. Pop b from stack (exponent)
/// 2. Pop a from stack (base)
/// 3. Calculate dynamic gas cost based on exponent size
/// 4. Consume the dynamic gas
/// 5. Calculate a^b using binary exponentiation
/// 6. Push result to stack
///
/// ## Algorithm
/// Uses binary exponentiation (square-and-multiply):
/// - Processes exponent bit by bit
/// - Squares base for each bit position
/// - Multiplies result when bit is set
/// - All operations modulo 2^256
///
/// ## Example
/// Stack: [2, 10] => [1024]
/// Stack: [3, 4] => [81]
/// Stack: [10, 0] => [1] (anything^0 = 1)
/// Stack: [0, 10] => [0] (0^anything = 0, except 0^0 = 1)
///
/// ## Gas Examples
/// - 2^10: 10 + 50*1 = 60 gas (exponent fits in 1 byte)
/// - 2^256: 10 + 50*2 = 110 gas (exponent needs 2 bytes)
/// - 2^(2^255): 10 + 50*32 = 1610 gas (huge exponent)
pub fn op_exp(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
_ = vm;
if (frame.stack.size < 2) unreachable;
const exp = frame.stack.pop_unsafe();
const base = frame.stack.peek_unsafe().*;
var exp_copy = exp;
var byte_size: u64 = 0;
while (exp_copy > 0) : (exp_copy >>= 8) {
byte_size += 1;
}
if (byte_size > 0) {
const gas_cost = 50 * byte_size;
try frame.consume_gas(gas_cost);
}
var result: u256 = 1;
var b = base;
var e = exp;
while (e > 0) {
if ((e & 1) == 1) {
result *%= b;
}
b *%= b;
e >>= 1;
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
/// SIGNEXTEND opcode (0x0B) - Sign extension
///
/// Extends the sign bit of a value from a given byte position to fill
/// all higher-order bits. Used to convert smaller signed integers to
/// full 256-bit representation.
///
/// ## Stack Input
/// - `b`: Byte position of sign bit (0-indexed from right)
/// - `x`: Value to sign-extend
///
/// ## Stack Output
/// - Sign-extended value
///
/// ## Gas Cost
/// 5 gas (GasFastStep)
///
/// ## Execution
/// 1. Pop b from stack (byte position)
/// 2. Pop x from stack (value to extend)
/// 3. If b >= 31, return x unchanged (already full width)
/// 4. Find sign bit at position (b * 8 + 7)
/// 5. If sign bit = 1, fill higher bits with 1s
/// 6. If sign bit = 0, fill higher bits with 0s
/// 7. Push result to stack
///
/// ## Byte Position
/// - b = 0: Extend from byte 0 (bits 0-7, rightmost byte)
/// - b = 1: Extend from byte 1 (bits 8-15)
/// - b = 31: Extend from byte 31 (bits 248-255, leftmost byte)
///
/// ## Example
/// Stack: [0, 0x7F] => [0x7F] (positive sign, no change)
/// Stack: [0, 0x80] => [0xFFFF...FF80] (negative sign extended)
/// Stack: [1, 0x80FF] => [0xFFFF...80FF] (extend from byte 1)
/// Stack: [31, x] => [x] (already full width)
///
/// ## Use Cases
/// - Converting int8/int16/etc to int256
/// - Arithmetic on mixed-width signed integers
/// - Implementing higher-level language semantics
pub fn op_signextend(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const byte_num = frame.stack.pop_unsafe();
const x = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (byte_num >= 31) {
result = x;
} else {
const byte_index = @as(u8, @intCast(byte_num));
const sign_bit_pos = byte_index * 8 + 7;
const sign_bit = (x >> @intCast(sign_bit_pos)) & 1;
const keep_bits = sign_bit_pos + 1;
if (sign_bit == 1) {
// First, create a mask of all 1s for the upper bits
if (keep_bits >= 256) {
result = x;
} else {
const shift_amount = @as(u9, 256) - @as(u9, keep_bits);
const ones_mask = ~(@as(u256, 0) >> @intCast(shift_amount));
result = x | ones_mask;
}
} else {
// Sign bit is 0, extend with 0s (just mask out upper bits)
if (keep_bits >= 256) {
result = x;
} else {
const zero_mask = (@as(u256, 1) << @intCast(keep_bits)) - 1;
result = x & zero_mask;
}
}
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
```
```zig [src/evm/execution/control.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const ExecutionResult = @import("execution_result.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Vm = @import("../vm.zig");
const gas_constants = @import("../constants/gas_constants.zig");
const AccessList = @import("../access_list/access_list.zig").AccessList;
const Address = @import("Address");
const from_u256 = Address.from_u256;
pub fn op_stop(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = pc;
_ = interpreter;
_ = state;
return ExecutionError.Error.STOP;
}
pub fn op_jump(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 1) unreachable;
// Use unsafe pop since bounds checking is done by jump_table
const dest = frame.stack.pop_unsafe();
// Check if destination is a valid JUMPDEST (pass u256 directly)
if (!frame.contract.valid_jumpdest(frame.allocator, dest)) return ExecutionError.Error.InvalidJump;
// After validation, convert to usize for setting pc
if (dest > std.math.maxInt(usize)) return ExecutionError.Error.InvalidJump;
frame.pc = @as(usize, @intCast(dest));
return ExecutionResult{};
}
pub fn op_jumpi(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Use batch pop for performance - pop 2 values at once
const values = frame.stack.pop2_unsafe();
const dest = values.b; // Second from top (was on top)
const condition = values.a; // Third from top (was second)
if (condition != 0) {
// Check if destination is a valid JUMPDEST (pass u256 directly)
if (!frame.contract.valid_jumpdest(frame.allocator, dest)) return ExecutionError.Error.InvalidJump;
// After validation, convert to usize for setting pc
if (dest > std.math.maxInt(usize)) return ExecutionError.Error.InvalidJump;
frame.pc = @as(usize, @intCast(dest));
}
return ExecutionResult{};
}
pub fn op_pc(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size >= Stack.CAPACITY) unreachable;
// Use unsafe push since bounds checking is done by jump_table
frame.stack.append_unsafe(@as(u256, @intCast(pc)));
return ExecutionResult{};
}
pub fn op_jumpdest(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = pc;
_ = interpreter;
_ = state;
// No-op, just marks valid jump destination
return ExecutionResult{};
}
pub fn op_return(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Use batch pop for performance - pop 2 values at once
const values = frame.stack.pop2_unsafe();
const size = values.b; // Second from top (was on top)
const offset = values.a; // Third from top (was second)
if (size == 0) {
frame.return_data_buffer = &[_]u8{};
} else {
if (offset > std.math.maxInt(usize) or size > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const offset_usize = @as(usize, @intCast(offset));
const size_usize = @as(usize, @intCast(size));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const end = offset_usize + size_usize;
if (end > offset_usize) { // Check for overflow
const memory_gas = gas_constants.memory_gas_cost(current_size, end);
try frame.consume_gas(memory_gas);
_ = try frame.memory.ensure_context_capacity(end);
}
// Get data from memory
const data = try frame.memory.get_slice(offset_usize, size_usize);
// Note: The memory gas cost already protects against excessive memory use.
// The VM should handle copying the data when needed. We just set the reference.
frame.return_data_buffer = data;
}
return ExecutionError.Error.STOP; // RETURN ends execution normally
}
pub fn op_revert(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Use batch pop for performance - pop 2 values at once
const values = frame.stack.pop2_unsafe();
const size = values.b; // Second from top (was on top)
const offset = values.a; // Third from top (was second)
if (size == 0) {
frame.return_data_buffer = &[_]u8{};
} else {
if (offset > std.math.maxInt(usize) or size > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const offset_usize = @as(usize, @intCast(offset));
const size_usize = @as(usize, @intCast(size));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const end = offset_usize + size_usize;
if (end > offset_usize) { // Check for overflow
const memory_gas = gas_constants.memory_gas_cost(current_size, end);
try frame.consume_gas(memory_gas);
_ = try frame.memory.ensure_context_capacity(end);
}
// Get data from memory
const data = try frame.memory.get_slice(offset_usize, size_usize);
// Note: The memory gas cost already protects against excessive memory use.
// The VM should handle copying the data when needed. We just set the reference.
frame.return_data_buffer = data;
}
return ExecutionError.Error.REVERT;
}
pub fn op_invalid(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Debug: op_invalid entered
// INVALID opcode consumes all remaining gas
frame.gas_remaining = 0;
// Debug: op_invalid returning InvalidOpcode
return ExecutionError.Error.InvalidOpcode;
}
pub fn op_selfdestruct(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Check if we're in a static call
if (frame.is_static) return ExecutionError.Error.WriteProtection;
if (frame.stack.size < 1) unreachable;
// Use unsafe pop since bounds checking is done by jump_table
const beneficiary_u256 = frame.stack.pop_unsafe();
const beneficiary = from_u256(beneficiary_u256);
// EIP-2929: Check if beneficiary address is cold and consume appropriate gas
const access_cost = vm.access_list.access_address(beneficiary) catch |err| switch (err) {
error.OutOfMemory => return ExecutionError.Error.OutOfGas,
};
const is_cold = access_cost == AccessList.COLD_ACCOUNT_ACCESS_COST;
if (is_cold) {
// Cold address access costs more (2600 gas)
try frame.consume_gas(gas_constants.ColdAccountAccessCost);
}
// Schedule selfdestruct for execution at the end of the transaction
// For now, just return STOP
return ExecutionError.Error.STOP;
}
```
```zig [src/evm/execution/package.zig]
// Package file for opcodes modules
// This file serves as the entry point for importing opcode modules
// Re-export all opcode modules for easy access
pub const arithmetic = @import("arithmetic.zig");
pub const bitwise = @import("bitwise.zig");
pub const block = @import("block.zig");
pub const comparison = @import("comparison.zig");
pub const control = @import("control.zig");
pub const crypto = @import("crypto.zig");
pub const environment = @import("environment.zig");
pub const log = @import("log.zig");
pub const memory = @import("memory.zig");
pub const stack = @import("stack.zig");
pub const storage = @import("storage.zig");
pub const system = @import("system.zig");
// Re-export common types
pub const Operation = @import("../opcodes/operation.zig");
pub const ExecutionError = @import("execution_error.zig");
pub const Frame = @import("../frame.zig");
pub const Stack = @import("../stack/stack.zig");
pub const Memory = @import("../memory.zig");
pub const Vm = @import("../vm.zig");
pub const Contract = @import("../contract/contract.zig");
pub const gas_constants = @import("../constants/gas_constants.zig");
```
```zig [src/evm/execution/execution_error.zig]
const std = @import("std");
/// ExecutionError represents various error conditions that can occur during EVM execution
///
/// This module defines all possible error conditions that can occur during the execution
/// of EVM bytecode. These errors are used throughout the EVM implementation to signal
/// various failure conditions, from normal stops to critical errors.
///
/// ## Error Categories
///
/// The errors can be broadly categorized into:
///
/// 1. **Normal Termination**: STOP, REVERT, INVALID
/// 2. **Resource Exhaustion**: OutOfGas, StackOverflow, MemoryLimitExceeded
/// 3. **Invalid Operations**: InvalidJump, InvalidOpcode, StaticStateChange
/// 4. **Bounds Violations**: StackUnderflow, OutOfOffset, ReturnDataOutOfBounds
/// 5. **Contract Creation**: DeployCodeTooBig, MaxCodeSizeExceeded, InvalidCodeEntry
/// 6. **Call Stack**: DepthLimit
/// 7. **Memory Management**: OutOfMemory, InvalidOffset, InvalidSize, ChildContextActive
/// 8. **Future Features**: EOFNotSupported
const Self = @This();
/// Error types for EVM execution
///
/// Each error represents a specific condition that can occur during EVM execution.
/// Some errors (like STOP and REVERT) are normal termination conditions, while
/// others represent actual failure states.
pub const Error = error{
/// Normal termination via STOP opcode (0x00)
/// This is not an error condition - it signals successful completion
STOP,
/// State reversion via REVERT opcode (0xFD)
/// Returns data and reverts all state changes in the current context
REVERT,
/// Execution of INVALID opcode (0xFE)
/// Consumes all remaining gas and reverts state
INVALID,
/// Insufficient gas to complete operation
/// Occurs when gas_remaining < gas_required for any operation
OutOfGas,
/// Attempted to pop from empty stack or insufficient stack items
/// Stack operations require specific minimum stack sizes
StackUnderflow,
/// Stack size exceeded maximum of 1024 elements
/// Pushing to a full stack causes this error
StackOverflow,
/// JUMP/JUMPI to invalid destination
/// Destination must be a JUMPDEST opcode at a valid position
InvalidJump,
/// Attempted to execute undefined opcode
/// Not all byte values 0x00-0xFF are defined opcodes
InvalidOpcode,
/// Attempted state modification in static call context
/// SSTORE, LOG*, CREATE*, and SELFDESTRUCT are forbidden in static calls
StaticStateChange,
/// Memory or calldata access beyond valid bounds
/// Usually from integer overflow in offset calculations
OutOfOffset,
/// Gas calculation resulted in integer overflow
/// Can occur with extremely large memory expansions
GasUintOverflow,
/// Attempted write in read-only context
/// Similar to StaticStateChange but more general
WriteProtection,
/// RETURNDATACOPY accessing data beyond RETURNDATASIZE
/// Unlike other copy operations, this is a hard error
ReturnDataOutOfBounds,
/// Contract deployment code exceeds maximum size
/// Deployment bytecode has its own size limits
DeployCodeTooBig,
/// Deployed contract code exceeds 24,576 byte limit (EIP-170)
/// Prevents storing excessively large contracts
MaxCodeSizeExceeded,
/// Invalid contract initialization code
/// Can occur with malformed constructor bytecode
InvalidCodeEntry,
/// Call stack depth exceeded 1024 levels
/// Prevents infinite recursion and stack overflow attacks
DepthLimit,
/// Memory allocation failed (host environment issue)
/// Not a normal EVM error - indicates system resource exhaustion
OutOfMemory,
/// Invalid memory offset in operation
/// Usually from malformed offset values
InvalidOffset,
/// Invalid memory size in operation
/// Usually from malformed size values
InvalidSize,
/// Memory expansion would exceed configured limits
/// Prevents excessive memory usage (typically 32MB limit)
MemoryLimitExceeded,
/// Attempted operation while child memory context is active
/// Memory contexts must be properly managed
ChildContextActive,
/// Attempted to revert/commit without active child context
/// Memory context operations must be balanced
NoChildContextToRevertOrCommit,
/// EOF (EVM Object Format) features not yet implemented
/// Placeholder for future EOF-related opcodes
EOFNotSupported,
};
/// Get a human-readable description for an execution error
///
/// Provides detailed descriptions of what each error means and when it occurs.
/// Useful for debugging, logging, and error reporting.
///
/// ## Parameters
/// - `err`: The execution error to describe
///
/// ## Returns
/// A string slice containing a human-readable description of the error
///
/// ## Example
/// ```zig
/// const err = Error.StackOverflow;
/// const desc = get_description(err);
/// std.log.err("EVM execution failed: {s}", .{desc});
/// ```
pub fn get_description(err: Error) []const u8 {
return switch (err) {
Error.STOP => "Normal STOP opcode execution",
Error.REVERT => "REVERT opcode - state reverted",
Error.INVALID => "INVALID opcode or invalid operation",
Error.OutOfGas => "Out of gas",
Error.StackUnderflow => "Stack underflow",
Error.StackOverflow => "Stack overflow (beyond 1024 elements)",
Error.InvalidJump => "Jump to invalid destination",
Error.InvalidOpcode => "Undefined opcode",
Error.StaticStateChange => "State modification in static context",
Error.OutOfOffset => "Memory access out of bounds",
Error.GasUintOverflow => "Gas calculation overflow",
Error.WriteProtection => "Write to protected storage",
Error.ReturnDataOutOfBounds => "Return data access out of bounds",
Error.DeployCodeTooBig => "Contract creation code too large",
Error.MaxCodeSizeExceeded => "Contract code size exceeds limit",
Error.InvalidCodeEntry => "Invalid contract entry code",
Error.DepthLimit => "Call depth exceeds limit (1024)",
Error.OutOfMemory => "Out of memory allocation failed",
Error.InvalidOffset => "Invalid memory offset",
Error.InvalidSize => "Invalid memory size",
Error.MemoryLimitExceeded => "Memory limit exceeded",
Error.ChildContextActive => "Child context is active",
Error.NoChildContextToRevertOrCommit => "No child context to revert or commit",
Error.EOFNotSupported => "EOF (EVM Object Format) opcode not supported",
};
}
```
```zig [src/evm/execution/bitwise.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
pub fn op_and(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
const result = a & b;
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_or(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
const result = a | b;
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_xor(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const b = frame.stack.pop_unsafe();
const a = frame.stack.peek_unsafe().*;
const result = a ^ b;
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_not(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 1) unreachable;
const value = frame.stack.peek_unsafe().*;
const result = ~value;
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_byte(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const i = frame.stack.pop_unsafe();
const val = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (i >= 32) {
result = 0;
} else {
const i_usize = @as(usize, @intCast(i));
// Byte 0 is MSB, byte 31 is LSB
// To get byte i, we need to shift right by (31 - i) * 8 positions
const shift_amount = (31 - i_usize) * 8;
result = (val >> @intCast(shift_amount)) & 0xFF;
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_shl(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const shift = frame.stack.pop_unsafe();
const value = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (shift >= 256) {
result = 0;
} else {
result = value << @intCast(shift);
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_shr(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const shift = frame.stack.pop_unsafe();
const value = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (shift >= 256) {
result = 0;
} else {
result = value >> @intCast(shift);
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_sar(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
const shift = frame.stack.pop_unsafe();
const value = frame.stack.peek_unsafe().*;
var result: u256 = undefined;
if (shift >= 256) {
const sign_bit = value >> 255;
if (sign_bit == 1) {
result = std.math.maxInt(u256);
} else {
result = 0;
}
} else {
// Arithmetic shift preserving sign
const shift_amount = @as(u8, @intCast(shift));
const value_i256 = @as(i256, @bitCast(value));
const result_i256 = value_i256 >> shift_amount;
result = @as(u256, @bitCast(result_i256));
}
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
```
```zig [src/evm/execution/crypto.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Vm = @import("../vm.zig");
pub fn op_sha3(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const offset = try frame.stack.pop();
const size = try frame.stack.pop();
// Check bounds before anything else
if (offset > std.math.maxInt(usize) or size > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
if (size == 0) {
// Even with size 0, we need to validate the offset is reasonable
if (offset > 0) {
// Check if offset is beyond reasonable memory limits
const offset_usize = @as(usize, @intCast(offset));
const memory_limits = @import("../constants/memory_limits.zig");
if (offset_usize > memory_limits.MAX_MEMORY_SIZE) return ExecutionError.Error.OutOfOffset;
}
// Hash of empty data = keccak256("")
const empty_hash: u256 = 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470;
try frame.stack.append( empty_hash);
return Operation.ExecutionResult{};
}
const offset_usize = @as(usize, @intCast(offset));
const size_usize = @as(usize, @intCast(size));
// Check if offset + size would overflow
const end = std.math.add(usize, offset_usize, size_usize) catch {
return ExecutionError.Error.OutOfOffset;
};
// Check if the end position exceeds reasonable memory limits
const memory_limits = @import("../constants/memory_limits.zig");
if (end > memory_limits.MAX_MEMORY_SIZE) return ExecutionError.Error.OutOfOffset;
// Dynamic gas cost for hashing
const word_size = (size_usize + 31) / 32;
const gas_cost = 6 * word_size;
_ = vm;
try frame.consume_gas(gas_cost);
// Ensure memory is available
_ = try frame.memory.ensure_context_capacity(offset_usize + size_usize);
// Get data and hash
const data = try frame.memory.get_slice(offset_usize, size_usize);
// Calculate keccak256 hash
var hash: [32]u8 = undefined;
std.crypto.hash.sha3.Keccak256.hash(data, &hash, .{});
// Hash calculated successfully
// Convert hash to u256
var result: u256 = 0;
for (hash) |byte| {
result = (result << 8) | byte;
}
try frame.stack.append(result);
return Operation.ExecutionResult{};
}
// Alias for backwards compatibility
pub const op_keccak256 = op_sha3;
```
```zig [src/evm/execution/environment.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Vm = @import("../vm.zig");
const Address = @import("Address");
const to_u256 = Address.to_u256;
const from_u256 = Address.from_u256;
const gas_constants = @import("../constants/gas_constants.zig");
const AccessList = @import("../access_list/access_list.zig").AccessList;
// Import helper functions from error_mapping
pub fn op_address(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Push contract address as u256
const addr = to_u256(frame.contract.address);
try frame.stack.append( addr);
return Operation.ExecutionResult{};
}
pub fn op_balance(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const address_u256 = try frame.stack.pop();
const address = from_u256(address_u256);
// EIP-2929: Check if address is cold and consume appropriate gas
const access_cost = try vm.access_list.access_address(address);
try frame.consume_gas(access_cost);
// Get balance from VM state
const balance = vm.state.get_balance(address);
try frame.stack.append( balance);
return Operation.ExecutionResult{};
}
pub fn op_origin(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Push transaction origin address
const origin = to_u256(vm.context.tx_origin);
try frame.stack.append( origin);
return Operation.ExecutionResult{};
}
pub fn op_caller(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Push caller address
const caller = to_u256(frame.contract.caller);
try frame.stack.append( caller);
return Operation.ExecutionResult{};
}
pub fn op_callvalue(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Push call value
try frame.stack.append( frame.contract.value);
return Operation.ExecutionResult{};
}
pub fn op_gasprice(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Push gas price from transaction context
try frame.stack.append( vm.context.gas_price);
return Operation.ExecutionResult{};
}
pub fn op_extcodesize(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const address_u256 = try frame.stack.pop();
const address = from_u256(address_u256);
// EIP-2929: Check if address is cold and consume appropriate gas
const access_cost = try vm.access_list.access_address(address);
try frame.consume_gas(access_cost);
// Get code size from VM state
const code = vm.state.get_code(address);
try frame.stack.append( @as(u256, @intCast(code.len)));
return Operation.ExecutionResult{};
}
pub fn op_extcodecopy(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const address_u256 = try frame.stack.pop();
const mem_offset = try frame.stack.pop();
const code_offset = try frame.stack.pop();
const size = try frame.stack.pop();
if (size == 0) return Operation.ExecutionResult{};
if (mem_offset > std.math.maxInt(usize) or size > std.math.maxInt(usize) or code_offset > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const address = from_u256(address_u256);
const mem_offset_usize = @as(usize, @intCast(mem_offset));
const code_offset_usize = @as(usize, @intCast(code_offset));
const size_usize = @as(usize, @intCast(size));
// EIP-2929: Check if address is cold and consume appropriate gas
const access_cost = try vm.access_list.access_address(address);
try frame.consume_gas(access_cost);
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = mem_offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(memory_gas);
// Dynamic gas for copy operation
const word_size = (size_usize + 31) / 32;
try frame.consume_gas(gas_constants.CopyGas * word_size);
// Get external code from VM state
const code = vm.state.get_code(address);
// Use set_data_bounded to copy the code to memory
// This handles partial copies and zero-padding automatically
try frame.memory.set_data_bounded(mem_offset_usize, code, code_offset_usize, size_usize);
return Operation.ExecutionResult{};
}
pub fn op_extcodehash(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const address_u256 = try frame.stack.pop();
const address = from_u256(address_u256);
// EIP-2929: Check if address is cold and consume appropriate gas
const access_cost = try vm.access_list.access_address(address);
try frame.consume_gas(access_cost);
// Get code from VM state and compute hash
const code = vm.state.get_code(address);
if (code.len == 0) {
// Empty account - return zero
try frame.stack.append( 0);
} else {
// Compute keccak256 hash of the code
var hash: [32]u8 = undefined;
std.crypto.hash.sha3.Keccak256.hash(code, &hash, .{});
// Convert hash to u256
var hash_u256: u256 = 0;
for (hash) |byte| {
hash_u256 = (hash_u256 << 8) | byte;
}
try frame.stack.append( hash_u256);
}
return Operation.ExecutionResult{};
}
pub fn op_selfbalance(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Get balance of current executing contract
const self_address = frame.contract.address;
const balance = vm.state.get_balance(self_address);
try frame.stack.append( balance);
return Operation.ExecutionResult{};
}
pub fn op_chainid(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Push chain ID from VM context
try frame.stack.append( vm.context.chain_id);
return Operation.ExecutionResult{};
}
pub fn op_calldatasize(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Push size of calldata - use frame.input which is set by the VM
// The frame.input is the actual calldata for this execution context
try frame.stack.append( @as(u256, @intCast(frame.input.len)));
return Operation.ExecutionResult{};
}
pub fn op_codesize(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Push size of current contract's code
try frame.stack.append( @as(u256, @intCast(frame.contract.code.len)));
return Operation.ExecutionResult{};
}
pub fn op_calldataload(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Pop offset from stack
const offset = try frame.stack.pop();
if (offset > std.math.maxInt(usize)) {
// Offset too large, push zero
try frame.stack.append( 0);
return Operation.ExecutionResult{};
}
const offset_usize = @as(usize, @intCast(offset));
const calldata = frame.input; // Use frame.input, not frame.contract.input
// Load 32 bytes from calldata, padding with zeros if necessary
var value: u256 = 0;
var i: usize = 0;
while (i < 32) : (i += 1) {
if (offset_usize + i < calldata.len) {
value = (value << 8) | calldata[offset_usize + i];
} else {
value = value << 8; // Pad with zero
}
}
try frame.stack.append( value);
return Operation.ExecutionResult{};
}
pub fn op_calldatacopy(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Pop memory offset, data offset, and size
const mem_offset = try frame.stack.pop();
const data_offset = try frame.stack.pop();
const size = try frame.stack.pop();
if (size == 0) return Operation.ExecutionResult{};
if (mem_offset > std.math.maxInt(usize) or size > std.math.maxInt(usize) or data_offset > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const mem_offset_usize = @as(usize, @intCast(mem_offset));
const data_offset_usize = @as(usize, @intCast(data_offset));
const size_usize = @as(usize, @intCast(size));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = mem_offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(memory_gas);
// Dynamic gas for copy operation (VERYLOW * word_count)
const word_size = (size_usize + 31) / 32;
try frame.consume_gas(gas_constants.CopyGas * word_size);
// Get calldata from frame.input
const calldata = frame.input;
// Use set_data_bounded to copy the calldata to memory
// This handles partial copies and zero-padding automatically
try frame.memory.set_data_bounded(mem_offset_usize, calldata, data_offset_usize, size_usize);
return Operation.ExecutionResult{};
}
pub fn op_codecopy(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Pop memory offset, code offset, and size
const mem_offset = try frame.stack.pop();
const code_offset = try frame.stack.pop();
const size = try frame.stack.pop();
if (size == 0) return Operation.ExecutionResult{};
if (mem_offset > std.math.maxInt(usize) or size > std.math.maxInt(usize) or code_offset > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const mem_offset_usize = @as(usize, @intCast(mem_offset));
const code_offset_usize = @as(usize, @intCast(code_offset));
const size_usize = @as(usize, @intCast(size));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = mem_offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(memory_gas);
// Dynamic gas for copy operation
const word_size = (size_usize + 31) / 32;
try frame.consume_gas(gas_constants.CopyGas * word_size);
// Get current contract code
const code = frame.contract.code;
// Use set_data_bounded to copy the code to memory
// This handles partial copies and zero-padding automatically
try frame.memory.set_data_bounded(mem_offset_usize, code, code_offset_usize, size_usize);
return Operation.ExecutionResult{};
}
/// RETURNDATALOAD opcode (0xF7): Loads a 32-byte word from return data
/// This is an EOF opcode that allows reading from the return data buffer
pub fn op_returndataload(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
// Pop offset from stack
const offset = try frame.stack.pop();
// Check if offset is within bounds
if (offset > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const offset_usize = @as(usize, @intCast(offset));
const return_data = frame.return_data_buffer;
// If offset + 32 > return_data.len, this is an error (unlike CALLDATALOAD which pads with zeros)
if (offset_usize + 32 > return_data.len) return ExecutionError.Error.OutOfOffset;
// Load 32 bytes from return data
var value: u256 = 0;
var i: usize = 0;
while (i < 32) : (i += 1) {
value = (value << 8) | return_data[offset_usize + i];
}
try frame.stack.append( value);
return Operation.ExecutionResult{};
}
```
```zig [src/evm/execution/log.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Vm = @import("../vm.zig");
const gas_constants = @import("../constants/gas_constants.zig");
const Address = @import("Address");
// Compile-time verification that this file is being used
const COMPILE_TIME_LOG_VERSION = "2024_LOG_FIX_V2";
// Import Log struct from VM
const Log = Vm.Log;
// Import helper functions from error_mapping
pub fn make_log(comptime num_topics: u8) fn (usize, *Operation.Interpreter, *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
return struct {
pub fn log(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Debug logging removed for production
// Check if we're in a static call
if (frame.is_static) return ExecutionError.Error.WriteProtection;
// REVM EXACT MATCH: Pop offset first, then len (revm: popn!([offset, len]))
const offset = try frame.stack.pop();
const size = try frame.stack.pop();
// Debug logging removed for production
// Pop N topics in order and store them in REVERSE (revm: stack.popn::() returns in push order)
var topics: [4]u256 = undefined;
for (0..num_topics) |i| {
topics[num_topics - 1 - i] = try frame.stack.pop();
// Topic popped successfully
}
if (size == 0) {
// Empty data
// Emit empty log
try vm.emit_log(frame.contract.address, topics[0..num_topics], &[_]u8{});
return Operation.ExecutionResult{};
}
// Process non-empty log data
if (offset > std.math.maxInt(usize) or size > std.math.maxInt(usize)) {
// Offset or size exceeds maximum
return ExecutionError.Error.OutOfOffset;
}
const offset_usize = @as(usize, @intCast(offset));
const size_usize = @as(usize, @intCast(size));
// Convert to usize for memory operations
// Note: Base LOG gas (375) and topic gas (375 * N) are handled by jump table as constant_gas
// We only need to handle dynamic costs: memory expansion and data bytes
// 1. Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
// Memory expansion gas calculated
try frame.consume_gas(memory_gas);
// 2. Dynamic gas for data
const byte_cost = gas_constants.LogDataGas * size_usize;
// Calculate dynamic gas for data
try frame.consume_gas(byte_cost);
// Gas consumed successfully
// Ensure memory is available
_ = try frame.memory.ensure_context_capacity(offset_usize + size_usize);
// Get log data
const data = try frame.memory.get_slice(offset_usize, size_usize);
// Emit log with data
// Add log
try vm.emit_log(frame.contract.address, topics[0..num_topics], data);
return Operation.ExecutionResult{};
}
}.log;
}
// LOG operations are now generated directly in jump_table.zig using make_log()
```
```zig [src/evm/execution/memory.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Memory = @import("../memory.zig");
const gas_constants = @import("../constants/gas_constants.zig");
// Helper to check if u256 fits in usize
fn check_offset_bounds(value: u256) ExecutionError.Error!void {
if (value > std.math.maxInt(usize)) return ExecutionError.Error.InvalidOffset;
}
pub fn op_mload(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 1) unreachable;
// Get offset from top of stack unsafely - bounds checking is done in jump_table.zig
const offset = frame.stack.peek_unsafe().*;
if (offset > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const offset_usize = @as(usize, @intCast(offset));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = offset_usize + 32;
const gas_cost = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(gas_cost);
// Ensure memory is available
_ = try frame.memory.ensure_context_capacity(offset_usize + 32);
// Read 32 bytes from memory
const value = try frame.memory.get_u256(offset_usize);
// Replace top of stack with loaded value unsafely - bounds checking is done in jump_table.zig
frame.stack.set_top_unsafe(value);
return Operation.ExecutionResult{};
}
pub fn op_mstore(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Pop two values unsafely using batch operation - bounds checking is done in jump_table.zig
// EVM Stack: [..., value, offset] where offset is on top
const popped = frame.stack.pop2_unsafe();
const value = popped.a; // First popped (was second from top)
const offset = popped.b; // Second popped (was top)
if (offset > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const offset_usize = @as(usize, @intCast(offset));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = offset_usize + 32; // MSTORE writes 32 bytes
const expansion_gas_cost = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(expansion_gas_cost);
// Ensure memory is available
_ = try frame.memory.ensure_context_capacity(offset_usize + 32);
// Write 32 bytes to memory (big-endian)
var bytes: [32]u8 = undefined;
// Convert u256 to big-endian bytes
var temp = value;
var i: usize = 0;
while (i < 32) : (i += 1) {
bytes[31 - i] = @intCast(temp & 0xFF);
temp = temp >> 8;
}
try frame.memory.set_data(offset_usize, &bytes);
return Operation.ExecutionResult{};
}
pub fn op_mstore8(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 2) unreachable;
// Pop two values unsafely using batch operation - bounds checking is done in jump_table.zig
// EVM Stack: [..., value, offset] where offset is on top
const popped = frame.stack.pop2_unsafe();
const value = popped.a; // First popped (was second from top)
const offset = popped.b; // Second popped (was top)
if (offset > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const offset_usize = @as(usize, @intCast(offset));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = offset_usize + 1;
const gas_cost = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(gas_cost);
// Ensure memory is available - expand to word boundary to match gas calculation
const word_aligned_size = ((new_size + 31) / 32) * 32;
_ = try frame.memory.ensure_context_capacity(word_aligned_size);
// Write single byte to memory
const byte_value = @as(u8, @truncate(value));
const bytes = [_]u8{byte_value};
try frame.memory.set_data(offset_usize, &bytes);
return Operation.ExecutionResult{};
}
pub fn op_msize(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size >= Stack.CAPACITY) unreachable;
// MSIZE returns the size in bytes, but memory is always expanded in 32-byte words
// So we need to round up to the nearest word boundary
const size = frame.memory.context_size();
const word_aligned_size = ((size + 31) / 32) * 32;
// Push result unsafely - bounds checking is done in jump_table.zig
frame.stack.append_unsafe(@as(u256, @intCast(word_aligned_size)));
return Operation.ExecutionResult{};
}
pub fn op_mcopy(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 3) unreachable;
// Pop three values unsafely - bounds checking is done in jump_table.zig
// EVM stack order: [..., dest, src, size] (top to bottom)
const size = frame.stack.pop_unsafe();
const src = frame.stack.pop_unsafe();
const dest = frame.stack.pop_unsafe();
if (size == 0) return Operation.ExecutionResult{};
if (dest > std.math.maxInt(usize) or src > std.math.maxInt(usize) or size > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const dest_usize = @as(usize, @intCast(dest));
const src_usize = @as(usize, @intCast(src));
const size_usize = @as(usize, @intCast(size));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const max_addr = @max(dest_usize + size_usize, src_usize + size_usize);
const memory_gas = gas_constants.memory_gas_cost(current_size, max_addr);
try frame.consume_gas(memory_gas);
// Dynamic gas for copy operation
const word_size = (size_usize + 31) / 32;
try frame.consume_gas(gas_constants.CopyGas * word_size);
// Ensure memory is available for both source and destination
_ = try frame.memory.ensure_context_capacity(max_addr);
// Copy with overlap handling
// Get memory slice and handle overlapping copy
const mem_slice = frame.memory.slice();
if (mem_slice.len >= max_addr) {
// Handle overlapping memory copy correctly
if (dest_usize > src_usize and dest_usize < src_usize + size_usize) {
// Forward overlap: dest is within source range, copy backwards
std.mem.copyBackwards(u8, mem_slice[dest_usize..dest_usize + size_usize], mem_slice[src_usize..src_usize + size_usize]);
} else if (src_usize > dest_usize and src_usize < dest_usize + size_usize) {
// Backward overlap: src is within dest range, copy forwards
std.mem.copyForwards(u8, mem_slice[dest_usize..dest_usize + size_usize], mem_slice[src_usize..src_usize + size_usize]);
} else {
// No overlap, either direction is fine
std.mem.copyForwards(u8, mem_slice[dest_usize..dest_usize + size_usize], mem_slice[src_usize..src_usize + size_usize]);
}
} else {
return ExecutionError.Error.OutOfOffset;
}
return Operation.ExecutionResult{};
}
pub fn op_calldataload(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 1) unreachable;
// Get offset from top of stack unsafely - bounds checking is done in jump_table.zig
const offset = frame.stack.peek_unsafe().*;
if (offset > std.math.maxInt(usize)) {
// Replace top of stack with 0
frame.stack.set_top_unsafe(0);
return Operation.ExecutionResult{};
}
const offset_usize = @as(usize, @intCast(offset));
// Read 32 bytes from calldata (pad with zeros)
var result: u256 = 0;
for (0..32) |i| {
if (offset_usize + i < frame.input.len) {
result = (result << 8) | frame.input[offset_usize + i];
} else {
result = result << 8;
}
}
// Replace top of stack with loaded value unsafely - bounds checking is done in jump_table.zig
frame.stack.set_top_unsafe(result);
return Operation.ExecutionResult{};
}
pub fn op_calldatasize(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size >= Stack.CAPACITY) unreachable;
// Push result unsafely - bounds checking is done in jump_table.zig
frame.stack.append_unsafe(@as(u256, @intCast(frame.input.len)));
return Operation.ExecutionResult{};
}
pub fn op_calldatacopy(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 3) unreachable;
// Pop three values unsafely - bounds checking is done in jump_table.zig
// EVM stack order: [..., size, data_offset, mem_offset] (top to bottom)
const mem_offset = frame.stack.pop_unsafe();
const data_offset = frame.stack.pop_unsafe();
const size = frame.stack.pop_unsafe();
if (size == 0) return Operation.ExecutionResult{};
if (mem_offset > std.math.maxInt(usize) or data_offset > std.math.maxInt(usize) or size > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const mem_offset_usize = @as(usize, @intCast(mem_offset));
const data_offset_usize = @as(usize, @intCast(data_offset));
const size_usize = @as(usize, @intCast(size));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = mem_offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(memory_gas);
// Dynamic gas for copy operation
const word_size = (size_usize + 31) / 32;
try frame.consume_gas(gas_constants.CopyGas * word_size);
// Ensure memory is available
_ = try frame.memory.ensure_context_capacity(mem_offset_usize + size_usize);
// Copy calldata to memory
try frame.memory.set_data_bounded(mem_offset_usize, frame.input, data_offset_usize, size_usize);
return Operation.ExecutionResult{};
}
pub fn op_codesize(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size >= Stack.CAPACITY) unreachable;
// Push result unsafely - bounds checking is done in jump_table.zig
frame.stack.append_unsafe(@as(u256, @intCast(frame.contract.code.len)));
return Operation.ExecutionResult{};
}
pub fn op_codecopy(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 3) unreachable;
// Pop three values unsafely - bounds checking is done in jump_table.zig
// EVM stack order: [..., size, code_offset, mem_offset] (top to bottom)
const mem_offset = frame.stack.pop_unsafe();
const code_offset = frame.stack.pop_unsafe();
const size = frame.stack.pop_unsafe();
if (size == 0) return Operation.ExecutionResult{};
if (mem_offset > std.math.maxInt(usize) or code_offset > std.math.maxInt(usize) or size > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const mem_offset_usize = @as(usize, @intCast(mem_offset));
const code_offset_usize = @as(usize, @intCast(code_offset));
const size_usize = @as(usize, @intCast(size));
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = mem_offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(memory_gas);
// Dynamic gas for copy operation
const word_size = (size_usize + 31) / 32;
try frame.consume_gas(gas_constants.CopyGas * word_size);
// Ensure memory is available
_ = try frame.memory.ensure_context_capacity(mem_offset_usize + size_usize);
// Copy code to memory
try frame.memory.set_data_bounded(mem_offset_usize, frame.contract.code, code_offset_usize, size_usize);
return Operation.ExecutionResult{};
}
pub fn op_returndatasize(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size >= Stack.CAPACITY) unreachable;
// Push result unsafely - bounds checking is done in jump_table.zig
frame.stack.append_unsafe(@as(u256, @intCast(frame.return_data_buffer.len)));
return Operation.ExecutionResult{};
}
pub fn op_returndatacopy(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < 3) unreachable;
// Pop three values unsafely - bounds checking is done in jump_table.zig
// EVM stack order: [..., size, data_offset, mem_offset] (top to bottom)
const mem_offset = frame.stack.pop_unsafe();
const data_offset = frame.stack.pop_unsafe();
const size = frame.stack.pop_unsafe();
if (size == 0) return Operation.ExecutionResult{};
if (mem_offset > std.math.maxInt(usize) or data_offset > std.math.maxInt(usize) or size > std.math.maxInt(usize)) return ExecutionError.Error.OutOfOffset;
const mem_offset_usize = @as(usize, @intCast(mem_offset));
const data_offset_usize = @as(usize, @intCast(data_offset));
const size_usize = @as(usize, @intCast(size));
// Check bounds
if (data_offset_usize + size_usize > frame.return_data_buffer.len) return ExecutionError.Error.ReturnDataOutOfBounds;
// Calculate memory expansion gas cost
const current_size = frame.memory.context_size();
const new_size = mem_offset_usize + size_usize;
const memory_gas = gas_constants.memory_gas_cost(current_size, new_size);
try frame.consume_gas(memory_gas);
// Dynamic gas for copy operation
const word_size = (size_usize + 31) / 32;
try frame.consume_gas(gas_constants.CopyGas * word_size);
// Ensure memory is available
_ = try frame.memory.ensure_context_capacity(mem_offset_usize + size_usize);
// Copy return data to memory
try frame.memory.set_data(mem_offset_usize, frame.return_data_buffer[data_offset_usize .. data_offset_usize + size_usize]);
return Operation.ExecutionResult{};
}
```
```zig [src/evm/execution/storage.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Vm = @import("../vm.zig");
const gas_constants = @import("../constants/gas_constants.zig");
const Address = @import("Address");
const Log = @import("../log.zig");
// EIP-3529 (London) gas costs for SSTORE
const SSTORE_SET_GAS: u64 = 20000;
const SSTORE_RESET_GAS: u64 = 2900;
const SSTORE_CLEARS_REFUND: u64 = 4800;
fn calculate_sstore_gas(current: u256, new: u256) u64 {
if (current == new) return 0;
if (current == 0) return SSTORE_SET_GAS;
if (new == 0) return SSTORE_RESET_GAS;
return SSTORE_RESET_GAS;
}
pub fn op_sload(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
if (frame.stack.size < 1) unreachable;
const slot = frame.stack.peek_unsafe().*;
if (vm.chain_rules.IsBerlin) {
const is_cold = frame.contract.mark_storage_slot_warm(frame.allocator, slot, null) catch {
return ExecutionError.Error.OutOfMemory;
};
const gas_cost = if (is_cold) gas_constants.ColdSloadCost else gas_constants.WarmStorageReadCost;
try frame.consume_gas(gas_cost);
} else {
// Pre-Berlin: gas is handled by jump table constant_gas
// For Istanbul, this would be 800 gas set in the jump table
}
const value = vm.state.get_storage(frame.contract.address, slot);
frame.stack.set_top_unsafe(value);
return Operation.ExecutionResult{};
}
/// SSTORE opcode - Store value in persistent storage
pub fn op_sstore(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
if (frame.is_static) return ExecutionError.Error.WriteProtection;
// EIP-1706: Disable SSTORE with gasleft lower than call stipend (2300)
// This prevents reentrancy attacks by ensuring enough gas remains for exception handling
if (vm.chain_rules.IsIstanbul and frame.gas_remaining <= gas_constants.SstoreSentryGas) return ExecutionError.Error.OutOfGas;
if (frame.stack.size < 2) unreachable;
// Stack order: [..., value, slot] where slot is on top
const popped = frame.stack.pop2_unsafe();
const value = popped.a; // First popped (was second from top)
const slot = popped.b; // Second popped (was top)
const current_value = vm.state.get_storage(frame.contract.address, slot);
const is_cold = frame.contract.mark_storage_slot_warm(frame.allocator, slot, null) catch |err| {
Log.err("SSTORE: mark_storage_slot_warm failed: {}", .{err});
return ExecutionError.Error.OutOfMemory;
};
var total_gas: u64 = 0;
if (is_cold) {
total_gas += gas_constants.ColdSloadCost;
}
// Add dynamic gas based on value change
const dynamic_gas = calculate_sstore_gas(current_value, value);
total_gas += dynamic_gas;
// Consume all gas at once
try frame.consume_gas(total_gas);
try vm.state.set_storage(frame.contract.address, slot, value);
return Operation.ExecutionResult{};
}
pub fn op_tload(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Gas is already handled by jump table constant_gas = 100
if (frame.stack.size < 1) unreachable;
// Get slot from top of stack unsafely - bounds checking is done in jump_table.zig
const slot = frame.stack.peek_unsafe().*;
const value = vm.state.get_transient_storage(frame.contract.address, slot);
// Replace top of stack with loaded value unsafely - bounds checking is done in jump_table.zig
frame.stack.set_top_unsafe(value);
return Operation.ExecutionResult{};
}
pub fn op_tstore(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
if (frame.is_static) return ExecutionError.Error.WriteProtection;
// Gas is already handled by jump table constant_gas = 100
if (frame.stack.size < 2) unreachable;
// Pop two values unsafely using batch operation - bounds checking is done in jump_table.zig
// Stack order: [..., value, slot] where slot is on top
const popped = frame.stack.pop2_unsafe();
const value = popped.a; // First popped (was second from top)
const slot = popped.b; // Second popped (was top)
try vm.state.set_transient_storage(frame.contract.address, slot, value);
return Operation.ExecutionResult{};
}
```
```zig [src/evm/execution/stack.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
pub fn op_pop(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
_ = try frame.stack.pop();
return Operation.ExecutionResult{};
}
pub fn op_push0(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
try frame.stack.append( 0);
return Operation.ExecutionResult{};
}
// Generate push operations for PUSH1 through PUSH32
pub fn make_push(comptime n: u8) fn (usize, *Operation.Interpreter, *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
return struct {
pub fn push(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size >= Stack.CAPACITY) unreachable;
var value: u256 = 0;
const code = frame.contract.code;
for (0..n) |i| {
if (pc + 1 + i < code.len) {
value = (value << 8) | code[pc + 1 + i];
} else {
value = value << 8;
}
}
frame.stack.append_unsafe(value);
// PUSH operations consume 1 + n bytes
// (1 for the opcode itself, n for the immediate data)
return Operation.ExecutionResult{ .bytes_consumed = 1 + n };
}
}.push;
}
// PUSH operations are now generated directly in jump_table.zig using make_push()
// Generate dup operations
pub fn make_dup(comptime n: u8) fn (usize, *Operation.Interpreter, *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
return struct {
pub fn dup(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < n) unreachable;
if (frame.stack.size >= Stack.CAPACITY) unreachable;
frame.stack.dup_unsafe(n);
return Operation.ExecutionResult{};
}
}.dup;
}
// DUP operations are now generated directly in jump_table.zig using make_dup()
// Generate swap operations
pub fn make_swap(comptime n: u8) fn (usize, *Operation.Interpreter, *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
return struct {
pub fn swap(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
_ = interpreter;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
if (frame.stack.size < n + 1) unreachable;
frame.stack.swapUnsafe(n);
return Operation.ExecutionResult{};
}
}.swap;
}
// SWAP operations are now generated directly in jump_table.zig using make_swap()
```
```zig [src/evm/execution/block.zig]
const std = @import("std");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Frame = @import("../frame.zig");
const Vm = @import("../vm.zig");
const Address = @import("Address");
pub fn op_blockhash(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const block_number = try frame.stack.pop();
const current_block = vm.context.block_number;
if (block_number >= current_block) {
try frame.stack.append( 0);
} else if (current_block > block_number + 256) {
try frame.stack.append( 0);
} else if (block_number == 0) {
try frame.stack.append( 0);
} else {
// Return a pseudo-hash based on block number for testing
// In production, this would retrieve the actual block hash from chain history
const hash = std.hash.Wyhash.hash(0, std.mem.asBytes(&block_number));
try frame.stack.append( hash);
}
return Operation.ExecutionResult{};
}
pub fn op_coinbase(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
try frame.stack.append( Address.to_u256(vm.context.block_coinbase));
return Operation.ExecutionResult{};
}
pub fn op_timestamp(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
try frame.stack.append( @as(u256, @intCast(vm.context.block_timestamp)));
return Operation.ExecutionResult{};
}
pub fn op_number(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
try frame.stack.append( @as(u256, @intCast(vm.context.block_number)));
return Operation.ExecutionResult{};
}
pub fn op_difficulty(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Get difficulty/prevrandao from block context
// Post-merge this returns PREVRANDAO
try frame.stack.append( vm.context.block_difficulty);
return Operation.ExecutionResult{};
}
pub fn op_prevrandao(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
// Same as difficulty post-merge
return op_difficulty(pc, interpreter, state);
}
pub fn op_gaslimit(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
try frame.stack.append( @as(u256, @intCast(vm.context.block_gas_limit)));
return Operation.ExecutionResult{};
}
pub fn op_basefee(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Get base fee from block context
// Push base fee (EIP-1559)
try frame.stack.append( vm.context.block_base_fee);
return Operation.ExecutionResult{};
}
pub fn op_blobhash(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
const index = try frame.stack.pop();
// EIP-4844: Get blob hash at index
if (index >= vm.context.blob_hashes.len) {
try frame.stack.append( 0);
} else {
const idx = @as(usize, @intCast(index));
try frame.stack.append( vm.context.blob_hashes[idx]);
}
return Operation.ExecutionResult{};
}
pub fn op_blobbasefee(pc: usize, interpreter: *Operation.Interpreter, state: *Operation.State) ExecutionError.Error!Operation.ExecutionResult {
_ = pc;
const frame = @as(*Frame, @ptrCast(@alignCast(state)));
const vm = @as(*Vm, @ptrCast(@alignCast(interpreter)));
// Get blob base fee from block context
// Push blob base fee (EIP-4844)
try frame.stack.append( vm.context.blob_base_fee);
return Operation.ExecutionResult{};
}
```
```zig [src/evm/log.zig]
const std = @import("std");
/// Professional isomorphic logger for the EVM that works across all target architectures
/// including native platforms, WASI, and WASM environments. Uses the std_options.logFn
/// system for automatic platform adaptation.
///
/// Provides debug, error, and warning logging with EVM-specific prefixing.
/// Debug logs are optimized away in release builds for performance.
/// Debug log for development and troubleshooting
/// Optimized away in release builds for performance
pub fn debug(comptime format: []const u8, args: anytype) void {
std.log.debug("[EVM] " ++ format, args);
}
/// Error log for critical issues that require attention
pub fn err(comptime format: []const u8, args: anytype) void {
std.log.err("[EVM] " ++ format, args);
}
/// Warning log for non-critical issues and unexpected conditions
pub fn warn(comptime format: []const u8, args: anytype) void {
std.log.warn("[EVM] " ++ format, args);
}
/// Info log for general information (use sparingly for performance)
pub fn info(comptime format: []const u8, args: anytype) void {
std.log.info("[EVM] " ++ format, args);
}
```
```zig [src/evm/hardforks/chain_rules.zig]
const std = @import("std");
const Hardfork = @import("hardfork.zig").Hardfork;
const Log = @import("../log.zig");
/// Configuration for Ethereum protocol rules and EIP activations across hardforks.
///
/// This structure defines which Ethereum Improvement Proposals (EIPs) and protocol
/// rules are active during EVM execution. It serves as the central configuration
/// point for hardfork-specific behavior, enabling the EVM to correctly execute
/// transactions according to the rules of any supported Ethereum hardfork.
///
/// ## Purpose
/// The Ethereum protocol evolves through hardforks that introduce new features,
/// change gas costs, add opcodes, or modify execution semantics. This structure
/// encapsulates all these changes, allowing the EVM to maintain compatibility
/// with any point in Ethereum's history.
///
/// ## Default Configuration
/// By default, all fields are set to support the latest stable hardfork (Cancun),
/// ensuring new deployments get the most recent protocol features. Use the
/// `for_hardfork()` method to configure for specific historical hardforks.
///
/// ## Usage Pattern
/// ```zig
/// // Create rules for a specific hardfork
/// const rules = ChainRules.for_hardfork(.LONDON);
///
/// // Check if specific features are enabled
/// if (rules.IsEIP1559) {
/// // Use EIP-1559 fee market logic
/// }
/// ```
///
/// ## Hardfork Progression
/// The Ethereum mainnet hardfork progression:
/// 1. Frontier (July 2015) - Initial release
/// 2. Homestead (March 2016) - First major improvements
/// 3. DAO Fork (July 2016) - Emergency fork after DAO hack
/// 4. Tangerine Whistle (October 2016) - Gas repricing (EIP-150)
/// 5. Spurious Dragon (November 2016) - State cleaning (EIP-158)
/// 6. Byzantium (October 2017) - Major protocol upgrade
/// 7. Constantinople (February 2019) - Efficiency improvements
/// 8. Petersburg (February 2019) - Constantinople fix
/// 9. Istanbul (December 2019) - Gas cost adjustments
/// 10. Muir Glacier (January 2020) - Difficulty bomb delay
/// 11. Berlin (April 2021) - Gas improvements (EIP-2929)
/// 12. London (August 2021) - EIP-1559 fee market
/// 13. Arrow Glacier (December 2021) - Difficulty bomb delay
/// 14. Gray Glacier (June 2022) - Difficulty bomb delay
/// 15. The Merge (September 2022) - Proof of Stake transition
/// 16. Shanghai (April 2023) - Withdrawals enabled
/// 17. Cancun (March 2024) - Proto-danksharding
///
/// ## Memory Layout
/// This structure uses bool fields for efficient memory usage and fast access.
/// The compiler typically packs multiple bools together for cache efficiency.
const Self = @This();
/// Homestead hardfork activation flag (March 2016).
///
/// ## Key Changes
/// - Fixed critical issues from Frontier release
/// - Introduced DELEGATECALL opcode (0xF4) for library pattern
/// - Changed difficulty adjustment algorithm
/// - Removed canary contracts
/// - Fixed gas cost inconsistencies
///
/// ## EVM Impact
/// - New opcode: DELEGATECALL for code reuse with caller's context
/// - Modified CREATE behavior for out-of-gas scenarios
/// - Changed gas costs for CALL operations
IsHomestead: bool = true,
/// EIP-150 "Tangerine Whistle" hardfork activation (October 2016).
///
/// ## Purpose
/// Addressed denial-of-service attack vectors by repricing operations
/// that were underpriced relative to their computational complexity.
///
/// ## Key Changes
/// - Increased gas costs for EXTCODESIZE, EXTCODECOPY, BALANCE, CALL, CALLCODE, DELEGATECALL
/// - Increased gas costs for SLOAD from 50 to 200
/// - 63/64 rule for CALL operations gas forwarding
/// - Max call depth reduced from 1024 to 1024 (stack-based)
///
/// ## Security Impact
/// Mitigated "Shanghai attacks" that exploited underpriced opcodes
/// to create transactions consuming excessive resources.
IsEIP150: bool = true,
/// EIP-158 "Spurious Dragon" hardfork activation (November 2016).
///
/// ## Purpose
/// State size reduction through removal of empty accounts,
/// complementing EIP-150's gas repricing.
///
/// ## Key Changes
/// - Empty account deletion (nonce=0, balance=0, code empty)
/// - Changed SELFDESTRUCT refund behavior
/// - Introduced EXP cost increase for large exponents
/// - Replay attack protection via chain ID
///
/// ## State Impact
/// Significantly reduced state size by removing ~20 million empty
/// accounts created by previous attacks.
IsEIP158: bool = true,
/// EIP-1559 fee market mechanism activation (London hardfork).
///
/// ## Purpose
/// Revolutionary change to Ethereum's fee mechanism introducing
/// base fee burning and priority fees (tips).
///
/// ## Key Changes
/// - Dynamic base fee adjusted per block based on utilization
/// - Base fee burned, reducing ETH supply
/// - Priority fee (tip) goes to miners/validators
/// - New transaction type (Type 2) with maxFeePerGas and maxPriorityFeePerGas
/// - BASEFEE opcode (0x48) to access current base fee
///
/// ## Economic Impact
/// - More predictable gas prices
/// - ETH becomes deflationary under high usage
/// - Better UX with fee estimation
IsEIP1559: bool = true,
/// Constantinople hardfork activation (February 2019).
///
/// ## Purpose
/// Optimization-focused upgrade adding cheaper operations and
/// preparing for future scaling solutions.
///
/// ## Key Changes
/// - New opcodes: SHL (0x1B), SHR (0x1C), SAR (0x1D) for bitwise shifting
/// - New opcode: EXTCODEHASH (0x3F) for cheaper code hash access
/// - CREATE2 (0xF5) for deterministic contract addresses
/// - Reduced gas costs for SSTORE operations (EIP-1283)
/// - Delayed difficulty bomb by 12 months
///
/// ## Developer Impact
/// - Bitwise operations enable more efficient algorithms
/// - CREATE2 enables counterfactual instantiation patterns
/// - Cheaper storage operations for certain patterns
IsConstantinople: bool = true,
/// Petersburg hardfork activation (February 2019).
///
/// ## Purpose
/// Emergency fix to Constantinople, disabling EIP-1283 due to
/// reentrancy concerns discovered before mainnet deployment.
///
/// ## Key Changes
/// - Removed EIP-1283 (SSTORE gas metering) from Constantinople
/// - Kept all other Constantinople features
/// - Essentially Constantinople minus problematic EIP
///
/// ## Historical Note
/// Constantinople was deployed on testnet but postponed on mainnet
/// when security researchers found the reentrancy issue. Petersburg
/// represents the actually deployed version.
IsPetersburg: bool = true,
/// Istanbul hardfork activation (December 2019).
///
/// ## Purpose
/// Gas cost adjustments based on real-world usage data and addition
/// of new opcodes for layer 2 support.
///
/// ## Key Changes
/// - EIP-152: Blake2b precompile for interoperability
/// - EIP-1108: Reduced alt_bn128 precompile gas costs
/// - EIP-1344: CHAINID opcode (0x46) for replay protection
/// - EIP-1884: Repricing for trie-size dependent opcodes
/// - EIP-2028: Reduced calldata gas cost (16 gas per non-zero byte)
/// - EIP-2200: Rebalanced SSTORE gas cost with stipend
///
/// ## Opcodes Added
/// - CHAINID (0x46): Returns the current chain ID
/// - SELFBALANCE (0x47): Get balance without expensive BALANCE call
///
/// ## Performance Impact
/// Significant reduction in costs for L2 solutions using calldata.
IsIstanbul: bool = true,
/// Berlin hardfork activation (April 2021).
///
/// ## Purpose
/// Major gas model reform introducing access lists and fixing
/// long-standing issues with state access pricing.
///
/// ## Key Changes
/// - EIP-2565: Reduced ModExp precompile gas cost
/// - EIP-2718: Typed transaction envelope framework
/// - EIP-2929: Gas cost increase for state access opcodes
/// - EIP-2930: Optional access lists (Type 1 transactions)
///
/// ## Access List Impact
/// - First-time SLOAD: 2100 gas (cold) vs 100 gas (warm)
/// - First-time account access: 2600 gas (cold) vs 100 gas (warm)
/// - Transactions can pre-declare accessed state for gas savings
///
/// ## Developer Considerations
/// Access lists allow contracts to optimize gas usage by pre-warming
/// storage slots and addresses they'll interact with.
IsBerlin: bool = true,
/// London hardfork activation (August 2021).
///
/// ## Purpose
/// Most significant economic change to Ethereum, introducing base fee
/// burning and dramatically improving fee predictability.
///
/// ## Key Changes
/// - EIP-1559: Fee market reform with base fee burning
/// - EIP-3198: BASEFEE opcode (0x48) to read current base fee
/// - EIP-3529: Reduction in refunds (SELFDESTRUCT, SSTORE)
/// - EIP-3541: Reject contracts starting with 0xEF byte
/// - EIP-3554: Difficulty bomb delay
///
/// ## EIP-3541 Impact
/// Reserves 0xEF prefix for future EVM Object Format (EOF),
/// preventing deployment of contracts with this prefix.
///
/// ## Economic Changes
/// - Base fee burned makes ETH potentially deflationary
/// - Gas price volatility significantly reduced
/// - Better fee estimation and user experience
IsLondon: bool = true,
/// The Merge activation (September 2022).
///
/// ## Purpose
/// Historic transition from Proof of Work to Proof of Stake,
/// reducing energy consumption by ~99.95%.
///
/// ## Key Changes
/// - EIP-3675: Consensus layer transition
/// - EIP-4399: DIFFICULTY (0x44) renamed to PREVRANDAO
/// - Removed block mining rewards
/// - Block time fixed at ~12 seconds
///
/// ## PREVRANDAO Usage
/// The DIFFICULTY opcode now returns the previous block's RANDAO
/// value, providing a source of randomness from the beacon chain.
/// Not suitable for high-security randomness needs.
///
/// ## Network Impact
/// - No more uncle blocks
/// - Predictable block times
/// - Validators replace miners
IsMerge: bool = true,
/// Shanghai hardfork activation (April 2023).
///
/// ## Purpose
/// First major upgrade post-Merge, enabling validator withdrawals
/// and introducing efficiency improvements.
///
/// ## Key Changes
/// - EIP-3651: Warm COINBASE address (reduced gas for MEV)
/// - EIP-3855: PUSH0 opcode (0x5F) for gas efficiency
/// - EIP-3860: Limit and meter initcode size
/// - EIP-4895: Beacon chain withdrawals
///
/// ## PUSH0 Impact
/// New opcode that pushes zero onto stack for 2 gas,
/// replacing common pattern of `PUSH1 0` (3 gas).
///
/// ## Withdrawal Mechanism
/// Validators can finally withdraw staked ETH, completing
/// the Proof of Stake transition.
IsShanghai: bool = true,
/// Cancun hardfork activation (March 2024).
///
/// ## Purpose
/// Major scalability upgrade introducing blob transactions for L2s
/// and transient storage for advanced contract patterns.
///
/// ## Key Changes
/// - EIP-1153: Transient storage opcodes (TLOAD 0x5C, TSTORE 0x5D)
/// - EIP-4844: Proto-danksharding with blob transactions
/// - EIP-4788: Beacon block root in EVM
/// - EIP-5656: MCOPY opcode (0x5E) for memory copying
/// - EIP-6780: SELFDESTRUCT only in same transaction
/// - EIP-7516: BLOBBASEFEE opcode (0x4A)
///
/// ## Blob Transactions
/// New transaction type carrying data blobs (4096 field elements)
/// for L2 data availability at ~10x lower cost.
///
/// ## Transient Storage
/// Storage that persists only within a transaction, enabling
/// reentrancy locks and other patterns without permanent storage.
IsCancun: bool = true,
/// Prague hardfork activation flag (future upgrade).
///
/// ## Status
/// Not yet scheduled or fully specified. Expected to include:
/// - EOF (EVM Object Format) implementation
/// - Account abstraction improvements
/// - Further gas optimizations
///
/// ## Note
/// This flag is reserved for future use and should remain
/// false until Prague specifications are finalized.
IsPrague: bool = false,
/// Verkle trees activation flag (future upgrade).
///
/// ## Purpose
/// Fundamental change to Ethereum's state storage using Verkle trees
/// instead of Merkle Patricia tries for massive witness size reduction.
///
/// ## Expected Benefits
/// - Witness sizes reduced from ~10MB to ~200KB
/// - Enables stateless clients
/// - Improved sync times and network efficiency
///
/// ## Status
/// Under active research and development. Will require extensive
/// testing before mainnet deployment.
IsVerkle: bool = false,
/// Byzantium hardfork activation (October 2017).
///
/// ## Purpose
/// Major protocol upgrade adding privacy features and improving
/// smart contract capabilities.
///
/// ## Key Changes
/// - New opcodes: REVERT (0xFD), RETURNDATASIZE (0x3D), RETURNDATACOPY (0x3E)
/// - New opcode: STATICCALL (0xFA) for read-only calls
/// - Added precompiles for zkSNARK verification (alt_bn128)
/// - Difficulty bomb delay by 18 months
/// - Block reward reduced from 5 to 3 ETH
///
/// ## REVERT Impact
/// Allows contracts to revert with data, enabling better error
/// messages while still refunding remaining gas.
///
/// ## Privacy Features
/// zkSNARK precompiles enable privacy-preserving applications
/// like private transactions and scalability solutions.
IsByzantium: bool = true,
/// EIP-2930 optional access lists activation (Berlin hardfork).
///
/// ## Purpose
/// Introduces Type 1 transactions with optional access lists,
/// allowing senders to pre-declare state they'll access.
///
/// ## Benefits
/// - Mitigates breaking changes from EIP-2929 gas increases
/// - Allows gas savings by pre-warming storage slots
/// - Provides predictable gas costs for complex interactions
///
/// ## Transaction Format
/// Type 1 transactions include an access list of:
/// - Addresses to be accessed
/// - Storage keys per address to be accessed
///
/// ## Gas Savings
/// Pre-declaring access saves ~2000 gas per address and
/// ~2000 gas per storage slot on first access.
IsEIP2930: bool = true,
/// EIP-3198 BASEFEE opcode activation (London hardfork).
///
/// ## Purpose
/// Provides smart contracts access to the current block's base fee,
/// enabling on-chain fee market awareness.
///
/// ## Opcode Details
/// - BASEFEE (0x48): Pushes current block's base fee onto stack
/// - Gas cost: 2 (same as other block context opcodes)
///
/// ## Use Cases
/// - Fee estimation within contracts
/// - Conditional execution based on network congestion
/// - MEV-aware contract patterns
/// - Gas price oracles
///
/// ## Complementary to EIP-1559
/// Essential for contracts to interact properly with the
/// new fee market mechanism.
IsEIP3198: bool = true,
/// EIP-3651 warm COINBASE activation (Shanghai hardfork).
///
/// ## Purpose
/// Pre-warms the COINBASE address (block producer) to reduce gas costs
/// for common patterns, especially in MEV transactions.
///
/// ## Gas Impact
/// - Before: First COINBASE access costs 2600 gas (cold)
/// - After: COINBASE always costs 100 gas (warm)
///
/// ## MEV Considerations
/// Critical for MEV searchers and builders who frequently
/// interact with the block producer address for payments.
///
/// ## Implementation
/// The COINBASE address is added to the warm address set
/// at the beginning of transaction execution.
IsEIP3651: bool = true,
/// EIP-3855 PUSH0 instruction activation (Shanghai hardfork).
///
/// ## Purpose
/// Introduces dedicated opcode for pushing zero onto the stack,
/// optimizing a very common pattern in smart contracts.
///
/// ## Opcode Details
/// - PUSH0 (0x5F): Pushes 0 onto the stack
/// - Gas cost: 2 (base opcode cost)
/// - Replaces: PUSH1 0x00 (costs 3 gas)
///
/// ## Benefits
/// - 33% gas reduction for pushing zero
/// - Smaller bytecode (1 byte vs 2 bytes)
/// - Cleaner assembly code
///
/// ## Usage Statistics
/// Analysis showed ~11% of all PUSH operations push zero,
/// making this a significant optimization.
IsEIP3855: bool = true,
/// EIP-3860 initcode size limit activation (Shanghai hardfork).
///
/// ## Purpose
/// Introduces explicit limits and gas metering for contract creation
/// code to prevent DoS vectors and ensure predictable costs.
///
/// ## Key Limits
/// - Maximum initcode size: 49152 bytes (2x max contract size)
/// - Gas cost: 2 gas per 32-byte word of initcode
///
/// ## Affected Operations
/// - CREATE: Limited initcode size
/// - CREATE2: Limited initcode size
/// - Contract creation transactions
///
/// ## Security Rationale
/// Previously unlimited initcode could cause nodes to consume
/// excessive resources during contract deployment verification.
IsEIP3860: bool = true,
/// EIP-4895 beacon chain withdrawals activation (Shanghai hardfork).
///
/// ## Purpose
/// Enables validators to withdraw staked ETH from the beacon chain
/// to the execution layer, completing the PoS transition.
///
/// ## Mechanism
/// - Withdrawals are processed as system-level operations
/// - Not regular transactions - no gas cost or signature
/// - Automatically credited to withdrawal addresses
/// - Up to 16 withdrawals per block
///
/// ## Validator Operations
/// - Partial withdrawals: Excess balance above 32 ETH
/// - Full withdrawals: Complete exit from validation
///
/// ## Network Impact
/// Completes the Ethereum staking lifecycle, allowing validators
/// to access their staked funds and rewards.
IsEIP4895: bool = true,
/// EIP-4844 proto-danksharding activation (Cancun hardfork).
///
/// ## Purpose
/// Introduces blob-carrying transactions for scalable data availability,
/// reducing L2 costs by ~10-100x through temporary data storage.
///
/// ## Blob Details
/// - Size: 4096 field elements (~125 KB)
/// - Max per block: 6 blobs (~750 KB)
/// - Retention: ~18 days (4096 epochs)
/// - Separate fee market with blob base fee
///
/// ## New Components
/// - Type 3 transactions with blob commitments
/// - KZG commitments for data availability proofs
/// - Blob fee market independent of execution gas
/// - BLOBHASH opcode (0x49) to access blob commitments
///
/// ## L2 Impact
/// Dramatically reduces costs for rollups by providing
/// dedicated data availability layer.
IsEIP4844: bool = true,
/// EIP-1153 transient storage activation (Cancun hardfork).
///
/// ## Purpose
/// Introduces transaction-scoped storage that automatically clears
/// after execution, enabling efficient temporary data patterns.
///
/// ## New Opcodes
/// - TLOAD (0x5C): Load from transient storage
/// - TSTORE (0x5D): Store to transient storage
/// - Gas costs: 100 for TLOAD, 100 for TSTORE
///
/// ## Key Properties
/// - Cleared after each transaction (not persisted)
/// - Reverted on transaction failure
/// - Separate namespace from persistent storage
/// - More gas efficient than SSTORE/SLOAD for temporary data
///
/// ## Use Cases
/// - Reentrancy guards without storage slots
/// - Temporary computation results
/// - Cross-contract communication within transaction
IsEIP1153: bool = true,
/// EIP-5656 MCOPY instruction activation (Cancun hardfork).
///
/// ## Purpose
/// Native memory copying instruction replacing inefficient
/// loop-based implementations in smart contracts.
///
/// ## Opcode Details
/// - MCOPY (0x5E): Copy memory regions
/// - Stack: [dest_offset, src_offset, length]
/// - Gas: 3 + 3 * ceil(length / 32) + memory expansion
///
/// ## Performance Impact
/// - ~10x faster than Solidity's loop-based copying
/// - Reduces bytecode size for memory operations
/// - Critical for data-heavy operations
///
/// ## Common Patterns
/// Optimizes array copying, string manipulation, and
/// data structure operations in smart contracts.
IsEIP5656: bool = true,
/// EIP-3541 contract code prefix restriction (London hardfork).
///
/// ## Purpose
/// Reserves the 0xEF byte prefix for future EVM Object Format (EOF),
/// preventing deployment of contracts with this prefix.
///
/// ## Restrictions
/// - New contracts cannot start with 0xEF byte
/// - Applies to CREATE, CREATE2, and deployment transactions
/// - Existing contracts with 0xEF prefix remain valid
///
/// ## EOF Preparation
/// This reservation enables future introduction of:
/// - Structured contract format with metadata
/// - Separate code and data sections
/// - Static jumps and improved analysis
/// - Versioning for EVM upgrades
///
/// ## Developer Impact
/// Extremely rare in practice as 0xEF was not a valid opcode,
/// making accidental conflicts unlikely.
IsEIP3541: bool = true,
/// Creates a ChainRules configuration for a specific Ethereum hardfork.
///
/// This factory function generates the appropriate set of protocol rules
/// for any supported hardfork, enabling the EVM to execute transactions
/// according to historical consensus rules.
///
/// ## Parameters
/// - `hardfork`: The target hardfork to configure rules for
///
/// ## Returns
/// A fully configured ChainRules instance with all flags set appropriately
/// for the specified hardfork.
///
/// ## Algorithm
/// The function starts with all features enabled (latest hardfork) and then
/// selectively disables features that weren't available at the specified
/// hardfork. This approach ensures new features are automatically included
/// in the latest configuration.
///
/// ## Example
/// ```zig
/// // Configure EVM for London hardfork rules
/// const london_rules = ChainRules.for_hardfork(.LONDON);
///
/// // Configure EVM for historical execution (e.g., replaying old blocks)
/// const byzantium_rules = ChainRules.for_hardfork(.BYZANTIUM);
/// ```
///
/// ## Hardfork Ordering
/// Each hardfork case disables all features introduced after it,
/// maintaining historical accuracy for transaction replay and testing.
/// Mapping of chain rule fields to the hardfork in which they were introduced.
const HardforkRule = struct {
field_name: []const u8,
introduced_in: Hardfork,
};
/// Comptime-generated mapping of all chain rules to their introduction hardforks.
/// This data-driven approach replaces the massive switch statement.
/// Default chain rules for the latest hardfork (CANCUN).
/// Pre-generated at compile time for zero runtime overhead.
pub const DEFAULT = for_hardfork(.DEFAULT);
const HARDFORK_RULES = [_]HardforkRule{
.{ .field_name = "IsHomestead", .introduced_in = .HOMESTEAD },
.{ .field_name = "IsEIP150", .introduced_in = .TANGERINE_WHISTLE },
.{ .field_name = "IsEIP158", .introduced_in = .SPURIOUS_DRAGON },
.{ .field_name = "IsByzantium", .introduced_in = .BYZANTIUM },
.{ .field_name = "IsConstantinople", .introduced_in = .CONSTANTINOPLE },
.{ .field_name = "IsPetersburg", .introduced_in = .PETERSBURG },
.{ .field_name = "IsIstanbul", .introduced_in = .ISTANBUL },
.{ .field_name = "IsBerlin", .introduced_in = .BERLIN },
.{ .field_name = "IsLondon", .introduced_in = .LONDON },
.{ .field_name = "IsMerge", .introduced_in = .MERGE },
.{ .field_name = "IsShanghai", .introduced_in = .SHANGHAI },
.{ .field_name = "IsCancun", .introduced_in = .CANCUN },
// EIPs grouped by their hardfork
.{ .field_name = "IsEIP1559", .introduced_in = .LONDON },
.{ .field_name = "IsEIP2930", .introduced_in = .BERLIN },
.{ .field_name = "IsEIP3198", .introduced_in = .LONDON },
.{ .field_name = "IsEIP3541", .introduced_in = .LONDON },
.{ .field_name = "IsEIP3651", .introduced_in = .SHANGHAI },
.{ .field_name = "IsEIP3855", .introduced_in = .SHANGHAI },
.{ .field_name = "IsEIP3860", .introduced_in = .SHANGHAI },
.{ .field_name = "IsEIP4895", .introduced_in = .SHANGHAI },
.{ .field_name = "IsEIP4844", .introduced_in = .CANCUN },
.{ .field_name = "IsEIP1153", .introduced_in = .CANCUN },
.{ .field_name = "IsEIP5656", .introduced_in = .CANCUN },
};
pub fn for_hardfork(hardfork: Hardfork) Self {
var rules = Self{}; // All fields default to true
// Disable features that were introduced after the target hardfork
inline for (HARDFORK_RULES) |rule| {
if (@intFromEnum(hardfork) < @intFromEnum(rule.introduced_in)) {
@field(rules, rule.field_name) = false;
}
}
return rules;
}
```
```zig [src/evm/hardforks/hardfork.zig]
/// Ethereum hardfork identifiers.
///
/// Hardforks represent protocol upgrades that change EVM behavior,
/// gas costs, or add new features. Each hardfork builds upon the
/// previous ones, maintaining backward compatibility while adding
/// improvements.
///
/// ## Hardfork History
/// The EVM has evolved through multiple hardforks, each addressing
/// specific issues or adding new capabilities:
/// - Early forks focused on security and gas pricing
/// - Later forks added new opcodes and features
/// - Recent forks optimize performance and add L2 support
///
/// ## Using Hardforks
/// Hardforks are primarily used to:
/// - Configure jump tables with correct opcodes
/// - Set appropriate gas costs for operations
/// - Enable/disable features based on fork rules
///
/// Example:
/// ```zig
/// const table = JumpTable.init_from_hardfork(.CANCUN);
/// const is_berlin_plus = @intFromEnum(hardfork) >= @intFromEnum(Hardfork.BERLIN);
/// ```
pub const Hardfork = enum {
/// Original Ethereum launch (July 2015).
/// Base EVM with fundamental opcodes.
FRONTIER,
/// First planned hardfork (March 2016).
/// Added DELEGATECALL and fixed critical issues.
HOMESTEAD,
/// Emergency fork for DAO hack (July 2016).
/// No EVM changes, only state modifications.
DAO,
/// Gas repricing fork (October 2016).
/// EIP-150: Increased gas costs for IO-heavy operations.
TANGERINE_WHISTLE,
/// State cleaning fork (November 2016).
/// EIP-161: Removed empty accounts.
SPURIOUS_DRAGON,
/// Major feature fork (October 2017).
/// Added REVERT, RETURNDATASIZE, RETURNDATACOPY, STATICCALL.
BYZANTIUM,
/// Efficiency improvements (February 2019).
/// Added CREATE2, shift opcodes, EXTCODEHASH.
CONSTANTINOPLE,
/// Quick fix fork (February 2019).
/// Removed EIP-1283 due to reentrancy concerns.
PETERSBURG,
/// Gas optimization fork (December 2019).
/// EIP-2200: Rebalanced SSTORE costs.
/// Added CHAINID and SELFBALANCE.
ISTANBUL,
/// Difficulty bomb delay (January 2020).
/// No EVM changes.
MUIR_GLACIER,
/// Access list fork (April 2021).
/// EIP-2929: Gas cost for cold/warm access.
/// EIP-2930: Optional access lists.
BERLIN,
/// Fee market reform (August 2021).
/// EIP-1559: Base fee and new transaction types.
/// Added BASEFEE opcode.
LONDON,
/// Difficulty bomb delay (December 2021).
/// No EVM changes.
ARROW_GLACIER,
/// Difficulty bomb delay (June 2022).
/// No EVM changes.
GRAY_GLACIER,
/// Proof of Stake transition (September 2022).
/// Replaced DIFFICULTY with PREVRANDAO.
MERGE,
/// Withdrawal enabling fork (April 2023).
/// EIP-3855: PUSH0 opcode.
SHANGHAI,
/// Proto-danksharding fork (March 2024).
/// EIP-4844: Blob transactions.
/// EIP-1153: Transient storage (TLOAD/TSTORE).
/// EIP-5656: MCOPY opcode.
CANCUN,
/// Default hardfork for new chains.
/// Set to latest stable fork (currently CANCUN).
pub const DEFAULT = Hardfork.CANCUN;
};
```
```zig [src/evm/memory.zig]
const std = @import("std");
const Log = @import("log.zig");
/// Memory implementation for EVM execution contexts.
const Self = @This();
pub const MemoryError = error{
OutOfMemory,
InvalidOffset,
InvalidSize,
MemoryLimitExceeded,
};
/// Calculate number of 32-byte words needed for byte length (rounds up)
pub fn calculate_num_words(len: usize) usize {
return (len + 31) / 32;
}
shared_buffer: std.ArrayList(u8),
allocator: std.mem.Allocator,
my_checkpoint: usize,
memory_limit: u64,
root_ptr: *Self,
pub const InitialCapacity: usize = 4 * 1024;
pub const DefaultMemoryLimit: u64 = 32 * 1024 * 1024; // 32 MB
/// Initializes the root Memory context. This instance owns the shared_buffer.
/// The caller must ensure the returned Memory is stored at a stable address
/// and call finalize_root() before use.
pub fn init(
allocator: std.mem.Allocator,
initial_capacity: usize,
memory_limit: u64,
) !Self {
Log.debug("Memory.init: Initializing memory, initial_capacity={}, memory_limit={}", .{ initial_capacity, memory_limit });
var shared_buffer = std.ArrayList(u8).init(allocator);
errdefer shared_buffer.deinit();
try shared_buffer.ensureTotalCapacity(initial_capacity);
Log.debug("Memory.init: Memory initialized successfully", .{});
return Self{
.shared_buffer = shared_buffer,
.allocator = allocator,
.my_checkpoint = 0,
.memory_limit = memory_limit,
.root_ptr = undefined,
};
}
/// Finalizes the root Memory by setting root_ptr to itself.
/// Must be called after init() and the Memory is stored at its final address.
pub fn finalize_root(self: *Self) void {
Log.debug("Memory.finalize_root: Finalizing root memory pointer", .{});
self.root_ptr = self;
}
pub fn init_default(allocator: std.mem.Allocator) !Self {
return try init(allocator, InitialCapacity, DefaultMemoryLimit);
}
/// Deinitializes the shared_buffer. Should ONLY be called on the root Memory instance.
pub fn deinit(self: *Self) void {
if (self.my_checkpoint == 0 and self.root_ptr == self) {
Log.debug("Memory.deinit: Deinitializing root memory, buffer_size={}", .{self.shared_buffer.items.len});
self.shared_buffer.deinit();
} else {
Log.debug("Memory.deinit: Skipping deinit for non-root memory context, checkpoint={}", .{self.my_checkpoint});
}
}
/// Returns the size of the memory region visible to the current context.
pub fn context_size(self: *const Self) usize {
const total_len = self.root_ptr.shared_buffer.items.len;
if (total_len < self.my_checkpoint) {
// This indicates a bug or inconsistent state
return 0;
}
return total_len - self.my_checkpoint;
}
/// Ensures the current context's memory region is at least `min_context_size` bytes.
/// Returns the number of *new 32-byte words added to the shared_buffer* if it expanded.
/// This is crucial for EVM gas calculation.
pub fn ensure_context_capacity(self: *Self, min_context_size: usize) MemoryError!u64 {
const required_total_len = self.my_checkpoint + min_context_size;
Log.debug("Memory.ensure_context_capacity: Ensuring capacity, min_context_size={}, required_total_len={}, memory_limit={}", .{ min_context_size, required_total_len, self.memory_limit });
if (required_total_len > self.memory_limit) {
Log.debug("Memory.ensure_context_capacity: Memory limit exceeded, required={}, limit={}", .{ required_total_len, self.memory_limit });
return MemoryError.MemoryLimitExceeded;
}
const root = self.root_ptr;
const old_total_buffer_len = root.shared_buffer.items.len;
const old_total_words = calculate_num_words(old_total_buffer_len);
if (required_total_len <= old_total_buffer_len) {
// Buffer is already large enough
Log.debug("Memory.ensure_context_capacity: Buffer already large enough, no expansion needed", .{});
return 0;
}
// Resize the buffer
const new_total_len = required_total_len;
Log.debug("Memory.ensure_context_capacity: Expanding buffer from {} to {} bytes", .{ old_total_buffer_len, new_total_len });
if (new_total_len > root.shared_buffer.capacity) {
var new_capacity = root.shared_buffer.capacity;
if (new_capacity == 0) new_capacity = 1; // Handle initial zero capacity
while (new_capacity < new_total_len) {
const doubled = @mulWithOverflow(new_capacity, 2);
if (doubled[1] != 0) {
// Overflow occurred
return MemoryError.OutOfMemory;
}
new_capacity = doubled[0];
}
// Ensure new_capacity doesn't exceed memory_limit
if (new_capacity > self.memory_limit and self.memory_limit <= std.math.maxInt(usize)) {
new_capacity = @intCast(self.memory_limit);
}
if (new_total_len > new_capacity) return MemoryError.MemoryLimitExceeded;
try root.shared_buffer.ensureTotalCapacity(new_capacity);
}
// Set new length and zero-initialize the newly added part
root.shared_buffer.items.len = new_total_len;
@memset(root.shared_buffer.items[old_total_buffer_len..new_total_len], 0);
const new_total_words = calculate_num_words(new_total_len);
const words_added = if (new_total_words > old_total_words) new_total_words - old_total_words else 0;
Log.debug("Memory.ensure_context_capacity: Expansion complete, old_words={}, new_words={}, words_added={}", .{ old_total_words, new_total_words, words_added });
return words_added;
}
/// Read 32 bytes as u256 at context-relative offset.
pub fn get_u256(self: *const Self, relative_offset: usize) MemoryError!u256 {
Log.debug("Memory.get_u256: Reading u256 at relative_offset={}, context_size={}", .{ relative_offset, self.context_size() });
if (relative_offset + 32 > self.context_size()) {
Log.debug("Memory.get_u256: Invalid offset, offset+32={} > context_size={}", .{ relative_offset + 32, self.context_size() });
return MemoryError.InvalidOffset;
}
const abs_offset = self.my_checkpoint + relative_offset;
const bytes = self.root_ptr.shared_buffer.items[abs_offset .. abs_offset + 32];
// Convert big-endian bytes to u256
var value: u256 = 0;
for (bytes) |byte| {
value = (value << 8) | byte;
}
Log.debug("Memory.get_u256: Read value={} from offset={}", .{ value, relative_offset });
return value;
}
/// Read arbitrary slice of memory at context-relative offset.
pub fn get_slice(self: *const Self, relative_offset: usize, len: usize) MemoryError![]const u8 {
Log.debug("Memory.get_slice: Reading slice at relative_offset={}, len={}", .{ relative_offset, len });
if (len == 0) return &[_]u8{};
const end = std.math.add(usize, relative_offset, len) catch {
Log.debug("Memory.get_slice: Invalid size overflow, offset={}, len={}", .{ relative_offset, len });
return MemoryError.InvalidSize;
};
if (end > self.context_size()) {
Log.debug("Memory.get_slice: Invalid offset, end={} > context_size={}", .{ end, self.context_size() });
return MemoryError.InvalidOffset;
}
const abs_offset = self.my_checkpoint + relative_offset;
const abs_end = abs_offset + len;
Log.debug("Memory.get_slice: Returning slice [{}..{}]", .{ abs_offset, abs_end });
return self.root_ptr.shared_buffer.items[abs_offset..abs_end];
}
/// Write arbitrary data at context-relative offset.
pub fn set_data(self: *Self, relative_offset: usize, data: []const u8) MemoryError!void {
Log.debug("Memory.set_data: Writing data at relative_offset={}, data_len={}", .{ relative_offset, data.len });
if (data.len == 0) return;
const end = std.math.add(usize, relative_offset, data.len) catch {
Log.debug("Memory.set_data: Invalid size overflow, offset={}, data_len={}", .{ relative_offset, data.len });
return MemoryError.InvalidSize;
};
_ = try self.ensure_context_capacity(end);
const abs_offset = self.my_checkpoint + relative_offset;
const abs_end = abs_offset + data.len;
Log.debug("Memory.set_data: Writing to buffer [{}..{}]", .{ abs_offset, abs_end });
@memcpy(self.root_ptr.shared_buffer.items[abs_offset..abs_end], data);
}
/// Write data with source offset and length (handles partial copies and zero-fills).
pub fn set_data_bounded(
self: *Self,
relative_memory_offset: usize,
data: []const u8,
data_offset: usize,
len: usize,
) MemoryError!void {
if (len == 0) return;
const end = std.math.add(usize, relative_memory_offset, len) catch return MemoryError.InvalidSize;
_ = try self.ensure_context_capacity(end);
const abs_offset = self.my_checkpoint + relative_memory_offset;
const abs_end = abs_offset + len;
// If source offset is beyond data bounds, fill with zeros
if (data_offset >= data.len) {
@memset(self.root_ptr.shared_buffer.items[abs_offset..abs_end], 0);
return;
}
// Calculate how much we can actually copy
const data_end = @min(data_offset + len, data.len);
const copy_len = data_end - data_offset;
// Copy available data
if (copy_len > 0) {
@memcpy(
self.root_ptr.shared_buffer.items[abs_offset .. abs_offset + copy_len],
data[data_offset..data_end],
);
}
// Zero-fill the rest
if (copy_len < len) {
@memset(self.root_ptr.shared_buffer.items[abs_offset + copy_len .. abs_end], 0);
}
}
/// Get total size of memory (context size)
pub fn total_size(self: *const Self) usize {
return self.context_size();
}
/// Get a mutable slice to the entire memory buffer (context-relative)
pub fn slice(self: *Self) []u8 {
const ctx_size = self.context_size();
const abs_start = self.my_checkpoint;
const abs_end = abs_start + ctx_size;
return self.root_ptr.shared_buffer.items[abs_start..abs_end];
}
/// Read a single byte at context-relative offset (for test compatibility)
pub fn get_byte(self: *const Self, relative_offset: usize) MemoryError!u8 {
if (relative_offset >= self.context_size()) return MemoryError.InvalidOffset;
const abs_offset = self.my_checkpoint + relative_offset;
return self.root_ptr.shared_buffer.items[abs_offset];
}
/// Resize the context to the specified size (for test compatibility)
pub fn resize_context(self: *Self, new_size: usize) MemoryError!void {
_ = try self.ensure_context_capacity(new_size);
}
/// Get the memory size (alias for context_size for test compatibility)
pub fn size(self: *const Self) usize {
return self.context_size();
}
/// Write u256 value at context-relative offset (for test compatibility)
pub fn set_u256(self: *Self, relative_offset: usize, value: u256) MemoryError!void {
Log.debug("Memory.set_u256: Writing u256 value={} at relative_offset={}", .{ value, relative_offset });
_ = try self.ensure_context_capacity(relative_offset + 32);
const abs_offset = self.my_checkpoint + relative_offset;
// Convert u256 to big-endian bytes
var bytes: [32]u8 = undefined;
var val = value;
var i: usize = 32;
while (i > 0) {
i -= 1;
bytes[i] = @intCast(val & 0xFF);
val >>= 8;
}
Log.debug("Memory.set_u256: Writing bytes to buffer at abs_offset={}", .{abs_offset});
@memcpy(self.root_ptr.shared_buffer.items[abs_offset..abs_offset + 32], &bytes);
}
```
```zig [src/evm/stack/stack_validation.zig]
const std = @import("std");
const Stack = @import("stack.zig");
const Operation = @import("../opcodes/operation.zig");
const ExecutionError = @import("../execution/execution_error.zig");
const Log = @import("../log.zig");
/// Stack validation utilities for EVM operations.
///
/// This module provides validation functions to ensure stack operations
/// will succeed before attempting them. This is crucial for:
/// - Preventing execution errors
/// - Enabling optimized unsafe operations after validation
/// - Maintaining EVM correctness
///
/// ## Validation Strategy
/// The EVM uses two-phase validation:
/// 1. Pre-execution validation (this module)
/// 2. Unsafe operations after validation passes
///
/// This allows opcodes to use fast unsafe operations in hot paths
/// while maintaining safety guarantees.
///
/// ## Stack Limits
/// The EVM enforces strict stack limits:
/// - Maximum depth: 1024 elements
/// - Underflow: Cannot pop from empty stack
/// - Overflow: Cannot exceed maximum depth
pub const ValidationPatterns = @import("validation_patterns.zig");
/// Validates stack requirements using Operation metadata.
///
/// Each EVM operation has min_stack and max_stack requirements:
/// - min_stack: Minimum elements needed on stack
/// - max_stack: Maximum allowed before operation (to prevent overflow)
///
/// @param stack The stack to validate
/// @param operation The operation with stack requirements
/// @throws StackUnderflow if stack has fewer than min_stack elements
/// @throws StackOverflow if stack has more than max_stack elements
///
/// Example:
/// ```zig
/// // Validate before executing an opcode
/// try validate_stack_requirements(&frame.stack, &operation);
/// // Safe to use unsafe operations now
/// operation.execute(&frame);
/// ```
pub fn validate_stack_requirements(
stack: *const Stack,
operation: *const Operation,
) ExecutionError.Error!void {
const stack_size = stack.size;
Log.debug("StackValidation.validate_stack_requirements: Validating stack, size={}, min_required={}, max_allowed={}", .{ stack_size, operation.min_stack, operation.max_stack });
// Check minimum stack requirement
if (stack_size < operation.min_stack) {
Log.debug("StackValidation.validate_stack_requirements: Stack underflow, size={} < min_stack={}", .{ stack_size, operation.min_stack });
return ExecutionError.Error.StackUnderflow;
}
// Check maximum stack requirement
// max_stack represents the maximum stack size allowed BEFORE the operation
// to ensure we don't overflow after the operation completes
if (stack_size > operation.max_stack) {
Log.debug("StackValidation.validate_stack_requirements: Stack overflow, size={} > max_stack={}", .{ stack_size, operation.max_stack });
return ExecutionError.Error.StackOverflow;
}
Log.debug("StackValidation.validate_stack_requirements: Validation passed", .{});
}
/// Validates stack has capacity for pop/push operations.
///
/// More flexible than validate_stack_requirements, this function
/// validates arbitrary pop/push counts. Used by:
/// - Dynamic operations (e.g., LOG with variable topics)
/// - Custom validation logic
/// - Testing and debugging
///
/// @param stack The stack to validate
/// @param pop_count Number of elements to pop
/// @param push_count Number of elements to push
/// @throws StackUnderflow if stack has < pop_count elements
/// @throws StackOverflow if operation would exceed capacity
///
/// Example:
/// ```zig
/// // Validate LOG3 operation (pops 5, pushes 0)
/// try validate_stack_operation(&stack, 5, 0);
/// ```
pub fn validate_stack_operation(
stack: *const Stack,
pop_count: u32,
push_count: u32,
) ExecutionError.Error!void {
const stack_size = stack.size;
Log.debug("StackValidation.validate_stack_operation: Validating operation, stack_size={}, pop_count={}, push_count={}", .{ stack_size, pop_count, push_count });
// Check if we have enough items to pop
if (stack_size < pop_count) {
Log.debug("StackValidation.validate_stack_operation: Stack underflow, size={} < pop_count={}", .{ stack_size, pop_count });
return ExecutionError.Error.StackUnderflow;
}
// Calculate stack size after operation
const new_size = stack_size - pop_count + push_count;
// Check if result would overflow
if (new_size > Stack.CAPACITY) {
Log.debug("StackValidation.validate_stack_operation: Stack overflow, new_size={} > capacity={}", .{ new_size, Stack.CAPACITY });
return ExecutionError.Error.StackOverflow;
}
Log.debug("StackValidation.validate_stack_operation: Validation passed, new_size={}", .{new_size});
}
/// Calculate the maximum allowed stack size for an operation.
///
/// The max_stack value ensures that after an operation completes,
/// the stack won't exceed capacity. This is calculated as:
/// - If operation grows stack: CAPACITY - net_growth
/// - If operation shrinks/neutral: CAPACITY
///
/// @param pop_count Number of elements operation pops
/// @param push_count Number of elements operation pushes
/// @return Maximum allowed stack size before operation
///
/// Example:
/// ```zig
/// // PUSH1 operation (pop 0, push 1)
/// const max = calculate_max_stack(0, 1); // Returns 1023
/// // Stack must have <= 1023 elements before PUSH1
/// ```
pub fn calculate_max_stack(pop_count: u32, push_count: u32) u32 {
if (push_count > pop_count) {
const net_growth = push_count - pop_count;
return @intCast(Stack.CAPACITY - net_growth);
}
// If operation reduces stack or is neutral, max is CAPACITY
return Stack.CAPACITY;
}
// Tests
const testing = std.testing;
test "validate_stack_requirements" {
var stack = Stack{};
// Test underflow
const op_needs_2 = Operation{
.execute = undefined,
.constant_gas = 3,
.min_stack = 2,
.max_stack = Stack.CAPACITY - 1,
};
try testing.expectError(ExecutionError.Error.StackUnderflow, validate_stack_requirements(&stack, &op_needs_2));
// Add items and test success
try stack.append(1);
try stack.append(2);
try validate_stack_requirements(&stack, &op_needs_2);
// Test overflow
const op_max_10 = Operation{
.execute = undefined,
.constant_gas = 3,
.min_stack = 0,
.max_stack = 10,
};
// Fill stack beyond max_stack
var i: usize = 2;
while (i < 11) : (i += 1) {
try stack.append(@intCast(i));
}
try testing.expectError(ExecutionError.Error.StackOverflow, validate_stack_requirements(&stack, &op_max_10));
}
test "validate_stack_operation" {
var stack = Stack{};
// Test underflow
try testing.expectError(ExecutionError.Error.StackUnderflow, validate_stack_operation(&stack, 2, 1));
// Add items
try stack.append(10);
try stack.append(20);
// Binary op should succeed
try validate_stack_operation(&stack, 2, 1);
// Test overflow - fill stack almost to capacity
stack.size = Stack.CAPACITY - 1;
// Operation that would overflow
try testing.expectError(ExecutionError.Error.StackOverflow, validate_stack_operation(&stack, 0, 2));
}
test "calculate_max_stack" {
// Binary operations (pop 2, push 1) - net decrease of 1
try testing.expectEqual(@as(u32, Stack.CAPACITY), calculate_max_stack(2, 1));
// Push operations (pop 0, push 1) - net increase of 1
try testing.expectEqual(@as(u32, Stack.CAPACITY - 1), calculate_max_stack(0, 1));
// DUP operations (pop 0, push 1) - net increase of 1
try testing.expectEqual(@as(u32, Stack.CAPACITY - 1), calculate_max_stack(0, 1));
// Operations that push more than pop
try testing.expectEqual(@as(u32, Stack.CAPACITY - 3), calculate_max_stack(1, 4));
}
test "ValidationPatterns" {
var stack = Stack{};
// Test binary op validation
try testing.expectError(ExecutionError.Error.StackUnderflow, ValidationPatterns.validate_binary_op(&stack));
try stack.append(1);
try stack.append(2);
try ValidationPatterns.validate_binary_op(&stack);
// Test DUP validation
try testing.expectError(ExecutionError.Error.StackUnderflow, ValidationPatterns.validate_dup(&stack, 3));
try ValidationPatterns.validate_dup(&stack, 2);
// Test SWAP validation
try testing.expectError(ExecutionError.Error.StackUnderflow, ValidationPatterns.validate_swap(&stack, 2));
try ValidationPatterns.validate_swap(&stack, 1);
// Test PUSH validation at capacity
stack.size = Stack.CAPACITY;
try testing.expectError(ExecutionError.Error.StackOverflow, ValidationPatterns.validate_push(&stack));
}
```
```zig [src/evm/stack/stack.zig]
const std = @import("std");
const Log = @import("../log.zig");
/// High-performance EVM stack implementation with fixed capacity.
///
/// The Stack is a core component of the EVM execution model, providing a
/// Last-In-First-Out (LIFO) data structure for 256-bit values. All EVM
/// computations operate on this stack, making its performance critical.
///
/// ## Design Rationale
/// - Fixed capacity of 1024 elements (per EVM specification)
/// - 32-byte alignment for optimal memory access on modern CPUs
/// - Unsafe variants skip bounds checking in hot paths for performance
///
/// ## Performance Optimizations
/// - Aligned memory for SIMD-friendly access patterns
/// - Unsafe variants used after jump table validation
/// - Direct memory access patterns for maximum speed
///
/// ## Safety Model
/// Operations are validated at the jump table level, allowing individual
/// opcodes to use faster unsafe operations without redundant bounds checking.
///
/// Example:
/// ```zig
/// var stack = Stack{};
/// try stack.append(100); // Safe variant (for error_mapping)
/// stack.append_unsafe(200); // Unsafe variant (for opcodes)
/// ```
const Self = @This();
/// Maximum stack capacity as defined by the EVM specification.
/// This limit prevents stack-based DoS attacks.
pub const CAPACITY: usize = 1024;
/// Error types for stack operations.
/// These map directly to EVM execution errors.
pub const Error = error{
/// Stack would exceed 1024 elements
StackOverflow,
/// Attempted to pop from empty stack
StackUnderflow,
};
/// Stack storage aligned to 32-byte boundaries.
/// Alignment improves performance on modern CPUs by:
/// - Enabling SIMD operations
/// - Reducing cache line splits
/// - Improving memory prefetching
data: [CAPACITY]u256 align(32) = [_]u256{0} ** CAPACITY,
/// Current number of elements on the stack.
/// Invariant: 0 <= size <= CAPACITY
size: usize = 0,
/// Push a value onto the stack (safe version).
///
/// @param self The stack to push onto
/// @param value The 256-bit value to push
/// @throws Overflow if stack is at capacity
///
/// Example:
/// ```zig
/// try stack.append(0x1234);
/// ```
pub fn append(self: *Self, value: u256) Error!void {
if (self.size >= CAPACITY) {
Log.debug("Stack.append: Stack overflow, size={}, capacity={}", .{ self.size, CAPACITY });
return Error.StackOverflow;
}
Log.debug("Stack.append: Pushing value={}, new_size={}", .{ value, self.size + 1 });
self.data[self.size] = value;
self.size += 1;
}
/// Push a value onto the stack (unsafe version).
///
/// Caller must ensure stack has capacity. Used in hot paths
/// after validation has already been performed.
///
/// @param self The stack to push onto
/// @param value The 256-bit value to push
pub fn append_unsafe(self: *Self, value: u256) void {
@branchHint(.likely); // We generally only use unsafe methods
self.data[self.size] = value;
self.size += 1;
}
/// Pop a value from the stack (safe version).
///
/// Removes and returns the top element. Clears the popped
/// slot to prevent information leakage.
///
/// @param self The stack to pop from
/// @return The popped value
/// @throws Underflow if stack is empty
///
/// Example:
/// ```zig
/// const value = try stack.pop();
/// ```
pub fn pop(self: *Self) Error!u256 {
if (self.size == 0) {
Log.debug("Stack.pop: Stack underflow, size=0", .{});
return Error.StackUnderflow;
}
self.size -= 1;
const value = self.data[self.size];
self.data[self.size] = 0;
Log.debug("Stack.pop: Popped value={}, new_size={}", .{ value, self.size });
return value;
}
/// Pop a value from the stack (unsafe version).
///
/// Caller must ensure stack is not empty. Used in hot paths
/// after validation.
///
/// @param self The stack to pop from
/// @return The popped value
pub fn pop_unsafe(self: *Self) u256 {
@branchHint(.likely);
self.size -= 1;
const value = self.data[self.size];
self.data[self.size] = 0;
return value;
}
/// Peek at the top value without removing it (unsafe version).
///
/// Caller must ensure stack is not empty.
///
/// @param self The stack to peek at
/// @return Pointer to the top value
pub fn peek_unsafe(self: *const Self) *const u256 {
@branchHint(.likely);
return &self.data[self.size - 1];
}
/// Duplicate the nth element onto the top of stack (unsafe version).
///
/// Caller must ensure preconditions are met.
///
/// @param self The stack to operate on
/// @param n Position to duplicate from (1-16)
pub fn dup_unsafe(self: *Self, n: usize) void {
@branchHint(.likely);
@setRuntimeSafety(false);
self.append_unsafe(self.data[self.size - n]);
}
/// Pop 2 values without pushing (unsafe version)
pub fn pop2_unsafe(self: *Self) struct { a: u256, b: u256 } {
@branchHint(.likely); // We generally only use unsafe methods
@setRuntimeSafety(false);
self.size -= 2;
return .{
.a = self.data[self.size],
.b = self.data[self.size + 1],
};
}
/// Pop 3 values without pushing (unsafe version)
pub fn pop3_unsafe(self: *Self) struct { a: u256, b: u256, c: u256 } {
@branchHint(.likely); // We generally only use unsafe methods
@setRuntimeSafety(false);
self.size -= 3;
return .{
.a = self.data[self.size],
.b = self.data[self.size + 1],
.c = self.data[self.size + 2],
};
}
pub fn set_top_unsafe(self: *Self, value: u256) void {
@branchHint(.likely); // We generally only use unsafe methods
// Assumes stack is not empty; this should be guaranteed by jump_table validation
// for opcodes that use this pattern (e.g., after a pop and peek on a stack with >= 2 items).
self.data[self.size - 1] = value;
}
/// CamelCase alias used by existing execution code
pub fn swapUnsafe(self: *Self, n: usize) void {
@branchHint(.likely);
std.mem.swap(u256, &self.data[self.size - 1], &self.data[self.size - n - 1]);
}
/// Peek at the nth element from the top (for test compatibility)
pub fn peek_n(self: *const Self, n: usize) Error!u256 {
if (n >= self.size) {
return Error.StackUnderflow;
}
return self.data[self.size - 1 - n];
}
/// Clear the stack (for test compatibility)
pub fn clear(self: *Self) void {
self.size = 0;
// Zero out the data for security
@memset(&self.data, 0);
}
/// Peek at the top value (for test compatibility)
pub fn peek(self: *const Self) Error!u256 {
if (self.size == 0) {
return Error.StackUnderflow;
}
return self.data[self.size - 1];
}```
```zig [src/evm/stack/validation_patterns.zig]
const Stack = @import("stack.zig");
const ExecutionError = @import("../execution/execution_error.zig");
const Log = @import("../log.zig");
/// Common validation patterns for EVM stack operations.
///
/// This module provides optimized validation functions for frequently used
/// stack operation patterns in the EVM. These functions check stack requirements
/// before operations execute, preventing stack underflow/overflow errors.
///
/// ## Design Philosophy
/// Rather than repeating validation logic across opcodes, these functions
/// encapsulate common patterns:
/// - Binary operations: pop 2, push 1 (ADD, MUL, SUB, etc.)
/// - Ternary operations: pop 3, push 1 (ADDMOD, MULMOD, etc.)
/// - Comparison operations: pop 2, push 1 (LT, GT, EQ, etc.)
/// - Unary operations: pop 1, push 1 (NOT, ISZERO, etc.)
///
/// ## Performance
/// These validation functions are designed to be inlined by the compiler,
/// making them zero-cost abstractions over direct validation code.
const Self = @This();
/// Validates stack requirements for binary operations.
///
/// Binary operations consume two stack items and produce one result.
/// This pattern is used by arithmetic operations like ADD, MUL, SUB, DIV,
/// and bitwise operations like AND, OR, XOR.
///
/// @param stack The stack to validate
/// @return Error if stack has fewer than 2 items or would overflow
///
/// Example:
/// ```zig
/// // Before ADD operation
/// try validate_binary_op(&frame.stack);
/// const b = frame.stack.pop();
/// const a = frame.stack.pop();
/// frame.stack.push(a + b);
/// ```
pub fn validate_binary_op(stack: *const Stack) ExecutionError.Error!void {
return validate_stack_operation(stack, 2, 1);
}
/// Validates stack requirements for ternary operations.
///
/// Ternary operations consume three stack items and produce one result.
/// This pattern is used by operations like ADDMOD and MULMOD which
/// perform modular arithmetic.
///
/// @param stack The stack to validate
/// @return Error if stack has fewer than 3 items or would overflow
///
/// Example:
/// ```zig
/// // Before ADDMOD operation: (a + b) % n
/// try validate_ternary_op(&frame.stack);
/// const n = frame.stack.pop();
/// const b = frame.stack.pop();
/// const a = frame.stack.pop();
/// frame.stack.push((a + b) % n);
/// ```
pub fn validate_ternary_op(stack: *const Stack) ExecutionError.Error!void {
return validate_stack_operation(stack, 3, 1);
}
/// Validates stack requirements for comparison operations.
///
/// Comparison operations consume two stack items and produce one boolean
/// result (0 or 1). This includes LT, GT, SLT, SGT, and EQ operations.
///
/// @param stack The stack to validate
/// @return Error if stack has fewer than 2 items or would overflow
///
/// Note: This is functionally identical to validate_binary_op but exists
/// as a separate function for semantic clarity and potential future
/// specialization.
pub fn validate_comparison_op(stack: *const Stack) ExecutionError.Error!void {
return validate_stack_operation(stack, 2, 1);
}
/// Validates stack requirements for unary operations.
///
/// Unary operations consume one stack item and produce one result.
/// This pattern is used by operations like NOT, ISZERO, and SIGNEXTEND.
///
/// @param stack The stack to validate
/// @return Error if stack is empty or would overflow
///
/// Example:
/// ```zig
/// // Before ISZERO operation
/// try validate_unary_op(&frame.stack);
/// const value = frame.stack.pop();
/// frame.stack.push(if (value == 0) 1 else 0);
/// ```
pub fn validate_unary_op(stack: *const Stack) ExecutionError.Error!void {
return validate_stack_operation(stack, 1, 1);
}
/// Validates stack requirements for DUP operations.
///
/// DUP operations duplicate the nth stack item, pushing a copy onto the top.
/// They consume no items but add one, so the stack must have:
/// - At least n items to duplicate from
/// - Room for one more item
///
/// @param stack The stack to validate
/// @param n The position to duplicate from (1-based, DUP1 duplicates top item)
/// @return StackUnderflow if fewer than n items, StackOverflow if full
///
/// Example:
/// ```zig
/// // DUP3 operation
/// try validate_dup(&frame.stack, 3);
/// const value = frame.stack.peek(2); // 0-based indexing
/// frame.stack.push(value);
/// ```
pub fn validate_dup(stack: *const Stack, n: u32) ExecutionError.Error!void {
Log.debug("ValidationPatterns.validate_dup: Validating DUP{}, stack_size={}", .{ n, stack.size });
// DUP pops 0 and pushes 1
if (stack.size < n) {
Log.debug("ValidationPatterns.validate_dup: Stack underflow, size={} < n={}", .{ stack.size, n });
return ExecutionError.Error.StackUnderflow;
}
if (stack.size >= Stack.CAPACITY) {
Log.debug("ValidationPatterns.validate_dup: Stack overflow, size={} >= capacity={}", .{ stack.size, Stack.CAPACITY });
return ExecutionError.Error.StackOverflow;
}
Log.debug("ValidationPatterns.validate_dup: Validation passed", .{});
}
/// Validates stack requirements for SWAP operations.
///
/// SWAP operations exchange the top stack item with the (n+1)th item.
/// They don't change the stack size, but require at least n+1 items.
///
/// @param stack The stack to validate
/// @param n The position to swap with (1-based, SWAP1 swaps top two items)
/// @return StackUnderflow if stack has n or fewer items
///
/// Example:
/// ```zig
/// // SWAP2 operation swaps top with 3rd item
/// try validate_swap(&frame.stack, 2);
/// frame.stack.swap(2);
/// ```
pub fn validate_swap(stack: *const Stack, n: u32) ExecutionError.Error!void {
Log.debug("ValidationPatterns.validate_swap: Validating SWAP{}, stack_size={}", .{ n, stack.size });
// SWAP needs at least n+1 items on stack
if (stack.size <= n) {
Log.debug("ValidationPatterns.validate_swap: Stack underflow, size={} <= n={}", .{ stack.size, n });
return ExecutionError.Error.StackUnderflow;
}
Log.debug("ValidationPatterns.validate_swap: Validation passed", .{});
}
/// Validates stack requirements for PUSH operations.
///
/// PUSH operations add one new item to the stack. They only require
/// checking that the stack isn't already full.
///
/// @param stack The stack to validate
/// @return StackOverflow if stack is at capacity
///
/// Example:
/// ```zig
/// // PUSH1 operation
/// try validate_push(&frame.stack);
/// const value = readByte(pc + 1);
/// frame.stack.push(value);
/// ```
pub fn validate_push(stack: *const Stack) ExecutionError.Error!void {
Log.debug("ValidationPatterns.validate_push: Validating PUSH, stack_size={}", .{stack.size});
if (stack.size >= Stack.CAPACITY) {
Log.debug("ValidationPatterns.validate_push: Stack overflow, size={} >= capacity={}", .{ stack.size, Stack.CAPACITY });
return ExecutionError.Error.StackOverflow;
}
Log.debug("ValidationPatterns.validate_push: Validation passed", .{});
}
// Import the helper function
const validate_stack_operation = @import("stack_validation.zig").validate_stack_operation;
```
```zig [src/evm/access_list/access_list.zig]
const std = @import("std");
const Address = @import("Address");
const AccessListStorageKey = @import("access_list_storage_key.zig");
const AccessListStorageKeyContext = @import("access_list_storage_key_context.zig");
/// EIP-2929 & EIP-2930: Access list management for gas cost calculation
///
/// Tracks which addresses and storage slots have been accessed during transaction
/// execution. First access (cold) costs more gas than subsequent accesses (warm).
///
/// Gas costs:
/// - Cold address access: 2600 gas
/// - Warm address access: 100 gas
/// - Cold storage slot access: 2100 gas
/// - Warm storage slot access: 100 gas
// Error types for AccessList operations
pub const AccessAddressError = std.mem.Allocator.Error;
pub const AccessStorageSlotError = std.mem.Allocator.Error;
pub const PreWarmAddressesError = std.mem.Allocator.Error;
pub const PreWarmStorageSlotsError = std.mem.Allocator.Error;
pub const InitTransactionError = std.mem.Allocator.Error;
pub const GetCallCostError = std.mem.Allocator.Error;
pub const AccessList = @This();
// Gas costs defined by EIP-2929
pub const COLD_ACCOUNT_ACCESS_COST: u64 = 2600;
pub const WARM_ACCOUNT_ACCESS_COST: u64 = 100;
pub const COLD_SLOAD_COST: u64 = 2100;
pub const WARM_SLOAD_COST: u64 = 100;
// Additional costs for CALL operations
pub const COLD_CALL_EXTRA_COST: u64 = COLD_ACCOUNT_ACCESS_COST - WARM_ACCOUNT_ACCESS_COST;
allocator: std.mem.Allocator,
/// Warm addresses - addresses that have been accessed
addresses: std.AutoHashMap(Address.Address, void),
/// Warm storage slots - storage slots that have been accessed
storage_slots: std.HashMap(AccessListStorageKey, void, AccessListStorageKeyContext, 80),
pub fn init(allocator: std.mem.Allocator) AccessList {
return .{
.allocator = allocator,
.addresses = std.AutoHashMap(Address.Address, void).init(allocator),
.storage_slots = std.HashMap(AccessListStorageKey, void, AccessListStorageKeyContext, 80).init(allocator),
};
}
pub fn deinit(self: *AccessList) void {
self.addresses.deinit();
self.storage_slots.deinit();
}
/// Clear all access lists for a new transaction
pub fn clear(self: *AccessList) void {
self.addresses.clearRetainingCapacity();
self.storage_slots.clearRetainingCapacity();
}
/// Mark an address as accessed and return the gas cost
/// Returns COLD_ACCOUNT_ACCESS_COST if first access, WARM_ACCOUNT_ACCESS_COST if already accessed
pub fn access_address(self: *AccessList, address: Address.Address) std.mem.Allocator.Error!u64 {
const result = try self.addresses.getOrPut(address);
if (result.found_existing) return WARM_ACCOUNT_ACCESS_COST;
return COLD_ACCOUNT_ACCESS_COST;
}
/// Mark a storage slot as accessed and return the gas cost
/// Returns COLD_SLOAD_COST if first access, WARM_SLOAD_COST if already accessed
pub fn access_storage_slot(self: *AccessList, address: Address.Address, slot: u256) std.mem.Allocator.Error!u64 {
const key = AccessListStorageKey{ .address = address, .slot = slot };
const result = try self.storage_slots.getOrPut(key);
if (result.found_existing) return WARM_SLOAD_COST;
return COLD_SLOAD_COST;
}
/// Check if an address is warm (has been accessed)
pub fn is_address_warm(self: *const AccessList, address: Address.Address) bool {
return self.addresses.contains(address);
}
/// Check if a storage slot is warm (has been accessed)
pub fn is_storage_slot_warm(self: *const AccessList, address: Address.Address, slot: u256) bool {
const key = AccessListStorageKey{ .address = address, .slot = slot };
return self.storage_slots.contains(key);
}
/// Pre-warm addresses from EIP-2930 access list
pub fn pre_warm_addresses(self: *AccessList, addresses: []const Address.Address) std.mem.Allocator.Error!void {
for (addresses) |address| {
try self.addresses.put(address, {});
}
}
/// Pre-warm storage slots from EIP-2930 access list
pub fn pre_warm_storage_slots(self: *AccessList, address: Address.Address, slots: []const u256) std.mem.Allocator.Error!void {
for (slots) |slot| {
const key = AccessListStorageKey{ .address = address, .slot = slot };
try self.storage_slots.put(key, {});
}
}
/// Initialize transaction access list with pre-warmed addresses
/// According to EIP-2929, tx.origin and block.coinbase are always pre-warmed
pub fn init_transaction(self: *AccessList, tx_origin: Address.Address, coinbase: Address.Address, to: ?Address.Address) std.mem.Allocator.Error!void {
// Clear previous transaction data
self.clear();
try self.addresses.put(tx_origin, {});
try self.addresses.put(coinbase, {});
if (to) |to_address| {
try self.addresses.put(to_address, {});
}
}
/// Get the extra gas cost for accessing an address (for CALL operations)
/// Returns 0 if warm, COLD_CALL_EXTRA_COST if cold
pub fn get_call_cost(self: *AccessList, address: Address.Address) std.mem.Allocator.Error!u64 {
const result = try self.addresses.getOrPut(address);
if (result.found_existing) return 0;
return COLD_CALL_EXTRA_COST;
}
// Tests
const testing = std.testing;
test "AccessList basic operations" {
var access_list = AccessList.init(testing.allocator);
defer access_list.deinit();
const test_address = [_]u8{1} ** 20;
// First access should be cold
const cost1 = try access_list.access_address(test_address);
try testing.expectEqual(COLD_ACCOUNT_ACCESS_COST, cost1);
// Second access should be warm
const cost2 = try access_list.access_address(test_address);
try testing.expectEqual(WARM_ACCOUNT_ACCESS_COST, cost2);
// Check warmth
try testing.expect(access_list.is_address_warm(test_address));
const cold_address = [_]u8{2} ** 20;
try testing.expect(!access_list.is_address_warm(cold_address));
}
test "AccessList storage slots" {
var access_list = AccessList.init(testing.allocator);
defer access_list.deinit();
const test_address = [_]u8{1} ** 20;
const slot1: u256 = 42;
const slot2: u256 = 100;
// First access to slot1 should be cold
const cost1 = try access_list.access_storage_slot(test_address, slot1);
try testing.expectEqual(COLD_SLOAD_COST, cost1);
// Second access to slot1 should be warm
const cost2 = try access_list.access_storage_slot(test_address, slot1);
try testing.expectEqual(WARM_SLOAD_COST, cost2);
// First access to slot2 should be cold
const cost3 = try access_list.access_storage_slot(test_address, slot2);
try testing.expectEqual(COLD_SLOAD_COST, cost3);
// Check warmth
try testing.expect(access_list.is_storage_slot_warm(test_address, slot1));
try testing.expect(access_list.is_storage_slot_warm(test_address, slot2));
try testing.expect(!access_list.is_storage_slot_warm(test_address, 999));
}
test "AccessList transaction initialization" {
var access_list = AccessList.init(testing.allocator);
defer access_list.deinit();
const tx_origin = [_]u8{1} ** 20;
const coinbase = [_]u8{2} ** 20;
const to_address = [_]u8{3} ** 20;
try access_list.init_transaction(tx_origin, coinbase, to_address);
// All should be pre-warmed
try testing.expect(access_list.is_address_warm(tx_origin));
try testing.expect(access_list.is_address_warm(coinbase));
try testing.expect(access_list.is_address_warm(to_address));
// Accessing them should return warm cost
try testing.expectEqual(WARM_ACCOUNT_ACCESS_COST, try access_list.access_address(tx_origin));
try testing.expectEqual(WARM_ACCOUNT_ACCESS_COST, try access_list.access_address(coinbase));
try testing.expectEqual(WARM_ACCOUNT_ACCESS_COST, try access_list.access_address(to_address));
}
test "AccessList pre-warming from EIP-2930" {
var access_list = AccessList.init(testing.allocator);
defer access_list.deinit();
const addresses = [_]Address.Address{
[_]u8{1} ** 20,
[_]u8{2} ** 20,
[_]u8{3} ** 20,
};
try access_list.pre_warm_addresses(&addresses);
// All should be warm
for (addresses) |address| {
try testing.expect(access_list.is_address_warm(address));
try testing.expectEqual(WARM_ACCOUNT_ACCESS_COST, try access_list.access_address(address));
}
// Test storage slot pre-warming
const contract_address = [_]u8{4} ** 20;
const slots = [_]u256{ 1, 2, 3, 100 };
try access_list.pre_warm_storage_slots(contract_address, &slots);
for (slots) |slot| {
try testing.expect(access_list.is_storage_slot_warm(contract_address, slot));
try testing.expectEqual(WARM_SLOAD_COST, try access_list.access_storage_slot(contract_address, slot));
}
}
test "AccessList call costs" {
var access_list = AccessList.init(testing.allocator);
defer access_list.deinit();
const cold_address = [_]u8{1} ** 20;
const warm_address = [_]u8{2} ** 20;
// Pre-warm one address
try access_list.pre_warm_addresses(&[_]Address.Address{warm_address});
// Cold address should have extra cost
try testing.expectEqual(COLD_CALL_EXTRA_COST, try access_list.get_call_cost(cold_address));
// Warm address should have no extra cost
try testing.expectEqual(@as(u64, 0), try access_list.get_call_cost(warm_address));
// After getting cost, cold address should now be warm
try testing.expect(access_list.is_address_warm(cold_address));
}
```
```zig [src/evm/access_list/access_list_storage_key_context.zig]
const AccessListStorageKey = @import("access_list_storage_key.zig");
/// HashMap context for AccessListStorageKey
const Self = @This();
pub fn hash(ctx: Self, key: AccessListStorageKey) u64 {
_ = ctx;
return key.hash();
}
pub fn eql(ctx: Self, a: AccessListStorageKey, b: AccessListStorageKey) bool {
_ = ctx;
return a.eql(b);
}
```
```zig [src/evm/access_list/access_list_storage_key.zig]
const std = @import("std");
const Address = @import("Address");
/// Storage slot key combining address and slot for access list operations
/// This version provides direct hash output for use with HashMap
const Self = @This();
address: Address.Address,
slot: u256,
pub fn hash(self: Self) u64 {
var hasher = std.hash.Wyhash.init(0);
hasher.update(&self.address);
hasher.update(std.mem.asBytes(&self.slot));
return hasher.final();
}
pub fn eql(self: Self, other: Self) bool {
return std.mem.eql(u8, &self.address, &other.address) and self.slot == other.slot;
}
```
```zig [src/evm/call_result.zig]
/// Result structure returned by contract call operations.
///
/// This structure encapsulates the outcome of executing a contract call in the EVM,
/// including standard calls (CALL), code calls (CALLCODE), delegate calls (DELEGATECALL),
/// and static calls (STATICCALL). It provides a unified interface for handling the
/// results of all inter-contract communication operations.
///
/// ## Usage
/// This structure is returned by the VM's call methods and contains all information
/// needed to determine the outcome of a call and process its results.
///
/// ## Call Types
/// - **CALL**: Standard contract call with its own storage context
/// - **CALLCODE**: Executes external code in current storage context (deprecated)
/// - **DELEGATECALL**: Executes external code with current storage and msg context
/// - **STATICCALL**: Read-only call that cannot modify state
///
/// ## Example
/// ```zig
/// const result = try vm.call_contract(caller, to, value, input, gas, is_static);
/// if (result.success) {
/// // Process successful call
/// if (result.output) |data| {
/// // Handle returned data
/// }
/// } else {
/// // Handle failed call - gas_left indicates remaining gas
/// }
/// defer if (result.output) |output| allocator.free(output);
/// ```
const Self = @This();
/// Indicates whether the call completed successfully.
///
/// - `true`: Call executed without errors and any state changes were committed
/// - `false`: Call failed due to revert, out of gas, or other errors
///
/// Note: A successful call may still have no output data if the called
/// contract intentionally returns nothing.
success: bool,
/// Amount of gas remaining after the call execution.
///
/// This value is important for gas accounting:
/// - For successful calls: Indicates unused gas to be refunded to the caller
/// - For failed calls: May be non-zero if the call reverted (vs running out of gas)
///
/// The calling context should add this back to its available gas to continue execution.
gas_left: u64,
/// Optional output data returned by the called contract.
///
/// - `null`: No data was returned (valid for both success and failure)
/// - `[]const u8`: Returned data buffer
///
/// ## Memory Management
/// The output data is allocated by the VM and ownership is transferred to the caller.
/// The caller is responsible for freeing this memory when no longer needed.
///
/// ## For Different Call Types
/// - **RETURN**: Contains the data specified in the RETURN opcode
/// - **REVERT**: Contains the revert reason/data if provided
/// - **STOP**: Will be null (no data returned)
/// - **Out of Gas/Invalid**: Will be null
output: ?[]const u8,
```
```zig [src/evm/opcodes/opcode.zig]
/// EVM opcode definitions and utilities.
///
/// This module defines all EVM opcodes as specified in the Ethereum Yellow Paper
/// and various EIPs. Each opcode is a single byte instruction that the EVM
/// interpreter executes.
///
/// ## Opcode Categories
/// - Arithmetic: ADD, MUL, SUB, DIV, MOD, EXP, etc.
/// - Comparison: LT, GT, EQ, ISZERO
/// - Bitwise: AND, OR, XOR, NOT, SHL, SHR, SAR
/// - Environmental: ADDRESS, BALANCE, CALLER, CALLVALUE
/// - Block Information: BLOCKHASH, COINBASE, TIMESTAMP, NUMBER
/// - Stack Operations: POP, PUSH1-PUSH32, DUP1-DUP16, SWAP1-SWAP16
/// - Memory Operations: MLOAD, MSTORE, MSTORE8, MSIZE
/// - Storage Operations: SLOAD, SSTORE, TLOAD, TSTORE
/// - Flow Control: JUMP, JUMPI, PC, JUMPDEST
/// - System Operations: CREATE, CALL, RETURN, REVERT, SELFDESTRUCT
/// - Logging: LOG0-LOG4
///
/// ## Opcode Encoding
/// Opcodes are encoded as single bytes (0x00-0xFF). Not all byte values
/// are assigned; unassigned values are treated as INVALID operations.
///
/// ## Hardfork Evolution
/// New opcodes are introduced through EIPs and activated at specific
/// hardforks. Examples:
/// - PUSH0 (EIP-3855): Shanghai hardfork
/// - TLOAD/TSTORE (EIP-1153): Cancun hardfork
/// - MCOPY (EIP-5656): Cancun hardfork
///
/// Example:
/// ```zig
/// const opcode = Opcode.Enum.ADD;
/// const byte_value = opcode.to_u8(); // 0x01
/// const name = opcode.get_name(); // "ADD"
/// ```
pub const MemorySize = @import("../memory_size.zig");
/// Opcode module providing EVM instruction definitions.
const Self = @This();
/// Enumeration of all EVM opcodes with their byte values.
///
/// Each opcode is assigned a specific byte value that remains
/// constant across all EVM implementations. The enum ensures
/// type safety when working with opcodes.
pub const Enum = enum(u8) {
/// Halts execution (0x00)
STOP = 0x00,
/// Addition operation: a + b (0x01)
ADD = 0x01,
/// Multiplication operation: a * b (0x02)
MUL = 0x02,
/// Subtraction operation: a - b (0x03)
SUB = 0x03,
/// Integer division operation: a / b (0x04)
DIV = 0x04,
/// Signed integer division operation (0x05)
SDIV = 0x05,
/// Modulo operation: a % b (0x06)
MOD = 0x06,
/// Signed modulo operation (0x07)
SMOD = 0x07,
/// Addition modulo: (a + b) % N (0x08)
ADDMOD = 0x08,
/// Multiplication modulo: (a * b) % N (0x09)
MULMOD = 0x09,
/// Exponential operation: a ** b (0x0A)
EXP = 0x0A,
/// Sign extend operation (0x0B)
SIGNEXTEND = 0x0B,
/// Less-than comparison: a < b (0x10)
LT = 0x10,
/// Greater-than comparison: a > b (0x11)
GT = 0x11,
/// Signed less-than comparison (0x12)
SLT = 0x12,
/// Signed greater-than comparison (0x13)
SGT = 0x13,
/// Equality comparison: a == b (0x14)
EQ = 0x14,
/// Check if value is zero (0x15)
ISZERO = 0x15,
/// Bitwise AND operation (0x16)
AND = 0x16,
/// Bitwise OR operation (0x17)
OR = 0x17,
/// Bitwise XOR operation (0x18)
XOR = 0x18,
/// Bitwise NOT operation (0x19)
NOT = 0x19,
/// Retrieve single byte from word (0x1A)
BYTE = 0x1A,
/// Logical shift left (0x1B)
SHL = 0x1B,
/// Logical shift right (0x1C)
SHR = 0x1C,
/// Arithmetic shift right (0x1D)
SAR = 0x1D,
/// Compute Keccak-256 hash (0x20)
KECCAK256 = 0x20,
/// Get address of currently executing account (0x30)
ADDRESS = 0x30,
/// Get balance of the given account (0x31)
BALANCE = 0x31,
/// Get execution origination address (0x32)
ORIGIN = 0x32,
/// Get caller address (0x33)
CALLER = 0x33,
/// Get deposited value by the caller (0x34)
CALLVALUE = 0x34,
/// Load input data of current call (0x35)
CALLDATALOAD = 0x35,
/// Get size of input data in current call (0x36)
CALLDATASIZE = 0x36,
/// Copy input data to memory (0x37)
CALLDATACOPY = 0x37,
/// Get size of code running in current environment (0x38)
CODESIZE = 0x38,
/// Copy code to memory (0x39)
CODECOPY = 0x39,
/// Get price of gas in current environment (0x3A)
GASPRICE = 0x3A,
EXTCODESIZE = 0x3B,
EXTCODECOPY = 0x3C,
RETURNDATASIZE = 0x3D,
RETURNDATACOPY = 0x3E,
EXTCODEHASH = 0x3F,
BLOCKHASH = 0x40,
COINBASE = 0x41,
TIMESTAMP = 0x42,
NUMBER = 0x43,
PREVRANDAO = 0x44,
GASLIMIT = 0x45,
CHAINID = 0x46,
SELFBALANCE = 0x47,
BASEFEE = 0x48,
BLOBHASH = 0x49,
BLOBBASEFEE = 0x4A,
POP = 0x50,
MLOAD = 0x51,
MSTORE = 0x52,
MSTORE8 = 0x53,
/// Load word from storage (0x54)
SLOAD = 0x54,
/// Store word to storage (0x55)
SSTORE = 0x55,
/// Unconditional jump (0x56)
JUMP = 0x56,
/// Conditional jump (0x57)
JUMPI = 0x57,
/// Get current program counter (0x58)
PC = 0x58,
/// Get size of active memory in bytes (0x59)
MSIZE = 0x59,
/// Get amount of available gas (0x5A)
GAS = 0x5A,
/// Mark valid jump destination (0x5B)
JUMPDEST = 0x5B,
/// Load word from transient storage (0x5C)
TLOAD = 0x5C,
/// Store word to transient storage (0x5D)
TSTORE = 0x5D,
/// Copy memory areas (0x5E)
MCOPY = 0x5E,
/// Push zero onto stack (0x5F)
PUSH0 = 0x5F,
PUSH1 = 0x60,
PUSH2 = 0x61,
PUSH3 = 0x62,
PUSH4 = 0x63,
PUSH5 = 0x64,
PUSH6 = 0x65,
PUSH7 = 0x66,
PUSH8 = 0x67,
PUSH9 = 0x68,
PUSH10 = 0x69,
PUSH11 = 0x6A,
PUSH12 = 0x6B,
PUSH13 = 0x6C,
PUSH14 = 0x6D,
PUSH15 = 0x6E,
PUSH16 = 0x6F,
PUSH17 = 0x70,
PUSH18 = 0x71,
PUSH19 = 0x72,
PUSH20 = 0x73,
PUSH21 = 0x74,
PUSH22 = 0x75,
PUSH23 = 0x76,
PUSH24 = 0x77,
PUSH25 = 0x78,
PUSH26 = 0x79,
PUSH27 = 0x7A,
PUSH28 = 0x7B,
PUSH29 = 0x7C,
PUSH30 = 0x7D,
PUSH31 = 0x7E,
PUSH32 = 0x7F,
DUP1 = 0x80,
DUP2 = 0x81,
DUP3 = 0x82,
DUP4 = 0x83,
DUP5 = 0x84,
DUP6 = 0x85,
DUP7 = 0x86,
DUP8 = 0x87,
DUP9 = 0x88,
DUP10 = 0x89,
DUP11 = 0x8A,
DUP12 = 0x8B,
DUP13 = 0x8C,
DUP14 = 0x8D,
DUP15 = 0x8E,
DUP16 = 0x8F,
SWAP1 = 0x90,
SWAP2 = 0x91,
SWAP3 = 0x92,
SWAP4 = 0x93,
SWAP5 = 0x94,
SWAP6 = 0x95,
SWAP7 = 0x96,
SWAP8 = 0x97,
SWAP9 = 0x98,
SWAP10 = 0x99,
SWAP11 = 0x9A,
SWAP12 = 0x9B,
SWAP13 = 0x9C,
SWAP14 = 0x9D,
SWAP15 = 0x9E,
SWAP16 = 0x9F,
LOG0 = 0xA0,
LOG1 = 0xA1,
LOG2 = 0xA2,
LOG3 = 0xA3,
LOG4 = 0xA4,
/// Create new contract (0xF0)
CREATE = 0xF0,
/// Message-call into account (0xF1)
CALL = 0xF1,
/// Message-call with current code (0xF2)
CALLCODE = 0xF2,
/// Halt execution returning output data (0xF3)
RETURN = 0xF3,
/// Call with current sender and value (0xF4)
DELEGATECALL = 0xF4,
/// Create with deterministic address (0xF5)
CREATE2 = 0xF5,
/// Load return data (0xF7)
RETURNDATALOAD = 0xF7,
/// Extended call (EOF) (0xF8)
EXTCALL = 0xF8,
/// Extended delegate call (EOF) (0xF9)
EXTDELEGATECALL = 0xF9,
/// Static message-call (0xFA)
STATICCALL = 0xFA,
/// Extended static call (EOF) (0xFB)
EXTSTATICCALL = 0xFB,
/// Halt execution reverting state changes (0xFD)
REVERT = 0xFD,
/// Invalid instruction (0xFE)
INVALID = 0xFE,
/// Destroy current contract (0xFF)
SELFDESTRUCT = 0xFF,
};
/// Convert an opcode to its byte representation.
///
/// Returns the underlying byte value of the opcode for use in
/// bytecode encoding/decoding and jump table lookups.
///
/// @param self The opcode to convert
/// @return The byte value (0x00-0xFF)
///
/// Example:
/// ```zig
/// const add_byte = Opcode.Enum.ADD.to_u8(); // Returns 0x01
/// const push1_byte = Opcode.Enum.PUSH1.to_u8(); // Returns 0x60
/// ```
pub fn to_u8(self: Enum) u8 {
return @intFromEnum(self);
}
/// Get the human-readable name of an opcode.
///
/// Returns the mnemonic string representation of the opcode
/// as used in assembly code and debugging output.
///
/// @param self The opcode to get the name of
/// @return Static string containing the opcode mnemonic
///
/// Example:
/// ```zig
/// const name = Opcode.Enum.ADD.get_name(); // Returns "ADD"
/// std.debug.print("Executing opcode: {s}\n", .{name});
/// ```
pub fn get_name(self: Enum) []const u8 {
// Build a lookup table at comptime
const names = comptime blk: {
var n: [256][]const u8 = undefined;
// Initialize all to "UNDEFINED"
for (&n) |*name| {
name.* = "UNDEFINED";
}
// Map enum values to their names using reflection
const enum_info = @typeInfo(Enum);
switch (enum_info) {
.@"enum" => |e| {
for (e.fields) |field| {
const value = @field(Enum, field.name);
n[@intFromEnum(value)] = field.name;
}
},
else => @compileError("get_name requires an enum type"),
}
break :blk n;
};
return names[@intFromEnum(self)];
}
```
```zig [src/evm/opcodes/operation.zig]
const std = @import("std");
const Opcode = @import("opcode.zig");
const ExecutionError = @import("../execution/execution_error.zig");
const Stack = @import("../stack/stack.zig");
const Memory = @import("../memory.zig");
/// Operation metadata and execution functions for EVM opcodes.
///
/// This module defines the structure for EVM operations, including their
/// execution logic, gas costs, and stack requirements. Each opcode in the
/// EVM is associated with an Operation that controls its behavior.
///
/// ## Design Philosophy
/// Operations encapsulate all opcode-specific logic:
/// - Execution function that implements the opcode
/// - Gas calculation (both constant and dynamic)
/// - Stack validation requirements
/// - Memory expansion calculations
///
/// ## Function Types
/// The module uses function pointers for flexibility, allowing:
/// - Different implementations for different hardforks
/// - Optimized variants for specific conditions
/// - Mock implementations for testing
///
/// ## Gas Model
/// EVM gas costs consist of:
/// - Constant gas: Fixed cost for the operation
/// - Dynamic gas: Variable cost based on operation parameters
///
/// Example:
/// ```zig
/// // ADD operation
/// const add_op = Operation{
/// .execute = executeAdd,
/// .constant_gas = 3,
/// .min_stack = 2,
/// .max_stack = Stack.CAPACITY - 1,
/// };
/// ```
pub const ExecutionResult = @import("../execution/execution_result.zig");
/// Forward declaration for the interpreter context.
/// The actual interpreter implementation provides VM state and context.
pub const Interpreter = opaque {};
/// Forward declaration for execution state.
/// Contains transaction context, account state, and execution environment.
pub const State = opaque {};
/// Function signature for opcode execution.
///
/// Each opcode implements this signature to perform its operation.
/// The function has access to:
/// - Program counter for reading immediate values
/// - Interpreter for stack/memory manipulation
/// - State for account and storage access
///
/// @param pc Current program counter position
/// @param interpreter VM interpreter context
/// @param state Execution state and environment
/// @return Execution result indicating success/failure and gas consumption
pub const ExecutionFunc = *const fn (pc: usize, interpreter: *Interpreter, state: *State) ExecutionError.Error!ExecutionResult;
/// Function signature for dynamic gas calculation.
///
/// Some operations have variable gas costs based on:
/// - Current state (e.g., cold vs warm storage access)
/// - Operation parameters (e.g., memory expansion size)
/// - Network rules (e.g., EIP-2929 access lists)
///
/// @param interpreter VM interpreter context
/// @param state Execution state
/// @param stack Current stack for parameter inspection
/// @param memory Current memory for size calculations
/// @param requested_size Additional memory requested by operation
/// @return Dynamic gas cost to add to constant gas
/// @throws OutOfGas if gas calculation overflows
pub const GasFunc = *const fn (interpreter: *Interpreter, state: *State, stack: *Stack, memory: *Memory, requested_size: u64) error{OutOfGas}!u64;
/// Function signature for memory size calculation.
///
/// Operations that access memory need to calculate the required size
/// before execution to:
/// - Charge memory expansion gas
/// - Validate memory bounds
/// - Pre-allocate memory if needed
///
/// @param stack Stack containing operation parameters
/// @return Required memory size for the operation
pub const MemorySizeFunc = *const fn (stack: *Stack) Opcode.MemorySize;
/// EVM operation definition containing all metadata and functions.
///
/// Each entry in the jump table is an Operation that fully describes
/// how to execute an opcode, including validation, gas calculation,
/// and the actual execution logic.
const Self = @This();
/// Execution function implementing the opcode logic.
/// This is called after all validations pass.
execute: ExecutionFunc,
/// Base gas cost for this operation.
/// This is the minimum gas charged regardless of parameters.
/// Defined by the Ethereum Yellow Paper and EIPs.
constant_gas: u64,
/// Optional dynamic gas calculation function.
/// Operations with variable costs (storage, memory, calls) use this
/// to calculate additional gas based on runtime parameters.
dynamic_gas: ?GasFunc = null,
/// Minimum stack items required before execution.
/// The operation will fail with StackUnderflow if the stack
/// has fewer than this many items.
min_stack: u32,
/// Maximum stack size allowed before execution.
/// Ensures the operation won't cause stack overflow.
/// Calculated as: CAPACITY - (pushes - pops)
max_stack: u32,
/// Optional memory size calculation function.
/// Operations that access memory use this to determine
/// memory expansion requirements before execution.
memory_size: ?MemorySizeFunc = null,
/// Indicates if this is an undefined/invalid opcode.
/// Undefined opcodes consume all gas and fail execution.
/// Used for opcodes not assigned in the current hardfork.
undefined: bool = false,
/// Singleton NULL operation for unassigned opcode slots.
///
/// This operation is used for opcodes that:
/// - Are not yet defined in the current hardfork
/// - Have been removed in the current hardfork
/// - Are reserved for future use
///
/// Executing NULL always results in InvalidOpcode error.
pub const NULL = Self{
.execute = undefined_execute,
.constant_gas = 0,
.min_stack = 0,
.max_stack = Stack.CAPACITY,
.undefined = true,
};
/// Execution function for undefined opcodes.
///
/// Consumes all remaining gas and returns InvalidOpcode error.
/// This ensures undefined opcodes cannot be used for computation.
fn undefined_execute(pc: usize, interpreter: *Interpreter, state: *State) ExecutionError.Error!ExecutionResult {
_ = pc;
_ = interpreter;
_ = state;
return ExecutionError.Error.InvalidOpcode;
}```
```zig [src/evm/context.zig]
const std = @import("std");
const Address = @import("Address");
/// Execution context providing transaction and block information to the EVM.
///
/// This structure encapsulates all environmental data that smart contracts
/// can access during execution. It provides the context needed for opcodes
/// like ORIGIN, TIMESTAMP, COINBASE, etc. to return appropriate values.
///
/// ## Purpose
/// The context separates environmental information from the VM's execution
/// state, enabling:
/// - Consistent environment across nested calls
/// - Easy testing with mock environments
/// - Support for historical block execution
/// - Fork simulation with custom parameters
///
/// ## Opcode Mapping
/// Context fields map directly to EVM opcodes:
/// - `tx_origin` → ORIGIN (0x32)
/// - `gas_price` → GASPRICE (0x3A)
/// - `block_number` → NUMBER (0x43)
/// - `block_timestamp` → TIMESTAMP (0x42)
/// - `block_coinbase` → COINBASE (0x41)
/// - `block_difficulty` → DIFFICULTY/PREVRANDAO (0x44)
/// - `block_gas_limit` → GASLIMIT (0x45)
/// - `chain_id` → CHAINID (0x46)
/// - `block_base_fee` → BASEFEE (0x48)
/// - `blob_hashes` → BLOBHASH (0x49)
///
/// ## Usage Example
/// ```zig
/// const context = Context.init_with_values(
/// .tx_origin = sender_address,
/// .gas_price = 20_000_000_000, // 20 gwei
/// .block_number = 15_000_000,
/// .block_timestamp = 1656633600,
/// .block_coinbase = miner_address,
/// .block_difficulty = 0, // post-merge
/// .block_gas_limit = 30_000_000,
/// .chain_id = 1, // mainnet
/// .block_base_fee = 15_000_000_000,
/// .blob_hashes = &.{},
/// .blob_base_fee = 1,
/// );
/// ```
const Self = @This();
/// The original sender address that initiated the transaction.
///
/// ## ORIGIN Opcode (0x32)
/// This value remains constant throughout all nested calls and
/// represents the externally-owned account (EOA) that signed the
/// transaction.
///
/// ## Security Warning
/// Using tx.origin for authentication is dangerous as it can be
/// exploited through phishing attacks. Always use msg.sender instead.
///
/// ## Example
/// EOA → Contract A → Contract B → Contract C
/// - tx.origin = EOA (same for all)
/// - msg.sender differs at each level
tx_origin: Address.Address = Address.zero(),
/// The gas price for the current transaction in wei.
///
/// ## GASPRICE Opcode (0x3A)
/// Returns the effective gas price that the transaction is paying:
/// - Legacy transactions: The specified gas price
/// - EIP-1559 transactions: min(maxFeePerGas, baseFee + maxPriorityFeePerGas)
///
/// ## Typical Values
/// - 1 gwei = 1,000,000,000 wei
/// - Mainnet: Usually 10-100 gwei
/// - Test networks: Often 0 or 1 gwei
gas_price: u256 = 0,
/// The current block number (height).
///
/// ## NUMBER Opcode (0x43)
/// Returns the number of the block being executed. Block numbers
/// start at 0 (genesis) and increment by 1 for each block.
///
/// ## Network Examples
/// - Mainnet genesis: 0
/// - The Merge: ~15,537,394
/// - Typical mainnet: >18,000,000
///
/// ## Use Cases
/// - Time-locked functionality
/// - Random number generation (pre-Merge)
/// - Historical reference points
block_number: u64 = 0,
/// The current block's timestamp in Unix seconds.
///
/// ## TIMESTAMP Opcode (0x42)
/// Returns seconds since Unix epoch (January 1, 1970).
/// Miners/validators can manipulate this within limits:
/// - Must be > parent timestamp
/// - Should be close to real time
///
/// ## Time Precision
/// - Pre-Merge: ~13 second blocks, loose precision
/// - Post-Merge: 12 second slots, more predictable
///
/// ## Security Note
/// Can be manipulated by miners/validators within ~15 seconds.
/// Not suitable for precise timing or as randomness source.
block_timestamp: u64 = 0,
/// The address of the block's miner/validator (beneficiary).
///
/// ## COINBASE Opcode (0x41)
/// Returns the address that receives block rewards and fees:
/// - Pre-Merge: Miner who found the block
/// - Post-Merge: Validator proposing the block
///
/// ## Special Values
/// - Zero address: Often used in tests
/// - Burn address: Some L2s burn fees
///
/// ## MEV Considerations
/// Searchers often send payments to block.coinbase for
/// transaction inclusion guarantees.
block_coinbase: Address.Address = Address.zero(),
/// Block difficulty (pre-Merge) or PREVRANDAO (post-Merge).
///
/// ## DIFFICULTY/PREVRANDAO Opcode (0x44)
/// The meaning changed at The Merge:
/// - Pre-Merge: Mining difficulty value
/// - Post-Merge: Previous block's RANDAO value
///
/// ## PREVRANDAO Usage
/// Provides weak randomness from beacon chain:
/// - NOT cryptographically secure
/// - Can be biased by validators
/// - Suitable only for non-critical randomness
///
/// ## Typical Values
/// - Pre-Merge: 10^15 to 10^16 range
/// - Post-Merge: Random 256-bit value
block_difficulty: u256 = 0,
/// Maximum gas allowed in the current block.
///
/// ## GASLIMIT Opcode (0x45)
/// Returns the total gas limit for all transactions in the block.
/// This limit is adjusted by miners/validators within protocol rules:
/// - Can change by max 1/1024 per block
/// - Target: 15M gas (100% full blocks)
/// - Max: 30M gas (200% full blocks)
///
/// ## Typical Values
/// - Mainnet: ~30,000,000
/// - Some L2s: 100,000,000+
///
/// ## EIP-1559 Impact
/// Elastic block sizes allow temporary increases to 2x target.
block_gas_limit: u64 = 0,
/// The chain identifier for replay protection.
///
/// ## CHAINID Opcode (0x46)
/// Returns the unique identifier for the current chain,
/// preventing transaction replay across different networks.
///
/// ## Common Values
/// - 1: Ethereum Mainnet
/// - 5: Goerli (deprecated)
/// - 11155111: Sepolia
/// - 137: Polygon
/// - 10: Optimism
/// - 42161: Arbitrum One
///
/// ## EIP-155
/// Introduced chain ID to prevent replay attacks where
/// signed transactions could be valid on multiple chains.
chain_id: u256 = 1,
/// The base fee per gas for the current block (EIP-1559).
///
/// ## BASEFEE Opcode (0x48)
/// Returns the minimum fee per gas that must be paid for
/// transaction inclusion. Dynamically adjusted based on
/// parent block's gas usage:
/// - Increases if blocks are >50% full
/// - Decreases if blocks are <50% full
/// - Changes by max 12.5% per block
///
/// ## Fee Calculation
/// Total fee = (base fee + priority fee) * gas used
/// Base fee is burned, priority fee goes to validator.
///
/// ## Typical Values
/// - Low congestion: 5-10 gwei
/// - Normal: 15-30 gwei
/// - High congestion: 100+ gwei
block_base_fee: u256 = 0,
/// List of blob hashes for EIP-4844 blob transactions.
///
/// ## BLOBHASH Opcode (0x49)
/// Returns the hash of a blob at the specified index.
/// Blob transactions can include up to 6 blobs, each
/// containing ~125KB of data for L2 data availability.
///
/// ## Blob Properties
/// - Size: 4096 field elements (~125KB)
/// - Hash: KZG commitment of blob data
/// - Lifetime: ~18 days on chain
/// - Cost: Separate blob fee market
///
/// ## Empty for Non-Blob Transactions
/// Regular transactions have no blob hashes.
blob_hashes: []const u256 = &[_]u256{},
/// The base fee per blob gas for the current block (EIP-4844).
///
/// ## BLOBBASEFEE Opcode (0x4A)
/// Returns the current base fee for blob gas, which uses
/// a separate fee market from regular transaction gas.
///
/// ## Blob Fee Market
/// - Independent from regular gas fees
/// - Target: 3 blobs per block
/// - Max: 6 blobs per block
/// - Adjusts similar to EIP-1559
///
/// ## Cost Calculation
/// Blob cost = blob_base_fee * blob_gas_used
/// Where blob_gas_used = num_blobs * 131,072
///
/// ## Typical Values
/// - Low usage: 1 wei
/// - High usage: Can spike significantly
blob_base_fee: u256 = 0,
/// Creates a new context with default values.
///
/// ## Default Values
/// - All addresses: Zero address (0x0000...0000)
/// - All numbers: 0
/// - Chain ID: 1 (Ethereum mainnet)
/// - Blob hashes: Empty array
///
/// ## Usage
/// ```zig
/// const context = Context.init();
/// // Suitable for basic testing, but usually you'll want
/// // to set more realistic values
/// ```
///
/// ## Warning
/// Default values may not be suitable for production use.
/// Consider using `init_with_values` for realistic contexts.
pub fn init() Self {
return .{};
}
/// Creates a new context with specified values.
///
/// This constructor allows full control over all environmental
/// parameters, enabling accurate simulation of any blockchain state.
///
/// ## Parameters
/// - `tx_origin`: EOA that initiated the transaction
/// - `gas_price`: Effective gas price in wei
/// - `block_number`: Current block height
/// - `block_timestamp`: Unix timestamp in seconds
/// - `block_coinbase`: Block producer address
/// - `block_difficulty`: Difficulty or PREVRANDAO value
/// - `block_gas_limit`: Maximum gas for the block
/// - `chain_id`: Network identifier
/// - `block_base_fee`: EIP-1559 base fee
/// - `blob_hashes`: Array of blob hashes for EIP-4844
/// - `blob_base_fee`: Base fee for blob gas
///
/// ## Example
/// ```zig
/// const context = Context.init_with_values(
/// sender_address, // tx_origin
/// 20_000_000_000, // gas_price: 20 gwei
/// 18_500_000, // block_number
/// 1_700_000_000, // block_timestamp
/// validator_address, // block_coinbase
/// 0, // block_difficulty (post-merge)
/// 30_000_000, // block_gas_limit
/// 1, // chain_id: mainnet
/// 15_000_000_000, // block_base_fee: 15 gwei
/// &[_]u256{}, // blob_hashes: none
/// 1, // blob_base_fee: minimum
/// );
/// ```
pub fn init_with_values(
tx_origin: Address.Address,
gas_price: u256,
block_number: u64,
block_timestamp: u64,
block_coinbase: Address.Address,
block_difficulty: u256,
block_gas_limit: u64,
chain_id: u256,
block_base_fee: u256,
blob_hashes: []const u256,
blob_base_fee: u256,
) Self {
return .{
.tx_origin = tx_origin,
.gas_price = gas_price,
.block_number = block_number,
.block_timestamp = block_timestamp,
.block_coinbase = block_coinbase,
.block_difficulty = block_difficulty,
.block_gas_limit = block_gas_limit,
.chain_id = chain_id,
.block_base_fee = block_base_fee,
.blob_hashes = blob_hashes,
.blob_base_fee = blob_base_fee,
};
}
/// Checks if the context represents Ethereum mainnet.
///
/// ## Returns
/// - `true` if chain_id == 1 (Ethereum mainnet)
/// - `false` for all other networks
///
/// ## Common Chain IDs
/// - 1: Ethereum Mainnet ✓
/// - 5: Goerli Testnet ✗
/// - 137: Polygon ✗
/// - 10: Optimism ✗
///
/// ## Usage
/// ```zig
/// if (context.is_eth_mainnet()) {
/// // Apply mainnet-specific logic
/// // e.g., different gas limits, precompiles
/// }
/// ```
///
/// ## Note
/// This is a convenience method. For checking other chains,
/// compare chain_id directly.
pub fn is_eth_mainnet(self: Self) bool {
return self.chain_id == 1;
}
```
```zig [src/evm/evm.zig]
//! EVM (Ethereum Virtual Machine) module - Core execution engine
//!
//! This is the main entry point for the EVM implementation. It exports all
//! the components needed to execute Ethereum bytecode, manage state, and
//! handle the complete lifecycle of smart contract execution.
//!
//! ## Architecture Overview
//!
//! The EVM is structured into several key components:
//!
//! ### Core Execution
//! - **VM**: The main virtual machine that orchestrates execution
//! - **Frame**: Execution contexts for calls and creates
//! - **Stack**: 256-bit word stack (max 1024 elements)
//! - **Memory**: Byte-addressable memory (expands as needed)
//! - **Contract**: Code and storage management
//!
//! ### Opcodes
//! - **Opcode**: Enumeration of all EVM instructions
//! - **Operation**: Metadata about each opcode (gas, stack effects)
//! - **JumpTable**: Maps opcodes to their implementations
//! - **execution/**: Individual opcode implementations
//!
//! ### Error Handling
//! - **ExecutionError**: Unified error type for all execution failures
//! - Strongly typed errors for each component
//! - Error mapping utilities for consistent handling
//!
//! ### Utilities
//! - **CodeAnalysis**: Bytecode analysis and jump destination detection
//! - **Hardfork**: Fork-specific behavior configuration
//! - **gas_constants**: Gas cost calculations
//! - **chain_rules**: Chain-specific validation rules
//!
//! ## Usage Example
//!
//! ```zig
//! const evm = @import("evm");
//!
//! // Create a VM instance
//! var vm = try evm.Vm.init(allocator, config);
//! defer vm.deinit();
//!
//! // Execute bytecode
//! const result = try vm.run(bytecode, context);
//! ```
//!
//! ## Design Principles
//!
//! 1. **Correctness**: Strict adherence to Ethereum Yellow Paper
//! 2. **Performance**: Efficient execution with minimal allocations
//! 3. **Safety**: Strong typing and comprehensive error handling
//! 4. **Modularity**: Clear separation of concerns
//! 5. **Testability**: Extensive test coverage for all components
const std = @import("std");
// Import external modules
/// Address utilities for Ethereum addresses
pub const Address = @import("Address");
// Import all EVM modules
/// Bytecode analysis for jump destination detection
pub const CodeAnalysis = @import("contract/code_analysis.zig");
/// Contract code and storage management
pub const Contract = @import("contract/contract.zig");
/// Unified error types for EVM execution
pub const ExecutionError = @import("execution/execution_error.zig");
/// Execution result type
pub const ExecutionResult = @import("execution/execution_result.zig");
/// Execution frame/context management
pub const Frame = @import("frame.zig");
/// Ethereum hardfork configuration
pub const Hardfork = @import("hardforks/hardfork.zig");
/// Opcode to implementation mapping
pub const JumpTable = @import("jump_table/jump_table.zig");
/// Byte-addressable memory implementation
pub const Memory = @import("memory.zig");
/// EVM instruction enumeration
pub const Opcode = @import("opcodes/opcode.zig");
/// Opcode metadata (gas costs, stack effects)
pub const Operation = @import("opcodes/operation.zig");
/// 256-bit word stack implementation
pub const Stack = @import("stack/stack.zig");
/// Stack depth validation utilities
pub const stack_validation = @import("stack/stack_validation.zig");
/// Storage slot pooling for gas optimization
pub const StoragePool = @import("contract/storage_pool.zig");
/// Main virtual machine implementation
pub const Vm = @import("vm.zig");
/// EVM state management (accounts, storage, logs)
pub const EvmState = @import("state/state.zig");
/// Precompiled contracts implementation (IDENTITY, SHA256, etc.)
pub const Precompiles = @import("precompiles/precompiles.zig");
// Import execution
/// All opcode implementations (arithmetic, stack, memory, etc.)
pub const execution = @import("execution/package.zig");
// Backwards compatibility alias
pub const opcodes = execution;
// Import utility modules
/// Bit vector utilities for jump destination tracking
pub const bitvec = @import("contract/bitvec.zig");
/// Chain-specific validation rules
pub const chain_rules = @import("hardforks/chain_rules.zig");
/// EVM constants (stack size, memory limits, etc.)
pub const constants = @import("constants/constants.zig");
/// EIP-7702 EOA delegation bytecode format
pub const eip_7702_bytecode = @import("contract/eip_7702_bytecode.zig");
/// Fee market calculations (EIP-1559)
pub const fee_market = @import("fee_market.zig");
/// Gas cost constants and calculations
pub const gas_constants = @import("constants/gas_constants.zig");
/// Memory size limits and expansion rules
pub const memory_limits = @import("constants/memory_limits.zig");
// Export all error types for strongly typed error handling
///
/// These error types provide fine-grained error handling throughout
/// the EVM. Each error type corresponds to a specific failure mode,
/// allowing precise error handling and recovery strategies.
// VM error types
/// Errors from VM contract creation operations
pub const CreateContractError = Vm.CreateContractError;
pub const CallContractError = Vm.CallContractError;
pub const ConsumeGasError = Vm.ConsumeGasError;
pub const Create2ContractError = Vm.Create2ContractError;
pub const CallcodeContractError = Vm.CallcodeContractError;
pub const DelegatecallContractError = Vm.DelegatecallContractError;
pub const StaticcallContractError = Vm.StaticcallContractError;
pub const EmitLogError = Vm.EmitLogError;
pub const InitTransactionAccessListError = Vm.InitTransactionAccessListError;
pub const PreWarmAddressesError = Vm.PreWarmAddressesError;
pub const PreWarmStorageSlotsError = Vm.PreWarmStorageSlotsError;
pub const GetAddressAccessCostError = Vm.GetAddressAccessCostError;
pub const GetStorageAccessCostError = Vm.GetStorageAccessCostError;
pub const GetCallCostError = Vm.GetCallCostError;
pub const ValidateStaticContextError = Vm.ValidateStaticContextError;
pub const SetStorageProtectedError = Vm.SetStorageProtectedError;
pub const SetTransientStorageProtectedError = Vm.SetTransientStorageProtectedError;
pub const SetBalanceProtectedError = Vm.SetBalanceProtectedError;
pub const SetCodeProtectedError = Vm.SetCodeProtectedError;
pub const EmitLogProtectedError = Vm.EmitLogProtectedError;
pub const CreateContractProtectedError = Vm.CreateContractProtectedError;
pub const Create2ContractProtectedError = Vm.Create2ContractProtectedError;
pub const ValidateValueTransferError = Vm.ValidateValueTransferError;
pub const SelfdestructProtectedError = Vm.SelfdestructProtectedError;
// VM result types
/// Result of running EVM bytecode
pub const RunResult = Vm.RunResult;
/// Result of CREATE/CREATE2 operations
pub const CreateResult = Vm.CreateResult;
/// Result of CALL/DELEGATECALL/STATICCALL operations
pub const CallResult = Vm.CallResult;
// Memory error types
/// Errors from memory operations (expansion, access)
pub const MemoryError = Memory.MemoryError;
// Stack error types
/// Errors from stack operations (overflow, underflow)
pub const StackError = Stack.Error;
// Contract error types
/// General contract operation errors
pub const ContractError = Contract.ContractError;
/// Storage access errors
pub const StorageOperationError = Contract.StorageOperationError;
/// Bytecode analysis errors
pub const CodeAnalysisError = Contract.CodeAnalysisError;
/// Storage warming errors (EIP-2929)
pub const MarkStorageSlotWarmError = Contract.MarkStorageSlotWarmError;
// Access List error types (imported via import statement to avoid circular deps)
/// Access list module for EIP-2929/2930 support
const AccessListModule = @import("access_list/access_list.zig");
/// Error accessing addresses in access list
pub const AccessAddressError = AccessListModule.AccessAddressError;
/// Error accessing storage slots in access list
pub const AccessStorageSlotError = AccessListModule.AccessStorageSlotError;
/// Error pre-warming addresses
pub const PreWarmAddressesAccessListError = AccessListModule.PreWarmAddressesError;
/// Error pre-warming storage slots
pub const PreWarmStorageSlotsAccessListError = AccessListModule.PreWarmStorageSlotsError;
/// Error initializing transaction access list
pub const InitTransactionError = AccessListModule.InitTransactionError;
/// Error calculating call costs with access list
pub const GetCallCostAccessListError = AccessListModule.GetCallCostError;
// Address error types
/// Error calculating CREATE address
pub const CalculateAddressError = Address.CalculateAddressError;
/// Error calculating CREATE2 address
pub const CalculateCreate2AddressError = Address.CalculateCreate2AddressError;
// Execution error
/// Main execution error enumeration used throughout EVM
pub const ExecutionErrorEnum = ExecutionError.Error;
// Tests - run all module tests
test {
std.testing.refAllDeclsRecursive(@This());
}
```