Add documentation for implementing EnumerableSet #786

Peponks9 · 2025-08-11T18:49:28Z

Description

This PR addresses issue #761 by adding the documentation for implementing EnumerableSet with user-defined storage types in Stylus.

Changes Made

Added Examples to Existing EnumerableSet Documentation

Added concise usage example with EnumerableSet<Address> in contracts/src/utils/structs/enumerable_set/mod.rs
Included brief guidance on implementing custom storage types via Element and Accessor traits

Created Antora Documentation

Added new documentation file: docs/modules/ROOT/pages/enumerable-set-custom.adoc
Provided step-by-step implementation guide for custom storage types
Included examples with custom User struct

Updated Navigation and References

Added new documentation to docs/modules/ROOT/nav.adoc
Updated docs/modules/ROOT/pages/utilities.adoc with cross-reference

Addressed Limitations

Clearly documented that StorageBytes and StorageString cannot currently be implemented due to Stylus SDK limitations

Testing

Documentation builds successfully with npm run docs
Cargo test successfully run

Related Issue

Closes #761

@0xNeshi

…ustom storage types - Enhanced existing EnumerableSet docs with usage examples - Created comprehensive Antora documentation for custom storage types - Added note about StorageBytes/StorageString limitations - Updated navigation and cross-references Closes OpenZeppelin#761

netlify · 2025-08-11T18:49:34Z

✅ Deploy Preview for contracts-stylus ready!

Name	Link
🔨 Latest commit	`581d9ed`
🔍 Latest deploy log	https://app.netlify.com/projects/contracts-stylus/deploys/68a593c536f26d000846b87f
😎 Deploy Preview	https://deploy-preview-786--contracts-stylus.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

0xNeshi

Very good work 🚀

Let's polish it a bit and we can merge

contracts/src/utils/structs/enumerable_set/mod.rs

docs/modules/ROOT/nav.adoc

contracts/src/utils/structs/enumerable_set/mod.rs

0xNeshi · 2025-08-15T06:07:47Z

contracts/src/utils/structs/enumerable_set/mod.rs

+//! ```
+//! extern crate alloc;
+//!
+//! use alloy_primitives::{Address, U256};
+//! use stylus_sdk::prelude::*;
+//! use openzeppelin_stylus::utils::structs::enumerable_set::EnumerableSet;
+//!
+//! #[storage]
+//! struct MyContract {
+//!     whitelist: EnumerableSet<Address>,
+//! }


Suggested change

//! ```

//! extern crate alloc;

//!

//! use alloy_primitives::{Address, U256};

//! use stylus_sdk::prelude::*;

//! use openzeppelin_stylus::utils::structs::enumerable_set::EnumerableSet;

//!

//! #[storage]

//! struct MyContract {

//! whitelist: EnumerableSet<Address>,

//! }

//! ```rust

//! extern crate alloc;

//!

//! use alloy_primitives::{Address, U256};

//! use stylus_sdk::prelude::*;

//! use openzeppelin_stylus::utils::structs::enumerable_set::EnumerableSet;

//!

//! #[storage]

//! #[entrypoint]

//! struct MyContract {

//! whitelist: EnumerableSet<Address>,

//! }

Unresolving, still missing #[entrypoint].

Unresolving, still missing #[entrypoint].

@Peponks9 I need to remind you to please not resolve change requests which have not been addressed. This is very important, as it makes for better clarity during code reviews. Only resolve change requests once:

The change request is addressed (implemented).

Your local changes are pushed to remote and PR is updated.

contracts/src/utils/structs/enumerable_set/mod.rs

0xNeshi · 2025-08-15T06:43:47Z

docs/modules/ROOT/pages/enumerable-set-custom.adoc

+[[limitations]]
+== Current Limitations
+
+**Note:** `StorageBytes` and `StorageString` cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. This limitations may change in future versions of the Stylus SDK.


Update the sentence to state that Bytes and String cannot currently be implemented due to SDK limitation. Link to the actual types.

Made the changes but didn't find a link for String, just Bytes.

https://doc.rust-lang.org/stable/alloc/string/struct.String.html

Both links added

The changes haven't been made or haven't been pushed, you can resolve this conversation together with https://github.com/OpenZeppelin/rust-contracts-stylus/pull/786/files#r2281442336

docs/modules/ROOT/pages/enumerable-set-custom.adoc

0xNeshi · 2025-08-15T06:46:13Z

docs/modules/ROOT/pages/enumerable-set-custom.adoc

+[[testing]]
+== Testing Your Implementation


Remove this section, devs can't run OZ tests from within their projects

Unresolving, the cargo test script is still present

@Peponks9 another reminder not to resolve conversations that haven't been fully addressed and the changes pushed.

docs/modules/ROOT/pages/enumerable-set-custom.adoc

docs/modules/ROOT/pages/utilities.adoc

Add `rust` Co-authored-by: Nenad <[email protected]>

- Add comprehensive primitive type list with rustdoc links - Move detailed docs from module level to struct level - Update custom implementation guide with step-by-step breakdown - Fix documentation structure and formatting issues - Update limitations section with proper type links

Peponks9 · 2025-08-16T01:50:11Z

Hey @0xNeshi, changes made :)

0xNeshi · 2025-08-18T06:13:46Z

contracts/src/utils/structs/enumerable_set/mod.rs

+/// Sets have the following properties:
+///
+/// * Elements are added, removed, and checked for existence in constant time
+///   (O(1)).
+/// * Elements are enumerated in O(n). No guarantees are made on the ordering.
+/// * Set can be cleared (all elements removed) in O(n).
+///
+/// ## Usage


Suggested change

/// Sets have the following properties:

///

/// * Elements are added, removed, and checked for existence in constant time

/// (O(1)).

/// * Elements are enumerated in O(n). No guarantees are made on the ordering.

/// * Set can be cleared (all elements removed) in O(n).

///

/// ## Usage

/// Storage type for managing [sets] of primitive types.

///

/// Sets have the following properties:

///

/// * Elements are added, removed, and checked for existence in constant time

/// (O(1)).

/// * Elements are enumerated in O(n). No guarantees are made on the ordering.

/// * Set can be cleared (all elements removed) in O(n).

///

/// [sets]: https://en.wikipedia.org/wiki/Set_(abstract_data_type)

///

/// ## Usage

0xNeshi · 2025-08-18T06:18:02Z

contracts/src/utils/structs/enumerable_set/mod.rs

@@ -188,6 +237,7 @@ mod tests {
                        use stylus_sdk::prelude::TopLevelStorage;
                        use alloy_primitives::private::proptest::{prop_assert, prop_assert_eq, proptest};

+


Suggested change

I don't seem to find this one, on lines provided it is not after use alloy_primitives::private::proptest::{prop_assert, prop_assert_eq, proptest}; anymore.

Maybe you didn't push local changes?

0xNeshi · 2025-08-18T06:19:35Z

contracts/src/utils/structs/enumerable_set/mod.rs

@@ -2,13 +2,6 @@



Change the mod-level doc to:

//! Storage type for managing [sets] of primitive types. //! //! [sets]: https://en.wikipedia.org/wiki/Set_(abstract_data_type)

0xNeshi · 2025-08-18T06:20:42Z

contracts/src/utils/structs/enumerable_set/mod.rs

+//! ```
+//! extern crate alloc;
+//!
+//! use alloy_primitives::{Address, U256};
+//! use stylus_sdk::prelude::*;
+//! use openzeppelin_stylus::utils::structs::enumerable_set::EnumerableSet;
+//!
+//! #[storage]
+//! struct MyContract {
+//!     whitelist: EnumerableSet<Address>,
+//! }


Unresolving, still missing #[entrypoint].

0xNeshi · 2025-08-18T06:22:48Z

contracts/src/utils/structs/enumerable_set/mod.rs

+//! You can implement `EnumerableSet` for your own storage types by implementing
+//! the `Element` and `Accessor` traits. See `element.rs` for trait definitions
+//! and the documentation for comprehensive examples.


Unresolving, as types for not converted into links.

0xNeshi · 2025-08-18T06:45:42Z

docs/modules/ROOT/pages/enumerable-set-custom.adoc

+[[limitations]]
+== Current Limitations
+
+**Note:** https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html[`Bytes`] and `String` cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. These limitations may change in future versions of the Stylus SDK.


Suggested change

**Note:** https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html[`Bytes`] and `String` cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. These limitations may change in future versions of the Stylus SDK.

https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html[`Bytes`] and `String` cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. These limitations may change in future versions of the Stylus SDK.

nit: redundant, already in a separate section.

0xNeshi · 2025-08-18T06:45:56Z

docs/modules/ROOT/pages/enumerable-set-custom.adoc

+[[limitations]]
+== Current Limitations
+
+**Note:** https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html[`Bytes`] and `String` cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. These limitations may change in future versions of the Stylus SDK.


Suggested change

**Note:** https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html[`Bytes`] and `String` cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. These limitations may change in future versions of the Stylus SDK.

**Note:** https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html[`Bytes`] and https://doc.rust-lang.org/stable/alloc/string/struct.String.html[`String`] cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. These limitations may change in future versions of the Stylus SDK.

0xNeshi · 2025-08-18T06:49:30Z

docs/modules/ROOT/pages/enumerable-set-custom.adoc

+[[testing]]
+== Testing Your Implementation


Unresolving, the cargo test script is still present

0xNeshi · 2025-08-18T06:51:53Z

docs/modules/ROOT/pages/enumerable-set-custom.adoc

+#[storage]
+struct AccessControl {
+    role_members: StorageMap<B256, EnumerableSet<Address>>,
+}
+
+impl AccessControl {
+    fn grant_role(&mut self, role: B256, account: Address) {
+        self.role_members.get(role).add(account);
+    }
+
+    fn revoke_role(&mut self, role: B256, account: Address) {
+        self.role_members.get(role).remove(account);
+    }
+
+    fn get_role_members(&self, role: B256) -> Vec<Address> {
+        self.role_members.get(role).values()
+    }
+}


Provide a full working contract example, including imports. Devs should be able to copy/paste this example and have it deployable out of the box.

0xNeshi · 2025-08-18T06:52:27Z

docs/modules/ROOT/pages/enumerable-set-custom.adoc

+[source,rust]
+----
+#[storage]
+struct Whitelist {


Same for this, make it fully working example

0xNeshi · 2025-08-18T07:01:29Z

Also, fix the failing doc CI.

The other CI jobs seem to be failing due to some issue with cargo-stylus, we'll take a look into that.

Peponks9 · 2025-08-19T04:59:50Z

@0xNeshi yes, still haven’t pushed changes and some errors still to be addressed. But didn’t some progress today ñ.

0xNeshi

All the active conversations need to be addressed. For future reference, feel free to just make the necessary change requests or discuss them in the conversation threads, but leave it to the maintainers to actually resolve the conversations.

0xNeshi · 2025-08-25T07:36:47Z

Hey @Peponks9 , just checking in to see if you need any help addressing the issues

Peponks9 mentioned this pull request Aug 14, 2025

[Docs]: Add Clear Examples and Docs for How to Implement Custom EnumerableSet #761

Open

1 task

0xNeshi reviewed Aug 15, 2025

View reviewed changes

0xNeshi mentioned this pull request Aug 15, 2025

docs: Add comprehensive documentation for custom EnumerableSet #797

Closed

Peponks9 and others added 6 commits August 15, 2025 18:19

Update contracts/src/utils/structs/enumerable_set/mod.rs

80719cf

Add `rust` Co-authored-by: Nenad <[email protected]>

Merge branch 'OpenZeppelin:main' into main

b360335

Correct mod.rs file

7fe7c36

Merge branch 'main' of github.com:Peponks9/rust-contracts-stylus

0d14b15

0xNeshi reviewed Aug 18, 2025

View reviewed changes

0xNeshi marked this pull request as ready for review August 19, 2025 04:45

0xNeshi requested review from bidzyyys and qalisander as code owners August 19, 2025 04:45

0xNeshi reviewed Aug 19, 2025

View reviewed changes

Merge branch 'main' into main

581d9ed

		@@ -188,6 +237,7 @@ mod tests {
		use stylus_sdk::prelude::TopLevelStorage;
		use alloy_primitives::private::proptest::{prop_assert, prop_assert_eq, proptest};

	Note: https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html[`Bytes`] and `String` cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. These limitations may change in future versions of the Stylus SDK.
	https://docs.rs/alloy-primitives/latest/alloy_primitives/struct.Bytes.html[`Bytes`] and `String` cannot currently be implemented for `EnumerableSet` due to limitations in the Stylus SDK. These limitations may change in future versions of the Stylus SDK.

Add documentation for implementing EnumerableSet #786

Are you sure you want to change the base?

Add documentation for implementing EnumerableSet #786

Uh oh!

Conversation

Peponks9 commented Aug 11, 2025

Description

Changes Made

Added Examples to Existing EnumerableSet Documentation

Created Antora Documentation

Updated Navigation and References

Addressed Limitations

Testing

Related Issue

Uh oh!

netlify bot commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for contracts-stylus ready!

Uh oh!

0xNeshi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xNeshi Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

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!

Uh oh!

Uh oh!

Peponks9 commented Aug 16, 2025

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!

0xNeshi commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

netlify bot commented Aug 11, 2025 •

edited

Loading

0xNeshi Aug 19, 2025 •

edited

Loading

0xNeshi commented Aug 18, 2025 •

edited

Loading

0xNeshi left a comment •

edited

Loading