Skip to content

Commit ec8d86b

Browse files
committed
Add #[abi_name(name = "foo") attribute to rename ABI items.
Add `#[abi_name(name = "foo")` attribute to rename enum and struct ABI items. Here is example of how it can be used: ```sway contract; struct MyStruct {} enum MyEnum { A: () } abi MyAbi { fn my_struct() -> MyStruct; fn my_enum() -> MyEnum; } impl MyAbi for Contract { fn my_struct() -> MyStruct { MyStruct{} } fn my_enum() -> MyEnum { MyEnum::A } } ``` Closes #5955.
1 parent 804d6df commit ec8d86b

File tree

39 files changed

+903
-295
lines changed

39 files changed

+903
-295
lines changed

docs/book/src/reference/attributes.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Attributes are a form of metadata that can additionally instruct Sway compiler o
44

55
Below is the list of attributes supported by the Sway compiler, ordered alphabetically:
66

7+
- [ABI Name](#abi-name)
78
- [Allow](#allow)
89
- [Cfg](#cfg)
910
- [Deprecated](#deprecated)
@@ -15,6 +16,62 @@ Below is the list of attributes supported by the Sway compiler, ordered alphabet
1516
- [Storage](#payable)
1617
- [Test](#test)
1718

19+
## ABI Name
20+
21+
The `#[abi_name]` attribute allows to specify the ABI name for an item.
22+
This means that when a contract ABI JSON file is generated, the name that is output is the one specified
23+
by the attribute. This can be useful to allow renaming items, while allowing for keeping backwards
24+
compatibility at the contract ABI level.
25+
26+
> **Note**: At the moment, only enum and struct types support the attribute.
27+
28+
In the example that follows, we originally had a `MyStruct` and `MyEnum` types, which we renamed in Sway:
29+
30+
```sway
31+
contract;
32+
33+
#[abi_name(name = "MyStruct")]
34+
struct RenamedMyStruct {}
35+
36+
#[abi_name(name = "MyEnum")]
37+
enum RenamedMyEnum {
38+
A: ()
39+
}
40+
41+
abi MyAbi {
42+
fn my_struct() -> RenamedMyStruct;
43+
fn my_enum() -> RenamedMyEnum;
44+
}
45+
46+
impl MyAbi for Contract {
47+
fn my_struct() -> RenamedMyStruct { RenamedMyStruct{} }
48+
fn my_enum() -> RenamedMyEnum { RenamedMyEnum::A }
49+
}
50+
```
51+
52+
This generates the following JSON ABI:
53+
54+
```json
55+
{
56+
"concreteTypes": [
57+
{
58+
"concreteTypeId": "215af2bca9e1aa8fec647dab22a0cd36c63ce5ed051a132d51323807e28c0d67",
59+
"metadataTypeId": 1,
60+
"type": "enum MyEnum"
61+
},
62+
{
63+
"concreteTypeId": "d31db280ac133d726851d8003bd2f06ec2d3fc76a46f1007d13914088fbd0791",
64+
"type": "struct MyStruct"
65+
}
66+
],
67+
...
68+
}
69+
```
70+
71+
We get the same JSON ABI output both before and after renaming the types, due to attributing them with
72+
`#[abi_name(name = ...)]`, which forces them to be generated with the previous Sway name.
73+
This means consumers of this contract will still get the original names, keeping compatibility at the ABI level.
74+
1875
## Allow
1976

2077
The `#[allow(...)]` attribute disables compiler checks so that certain warnings will go unreported. The following warnings can be disabled:

forc-pkg/src/pkg.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1784,6 +1784,7 @@ pub fn compile(
17841784
program: typed_program,
17851785
abi_with_callpaths: true,
17861786
type_ids_to_full_type_str: HashMap::<String, String>::new(),
1787+
unique_names: HashSet::<String>::new(),
17871788
},
17881789
engines,
17891790
if experimental.new_encoding {

sway-ast/src/attribute.rs

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ pub const ERROR_TYPE_ATTRIBUTE_NAME: &str = "error_type";
5252
pub const ERROR_ATTRIBUTE_NAME: &str = "error";
5353
pub const ERROR_M_ARG_NAME: &str = "m";
5454

55+
// Abi names.
56+
pub const ABI_NAME_ATTRIBUTE_NAME: &str = "abi_name";
57+
pub const ABI_NAME_NAME_ARG_NAME: &str = "name";
58+
5559
pub const KNOWN_ATTRIBUTE_NAMES: &[&str] = &[
5660
STORAGE_ATTRIBUTE_NAME,
5761
DOC_COMMENT_ATTRIBUTE_NAME,
@@ -62,6 +66,7 @@ pub const KNOWN_ATTRIBUTE_NAMES: &[&str] = &[
6266
CFG_ATTRIBUTE_NAME,
6367
DEPRECATED_ATTRIBUTE_NAME,
6468
FALLBACK_ATTRIBUTE_NAME,
69+
ABI_NAME_ATTRIBUTE_NAME,
6570
];
6671

6772
/// An attribute declaration. Attribute declaration

0 commit comments

Comments
 (0)