docs: contract abi arg and provided Rust/ink! to Solidity type mappings

Author: davidsemakula

crates/ink/macro/src/lib.rs

@@ -117,6 +117,113 @@ pub fn selector_bytes(input: TokenStream) -> TokenStream {
 ///
 /// The `#[ink::contract]` macro can be provided with some additional comma-separated
 /// header arguments:
+/// - `abi: String`
+///
+///   Tells the ink! code generator which ABI (Application Binary Interface)
+///   specification(s) to support for contract interactions
+///   (i.e. which calling conventions to use for message calls).
+///
+///   **Default value:** `"ink"`
+///
+///   **Allowed values:** `"ink"`, `"sol"`, `"all"`
+///
+///   **Usage Example:**
+///   ```
+///   #[ink::contract(abi = "sol")]
+///   mod my_contract {
+///       # #[ink(storage)]
+///       # pub struct MyStorage;
+///       # impl MyStorage {
+///       #     #[ink(constructor)]
+///       //    #[bar]
+///       #     pub fn construct() -> Self { MyStorage {} }
+///       #     #[ink(message)]
+///       //    #[foo]
+///       #     pub fn message(&self) {}
+///       # }
+///       // ...
+///   }
+///   ```
+///
+///   - `abi = "ink"`
+///
+///      The code generator follows the ink! ABI specification. This means:
+///      - By default, message selectors are generated according to the [ink! ABI
+///        specification for selectors][ink-spec-selector]
+///      - Message selectors can be manually overridden using the [`selector` attribute
+///        argument][ink-selector-attribute]
+///      - Parity's [SCALE Codec][scale-codec] is used for input/output encoding/decoding
+///
+///   - `abi = "sol"`
+///
+///      The code generator follows the [Solidity ABI specification][sol-spec].
+///      This means:
+///      - Message selectors are **always** generated according to the [Solidity ABI
+///        specification for function selectors][sol-spec-selector]
+///      - Message selector manual overrides using the [`selector` attribute
+///        argument][ink-selector-attribute] are ignored
+///      - [Solidity ABI encoding][sol-abi-codec] is used for input/output
+///        encoding/decoding
+///
+///   - `abi = "all"`
+///
+///     The code generator will generate selectors and input/output encoding/decoding
+///     logic for both ink! and Solidity ABI.
+///
+///     Please note that your contract sizes will get larger if you support both the ink!
+///     and Solidity ABI.
+///
+///   For contracts that support Solidity ABI encoding
+///   (i.e. `abi = "sol"` or `abi = "all"`), all types used as constructor/message
+///   arguments and return types must define a mapping to an equivalent Solidity type.
+///   This mapping is defined using the [`SolEncode`][sol-trait-encode] and
+///   [`SolDecode`][sol-trait-decode] traits that are analogs to `scale::Encode` and
+///   `scale::Decode` (but for Solidity ABI encoding/decoding).
+///
+///   [`SolEncode`][sol-trait-encode] and [`SolDecode`][sol-trait-decode] are implemented
+///   for the following Rust/ink! primitive types creating a mapping
+///   to the corresponding Solidity ABI types as shown in the table below:
+///
+///   | Rust/ink! type | Solidity ABI type | Notes |
+///   | -------------- | ----------------- | ----- |
+///   | `bool` | `bool` ||
+///   | `iN` for `N ∈ {8,16,32,64,128}` | `intN` | e.g `i8` <=> `int8` |
+///   | `uN` for `N ∈ {8,16,32,64,128}` | `uintN` | e.g `u8` <=> `uint8` |
+///   | `U256` | `uint256` ||
+///   | `String` | `string` ||
+///   | `Address` | `address` ||
+///   | `[T; N]` for `const N: usize` | `T[N]` | e.g. `[i8; 64]` <=> `int8[64]` |
+///   | `Vec<T>` | `T[]` | e.g. `Vec<i8>` <=> `int8[]` |
+///   | `AsSolBytes<[u8; N]>` for `1 <= N <= 32` |  `bytesN` | e.g. `AsSolBytes<[u8; 1]>` <=> `bytes1` |
+///   | `AsSolBytes<Vec<u8>>` |  `bytes` ||
+///   | `(T1, T2, T3, ... T12)` | `(U1, U2, U3, ... U12)` | where `T1` <=> `U1`, ... `T12` <=> `U12` e.g. `(bool, u8, Address)` <=> `(bool, uint8, address)` |
+///
+///   [`SolEncode`][sol-trait-encode] is additionally implemented for reference and smart
+///   pointer types below:
+///
+///   | Rust/ink! type | Solidity ABI type | Notes |
+///   | -------------- | ----------------- | ----- |
+///   | `&str`, `&mut str`, `Box<str>` | string ||
+///   | `&T`, `&mut T`, `Box<T>` | T | e.g. `&i8 <=> int8` |
+///   | `&[T]`, `&mut [T]`, `Box<[T]>` | T[] | e.g. `&[i8]` <=> `int8[]` |
+///
+///   See the rustdoc for [`SolEncode`][sol-trait-encode] and
+///   [`SolDecode`][sol-trait-decode] for instructions for implementing the traits for
+///   custom arbitrary types.
+///
+///   Please note that Rust's [coherence/orphan rules][rust-coherence] mean that you can
+///   only implement the [`SolEncode`][sol-trait-encode] and
+///   [`SolDecode`][sol-trait-decode]   traits for local types.
+///
+/// [ink-spec-selector]: https://use.ink/basics/selectors/
+/// [ink-selector-attribute]: https://use.ink/macros-attributes/selector
+/// [scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec
+/// [sol-spec]: https://docs.soliditylang.org/en/latest/abi-spec.html
+/// [sol-spec-selector]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector
+/// [sol-abi-codec]: https://docs.soliditylang.org/en/latest/abi-spec.html#formal-specification-of-the-encoding
+/// [sol-trait-encode]: https://docs.rs/ink/latest/ink/trait.SolEncode.html
+/// [sol-trait-decode]: https://docs.rs/ink/latest/ink/trait.SolEncode.html
+/// [rust-coherence]: https://doc.rust-lang.org/reference/items/implementations.html#trait-implementation-coherence
 ///
 /// - `keep_attr: String`
 ///