@1hive/radspec 中文文档教程

Question

radspec ????

Radspec 是以太坊 NatSpec。

这允许智能联系人开发人员向最终用户展示改进的功能文档，而没有 natspec.js 的安全隐患。 Radspec 定义了自己的语法结构并解析了自己的 AST，而不是直接评估不受信任的 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 支持任何合约编程语言，例如 Solidity 或 Vyper，因为 radspec 在编译后的 JSON ABI 上运行。 这是一个使用 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
    }
}

请注意 setAge 函数的动态表达式 文档。 当呈现给最终用户时，这将根据用户提供的输入进行呈现。 例如，如果最终用户使用 10 年的输入调用合约，这将由 radspec 呈现为：

将树龄设置为 10 年

使用 Solidity 编译器生成用户文档和 ABI：

solc --userdoc --abi tree.sol

这会产生输出：

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

请注意，

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

您还可以使用 Human-Redable abis。 对于上面的示例，将是：

["function setAge(uint256 numYears) public view"]

---

使用 radspec 编写一个简单的工具来解释它：

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"

或者在此处和测试。

如果您希望 Radspec 能够评估任何其他内容，请通过提交问题告诉我们！

Installation

只需使用您最喜欢的 Node.js 包管理器：

npm i radspec

Documentation

可以在此处找到有关 radspec 和 radspec 内部结构的文档。

Contributing

TBD

Aside: Why is natspec.js unsafe?

natspec.js 接受任何有效的 JavaScript。 这是一个坏主意有多种原因：

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.

随着 dapps 变得越来越复杂，以一种几乎不可能进行网络钓鱼的方式编写工具是最重要的。 直接评估 JavaScript 会使您的 dapp 容易受到用户仅提交交易 (!) 的跨站点脚本攻击。

License

麻省理工学院