Skip to content

feat: ARC56 field descriptions#666

Open
iglosiggio wants to merge 2 commits intomainfrom
arc56-field-descriptions
Open

feat: ARC56 field descriptions#666
iglosiggio wants to merge 2 commits intomainfrom
arc56-field-descriptions

Conversation

@iglosiggio
Copy link
Copy Markdown
Member

@iglosiggio iglosiggio commented Mar 5, 2026

This PR modifies the structure of both struct PyTypes and struct WTypes so their fields can carry documentation.

When a structured value is emitted we properly plumb these field docs up to their proper place in the ARC56 spec.

The AWST tests had their JSONs regenerated by parsing and re-serializing them thanks to a custom adapter made by @daniel-makerx modified a bit by me (because we changed the format in the meantime).

@engineering-ci
Copy link
Copy Markdown

engineering-ci bot commented Mar 5, 2026

⚠️ No changelog fragment detected

@engineering-ci
Copy link
Copy Markdown

engineering-ci bot commented Mar 5, 2026

Checking stubs for changes and corresponding version bump in origin/arc56-field-descriptions

Last puyapy release: v5.7.1
This branch stubs version: 3.5.0
Last released stubs version: 3.4.0
Main stubs version: 3.5.0

💡 Stub version change: 3.4.0 -> 3.5.0
✅ Stub files unchanged
✅ Stub check passed!

@engineering-ci
Copy link
Copy Markdown

engineering-ci bot commented Mar 5, 2026

Name Status O0 bytes O1 bytes O2 bytes O0 ops O1 ops O2 ops

@engineering-ci
Copy link
Copy Markdown

engineering-ci bot commented Mar 5, 2026

Coverage

Tests Skipped Failures Errors Time
1493 3 💤 0 ❌ 0 🔥 13m 50s ⏱️

Comment on lines +336 to +343
@typing.final
@attrs.frozen(kw_only=True)
class WTypeField:
name: str = attrs.field()
type: WType = attrs.field()
docs: str | None = attrs.field(default=None, eq=False)


Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will have to regenerate the bindings on the puya-ts side. Is there anything else to regenerate?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

test_ts_code_gen.py should update tests\output\nodes.ts.txt which can then be used in puya-ts

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually that only updates nodes, WTypes change fairly infrequently so at the moment I think we just update those manually in puya-ts

@iglosiggio iglosiggio force-pushed the arc56-field-descriptions branch from c75a826 to f51aaa3 Compare March 6, 2026 18:13
@iglosiggio iglosiggio changed the title WIP: ARC56 field descriptions feat: ARC56 field descriptions Mar 6, 2026
@iglosiggio iglosiggio marked this pull request as ready for review March 6, 2026 18:21
@daniel-makerx
Copy link
Copy Markdown
Contributor

daniel-makerx commented Mar 9, 2026

Broadly looks good, I would update test_cases/arc_56 to include documentation for some of the event fields so we can see the effect of this change. Nevermind, I see there is an example change!

@iglosiggio iglosiggio force-pushed the arc56-field-descriptions branch 2 times, most recently from 3c1dfb3 to 318cebe Compare March 11, 2026 19:04
@iglosiggio iglosiggio force-pushed the arc56-field-descriptions branch from 318cebe to dfe9a14 Compare March 11, 2026 19:09
if repeated_field_names:
raise CodeError(
"invalid ARC-4 Struct declaration,"
f"the following fields are not unique: {', '.join(repeated_field_names)}"
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So because this is using a set, if there was a test for this error, the output would not be stable (side note: should there be a test?).

location=self.source_location,
)

field_names = set()
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Counter is a subclass of dict so will be stable

Suggested change
field_names = set()
field_counts = Counter(field.name for field in value)
repeated_field_names = [
field_name for field_name, count in field_counts.items() if count > 1
]

Will also need from collections import Counter

Copy link
Copy Markdown
Contributor

@daniel-makerx daniel-makerx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Once those comments are resolved this looks good to go!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants