docs(json-abi): add README.md

README.md

@@ -26,7 +26,7 @@ This repository contains the following crates:
 - [`alloy-sol-types`] - Compile-time [ABI] and [EIP-712] implementations
 - [`alloy-sol-macro`] - The [`sol!`] procedural macro
 - [`alloy-dyn-abi`] - Run-time [ABI] and [EIP-712] implementations
-- [`alloy-json-abi`] - [JSON-ABI] implementation
+- [`alloy-json-abi`] - Full Ethereum [JSON-ABI] implementation
 - [`alloy-sol-type-parser`] - A simple parser for Solidity type strings
 - [`syn-solidity`] - [`syn`]-powered Solidity parser
 

crates/json-abi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "alloy-json-abi"
-description = "Ethereum ABI JSON file (de)serialization"
+description = "Full Ethereum JSON-ABI implementation"
 keywords = ["ethereum", "abi", "serialization"]
 categories = ["encoding", "cryptography::cryptocurrencies"]
 homepage = "https://github.com/alloy-rs/core/tree/main/crates/json-abi"

crates/json-abi/README.md

@@ -0,0 +1,37 @@
+# alloy-json-abi
+
+Full Ethereum [JSON-ABI] implementation.
+
+This crate is a re-implementation of a part of [ethabi]'s API, with a few main
+differences:
+- the `Contract` struct is now called `JsonAbi` and also contains the `fallback`
+  and `receive` functions
+- the `Param` and `EventParam` structs only partially parse the type string
+  instead of fully resolving it into a Solidity type
+
+[JSON-ABI]: https://docs.soliditylang.org/en/latest/abi-spec.html#json
+[ethabi]: https://crates.io/crates/ethabi
+
+## Examples
+
+Parse a JSON ABI file into a `JsonAbi` struct:
+
+```rust
+use alloy_json_abi::JsonAbi;
+
+# stringify!(
+let path = "path/to/abi.json";
+let json = std::fs::read_to_string(path).unwrap();
+# );
+# let json = "[]";
+let abi: JsonAbi = serde_json::from_str(&json).unwrap();
+for item in abi.items() {
+    println!("{item:?}");
+}
+```
+
+Resolve a `Function`'s input type with [`alloy-dyn-abi`](../dyn-abi):
+
+```rust,ignore
+todo!()
+```

crates/json-abi/src/lib.rs

@@ -7,17 +7,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! ABI JSON file format for Solidity contracts.
-//!
-//! Please consult the [specification] for full details.
-//!
-//! This crate is a reimplementation of [ethabi]. There's only one right way to
-//! implement a JSON serialization scheme in rust. So while the internals are
-//! nearly-identical, the API is our own.
-//!
-//! [specification]: https://docs.soliditylang.org/en/latest/abi-spec.html#json
-//! [ethabi]: https://github.com/rust-ethereum/ethabi
-
+#![doc = include_str!("../README.md")]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/alloy-rs/core/main/assets/alloy.jpg",
     html_favicon_url = "https://raw.githubusercontent.com/alloy-rs/core/main/assets/favicon.ico"