paritytech / paritytech/dotns

[Feat]: Make contract NatSpec platform-agnostic (remove runtime-specific references)

Open
#284 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

P2 type: feature
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-revive and its store-deposit/contract-creation behaviour (for example "substrate Root
    cannot deploy a LabelStore under pallet-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.sol
  • contracts/registrars/DotnsRegistrarController.sol
  • contracts/registrars/IDotnsRegistrarController.sol
  • contracts/pop/PopRules.sol
  • contracts/pop/IPopRules.sol
  • contracts/whitelist/DotnsNameWhitelist.sol
  • contracts/whitelist/IDotnsNameWhitelist.sol
  • contracts/utils/SystemUtils.sol
  • contracts/utils/DotnsConstants.sol
Acceptance criteria
  • No pallet, revive, or substrate reference 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 build passes.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.