search

aragon / radspec

🤘 Radspec is a safe interpreter for Ethereum's NatSpec
MIT License
141 stars 36 forks source link

Add requirements radspec #33

Closed fubuloubu closed 4 years ago

fubuloubu commented 6 years ago

We have a suggestion for adding requirements at the file level or contract level to aid in understanding what the contract(s) are supposed to do, as well as another suggestion for a comment on implementation notes that link back to those requirements. You can read more about this here: https://guidelines.secureth.org/development/traceability

If this were formalized in radspec, it could aid analysis of traceability of requirements from the spec level to implementation for an auditor to use in a review.

sohkai commented 6 years ago

Nice, SecureEth is shaping up quite nicely!

One thing I'm not sure about this is if it needs to be parsed by radpsec—radspec is meant to make it easier for UIs to render descriptive descriptions for users to understand.

The traceability spec (so far) seems to be in the other direction: for developers / auditors to help understand, develop, and test their code. It seems like maybe a different tool would be better for that (especially for generating dot graphs / dependency graphs from those requirements)?

fubuloubu commented 6 years ago

I was thinking about this yesterday, Natspec/Radspec have problems in that they don't allow for easy internationalization of these descriptions, at least not without some significant transformation using enums instead of text so a lookup can be done to a UI message.

What it does do is create better interactions for front end developers to create logs of what's occurring without having to modify or inject anything into the smart contract code. I think their primary use case is actually meant for developers and auditors, and those parties would really like to see requirement dependency graphs too. This might be two separate tools as you mentioned, but only because traceability and document review are two separate activities typically.

sohkai commented 6 years ago

We've been thinking about providing some sort of interface for internationalization in radspec, but haven't put a lot resources towards this yet.

What it does do is create better interactions for front end developers to create logs of what's occurring without having to modify or inject anything into the smart contract code.

I think this is a pretty great use case, and one that we haven't explored too much on our side.

To me, the most difficult part about natspec/radspec is that their strings are fairly constrained and difficult for an frontend to construct well-structured prose with. I wouldn't say this limits their use to be primarily towards developers or auditors though.

sohkai commented 4 years ago

Closing; the discussed scope does not currently fall within radspec's. We can evaluate in the future how to make it more generic.