| | Parity-Rlp | Alloy-Rlp | Speedup | | :----------- | :--------- | :--------- | :----------- | | **Encoding** | `86.70 ns` | `26.88 ns` | ๐ **3.23x** | | **Decoding** | `88.79 ns` | `21.43 ns` | ๐ **4.14x** | # Getting Started \[The simplest, fastest Rust toolkit to interact with any EVM chain] ## Overview Alloy is a high-performance Rust toolkit for Ethereum and EVM-based blockchains providing developers with: * **High Performance**: Optimized primitives with up to 60% faster U256 operations and 10x faster ABI encoding * **Developer Experience**: Intuitive API for interacting with Smart contracts via the `sol!` macro * **Chain-Agnostic Type System**: Multi-chain support without feature flags or type casting * **Extensibility**: Customizable provider architecture with layers and fillers ## Installation Install alloy to any cargo project using the command line. See [Installation](/introduction/installation#features) for more details on the various features flags. ```bash [cargo] cargo add alloy ``` ## Quick Start ### 1. Sending Transactions This example shows how to send 100 ETH using the [`TransactionBuilder`](/transactions/using-the-transaction-builder) on a local anvil node ```rust use alloy::{ network::TransactionBuilder, primitives::{ address, utils::{format_ether, Unit}, U256, }, providers::{Provider, ProviderBuilder}, rpc::types::TransactionRequest, signers::local::PrivateKeySigner, }; use std::error::Error; #[tokio::main] async fn main() -> Result<(), Box
, // Unnecssary
}
```
This is actually unnecessary because Alloy's Providers already implement internal reference counting. Instead, simply add the `Clone` bound when needed:
```rust
struct MyProvider (
&self,
_provider: &P,
_tx: & ,
}
```
## Improving function call return types
With the inclusion of [core#855](https://github.com/alloy-rs/core/pull/855) return values of function calls with a *singular* value is more intuitive and easier to work with.
Consider the following example of reading the balance of an ERC20:
```rust
sol! {
#[sol(rpc)]
contract ERC20 {
// Note: Only a single value is being returned
function balanceOf(address) returns (uint256);
}
}
```
## Before
Calling the `balanceOf` fn would return a struct `balanceOfReturn` which encapsulated the actual balance value.
```rust
// .. snip ..
let balance_return: balanceOfReturn = erc20.balanceOf(owner).await?;
let actual_balance = balance_return._0;
```
## After
Calling the `balanceOf` fn would now yield the balance directly instead of a struct wrapping it.
```rust
// .. snip ..
let balance: U256 = erc20.balanceOf(owner).await?;
```
It is important to note that this change only applies to function calls that have a **singular** return value.
Function calls that **return multiple values** have their return types **unchanged**, i.e they still return a struct with values inside it.
```rust
sol! {
function multiValues() returns (uint256 a, address b, bytes c);
}
// The above function call will have the following return type.
pub struct multiValuesReturn {
pub a: U256,
pub b: Address,
pub c: Bytes,
}
```
## Changes to function call bindings
With [core#884](https://github.com/alloy-rs/core/pull/884) the form of the generated call type (used for abi-encoding) is now dependent upon two factors:
1. Number of parameters/args does the function take
2. Whether the parameter is named or unnamed in case it has only **one** param
Consider the following:
```rust
sol! {
// No params/args
function totalSupply() returns (uint256)
// Exactly one unnamed param
function balanceOf(address) returns (uint256);
// Multiple params - Bindings for this remain unchanged.
function approve(address spender, uint256 amount) returns (bool);
}
```
### Before
Generated bindings were independent of the number of parameters and names, and the following struct were generated for the above function calls
```rust
// A struct with no fields as there are no parameters.
pub struct totalSupplyCall { };
let encoding = totalSupplyCall { }.abi_encode();
pub struct balanceOfCall { _0: Address };
let encoding = balanceOfCall { _0: Address::ZERO }.abi_encode();
```
### After
```rust
// A unit struct is generated when there are no parameters.
pub struct totalSupplyCall;
let encoding = totalSupplyCall.abi_encode();
// A tuple struct with a single value is generated in case of a SINGLE UNNAMED param.
pub struct balanceOfCall(pub Address);
let encoding = balanceOfCall(Address::ZERO).abi_encode();
```
Now if the parameter in `balanceOf` was named like so:
```rust
sol! {
function balanceOf(address owner) returns (uint256);
}
```
Then a regular struct would be generated like before:
```rust, ignore
pub struct balanceOfCall { owner: Address };
```
Bindings for function calls with **multiple parameters** are **unchanged**.
## Changes to event bindings
[core#885](https://github.com/alloy-rs/core/pull/885) makes changes to the event bindings in a breaking but very minimal way.
It changes the bindings for **only** events with no parameters
Consider the following event:
```rust
sol! {
event Incremented();
}
```
### Before
The generated struct was an empty struct like below:
```rust
pub struct Incremented { };
```
### After
A unit struct is generated like below:
```rust
pub struct Incremented;
```
Bindings for events with parameters remain **unchanged**.
## Changes to error bindings
[core#883](https://github.com/alloy-rs/core/pull/883) makes similar changes to the error bindings that [core#884](https://github.com/alloy-rs/core/pull/884) did to function call bindings in the sense that the form of the generated type is dependent upon two factors:
1. Number of parameters the error has.
2. Whether the parameter is named or unnamed in case it has only **one** param
Consider the following example:
```rust
sol! {
// No params/args
error Some();
// Exactly one unnamed param
error Another(uint256);
// Exactly one named param - bindings for this remain unchanged
error YetAnother(uint256 a);
}
```
## Before
All of the above were generated as regular structs.
```rust
// Empty struct
pub struct SomeError { };
pub struct AnotherError {
_0: U256
}
pub struct YetAnotherError {
a: U256
}
```
## After
```rust
// Unit struct for error with no params
pub struct SomeError;
// Tuple struct for SINGLE UNNAMED param
pub struct AnotherError(pub U256);
```
Bindings remain **unchanged** for errors with **multiple params** and **single but named param**.
## Encoding return structs
[core#909](https://github.com/alloy-rs/core/pull/909) improves return type encoding by allowing to pass the return struct directly into `SolCall::abi_encode_returns`.
Consider the following:
```rust
sol! {
function something() returns (uint256, address);
}
```
### Before
A tuple would need to passed of the fields from return type, `somethingReturn`
```rust
let encoding = somethingCall::abi_encode_returns(&(somethingReturn._0, somethingReturn._1));
```
### After
One can now pass the return struct directly without deconstructing it as a tuple.
```rust
let encoding = somethingCall::abi_encode_returns(&somethingReturn);
```
## Removing the `validate: bool` from the `abi_decode` methods
[core#863](https://github.com/alloy-rs/core/pull/863) removes the `validate: bool` parameter from the `abi_decode_*` methods. The behavior of these `abi_decode_*` methods is now equivalent to passing `validate = false`.
## Other breaking changes
* [Removal of the deprecated `Signature` type. `PrimitiveSignature` is now aliased to `Signature`](https://github.com/alloy-rs/core/pull/899)
* [Renaming methods in User-defined types (UDT)'s bindings and implementing `From` and `Into` traits for UDT's](https://github.com/alloy-rs/core/pull/905)
* [Bumping `getrandom` and `rand`](https://github.com/alloy-rs/core/pull/869)
* [Removal of `From Layer for DelayLayer {
type Service = DelayService;
fn layer(&self, service: S) -> Self::Service {
DelayService {
service,
delay: self.delay,
}
}
}
struct DelayService {
service: S,
delay: Duration,
}
impl
where
S: Service Layer for LoggingLayer {
type Service = LoggingService;
fn layer(&self, inner: S) -> Self::Service {
LoggingService { inner }
}
}
#[derive(Debug, Clone)]
struct LoggingService {
inner: S,
}
impl Service
where
S: Service
alloy
Connect applications to blockchains using performant, intuitive, and battle-tested APIs.
```bash [cargo]
cargo add alloy
```
# Features
Alloy supports the following out of the box for a best-in-class developer experience:
* Fully [Ethereum JSON-RPC](https://ethereum.github.io/execution-apis/docs/reference/json-rpc-api) compliant along with support for `trace`, `debug` and `anvil` endpoints
* Seamless contract interactions using the [`sol!`](/contract-interactions/using-sol!) macro
* Highly performant [core primitives](https://github.com/alloy-rs/core) such as `U256` Operations and ABI encoding
* Override / extend provider and transport behavior using [layers](/examples/layers/README) and [fillers](/rpc-providers/understanding-fillers) akin to [Tower](https://docs.rs/tower/latest/tower/)'s [layers](https://docs.rs/tower/latest/tower/trait.Layer.html)
* [Node bindings](https://docs.rs/alloy-node-bindings/latest/alloy_node_bindings/) for popular nodes such as [Reth](https://github.com/paradigmxyz/reth), [Geth](https://github.com/ethereum/go-ethereum) and [Anvil](https://book.getfoundry.sh/anvil/) for testing purposes
# Community
Join the Community
* Ask for support in the [Telegram chat](https://t.me/ethers_rs) or create an [issue on Github](https://github.com/alloy-rs/alloy/issues)
* Join the 160+ developers by [contributing](https://github.com/alloy-rs/alloy/blob/main/CONTRIBUTING.md) to Alloy
# Supporters