bdware/bdcontract-doc
2
0
Fork 0
mirror of https://gitee.com/BDWare/bdcontract-doc synced 2025-01-25 01:04:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

release 1.4.5

Browse Source
This commit is contained in:
CaiHQ 2022-01-04 13:14:02 +08:00
parent 47b3b7b395
commit 91b28aee61
8 changed files with 961 additions and 655 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1023
source/ContractAPI.rst
View File

File diff suppressed because it is too large Load Diff

4
source/IDEUsage.rst
View File

@ -1,5 +1,5 @@
BDContract管理界面
==================
管理界面
========
--------------

4
source/InstallTips.rst
View File

@ -1,5 +1,5 @@
BDContract安装说明
==================
安装说明
========
--------------

207
source/Introduction.rst
View File

@ -1,12 +1,12 @@
BDContract介绍
==============
北大数瑞介绍
============
--------------
什么是BDContract?
-----------------
什么是北大数瑞?
---------------
BDContract是智融云河大数据区块链中，基于北大数瑞开源的智能合约引擎封装的一套软件。是面向大数据场景的数据资源、IoT资源、云资源的管理、调度平台。BDContract是一个可信计算框架，计算逻辑以智能合约的方式表达。通过”随机“和”冗余计算“的方式实现智能合约的可信执行。BDContract在保证智能合约的可用性、可靠性的同时，着重提升执行效率和安全性。
北大数瑞是面向大数据场景的数据资源、IoT资源、云资源的管理、调度平台。BDContract是一个可信计算框架，计算逻辑以智能合约的方式表达。通过”随机“和”冗余计算“的方式实现智能合约的可信执行。BDContract在保证智能合约的可用性、可靠性的同时，着重提升执行效率和安全性。
--------------
@ -22,205 +22,10 @@ BDContract是智融云河大数据区块链中，基于北大数瑞开源的智
--------------
更新日志
--------
- **v1.4.5** 2021年6月29日
- 稳定性提升
- HTTP服务端的URIPath优化
- 支持以Http方式进行静态资源文件加载
- **v1.4.4** 2021年6月15日
- 修复了getContractMeta时没优先返回RUNNING/HANGED的合约的问题
- 实现了HomomorphicEncrypt的逻辑
- **v1.4.3** 2021年6月9日
- 修复SSL Renegotiate Bug
- 实现内存不足时自动Hangup-Resume
- 实现contract meta的硬盘持久化
- **v1.4.1** 2021年5月26日
- 实现了事件机制中的事件语义，支持“至少一次”、“至多一次”和“只有一次”
- 优化了合约模板
- 增加模板配置文件
- 优化了MockTemplate注解
- **v1.4.0** 2021年5月9日
- 优化了ACTemplate
- 完善了DoRepo的配置联动
- **v1.3.9** 2021年4月22日
- 修复了doipConfig在updateConfig中不支持的bug
- test-tool支持了sudo
- 优化了contract-template中的ACTemplate模板
- **v1.3.6** 2021年4月21日
- 修复了docker中无法获取cpuid的问题
- **v1.3.6** 2021年4月16日
- 修复了部分bug
- 修复了GRPCPool线程数量不足导致排队的bug
- 修复了requestID分配在压力测试下可能重复的bug
- **v1.3.5** 2021年3月31日
- 修复了部分bug
- http的合约调用部分增加了简单拥塞控制策略
- 稳定性提升
- **v1.3.0** 2021年2月1日
- 优化心跳机制
- 修复部分Bug
- 更新SM2/SM3库
- 更新前端签名计算方式
- **v1.2.0** 2020年12月11日
- 优化了多节点执行模式
- 优化了合约master路由的逻辑
- 修复了部分bug
- 修复文件系统相关的漏洞
- **v1.1.0** 2020年9月
- 支持https，并更新了该部分文档
- **v1.0.9** 2020年8月27日
- 完善IO相关工具类的文档
- 优化合约模板：DAC持久化
- **v1.0.7** 2020年8月13日
- 优化合约日志、账本接口
- 优化相关接口的文档
- 提供合约模板的websocket接口
- 自动编译bug修复
- **v1.0.5** 2020年7月25日
- 弱化NC的中心化作用，集群点对点连接。
- 优化bdwareclient
- TODO MemoryDurable
- **v1.0.2** 2020年7月22日
- 修复CentOS7下Too Many Opened Files的Bug
- 修复权限Bug
- 增加权限说明
- 修复MySQLUtil的bug
- 升级BDLedger版本
- **v1.0.1** 2020年7月5日
- 更新了NodePortal/CenterPortal的UI。
- 修改了编译流程，在NodePortal中可查看编译结果，在OnlineIDE中可手动/启动时编译
- 修改了合约分发逻辑，以编译后ypk作为分发的文件
- 支持public目录下的ypk在多节点模式下执行时，合约故障自动恢复
- **v0.99** 2020年6月22日
- 自定义合约方法的计费
- 新增了GasExample、Incentives示例
- 在客户端实现了“校验多点结果”，并优化了结果返回的方式
- 修复断线重连后无权限提示
- **v0.97** 2020年5月25日
- cpu等资源的计量：gas机制
- onlineIDE.html 支持上传多个文件
- udp方式组网进行多点执行[无定序消息]
- bdwareclient.html，修复只包含计算逻辑的调用示例生成前缀错误
- **v0.95** 2020年5月19日
- 修复了onlineIDE.html在的pathname有前缀时不能正确跳转bdwareclient的bug。
- 修复了bdwareclient的pathname有前缀时自动提取url的bug。
- 启用了合约的权限
- 增加了NodePortal.html/OnlineIDE.html和bdwareclient.html中无权限时的提醒
- **v0.90** 2020年5月9日
- 更改了yjs.jar/bdserver.jar的打包方式
- 更新了install.sh/update.sh
- onlineIDE的修改后提醒
- onlineIDE标签页自适应宽度
- 文件接口隔离
- **v0.8** 2020年4月26日
- 完善文档界面和优化SDK提供方式
- 数瑞Web客户端，客户端中所有的数据处理和如何对处理后的数据进行渲染均来自合约调用，实现可信Web应用。
- **v0.78** 2020年4月13日
- 合约调用DAC示例
- 支持动态修改IO权限
- 支持合约状态自定义备份（定时）策略
- 修复部分页面bug
- 日志展示优化
- 优化账本日志展示
- 启用部分权限访问控制
- **v0.7** 2020年3月25日
- 支持多种角色的访问控制
- 更新了UI
- **v0.6** 2020年2月14日
- 优化了合约进程间的通讯
- 尝试接入P2P网络
- **v0.5** 2019年12月10日
- 完善了3种智能合约状态记录-回放策略
- 支持了最简单的多点执行算法（不同步）
- **v0.45** 2019年9月2日
- 初步实现PBFT算法
- **v0.4** 2019年5月10日
- 支持memory dump
- **v0.35** 2019年4月26日
- 实现合约的静态分析框架
- 支持事件的发布-订阅
- **v0.3** 2019年1月8日
- 支持账本数据的接入
- 合约状态上链
- **v0.2** 2018年10月9日
- 支持Python包的自动生成
- 支持合约打包为ypk
- 支持文件、数据库等数据的接入
- **v0.1** 2018年8月6日
- 定义了智能合约的语法
- 基于nashorn引擎，实现了智能合约的执行
--------------
使用开源项目说明
----------------
BDWareContract项目站在了许多巨人的肩膀上，感谢这些开源项目。
BDWare项目站在了许多巨人的肩膀上，感谢这些开源项目。
本项目的智能合约后端使用了以下开源库。

348
source/YJSAPI.rst
View File

@ -68,7 +68,7 @@ YJS Build-in API
}
发布事件 pubEvent
~~~~~~~~~~~~~~~~~
-----------------
参数
@ -86,7 +86,7 @@ YJS Build-in API
return "done";
}
也可以在合约开头声明事件，则事件名即为事件主题，此时可直接使用事件作为方法名发布事件
也可以在合约开头定义事件，则事件名即为事件主题，此时可直接使用事件作为方法名发布事件
.. code:: javascript
@ -98,55 +98,6 @@ YJS Build-in API
该写法与上面的\ ``pub1``\ 等价。
发布带语义事件 pubEventConstraint
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
参数
.. code:: bash
topic：字符串类型，发布的事件主题
content：字符串类型，发布的事件内容
semantics：枚举类型，作为字符串输入，事件语义
事件语义参数 + AT_LEAST_ONCE：至少一次，默认语义 +
AT_MOST_ONCE：至多一次 + ONLY_ONCE：只有一次
使用示例：
.. code:: javascript
export function pub1(arg) {
YancloudUtil.pubEventConstraint("topic", arg, "AT_MOST_ONCE");
return "done";
}
也可以在合约开头声明事件，则事件名即为事件主题，此时可直接使用事件作为方法名按声明的语义发布事件
.. code:: javascript
event AT_MOST_ONCE topic;
export function pub2(arg) {
topic(arg);
return "done";
}
该写法与上面的\ ``pub1``\ 等价。
事先声明的事件无论是否声明语义，都可以用后缀s作为方法名的方式调用，发布任意语义的事件：
.. code:: javascript
event topic;
export function pub3(arg) {
topics(arg, "AT_MOST_ONCE");
return "done";
}
该写法与上面的\ ``pub1, pub2``\ 等价。
*不带事件语义声明事件时，语义默认为至少一次（AT_LEAST_ONCE）。*
访问资源文件
~~~~~~~~~~~~
@ -182,30 +133,6 @@ loadAsScanner
var scanner = Global.Resources.loadAsScanner("/local.txt");
YancloudUtil
~~~~~~~~~~~~
提供了一些内置的工具方法。
getKeyPair
^^^^^^^^^^
参数：
::
无
使用示例：
::
var keyPair = YancloudUtil.getKeyPair();
//该类型为SM2KeyPair类型，
print(keyPair.getPublicKeyStr());
print(keyPair.getPrivateKeyStr());
print(keyPair.toJson());
YJS Build-in Annotation
-----------------------
@ -325,15 +252,13 @@ LogType注解通过参数的方式声明合约或函数的需要记录的日志
::
@integer 整数
@string 字符串
@boolean 布尔值
@date @time @datatime
@word 单词 @cword 中文单词
@first @last 英文姓，名
@cfirst @clast @cname 中文姓，名，全名
@url @domin @ip @email
@region @province @city @county 地区，省，市，县
@integer
@string
@boolean
@date
@time
@datatime
/[a-z][A-Z][0-9]/ （正则表达式）
……
详细格式可以参考http://mockjs.com/examples.html
@ -341,10 +266,20 @@ LogType注解通过参数的方式声明合约或函数的需要记录的日志
.. code:: json
//返回一个1-100之间的整数
@MockTemplate({'result|1-100':1})
//返回
{'result':76}
//返回一个1-5个数的数组
@MockTemplate({'result|1-5':[{'value|1-100':1}]})
//返回
{"result":[{"value":34},{"value":8},{"value":48},{"value":50},{"value":43}]}
//返回一个对象包含如下字段
@MockTemplate({'result':{'id':'@integer','email':'@email','password':'@string','name':'@name'}})
//返回
{"password":"3ZLc","name":"William Young","id":36097783842688,"email":"d.fuunwe@gqnr.to"}"
{"password":"3ZLc","name":"William Young","id":36097783842688,"email":"d.fuunwe@gqnr.to"}
//返回元素个数为1-5个之间的一个数组，数组的每个元素都是上述格式的一个对象
@ -374,6 +309,7 @@ LogType注解通过参数的方式声明合约或函数的需要记录的日志
~~~~~~~
该注解可以修饰\ ``function``\ 。
若没有模拟数据模板，则返回模拟数据时使用该注解的内容
提供函数的返回结果示例，若加此注解则生成说明文档时将直接返回此结果而不使用默认参数调用函数。
::
@ -390,16 +326,6 @@ LogType注解通过参数的方式声明合约或函数的需要记录的日志
return JSON.stringify(c);
}
@Cost
~~~~~
该注解可以修饰\ ``function``\ 。 提供函数的cpu计量功能。
::
@Cost({"countGas":true})
export function ....
IO工具类
--------
@ -1068,53 +994,22 @@ update
var digitalObject = JSON.parse("{\"doID\":\"86.5000.470/do.hello\",\"doBody\":\"hello world\"}");
var ret = DOIPUtil.update(digitalObject);
SQLUtil
~~~~~~~
MySQLUtil
~~~~~~~~~
可以使用@Permission(“SQL”)来引入SQLUtil对象。
可支持MySQL/PostgreSQL/Oracle/GuassDB200等SQL数据库。
需要将对应的jdbc的jar上传到项目中。
例如，要使用mysql，可上传mysql-connector-java-8.0.24.jar
可以使用@Permission(“MySQL”)来引入MySQLUtil对象。
::
@Permission("SQL")
oracle MySQLExample{
@Permission("MySQL")
contract MySQLExample{
...
}
initDriver
^^^^^^^^^^
.. _参数-21:
参数
''''
==== =========== ==========
序号 参数 说明
==== =========== ==========
1 driverClass 字符串类型
==== =========== ==========
.. _使用示例-22:
使用示例
''''''''
.. code:: javascript
//使用mysql
SQLUtil.initDriver("com.mysql.cj.jdbc.Driver");
//使用postgresql
SQLUtil.initDriver("org.postgresql.Driver");
//使用oracle
SQLUtil.initDriver("oracle.jdbc.OracleDriver");
getConnection
^^^^^^^^^^^^^
.. _参数-22:
.. _参数-21:
参数
''''
@ -1127,7 +1022,7 @@ getConnection
3 pwd 字符串类型，密码
==== ======= ====================
.. _使用示例-23:
.. _使用示例-22:
使用示例
''''''''
@ -1138,7 +1033,7 @@ getConnection
var usrName = "xxx";
var pwd = "xxx";
//配置好用户名和密码，url格式为ip或域名+端口，中间以”:”隔开。
var conn = SQLUtil.getConnection(url,usrName,pwd);
var conn = MySQLUtil.getConnection(url,usrName,pwd);
//获取数据库连接
var sql = "select * from newele.data";
//创建查询语句
@ -1176,7 +1071,7 @@ MongoDBUtil
getConnection
^^^^^^^^^^^^^
.. _参数-23:
.. _参数-22:
参数
''''
@ -1191,7 +1086,7 @@ getConnection
5 pwd 字符串类型 数据库的密码
==== ======= =========================
.. _使用示例-24:
.. _使用示例-23:
使用示例
''''''''
@ -1233,7 +1128,7 @@ loadDB
通过loadDB来加载一个RocksDB数据库。 加载后，可进行get/delete/put等操作。
.. _参数-24:
.. _参数-23:
参数
''''
@ -1245,7 +1140,7 @@ loadDB
2 readOnly 布尔类型 数据库只读
==== ======== ===========================
.. _使用示例-25:
.. _使用示例-24:
使用示例
''''''''
@ -1360,14 +1255,14 @@ generateKeyPair
生成公私钥。
.. _参数-25:
.. _参数-24:
参数
''''
无参数。
.. _使用示例-26:
.. _使用示例-25:
使用示例
''''''''
@ -1384,7 +1279,7 @@ sign
签名。
.. _参数-26:
.. _参数-25:
参数
''''
@ -1396,7 +1291,7 @@ sign
2 keyPair sm2
==== ======= ===========================
.. _使用示例-27:
.. _使用示例-26:
使用示例
''''''''
@ -1416,7 +1311,7 @@ verify
验签。
.. _参数-27:
.. _参数-26:
参数
''''
@ -1429,7 +1324,7 @@ verify
3 publicKey 字符串类型 公钥
==== ========= =======================
.. _使用示例-28:
.. _使用示例-27:
使用示例
''''''''
@ -1442,60 +1337,6 @@ verify
print(ret.status);
print(ret.result);
encrypt
^^^^^^^
sm2加密。
.. _参数-28:
参数
''''
==== ========= =======================
序号 参数 说明
==== ========= =======================
1 content 字符串类型 待验签的内容
3 publicKey 字符串类型 公钥
==== ========= =======================
.. _使用示例-29:
使用示例
''''''''
.. code:: javascript
var ret = SM2Util.encrypt("Hello","...公钥");
print(ret);
decrypt
^^^^^^^
sm2解密。
.. _参数-29:
参数
''''
==== ========== =======================
序号 参数 说明
==== ========== =======================
1 content 字符串类型 待验签的内容
3 privateKey 字符串类型 公钥
==== ========== =======================
.. _使用示例-30:
使用示例
''''''''
.. code:: javascript
var ret = SM2Util.decrypt("Hello","...私钥");
print(ret);
多线程工具类
------------
@ -1529,7 +1370,7 @@ AsyncUtil
postFunction
^^^^^^^^^^^^
.. _参数-30:
.. _参数-27:
参数
''''
@ -1541,7 +1382,7 @@ postFunction
2 arg1 对象
==== ==== ==============
.. _使用示例-31:
.. _使用示例-28:
使用示例
''''''''
@ -1553,7 +1394,7 @@ postFunction
setInterval
^^^^^^^^^^^
.. _参数-31:
.. _参数-28:
参数
''''
@ -1567,7 +1408,7 @@ setInterval
4 arg3 对象
==== ==== ==============
.. _使用示例-32:
.. _使用示例-29:
使用示例
''''''''
@ -1579,7 +1420,7 @@ setInterval
setTimeOut
^^^^^^^^^^
.. _参数-32:
.. _参数-29:
参数
''''
@ -1592,7 +1433,7 @@ setTimeOut
3 arg2 Object
==== ==== ==============
.. _使用示例-33:
.. _使用示例-30:
使用示例
''''''''
@ -1604,7 +1445,7 @@ setTimeOut
sleep
^^^^^
.. _参数-33:
.. _参数-30:
参数
''''
@ -1615,7 +1456,7 @@ sleep
1 arg0 long
==== ==== ====
.. _使用示例-34:
.. _使用示例-31:
使用示例
''''''''
@ -1642,98 +1483,3 @@ YJS支持ECMAScript6的部分内置对象 ：
- Error https://www.w3schools.com/js/js_errors.asp
- JSON https://www.w3schools.com/js/js_json.asp
YJS应用框架
-----------
ypk项目组成
~~~~~~~~~~~
如之前描述，ypk中可存放静态资源文件（html/css/js)，在智能合约中声明loadResource方法，可返回静态资源文件。
基于loadResource，本项目提供了一个yjs应用框架。
该框架可以将合约ypk中的(html/css/js)文件通过executeContract调用，加载至前端并展示。
函数约定
~~~~~~~~
==== ============ ======================================================
序号 合约函数名 说明
==== ============ ======================================================
1 needRender 不会被调用，有该函数表示需要渲染前端
2 getMainFrame 无参数，返回结果为String类型，表示主页的html文件路径
3 loadResource 参数为String，以文本形式，返回相对路径下的静态资源文件
==== ============ ======================================================
加载流程
~~~~~~~~
前端加载的参数会解析至global.urlparam。 包括以下参数：
::
//global.urlparam对象示例
{
"contract":"TrustedStorage0899", //表示合约ID或是合约的名称
"keys":{ //表示当前登录者的密钥对
"privateKey":"ff38dd04710...",
"publicKey":"04fc228..."
},
"nodeAddr":"022.node.internetapi.cn:21030" //节点的ip+端口
}
加载前会先建立与nodeAddr的websocket连接。 连接建立后，加载流程分为两步：
第一步是用当前的publickey-privatekey登录。登录过程详见\ ``BDContract SDK``
的 ``合约节点WebSocket接口`` 登录之后，会获取合约的信息。
并存放于global.currentContract对象。
第二步，是根据global.currentContract对象中，是否有needRender方法，
如果有，就会进入加载前端代码的流程。
具体为1.执行executeCurrentContract(“getMainFrame”)
获取页面的html，append至mainDIV之后，
会解析所有\ ``<script>``,\ ``<link>``\ 等标签。2.会以标签中的\ ``fromContract``\ 属性，去调用executeCurrentContract(“loadResources”)方法。
典型的yjs的loadResources方法如下。3.获取所有script会进行eval,link会当css加载。
::
//在某个yjs文件中声明。
export function loadResource(arg){
return Global.Resources.loadAsString(arg);
}
.. figure:: ./_static/imgs/clientLoadProcess.png
:alt: 前端加载流程图
前端加载流程图
前端框架预置函数说明
~~~~~~~~~~~~~~~~~~~~
前端的javascript在html中已加载了jquery(使用$.)和vue2。
为避免冲突，本版不支持再加载vue2/vue3脚本。
前端通过executeContract/executeCurrentContract与后端交互。
executeContract
^^^^^^^^^^^^^^^
调用某个合约的某个函数。会自动使用当前的global.sm2Key进行签名。参数说明及示例：
.. code:: javascript
executeContract(contracID,operation,arg,callback);
//其中，contractID为string类型，为被调用的合约名称/合约ID。
//operation为string类型，合约函数
//arg为string类型，表示参数
//callback为函数类型，接受返回结果的回调函数。
executeCurrentContract
^^^^^^^^^^^^^^^^^^^^^^
执行当前合约的某个函数。会自动使用当前的global.sm2Key进行签名。参数说明及示例：
.. code:: javascript
executeContract(operation,arg,callback);
//operation为string类型，合约函数
//arg为string类型，表示参数
//callback为函数类型，接受返回结果的回调函数。

0
source/_template/versions.html → source/_templates/versions.html
View File

28
source/conf.py
View File

@ -16,13 +16,14 @@
# -- Project information -----------------------------------------------------
project = '智融云河大数据区块链'
copyright = '2021, ZRYH'
author = 'ZRYH'
project = '北大数瑞大数据区块链'
copyright = '2021, Peking University'
author = 'Peking University'
# The full version, including alpha/beta/rc tags
release = 'V1.0'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
@ -30,9 +31,9 @@ release = 'V1.0'
# ones.
html_theme = "sphinx_rtd_theme"
html_logo = "_static/imgs/logo.png"
html_logo="_static/imgs/logo.png"
html_theme_options = {
'logo_only': True
'logo_only': True
}
source_parsers = {
@ -48,9 +49,10 @@ source_suffix = ['.rst', '.md']
# }
extensions = [
'recommonmark',
'sphinx_rtd_theme',
'sphinx_markdown_tables'
'recommonmark',
'sphinx_rtd_theme',
'sphinx_markdown_tables',
'sphinx_multiversion'
]
html_favicon = "_static/imgs/favicon.ico"
@ -64,17 +66,25 @@ templates_path = ['_templates']
# Usually you set "language" from the command line for these cases.
language = 'zh_CN'
html_sidebars = {
'**': [
'versioning.html',
],
}
smv_latest_version = 'master'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
# html_theme = 'alabaster'
#html_theme = 'alabaster'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,

2
toRst.sh
View File

@ -29,4 +29,4 @@ pandoc ${src}/YJSAPI.md -f markdown -t rst -o YJSAPI.rst
pandoc ${src}/YJSInDepth.md -f markdown -t rst -o YJSInDepth.rst
cd ..
make clean
make html
#make html