# radspec > Radspec is a safe alternative to Ethereum's natspec Latest version **1.12.1** (published 2022-06-07) · MIT license · 0 weekly downloads ## Install ```sh npm install radspec pnpm add radspec yarn add radspec bun add radspec ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.12.1 | | Published | 2022-06-07 | | First published | 2018-02-05 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 6 | | Unpacked size | 171.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 147 | | Author | Aragon Association | | Maintainers | brickpop, arabot-1, hack0, izqui, luisivan, aragon-ci, sohkai, nivida | | Keywords | language, compiler, ethereum | ## Links - npm: https://www.npmjs.com/package/radspec - Repository: https://github.com/aragon/radspec - Homepage: https://github.com/aragon/radspec#readme - Issues: https://github.com/aragon/radspec/issues - npm.io page: https://npm.io/package/radspec ## Dependencies (6) - [bn.js](https://npm.io/package/bn.js.md) ^4.11.8 - [date-fns](https://npm.io/package/date-fns.md) 2.0.0-alpha.22 - [web3-eth](https://npm.io/package/web3-eth.md) ^1.2.1 - [web3-utils](https://npm.io/package/web3-utils.md) ^1.2.1 - [web3-eth-abi](https://npm.io/package/web3-eth-abi.md) ^1.2.1 - [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.1.2 ## Alternatives - [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads - [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads - [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads - [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads - [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads ## Recent versions - 1.12.1 (latest) — 2022-06-07 - 1.12.0 — 2021-09-09 - 1.11.0 — 2021-02-03 - 2.0.0-rc.2 — 2020-08-28 - 1.10.0 — 2020-08-10 - 1.9.0 — 2020-07-20 - 1.8.0 — 2020-06-26 - 2.0.0-rc.1 — 2020-06-15 - 1.7.0 — 2020-06-03 - 1.6.4 — 2020-01-29 - 1.6.3 — 2020-01-24 - 1.6.2 — 2020-01-23 - 1.6.1 — 2019-11-08 - 1.6.0 — 2019-11-07 - 1.5.0 — 2019-10-24 - … 19 more at https://npm.io/package/radspec/versions ## README # radspec 🤘 [![Travis branch](https://img.shields.io/travis/aragon/radspec/master.svg?style=flat-square)](https://travis-ci.org/aragon/radspec) [![Coveralls github branch](https://img.shields.io/coveralls/github/aragon/radspec/master.svg?style=flat-square)](https://coveralls.io/github/aragon/radspec) Radspec is a safe interpreter for dynamic expressions in Ethereum's [NatSpec](https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format). This allows smart contact developers to show improved function documentation to end users, without the [security pitfalls of natspec.js](#aside-why-is-natspecjs-unsafe). 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. ```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: ```sh solc --userdoc --abi tree.sol ``` This produces the outputs: ```json { "methods" : { "setAge(uint256)" : { "notice" : "Set the tree age to `numYears` years" } } } ``` and ```json [{ "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: ```js 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](examples) and in the [tests](test/examples/examples.js). Please let us know if there's anything else you'd like Radspec to be able to evaluate by filing an [issue](https://github.com/aragon/radspec/issues/new)! ## Installation Simply use your favorite Node.js package manager: ```sh npm i radspec ``` ## Documentation Documentation about radspec and the internals of radspec can be found [here](docs). ## Contributing TBD ## Aside: Why is natspec.js unsafe? [natspec.js](https://github.com/ethereum/natspec.js) accepts any valid JavaScript. There are multiple reasons this is a bad idea: 1. You either need to write your own JavaScript VM or use `eval` (unsafe!) from inside JavaScript 2. 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 --- _Source: https://npm.io/package/radspec · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._