/ic-alloy

A fork of the Alloy project that adds the ICP blockchain as a transport layer and signer.

Primary LanguageRustApache License 2.0Apache-2.0

Important

This is a fork of the original alloy repository that adds support for the Internet Computer (ICP). The original repository can be found here.

See ICP Notes for more information.

For demos and documentation on how to use the ICP adaption of Alloy, see ic-alloy.dev.

Alloy for the Internet Computer

ic-alloy connects Rust ICP canisters to EVM blockchains.

Alloy is a rewrite of ethers-rs from the ground up, with exciting new features, high performance, and excellent docs.

We also have a book on all things Alloy and many examples to help you get started.

Telegram chat

Installation

Alloy consists of a number of crates that provide a range of functionality essential for interfacing with any EVM-based blockchain.

To get started, you can add the following to your Cargo.toml file:

alloy = { git = "https://github.com/ic-alloy/ic-alloy.git", tag = "v0.3.5-icp.0", default-features = false, features = ["icp"]}
getrandom = { version = "0.2.15", features = ["custom"] }

To use the sol!() macro, add the following crate features:

  • sol-types
  • json
  • contract

For a more fine-grained control over the features you wish to include, you can add the individual crates to your Cargo.toml file, or use the alloy crate with the features you need.

A comprehensive list of available features can be found on docs.rs or in the alloy crate's Cargo.toml.

Overview

This repository contains the following crates:

Supported Rust Versions (MSRV)

The current MSRV (minimum supported rust version) is 1.79.

Alloy will keep a rolling MSRV policy of at least two versions behind the latest stable release (so if the latest stable release is 1.58, we would support 1.56).

Note that the MSRV is not increased automatically, and only as part of a patch (pre-1.0) or minor (post-1.0) release.

ICP Notes

Smart contracts on ICP can directly interact with the Ethereum network and other networks that are using the Ethereum Virtual Machine (EVM), such as Polygon and Avalanche. This integration is possible thanks to ICP's HTTPS outcalls and threshold ECDSA features, which allow Ethereum transactions to be queried and ICP smart contracts to sign and submit transactions to Ethereum.

ICP Packages added to Alloy

transport-icp

Adds ICP as a Alloy transport layer, routing requests through the IC EVM RPC canister or an external RPC proxy.

The ICP transport uses HTTPS outcalls to query information from Ethereum and other EVM networks.

signer-icp

Abstracts away the complexity of signing messages and transactions on ICP.

The ICP signer uses Threshold ECDSA allowing the canister to create signaturs in a secure and decentralised way.

Alloy packages modified

provider

  • Adds the on_icp() function to build a provider using an IcpTransport with the given IcpConfig.
  • Adapts the watch_x functions to work with the ICP poller.
  • watch_pending_transactions is not available on ICP as it relies on heartbeat functionality not yet implemented

rpc-client

  • Adds the icp() function to the ClientBuilder, a convenience function to create a new RpcClient with an IcpTransport using the given IcpConfig details.
  • Adapts the new_batch() function to support IcpTransport for batch requests.
  • Adds the IcpPollerBuilder used for watching for logs, transactions and blocks. The ICP poller relies on IC timers for continuously listening to events.
  • Adds the IcpClient type that maps to IcpTransport
    • pub type IcpClient = RpcClient<alloy_transport_icp::IcpTransport>;

Additional notes for the ICP fork

  • The subscription features of Alloy are not supported. To subscribe to logs or blocks, instead use watch and poll.

Contributing

Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the Alloy project.

Pull requests will not be merged unless CI passes, so please ensure that your contribution follows the linting rules and passes clippy.

Note on no_std

Because these crates are primarily network-focused, we do not intend to support no_std for most of them at this time.

The following crates support no_std:

  • alloy-eips
  • alloy-genesis
  • alloy-serde
  • alloy-consensus

If you would like to add no_std support to a crate, please make sure to update scripts/check_no_std.sh as well.

Credits

None of these crates would have been possible without the great work done in:

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.