ImSQL Lua 合约工具

ImSQL 是由中科物缘原创，具有完全自主知识产权, 基于区块链及分布式存储等技术思想，兼具了可信数据存储、海量大数据存储、隐私碎片化存储等能力和优势。插件具有以下功能：

• 智能合约编译，右键点击菜单
• 智能合约部署
• 已部署的智能合约列表
• 智能合约执行函数

您需要自行下载 Lua 语言的代码高亮及语法提示工具

智能合约的编写

若第一次接触 Lua, 请参见菜鸟教程

Hello World

下面提供一个示例程序，设置一个键值对，键名为参数 key 的值，键值为 "Hello World".

--- contract.lua
local key = args.key
if (key == '') then
    error('键为空')
end
-- 设置键值对
imsql.set(key, 'Hello World')

# contract.yaml
description: Hello World
usage:
    arguments:
        - key
testCases:
  - arguments:
    key: sample/key
    keyValueSets: []
    shouldReturns:
      sample/key: Hello World
  - arguments:
      key: ""
    keyValueSets: []
    shouldError: true

简介

ImSQL 智能合约 (Lua) 只生成一个 main 方法运行主代码块，用户需要自行决定如何调用合约中不同的功能。

例如，可以通过传入一个参数用于指定调用的方法名称：

local methods = {}

function methods.a ()
    -- do something
end

function methods.b ()
    -- do something
end

-- 由于发生错误会自动回滚，不需要对方法名进行检查
methods[args.method] ()

同时，为规范参数表及测试流程，需要额外提供一个 YAML 文件用于描述此合约：

# 定义合约描述，必填
description: Contract Description
# 定义合约参数信息，必填
usage:
  arguments:
    # 参数默认编译为 string 类型，需要用户自行转换
    - method_name
    - method_arg
# 合约测试，必须全部通过后才可上传
# 目前用户必须提供测试用例才能上传合约
# 目前不支持自定义模拟 "owner" 和 "sender" 的值
testCases:
  - arguments:
      # 提供测试用的参数
      method: a
    keyValueSets:
      # 提供测试环境可以获取的键值对
      # 若尝试获取其他键值对则执行失败
      key: value
    shouldReturns:
      # 提供结果集，若执行的结果集与结果不同则执行失败
      result: hello world
  - arguments:
      method: do-not-exist
    keyValueSets: []
    # 通过设置此字段，可以测试合约执行失败的状况
    shouldError: true

ImSQL API

ImSQL 智能合约 (Lua) 提供下列方法:

--- 用户传入的参数表
-- @usage args.argument_name
args = {}

--- 从 ImSQL 联盟链中获取数据
-- @param key 获取数据的键
-- @return 获取到的数据值
-- @raise 若值不存在或无权访问，则发生错误
-- @usage imsql.get('test/key')
function imsql.get(key) end

--- 向 ImSQL 联盟链中写入数据
-- @param key 写入数据的键
-- @param value 写入数据的值
-- @raise 若键已存在或用户无权写入，则发生错误
-- @usage imsql.get('test/key', 'HELLO WORLD')
function imsql.set(key, value) end

--- 获取合约的调用者
-- @return 合约的调用者
-- @usage imsql.sender()
function imsql.sender() end

--- 获取合约的创建者
-- @return 合约的创建者
-- @usage imsql.owner()
function imsql.owner() end

--- @section 部分 Lua 功能被禁止使用
os = nil
io = nil
debug = nil
package = nil

--- @section 部分 Lua 函数被禁止使用
load = nil
loadfile = nil
loadstring = nil
dofile = nil
module = nil
require = nil
print = nil

多文件支持

目前，ImSQL Lua 智能合约不支持将多个源代码文件编译为一个智能合约。

智能合约的部署和执行

ImSQL智能合约在部署调用的时候都会携带用户的专属证书，证书会在用户加入联盟链的时候由联盟链的管理者颁发，证书中包括了用户的个人信息，代替了用户名密码的作用，并且该证书由根证书的公钥加密，在进行接口调用时会使用根证书的私钥对证书进行验证，确保使用者是联盟成员。ImSQL智能合约部署的时候会将智能合约编译，并将编译后的结果和证书一起传到后台，将智能合约编码，用户信息以及ABI信息组合使用sha3加密，作为键，将智能合约作为值，组成键值对存储在链上。在存储之前会根据算出的键去查找是否已经存在该智能合约，所以，一个用户只能部署相同的智能合约一次，但是不同的用户可以部署相同的智能合约。所以，当提示 “该智能合约已经存在” 的时候，请查看一下已部署的智能合约。

编译智能合约

用户在 VSCode 中打开智能合约 Lua 文件，点击右键，在右键菜单中单击 “编译/测试智能合约”。

• 用户在编译/测试合约之前，建议先保存文件

在接下来弹出的窗口中，选择合约的描述文件 (YAML)。

• 此文件可以存储在任意位置，但一旦选择，接下来对此文件的更改将不会生效，除非您重新编译该合约。

在接下来弹出的页面，您可以看到合约的编译及测试结果。

• 若您的合约未能通过所有测试用例，您需要修改您的合约或测试用例，直到通过为止。

上传智能合约

用户在编译页面中选择 “上传合约”，进入上传合约页面。

• 有可能用户需要登录到联盟链，您需要在“检查您的设置”中，输入 API 地址并提供证书文件。

检查您的用户信息和合约信息，然后点击“上传合约”

上传成功后，将显示合约的地址和“执行合约”按钮，您可以点击“执行合约”测试您的合约。

• 点击您合约地址右方的“复制”按钮可以快速将您的合约地址复制到剪贴板中。

(可选) 点击“执行合约”，输入参数值，点击“执行”，执行结果将会输出到控制台中。

执行智能合约

打开 VSCode 命令面板，选择“执行智能合约”。

• 您也可以继续使用编译智能合约时的界面

在该页面中，“我部署的”标签页显示已您的身份部署的合约，在“浏览”标签页您可以搜索执行环境中所有可发现的合约。

点击“执行合约”，选择方法，输入参数值，点击“执行”，执行结果将会输出到控制台中。

• 执行合约的控制台被命名为 {合约地址}@ImSQL，执行完成 1 分钟后控制台会自动销毁，请注意及时保存数据。

切换证书

若您需要切换操作智能合约时使用的身份，您需要点击编译/上传/执行页面中的“切换证书”按钮，此时您将会回到未登录状态，您可以重新在“检查您的设置”界面中输入不同的 API 地址或导入不同的证书，以不同的身份部署/执行智能合约。