Merge pull request #70 from alloy-rs/yash/core-1.0

feat: migrating to core v1.0

Author: DaniPopes

src/SUMMARY.md

@@ -151,6 +151,20 @@
 
 <!-- MANUALLY MAINTAINED -->
 
+# Migrating to `alloy-core` v1.0
+
+- [Highlights](./migrating-to-core-1.0/README.md)
+- [sol! macro changes](./migrating-to-core-1.0/sol!-changes/README.md)
+  - [Removing the `T` transport generic](./migrating-to-core-1.0/sol!-changes/removing-T-generic.md)
+  - [Improving function return type](./migrating-to-core-1.0/sol!-changes/improving-function-return-types.md)
+  - [Changes to function call bindings](./migrating-to-core-1.0/sol!-changes/changes-to-function-call-bindings.md)
+  - [Changes to event bindings](./migrating-to-core-1.0/sol!-changes/changes-to-event-bindings.md)
+  - [Changes to error bindings](./migrating-to-core-1.0/sol!-changes/changes-to-error-bindings.md)
+- [Simplify ABI encoding and decoding](./migrating-to-core-1.0/encoding-decoding-changes/README.md)
+  - [Encoding function return structs](./migrating-to-core-1.0/encoding-decoding-changes/encoding-return-structs.md)
+  - [Removing `validate: bool` from the `abi_decode` methods](./migrating-to-core-1.0/encoding-decoding-changes/removing-validate-bool.md)
+- [Other breaking changes](./migrating-to-core-1.0/other-breaking-changes.md)
+
 # Appendix
 
 - [Help us improve Alloy](./appendix/contributing.md)

src/migrating-to-core-1.0/README.md

@@ -0,0 +1,23 @@
+# Core v1.0 Highlights
+
+### Revamping the `sol!` macro bindings
+
+- [Contract and RPC codegen made cleaner by removal of the `T` transport generic](./sol!-changes/removing-T-generic.md)
+- [Improving the function return types by removing the need for `_0`](./sol!-changes/improving-function-return-types.md)
+- [Changes to function call bindings e.g `pub struct balanceOfCall { _0: Address }` to `pub struct balanceOfCall(pub Address)`](./sol!-changes/changes-to-function-call-bindings.md)
+- [Changes to event bindings](./sol!-changes/changes-to-event-bindings.md)
+- [Changes to error bindings](./sol!-changes/changes-to-error-bindings.md)
+
+### Simplify ABI encoding and decoding
+
+- [ABI encoding function return structs](./encoding-decoding-changes/encoding-return-structs.md)
+- [Removing `validate: bool` from the `abi_decode` methods](./encoding-decoding-changes/removing-validate-bool.md)
+
+### Other breaking changes
+
+- [Removal of the deprecated `Signature` type. `PrimitiveSignature` is now aliased to `Signature`](https://github.com/alloy-rs/core/pull/899)
+- [Renaming methods in User-defined types (UDT)'s bindings and implementing `From` and `Into` traits for UDT's](https://github.com/alloy-rs/core/pull/905)
+- [Bumping `getrandom` and `rand`](https://github.com/alloy-rs/core/pull/869)
+- [Removal of `From<String>` for `Bytes`](https://github.com/alloy-rs/core/pull/907)
+
+If you'd like to dive into the details of each change, please take a look at this [PR](https://github.com/alloy-rs/core/pull/895)

src/migrating-to-core-1.0/encoding-decoding-changes/README.md

@@ -0,0 +1,4 @@
+## Simply ABI encoding and decoding
+
+- [ABI encoding function return structs](./encoding-return-structs.md)
+- [Removing `validate: bool` from the `abi_decode` methods](./removing-validate-bool.md)

src/migrating-to-core-1.0/encoding-decoding-changes/encoding-return-structs.md

@@ -0,0 +1,27 @@
+## Encoding return structs
+
+[core#909](https://github.com/alloy-rs/core/pull/909) improves return type encoding by allowing to pass the return struct directly into `SolCall::abi_encode_returns`.
+
+Consider the following:
+
+```rust,ignore
+sol! {
+    function something() returns (uint256, address);
+}
+```
+
+### Before
+
+A tuple would need to passed of the fields from return type, `somethingReturn`
+
+```rust,ignore
+let encoding = somethingCall::abi_encode_returns(&(somethingReturn._0, somethingReturn._1));
+```
+
+### After
+
+One can now pass the return struct directly without deconstructing it as a tuple.
+
+```rust,ignore
+let encoding = somethingCall::abi_encode_returns(&somethingReturn);
+```

src/migrating-to-core-1.0/encoding-decoding-changes/removing-validate-bool.md

@@ -0,0 +1,3 @@
+## Removing the `validate: bool` from the `abi_decode` methods
+
+[core#863](https://github.com/alloy-rs/core/pull/863) removes the `validate: bool` parameter from the `abi_decode_*` methods. The behaviour of these `abi_decode_*` methods is now equivalent to passing `validate = false`.

src/migrating-to-core-1.0/other-breaking-changes.md

@@ -0,0 +1,6 @@
+## Other breaking changes
+
+- [Removal of the deprecated `Signature` type. `PrimitiveSignature` is now aliased to `Signature`](https://github.com/alloy-rs/core/pull/899)
+- [Renaming methods in User-defined types (UDT)'s bindings and implementing `From` and `Into` traits for UDT's](https://github.com/alloy-rs/core/pull/905)
+- [Bumping `getrandom` and `rand`](https://github.com/alloy-rs/core/pull/869)
+- [Removal of `From<String>` for `Bytes`](https://github.com/alloy-rs/core/pull/907)

src/migrating-to-core-1.0/sol!-changes/README.md

@@ -0,0 +1,7 @@
+## sol! changes
+
+- [Removing the `T` transport generic](./removing-T-generic.md)
+- [Improving function return type](./improving-function-return-types.md)
+- [Changes to function call bindings](./changes-to-function-call-bindings.md)
+- [Changes to event bindings](./changes-to-event-bindings.md)
+- [Changes to error bindings](./changes-to-error-bindings.md)

src/migrating-to-core-1.0/sol!-changes/changes-to-error-bindings.md

@@ -0,0 +1,49 @@
+## Changes to error bindings
+
+[core#883](https://github.com/alloy-rs/core/pull/883) makes similar changes to the error bindings that [core#884](https://github.com/alloy-rs/core/pull/884) did to function call bindings in the sense that the form of the generated type is dependent upon two factors:
+
+1. Number of parameters the error has.
+2. Whether the parameter is named or unnamed in case it has only **one** param
+
+Consider the following example:
+
+```rust,ignore
+sol! {
+   // No params/args
+   error Some();
+   // Exactly one unnamed param
+   error Another(uint256);
+   // Exactly one named param - bindings for this remain unchanged
+   error YetAnother(uint256 a);
+}
+```
+
+## Before
+
+All of the above were generated as regular structs.
+
+```rust,ignore
+// Empty struct
+pub struct SomeError { };
+
+pub struct AnotherError {
+    _0: U256
+}
+
+pub struct YetAnotherError {
+    a: U256
+}
+```
+
+## After
+
+```rust,ignore
+
+// Unit struct for error with no params
+pub struct SomeError;
+
+// Tuple struct for SINGLE UNNAMED param
+pub struct AnotherError(pub U256);
+```
+
+Bindings remain **unchanged** for errors with **multiple params** and **single but named param**.

src/migrating-to-core-1.0/sol!-changes/changes-to-event-bindings.md

@@ -0,0 +1,30 @@
+## Changes to event bindings
+
+[core#885](https://github.com/alloy-rs/core/pull/885) makes changes to the event bindings in a breaking but very minimal way.
+It changes the bindings for **only** events with no parameters
+
+Consider the following event:
+
+```rust,ignore
+sol! {
+    event Incremented();
+}
+```
+
+### Before
+
+The generated struct was an empty struct like below:
+
+```rust,ignore
+pub struct Incremented { };
+```
+
+### After
+
+A unit struct is generated like below:
+
+```rust,ignore
+pub struct Incremented;
+```
+
+Bindings for events with parameters remain **unchanged**.

src/migrating-to-core-1.0/sol!-changes/changes-to-function-call-bindings.md

@@ -0,0 +1,60 @@
+## Changes to function call bindings
+
+With [core#884](https://github.com/alloy-rs/core/pull/884) the form of the generated call type (used for abi-encoding) is now dependent upon two factors:
+
+1. Number of parameters/args does the function take
+2. Whether the parameter is named or unnamed in case it has only **one** param
+
+Consider the following:
+
+```rust,ignore
+sol! {
+    // No params/args
+    function totalSupply() returns (uint256)
+    // Exactly one unnamed param
+    function balanceOf(address) returns (uint256);
+    // Multiple params - Bindings for this remain unchanged.
+    function approve(address spender, uint256 amount) returns (bool);
+}
+```
+
+### Before
+
+Generated bindings were independent of the number of parameters and names, and the following struct were generated for the above function calls
+
+```rust,ignore
+// A struct with no fields as there are no parameters.
+pub struct totalSupplyCall { };
+let encoding = totalSupplyCall { }.abi_encode();
+
+pub struct balanceOfCall { _0: Address };
+let encoding = balanceOfCall { _0: Address::ZERO }.abi_encode();
+```
+
+### After
+
+```rust,ignore
+// A unit struct is generated when there are no parameters.
+pub struct totalSupplyCall;
+let encoding = totalSupplyCall.abi_encode();
+
+// A tuple struct with a single value is generated in case of a SINGLE UNNAMED param.
+pub struct balanceOfCall(pub Address);
+let encoding = balanceOfCall(Address::ZERO).abi_encode();
+```
+
+Now if the parameter in `balanceOf` was named like so:
+
+```rust,ignore
+sol! {
+    function balanceOf(address owner) returns (uint256);
+}
+```
+
+Then a regular struct would be generated like before:
+
+```rust, ignore
+pub struct balanceOfCall { owner: Address };
+```
+
+Bindings for function calls with **multiple parameters** are **unchanged**.

src/migrating-to-core-1.0/sol!-changes/improving-function-return-types.md

@@ -0,0 +1,53 @@
+## Improving function call return types
+
+With the inclusion of [core#855](https://github.com/alloy-rs/core/pull/855) return values of function calls with a _singular_ value is more intuitive and easier to work with.
+
+Consider the following example of reading the balance of an ERC20:
+
+```rust,ignore
+sol! {
+    #[sol(rpc)]
+    contract ERC20 {
+        // Note: Only a single value is being returned
+        function balanceOf(address) returns (uint256);
+    }
+}
+```
+
+## Before
+
+Calling the `balanceOf` fn would return a struct `balanceOfReturn` which encapsulated the actual balance value.
+
+```rust,ignore
+// .. snip ..
+let balance_return: balanceOfReturn = erc20.balanceOf(owner).await?;
+
+let actual_balance = balance_return._0;
+```
+
+## After
+
+Calling the `balanceOf` fn would now yield the balance directly instead of a struct wrapping it.
+
+```rust,ignore
+// .. snip ..
+let balance: U256 = erc20.balanceOf(owner).await?;
+```
+
+It is important to note that this change only applies to function calls that have a **singular** return value.
+
+Function calls that **return multiple values** have their return types **unchanged**, i.e they still return a struct with values inside it.
+
+```rust,ignore
+sol! {
+    function multiValues() returns (uint256 a, address b, bytes c);
+}
+
+// The above function call will have the following return type.
+
+pub struct multiValuesReturn {
+    pub a: U256,
+    pub b: Address,
+    pub c: Bytes,
+}
+```

src/migrating-to-core-1.0/sol!-changes/removing-T-generic.md

@@ -0,0 +1,23 @@
+## Removing the `T` transport generic
+
+Since [alloy#1859](https://github.com/alloy-rs/alloy/pull/1859) the `Provider` is independent of the `Transport`, making it easier to roll types that wrap the `Provider`. This improvement was reflected in the [`CallBuilder`](https://docs.rs/alloy-contract/latest/alloy_contract/struct.CallBuilder.html) type but not carried to the `sol!` macro bindings.
+
+[core#865](https://github.com/alloy-rs/core/pull/865) removes the `T` transport generic from the `sol!` macro bindings, making the contract and RPC codegen cleaner.
+
+This can be demonstrated using a simple example that wraps an `ERC20Instance` type.
+
+### Before
+
+```rust,ignore
+struct Erc20<P: Provider> {
+    instance: ERC20Instance<(), P>,
+}
+```
+
+### After
+
+```rust,ignore
+struct Erc20<P: Provider> {
+    instance: ERC20Instance<P>,
+}
+```