# Edge Language > A domain specific language for the Ethereum Virtual Machine ## Introduction Edge is a domain-specific language for the Ethereum Virtual Machine (EVM): high-level, strongly statically typed, and designed to make smart contract development more expressive without giving up control over execution. It is the brainchild of [jtriley](https://github.com/jtriley-eth), to whom the current specifications are attributable. The Edge documentation is organized into the following sections: * [Specifications](/specs/overview): An in-depth blueprint to the Edge language, including syntax showcase examples. * [Compiler](/compiler/overview): The inner workings of the Rust compiler implementation. * [Tooling](/tools/overview): An overview of Edge tooling and other developer utilities. * [Contributing](/contributing/contributing): Repository contribution guidelines. * [Contact](/contact/contact): Methods of contacting the maintainers. ## Tooling overview Edge's tooling is centered around the compiler CLI, the installer, and the language server. ### `edgec` `edgec` is the main command-line entry point for the compiler. It can compile contracts directly to EVM bytecode or stop after earlier phases for inspection. ```bash edgec examples/counter.edge edgec lex examples/counter.edge edgec parse examples/counter.edge edgec check examples/counter.edge edgec lsp ``` #### Subcommands | Subcommand | Description | | -------------- | ------------------------------------------- | | `lex ` | Lex file and print tokens (debug output) | | `parse ` | Parse file and print AST (debug output) | | `check ` | Compile for errors without producing output | | `lsp` | Start the LSP server over stdin/stdout | #### Compiler flags | Flag / Option | Short | Default | Description | | ---------------- | ----- | ---------- | ------------------------------------------------------------------------------ | | `` | — | — | Source file to compile (outputs hex bytecode to stdout) | | `--output` | `-o` | — | Write raw bytecode bytes to file (requires FILE) | | `--emit ` | — | `bytecode` | `tokens` / `ast` / `ir` / `pretty-ir` / `asm` / `bytecode` | | `-O ` | — | `0` | Optimization level (0–3) | | `--optimize-for` | — | `gas` | Optimization target: `gas` or `size` | | `--std-path` | — | — | Filesystem stdlib path (also: `EDGE_STD_PATH` env var) | | `--verbose` | `-v` | — | Verbosity; repeat for more: `-v`=WARN, `-vv`=INFO, `-vvv`=DEBUG, `-vvvv`=TRACE | | `--version` | — | — | Print version and exit | | `--help` | `-h` | — | Print help | #### Verbosity levels | `-v` count | Log level | Notes | | ---------- | --------- | ----------------------------------------- | | 0 | (off) | No tracing output | | 1 | `WARN` | | | 2 | `INFO` | | | 3 | `DEBUG` | | | 4+ | `TRACE` | egglog also set to TRACE (otherwise WARN) | #### Emit output behavior | Emit | Stdout | File (`-o`) | | ----------- | ------------------------- | ----------- | | `tokens` | Debug print of each Token | — | | `ast` | Debug print of Program | — | | `ir` | S-expression format | — | | `pretty-ir` | Pretty-printed IR | — | | `asm` | Labeled block assembly | — | | `bytecode` | `0x` string | Raw bytes | ### `edgeup` `edgeup` is the Edge toolchain manager. Install it first, then use it to install and manage `edgec` versions. ```bash # 1. Install edgeup curl -fsSL https://raw.githubusercontent.com/refcell/edge-rs/main/etc/install.sh | sh # 2. Install the Edge compiler edgeup install ``` **Supported platforms:** Linux x86\_64, macOS x86\_64, macOS arm64. Windows is not supported. `edgeup` detects your shell (bash, zsh, or fish) and appends `~/.edgeup/bin` to your `PATH` in the appropriate RC file (`~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`). Restart your shell or run the printed `source` command after installation. #### Directory layout ``` ~/.edgeup/ bin/ edgec ← symlink → versions/{tag}/edgec versions/ v0.1.6/ edgec ← actual binary (chmod 755) v0.1.7/ edgec ``` #### `edgeup` subcommands | Subcommand | Description | | --------------------- | ----------------------------------------------------- | | `install [VERSION]` | Download and install Edge toolchain (default: latest) | | `update` | Alias for `install` — installs latest version | | `list` | List all installed versions | | `use ` | Switch active version (updates symlink) | | `uninstall [VERSION]` | Remove a version, or all if omitted | | `self-update` | Update `edgeup` itself to the latest release | | `version` | Print the `edgeup` version | ### LSP Edge ships an LSP server for editor integration: ```bash edgec lsp ``` The server communicates over stdin/stdout and provides parse and type-check diagnostics with precise source spans. :::warning Hover, completions, and go-to-definition are not yet implemented. The LSP currently only reports parse errors and type-check errors. ::: ### Repository utilities The repository ships a [`Justfile`](https://github.com/refcell/edge-rs/blob/main/Justfile) with common contributor workflows: | Command | Description | | --------------------- | -------------------------------------------- | | `just build` | Build all crates (`cargo build --workspace`) | | `just test` | Run all tests (`cargo test --workspace`) | | `just lint` | Run all lints (format, clippy, deny, docs) | | `just e2e` | Run end-to-end tests | | `just bench` | Run benchmarks | | `just docs` | Serve the Vocs documentation site locally | | `just docs-build` | Build the documentation site | | `just check-examples` | Parse all example contracts | | `just check-stdlib` | Parse all stdlib contracts | ### Reference material For runnable contracts and language samples, see the [`examples/`](https://github.com/refcell/edge-rs/tree/main/examples) and [`std/`](https://github.com/refcell/edge-rs/tree/main/std) directories. ## Built-in Built-in functionality refers to features available during compilation that are otherwise inaccessible through the language's regular syntax. The parser accepts any `@identifier` form without validation; unknown builtin names are caught during IR lowering (semantic analysis), not parsing. ### EVM environment builtins These builtins read EVM execution context values. Each compiles to a single `EnvRead` IR node and a corresponding EVM opcode: | Builtin | EVM opcode | Returns | | ----------------- | ---------------- | ------------------------------------- | | `@caller` | `CALLER` | Address of the direct caller | | `@callvalue` | `CALLVALUE` | Wei sent with the call | | `@value` | `CALLVALUE` | Alias for `@callvalue` | | `@calldatasize` | `CALLDATASIZE` | Size of calldata in bytes | | `@origin` | `ORIGIN` | Transaction originator address | | `@gasprice` | `GASPRICE` | Gas price of the transaction | | `@coinbase` | `COINBASE` | Current block's beneficiary address | | `@timestamp` | `TIMESTAMP` | Current block's timestamp | | `@number` | `NUMBER` | Current block number | | `@gaslimit` | `GASLIMIT` | Current block's gas limit | | `@chainid` | `CHAINID` | Chain ID (EIP-155) | | `@selfbalance` | `SELFBALANCE` | Balance of the executing contract | | `@basefee` | `BASEFEE` | Current block's base fee (EIP-1559) | | `@gas` | `GAS` | Remaining gas | | `@address` | `ADDRESS` | Address of the executing contract | | `@codesize` | `CODESIZE` | Size of the executing contract's code | | `@returndatasize` | `RETURNDATASIZE` | Size of the last call's return data | All EVM environment builtins are zero-argument. Parentheses are optional: both `@caller` and `@caller()` are valid. Arguments passed to them are currently ignored. ```edge fn checkCaller() { if @caller == 0x0000000000000000000000000000000000000000 { revert(); } } ``` ### Comptime builtins These builtins execute at compile time and are used for type introspection, compile-time assertions, and code generation. #### Types ```edge type PrimitiveType; type StructType; type UnionType; type FunctionType; type TypeInfo = | Primitive(PrimitiveType) | Struct(StructType) | Union(UnionType) | Function(FunctionType); ``` :::note `TypeInfo` does not include an `Enum` variant. In Edge, enums are a subset of union types (unions where no variant carries data). They are represented as `Union(UnionType)` in the type system — there is no distinct enum concept at the AST or IR level. ::: ```edge type HardFork = | Frontier | Homestead | Dao | Tangerine | SpuriousDragon | Byzantium | Constantinople | Petersburg | Istanbul | MuirGlacier | Berlin | London | ArrowGlacier | GrayGlacier | Paris | Shanghai | Cancun; ``` #### Functions ##### `@typeInfo` ```edge @typeInfo(typeSignature) -> TypeInfo; ``` Takes a single type signature as an argument and returns a `TypeInfo` union describing the kind of the type. ##### `@bitsize` ```edge @bitsize(typeSignature) -> u256; ``` Takes a single type signature as an argument and returns the bitsize of the underlying type. ##### `@fields` ```edge @fields(structType) -> [T, N]; ``` Takes a single `StructType` as an argument and returns an array of type signatures of length N, where N is the number of fields in the struct. ##### `@compilerError` ```edge @compilerError(errorMessage); ``` Emits a compile-time error with the provided message. Useful in `comptime` branches to enforce invariants. ##### `@hardFork` ```edge @hardFork() -> HardFork; ``` Returns the target hard fork from the compiler configuration as a `HardFork` union value. ##### `@bytecode` ```edge @bytecode(T -> U) -> Bytes; ``` Takes an arbitrary function and returns its compiled bytecode as a `Bytes` value. `Bytes` is an opaque compiler-internal type representing a sequence of raw bytes; it is not a user-definable Edge type. ## Inline assembly Edge supports inline EVM assembly for low-level control when the high-level language abstractions are insufficient. ### Opcodes The following EVM opcodes are accepted in inline assembly blocks. Opcode names are case-insensitive. **Arithmetic and logic:** `stop`, `add`, `mul`, `sub`, `div`, `sdiv`, `mod`, `smod`, `addmod`, `mulmod`, `exp`, `signextend`, `lt`, `gt`, `slt`, `sgt`, `eq`, `iszero`, `and`, `or`, `xor`, `not`, `byte`, `shl`, `shr`, `sar` **Cryptographic:** `keccak256` (alias: `sha3`) **Environment:** `address`, `balance`, `origin`, `caller`, `callvalue`, `calldataload`, `calldatasize`, `calldatacopy`, `codesize`, `codecopy`, `gasprice`, `extcodesize`, `extcodecopy`, `returndatasize`, `returndatacopy`, `extcodehash` **Block:** `blockhash`, `coinbase`, `timestamp`, `number`, `prevrandao` (alias: `difficulty`), `gaslimit`, `chainid`, `selfbalance`, `basefee`, `blobhash`, `blobbasefee` **Stack, memory, and storage:** `pop`, `mload`, `mstore`, `mstore8`, `sload`, `sstore`, `tload`, `tstore`, `mcopy` **Flow control:** `jump`, `jumpi`, `pc`, `msize`, `gas`, `jumpdest` **Push:** `push0`, `push1` through `push32` **Duplication:** `dup1` through `dup16` **Exchange:** `swap1` through `swap16` **Logging:** `log0`, `log1`, `log2`, `log3`, `log4` **System:** `create`, `call`, `callcode`, `return`, `delegatecall`, `create2`, `staticcall`, `revert`, `invalid`, `selfdestruct` In addition to mnemonics, numeric literals and identifiers are accepted (see grammar below). #### Grammar ``` ::= | | ; ``` Where `` is any of the opcodes listed above. ### Inline assembly block ``` ::= | "_" ; ::= "asm" "(" [ ("," )* [","]] ")" ["->" "(" [ ("," )* [","]] ")"] "{" ()* "}" ; ``` The `` consists of the `asm` keyword, followed by a parenthesized, comma-separated list of input expressions, an optional `-> (...)` clause listing output names, and a code block containing opcodes. The entire `-> (...)` clause may be omitted when no outputs are needed. ### Semantics Arguments are ordered such that the state of the stack at the start of the block, top to bottom, is the list of arguments, left to right. Identifiers in the output list are ordered such that the state of the stack at the end of the assembly block, top to bottom, is the list of outputs, left to right. ```edge asm (1, 2, 3) -> (a) { // stack: [1, 2, 3] add // [3, 3] mul // [9] } ``` #### Numeric literals Inside the assembly block, numeric literals are implicitly converted into `PUSH{N}` instructions. Literals are encoded in the smallest `N` by value, except that leading zeros in hex literals are preserved. For example, `0x0000` becomes `PUSH2 0x0000` to allow for bytecode padding. #### Identifiers Identifiers in the assembly body can be: * **Variables** — resolved to their stack position (scheduled by the compiler). Only compile-time constants and stack-allocated variables are supported; memory-backed variables must be passed as input arguments. * **Constants** — replaced with their `PUSH{N}` encoding, same as numeric literals. * **Opcode names** — treated as the corresponding EVM instruction (case-insensitive). #### Outputs * **Named outputs** (e.g., `a`) are bound as local variables accessible in subsequent code. * **Discarded outputs** (`_`) are popped from the stack. * **Multiple outputs** (N > 1) are stored to sequential memory slots internally and bound as `LetBind` variables via `MLOAD`. #### IR representation Inline assembly compiles to an `InlineAsm(inputs, hex_bytecode, num_outputs)` IR node. This node is opaque to the egglog optimizer — it passes through equality saturation unchanged. :::note If the input arguments contain local variables, the stack scheduling required to construct the pre-assembly stack state may be unprofitable for small assembly blocks. Consider passing values as immediate literals when possible. ::: ## Specifications ### All Edge, no drag. This document defines Edge, a domain-specific language for the Ethereum Virtual Machine (EVM). Edge is a high-level, strongly statically typed, multi-paradigm language. It provides: * A thin layer of abstraction over the EVM's instruction set architecture (ISA). * An extensible polymorphic type system with subtyping. * First-class support for modules and code reuse. * Compile-time code execution to fine-tune the compiler's input. Edge's syntax is similar to Rust and Zig where intuitive, however, the language is not designed to be a general-purpose language with EVM features as an afterthought. Rather, it extends the EVM instruction set with a reasonable type system and syntax sugar over universally understood programming constructs. #### Notation This specification uses a grammar similar to Extended Backus-Naur Form (EBNF) with the following rules: * Non-terminal tokens are wrapped in angle brackets ``. * Terminal tokens are wrapped in double quotes `"const"`. * Optional items are wrapped in brackets `["mut"]`. * Sequences of zero or more items are wrapped in parentheses and suffixed with a star `("," )*`. * Sequences of one or more items are wrapped in parentheses and suffixed with a plus `()+`. In contrast to EBNF, all items are non-atomic: arbitrary whitespace characters (`\n`, `\t`, `\r`) may surround all tokens unless wrapped with curly braces `{ "0x" ()* }`. Common abbreviations: * `ident` — identifier * `expr` — expression * `stmt` — statement #### Disambiguation ##### Return vs return The word "return" refers to two different behaviors: returned values from expressions and the halting return opcode. When "return" is used, this refers to the values returned from expressions — the values left on the stack, if any. When "halting return" is used, this refers to the EVM opcode `RETURN` that halts execution and returns a value from a slice of memory to the caller of the current execution context. ## Comments ```text ::= "//" (!"\n" )* "\n" ; ::= "/*" (!"*/" | )* "*/" ; ::= "///" (!"\n" )* "\n" ; ::= "//!" (!"\n" )* "\n" ; ``` The `` is a single-line comment, ignored by the parser. The `` is a multi-line comment, ignored by the parser. Block comments may be nested; the lexer tracks depth to find the matching close (`/* /* inner */ outer still open */` is valid). The `` is a developer documentation comment, treated as documentation for the immediately following item. The `` is a developer documentation comment, treated as documentation for the module in which it is defined. Developer documentation comments are treated as GitHub-flavored markdown. :::note Unlike regular comments, `DocComment` tokens (`///` and `//!`) are **retained** by the parser and associated with the item or module they document. Tooling that consumes the parse tree (e.g. doc generators) will find doc comments there; plain `//` and `/* */` comments are dropped before the parser ever runs. ::: ## Expressions ```text ::= | | | | | | | | | | | | | | | | | | | | | "(" ")" ; ``` An `` is any construct that produces a value. ### Binary operations ```text ::= ; ``` Binary operations use an infixed operator between two sub-expressions. See [operators](./operators) for the full operator table and precedence. ### Unary operations ```text ::= ; ``` Prefix unary operators: `-` (negation), `~` (bitwise NOT), `!` (logical NOT). ### Ternary ```text ::= "?" ":" ; ``` The ternary operator is right-associative. Both branches are full expressions. ### Literals The `` non-terminal is defined in [Literals](/specs/syntax/compile/literals). In expression context, the following additional details apply: * Integer literals support `_` as a visual separator (e.g. `1_000_000`). Type suffixes (e.g. `42u8`, `256u16`) are recognized by the lexer but currently silently discarded — the type is inferred from context or defaults to `u256`. * String literals use either double or single quotes. Supported escape sequences: `\n`, `\t`, `\r`, `\\`, `\"`, `\'`. * Hex and binary literals produce byte-array values (`Lit::Hex` and `Lit::Bin` respectively). ### Function calls ```text ::= ["::" "<" ("," )* ">"] "(" [ ("," )*] ")" ; ``` Functions are called with parenthesized argument lists. Turbofish syntax (`::`) provides explicit type arguments. ### Field and index access ```text ::= "." ; ::= "." + ; ::= "[" [":" ] "]" ; ``` Dot access resolves struct fields by name or tuple fields by numeric index. Array indexing supports both single-element access (`arr[i]`) and slicing (`arr[start:end]`). ### Instantiation ```text ::= [] "{" ":" ("," ":" )* "}" ; ::= [] "(" [ ("," )*] ")" ; ::= [] "[" [ ("," )*] "]" ; ::= "::" "(" [ ("," )*] ")" ; ``` Struct, tuple, and array instantiations may be prefixed with a `` annotation. Union variants are instantiated with path syntax (`Type::Variant(args)`). ### Pattern matching expression ```text ::= "matches" "::" ["(" ("," )* ")"] ; ``` The `matches` keyword tests whether an expression matches a union variant, optionally binding the variant's payload to identifiers. Commonly used in `if` conditions. ### Arrow functions ```text ::= ( | "(" [ ("," )*] ")") "=>" ; ``` Arrow functions (closures) take identifier parameters and a brace-delimited body. ### Compile-time expressions ```text ::= "comptime" "(" ")" ; ``` Wraps an expression for compile-time evaluation. ### Path expressions ```text ::= ("::" )+ ; ``` Double-colon-separated identifier paths, used for module paths and union variant access. ### Builtin calls ```text ::= "@" ["(" [ ("," )*] ")"] ; ``` The `@` sigil invokes compiler builtins. The parser accepts any identifier after `@`; validation of builtin names happens in later compiler stages. ### Assignment expression ```text ::= "=" ; ``` Assignment at the expression level (precedence 0, right-associative). Produces `Expr::Assign`. ### Inline assembly ```text ::= "asm" "(" [ ("," )*] ")" ["->" "(" [ ("," )*] ")"] "{" * "}" ; ::= | | ; ``` Inline assembly provides direct access to EVM opcodes. Inputs are pushed onto the stack (leftmost = top of stack). Outputs are optionally bound to identifiers; use `_` to discard a stack value. ## Identifiers ```text ::= ( | "_") ( | | "_")* ; ``` Dependencies: * `` * `` The `` is a C-style identifier, beginning with an alphabetic character or underscore, followed by zero or more alphanumeric or underscore characters. ### Reserved names Identifiers share their lexical space with keywords, primitive type names, and boolean literals. The lexer resolves ambiguity in the following priority order: 1. **EVM primitive type** — `u8`–`u256`, `i8`–`i256`, `b1`–`b32`, `addr`, `bool`, `bit` 2. **Keyword** — e.g. `let`, `fn`, `contract`, `mod`, `use`, `mut`, `pub`, `Self`, … 3. **Boolean literal** — `true`, `false` 4. **Identifier** — everything else Any string that matches a higher-priority rule will **never** produce an `Ident` token. In particular, `Self` (capital S) is a reserved keyword and cannot be used as a plain identifier. ### Special identifiers The parser accepts `self` and `super` as identifiers in certain contexts (e.g. module paths, method receivers). These are keywords but are returned as identifier nodes with the names `"self"` and `"super"` respectively. ## Data locations ```text ::= "&s" ; ::= "&t" ; ::= "&m" ; ::= "&cd" ; ::= "&rd" ; ::= "&ic" ; ::= "&ec" ; ::= | | | | | | | ; ``` The `` is a pointer annotation indicating which EVM data region a value resides in. Edge defines seven distinct location annotations. This is a divergence from general-purpose programming languages to more accurately represent the EVM execution environment. * `&s` — persistent storage * `&t` — transient storage (EIP-1153) * `&m` — memory * `&cd` — calldata * `&rd` — returndata * `&ic` — internal (local) code * `&ec` — external code :::note The `&` character is heavily overloaded in the lexer. It checks for data-location sigils first (`&s`, `&t`, `&m`, `&cd`, `&rd`, `&ic`, `&ec`), then `&=`, then `&&`, and finally falls back to bitwise AND. ::: ### Semantics Data locations can be grouped into two broad categories: buffers and maps. #### Maps Persistent and transient storage are part of the map category — 256-bit keys map to 256-bit values. Both may be written or read one word at a time. #### Buffers Memory, calldata, returndata, internal code, and external code are all linear data buffers. All can be either read to the stack or copied into memory, but only memory can be written or copied to. | Name | Read to stack | Copy to memory | Write | | ------------- | ------------- | -------------- | ----- | | memory | yes | yes | yes | | calldata | yes | yes | no | | returndata | no | yes | no | | internal code | no | yes | no | | external code | no | yes | no | #### Transitions Transitioning from map to memory buffer is performed by loading each element from the map to the stack and storing each stack item in memory O(N). Transitioning from memory buffer to a map is performed by loading each element from memory to the stack and storing each stack item in the map O(N). Transitioning from any other buffer to a map is performed by copying the buffer's data into memory then transitioning the data from memory into the map O(N+1). #### Pointer bit sizes Pointers to different data locations consist of different sizes based on the properties of that data location. In-depth semantics of each data location are specified in the type system documents. | Location | Bit size | Reason | | ------------------ | -------- | ------------------------------------------------------- | | persistent storage | 256 | Storage is a 256-bit key–value hashmap | | transient storage | 256 | Transient storage is a 256-bit key–value hashmap | | memory | 32 | Theoretical maximum memory size does not approach 2³² | | calldata | 32 | Theoretical maximum calldata size does not approach 2³² | | returndata | 32 | Maximum returndata size equals maximum memory size | | internal code | 16 | Code size is less than 0xFFFF | | external code | 176 | Contains 160-bit address and 16-bit code pointer | ## Modules ### Declaration ```text ::= ["pub"] "mod" (";" | "{" [] * "}") ; ``` Dependencies: * `` * `` * `` The `` is composed of an optional `pub` prefix, the `mod` keyword followed by an identifier, then either a semicolon (external/bodyless form) or a body delimited by curly braces. The bodyless form (`mod name;`) declares an external module whose content lives in a file with a matching name. ### Import ```text ::= "*" | ( "::" ( | "{" ("," )* [","] "}" | ) )* ; ::= ["pub"] "use" ["::" ] ";" ; ``` Dependencies: * `` The `` is a recursive production, containing either a wildcard (`*`), another module import item, or a comma-separated list of module import items delimited by curly braces. The `` is an optional `pub` annotation followed by `use`, the root module name, then optional path segments. :::warning Neither `pub mod` nor `pub use` is currently implemented. The parser's `parse_pub()` function only dispatches to `fn` and `contract` declarations, so the `pub` modifier before `mod` or `use` is silently ignored. Use plain `mod` and `use` for all module declarations and imports. ::: ### Semantics Namespace semantics in modules are defined in the namespace document. Visibility semantics in modules are defined in the visibility document. Modules can contain developer documentation, declarations, and assignments. If the module contains developer documentation, it must be the first item in the module. This is for readability. Files are implicitly modules with a name equivalent to the file name. Type, function, ABI, and contract declarations must be assigned in the same module. However, traits are declared without assignment and submodules may be declared without a block only if there is a file with a matching name. The `super` identifier represents the direct parent module of the module in which it is invoked. ## Operators Operators are syntax sugar over built-in functions. Operator overloading is disallowed. ### Binary operators ```text ::= | "+" | "-" | "*" | "/" | "%" | "**" ; ::= | "&" | "|" | "^" | "<<" | ">>" ; ::= | "==" | "!=" | "<" | "<=" | ">" | ">=" ; ::= | "&&" | "||" ; ::= | "+=" | "-=" | "*=" | "/=" | "%=" | "**=" | "&=" | "|=" | "^=" | "<<=" | ">>=" ; ::= | | | | | ; ``` ### Unary operators ```text ::= "-" ; ::= "~" ; ::= "!" ; ::= | | | ; ``` ### Precedence The expression parser uses precedence climbing (Pratt parsing). Lower numbers bind less tightly: | Precedence | Operators | Associativity | | ---------- | ----------------- | ------------- | | 0 | `=` | Right | | 1 | `\|\|` | Left | | 2 | `&&` | Left | | 3 | `==` `!=` | Left | | 4 | `<` `>` `<=` `>=` | Left | | 5 | `\|` (bitwise OR) | Left | | 6 | `^` (bitwise XOR) | Left | | 7 | `&` (bitwise AND) | Left | | 8 | `<<` `>>` | Left | | 9 | `+` `-` | Left | | 10 | `*` `/` `%` | Left | | 11 | `**` | Right | The ternary operator (`? :`) is parsed after the Pratt binary expression, with right-to-left associativity. Compound assignment operators (`+=`, `-=`, etc.) are parsed as binary operations and produce `Expr::Binary` nodes with the corresponding `BinOp` variant. ### Semantics | Operator | Types | Behavior | Panic case | | ------------ | -------- | ---------------------- | -------------- | | `+` | integers | checked addition | overflow | | `-` (binary) | integers | checked subtraction | underflow | | `-` (unary) | integers | checked negation | overflow | | `*` | integers | checked multiplication | overflow | | `/` | integers | checked division | divide by zero | | `%` | integers | checked modulus | divide by zero | | `**` | integers | exponentiation | — | | `&` | integers | bitwise AND | — | | `\|` | integers | bitwise OR | — | | `~` | integers | bitwise NOT | — | | `^` | integers | bitwise XOR | — | | `>>` | integers | bitwise shift right | — | | `<<` | integers | bitwise shift left | — | | `==` | any | equality | — | | `!=` | any | inequality | — | | `&&` | booleans | logical AND | — | | `\|\|` | booleans | logical OR | — | | `!` | booleans | logical NOT | — | | `>` | integers | greater than | — | | `>=` | integers | greater than or equal | — | | `<` | integers | less than | — | | `<=` | integers | less than or equal | — | ## Syntax Conceptually, all EVM contracts are single-entry point executables and at compile time, Edge programs are no different. Other languages have used primarily the contract-is-an-object paradigm, mapping fields to storage layouts and methods to "external functions" that may read and write the storage. Inheritance enables interface constraints, code reuse, and a reasonable model for message passing that relates to the EVM external call model. However, this is limited in scope. Conceptually, the contract object paradigm groups stateful data and functionality, limiting the deployability to the product type. Extending the deployability to arbitrary data types allows for contracts to be functions, type unions, product types, and more. While most of these are not particularly useful, this simplifies the type system as well as opens the design space to new contract paradigms. The core syntax of Edge is derived from commonly used patterns in modern programming. Functions, branches, and loops are largely intuitive for engineers with experience in C, Rust, Javascript, etc. Parametric polymorphism uses syntax similar to Rust and Typescript. Compiler built-in functions and "comptime" constructs follow the syntax of Zig. ### Top-level items An Edge source file is a sequence of top-level declarations. The following item kinds are supported at the top level: | Keyword | Form | Purpose | | ---------- | ------------------------------- | ------------------------- | | `contract` | `contract Name { … }` | Contract definition | | `fn` | `fn name(…) [-> T] { … }` | Free function | | `const` | `const NAME[: T] = expr;` | Compile-time constant | | `let` | `let [mut] name[: T] [= expr];` | Variable declaration | | `type` | `type Name[] = …;` | Type alias or union type | | `trait` | `trait Name[] { … }` | Trait definition | | `impl` | `impl Type[:Trait] { … }` | Implementation block | | `abi` | `abi Name { … }` | ABI interface declaration | | `event` | `event Name(…);` | Event declaration | | `mod` | `mod name;` / `mod name { … }` | Module declaration | | `use` | `use root::path;` | Module import | Functions and declarations may be prefixed with `pub` (public visibility). See the sub-pages for the full grammar of each item kind. ### Keywords Edge reserves the following 33 keywords: **Declaration:** `contract`, `type`, `const`, `fn`, `packed`, `trait`, `impl`, `mod`, `use`, `abi`, `event` **Modifiers:** `pub`, `mut`, `ext`, `indexed`, `anon`, `comptime` **Control flow:** `return`, `if`, `else`, `match`, `matches`, `for`, `while`, `loop`, `do`, `break`, `continue` **Variables / scope:** `let`, `Self`, `super` **Side effects / assembly:** `emit`, `asm` ## Statements ```text ::= | | | | | | | | | | | | | | | | | | | | | | | | | | | | ";" ; ``` A `` is a language construct that does not itself produce a value (unlike an expression). The top-level parse loop collects statements until EOF. ### Control flow statements ```text ::= "return" [] ";" ; ::= "break" ";" ; ::= "continue" ";" ; ``` ### Code blocks ```text ::= "{" ( | ";")* [] "}" ; ``` A code block is a brace-delimited sequence of statements. The final item may be a bare expression without a trailing semicolon (tail expression), which becomes the block's value — similar to Rust. :::note At the AST level, tail expressions are wrapped as `BlockItem::Stmt(Stmt::Expr(…))`. There is no distinct AST node for tail expressions; the semantic difference is inferred from position. ::: ### If / else ```text ::= "if" "(" ")" ("else" "if" "(" ")" )* ["else" ] ; ::= "if" "matches" "::" ["(" ("," )* ")"] ; ``` The standard `if`/`else if`/`else` chain uses parenthesized conditions and brace-delimited bodies. The `if … matches` form combines a conditional with union pattern destructuring. :::note The `Stmt::IfMatch` variant exists in the AST, but the current parser produces `Stmt::IfElse` with an `Expr::PatternMatch` as the condition instead. The dedicated variant is reserved for future use. ::: ### Match ```text ::= "match" "{" ("," )* [","] "}" ; ::= "=>" ( | | "return" []) ; ::= | | "_" ; ::= "::" ["(" ("," )* ")"] ; ``` Match arms accept a code block, a bare expression, or a `return` statement as the body. At the AST level, all arm bodies are normalized to `CodeBlock`. ### Loops ```text ::= "loop" ; ::= "for" "(" [ | ] ";" [] ";" [ | ] ")" ; ::= "while" "(" ")" ; ::= "do" "while" "(" ")" ";" ; ::= "{" ( | ";" | "break" ";" | "continue" ";")* "}" ; ``` The `` uses a separate AST type (`LoopBlock` / `LoopItem`) from regular code blocks. `break` and `continue` have dedicated `LoopItem` variants in addition to the `Stmt::Break` / `Stmt::Continue` variants used outside loops. :::warning `break` and `continue` are parsed but not yet implemented in the compiler backend. They will silently compile as if the statement were absent. ::: ### Contracts ```text ::= "contract" "{" * "}" ; ::= | "let" ":" ";" | "const" [":" ] "=" ";" | ["pub"] ["ext"] ["mut"] "fn" "(" [] ")" ["->" ] ; ::= "impl" [":" ] "{" * "}" ; ``` Contract bodies contain storage field declarations (`let`), constants, and function definitions. The `impl` block provides the implementation for a contract, optionally satisfying an ABI interface. ### Functions ```text ::= ["pub"] ["ext"] ["mut"] "fn" ["<" ("," )* ">"] "(" [] ")" ["->" ] ; ::= ":" ("," ":" )* ; ::= | "(" ("," )* ")" ; ::= [":" ("&" )*] ; ``` Functions support generic type parameters with trait bounds (``). The `self` keyword may appear as the first parameter without a type annotation (implicit `Self` type). Return types can be a single type or a tuple. Visibility and modifier flags: * `pub` — public visibility * `ext` — external ABI entry point * `mut` — may mutate contract state ### Type aliases ```text ::= "type" ["<" ("," )* ">"] "=" ";" ; ::= | ; ::= ["|"] ("|" )+ ; ::= ["(" ")"] ; ``` Type aliases bind a name to a type signature or a union type. Union types define sum types with named variants that optionally carry a payload. ### Traits and implementations ```text ::= "trait" ["<" ("," )* ">"] [":" ("+" )*] "{" * "}" ; ::= | "fn" "(" [] ")" ["->" ] (";" | ) | "const" ":" ["=" ] ";" | "type" ["=" ] ";" ; ::= "impl" ["<" ("," )* ">"] [":" ["<" ("," )* ">"]] "{" * "}" ; ::= | ["pub"] "fn" "(" [] ")" ["->" ] | ["pub"] "const" ":" "=" ";" | ["pub"] "type" "=" ";" ; ``` Traits declare abstract interfaces with optional default implementations. Supertraits use `+` syntax: `trait Ordered: Comparable + Displayable { … }`. Implementation blocks provide concrete implementations for types, optionally satisfying a trait: `impl Type : Trait { … }`. ### ABI declarations ```text ::= "abi" [":" ("+" )*] "{" * "}" ; ::= ["mut"] "fn" "(" [] ")" ["->" ] ";" ; ``` ABI declarations define external interfaces. They are similar to traits but specific to the EVM calling convention. Superabis are supported with the same `+` syntax as supertraits. ### Events and emit ```text ::= ["anon"] "event" "(" [ ("," )*] ")" ";" ; ::= ["indexed"] ":" ; ::= "emit" "(" [ (","