[Feat]: Make contract NatSpec platform-agnostic (remove runtime-specific references)
Nobody has claimed this yet.
- Dominant language
- Solidity
- Stars
- 4
- Forks
- 2
- Avg merge
- 1d 18h
- Merged PRs (30d)
- 24
Description
Component
Other
Priority
P2
Summary
Several contracts describe their behaviour in NatSpec using terms specific to one runtime, so the
documentation is inaccurate wherever the contracts are deployed on a different EVM platform. The
contracts themselves are platform-agnostic; the NatSpec should be too.
Runtime-coupled wording currently in the NatSpec includes:
pallet-reviveand its store-deposit/contract-creation behaviour (for example "substrate Root
cannot deploy aLabelStoreunderpallet-revive");- "substrate Root" as the origin name, where "Root origin" alone is sufficient;
- foreign source symbols named directly:
pallet_resources::UsernameReservationDuration,
BaseLabel::is_valid_person,MinUsernameLength; - "People Chain" as the source of a naming constraint;
- the upstream source path
substrate/frame/revive/uapi/sol/ISystem.sol.
Desired outcome: NatSpec states the contract behaviour and constraints in direct, platform-agnostic
English, so a reader on any deployment target reads an accurate description.
Proposal
Rewrite the runtime-coupled NatSpec in the files below to describe the same behaviour without naming
a runtime, a foreign source symbol, or a specific chain. For example: "the mint origin cannot deploy
a LabelStore, so the label write is deferred" rather than naming the runtime; "the full-person
label rule (letters only)" rather than BaseLabel::is_valid_person; "a Root origin" rather than "a
substrate Root origin".
Files with runtime-coupled NatSpec (the contracts/external/revive/ interface is a genuine binding
to the System precompile and is out of scope):
contracts/registrars/DotnsRegistrar.solcontracts/registrars/DotnsRegistrarController.solcontracts/registrars/IDotnsRegistrarController.solcontracts/pop/PopRules.solcontracts/pop/IPopRules.solcontracts/whitelist/DotnsNameWhitelist.solcontracts/whitelist/IDotnsNameWhitelist.solcontracts/utils/SystemUtils.solcontracts/utils/DotnsConstants.sol
Acceptance criteria
- No
pallet,revive, orsubstratereference remains in the NatSpec of the listed files. - No foreign source symbol (
pallet_resources::…,BaseLabel::…,MinUsernameLength) or
chain name ("People Chain") remains in their NatSpec. - The described behaviour is unchanged; only the wording is agnostic and direct.
-
forge buildpasses.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the listed NatSpec in contracts/registrars/, contracts/pop/, contracts/whitelist/, and contracts/utils/, excluding contracts/external/revive/. Replace runtime, foreign-symbol, and chain-specific wording while preserving the documented behavior, then verify that no listed references remain and run forge build.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- solidity
- Domain
- blockchain, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100