Markdown Converter
Agent skill for markdown-converter
- **Jet** is an LLVM-based JIT compiler for the Ethereum Virtual Machine (EVM)
Sign in to like and favorite skills
inkwell bindings)Root files:
Cargo.toml (workspace manifest with 4 members)Makefile (build automation, exports LLVM env vars).cargo/config.toml (Android/Termux linker flags)rust-toolchain.toml (pins stable Rust channel)README.md, DEVELOPMENT.md (getting started, dev workflow).nextest.toml (cargo-nextest test runner config)Workspace members (4 crates):
crates/jet - Main compiler crate
builder/{contract,env,manager,ops}.rs, engine/mod.rs, instructions.rsbin/jetdbg.rs (debugger/executor)tests/test_roms.rs (EVM opcode integration tests)crates/jet_runtime - Runtime execution context
["dylib", "lib"]{lib,exec,builtins,symbols}.rs, binding/mod.rscrates/jet_ir - Shared LLVM IR types
crates/jet_push_macros - Procedural macros
Scripts:
scripts/{detect-llvm,detect-platform,install-llvm,llvm}.sh
Documentation:
docs/ (see Key Documentation section)
CI:
.github/workflows/ci.yml (GitHub Actions, see CI/CD section)
crates/jet/src/:
lib.rs - Public API exportsinstructions.rs - EVM instruction enum and opcode mappingsbuilder/contract.rs - Bytecode chunking, CFG construction, jump tablesbuilder/ops.rs - LLVM IR generation for each EVM opcodebuilder/env.rs - Compilation environment (types, symbols, modes)builder/manager.rs - Build orchestrationengine/mod.rs - LLVM ORC JIT engine, symbol resolutionbin/jetdbg.rs - CLI debugger for EVM contractscrates/jet_runtime/src/:
builtins.rs - Complex operations implemented in Rust (EXP, KECCAK256, etc.)exec.rs - Execution context (stack, memory, storage, logs)symbols.rs - Runtime symbol name constantsruntime_builder.rs - LLVM IR declarations for runtime functionsrust-toolchain.toml)scripts/detect-llvm.sh finds /usr/lib/llvm-21LLVM_SYS_211_PREFIX automaticallyinkwell - Git dependency with llvm21-1-prefer-dynamic featurellvm-sys - Expects llvm-config-21 or LLVM_SYS_211_PREFIXinkwell (Git: TheDan64/inkwell, branch with LLVM 21 support)sha3, bnum (256-bit arithmetic), hexclap (derive), colored, syntect (syntax highlighting)serde, serde_json, bincodelog, simple_loggerthiserrorscripts/detect-platform.sh branches by platform.cargo/config.toml contains linker flagsCARGO_TARGET_DIR relocated to /data/data/com.termux/files/home/.cargo/jet-targetALWAYS run this before any cargo command:
make install-llvm
This:
scripts/detect-platform.shsudo for system package installationFailure symptoms if LLVM missing:
cargo check fails with: No suitable version of LLVM was found system-wide or pointed to by LLVM_SYS_211_PREFIXllvm-sys build script cannot find llvm-config-21Verification:
bash scripts/detect-llvm.sh # Should output: /usr/lib/llvm-21 which llvm-config-21 # Should find executable
# Standard workflow make check # cargo check --all-targets --all-features (fastest validation) make build # cargo build make fmt # cargo fmt --all (auto-format) make clippy # cargo clippy --all-targets --all-features -- -D warnings (strict) # Combined pre-push check make commit-check # Runs: fmt-check, check, clippy, test-all make ci # Alias for commit-check (mirrors CI pipeline)
Note:
make commit-check is the recommended pre-push command - it runs all CI checks locally.
Test infrastructure:
cargo-nextest (faster, better output than cargo test)make install-tools or cargo install cargo-nextest --locked.nextest.tomlTest commands:
make test # cargo nextest run --all-features (fastest) make test-cargo # cargo test --all-features (fallback if nextest unavailable) make doctest # cargo test --doc --all-features (nextest doesn't support doctests) make test-all # Runs both: nextest + doctests
Test structure:
crates/jet/tests/test_roms.rs - Main EVM opcode integration tests
rom_tests! macro to define test casescrates/jet/tests/invalid_opcode.rs - Error handling tests# Check formatting (CI enforced) make fmt-check # cargo fmt --all -- --check # Auto-format (CI will auto-commit this) make fmt # cargo fmt --all # Lint (strict mode) make clippy # -D warnings (all warnings are errors in CI) # Auto-fix clippy issues make clippy-fix # cargo clippy --fix
Clippy notes:
-D warnings (zero-warning policy)#[allow(...)] pragmas without explicit permission. Fix the underlying issue or report why it should be allowed..github/workflows/ci.ymlmaster/main, PRs to master/main/ts/*, manual dispatchubuntu-latest (single sequential job)contents: write (for auto-commit formatting fixes)LLVM_SYS_211_PREFIX, include paths)cargo fmt --all)-D warnings)cargo check)cargo build --verbose --all-features)--no-fail-fast)cargo test --doc)cargo fmt changes and pushes backRUSTFLAGS="-D warnings" environment variableCARGO_TERM_COLOR=always # Colored output RUST_BACKTRACE=1 # Full backtraces on panic CARGO_INCREMENTAL=0 # Disable incremental (CI optimization) RUSTFLAGS="-D warnings" # Treat warnings as errors
Architecture & design:
docs/architecture.md - Complete system architecture (compilation pipeline, memory model, CFG)docs/bytecode-to-llvm-blocks.md - Bytecode chunking, jump tables, CodeBlock lifecycledocs/jet-description.md - High-level project descriptiondocs/manifesto.md - Design philosophyDevelopment guides:
DEVELOPMENT.md - Toolchain setup, workflow, CI detailsdocs/process/new-opcode.md - CRITICAL: Step-by-step opcode implementation guide
docs/process/segfault-troubleshooting.md - Debugging and reporting segfaults (P0 priority)ADRs (Architecture Decision Records):
docs/adrs/adr-001.md, adr-002.md, adr-003.md, adr-004.md - Design decisions with rationaleEVM spec references:
evm-spec-lookup skill if available for EVM opcode specificationsHistorical:
docs/plans/2026-01-27-restore-build-system.md - Build system restoration notesfrom_le_bytes()bnum::U256::from_digits([u64; 4]) with u64::from_le_bytes()// Always use helper functions (never manipulate stack directly) let (a, b) = stack_pop_2(bctx)?; // Returns (top, second) stack_push_int(bctx, result)?; // Push integer stack_push_ptr(bctx, ptr)?; // Push pointer
CRITICAL:
stack_pop_2() returns (top, second) where top is most recently pushed.
For SUB: PUSH 3; PUSH 10; SUB → pops (10, 3) → computes 10 - 3 = 7 (NOT 3 - 10).
EVM requirement: Division/modulo by zero MUST return 0 (not undefined behavior).
// WRONG - LLVM poison value on zero divisor let result = bctx.builder.build_int_unsigned_div(a, b, "div")?; // ALSO WRONG - select still evaluates both arms, causing poison let zero = bctx.env.types().i256.const_zero(); let b_is_zero = bctx.builder.build_int_compare(IntPredicate::EQ, b, zero, "b_is_zero")?; let div_result = bctx.builder.build_int_unsigned_div(a, b, "div")?; let result = bctx.builder.build_select(b_is_zero, zero, div_result, "final")?;
CORRECT approach: Use explicit branching (see below).
Applies to: DIV, MOD, SDIV, SMOD, and any division-like operations.
conditional_branch for zero checks (not select)select, causing poison on div-by-zerobuilder/ops.rsbuild_zero_guard() helper for division-by-zero handling// CORRECT: Create blocks for explicit branching let zero_block = bctx .env .context() .append_basic_block(bctx.func, "zero"); let nonzero_block = bctx .env .context() .append_basic_block(bctx.func, "nonzero"); let cont = bctx .env .context() .append_basic_block(bctx.func, "cont"); // Conditional branch based on divisor bctx.builder.build_conditional_branch(b_is_zero, zero_block, nonzero_block)?; // In zero_block: push zero and jump to cont bctx.builder.position_at_end(zero_block); stack_push_int(bctx, zero)?; bctx.builder.build_unconditional_branch(cont)?; // In nonzero_block: compute and push result, jump to cont bctx.builder.position_at_end(nonzero_block); let result = bctx.builder.build_int_unsigned_div(a, b, "div")?; stack_push_int(bctx, result)?; bctx.builder.build_unconditional_branch(cont)?; // Continue from cont bctx.builder.position_at_end(cont);
Always expand memory before access:
let offset_i32 = load_i32(bctx, offset_ptr)?; let size = bctx.env.types().i32.const_int(SIZE, false); bctx.builder.build_call( bctx.env.symbols().mem_expand(), &[bctx.registers.exec_ctx.into(), offset_i32.into(), size.into()], "expand", )?;
memory_len monotonicallyRust side (
crates/jet_runtime/src/builtins.rs):
pub extern "C" fn jet_ops_exp(base_ptr: &mut [u8; 32], exp_ptr: &[u8; 32]) -> i8 { // Little-endian representation let base = U256::from_digits([...]); let exp = U256::from_digits([...]); let result = base.pow(exp); // Write result back to base_ptr 0 // Success return code }
LLVM IR declaration (
crates/jet_runtime/src/runtime_builder.rs):
self.module.add_function( "jet.ops.exp", self.types.i8.fn_type(&[self.types.ptr.into(), self.types.ptr.into()], false), None, );
Symbol registration (
crates/jet/src/builder/env.rs):
pub(crate) struct Symbols<'ctx> { exp: FunctionValue<'ctx>, }
JIT linking (
crates/jet/src/engine/mod.rs):
map_fn(sym.exp(), builtins::jet_ops_exp as *const () as usize);
For complete implementation guidance, see
docs/process/new-opcode.md. Key steps:
evm-spec-lookup skill if available; understand operand order and edge casesInstruction enum in instructions.rsbuilder/ops.rsbuilder/mod.rsmake test or make test-cargomake commit-check (fmt, clippy, tests)# Symptom cargo check # Error: No suitable version of LLVM was found # Solution 1: Install LLVM make install-llvm # Solution 2: Verify detection bash scripts/detect-llvm.sh # Should output: /usr/lib/llvm-21 # Solution 3: Manual env var export LLVM_SYS_211_PREFIX=/usr/lib/llvm-21 cargo check
# Symptom make test # Error: no such command: `nextest` # Solution: Install nextest make install-tools # Or: cargo install cargo-nextest --locked # Workaround: Use cargo test instead make test-cargo
CRITICAL: Test segfaults are P0 priority issues that must be addressed immediately.
For complete troubleshooting guidance, see
docs/process/segfault-troubleshooting.md.
Quick reference:
# Run with debug output RUST_LOG=debug cargo test # Run single test to isolate cargo test --test test_roms -- test_name --exact # Use jetdbg for interactive debugging cargo run --bin jetdbg
Required action:
# Symptom: Tests fail after fixing implementation # Solution: Clean rebuild rm -rf target # Or on Termux: rm -rf /data/data/com.termux/files/home/.cargo/jet-target cargo test
# Symptom: CI fails on clippy step with warnings # Solution: Fix locally make clippy # See warnings make clippy-fix # Auto-fix some issues # CRITICAL: Do NOT add #[allow(...)] pragmas without explicit permission # You must fix the underlying issue or report why it should be allowed
# The CI auto-commits formatting changes # If you see unexpected formatting: # 1. Pull latest from remote (CI may have pushed formatting fixes) git pull # 2. Run fmt locally before committing make fmt # 3. Check fmt before pushing make fmt-check
Termux (Android):
gcc-default and ndk-multilib-native-static packagesmake install-llvm (handles platform detection)/data/data/com.termux/files/home/.cargo/jet-target (not ./target)macOS:
scripts/detect-platform.sh → darwin branchUnsupported platforms:
scripts/detect-platform.sh will error with clear messageAll previously known bugs have been resolved. Any new segfaults or bugs discovered must be reported immediately as P0 issues.
instructions.rs)Follow conventional commits:
feat: implement OPCODE (0xHH) fix: correct stack order in OPCODE docs: update architecture documentation test: add edge case for OPCODE refactor: simplify LLVM IR generation chore: update dependencies
docs/process/new-opcode.md for detailed implementation guidancebuilder/ops.rs for patternscrates/jet_runtime/src/builtins.rsevm-spec-lookup skill if available for EVM opcode specifications# One-time setup make install-llvm # Bootstrap LLVM 21 (required first) make install-tools # Install cargo-nextest (optional but recommended) # Daily workflow make fmt # Format code make check # Fast validation make clippy # Lint make test # Run tests (requires nextest) make test-cargo # Run tests (fallback, no nextest needed) make commit-check # Full pre-push validation # Debugging cargo run --bin jetdbg # Run debugger/executor RUST_LOG=debug cargo test # Verbose test output
crates/jet/src/builder/ops.rs → Opcode implementations crates/jet/src/instructions.rs → Instruction enum crates/jet_runtime/src/builtins.rs → Complex operations (Rust) crates/jet/tests/test_roms.rs → Integration tests docs/process/new-opcode.md → Implementation guide docs/process/segfault-troubleshooting.md → Segfault debugging (P0) .github/workflows/ci.yml → CI pipeline
export LLVM_SYS_211_PREFIX=/usr/lib/llvm-21 # Manual LLVM path export RUST_BACKTRACE=1 # Full backtraces (default in Makefile) export RUST_LOG=debug # Verbose logging export CARGO_TARGET_DIR=/custom/path # Override target directory
Last updated: 2026-02-16
LLVM version: 21
Rust edition: 2024 (jet, jet_runtime, jet_ir, jet_push_macros)
Test runner: cargo-nextest (recommended) or cargo test (fallback)