Natspec->Radspec


#1

Moving this discussion from twitter to the magicians so we are not limited in character count:

My current questions:

  • Are the radspec keywords documented somewhere? when googling for “@tokenAmount” or “@formatPct” I only find usages but no documentation. Would especially be interested in a list of possible keywords.
  • who can publish to the registry - in natspec it was part of the solidity compilation - not yet sure how this would work for radspec
  • as @pedrouid correctly mentioned - while attacking this problem we could also think about localisation

#2
  • Are the radspec keywords documented somewhere? when googling for “@tokenAmount” or “@formatPct” I only find usages but no documentation. Would especially be interested in a list of possible keywords.
  • who can publish to the registry - in natspec it was part of the solidity compilation - not yet sure how this would work for radspec

The registry needs to be designed and we can get as crazy as our imagination takes us. I think to get started something fairly centralized is fine, you just need a way to prevent spam and encourage submissions for the most used smart contracts. I was thinking a model where you have bonded curators/maintainers that ‘merge’ contributions that get rewarded. Changing an existing description should be way harder than adding a new one.

Radspec strings for new contracts can be extracted from solidity files in the same way as Natspec strings do, so they are also part of the Solidity source code hash swarm link at the end of the bytecode.

  • as @pedrouid correctly mentioned - while attacking this problem we could also think about localisation

Absolutely. This is the format I thought of when adding meta-radspec string support and hardcoding some strings in the package. It would be trivial to convert it into an object in which lang identifiers are the keys and the localized strings are the value:


#3

If we keep radspec operations basic enough we might not need it to be done on client-side

@tokenAmount(self, $3) could be replaced by div($3, pow(10, self.decimals))


#4

I totally get your point, but if you look at the actual implementation of the helper you will be surprised at how non-trivial it is to properly format token amounts :sweat_smile:


#5

Yeah, because I didn’t include the symbol and precision. Honestly I don’t mind so much about the off-chain computation of the metadata. Currently it’s much worse so this definitely is a significant improvement. No need to be purist now as we should move this to be adopted as soon as possible


#6

Was just talking to chriseth about this and we think creating a registry is not really needed. We can just fix natspec (remove the dependency to/usage of JS - seems(*1) to be not really used anyway) - solidity is not actually doing something with the JS expressions - just piping them through.
So the JS stuff could just be removed from natspec and we should be done.
That said: it would not really solve the localisation problem.

(*1) - we should gather some data on this


#7

If you remove JS, you need to add a way to perform basic data transformations so the descriptions can be useful UI. This is why we built radspec.


#8

Sure - but this can be added to NatSpec. Having NatSpec and RadSpec at the same time makes things quite ugly. No real reason to fork here - just improve/fix whats there already.


#9

Radspec is just Natspec but it uses its own DSL rather than JS’ evals for executing code. Radspec strings are placed in Solidity code in the same place that Natspec strings are, so all the Natspec extractors (solc included) work with Radspec out of the box.


#10

But why would you need the registry then?