docs: touch up docs, TODOs (alloy-rs#918)

* docs: touch up docs, TODOs * docs: more docs.rs
ben186 · Jul 27, 2024 · 93d0fea · 93d0fea
1 parent 108dc9d
commit 93d0fea
Show file tree

Hide file tree

Showing 29 changed files with 80 additions and 78 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -62,8 +62,6 @@ alloy-transport-http = { version = "0.1.1", default-features = false, path = "cr
 alloy-transport-ipc = { version = "0.1.1", default-features = false, path = "crates/transport-ipc" }
 alloy-transport-ws = { version = "0.1.1", default-features = false, path = "crates/transport-ws" }
 
-test-utils = { version = "0.1.0", default-features = false, path = "crates/internal-test-utils", package = "alloy-internal-test-utils" }
-
 alloy-core = { version = "0.7.6", default-features = false }
 alloy-dyn-abi = { version = "0.7.6", default-features = false }
 alloy-json-abi = { version = "0.7.6", default-features = false }
@@ -100,7 +98,7 @@ tokio-util = "0.7"
 tokio-stream = "0.1"
 rustls = { version = "0.23", default-features = false, features = ["std"] }
 tokio-test = "0.4"
-tokio-tungstenite = { version = "0.23" }
+tokio-tungstenite = "0.23"
 tower = { version = "0.4", features = ["util"] }
 
 # tracing

diff --git a/README.md b/README.md
@@ -15,15 +15,23 @@ We also have a [book](https://alloy.rs/) on all things Alloy and many [examples]
 
 ## Installation
 
-Currently, Alloy is not hosted on [crates.io](https://crates.io), the Rust package registry.
+Alloy consists of a number of crates that provide a range of functionality essential for interfacing with any Ethereum-based blockchain.
 
-To incorporate Alloy into your project, you will need to specify the GitHub repository as the source. This can be achieved by executing the following command in your terminal:
+The easiest way to get started is to add the `alloy` crate with the `full` feature flag from the command-line using Cargo:
 
 ```sh
-cargo add alloy --git https://github.com/alloy-rs/alloy
+cargo add alloy --features full
 ```
 
-After incorporating Alloy, you may wish to utilize specific features of the crate. These features can be enabled through modifications in your project's `Cargo.toml` file. A comprehensive list of available features can be found at [this GitHub link](https://github.com/alloy-rs/alloy/blob/main/crates/alloy/Cargo.toml).
+Alternatively, you can add the following to your `Cargo.toml` file:
+
+```toml
+alloy = { version = "0.1", features = ["full"] }
+```
+
+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](https://docs.rs/crate/alloy/latest/features) or in the [`alloy` crate's `Cargo.toml`](https://github.com/alloy-rs/alloy/blob/main/crates/alloy/Cargo.toml).
 
 ## Overview
 
@@ -41,14 +49,14 @@ This repository contains the following crates:
 - [`alloy-pubsub`] - Ethereum JSON-RPC [publish-subscribe] tower service and type definitions
 - [`alloy-rpc-client`] - Low-level Ethereum JSON-RPC client implementation
 - [`alloy-rpc-types`] - Meta-crate for all Ethereum JSON-RPC types
-  - [`alloy-rpc-types-admin`] - Ethereum RPC admin types
-  - [`alloy-rpc-types-anvil`] - RPC types for the Anvil development node
-  - [`alloy-rpc-types-beacon`] - Ethereum RPC-related types for the Beacon API
-  - [`alloy-rpc-types-engine`] - Ethereum execution-consensus layer (engine) API RPC types
-  - [`alloy-rpc-types-eth`] - Ethereum RPC-related types for Alloy
-  - [`alloy-rpc-types-trace`] - Ethereum RPC trace types
-  - [`alloy-rpc-types-txpool`] - Ethereum RPC txpool types
-- [`alloy-serde`] - Serde related helpers for Alloy.
+  - [`alloy-rpc-types-admin`] - Types for the `admin` Ethereum JSON-RPC namespace
+  - [`alloy-rpc-types-anvil`] - Types for the [Anvil] development node's Ethereum JSON-RPC namespace
+  - [`alloy-rpc-types-beacon`] - Types for the [Ethereum Beacon Node API][beacon-apis]
+  - [`alloy-rpc-types-engine`] - Types for the `engine` Ethereum JSON-RPC namespace
+  - [`alloy-rpc-types-eth`] - Types for the `eth` Ethereum JSON-RPC namespace
+  - [`alloy-rpc-types-trace`] - Types for the `trace` Ethereum JSON-RPC namespace
+  - [`alloy-rpc-types-txpool`] - Types for the `txpool` Ethereum JSON-RPC namespace
+- [`alloy-serde`] - [Serde]-related utilities
 - [`alloy-signer`] - Ethereum signer abstraction
   - [`alloy-signer-aws`] - [AWS KMS] signer implementation
   - [`alloy-signer-gcp`] - [GCP KMS] signer implementation
@@ -97,6 +105,9 @@ This repository contains the following crates:
 [GCP KMS]: https://cloud.google.com/kms
 [Ledger]: https://www.ledger.com
 [Trezor]: https://trezor.io
+[Serde]: https://serde.rs
+[beacon-apis]: https://ethereum.github.io/beacon-APIs
+[Anvil]: https://github.com/foundry-rs/foundry
 
 ## Supported Rust Versions (MSRV)
 

diff --git a/crates/eips/src/eip1559/constants.rs b/crates/eips/src/eip1559/constants.rs
@@ -1,9 +1,6 @@
 use alloy_primitives::U256;
 
 /// The default Ethereum block gas limit.
-///
-/// TODO: This should be a chain spec parameter.
-/// See <https://github.com/paradigmxyz/reth/issues/3233>.
 pub const ETHEREUM_BLOCK_GAS_LIMIT: u64 = 30_000_000;
 
 /// The minimum tx fee below which the txpool will reject the transaction.

diff --git a/crates/provider/README.md b/crates/provider/README.md
@@ -28,8 +28,8 @@ The `ProviderBuilder` struct can quickly create a stacked provider, similar to
 ## Feature flags
 
 - `pubsub` - Enable support for subscription methods.
-- `ws` - Enable WebSocket support. Implictly enables `pubsub`.
-- `ipc` - Enable IPC support. Implictly enables `pubsub`.
+- `ws` - Enable WebSocket support. Implicitly enables `pubsub`.
+- `ipc` - Enable IPC support. Implicitly enables `pubsub`.
 
 ## Usage
 

diff --git a/crates/provider/src/heart.rs b/crates/provider/src/heart.rs
@@ -195,11 +195,11 @@ impl<'a, T: Transport + Clone, N: Network> PendingTransactionBuilder<'a, T, N> {
             let mut confirmed = false;
 
             select! {
-                 _ = interval.tick() => {},
-                 res = &mut pending_tx => {
-                        let _ = res?;
-                        confirmed = true;
-                    }
+                _ = interval.tick() => {},
+                res = &mut pending_tx => {
+                    let _ = res?;
+                    confirmed = true;
+                }
             }
 
             // try to fetch the receipt

diff --git a/crates/provider/src/provider/trait.rs b/crates/provider/src/provider/trait.rs
@@ -653,7 +653,7 @@ pub trait Provider<T: Transport + Clone = BoxTransport, N: Network = Ethereum>:
         self.send_transaction_internal(SendableTx::Envelope(tx)).await
     }
 
-    /// This method allows [`ProviderLayer`] and [`TxFiller`] to bulid the
+    /// This method allows [`ProviderLayer`] and [`TxFiller`] to build the
     /// transaction and send it to the network without changing user-facing
     /// APIs. Generally implementors should NOT override this method.
     ///

diff --git a/crates/rpc-client/src/client.rs b/crates/rpc-client/src/client.rs
@@ -118,8 +118,8 @@ impl<T: Transport + Clone> RpcClient<T> {
     pub fn boxed(self) -> RpcClient<BoxTransport> {
         let inner = match Arc::try_unwrap(self.0) {
             Ok(inner) => inner,
-            // TODO: `id` is discarded.
-            Err(inner) => RpcClientInner::new(inner.transport.clone(), inner.is_local),
+            Err(inner) => RpcClientInner::new(inner.transport.clone(), inner.is_local)
+                .with_id(inner.id.load(Ordering::Relaxed)),
         };
         RpcClient::from_inner(inner.boxed())
     }
@@ -180,6 +180,12 @@ impl<T> RpcClientInner<T> {
         }
     }
 
+    /// Sets the starting ID for the client.
+    #[inline]
+    pub fn with_id(self, id: u64) -> Self {
+        Self { id: AtomicU64::new(id), ..self }
+    }
+
     /// Returns the default poll interval (milliseconds) for the client.
     pub fn poll_interval(&self) -> Duration {
         Duration::from_millis(self.poll_interval.load(Ordering::Relaxed))

diff --git a/crates/rpc-types-admin/README.md b/crates/rpc-types-admin/README.md
@@ -1,3 +1,3 @@
 # alloy-rpc-types-admin
 
-Ethereum RPC `admin` types.
+Types for the `admin` Ethereum JSON-RPC namespace.
diff --git a/crates/rpc-types-anvil/Cargo.toml b/crates/rpc-types-anvil/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-types-anvil"
-description = "Anvil RPC types"
+description = "Types for the Anvil development node's Ethereum JSON-RPC namespace"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/rpc-types-anvil/README.md b/crates/rpc-types-anvil/README.md
@@ -1,3 +1,5 @@
 # alloy-rpc-types-anvil
 
-RPC types for the Anvil development node.
+Types for the [Anvil] development node's Ethereum JSON-RPC namespace.
+
+[Anvil]: https://github.com/foundry-rs/foundry
diff --git a/crates/rpc-types-beacon/Cargo.toml b/crates/rpc-types-beacon/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-types-beacon"
-description = "Ethereum RPC-related types for the Beacon API."
+description = "Types for the Ethereum Beacon Node API"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true

diff --git a/crates/rpc-types-beacon/README.md b/crates/rpc-types-beacon/README.md
@@ -1,3 +1,5 @@
 # alloy-rpc-types-beacon
 
-Ethereum RPC-related types for the [Beacon API](https://ethereum.github.io/beacon-APIs).
+Types for the [Ethereum Beacon Node API][beacon-apis].
+
+[beacon-apis]: https://ethereum.github.io/beacon-APIs
diff --git a/crates/rpc-types-engine/Cargo.toml b/crates/rpc-types-engine/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-types-engine"
-description = "Ethereum execution-consensus layer (engine) API RPC types"
+description = "Types for the `engine` Ethereum JSON-RPC namespace"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/rpc-types-engine/README.md b/crates/rpc-types-engine/README.md
@@ -1,3 +1,8 @@
 # alloy-rpc-types-engine
 
-Ethereum execution-consensus layer (engine) API RPC types.
+Types for the `engine` Ethereum JSON-RPC namespace.
+
+Engine API types:
+<https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md>
+and <https://eips.ethereum.org/EIPS/eip-3675>,
+following the execution specs <https://github.com/ethereum/execution-apis/tree/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine>.
diff --git a/crates/rpc-types-engine/src/lib.rs b/crates/rpc-types-engine/src/lib.rs
@@ -1,8 +1,3 @@
-//! Engine API types:
-//! <https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md>
-//! and <https://eips.ethereum.org/EIPS/eip-3675>,
-//! following the execution specs <https://github.com/ethereum/execution-apis/tree/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine>.
-
 #![doc = include_str!("../README.md")]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/alloy-rs/core/main/assets/alloy.jpg",

diff --git a/crates/rpc-types-eth/Cargo.toml b/crates/rpc-types-eth/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-types-eth"
-description = "Ethereum RPC-related types"
+description = "Types for the `eth` Ethereum JSON-RPC namespace"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/rpc-types-eth/README.md b/crates/rpc-types-eth/README.md
@@ -1,3 +1,3 @@
 # alloy-rpc-types-eth
 
-Ethereum RPC-related types for Alloy.
+Types for the `eth` Ethereum JSON-RPC namespace.
diff --git a/crates/rpc-types-trace/Cargo.toml b/crates/rpc-types-trace/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-types-trace"
-description = "Ethereum RPC trace types"
+description = "Types for the `trace` Ethereum JSON-RPC namespace"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/rpc-types-trace/README.md b/crates/rpc-types-trace/README.md
@@ -1,3 +1,3 @@
 # alloy-rpc-types-trace
 
-Ethereum RPC trace types.
+Types for the `trace` Ethereum JSON-RPC namespace.
diff --git a/crates/rpc-types-txpool/Cargo.toml b/crates/rpc-types-txpool/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-types-txpool"
-description = "Ethereum RPC txpool types"
+description = "Types for the `txpool` Ethereum JSON-RPC namespace"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/rpc-types-txpool/README.md b/crates/rpc-types-txpool/README.md
@@ -1,3 +1,3 @@
 # alloy-rpc-types-txpool
 
-Ethereum RPC `txpool` types.
+Types for the `txpool` Ethereum JSON-RPC namespace.
diff --git a/crates/rpc-types/Cargo.toml b/crates/rpc-types/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-types"
-description = "Alloy RPC types"
+description = "Meta-crate for all Ethereum JSON-RPC types"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/rpc-types/README.md b/crates/rpc-types/README.md
@@ -1,3 +1,3 @@
 # alloy-rpc-types
 
-Ethereum RPC-related types for Alloy.
+Meta-crate for all Ethereum JSON-RPC types.
diff --git a/crates/rpc-types/src/lib.rs b/crates/rpc-types/src/lib.rs
@@ -1,7 +1,3 @@
-//! Alloy RPC type definitions.
-//!
-//! Provides all relevant types for the various RPC endpoints, grouped by namespace.
-
 #![doc = include_str!("../README.md")]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/alloy-rs/core/main/assets/alloy.jpg",

diff --git a/crates/signer-local/README.md b/crates/signer-local/README.md
@@ -2,9 +2,10 @@
 
 Local signer implementations:
 
-- [K256 private key](./src/private_key.rs)
-- [Mnemonic phrase](./src/mnemonic.rs)
-- [YubiHSM2](./src/yubi.rs)
+- [K256 private key](https://docs.rs/alloy-signer-local/latest/alloy_signer_local/struct.LocalSigner.html)
+<!-- TODO: use the struct URL in these once it appears on docs.rs -->
+- [Mnemonic phrase](https://docs.rs/alloy-signer-local/)
+- [YubiHSM2](https://docs.rs/alloy-signer-local/)
 
 ## Features
 

diff --git a/crates/signer-trezor/src/signer.rs b/crates/signer-trezor/src/signer.rs
@@ -187,7 +187,7 @@ impl TrezorSigner {
         let data = tx.input().to_vec();
         let chain_id = tx.chain_id();
 
-        // TODO: Uncomment in 1.76
+        // TODO: Uncomment once dyn trait upcasting is stable
         /*
         let signature = if let Some(tx) = (tx as &dyn std::any::Any).downcast_ref::<TxEip1559>() {
         */

diff --git a/crates/signer/README.md b/crates/signer/README.md
@@ -6,15 +6,14 @@ You can implement the [`Signer`][Signer] trait to extend functionality to other
 such as Hardware Security Modules, KMS etc. See [its documentation][Signer] for more.
 
 Signer implementations in Alloy:
-- [K256 private key](../signer-local/src/private_key.rs)
-- [YubiHSM2](../signer-local/src/yubi.rs)
-- [Ledger](../signer-ledger/)
-- [Trezor](../signer-trezor/)
-- [AWS KMS](../signer-aws/)
-- [GCP KMS](../signer-gcp/)
+- [K256 private key](https://docs.rs/alloy-signer-local)
+- [YubiHSM2](https://docs.rs/alloy-signer-local)
+- [Ledger](https://docs.rs/alloy-signer-ledger)
+- [Trezor](https://docs.rs/alloy-signer-trezor)
+- [AWS KMS](https://docs.rs/alloy-signer-aws)
+- [GCP KMS](https://docs.rs/alloy-signer-gcp)
 
-<!-- TODO: docs.rs -->
-[Signer]: https://alloy-rs.github.io/alloy/alloy_signer/trait.Signer.html
+[Signer]: https://docs.rs/alloy-signer/latest/alloy_signer/trait.Signer.html
 
 ## Examples
 

diff --git a/crates/transport/src/error.rs b/crates/transport/src/error.rs
@@ -72,7 +72,7 @@ impl TransportErrorKind {
         RpcError::Transport(Self::PubsubUnavailable)
     }
 
-    /// Instantiate a new `TrasnportError::HttpError`.
+    /// Instantiate a new `TransportError::HttpError`.
     pub const fn http_error(status: u16, body: String) -> TransportError {
         RpcError::Transport(Self::HttpError(HttpError { status, body }))
     }

diff --git a/deny.toml b/deny.toml
@@ -1,19 +1,15 @@
 [advisories]
-vulnerability = "deny"
-unmaintained = "warn"
-unsound = "warn"
+version = 2
 yanked = "warn"
-notice = "warn"
 
 [bans]
 multiple-versions = "warn"
 wildcards = "deny"
 highlight = "all"
 
 [licenses]
-unlicensed = "deny"
-confidence-threshold = 0.9
-# copyleft = "deny"
+version = 2
+confidence-threshold = 0.8
 
 allow = [
     "MIT",
@@ -28,17 +24,13 @@ allow = [
     "MPL-2.0",
     # https://github.com/briansmith/ring/issues/902
     "LicenseRef-ring",
-    "Unicode-3.0",
 ]
 
 exceptions = [
     # CC0 is a permissive license but somewhat unclear status for source code
     # so we prefer to not have dependencies using it
     # https://tldrlegal.com/license/creative-commons-cc0-1.0-universal
-    { allow = ["CC0-1.0"], name = "secp256k1" },
-    { allow = ["CC0-1.0"], name = "secp256k1-sys" },
     { allow = ["CC0-1.0"], name = "tiny-keccak" },
-    { allow = ["CC0-1.0"], name = "to_method" },
     { allow = ["CC0-1.0"], name = "trezor-client" },
 ]
 
@@ -55,5 +47,3 @@ license-files = [{ path = "LICENSE", hash = 0x001c7e6c }]
 [sources]
 unknown-registry = "deny"
 unknown-git = "deny"
-# TODO: Remove once alloy-contract is stable. This is only used in tests for `sol!`.
-allow-git = ["https://github.com/alloy-rs/core"]