蚂蚁区块链第18课 区块链预言机(ORACLE)的定义及在蚂蚁BAAS中的使用

// OracleInterface.sol
pragma solidity ^0.4.22;
// 使用预言机 API 需要在用户合约中开启 ABIEncoderV2 特性
pragma experimental ABIEncoderV2; 
 
interface OracleInterface {
    /**
     * function: 发送 CURL 请求
     * parameters:
     *         _biz_id            : 用户自定义的业务请求 ID
     *         _curl_cmd          : CURL 命令，参考 CURL 命令使用文档进行构造
     *         _if_callback       : 是否需要预言机将请求结果回调用户合约
     *         _callback_identity : 预言机请求结果回调的合约 ID，可以是发送请求的合约，也可以是其他合约
     *         _delay_time        : 该特性未激活，填 0 即可
     * return value:           : 预言机请求 ID，是预言机合约为本次请求生成的唯一请求 ID
     */
    function curlRequestDefault(bytes32 _biz_id, string _curl_cmd, bool _if_callback, identity _callback_identity, uint256 _delay_time) external returns (bytes32);
 
    /**
     * function: oracleCallbackCurlResponse
     * parameters:
     *         _request_id        : 预言机合约请求 ID（在发送请求时预言机合约会返回此 ID）
     *         _biz_id            : 用户合约的业务请求 ID
     *         _error_code         : 请求结果码，如果值是 0，则表示预言机请求处理成功；如果是其他值，则为请求处理失败，详见合约错误码表
     *        _resp_status       : HTTP 响应的状态码，一般 200 表示 HTTP 请求处理成功，5xx 表示服务端处理错误，调用者可根据自己的使用场景做判断
     *        _resp_header       : HTTP 响应的 header，如果 CURL 中指定了要返回 HTTP 响应的 header，则回调时会返回对应的值
     *        _resp_body         : http 响应的 body
     *        _call_identity     : 发起该请求的合约 ID
     * return value            : 无
     */
    function oracleCallbackCurlResponse (bytes32 _request_id, bytes32 _biz_id, uint32 _error_code, uint32 _resp_status, bytes _resp_header, bytes _resp_body, identity _call_identity) external;
 
}

 function curlRequestDefault(bytes32 _biz_id, string _curl_cmd, bool _if_callback, identity _callback_identity, uint256 _delay_time) external returns (bytes32);

 function oracleCallbackCurlResponse (bytes32 _request_id, bytes32 _biz_id, uint32 _error_code, uint32 _resp_status, bytes _resp_header, bytes _resp_body, identity _call_identity) external;

pragma solidity ^0.4.22;
// 使用预言机 API 需要在用户合约中开启 ABIEncoderV2 特性
pragma experimental ABIEncoderV2; 
 
import "./OracleInterface.sol";
 
// 实现一个demo合约
contract BizContract {
 
    // 业务 ID 与预言机请求 ID 的关联关系
    mapping(bytes32 => bytes32) request_id;
 
    // 调用预言机合约的 CURL 接口
    function rawCURLRequest(identity oracle_address, bytes32 biz_id, string cmd) public{
        // 1. 跨合约调用，需要通过合约 API 定义及合约 ID 生成一个合约对象
        OracleInterface oracle = OracleInterface(oracle_address);
 
        // 
        // 2. 发送 CURL 请求
        //   （例如查询股票行情信息，cmd 参数的值可以是“https://hq.sinajs.cn/list=hk00941”）
         bytes32 request_id = oracle.curlRequest(service_id, biz_id, cmd, true, this, 0);
          // 3. 记录预言机返回的request id
         request_id[biz_id] = request_id;
 
        // 4. 请求阶段结束，等待回调
        return;
    }
 
    // 业务合约用于接收预言机合约的 CURL 请求结果回调
    function oracleCallbackCurlResponse (bytes32 _request_id, bytes32 _biz_id, uint32 _error_code, uint32 _web_status, bytes _resp_header, bytes _resp_body, identity _call_identity) external {
 
        // 业务处理回调结果
    }
}

NAME
    curl
 
VERSION
    1.0.0_BETA
 
SYNOPSIS
    curl https://address[:port][/path][?args] [options]
 
DESCRIPTION    
    CURL 命令是预言机提供的 Web API 接口必要传入参数之一。CURL 命令描述了指定预言机访问目的互联网资源的 URI，以及其他可选配置项。
    当前外部数据源服务版本暂不支持 HTTP 分块传输编码，即不支持 HTTP 响应的 Transfer-Encoding 为 chunked，后续版本会支持该特性。
 
OPTIONS
    --request <GET|POST>
        HTTP 访问的方法，支持 GET 和 POST。缺省使用 GET 方法。
        e.g. 
            --request GET
            --request POST
 
    --header <header:value>
        指定 HTTP 请求中附带的 header 信息。
        header 名和 header 值使用冒号分割。如果 header 名或者值包含空格，应该使用单引号将其作为整体包起来，譬如 --header 'content-type:plain text'。
        --header 选项可以重复使用多次来配置多对 header，最多不超过 100 对。
        以下为保留 header，用户配置不生效："Host"、"Accept"、"User-Agent"、"Connection"、"Content-Length"。
        e.g.
            --header SomeHeader:SomeValue
            --header 'Some Header:Some Value' --header k2:v2
 
    --data <value>
        HTTP 使用 POST 方法时附带的 body 信息，建议使用单引号包起来。
        e.g.
            --data 'Hello world!'
 
    --json-path <value> 
        指定了对 HTTP 原始响应 body 进行 JSONPath 处理。
        JSONPath 语法说明：https://goessner.net/articles/JsonPath/
        目前支持：$.[]*
        e.g.
            --json-path '$.obj'  取子对象
            --json-path '$[0]'   从数组取下标
            --json-path "$['obj']" 取子对象
            --json-path '$[0,1].obj' 取多个对象
 
    --body-plain-text 
        指定了返回正文内容格式，缺省 --body-plain-text。
 
    --resp-header <header>
        指定了从 HTTP 原始响应 header 全集中返回给查询方的子集。
        如果指定的 header 不在原始响应 header 全集中，则返回 value 为空字符串。
        可以指定多次 --resp-header 来指定返回多个 header。
 
    --header-plain-text
        指定了返回 HTTP 响应 header 的格式，缺省 --header-plain-text。
        具体格式为每个"header:value"占一行，使用 \r\n 换行。
 
    --header-to-json
        指定了返回 HTTP 响应 header 使用 JSON 格式组织，每个 header:value 为顶层 kv。
 
    --encrypted-envelope <value>
        加密信封字段，传递机密信息给预言机 TEE 实例。
        加密信封为以下 JSON 格式字符串的 BASE64 编码：
        { "cipher_text": "", // 机密信息密文，使用 aes-256-gcm 加密
          "aes_iv":"", // 对称加密 iv
          "gcm_aad": "", // 对称加密 add
          "gcm_tag": "" // 对称加密 tag
          "encrypted_aes_key": "" // 经过 TEE 公钥加密后的对称加密 key
          "rsa_key": "", // TEE 实例的 RSA 公钥
         }
        其中 cipher_text 字段为机密信息，值为以下固定结构的 JSON 字符串：
        {"macro_replacement":{}, "content_hash":"", "nonce_str":"", "timestamp":"", "time_to_live":""}
        其中 macro_replacement 存放宏替换内容，可以在 URL path、body、header 中嵌入宏，然后将替换值写在macro_replacement 中，只对 TEE 可见。合法宏只能从 'ORACLE_SUB_MACRO_0' ~ 'ORACLE_SUB_MACRO_4' 选择，并且替换值中不能包括合法宏。
        content_hash 存放 CURL 命令明文部分内容计算的哈希值，锁定加密信封只能与锁定的明文一起使用。
        nonce_str、timestamp、time_to_live 暂未启用。
        机密信息使用 AES/GCM/NoPadding 加密，再用 TEE 的公钥使用（TEE 的公钥在跨链服务页面中查询）RSA/None/OAEPPadding 加密 AES 密钥。