Add `#[abi_name(name = "foo")]` attribute to rename ABI items. #7057

tritao · 2025-04-02T19:07:41Z

Description

Add #[abi_name(name = "foo")] attribute to rename enum and struct ABI items.

Here is example of how it can be used:

contract;

#[abi_name(name = "RenamedMyStruct")]
struct MyStruct {}

#[abi_name(name = "RenamedMyEnum")]
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.

Remarks

The checking for ABI names is being done in the ABI generation phase, which made it a requirement to change the interface of ABI checking to return Results everywhere and passing Handler all the way down, so emitted errors can be passed down to the driver for reporting.

Checklist

I have linked to any relevant issues.
I have commented my code, particularly in hard-to-understand areas.
I have updated the documentation where relevant (API docs, the reference, and the Sway book).
- If my change requires substantial documentation changes, I have requested support from the DevRel team
I have added tests that prove my fix is effective or that my feature works.
I have added (or requested a maintainer to add) the necessary Breaking* or New Feature labels where relevant.
I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
I have requested a review from the relevant team or maintainers.

codspeed-hq · 2025-04-02T19:22:43Z

CodSpeed Performance Report

Merging #7057 will not alter performance

_{Comparing tritao:annotation-abi-name (952ebae) with master (5c22e33)}

Summary

✅ 24 untouched benchmarks

sway-core/src/transform/attribute.rs

test/src/e2e_vm_tests/test_programs/should_pass/language/abi_name_attribute/.gitignore

test/src/e2e_vm_tests/test_programs/should_pass/language/abi_name_attribute/src/lib.sw

sway-core/src/abi_generation/abi_str.rs

sway-types/src/span.rs

ironcev

The attribute should be added to the Attributes chapter in the documentation.

I've changed that documentation page fully in #7058 because it was seriously outdated. So, whoever gets the PR merged later will have some slight merge conflicts to solve on that page 😄

sway-core/src/abi_generation/abi_str.rs

docs/book/src/reference/attributes.md

sway-core/src/transform/attribute.rs

tritao · 2025-05-05T16:35:35Z

Rebased, feedback address, ready for re-review.

ironcev

The changes added since the previous review are quite substantial so it will take some time to re-review fully 😄

Here some quick observations and suggestions.

And one general question. I assume the checking was moved to the ABI generation phase, which results in returning Results everywhere and passing Handler all the way down, because there is no option to detect at the type checking phase which types will actually end up in the ABI?

If so, maybe this assumption can be added to the issue description and shortly elaborated, it will help in understanding the reason for the widespread change.

docs/book/src/reference/attributes.md

sway-core/src/abi_generation/fuel_abi.rs

test/src/e2e_vm_tests/test_programs/should_pass/language/attributes_abi_name/Forc.toml

test/src/e2e_vm_tests/test_programs/should_fail/attributes_invalid_abi_names/stdout.snap

tritao · 2025-06-13T14:00:20Z

The PR has been updated with a significantly more robust approach for name checking, it now can find naming conflicts for more cases, namely existing types previously defined in the ABI interface surface, both in the main and imported modules. The diagnostics have also been improved, with support for expressive diagnostics and more detailed error messages.

Add `#[abi_name(name = "foo")]` attribute to rename enum and struct ABI items. Here is example of how it can be used: ``` 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 FuelLabs#5955.

ironcev

One small mistake in the docs definitely worth fixing, otherwise only nitpicks 😄

Regarding the comments about diagnostics guidelines, we should add those guidelines to the repo (currently they are only in the RFC) and polish existing diagnostics that violate them, but that's a low prio so far.

ironcev · 2025-06-30T11:40:53Z

docs/book/src/reference/attributes.md

+
+> **Note**: At the moment, only enum and struct types support the attribute.
+
+In the example that follows, we originally had `MyStruct` and `MyEnum` types, which we, later on, renamed to `MyStruct` and `MyEnum` in code. To keep the backward compatibility of the ABI, we annotate the types with the `#[abi_name]` attribute and give them the original names:


Suggested change

In the example that follows, we originally had `MyStruct` and `MyEnum` types, which we, later on, renamed to `MyStruct` and `MyEnum` in code. To keep the backward compatibility of the ABI, we annotate the types with the `#[abi_name]` attribute and give them the original names:

In the example that follows, we originally had `MyStruct` and `MyEnum` types, which we, later on, renamed to `RenamedMyStruct` and `RenamedMyEnum` in code. To keep the backward compatibility of the ABI, we annotate the types with the `#[abi_name]` attribute and give them the original names:

ironcev · 2025-06-30T11:49:00Z

sway-core/src/abi_generation/fuel_abi.rs

+impl AbiNameDiagnosticSpan {
+    pub fn span(self) -> Span {
+        match self {
+            Self::Attribute(span) => span,


Nitpick!

Suggested change

Self::Attribute(span) => span,

Self::Attribute(span) | Self::Type(span) => span,

ironcev · 2025-06-30T11:53:28Z

sway-core/src/abi_generation/fuel_abi.rs

@@ -34,7 +54,79 @@ impl AbiContext<'_> {
    }
 }

+pub fn extract_abi_name_inner(span: &Span) -> Option<Span> {
+    let text = &span.src().text;
+    let full_attr: &str = &text[span.start()..span.end()];


Aren't these two lines the same as span.as_str()?

Suggested change

let full_attr: &str = &text[span.start()..span.end()];

let full_attr: = span.as_str();

ironcev · 2025-06-30T12:08:10Z

sway-core/src/abi_generation/fuel_abi.rs

        );
+
+        if should_check_name {
+            let mut has_abi_name_attribute = false;


Nitpick. Having a mut boolean here feels a bit over-complicated. One trivial possibility is to "calculate" has_abi_name_attribute after the let (name, attribute_span) or assign it within that same let: let (has_abi_name, name, attr_span).

ironcev · 2025-06-30T12:09:10Z

sway-core/src/abi_generation/fuel_abi.rs

+                    }
+                    None => (String::new(), Span::dummy()),
+                };
+


E.g., here: let has_abi_name_attribute = !(name.is_empty() || attribute_span.is_dummy());

ironcev · 2025-06-30T12:18:54Z

sway-error/src/error.rs

@@ -3112,6 +3122,32 @@ impl ToDiagnostic for CompileError {
                    help
                },
            },
+            ABIDuplicateName { span, other_span: other, is_attribute } => Diagnostic {
+                reason: Some(Reason::new(code(1), "Duplicated name found for renamed ABI type.".into())),


According to the guidelines, Reasons shouldn't end up in punctuation (we have messages that violates that, I know...)

Suggested change

reason: Some(Reason::new(code(1), "Duplicated name found for renamed ABI type.".into())),

reason: Some(Reason::new(code(1), "Duplicated name found for renamed ABI type".into())),

ironcev · 2025-06-30T12:19:52Z

sway-error/src/error.rs

+                    Hint::help(
+                        source_engine,
+                        other.clone(),
+                        format!("This is the existing {} with conflicting name", if *is_attribute { "attribute" } else { "type" }),


According to the guidelines, hints shoul end up in punctuation (we have messages that violates that, I know...).

Suggested change

format!("This is the existing {} with conflicting name", if *is_attribute { "attribute" } else { "type" }),

format!("This is the existing {} with conflicting name.", if *is_attribute { "attribute" } else { "type" }),

ironcev · 2025-06-30T12:22:32Z

sway-error/src/error.rs

+                help: vec![],
+            },
+            ABIInvalidName { span, name } => Diagnostic {
+                reason: Some(Reason::new(code(1), "Invalid name found for renamed ABI type.".into())),


Suggested change

reason: Some(Reason::new(code(1), "Invalid name found for renamed ABI type.".into())),

reason: Some(Reason::new(code(1), "Invalid name found for renamed ABI type".into())),

ironcev · 2025-06-30T12:23:10Z

sway-error/src/error.rs

+                    String::new()
+                ),
+                hints: vec![],
+                help: vec![format!("The name must be a valid Sway identifier{}", if name.is_empty() { " and cannot be empty" } else { "" })],


Suggested change

help: vec![format!("The name must be a valid Sway identifier{}", if name.is_empty() { " and cannot be empty" } else { "" })],

help: vec![format!("The name must be a valid Sway identifier{}.", if name.is_empty() { " and cannot be empty" } else { "" })],

ironcev · 2025-06-30T12:45:02Z

sway-parse/src/token.rs

@@ -105,6 +105,29 @@ pub fn lex(
    lex_commented(handler, src, start, end, &source_id).map(|stream| stream.strip_comments())
 }

+pub fn is_valid_identifier_or_path(s: &str) -> bool {


If I interpret the last line of the implementation correctly, these strings will be consider valid:

_:

:::

a:b:c:::

a::1234::b

etc.

And these will not, because : is not a XID_Start, although a valid Sway import path can start with it:

::some_module::in_the_same::package

I assume such path, relative to the current package, cannot be used in the #[abi_name] attribute, but this is a general function in the token.rs so it should IMO accept all supported paths. Additional check can be done in the ABI name handling.

Proposal is to add Rust unit tests for this function.

One more remark here, it looks like the current implementation will also accept these as valid identifiers:

__ (two underscores)

__this_is_not_a_valid_identifier

In the regular, non compiler-generated, Sway, identifiers starting with two underscores are not allowed.

ironcev · 2025-06-30T12:47:48Z

test/src/e2e_vm_tests/test_programs/should_fail/attributes_invalid_abi_names/Forc.toml

+name = "attributes_invalid_abi_names"
+
+[dependencies]
+std = { path = "../../../../../../sway-lib-std" }


A reduced lib sway-lib-std-core can be used here.

ironcev · 2025-06-30T12:49:45Z

test/src/e2e_vm_tests/test_programs/should_fail/attributes_invalid_abi_names/src/lib.sw

@@ -0,0 +1,70 @@
+contract;


This is a contract, so it feels very strange that the entry point is not main.sw but lib.sw. Proposal is to rename this file to main.sw.

ironcev · 2025-06-30T12:51:00Z

test/src/e2e_vm_tests/test_programs/should_fail/attributes_invalid_abi_names/Forc.toml

@@ -0,0 +1,9 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "lib.sw"


Here as well.

Suggested change

entry = "lib.sw"

entry = "main.sw"

ironcev · 2025-06-30T12:58:49Z

...vm_tests/test_programs/should_fail/attributes_invalid_args_values_types/src/abi_name_attr.sw

+library;
+
+#[abi_name(name = true)]
+pub fn not_ok() {}


This must be either a struct or an enum, otherwise the test is not testing that the name argument value is of the wrong type, because the argument itself is misplaced.

Suggested change

pub fn not_ok() {}

pub struct NotOk {}

ironcev · 2025-06-30T13:00:06Z

.../src/e2e_vm_tests/test_programs/should_fail/attributes_invalid_args_values_types/stdout.snap

+ --> test/src/e2e_vm_tests/test_programs/should_fail/attributes_invalid_args_values_types/src/abi_name_attr.sw:3:3
+  |
+...
+3 | #[abi_name(name = true)]


As explained above, the test should show error that true is not a valid value, but it is showing that the function cannot be annotated with #[abi_name].

tritao added compiler General compiler. Should eventually become more specific as the issue is triaged compiler: frontend Everything to do with type checking, control flow analysis, and everything between parsing and IRgen labels Apr 2, 2025

tritao self-assigned this Apr 2, 2025

tritao temporarily deployed to fuel-sway-bot April 2, 2025 19:08 — with GitHub Actions Inactive

tritao changed the title ~~Add #[abi_name() attribute to rename ABI items.~~ Add #[abi_name(name = "foo") attribute to rename ABI items. Apr 2, 2025

tritao force-pushed the annotation-abi-name branch from 04f5114 to 0bddb9d Compare April 2, 2025 19:51

tritao added the enhancement New feature or request label Apr 2, 2025

tritao temporarily deployed to fuel-sway-bot April 2, 2025 19:52 — with GitHub Actions Inactive

tritao marked this pull request as ready for review April 3, 2025 00:05

tritao requested a review from a team as a code owner April 3, 2025 00:05

IGI-111 previously approved these changes Apr 3, 2025

View reviewed changes

tritao enabled auto-merge (squash) April 3, 2025 10:47

IGI-111 requested a review from a team April 3, 2025 11:26

ironcev changed the title ~~Add #[abi_name(name = "foo") attribute to rename ABI items.~~ Add #[abi_name(name = "foo")] attribute to rename ABI items. Apr 3, 2025

ironcev requested changes Apr 3, 2025

View reviewed changes

tritao marked this pull request as draft April 3, 2025 16:16

auto-merge was automatically disabled April 3, 2025 16:16
Pull request was converted to draft

ironcev reviewed Apr 3, 2025

View reviewed changes

sway-core/src/abi_generation/abi_str.rs Outdated Show resolved Hide resolved

tritao dismissed IGI-111’s stale review via e45048c April 4, 2025 18:06

tritao force-pushed the annotation-abi-name branch from 0bddb9d to e45048c Compare April 4, 2025 18:06

tritao temporarily deployed to fuel-sway-bot April 4, 2025 18:07 — with GitHub Actions Inactive

tritao force-pushed the annotation-abi-name branch from e45048c to e364c5c Compare April 7, 2025 11:32

tritao temporarily deployed to fuel-sway-bot April 7, 2025 11:32 — with GitHub Actions Inactive

tritao force-pushed the annotation-abi-name branch from e364c5c to b993940 Compare April 7, 2025 11:49

tritao temporarily deployed to fuel-sway-bot April 7, 2025 11:50 — with GitHub Actions Inactive

tritao force-pushed the annotation-abi-name branch from b993940 to a9d5c2a Compare April 15, 2025 22:15

tritao temporarily deployed to fuel-sway-bot April 15, 2025 22:16 — with GitHub Actions Inactive

tritao force-pushed the annotation-abi-name branch from a9d5c2a to 9046048 Compare April 15, 2025 22:26

IGI-111 reviewed Apr 29, 2025

View reviewed changes

docs/book/src/reference/attributes.md Outdated Show resolved Hide resolved

ironcev requested changes Apr 30, 2025

View reviewed changes

sway-core/src/transform/attribute.rs Outdated Show resolved Hide resolved

tritao dismissed xunilrj’s stale review via 6e51087 April 30, 2025 08:13

tritao requested a review from a team as a code owner April 30, 2025 08:13

tritao force-pushed the annotation-abi-name branch from 6e51087 to 295a938 Compare May 5, 2025 13:26

tritao temporarily deployed to fuel-sway-bot May 5, 2025 13:27 — with GitHub Actions Inactive

tritao force-pushed the annotation-abi-name branch from 295a938 to ec8d86b Compare May 5, 2025 14:17

tritao temporarily deployed to fuel-sway-bot May 5, 2025 14:18 — with GitHub Actions Inactive

ironcev requested changes May 7, 2025

View reviewed changes

tritao force-pushed the annotation-abi-name branch from ec8d86b to fbd45c2 Compare June 3, 2025 18:39

tritao force-pushed the annotation-abi-name branch from fbd45c2 to f4e44fb Compare June 11, 2025 15:34

tritao temporarily deployed to fuel-sway-bot June 11, 2025 15:34 — with GitHub Actions Inactive

tritao force-pushed the annotation-abi-name branch from f4e44fb to 6ee826b Compare June 13, 2025 12:02

tritao temporarily deployed to fuel-sway-bot June 13, 2025 12:02 — with GitHub Actions Inactive

tritao force-pushed the annotation-abi-name branch from 6ee826b to 7f06ed7 Compare June 13, 2025 12:26

tritao temporarily deployed to fuel-sway-bot June 13, 2025 12:26 — with GitHub Actions Inactive

tritao force-pushed the annotation-abi-name branch from 7f06ed7 to ec159db Compare June 13, 2025 13:40

tritao temporarily deployed to fuel-sway-bot June 13, 2025 13:40 — with GitHub Actions Inactive

tritao requested a review from ironcev June 13, 2025 14:00

tritao force-pushed the annotation-abi-name branch from ec159db to 34b3572 Compare June 24, 2025 15:58

tritao temporarily deployed to fuel-sway-bot June 24, 2025 15:58 — with GitHub Actions Inactive

Implement expressive diagnostics for ABI name attribute.

952ebae

tritao force-pushed the annotation-abi-name branch from 34b3572 to 952ebae Compare June 25, 2025 09:19

tritao temporarily deployed to fuel-sway-bot June 25, 2025 09:19 — with GitHub Actions Inactive

IGI-111 approved these changes Jun 27, 2025

View reviewed changes

ironcev requested changes Jun 30, 2025

View reviewed changes


		> Note: At the moment, only enum and struct types support the attribute.

		In the example that follows, we originally had `MyStruct` and `MyEnum` types, which we, later on, renamed to `MyStruct` and `MyEnum` in code. To keep the backward compatibility of the ABI, we annotate the types with the `#[abi_name]` attribute and give them the original names:

	Self::Attribute(span) => span,
	Self::Attribute(span) \| Self::Type(span) => span,

	let full_attr: &str = &text[span.start()..span.end()];
	let full_attr: = span.as_str();

	reason: Some(Reason::new(code(1), "Duplicated name found for renamed ABI type.".into())),
	reason: Some(Reason::new(code(1), "Duplicated name found for renamed ABI type".into())),

	format!("This is the existing {} with conflicting name", if *is_attribute { "attribute" } else { "type" }),
	format!("This is the existing {} with conflicting name.", if *is_attribute { "attribute" } else { "type" }),

	reason: Some(Reason::new(code(1), "Invalid name found for renamed ABI type.".into())),
	reason: Some(Reason::new(code(1), "Invalid name found for renamed ABI type".into())),

	help: vec![format!("The name must be a valid Sway identifier{}", if name.is_empty() { " and cannot be empty" } else { "" })],
	help: vec![format!("The name must be a valid Sway identifier{}.", if name.is_empty() { " and cannot be empty" } else { "" })],

Add #[abi_name(name = "foo")] attribute to rename ABI items. #7057

Are you sure you want to change the base?

Add #[abi_name(name = "foo")] attribute to rename ABI items. #7057

Uh oh!

Conversation

tritao commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Remarks

Checklist

Uh oh!

codspeed-hq bot commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging #7057 will not alter performance

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ironcev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tritao commented May 5, 2025

Uh oh!

ironcev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tritao commented Jun 13, 2025

Uh oh!

ironcev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Add `#[abi_name(name = "foo")]` attribute to rename ABI items. #7057

Add `#[abi_name(name = "foo")]` attribute to rename ABI items. #7057

tritao commented Apr 2, 2025 •

edited

Loading

codspeed-hq bot commented Apr 2, 2025 •

edited

Loading