CYBEX CYBEX 开发快速接入

pendingauth · 2019年01月16日 · 75 次阅读

本文转载自CybexDex/cybex-node-doc,原文链接:https://github.com/CybexDex/cybex-node-doc/wiki/CYBEX开发接入

HTTP及Websocket调用

CYBEX中任意节点包含两种API接⼝,所有API数据均使用JSON-RPC2.0形式。可以选择使用HTTP或Websocket⽅式进⾏访问。两种方式的params参数结构均为:

[API-identifier, Method-to-Call, Call-Parameters]

HTTP⽅式仅允许只读的查询数据库,如:

$ curl --data '{"jsonrpc": "2.0", "method": "call", "params": [0, "get_accounts", [["1.2.0"]]], "id": 1}' http://127.0.0.1:8090/rpc

返回结果

{
    "id": 1,
    "result": [{
        "id": "1.2.0",
        "annotations": [],
        "membership_expiration_date": "1969-12-31T23:59:59",
        "registrar": "1.2.0",
        "referrer": "1.2.0",
        "lifetime_referrer": "1.2.0",
        "network_fee_percentage": 2000,
        "lifetime_referrer_fee_percentage": 8000,
        "referrer_rewards_percentage": 0,
        "name": "committee-account",
        "owner": {
            "weight_threshold": 1,
            "account_autos": [],
            "key_auths": [],
            "address_auths": []
        },
        "active": {
            "weight_threshold": 6,
            "account_auths": [
                ["1.2.5", 1],
                ["1.2.6", 1],
                ["1.2.7", 1],
                ["1.2.8", 1],
                ["1.2.9", 1],
                ["1.2.10", 1],
                ["1.2.11", 1],
                ["1.2.12", 1],
                ["1.2.13", 1],
                ["1.2.14", 1]
            ],
            "key_auths": [],
            "address_auths": []
        },
        "options": {
            "memo_key": "GPH1111111111111111111111111111111114T1Anm",
            "voting_account": "1.2.0",
            "num_witness": 0,
            "num_committee": 0,
            "votes": [],
            "extensions": []
        },
        "statistics": "2.7.0",
        "whitelisting_accounts": [],
        "blacklisting_accounts": []
    }]
}

Websocket⽅式需要登录(链上执行⼴播需要会话信息)并可执行查询和修改操作。wscat调用示例:

$ npm install -g wscat
$ wscat -c ws://127.0.0.1:8090   
> {"id":1, "method":"call", "params":[0,"get_accounts",[["1.2.0"]]]}

返回结果

{
    "id": 1,
    "result": [{
        "id": "1.2.0",
        "annotations": [],
        "membership_expiration_date": "1969-12-31T23:59:59",
        "registrar": "1.2.0",
        "referrer": "1.2.0",
        "lifetime_referrer": "1.2.0",
        "network_fee_percentage": 2000,
        "lifetime_referrer_fee_percentage": 8000,
        "referrer_rewards_percentage": 0,
        "name": "committee-account",
        "owner": {
            "weight_threshold": 1,
            "account_autos": [],
            "key_auths": [],
            "address_auths": []
        },
        "active": {
            "weight_threshold": 6,
            "account_auths": [
                ["1.2.5", 1],
                ["1.2.6", 1],
                ["1.2.7", 1],
                ["1.2.8", 1],
                ["1.2.9", 1],
                ["1.2.10", 1],
                ["1.2.11", 1],
                ["1.2.12", 1],
                ["1.2.13", 1],
                ["1.2.14", 1]
            ],
            "key_auths": [],
            "address_auths": []
        },
        "options": {
            "memo_key": "GPH1111111111111111111111111111111114T1Anm",
            "voting_account": "1.2.0",
            "num_witness": 0,
            "num_committee": 0,
            "votes": [],
            "extensions": []
        },
        "statistics": "2.7.0",
        "whitelisting_accounts": [],
        "blacklisting_accounts": []
    }]
}

发起API请求

CYBEX的API分为两类:

  1. 查询操作,可以直接访问
  2. 修改操作,需要通过广播交易broadcast_transaction方式进行,⼴播交易时,需要进行签名。

进⾏查询时,可以使⽤curl的普通HTTP形式访问节点端⼝下的/rpc路路径来执⾏,或者使用辅助库的工具类来进行,工具类使用Websocket方式连接节点。

发起API请求

CYBEX节点提供了许多可以通过Websocket进行连接的API,包括:Database API、Account History API、Network Broadcast API、Network Nodes API。

请求API的具体步骤如下:

  1. 登录全节点
  2. 获得API访问权限
  3. 获取API标识
  4. 提供获取的标识,调用某个具体的API方法

1. 登录

首先,我们需要完成登录操作:

> {"id":2,"method":"call","params":[1,"login",["",""]]}
< {"id":2,"result":true}

对于需要登录后才能调用的API,调用方需要填写 用户名密码。节点在验证通过后,将会返回登录成功的信息。

2. 获得API访问权限

数据库API提供了大部分常用的查询接口,以此为例,我们可以通过以下方式 注册 Database API:

> {"id":2,"method":"call","params":[1,"database",[]]}

3. 获取API标识

在发起连接请求后,全节点会驳回该请求或返回一个唯一标识:

< {"id":2,"result":2}

这个返回结果代表了我们之前对Database API发出请求被允许了,这个id被称为DATABASE API ID。

4. 提供获取的标识,调用某个具体的API方法

现在,我们就可以调用Database API的某个具体方法了:

> {"id":1, "method":"call", "params":[DATABASE_API_ID,"get_accounts",[["1.2.0"]]]}

广播交易

CYBEX原生的操作(Operations)需要通过广播的方式执行,广播操作通过broadcast_transaction完成。

void graphene::app::network_broadcast_api::broadcast_transaction(const signed_transaction &trx)

其中,trx参数用来包裹Operation。

⼴播并执⾏⼀个交易,⼤致的步骤是:

  1. 构造交易体
  2. 向交易体中添加操作
  3. 添加签名
  4. ⼴播交易

前两个步骤是需要手动进行的,后两个步骤可以通过辅助库的工具类协助执行。

注册用户是一个常见的业务操作,我们以这个操作和JavaScript库为例,详细讲解一下广播的交易步骤。

首先,判断这是一个数据修改(新增)操作,所以需要通过广播交易broadcast_transaction方式进行。创建账户使用的是account_create_operation,因此,我们通过以下方式实现:

let tr = new TransactionBuilder(); // 构造一个交易体,TransactionBuilder可从cybexjs库中获得。
tr.add_type_operation("account_create", { // 向交易中添加所需广播的操作,操作名称为 account_create.
    fee: { 
        amount: 0,
        asset_id: "1.3.0"
    }, // 该笔交易的手续费字段。
    registrar: chain_registrar.get("id"), // 注册人ID
    referrer: chain_referrer.get("id"), // 引荐人ID
    referrer_percent: referrer_percent, // 引荐人返利额度
    name: new_account_name, // 用户名
    owner: { // 用户的Owner权限设置
        weight_threshold: 1, // Owner权限的域限
        account_auths: [], // 占有权限的用户列表
        key_auths: [[owner_pubkey, 1]], // 占有权限的公钥列表
        address_auths: [] // 占有权限的地址列表
    },
    active: { // 活跃权限配置
        weight_threshold: 1,
        account_auths: [],
        key_auths: [[active_pubkey, 1]],
        address_auths: []
    },
    options: { //其他配置
        memo_key: active_pubkey, // Memo公钥,其他人向该用户发送Memo时,将使用该公钥进行加密
        voting_account: "1.2.5", // 默认投票代理
        num_witness: 0, // 初始投票的证人数量
        num_committee: 0, // 初始投票的委员会数量
        votes: [] //初始投票的ID集合
    }
 });
 tr.add_signer(privKey); // 向交易添加签名,传入私钥
 await tr.broadcast(); // 广播交易,异步操作

数据库通知

在CYBEX中,通过websocket连接的方式监听数据库变更或事件发生。

CYBEX运行通过以下方式进行订阅:

set_subscribe_callback( int identifier, bool clear_filter ):

简单的全局监听回调可以通过该方法实现。

每个通知经由全节点初始化的通知都会具有一个唯一的ID,用户通过identifier参数为ID赋值。

set_pending_transaction_callback(int identifier):

待确认的事务回调。

subscribe_to_market(int identifier, asset_id a, asset_id b)):

订阅市场上关于a:b交易对的变更并使用identifier的ID进行通知。

get_full_accounts(array account_ids, bool subscribe):

根据指定account_ids查询该账户所有相关信息,并通过将subscribe设置为True订阅该账户的更新。

让我们通过一个全局订阅的回调将通知与通常的RPC调用做一下区分:

> {"id":4,"method":"call","params":[DATABASE_API_ID,"set_subscribe_callback",[SUBSCRIPTION_ID, true]]}

上述调用需要将SUBSCRIPTION_ID注册为ID来获取通知.

自此,你从见证人节点获取的对象都会自动订阅该对象未来的所有变更。

在调用set_subscribe_callback方法之后,见证人节点会将该对象的每一次变更都以通知的形式发送给你:

< {
    "method": "notice"
    "params": [
        SUBSCRIPTION_ID,
        [[
            { "id": "2.1.0", ...  },
            { "id": ...  },
            { "id": ...  },
            { "id": ...  }
        ]]
    ],
}

Session示例

以下是一个完整seesion的示例:

> {"method": "call", "params": [1, "login", ["", ""]], "id": 2}
< {"id":2,"result":true}
> {"method": "call", "params": [1, "database", []], "id": 3}
< {"id":3,"result":2}
> {"method": "call", "params": [1, "history", []], "id": 4}
< {"id":4,"result":3}
> {"method": "call", "params": [2, "set_subscribe_callback", [5, false]], "id": 6}
< {"id":6,"result":null}
> {"method": "call", "params": [2, "get_objects", [["2.1.0"]]], "id": 7}
(plenty of data coming in from this point on)

常见问题

1. 金额和价格如何表示?

CYBEX网络的所有费用,均使用整数计数,即amount类型,其价值value(或价格price)根据以下公式计算:

value = amount / 10^precision

其中,precision 为资产类型对应的精度。

2. 如何获取手续费信息?

在CYBEX网络内,所有需要广播的操作都需要缴纳手续费,手续费用fee字段表示。消耗的手续费会部分燃烧,燃烧的手续费进入系统预算池。fee包含的参数如下:

参数 类型 描述
amount share_type 手续费金额
asset_id asset_id_type 用来缴纳手续费的资产ID

在添加operation时,可以先将amount设为0,然后通过调用database_api中的get_required_fees接口获取该交易所需的最低手续费。

一旦手续费不足,交易广播会失败。手续费可以填写等于或高于最低手续费的任意值,多出的手续费会被系统销毁。

3. 手续费如何计算?

CYBEX网络内的所有操作,都需要向网络缴付手续费。手续费默认以CYB计算,对于不持有CYB的操作发起者,可以使用其他CYBEX网络内的资产支付手续费,换算公式为:

操作手续费 = 操作手续费(以CYB计) * 用来支付的资产与CYB的汇率

其中,后者是资产创建时,与CYB之间设置的初始汇率,该汇率可以通过get_assets接口查询。

以一般转账为例,当前transfer_operation的费率为0.01 CYB,手续费希望以BAT计算。CYB/BAT的初始汇率为0.4,则一般转账用BAT支付的收费 = 0.01 * 0.4 = 0.004 BAT

4. 为什么提现手续费高于普通转账手续费?

CYBEX的提现操作,是指将账户余额从CYBEX网络转出至外部网络(账户)。提现操作需要通过CYBEX网关,完成内盘资产到外盘的汇兑。实际上,资金经由网关出入CYBEX网络,都会产生服务手续费,只是一般情况下,网关免除了充值操作(从外盘转入CYBEX内盘)的手续费,仅收取提现手续费。

通过CYBEX网关,将从将CYBEX账户余额提现至外部账户(地址)的手续费计算公式为

提现手续费 = 网关手续费 + 提现操作手续费

其中,前者由提供充提服务的网关收取,一般以提现资产计费。后者与其他CYBEX网络内的操作一样,由CYBEX网络收取,默认使用CYB支付。如果提现账户未持有CYB,则可以选择使用提现资产进行支付。

注:提现操作手续费会因为备注内容的字数而增加,每千字节手续费为0.00555 CYB。如以提现币种计,则按以上规则换算。

共收到 0 条回复
dposclub001 屏蔽了此话题:测试 03月05日 15:48
需要 登录 后方可回复, 如果你还没有账号请点击这里 注册