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
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 Rootcannot deploy a
LabelStoreunderpallet-revive");pallet_resources::UsernameReservationDuration,BaseLabel::is_valid_person,MinUsernameLength;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-personlabel rule (letters only)" rather than
BaseLabel::is_valid_person; "a Root origin" rather than "asubstrate Root origin".
Files with runtime-coupled NatSpec (the
contracts/external/revive/interface is a genuine bindingto 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.solAcceptance criteria
pallet,revive, orsubstratereference remains in the NatSpec of the listed files.pallet_resources::…,BaseLabel::…,MinUsernameLength) orchain name ("People Chain") remains in their NatSpec.
forge buildpasses.