alloy-rs/core

Alloy is a high-performance rewrite of ethers-rs for the Rust Ethereum ecosystem. The repository is organized into several specialized crates:

• alloy-core: The meta-crate for the entire project.
• alloy-primitives: Provides primitive integer and byte types.
• alloy-sol-types: Provides compile-time ABI and EIP-712 implementations.
• alloy-sol-macro: Contains the sol! procedural macro for Solidity integration.
• alloy-dyn-abi: Provides run-time ABI and EIP-712 implementations.
• alloy-json-abi: A full implementation of the Ethereum JSON-ABI.
• alloy-sol-type-parser: A simple parser for Solidity type strings.
• syn-solidity: A Solidity parser powered by syn.

The alloy-sol-macro crate provides the sol! procedural macro. This macro allows you to write Solidity syntax directly within your Rust code. It parses the Solidity code and automatically generates corresponding Rust types that implement the alloy-sol-types traits, enabling seamless interaction between Rust and Ethereum smart contracts.

// Example usage (refer to macro documentation for specific syntax)
// sol! {
//     contract MyContract {
//         function doSomething(uint256 x) external returns (bool);
//     }
// }

The alloy-sol-macro-expander crate provides the core logic for expanding a Solidity proc_macro2::TokenStream. It is designed to be used as a library crate to expand Solidity source code and generate corresponding Rust bindings.

Note that this is not the procedural macro crate itself; instead, it is the underlying engine used by the [sol!] macro in the [alloy-sol-macro] crate to perform the actual expansion work.

Because the shape of data is only known at runtime, alloy-dyn-abi cannot perform compile-time memory allocation for decoded data.

DynToken::decode_populate allows you to pre-allocate a DynToken with the expected shape (containing empty values) and then populate those empty values with decoded data.

Note: Direct use of DynToken is not recommended. Instead, use the abi_decode and abi_encode methods provided on DynSolType for a more ergonomic experience.

The library uses a two-step process for handling ABI data:

1. Tokenization/Detokenization: Converting between a Rust type and an ABI Token.

   • Use SolType::tokenize() to go from Rust $\rightarrow$ Token.
   • Use SolType::detokenize() to go from Token $\rightarrow$ Rust.
   • Note: This is primarily for power users implementing custom SolTypes.

2. Encoding/Decoding: Converting between a Token and a serialized ABI blob (bytes).

   • Recommendation: Most users should avoid interacting with Token directly. Instead, use the SolType or SolValue methods (like abi_encode and abi_decode) to operate directly on Rust types.

Because syn-solidity is limited to valid Rust tokens, certain Solidity constructs are not supported.

Unsupported Constructs:

• Identifiers with dollar signs: $ is not allowed inside identifiers.
• Single quote strings: Only double-quoted strings are supported.
• Literal prefixes: hex and unicode string literal prefixes are not supported (as they are reserved in Rust 2021 edition and above).
• Unicode escapes: Uses Rust's "\u{XXXX}" format instead of Solidity's "\uXXXX".
• Nested block comments: Invalid nested block comments like /*/*/ will fail to parse.

The dynamic system relies on three core enums that represent the Solidity type system at runtime:

1. DynSolType: Represents a Solidity type (equivalent to an enum over types implementing the SolType trait). This is the primary entry point for decoding.
2. DynSolValue: Represents the Rust-side shape of a decoded Solidity value. Users must manually convert these values to their own Rust types using From implementations or fallible casts.
3. DynToken: Represents an ABI token (equivalent to types implementing alloy_sol_types::abi::Token).

The Detokenizing Process: DynSolType + DynToken = DynSolValue.

Unlike static encoding, which uses the Rust type system to define expectations, the dynamic encoder requires an instance of DynSolType to be provided at runtime to guide the decoding process.

The alloy-sol-type-parser is a lightweight tool specifically designed for parsing type strings found in ecosystem tooling (like JSON ABIs). It is not a full Solidity parser.

Use this crate for:

• Syntax-checking JSON ABI files.
• Providing input to alloy-dyn-abi.
• Porting ethers.js code to Rust.

Do NOT use this crate for:

• Parsing Solidity source code.
• Generating Rust code from Solidity source code.
• Generating Solidity source code from Rust code.

For full Solidity syntax parsing and code generation, use syn-solidity instead.

Integer types are provided for common Ethereum requirements:

• Unsigned integers: Re-exported from ruint (e.g., U256).
• Signed integers: Provided as wrappers around ruint integers (e.g., I256).

These types support standard parsing from strings and arithmetic operations.

use alloy_primitives::{I256, U256};

// Unsigned integer usage
let mut n: U256 = "42".parse().unwrap();
n += U256::from(10);
assert_eq!(n.to_string(), "52");

// Signed integer usage
let mut n: I256 = "-42".parse().unwrap();
n = -n;
assert_eq!(n.to_string(), "42");