docs: fix broken links, update documentation

CONTRIBUTING.md

@@ -22,7 +22,7 @@ us!
 The ethers-rs project adheres to the [Rust Code of Conduct][coc]. This describes
 the _minimum_ behavior expected from all contributors. Instances of violations of the Code of Conduct can be reported by contacting the project team at [[email protected]](mailto:[email protected]).
 
-[coc]: https://github.com/rust-lang/rust/blob/master/CODE_OF_CONDUCT.md
+[coc]: https://www.rust-lang.org/policies/code-of-conduct
 
 ## Contributing in Issues
 

Cargo.toml

@@ -9,7 +9,7 @@ readme = "README.md"
 documentation = "https://docs.rs/ethers"
 repository = "https://github.com/gakonst/ethers-rs"
 homepage = "https://docs.rs/ethers"
-description = "Complete Ethereum library and wallet implementation in Rust."
+description = "A complete Ethereum and Celo Rust library"
 
 [workspace]
 members = [

README.md

@@ -1,6 +1,6 @@
-# <h1 align="center"> ethers.rs </h1>
+# <h1 align="center"> ethers-rs </h1>
 
-**Complete Ethereum and Celo wallet implementation and utilities in Rust**
+**A complete Ethereum and Celo Rust library**
 
 ![Github Actions](https://github.com/gakonst/ethers-rs/workflows/Tests/badge.svg)
 [![Telegram Chat](https://img.shields.io/endpoint?color=neon&style=flat-square&url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Fethers_rs)](https://t.me/ethers_rs)
@@ -9,42 +9,34 @@
 [crates-badge]: https://img.shields.io/crates/v/ethers.svg
 [crates-url]: https://crates.io/crates/ethers
 
-## Documentation
-
-Extensive documentation and examples are available [here](https://docs.rs/ethers).
-
-Alternatively, you may clone the repository and run `cd ethers/ && cargo doc --open`
-
-Examples are organized into individual crates under the `/examples` folder.
-You can run any of the examples by executing: 
-```bash
-# cargo run -p <example-crate-name> --example <name>
-cargo run -p examples-big-numbers --example math_operations
-```
+## Quickstart
 
-## Add ethers-rs to your repository
+Add this to your Cargo.toml:
 
 ```toml
 [dependencies]
-
-ethers = "1.0.0"
+ethers = "1.0.2"
 ```
 
-</details>
+And this to your code:
 
-## Running the tests
+```rust
+use ethers::prelude::*;
+```
 
-Tests require the following installed:
+## Documentation
 
-1. [`solc`](https://solidity.readthedocs.io/en/latest/installing-solidity.html) (>=0.8.10). We also recommend using [solc-select](https://github.com/crytic/solc-select) for more flexibility.
-2. [`anvil`](https://github.com/foundry-rs/foundry/blob/master/anvil/README.md)
-3. [`geth`](https://github.com/ethereum/go-ethereum)
+View the API reference [here](https://docs.rs/ethers) or the online book [here](https://gakonst.com/ethers-rs).
 
-In addition, it is recommended that you set the `ETHERSCAN_API_KEY` environment variable
-for [the abigen via Etherscan](https://github.com/gakonst/ethers-rs/blob/master/ethers-contract/tests/it/abigen.rs) tests.
-You can get one [here](https://etherscan.io/apis).
+Examples are organized into individual crates under the `/examples` folder.
+You can run any of the examples by executing:
+
+```bash
+# cargo run -p <example-crate-name> --example <name>
+cargo run -p examples-big-numbers --example math_operations
+```
 
-### EVM-compatible chains support
+## EVM-compatible chains support
 
 There are many chains live which are Ethereum JSON-RPC & EVM compatible, but do not yet have
 support for [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) Typed Transactions. This means
@@ -53,8 +45,7 @@ address that, you must use the `legacy` feature flag:
 
 ```toml
 [dependencies]
-
-ethers = { version = "1.0.0", features = ["legacy"] }
+ethers = { version = "1.0.2", features = ["legacy"] }
 ```
 
 ### Polygon support
@@ -73,8 +64,7 @@ You can get one [here](https://snowtrace.io/apis).
 
 ```toml
 [dependencies]
-
-ethers = { version = "1.0.0", features = ["celo"] }
+ethers = { version = "1.0.2", features = ["celo"] }
 ```
 
 Celo's transactions differ from Ethereum transactions by including 3 new fields:
@@ -111,8 +101,7 @@ Websockets support is turned on via the feature-flag `ws`:
 
 ```toml
 [dependencies]
-
-ethers = { version = "1.0.0", features = ["ws"] }
+ethers = { version = "1.0.2", features = ["ws"] }
 ```
 
 ### Interprocess Communication (IPC)
@@ -121,8 +110,7 @@ IPC support is turned on via the feature-flag `ipc`:
 
 ```toml
 [dependencies]
-
-ethers = { version = "1.0.0", features = ["ipc"] }
+ethers = { version = "1.0.2", features = ["ipc"] }
 ```
 
 ### HTTP Secure (HTTPS)
@@ -134,16 +122,14 @@ To enable `rustls`:
 
 ```toml
 [dependencies]
-
-ethers = { version = "1.0.0", features = ["rustls"] }
+ethers = { version = "1.0.2", features = ["rustls"] }
 ```
 
 To enable `openssl`:
 
 ```toml
 [dependencies]
-
-ethers = { version = "1.0.0", features = ["openssl"] }
+ethers = { version = "1.0.2", features = ["openssl"] }
 ```
 
 ## Note on WASM and FFI bindings
@@ -171,24 +157,22 @@ Join the [ethers-rs telegram](https://t.me/ethers_rs) to chat with the community
 ## Contributing
 
 Thanks for your help improving the project! We are so happy to have you! We have
-[a contributing guide](https://github.com/gakonst/ethers-rs/blob/master/CONTRIBUTING.md) to
-help you get involved in the ethers-rs project.
+[a contributing guide](./CONTRIBUTING.md) to help you get involved in the ethers-rs project.
 
-If you make a Pull Request, do not forget to add your changes in the [CHANGELOG](CHANGELOG.md) and ensure your code is
-properly formatted with `cargo +nightly fmt` and clippy is happy `cargo clippy`, you can even try to let clippy fix simple
-issues itself: `cargo +nightly clippy --fix -Z unstable-options`
+If you open a Pull Request, do not forget to add your changes in the [CHANGELOG](./CHANGELOG.md), ensure your code is
+properly formatted with `cargo +nightly fmt` and that Clippy is happy `cargo clippy`; you can even try to let clippy fix simple
+issues itself: `cargo +nightly clippy --fix`
 
-## Related Projects
+### Running the tests
 
-This library would not have been possible without the great work done in:
+Tests require the following installed:
 
--   [`ethers.js`](https://github.com/ethers-io/ethers.js/)
--   [`rust-web3`](https://github.com/tomusdrw/rust-web3/)
--   [`ethcontract-rs`](https://github.com/gnosis/ethcontract-rs/)
--   [`guac_rs`](https://github.com/althea-net/guac_rs/tree/master/web3/src/jsonrpc)
+1. [`solc`](https://docs.soliditylang.org/en/latest/installing-solidity.html) (>=0.8.0). We also recommend using [svm](https://github.com/roynalnaruto/svm-rs) for more flexibility.
+2. [`anvil`](https://github.com/foundry-rs/foundry/blob/master/anvil/README.md)
+3. [`geth`](https://github.com/ethereum/go-ethereum)
 
-A lot of the code was inspired and adapted from them, to a unified and opinionated interface,
-built with async/await and std futures from the ground up.
+Additionally, the `ETHERSCAN_API_KEY` environment variable has to be set to run [`ethers-etherscan`](./ethers-etherscan) tests.
+You can get one [here](https://etherscan.io/apis).
 
 ## Projects using ethers-rs
 
@@ -199,3 +183,15 @@ built with async/await and std futures from the ground up.
 -   [Celo Threshold BLS DKG](https://github.com/celo-org/celo-threshold-bls-rs/): CLI for using Celo as a data availability network for the Joint-Feldman BLS DKG
 -   [Celo Plumo Prover](https://github.com/celo-org/plumo-prover): Creates Celo's ultralight client proof from on-chain data
 -   [Celo SNARK Setup Coordinator](https://github.com/celo-org/snark-setup-operator): Coordinator for executing a pipelined Groth16 SNARK setup
+
+## Credits
+
+This library would not have been possible without the great work done in:
+
+-   [`ethers.js`](https://github.com/ethers-io/ethers.js/)
+-   [`rust-web3`](https://github.com/tomusdrw/rust-web3/)
+-   [`ethcontract-rs`](https://github.com/gnosis/ethcontract-rs/)
+-   [`guac_rs`](https://github.com/althea-net/guac_rs/)
+
+A lot of the code was inspired and adapted from them, to a unified and opinionated interface,
+built with async/await and std futures from the ground up.

ethers-addressbook/Cargo.toml

@@ -11,8 +11,8 @@ repository = "https://github.com/gakonst/ethers-rs"
 keywords = ["ethereum", "web3", "celo", "ethers"]
 
 [dependencies]
+ethers-core = { version = "^1.0.0", path = "../ethers-core", default-features = false }
+
 once_cell = "1.17.1"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
-
-ethers-core = { path = "../ethers-core", version = "^1.0.0" }

ethers-addressbook/README.md

@@ -0,0 +1,15 @@
+# ethers-addressbook
+
+A collection of commonly used smart contract addresses.
+
+For more information, please refer to the [book](https://gakonst.com/ethers-rs).
+
+## Examples
+
+```rust
+use ethers_addressbook::{contract, Chain};
+
+let weth = contract("weth").unwrap();
+let mainnet_address = weth.address(Chain::Mainnet).unwrap();
+assert_eq!(mainnet_address, "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2".parse().unwrap());
+```

ethers-addressbook/src/lib.rs

@@ -1,15 +1,18 @@
-use ethers_core::types::{Address, Chain};
+#![doc = include_str!("../README.md")]
+#![deny(unsafe_code, rustdoc::broken_intra_doc_links)]
+
+pub use ethers_core::types::{Address, Chain};
+
 use once_cell::sync::Lazy;
 use serde::Deserialize;
-
 use std::collections::HashMap;
 
 const CONTRACTS_JSON: &str = include_str!("./contracts/contracts.json");
 
 static ADDRESSBOOK: Lazy<HashMap<String, Contract>> =
     Lazy::new(|| serde_json::from_str(CONTRACTS_JSON).unwrap());
 
-/// Wrapper around a hash map that maps a [chain](https://github.com/gakonst/ethers-rs/blob/master/ethers-core/src/types/chain.rs) to the contract's deployed address on that chain.
+/// Wrapper around a hash map that maps a [Chain] to the contract's deployed address on that chain.
 #[derive(Clone, Debug, Deserialize)]
 pub struct Contract {
     addresses: HashMap<Chain, Address>,

ethers-contract/README.md

@@ -1,4 +1,6 @@
-Type-safe abstractions for interacting with Ethereum smart contracts
+# ethers-core
+
+Type-safe abstractions for interacting with Ethereum smart contracts.
 
 Interacting with a smart contract requires broadcasting carefully crafted
 [transactions](ethers_core::types::TransactionRequest) where the `data` field
@@ -10,6 +12,8 @@ This module provides the [`Contract`] and [`ContractFactory`] abstractions so
 that you do not have to worry about that. It also provides typesafe bindings via
 the [`abigen`] macro and the [`Abigen` builder].
 
+For more information, please refer to the [book](https://gakonst.com/ethers-rs).
+
 [`contractfactory`]: ./struct.ContractFactory.html
 [`contract`]: ./struct.Contract.html
 [`abigen`]: ./macro.abigen.html

ethers-contract/ethers-contract-abigen/src/contract/methods.rs

@@ -371,8 +371,8 @@ impl Context {
     /// convention of suffixing the function name with _with
     ///
     /// The first function or the function with the least amount of arguments should
-    /// be named as in the ABI, the following functions suffixed with _with_ +
-    /// additional_params[0].name + (_and_(additional_params[1+i].name))*
+    /// be named as in the ABI, the following functions suffixed with:
+    /// `_with_ + additional_params[0].name + (_and_(additional_params[1+i].name))*`
     fn get_method_aliases(&self) -> Result<BTreeMap<String, MethodAlias>> {
         let mut aliases = self.method_aliases.clone();
 

ethers-contract/ethers-contract-abigen/src/source/online.rs

@@ -119,7 +119,7 @@ impl Source {
     /// Parse `s` as an explorer ("etherscan"), explorer domain ("etherscan.io") or a chain that has
     /// an explorer ("mainnet").
     ///
-    /// The URL can be either <explorer>:<address> or <explorer_url>/.../<address>
+    /// The URL can be either `<explorer>:<address>` or `<explorer_url>/.../<address>`
     fn from_explorer(s: &str, url: &Url) -> Result<Self> {
         let explorer: Explorer = s.parse().or_else(|_| Explorer::from_chain(s.parse()?))?;
         let address = last_segment_address(url).ok_or_else(|| eyre::eyre!("Invalid URL: {url}"))?;

ethers-core/README.md

@@ -1,48 +1,50 @@
-# Ethereum types, cryptography and utilities.
+# ethers-core
+
+Ethereum data types, cryptography and utilities.
 
 It is recommended to use the `utils`, `types` and `abi` re-exports instead of
 the `core` module to simplify your imports.
 
 This library provides type definitions for Ethereum's main datatypes along with
 other utilities for interacting with the Ethereum ecosystem
 
-## Signing an ethereum-prefixed message
-
-Signing in Ethereum is done by first prefixing the message with
-`"\x19Ethereum Signed Message:\n" + message.length`, and then signing the hash
-of the result.
+For more information, please refer to the [book](https://gakonst.com/ethers-rs).
 
-```rust,ignore
-# async fn foo() -> Result<(), Box<dyn std::error::Error>> {
-use ethers::signers::{Signer, LocalWallet};
+## Feature flags
 
-let message = "Some data";
-let wallet = LocalWallet::new(&mut rand::thread_rng());
+-   `eip712`: Provides the `Eip712` trait and derive procedural macro for EIP-712 encoding of typed data.
 
-// Sign the message
-let signature = wallet.sign_message(message).await?;
+## ABI
 
-// Recover the signer from the message
-let recovered = signature.recover(message)?;
-
-assert_eq!(recovered, wallet.address());
-# Ok(())
-# }
-```
+This crate re-exports the [`ethabi`](https://docs.rs/ethabi) crate's functions
+under the `abi` module, as well as the
+[`secp256k1`](https://docs.rs/libsecp256k1) and [`rand`](https://docs.rs/rand)
+crates for convenience.
 
 ## Utilities
 
 The crate provides utilities for launching local Ethereum testnets by using
 `ganache-cli` via the `GanacheBuilder` struct.
 
-# Features
+## Examples
 
--   ["eip712"] | Provides Eip712 trait for EIP-712 encoding of typed data for
-    derived structs
+Calculate the UniswapV2 pair address for two ERC20 tokens:
 
-# ABI Encoding and Decoding
+```rust
+# use ethers_core::abi::{self, Token};
+# use ethers_core::types::{Address, H256};
+# use ethers_core::utils;
+let factory: Address = "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f".parse()?;
 
-This crate re-exports the [`ethabi`](https://docs.rs/ethabi) crate's functions
-under the `abi` module, as well as the
-[`secp256k1`](https://docs.rs/libsecp256k1) and [`rand`](https://docs.rs/rand)
-crates for convenience.
+let token_a: Address = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48".parse()?;
+let token_b: Address = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2".parse()?;
+let encoded = abi::encode_packed(&[Token::Address(token_a), Token::Address(token_b)])?;
+let salt = utils::keccak256(encoded);
+
+let init_code_hash: H256 = "0x96e8ac4277198ff8b6f785478aa9a39f403cb768dd02cbee326c3e7da348845f".parse()?;
+
+let pair = utils::get_create2_address_from_hash(factory, salt, init_code_hash);
+let weth_usdc = "0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc".parse()?;
+assert_eq!(pair, weth_usdc);
+# Ok::<(), Box<dyn std::error::Error>>(())
+```

ethers-core/src/abi/mod.rs

@@ -1,5 +1,7 @@
-//! This module implements extensions to the [`ethabi`](https://docs.rs/ethabi) API.
-// Adapted from [Gnosis' ethcontract](https://github.com/gnosis/ethcontract-rs/blob/master/common/src/abiext.rs)
+//! Extensions to the [`ethabi`](https://docs.rs/ethabi) API.
+//!
+//! Adapted from [Gnosis' `ethcontract-rs`](https://github.com/gnosis/ethcontract-rs).
+
 use crate::{
     types::{Bytes, Selector, Uint8, H256, H512, I256, U128, U256, U64},
     utils::id,

ethers-core/src/types/mod.rs

@@ -1,3 +1,5 @@
+//! Ethereum data types.
+
 pub type Selector = [u8; 4];
 
 // Re-export common ethereum datatypes with more specific names