Skip to content

Commit eaf1376

Browse files
davidsemakuladavidsemakula
committed
ABI docs
1 parent 0d4f534 commit eaf1376

File tree

7 files changed

+206
-87
lines changed

7 files changed

+206
-87
lines changed

‎versioned_docs/version-v6/background/solidity-metamask-compat.md

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,18 +20,26 @@ slug: /background/solidity-metamask-compatibility
2020

2121
# Solidity & MetaMask Compatibility
2222

23-
With ink! v6, we have introduced a new attribute argument `abi` for the `#[ink::contract]` macro.
24-
It allows building your contract in Solidity ABI compatibility mode ([more details here][contract-abi-arg]).
23+
With ink! v6, we have introduced an `abi` field in a custom `ink-lang` table
24+
in the [`package.metadata` table][package-metadata] of a contract's manifest
25+
file (i.e. the `Cargo.toml` file) - [more details here][abi-declaration].
26+
It allows building your contract in Solidity ABI compatibility mode.
2527

26-
The implication of supporting Solidity ABI encoding is that all types used as constructor/message arguments
27-
and return types must define a mapping to an equivalent Solidity type.
28+
```toml
29+
[package.metadata.ink-lang]
30+
abi = "sol"
31+
```
32+
33+
The implication of supporting Solidity ABI encoding is that all types used as constructor/message argument
34+
and return types, and event argument types must define a mapping to an equivalent Solidity ABI type.
2835

2936
This mapping is defined using the [`SolEncode`][sol-trait-encode] and [`SolDecode`][sol-trait-decode] traits,
3037
which are analogs to [`scale::Encode` and `scale::Decode`][scale-codec] (but for Solidity ABI encoding/decoding).
3138
You won't be able to use Rust types for which no mapping to a Solidity type exists.
3239
An error about a missing trait implementation for this type will be thrown.
3340

34-
[contract-abi-arg]: ../macros-attributes/contract.md#abi-string
41+
[package-metadata]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table
42+
[abi-declaration]: ../basics/abi#declaring-the-abi
3543
[sol-trait-encode]: https://docs.rs/ink/latest/ink/trait.SolEncode.html
3644
[sol-trait-decode]: https://docs.rs/ink/latest/ink/trait.SolEncode.html
3745
[scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec

‎versioned_docs/version-v6/basics/abi/all.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: |
3+
"All" ABI Mode
4+
hide_title: true
5+
slug: /basics/abi/all
6+
---
7+
8+
![Metadata Title Picture](/img/title/metadata-revive.svg)
9+
10+
# "All" ABI Mode
11+
12+
The "all" ABI mode is declared in the contract's manifest file (i.e. the `Cargo.toml` file)
13+
as follows:
14+
15+
```toml
16+
[package.metadata.ink-lang]
17+
abi = "all"
18+
```
19+
20+
When the "all" ABI is specified, the ink! code generator follows both
21+
the ink! and Solidity ABI specifications, and generates entry points
22+
for both calling conventions. This means:
23+
24+
- For each message, two selectors are generated, one for [ink!](./ink)
25+
and another for [Solidity](./solidity) ABI.
26+
- Each selector is ABI specific and its entry point uses the corresponding
27+
input/output encoding/decoding scheme (i.e. entry points for ink! selectors use
28+
Parity's [SCALE Codec][scale-codec], while entry points for Solidity selectors
29+
use Solidity ABI encoding/decoding for input/output encoding/decoding).
30+
- Message selector manual overrides
31+
(using the [`selector` attribute][selector-attribute]) are respected for
32+
ink! ABI entry points but ignored for Solidity ABI entry points
33+
(i.e. Solidity selectors are **always** generated according to the
34+
[Solidity ABI specification for function selectors][sol-abi-selector]).
35+
- Call builders are generated for both ink! and Solidity ABI calling conventions,
36+
and a `_sol` suffix is used to disambiguate Solidity calls.
37+
38+
:::note
39+
Your contract sizes will get larger if you support both the ink! and Solidity ABI.
40+
:::
41+
42+
:::note
43+
The "all" ABI mode can only be used if all constructor and message
44+
argument and return types, and event argument types can be mapped to
45+
equivalent Solidity ABI types ([more details here][sol-type-mapping]).
46+
:::
47+
48+
[scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec
49+
[sol-abi-selector]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector
50+
[selector-attribute]: ../../macros-attributes/selector
51+
[sol-type-mapping]: ../../background/solidity-metamask-compat.md#rustink-to-solidity-abi-type-mapping

‎versioned_docs/version-v6/basics/abi/ink.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: ink! ABI
3+
hide_title: true
4+
slug: /basics/abi/ink
5+
---
6+
7+
![Metadata Title Picture](/img/title/metadata-revive.svg)
8+
9+
# ink! ABI
10+
11+
The ink! ABI is declared in the contract's manifest file (i.e. the `Cargo.toml` file)
12+
as follows:
13+
14+
```toml
15+
[package.metadata.ink-lang]
16+
abi = "ink"
17+
```
18+
19+
When the ink! ABI is specified, the ink! code generator follows the ink! ABI specification.
20+
This means:
21+
22+
- By default, message selectors are generated according to the
23+
[ink! ABI specification for selectors][ink-spec-selector].
24+
- Message selectors can be manually overridden using the [`selector` attribute][selector-attribute].
25+
- Parity's [SCALE Codec][scale-codec] is used for input/output encoding/decoding.
26+
- Call builders (used for making cross-contract calls) are generated for ink! ABI
27+
calling conventions.
28+
29+
[ink-spec-selector]: ../../basics/selectors
30+
[selector-attribute]: ../../macros-attributes/selector
31+
[scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec

‎versioned_docs/version-v6/basics/abi/overview.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: Overview
3+
hide_title: true
4+
slug: /basics/abi
5+
---
6+
7+
![Metadata Title Picture](/img/title/metadata-revive.svg)
8+
9+
# ABI (Application Binary Interface)
10+
11+
An ABI (Application Binary Interface) defines a standard way to interact with contracts
12+
(i.e. it defines the calling conventions to use for message calls).
13+
14+
More concretely this entails:
15+
- Specifications for generating selectors which identify the entry points
16+
for message/function calls
17+
- Specifications for encoding and decoding message/function arguments and return types,
18+
as well as event and error argument types
19+
20+
With ink! v6, the ink! code generator supports two ABI specifications:
21+
22+
- [Our own native ink! ABI specification](./ink.md)
23+
- [The Solidity ABI specification](./solidity.md)
24+
25+
Supporting the Solidity ABI specification allows:
26+
- Solidity contracts to transparently call ink! contracts
27+
- Developers to use Solidity tools (e.g. [ethers.js][ethers-js]) to
28+
transparently interact with ink! contracts.
29+
30+
Additionally, the ink! code generator can operate in an [`"all"` ABI mode](./all.md),
31+
where it generates a binary that supports both the ink! and Solidity ABI specifications
32+
(i.e. it generates a binary that transparently supports both ink! and Solidity
33+
calling conventions, and thus transparently supports interactions from
34+
both ink! and Solidity contracts and external tools).
35+
36+
## Declaring the ABI
37+
38+
The ABI for an ink! contract is declared in the contract's manifest file
39+
(i.e. the `Cargo.toml` file), as a field `abi` of a custom `ink-lang` table
40+
in the [`package.metadata` table][package-metadata] e.g.
41+
42+
```toml
43+
[package.metadata.ink-lang]
44+
abi = "sol"
45+
```
46+
47+
The default value for `abi` is `"ink"`.
48+
49+
Allowed values are `"ink"`, `"sol"` and `"all"`.
50+
51+
:::note
52+
The Solidity ABI specification can only be used if all constructor and message
53+
argument and return types, and event argument types can be mapped to
54+
equivalent Solidity ABI types ([more details here][sol-type-mapping]).
55+
:::
56+
57+
:::note
58+
Your contract sizes will get larger if you support both the ink! and Solidity ABI.
59+
:::
60+
61+
[package-metadata]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table
62+
[ethers-js]: https://docs.ethers.org/
63+
[sol-type-mapping]: ../../background/solidity-metamask-compat.md#rustink-to-solidity-abi-type-mapping

‎versioned_docs/version-v6/basics/abi/solidity.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Solidity ABI
3+
hide_title: true
4+
slug: /basics/abi/solidity
5+
---
6+
7+
![Metadata Title Picture](/img/title/solidity.svg)
8+
9+
# Solidity ABI
10+
11+
The Solidity ABI is declared in the contract's manifest file (i.e. the `Cargo.toml` file)
12+
as follows:
13+
14+
```toml
15+
[package.metadata.ink-lang]
16+
abi = "sol"
17+
```
18+
19+
When the Solidity ABI is specified, the ink! code generator follows the [Solidity ABI specification][sol-abi].
20+
This means:
21+
22+
- Message selectors are **always** generated according to the
23+
[Solidity ABI specification for function selectors][sol-abi-selector].
24+
- Message selector manual overrides using the [`selector` attribute][selector-attribute] are ignored.
25+
- [Solidity ABI encoding][sol-abi-codec] is used for input/output encoding/decoding.
26+
- Call builders are generated for Solidity ABI calling conventions.
27+
28+
:::note
29+
The Solidity ABI specification can only be used if all constructor and message
30+
argument and return types, and event argument types can be mapped to
31+
equivalent Solidity ABI types ([more details here][sol-type-mapping]).
32+
:::
33+
34+
[sol-abi]: https://docs.soliditylang.org/en/latest/abi-spec.html
35+
[sol-abi-selector]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector
36+
[selector-attribute]: ../../macros-attributes/selector
37+
[sol-abi-codec]: https://docs.soliditylang.org/en/latest/abi-spec.html#formal-specification-of-the-encoding
38+
[sol-type-mapping]: ../../background/solidity-metamask-compat.md#rustink-to-solidity-abi-type-mapping

‎versioned_docs/version-v6/macros-attributes/contract.md

Lines changed: 0 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -25,88 +25,6 @@ proper code.
2525
The `#[ink::contract]` macro can be provided with some additional comma-separated
2626
header arguments:
2727

28-
### `abi: String`
29-
30-
Tells the ink! code generator which ABI (Application Binary Interface)
31-
specification(s) to support for contract interactions
32-
(i.e. which calling conventions to use for message calls).
33-
34-
**Default value:** `"ink"`
35-
36-
**Allowed values:** `"ink"`, `"sol"`, `"all"`
37-
38-
**Usage Example:**
39-
```rust
40-
#[ink::contract(abi = "sol")]
41-
mod my_contract {
42-
#[ink(storage)]
43-
pub struct MyStorage;
44-
45-
impl MyStorage {
46-
#[ink(constructor)]
47-
pub fn construct() -> Self { MyStorage {} }
48-
49-
#[ink(message)]
50-
pub fn message(&self) {}
51-
}
52-
53-
// ...
54-
}
55-
```
56-
57-
#### `abi = "ink"`
58-
59-
The code generator follows the ink! ABI specification. This means:
60-
- By default, message selectors are generated according to the
61-
[ink! ABI specification for selectors][ink-spec-selector].
62-
- Message selectors can be manually overridden using the `selector` attribute.
63-
- Parity's [SCALE Codec][scale-codec] is used for input/output encoding/decoding.
64-
- Call builders (used for making cross-contract calls) are generated for ink! ABI
65-
calling conventions.
66-
67-
#### `abi = "sol"`
68-
69-
The code generator follows the [Solidity ABI specification][sol-abi]. This means:
70-
71-
- Message selectors are **always** generated according to the
72-
[Solidity ABI specification for function selectors][sol-abi-selector].
73-
- Message selector manual overrides using the `selector` attribute are ignored.
74-
- [Solidity ABI encoding][sol-abi-codec] is used for input/output encoding/decoding.
75-
- Call builders are generated for Solidity ABI calling conventions.
76-
77-
#### `abi = "all"`
78-
79-
The code generator follows both the ink! and Solidity ABI specifications, and
80-
generates entry points for both calling conventions. This means:
81-
82-
- For each message, two selectors are generated, one for ink! and another for
83-
Solidity ABI.
84-
- Each selector is ABI specific and its entry point uses the corresponding
85-
input/output encoding/decoding scheme (i.e. entry points for ink! selectors use
86-
Parity's [SCALE Codec][scale-codec], while entry points for Solidity selectors
87-
use Solidity ABI encoding/decoding for input/output encoding/decoding).
88-
- Message selector manual overrides (using the `selector` attribute) are respected
89-
for ink! ABI entry points but ignored for Solidity ABI entry points
90-
(i.e. Solidity selectors are **always** generated according to the
91-
[Solidity ABI specification for function selectors][sol-abi-selector]).
92-
- Call builders are generated for both ink! and Solidity ABI calling conventions,
93-
and a `_sol` suffix is used to disambiguate Solidity calls.
94-
95-
:::note
96-
Your contract sizes will get larger if you support both the ink! and Solidity ABI.
97-
:::
98-
99-
For contracts that support Solidity ABI encoding (i.e. `abi = "sol"` or `abi = "all"`),
100-
all types used as constructor/message arguments and return types must define a mapping
101-
to an equivalent Solidity type ([more details here][sol-type-mapping]).
102-
103-
[ink-spec-selector]: https://use.ink/basics/selectors/
104-
[scale-codec]: https://docs.rs/parity-scale-codec/latest/parity_scale_codec
105-
[sol-abi]: https://docs.soliditylang.org/en/latest/abi-spec.html
106-
[sol-abi-selector]: https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector
107-
[sol-abi-codec]: https://docs.soliditylang.org/en/latest/abi-spec.html#formal-specification-of-the-encoding
108-
[sol-type-mapping]: ../background/solidity-metamask-compat.md#rustink-to-solidity-abi-type-mapping
109-
11028
### `keep_attr: String`
11129

11230
Tells the ink! code generator which attributes should be passed to call builders.

‎versioned_sidebars/version-v6-sidebars.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,16 @@
2727
"basics/upgradeability",
2828
"basics/env-functions",
2929
"basics/environment",
30+
{
31+
"type": "category",
32+
"label": "ABI",
33+
"items": [
34+
"basics/abi/overview",
35+
"basics/abi/ink",
36+
"basics/abi/solidity",
37+
"basics/abi/all"
38+
]
39+
},
3040
{
3141
"type": "category",
3242
"label": "Metadata",

0 commit comments

Comments
 (0)