radspec 🤘

Radspec is a safe interpreter for dynamic expressions in Ethereum's NatSpec.

This allows smart contact developers to show improved function documentation to end users, without the security pitfalls of natspec.js. Radspec defines its own syntax structure and parses its own AST rather than directly evaluating untrusted JavaScript.

Features

Expressive: Show relevant details to smart contract end-users at the time they make transactions.
External calls: Radspec can query other contracts.
Safe: Radspec requires no DOM access or untrusted JavaScript evaluation.
Compatible: Most existing NatSpec dynamic expressions are compatible with Radspec.

Introduction & quick start

Radspec supports any contract programming language, such as Solidity or Vyper because radspec works on the compiled JSON ABI. Here is an example using Solidity.

pragma solidity ^0.5.0;

contract Tree {
    /// @notice Set the tree age to `numYears` years
    function setAge(uint256 numYears) external {
        // set the age into storage
    }
}

Notice the dynamic expression documentation for the setAge function. When presented to the end user, this will render based on the inputs provided by the user. For example, if the end user is calling the contract with an input of 10 years, this will be rendered by radspec as:

Set the tree age to 10 years

Use the Solidity compiler to generate user documentation and ABI with:

solc --userdoc --abi tree.sol

This produces the outputs:

{
  "methods" :
  {
    "setAge(uint256)" :
    {
      "notice" : "Set the tree age to `numYears` years"
    }
  }
}

and

[{
  "constant":false,
  "inputs":[{"name":"numYears","type":"uint256"}],
  "name":"setAge",
  "outputs":[],
  "payable":false,
  "stateMutability":"nonpayable",
  "type":"function"
}]

Write a simple tool using radspec to interpret this:

import radspec from 'radspec'

// Set userDoc and ABI from above
const expression = userDoc.methods["setAge(uint256)"].notice
const call = {
  abi: abi,
  transaction: {
    to: '0x8521742d3f456bd237e312d6e30724960f72517a',
    data: '0xd5dcf127000000000000000000000000000000000000000000000000000000000000000a'
  }
}
radspec.evaluate(expression, call)
  .then(console.log) // => "Set the tree age to 10 years"

See more examples here and in the tests.

Please let us know if there's anything else you'd like Radspec to be able to evaluate by filing an issue!

Installation

Simply use your favorite Node.js package manager:

npm i radspec

Documentation

Documentation about radspec and the internals of radspec can be found here.

Contributing

TBD

Aside: Why is natspec.js unsafe?

natspec.js accepts any valid JavaScript. There are multiple reasons this is a bad idea:

You either need to write your own JavaScript VM or use eval (unsafe!) from inside JavaScript
A fully-featured language with classes, functions and much more is absolutely overkill for something that could be solved with a simple DSL.

As dapps become increasingly complex, it is paramount that tools are written in a way that makes phishing near impossible. Evaluating JavaScript directly makes opens your dapp up to cross-site scripting attacks by users merely submitting a transaction(!).

License

MIT

aragon / radspec

readme