From 435a3b64102e043e02460ee5c9c12612eaab4792 Mon Sep 17 00:00:00 2001
From: DaniPopes <57450786+DaniPopes@users.noreply.github.com>
Date: Wed, 23 Aug 2023 16:57:06 +0200
Subject: [PATCH] chore(primitives): discourage use of `B160` (#235)

---
 crates/primitives/src/aliases.rs      | 10 +++++++---
 crates/primitives/src/bits/address.rs |  6 +++---
 crates/primitives/src/lib.rs          | 20 ++++++++++++++++++--
 3 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/crates/primitives/src/aliases.rs b/crates/primitives/src/aliases.rs
index 3c5ff1cd22..d558222108 100644
--- a/crates/primitives/src/aliases.rs
+++ b/crates/primitives/src/aliases.rs
@@ -33,8 +33,9 @@ int_aliases! {
 }
 
 macro_rules! fixed_bytes_aliases {
-    ($($name:ident<$N:literal>),* $(,)?) => {$(
+    ($($(#[$attr:meta])* $name:ident<$N:literal>),* $(,)?) => {$(
         #[doc = concat!($N, "-byte [fixed byte-array][FixedBytes] type.")]
+        $(#[$attr])*
         pub type $name = FixedBytes<$N>;
     )*};
 }
@@ -46,6 +47,9 @@ fixed_bytes_aliases! {
     B64<8>,
     B96<12>,
     B128<16>,
+    /// See [`crate::B160`] as to why you likely want to use
+    /// [`Address`](crate::Address) instead.
+    #[doc(hidden)]
     B160<20>,
     B192<24>,
     B224<28>,
@@ -79,6 +83,6 @@ pub type StorageKey = B256;
 /// An account storage value.
 pub type StorageValue = U256;
 
-/// Solidity contract functions are addressed using the first four byte of the
-/// Keccak-256 hash of their signature
+/// Solidity contract functions are addressed using the first four bytes of the
+/// Keccak-256 hash of their signature.
 pub type Selector = [u8; 4];
diff --git a/crates/primitives/src/bits/address.rs b/crates/primitives/src/bits/address.rs
index 520cb12f23..def0ed028a 100644
--- a/crates/primitives/src/bits/address.rs
+++ b/crates/primitives/src/bits/address.rs
@@ -47,9 +47,9 @@ wrap_fixed_bytes!(
     extra_derives: [],
     /// An Ethereum address, 20 bytes in length.
     ///
-    /// This type is separate from [`FixedBytes<20>`] and is declared with the
-    /// [`wrap_fixed_bytes!`] macro. This allows us to implement address-specific
-    /// functionality.
+    /// This type is separate from [`B160`](crate::B160) / [`FixedBytes<20>`]
+    /// and is declared with the [`wrap_fixed_bytes!`] macro. This allows us
+    /// to implement address-specific functionality.
     ///
     /// The main difference with the generic [`FixedBytes`] implementation is that
     /// [`Display`] formats the address using its [EIP-55] checksum
diff --git a/crates/primitives/src/lib.rs b/crates/primitives/src/lib.rs
index 1331638679..a6fe985487 100644
--- a/crates/primitives/src/lib.rs
+++ b/crates/primitives/src/lib.rs
@@ -27,8 +27,8 @@ pub mod aliases;
 #[doc(no_inline)]
 pub use aliases::{
     BlockHash, BlockNumber, ChainId, Selector, StorageKey, StorageValue, TxHash, TxIndex, TxNumber,
-    B128, B160, B256, B512, B64, I128, I16, I160, I256, I32, I64, I8, U128, U16, U160, U256, U32,
-    U512, U64, U8,
+    B128, B256, B512, B64, I128, I16, I160, I256, I32, I64, I8, U128, U16, U160, U256, U32, U512,
+    U64, U8,
 };
 
 mod bits;
@@ -62,6 +62,22 @@ pub use tiny_keccak::{self, Hasher, Keccak};
 #[doc(no_inline)]
 pub use ::hex::serde as serde_hex;
 
+/// 20-byte [fixed byte-array][FixedBytes] type.
+///
+/// You'll likely want to use [`Address`] instead, as it is a different type
+/// from `FixedBytes<20>`, and implements methods useful for working with
+/// Ethereum addresses.
+///
+/// If you are sure you want to use this type, and you don't want the
+/// deprecation warning, you can use `aliases::B160`.
+#[deprecated(
+    since = "0.3.2",
+    note = "you likely want to use `Address` instead. \
+            `B160` and `Address` are different types, \
+            see this type's documentation for more."
+)]
+pub type B160 = FixedBytes<20>;
+
 // Not public API.
 #[doc(hidden)]
 pub mod private {