ethnum

This crate provides implementations for 256-bit integers, the primitive integer type in Ethereum. This implementation is meant to be as close as possible to Rust integer primitives, implementing the same methods and traits.

Usage

Add this to your Cargo.toml:

ethnum = "1"

The API follows the Rust {i,u}N primitive types as close as possible.

Features

macros:

The macros feature adds 256-bit integer literal support. This allows you to specify 256-bit signed and unsigned integer literals (that can, for example, be used as consts) that are larger than the largest native integer literal (i128::MIN and i128::MAX for signed integers and u128::MAX for unsigned integers).

ethnum = { version = "1", features = ["macros"] }

And then:

int!("-57896044618658097711785492504343953926634992332820282019728792003956564819968");
int!("57896044618658097711785492504343953926634992332820282019728792003956564819967");
uint!("115792089237316195423570985008687907853269984665640564039457584007913129639935");

Note that these literals support prefixes (0b for binary, 0o for octal, and 0x for hexadecimal) as well as _ and whitespace separators:

int!("-0b1010101010101010101010101010101010101010101010101010101010101010
         0101010101010101010101010101010101010101010101010101010101010101");
int!("0o 0123 4567");
uint!("0xffff_ffff");

serde

The serde feature adds support for serde serialization and deserialization. By default, the 256-bit integer types are serialized as prefixed hexadecimal strings. Various serialization helpers are also provided for more fine-grained control over how serialization is performed.

Intrinsics

The 256-bit integers uses intrinsics based on two implementations:

Native Rust Implementation

The integer intrinsics are implemented using standard Rust. The more complicated operations such as multiplication and division are ported from C compiler intrinsics for implementing equivalent 128-bit operations on 64-bit systems (or 64-bit operations on 32-bit systems). In general, these are ported from the Clang compiler-rt support routines.

This is the default implementation used by the crate, and in general is quite well optimized. When using native the implementation, there are no additional dependencies for this crate.

LLVM Generated Implementation

Alternatively, ethnum can use LLVM-generated intrinsics for base 256-bit integer operations. This takes advantage of the fact that LLVM IR supports arbitrarily sized integer operations (such as @llvm.uadd.with.overflow.i256 for overflowing unsigned addition). This will produce more optimized assembly for things like addition and multiplication.

However, there are a couple downsides to using LLVM-generated intrinsics. First of all, Clang is required in order to compile the LLVM IR. Additionally, Rust usually optimizes when compiling and linking Rust code (and not externally linked code), this means that these intrinsics cannot be inlined adding an extra function call overhead in some cases which make it perform worse than the native Rust implementation despite having more optimized assembly. Luckily, Rust currently has support for linker plugin LTO to enable optimizations during the link step, enabling optimizations with Clang-compiled LLVM IR.

In order to use LLVM-generated intrinsics, enable the llvm-intrinsics feature:

ethnum = { version = "1", features = ["llvm-intrinsics"] }

And, genererally it is a good idea to compile with linker-plugin-lto enabled in order to actually take advantage of the the optimized assembly:

RUSTFLAGS="-Clinker-plugin-lto -Clinker=clang -Clink-arg=-fuse-ld=lld" cargo build

API Stability

The instinsics are exported under ethnum::intrinsics. That being said, be careful when using these intrinsics directly. Semantic versioning API compatibility is not guaranteed for any of these intrinsics.

If you do you use these in your projects, it is recommended to use strict versioning:

[dependencies]
ethnum = "=x.y.z"

This will ensure commands like cargo update won't change the version of the ethnum dependency.

Benchmarking

The ethnum-bench crate implements criterion benchmarks for performance of integer intrinsics:

cargo bench -p ethnum-bench
RUSTFLAGS="-Clinker-plugin-lto -Clinker=clang -Clink-arg=-fuse-ld=lld" cargo bench -p ethnum-bench --features llvm-intrinsics

Fuzzing

The ethnum-fuzz crate implements an AFL fuzzing target (as well as some utilities for working with cargo afl). Internally, it converts the signed 256-bit integer types to num::BigInt and uses its operation implementations as a reference.

In order to start fuzzing:

cargo install afl
cargo run -p ethnum-fuzz --bin init target/fuzz
cargo afl build -p ethnum-fuzz --bin fuzz
cargo afl fuzz -i target/fuzz/in -o target/fuzz/out target/debug/fuzz

In order to replay crashes:

cargo run -p ethnum-fuzz --bin dump target/fuzz/out/default/crashes/FILE