Skip to content

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

Description

@sphamjoli

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.

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Tetiary Prioritytype: featureFeature request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions