docs: update descriptions and top level summary (#128)

* chore(meta): update components in report forms * docs: update descriptions and top level summary * Apply suggestions from code review Co-authored-by: Georgios Konstantopoulos <[email protected]> --------- Co-authored-by: Georgios Konstantopoulos <[email protected]>
alloy-rs · Jan 18, 2024 · 8cfbb78 · 8cfbb78
1 parent edf9518
commit 8cfbb78
Show file tree

Hide file tree

Showing 17 changed files with 81 additions and 51 deletions.
diff --git a/.github/ISSUE_TEMPLATE/BUG-FORM.yml b/.github/ISSUE_TEMPLATE/BUG-FORM.yml
@@ -15,13 +15,11 @@ body:
       description: What component is the bug in?
       multiple: true
       options:
-        - consensus
-        - json-rpc
-        - networks
-        - providers
-        - pubsub
-        - rpc-client
-        - rpc-types
+        - consensus, eips, genesis
+        - network, json-rpc
+        - nodes
+        - providers, pubsub
+        - rpc
         - signers
         - transports
     validations:

diff --git a/.github/ISSUE_TEMPLATE/FEATURE-FORM.yml b/.github/ISSUE_TEMPLATE/FEATURE-FORM.yml
@@ -13,20 +13,21 @@ body:
       description: What component is the feature for?
       multiple: true
       options:
-        - json-rpc
-        - networks
-        - providers
-        - pubsub
-        - rpc-client
-        - rpc-types
+        - consensus, eips, genesis
+        - network, json-rpc
+        - nodes
+        - providers, pubsub
+        - rpc
         - signers
         - transports
     validations:
       required: true
   - type: textarea
     attributes:
       label: Describe the feature you would like
-      description: Please also describe your goals for the feature. What problems it solves, how it would be used, etc.
+      description:
+        Please also describe your goals for the feature. What problems it solves, how it would be
+        used, etc.
     validations:
       required: true
   - type: textarea

diff --git a/README.md b/README.md
@@ -18,18 +18,55 @@ feature-parity in Alloy. No action is currently needed from devs.
 
 This repository contains the following crates:
 
-- [`alloy-json-rpc`] - Core data types for JSON-RPC 2.0 clients.
-- [`alloy-transport`] - Transport implementations for JSON-RPC 2.0 clients.
-- [`alloy-networks`] - Network abstraction for RPC types. Allows capturing
-  different RPC param and response types on a per-network basis.
-- [`alloy-providers`] - A client trait for interacting with Ethereum-like RPC
-  endpoints. Abstract over `alloy_networks::Network`, which allows capturing
-  different RPC types on a per-network basis.
-
-[`alloy-json-rpc`]: ./crates/json-rpc
-[`alloy-transport`]: ./crates/transport
-[`alloy-networks`]: ./crates/networks
-[`alloy-providers`]: ./crates/providers
+- [`alloy-consensus`] - Ethereum consensus interface
+- [`alloy-eips`] - Ethereum Improvement Proprosal (EIP) implementations
+- [`alloy-genesis`] - Ethereum genesis file definitions
+- [`alloy-json-rpc`] - Core data types for JSON-RPC 2.0 clients
+- [`alloy-network`] - Network abstraction for RPC types
+- [`alloy-node-bindings`] - Ethereum execution-layer client bindings
+- [`alloy-providers`] - Client trait for interacting with Ethereum-like RPC endpoints
+- [`alloy-pubsub`] - Ethereum JSON-RPC [publish-subscribe] provider
+- [`alloy-rpc-client`] - High-level Ethereum JSON-RPC client implementation
+- [`alloy-rpc-types`] - Ethereum JSON-RPC types
+  - [`alloy-rpc-engine-types`] - Ethereum execution-consensus layer (engine) API RPC types
+  - [`alloy-rpc-trace-types`] - Ethereum RPC trace types
+- [`alloy-signer`] - Ethereum signer abstraction
+  - [`alloy-signer-aws`] - [AWS KMS] signer implementation
+  - [`alloy-signer-gcp`] - [GCP KMS] signer implementation
+  - [`alloy-signer-ledger`] - [Ledger] signer implementation
+  - [`alloy-signer-trezor`] - [Trezor] signer implementation
+- [`alloy-transport`] - Low-level Ethereum JSON-RPC transport abstraction
+  - [`alloy-transport-http`] - HTTP transport implementation
+  - [`alloy-transport-ipc`] - IPC transport implementation
+  - [`alloy-transport-ws`] - WS transport implementation
+
+[`alloy-consensus`]: crates/consensus
+[`alloy-eips`]: crates/eips
+[`alloy-genesis`]: crates/genesis
+[`alloy-json-rpc`]: crates/json-rpc
+[`alloy-network`]: crates/network
+[`alloy-node-bindings`]: crates/node-bindings
+[`alloy-providers`]: crates/providers
+[`alloy-pubsub`]: crates/pubsub
+[`alloy-rpc-client`]: crates/rpc-client
+[`alloy-rpc-engine-types`]: crates/rpc-engine-types
+[`alloy-rpc-trace-types`]: crates/rpc-trace-types
+[`alloy-rpc-types`]: crates/rpc-types
+[`alloy-signer`]: crates/signer
+[`alloy-signer-aws`]: crates/signer-aws
+[`alloy-signer-gcp`]: crates/signer-gcp
+[`alloy-signer-ledger`]: crates/signer-ledger
+[`alloy-signer-trezor`]: crates/signer-trezor
+[`alloy-transport`]: crates/transport
+[`alloy-transport-http`]: crates/transport-http
+[`alloy-transport-ipc`]: crates/transport-ipc
+[`alloy-transport-ws`]: crates/transport-ws
+
+[publish-subscribe]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern
+[AWS KMS]: https://aws.amazon.com/kms
+[GCP KMS]: https://cloud.google.com/kms
+[Ledger]: https://www.ledger.com
+[Trezor]: https://trezor.io
 
 ## Supported Rust Versions
 

diff --git a/crates/consensus/README.md b/crates/consensus/README.md
@@ -1,6 +1,6 @@
 # alloy-consensus
 
-Consensus types for the Ethereum blockchain.
+Ethereum consensus interface.
 
 This crate contains constants, types, and functions for implementing Ethereum
 EL consensus and communication. This includes headers, blocks, transactions,

diff --git a/crates/eips/README.md b/crates/eips/README.md
@@ -1,5 +1,7 @@
 # alloy-eips
 
+Ethereum Improvement Proprosal (EIP) implementations.
+
 Contains constants, helpers, and basic data structures for consensus EIPs.
 
 ## Current support

diff --git a/crates/genesis/Cargo.toml b/crates/genesis/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-genesis"
-description = "Genesis types "
+description = "Ethereum genesis file definitions"
 
 version.workspace = true
 edition.workspace = true
@@ -20,4 +20,3 @@ serde.workspace = true
 
 [dev-dependencies]
 serde_json.workspace = true
-
diff --git a/crates/genesis/README.md b/crates/genesis/README.md
@@ -1,13 +1,6 @@
 # alloy-genesis
 
-The genesis file in an Ethereum blockchain is a JSON-formatted file used to define the initial state of the blockchain at the time of its creation. alloy-genesis provides tools and structures to create, manipulate, and interpret these genesis files, ensuring seamless integration and configuration for Ethereum-compatible networks.
+Ethereum genesis file definitions.
 
-## Features
-
-- `Genesis Block Configuration`- Facilitates the creation and definition of genesis blocks, including parameters such as nonce, timestamp, gas limits, and initial account states.
-- `Custom Account Initialization`- Allows for the specification of custom accounts with predefined balances, nonces, and contract codes in the genesis block.
-- `Network Compatibility`- Designed to work with Ethereum-like networks, ensuring compatibility with various Ethereum standards.
-
-## Usage
-
-This crate is primarily used internally within the Alloy project and is not intended for direct use. However, it can be utilized by blockchain developers or maintainers for setting up new Ethereum-like networks or for testing purposes.
+The genesis file in an Ethereum blockchain is a JSON-formatted file used to
+define the initial state of the blockchain at the time of its creation.
diff --git a/crates/providers/README.md b/crates/providers/README.md
@@ -2,7 +2,7 @@
 
 <!-- TODO: links, docs, examples, etc -->
 
-Ethereum JSON-RPC providers.
+Client trait for interacting with Ethereum-like RPC endpoints.
 
 This crate contains the `Provider` trait, which exposes Ethereum JSON-RPC
 methods. Providers in alloy are similar to ethers.js Providers. They manage an

diff --git a/crates/pubsub/README.md b/crates/pubsub/README.md
@@ -1,8 +1,8 @@
 # alloy-pubsub
 
-[Publish-subscribe] Alloy provider.
+Ethereum JSON-RPC [publish-subscribe] provider.
 
-[Publish-subscribe]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern
+[publish-subscribe]: https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern
 
 ## Overview
 

diff --git a/crates/rpc-client/Cargo.toml b/crates/rpc-client/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-client"
-description = "RPC client"
+description = "High-level Ethereum JSON-RPC client implementation"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/rpc-client/README.md b/crates/rpc-client/README.md
@@ -1,3 +1,3 @@
 # alloy-rpc-client
 
-RPC client.
+High-level Ethereum JSON-RPC client implementation.
diff --git a/crates/rpc-engine-types/Cargo.toml b/crates/rpc-engine-types/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-engine-types"
-description = "Alloy RPC engine types"
+description = "Ethereum execution-consensus layer (engine) API RPC types"
 
 version.workspace = true
 edition.workspace = true
@@ -32,4 +32,4 @@ alloy-primitives = { workspace = true, features = ["rand", "rlp", "serde", "arbi
 arbitrary = { workspace = true, features = ["derive"] }
 rand.workspace = true
 serde_json.workspace = true
-similar-asserts.workspace = true
+similar-asserts.workspace = true
diff --git a/crates/rpc-engine-types/README.md b/crates/rpc-engine-types/README.md
@@ -1,3 +1,3 @@
 # alloy-engine-rpc-types
 
-Engine related RPC types for Alloy.
+Ethereum execution-consensus layer (engine) API RPC types.
diff --git a/crates/rpc-trace-types/Cargo.toml b/crates/rpc-trace-types/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-rpc-trace-types"
-description = "RPC trace types"
+description = "Ethereum RPC trace types"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/rpc-trace-types/README.md b/crates/rpc-trace-types/README.md
@@ -1,3 +1,3 @@
 # alloy-rpc-trace-types
 
-RPC trace types.
+Ethereum RPC trace types.
diff --git a/crates/transport/Cargo.toml b/crates/transport/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "alloy-transport"
-description = "Transport implementations for Alloy providers"
+description = "Low-level Ethereum JSON-RPC transport abstraction"
 
 version.workspace = true
 edition.workspace = true

diff --git a/crates/transport/README.md b/crates/transport/README.md
@@ -2,7 +2,7 @@
 
 <!-- TODO: More links and real doctests -->
 
-Transport implementations for Alloy providers.
+Low-level Ethereum JSON-RPC transport abstraction.
 
 This crate handles RPC connection and request management. It builds an
 `RpcClient` on top of the [tower `Service`] abstraction, and provides