API接口描述文档

一、概念

站点提供的API接口均为WEB接口，开发者根据文档描述的规则正确使用接口即可完成相关操作，不需要下载SDK。本站接口信息均在/public.json导航文件中进行公示，此文件对外公开，使用JSON文件格式，开发者加载此文件后进行JSON解码后即可按其指导即可获取接口WEB地址。未经特别说明，接口请求及响应信息均使用JSON格式封装。

下面文档中未说明具体哈希算法时均为sha3-256在前sha256在后组成的小写16进制形式组成的自定义哈希值。为方面说明，将参与系统中运作的服务器分成两类，分别为计算服务器及应用服务器，计算服务器为带有计算任务性质的服务器，其产生主链称为权重链（后文中未特殊说明权重链即指计算服务器主链），权重链哈希有一定特点（如以deedface开头）；应用服务器为普通服务器，其主链称为最终链，链哈希无规律，其会向计算服务器提交哈希，并且获取其对应的权重链哈希当作参数生成本站最终链。计算服务器同时具有操作链（区别于权重链），操作链数据也参与权重链生成。文本编码未特殊说明均为UTF8编码；文本中未特殊说明符号所属语言均为英文符号（如逗号未特殊说明均指英文逗号,而非中文逗号，）。

不同的API接口使用URL地址，且系统中API接口的URL地址为方便起见（站点开发语言不同，如PHP、Java、Asp.net等多种多样；开发模式不同如有MVC、传统模式等，URL不方便统一）不做规定，但是必须在站点根目录下存在接口导航文件public.json。为使接口使用方便，请加盟成员（无论计算服务器还是应用服务器）不要在接口路径中包含?、&等特殊字符（仅建议，非要求，若存在可能导致使用接口通信的不规范代码通信出错），建议API的WEB接口尽量不要经常变动（即public.json不要经常变动）。

public.json介绍。服务器public.json格式统一为对象类型的键值对儿，键为接口名，值为接口本站路径（是路径，不要包含协议名、主机名等信息）。未特殊说明可选，均为必选。具体请查看下方。

接口的访问可以是https或http，强力建议使用https（由于证书等问题，某些平台无法使用https可使用http，如Windows系统WinInet系统API使用IE组件，由于证书问题通过https协议访问会出错）。访问的方法视接口不同一般为GET或POST方式（一般要求GET方式的使用POST方式也可访问，但是需要注意如果存在参数即使是POST方式也一定要通过GET方式传递）。接口的响应信息未特殊说明为JSON格式数据，一般为包含success和detail的对象。success为bool类型，结果只可能为true（执行成功）或false（执行失败），一般情况下，执行失败时success成员为false，detail为错误原因，比如某一接口功能为查询主链某一节点条目信息，执行失败success为false，detail为字符串类型”系统繁忙”。执行成功时success为true，detail视接口不同类型及信息不同，比如查询主链某一节点信息成功success为true，detail为一个对象类型数据，描述节点的哈希值、节点序号、节点产生时间等，又如添加连接接口添加连接成功success为true时，detail仅仅为操作成功的无意义提示。要看操作成功请注意success成员。

二、计算服务器API接口

public.json典型格式如：

{

"PathGetAllowedServers":"\/customize\/pages\/GetAllowedServers.php",

"PathRemoteLoginVerify":"\/customize\/pages\/RemoteLoginVerify.php",

"PathSubmitCalcTask":"\/customize\/pages\/SubmitCalcTask.php",

"QueryCalcTask":"\/customize\/pages\/QueryCalcTask.php",

"PathCurrentTaskFromHosts":"\/customize\/pages\/CurrentTaskFromHosts.php",

"PathQueryLastChainHash":"\/customize\/pages\/QueryLastChainHash.php",

"PathReportChainError":"\/customize\/pages\/ReportChainError.php",

"PathGetSingleWeightedChainItem":"\/customize\/pages\/GetSingleWeightedChainItem.php",

"PathGetSingleManualChainItem":"\/customize\/pages\/GetSingleManualChainItem.php",

"PathGetFinalChainErrors":"\/customize\/pages\/GetFinalChainErrors.php",

"PathGetLastWaitingTask":"\/customize\/pages\/GetLastWaitingTask.php",

"PathSubmitLastTask":"\/customize\/pages\/SubmitLastTask.php"

}

上述仅为格式展示使用，加盟成员可根据需要增加自定义API，或不提供非必需的PathGetLastWaitingTask。

1、PathGetAllowedServers键对应的键值指明最近一次扫描后认定允许连接的计算服务器（扫描时同样扫描本服务器，且无特殊处理），如上所示，路径为/customize/pages/GetAllowedServers.php，获取对应的列表。此接口无参数，使用GET方式即可。若操作成功，则本机响应为JSON格式的对象类型success为true，detail为字符串组成的数组类型，每个字符串都是一个主机名（一般为域名）。若操作失败success成员为false且detail为字符串类型错误原因，如”系统繁忙”。以PHP代码为例：

file_get_contents(‘https://test.block.ltd/customize/pages/GetAllowedServers.php’);

操作成功返回示例：{“success”:true:”detail”:[”a.ltd”,“b.ltd”]}；

操作失败返回示例：{“success”:true:”detail”:”系统繁忙”}（实际操作时中文可能被\u开始的转义字符等价替换）。

PathRemoteLoginVerify键对应远程验证令牌（信息）信息。本接口需要userid及userpwd两个参数，分别为用户ID及密码的MD5加密值。接口要求POST方式访问，参数在POST数据中给出。PHP代码为例访问本接口：

$postdata = http_build_query([‘userid’=>1,’userpwd’=>’测试加密密码’]);

$options = [

        'http' =>

        [

            'method' => 'POST',

            'header' => 'Content-type:application/x-www-form-urlencoded',

            'content' => $postdata,

            'timeout' => 20 //超时时间，单位秒

        ]

    ];

    $context = stream_context_create($options);

    $response = file_get_contents(‘https://block.ltd/RemoteLoginVerify.php’, false, $context);

成功返回如：{“success”:true:”detail”:”验证一致，验证时间 2020-05-01 00:00:00 （服务器时间），当前余额 10000 分”}，其中时间及余额为动态数据，仅为举例使用。；失败返回结果如{“success”:true:”detail”:”系统繁忙”}（实际操作时中文可能被\u开始的转义字符等价替换）。

3、PathSubmitCalcTask键对应提交计算任务接口路径。本接口需要使用POST方式，参数需要userid、userpwd、tasks、servername共4个参数，参数分别指明用户ID、用户密码加密值、JSON格式字符串数组类型的计算任务列表（每个字符串必须是合法的128位小写字母数字组成的字符串）及服务器主机名。此参数和设置登录令牌及设置IP白名单主机有关。PHP代码为例访问本接口： $postdata = http_build_query([‘userid’=>1,’userpwd’=>’测试加密密码’,‘tasks’=>[‘哈希值1’,’哈希值2’],’servername’=>’jilu.block.ltd’]);

$options = [

        'http' =>

        [

            'method' => 'POST',

            'header' => 'Content-type:application/x-www-form-urlencoded',

            'content' => $postdata,

            'timeout' => 20 //超时时间，单位秒

        ]

    ];

$context = stream_context_create($options);

$response = file_get_contents(‘https://block.ltd/SubmitCalcTask.php’, false, $context);

4、   QueryCalcTask指定获取计算任务结果接口路径，此接口一次只能获取一个哈希值结果，要求GET方式访问，需要3个参数，分别是uesrid、userpwd、task，对应的是用户ID、加密的用户密码及要获取哪个哈希值对应的计算结果。$response = file_get_contents(‘https://block.ltd/QueryCalcTask.php?querykey=查询码&task=哈希值1’);，成功返回如：{“error”:0:”detail”:$具体内容}；$具体内容是一个对象，其结构如下：

{

“WeightHash3”:”权重SHA3-256哈希值”,

“WeightHash2”:”权重SHA256哈希值”,

“LastChain”:”上一权重链哈希”,

“Hash3Value”:”SHA3-256值”,

“Hash2Value”:”SHA256值”

}

具体值生成过程请查看技术白皮书

失败返回结果如{“error”:1:”message”:”系统繁忙”}（实际操作时中文可能被\u开始的转义字符等价替换）。

• PathCurrentTaskFromHosts指明当前计算服务器相关的子服务器列表，使用GET方式访问即可，PHP代码如：file_get_contents(‘https://block.ltd/CurrentTaskFromHosts.php”);成功detail字段是一个字符串组成的数组，每个字符串均为一个主机名，失败detail表示失败原因。成功如：{“success”:true:”detail”:[‘a.ltd’,’b.ltd’]}。
• PathQueryLastChainHash指明获取最新权重链哈希路径，无参数，GET方式访问即可。成功时success为true，detail为128位哈希值或空字符串（链数据为空）。
• PathReportChainError指明报告链错误路径，POST方式，参数如下：

userid:用户ID

userpwd:用户密码的md5值

servername:上报服务器自身主机名

FinalChainItemId:最终链序号

ShoudHash:上报服务器计算出的哈希

RealHash:被报告服务器存在的哈希

PreviousHash:最终链上一条目哈希

ToServer:被报告服务器哈希

• PathGetSingleWeightedChainItem指明获取单个权重链条目信息，GET方式，参数：no:获取的链节点序号，0表示最新节点信息，默认为0；nonexist：值必须为next、previous、error中的一个，表示若指定序号不存在则返回下一个、上一个、出错。成功时detail为对象类型成员，成员如下：

WeightHash3:最终链哈希3值

WeightHash2：最终链哈希2值

Hash3Value:哈希3值

Hash2Value:哈希2值

CalcChainHash：来自应用服务器提交的哈希值+验证码计算而出的哈希值

FromServer：来自的应用服务器

CalcTaskId：任务ID即最终链序号

• PathGetSingleManualChainItem指明获取单个操作链条目信息，GET方式。参数：no:获取的链节点序号，0表示最新节点信息，默认为0；nonexist：值必须为next、previous、error中的一个，表示若指定序号不存在则返回下一个、上一个、出错。成功detail为对象类型成员，成员如下：

TypeShowName:类型

         Description:文本描述

         ItemHash:文本描述哈希值

         ChainHash:操作链哈希值

         CreateTime:产生时间

         ManualChainId:链序号

• PathGetFinalChainErrors指明获取最终链错误主机列表，GET方式，无参数，成功detail成员为一个数组，数组每个成员是对象类型，对象成员如下：

ToServer:被报错主机

ShoudHash:报错主机计算出的最终链哈希

RealHash:被报错主机实际存在的最终链哈希

LastHash:上一链节点哈希值

ChainItemId:最终链序号

CreateTime:产生时间

ReportedServer:被报错主机名

• PathGetLastWaitingTask指明获取当前任务，GET方式，无参数，成功时detail为对象类型，成员如下：

CalcChainHash:任务哈希

LastChain:上一哈希值

         MustHash3Prefix:要求的哈希3前缀

         MustHash2Prefix:要求的哈希2前缀

• PathSubmitLastTask指明提交当前任务，GET方式，参数：

Hash3value:计算出的哈希3值

hash2value:计算出的哈希2值

userid:提交的用户ID（若计算成功可能会给该用户添加奖励）

success指明成功失败，detail为成功或失败原因，字符串类型

一般访问各实际接口时先需要访问导航文件public.json文件，上述示例中为方便说明直接使用一接口名。实际的接口名不同加入的成员主机并不一致，并且同一主机也可能会修改接口路径（如网络升级等原因）。本段以验证用户令牌接口为例，使用PHP代码展示一般访问过程：

<?php

 

try

{

$useridsubmit=1;//用户ID

$userpwd=mdt('123');//用户密码加密

$servername='block.ltd';

//获取导航文件

$t=file_get_contents('https://'.$servername.'/public.json');

    if(!$t)

        throw new Exception('获取导航文件失败', 1);

    //true参数指定了将对象转换成数组，开发者也可活力true当对象处理

    $t =json_decode($t,true);

    if(!$t)

        throw new Exception('JSON解码失败', 1);

    $public_config_server=$t;

 

    //此为数组类型访问方式，若解码成对象类型

    //则写法为$public_config_server->PathRemoteLoginVerify，下周

    if(!isset($public_config_server['PathRemoteLoginVerify']))

        throw new Exception('配置文件错误，未定义远程登录验证网址', 1);

 

    //send_post函数后面有定义

    $t = send_post('https://'.$server_name.$public_config_server['PathRemoteLoginVerify'],['userid'=>$useridsubmit,'userpwd'=>$userpwd]);

    if($t===false)

        throw new Exception('访问远程服务器失败', 1);

    $t =json_decode($t,true);

    if(!$t)

        throw new Exception('JSON解码失败', 1);

    if(!$t['success'])

        throw new Exception('验证失败，'.$t['detail'], 1);

    /*

    **若上面均未抛出异常，即为验证通过

    **此处应该在数据保存用户名、加密后的密码、主机名等数据及其它逻辑操作

    */

}

catch (Exception $e)

{

//变量$err_message记录了异常信息

$err_message=$e->getMessage();

/*自定义处理异常的代码...*/

}

 

/**

 * 发送post请求

 * @param string $url 网址

 * @param array $post_data post键值对

 * @return string

 */

function send_post($url, $post_data)

{

    $postdata = http_build_query($post_data);

    $options = [

        'http' =>

        [

            'method' => 'POST',

            'header' => 'Content-type:application/x-www-form-urlencoded',

            'content' => $postdata,

            'timeout' => 20 //超时时间，单位秒

        ]

    ];

    $context = stream_context_create($options);

    $result = file_get_contents($url, false, $context);

    return $result;

}

 

?>

 

 

三、应用服务器计算接口

public.json一般格式如下

{

"PathAddConnect":"\/customize\/pages\/PathAddConnect.php",

"PathGetFinalChainHash":"\/customize\/pages\/GetFinalChainHash.php",

"PathGetCreditGrade":"\/customize\/pages\/GetCreditGrade.php",

"PathGetSingleFinalChainItem":"\/customize\/pages\/GetSingleFinalChainItem.php",

"PathGetFinalChainErrors":"\/customize\/pages\/GetFinalChainErrors.php"

1、PathAddConnect键对应的键值指明添加连接的接口路径，如上所示，路径为/customize/pages/PathAddConnect.php，即想与本机想连需要访问本机的此路径。访问此路径需要提供GET参数server。若操作成功，则本机响应为JSON格式的对象类型success为true，detail无意义，均为字符串类型数据”操作成功”。若操作失败success成员为false且detail为字符串类型错误原因，如”连接数超过上限”。若开发者的主机为a.ltd，其想加入与本机的连接，配置好协议文件等环境后，访问此接口时指定其主机域名，以PHP代码为例：

file_get_contents(‘https://test.block.ltd/customize/pages/PathAddConnect.php?server=a.ltd’);

操作成功返回示例：{“success”:true:”detail”:”操作成功”}（实际操作时中文可能被\u开始的转义字符等价替换）；

操作失败返回示例：{“success”:true:”detail”:”连接数超过上限”}

2、PathGetFinalChainHash键对应最终链条目信息。本接口无参数，PHP代码为例访问本接口： file_get_contents(‘https://test.block.ltd/customize/pages/GetFinalChainHash.php’)，成功返回如：{“success”:true:”detail”:”xxxxxxxxxxxx”}，其中xxxxxxxxxxxx为128位小写字母+数字组成的哈希值；失败返回结果如{“success”:true:”detail”:”系统繁忙”}（实际操作时中文可能被\u开始的转义字符等价替换）。

3、PathGetCreditGrade键对应最终链条目信息。本接口无参数，PHP代码为例访问本接口： file_get_contents(‘https://test.block.ltd/customize/pages/PathGetCreditGrade.php’)，成功返回如：{“success”:true:”detail”:999}，其中999则为本站权重值；失败返回结果如{“success”:true:”detail”:”系统还未生成”}（实际操作时中文可能被\u开始的转义字符等价替换）。

4、PathGetSingleFinalChainItem指明获取单个最终链条目信息，GET方式，参数：no:获取的链节点序号，0表示最新节点信息，默认为0；nonexist：值必须为next、previous、error中的一个，表示若指定序号不存在则返回下一个、上一个、出错。成功时detail为对象类型成员，成员如下：

ChainHash:主链哈希值

         ContentText:描述文本

         ContentHash:描述文本哈希

         BlockWeightChainId:最终链序号

         WeightedHash3:最终链哈希3值

         WeightedHash3Value:最终链只哈希3依赖的变量

         WeightedHash2:最终链哈希2值

         WeightedHash3Value:最终链只哈希2依赖的变量

         FinalChainHash:最终链

         NodeHash:节点值

         CalcOutAddtion:计算服务器相连主机哈希值

         CalcInnerAddtion:计算服务器操作链哈希值

         CalcLast:上一条哈希

5、PathGetFinalChainErrors指明获取报错主机信息，成功detail成员为一个数组，数组每个成员是对象类型，对象成员如下：

ToServer:被报错主机

ShoudHash:报错主机计算出的最终链哈希

RealHash:被报错主机实际存在的最终链哈希

LastHash:上一链节点哈希值

ChainItemId:最终链序号

CreateTime:产生时间

ReportedServer:被报错主机名

 

一般访问各实际接口时先需要访问导航文件public.json文件，上述示例中为方便说明直接使用一接口名。实际的接口名不同加入的成员主机并不一致，并且同一主机也可能会修改接口路径（如网络升级等原因）。本段以添加主机接口为例，使用PHP代码展示一般访问过程：

<?php

 

try

{

//获取接口导航文件

$t=file_get_contents('https://test.block.ltd/public.json');

    if(!$t)

        throw new Exception('获取导航文件失败', 0);//若失败抛出异常

 

    //json解码，true参数指定为将对象转换为数组类型

    //这里开发者如习惯对象类型，请省略true参数

    $t =json_decode($t,true);

    if(!$t)

        throw new Exception('JSON解码失败', 0);

    $public_config=$t;//$public_config记录导航文件信息

 

    //正常情况下肯定存在PathAddConnect键，以防万一

    //若JSON转化时为对象格式请使用$public_config->PathAddConnect

    //同理，后面的数组方式访问均按描述转化为对象类型

    if(!isset($public_config['PathAddConnect']))

        throw new Exception('配置文件错误', 0);

    //注意，路径中已经包含了根目录符号/，所以主要名后面不要带有/

    $url = 'https://test.block.ltd'.$public_config['PathAddConnect'];

    //API接口可能多种多样，如有采用MVC架构或本身就带有GET参数（接口ID等）

    //目前本站API接口本身均无GET参数，所以不需要处理？，代码仅为以防万一

    if(strpos($public_config['PathAddConnect'], '?')===false)

        $url.='?';

    $t = explode('?', $url);

    if(count($t)!=2)

        throw new Exception('服务器路径不合法'.$url, 0);

    if(strlen($t[1]))

        $url.='&';

    $url.='server='.urlencode($_SERVER['SERVER_NAME']);

    $t = @file_get_contents($url,false);

    if($t===false)

        throw new Exception('访问远程服务器'.$url.'失败', 0);

 

    //接口返回的响应信息同样为JSON格式

    $t =json_decode($t,true);

    if(!$t)

        throw new Exception('JSON解码失败', 0);

    if(!$t['success'])

        throw new Exception('操作失败，服务器报告：'.$t['detail'], 0);

 

    /*

    **若上面均未抛出异常，即为对方添加本机成功

    **此处应该添加对方添加本机成功后的代码

    **如本机数据库将对方主机添加连接信息等

    */

}

catch (Exception $e)

{

//变量$err_message记录了异常信息

$err_message=$e->getMessage();

/*自定义处理异常的代码...*/

}

 

?>

 

四、总结

API接口均为WEB方式，不必下载SDK开发包。对接接口时选择自己适合的开发语言对接口先进行测试。部分接口使用前需要先到对应的网站上进行充值、设置密码、设置IP白名单等操作，具体参考使用文档。通过API获取的信息，具体使用方式请参考技术白皮书。