From 8cfbb786f4f5149695a8a328c4a7fb6b9dd8cad6 Mon Sep 17 00:00:00 2001 From: DaniPopes <57450786+DaniPopes@users.noreply.github.com> Date: Thu, 18 Jan 2024 22:55:51 +0100 Subject: [PATCH] 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 --------- Co-authored-by: Georgios Konstantopoulos --- .github/ISSUE_TEMPLATE/BUG-FORM.yml | 12 ++--- .github/ISSUE_TEMPLATE/FEATURE-FORM.yml | 15 +++--- README.md | 61 ++++++++++++++++++++----- crates/consensus/README.md | 2 +- crates/eips/README.md | 2 + crates/genesis/Cargo.toml | 3 +- crates/genesis/README.md | 13 ++---- crates/providers/README.md | 2 +- crates/pubsub/README.md | 4 +- crates/rpc-client/Cargo.toml | 2 +- crates/rpc-client/README.md | 2 +- crates/rpc-engine-types/Cargo.toml | 4 +- crates/rpc-engine-types/README.md | 2 +- crates/rpc-trace-types/Cargo.toml | 2 +- crates/rpc-trace-types/README.md | 2 +- crates/transport/Cargo.toml | 2 +- crates/transport/README.md | 2 +- 17 files changed, 81 insertions(+), 51 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/BUG-FORM.yml b/.github/ISSUE_TEMPLATE/BUG-FORM.yml index d0ff0800413..7fddd64437a 100644 --- 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 index 52ad62a0b2e..1c5f929cbef 100644 --- a/.github/ISSUE_TEMPLATE/FEATURE-FORM.yml +++ b/.github/ISSUE_TEMPLATE/FEATURE-FORM.yml @@ -13,12 +13,11 @@ 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: @@ -26,7 +25,9 @@ body: - 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 index f16254cd916..06c49c89189 100644 --- 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 index cd4a01083a0..e16ce91961f 100644 --- 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 index bc45b7ea908..d6a77560316 100644 --- 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 index b8c9b484885..a63cadba21c 100644 --- 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 index 43332c322f5..5ad846c7f18 100644 --- 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. \ No newline at end of file +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 index 86995f55c25..42dfce29295 100644 --- a/crates/providers/README.md +++ b/crates/providers/README.md @@ -2,7 +2,7 @@ -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 index b8717dbc808..79a1d224d25 100644 --- 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 index 5d62220fd98..ae9284525fb 100644 --- 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 index 3e561b28408..5080e063a51 100644 --- 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 index b955b369e64..fb68134580a 100644 --- 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 \ No newline at end of file +similar-asserts.workspace = true diff --git a/crates/rpc-engine-types/README.md b/crates/rpc-engine-types/README.md index 79a7d3b5300..ecaa5c81d3b 100644 --- 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. \ No newline at end of file +Ethereum execution-consensus layer (engine) API RPC types. diff --git a/crates/rpc-trace-types/Cargo.toml b/crates/rpc-trace-types/Cargo.toml index 5ddd5456126..5c31ddca602 100644 --- 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 index 373e7b2658c..e8ebfe0394c 100644 --- 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 index d7a2e391ac2..85a06b3e992 100644 --- 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 index f912a06c33c..e74408027e3 100644 --- a/crates/transport/README.md +++ b/crates/transport/README.md @@ -2,7 +2,7 @@ -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