Merge pull request #68 from hyperchain/csw/docs

Csw/docs

docs/en/make.bat

@@ -1,36 +1,36 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=python -msphinx
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-set SPHINXPROJ=hyperchain
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
-	echo.then set the SPHINXBUILD environment variable to point to the full
-	echo.path of the 'sphinx-build' executable. Alternatively you may add the
-	echo.Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=hyperchain
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/zh_CN/Architecture development.rst

@@ -0,0 +1,30 @@
+大规模组网
+^^^^^^^^^^^^^^
+
+随着联盟规模不断扩大，多样化业务模式不断扩展，传统的对等网络已经无法满足应用需求。比如在工业互联网、物联网场景中，传统的对等网络模式难以支撑海量终端设备接入区块链，混合式分层级的新型组网模型才能更好的应对这种大规模终端接入的应用场景。
+
+基于上述问题，平台相应提出大规模分层组网模型, 通过分层架构设计，有效实现整体网络节点水平扩展，并提供实时计算与验证服务，实现数十万级不同类型网络节点的大规模部署。层级结构如下所示：
+
+|image0|
+
+- **共识节点层** ：由VP（Validation Peer）组成，该层级节点全部参与共识，负责区块链网络的共识验证与账本一致性保证。
+- **非共识节点层** ：由NVP（Non-Validation Peer）组成，同步共识节点账本数据，不参与共识，并通过网络自发现转发模型实现大规模NVP节点组网，实现区块链数据网络水平扩展。
+- **轻节点层** ：包含微数据中心、IOT网关等，靠近边缘设备终端，提供轻量级的计算功能，具备数据缓存以及本地计算的能力，将各种边缘设备与区块链网络桥接起来，赋予边缘计算能力，提高数据的处理效率，降低整体响应延迟。
+- **终端设备层** ：包括感知器、通信模组、摄像头等各类IOT设备，负责数据采集与转发上链，解决数据真实性的“第一公里”问题。
+
+非共识节点（NVP）
+-----------------
+
+在数据新基建的大潮流下，随着人民链、星火链网、BSN等国家级区块链平台的相继推出，未来区块链需要支撑的应用场景规模将会越来越大，这势必会带来性能与扩展性的矛盾。试想如果区块链网络中都为共识节点，一方面，网络复杂度的增加对网络连通性和稳定性提出了更高的要求，但在真实落地场景中，出于网络安全和建设成本的考虑理想化的网络环境往往很难实现；另一方面，共识节点的数量增加会导致共识效率的降低，从而拖慢系统的整体性能。针对这些问题，趣链区块链平台通过非共识节点NVP提供了一种新的解题思路。
+
+NVP定位于轻量级服务节点，不参与共识，仅通过信任的VP来同步账本数据，并对外提供交易转发、查询等服务。NVP拥有完善的数据恢复机制，当由于网络异常等原因导致节点落后时，能及时同步数据，恢复到最新的账本状态，提高了节点的可用性。此外，NVP提供的区块链服务是独立于VP的，除了交易上链、查询、验证等基础功能外，还支持数据索引、数据归档、可信文件存储、接口权限管理等功能，适应更加多样化的应用场景。趣链区块链平台支持一个VP连接多个NVP，用户可选择同步VP的全量账本数据或某个NS的账本数据，同步范围灵活可配。
+
+NVP适用于多种应用场景：
+
+- 针对数据低频写、高度读的存证类场景，机构内部可在VP的基础上再增设NVP，将一部分数据读压力转移到NVP上，让VP专注于数据写入，通过读写分离来分担VP压力，实现区块链系统的高效运行。
+- 针对大规模、分层级、跨区域的国家级基础设施类场景，下属机构或中小型企业可用NVP替代VP，从平台角度考虑，一方面减轻了共识网络的压力，在保证性能的提前下提高了区块链网络的可扩展性，另一方面网络复杂度的降低也更利于平台落地；从机构及企业角度考虑，在满足业务需求的同时也降低了设备及运维成本。
+- 针对海量终端设备接入的城市级物联网场景，以共识节点层为中心，通过NVP非共识节点层实现数据网络的扩展，优化分摊系统压力。
+
+
+
+.. |image0| image:: ../../images/massive1.png

docs/zh_CN/Data management.rst

@@ -0,0 +1,60 @@
+数据管理
+^^^^^^^^^^^^^
+
+数据归档
+-------------
+
+随着区块链运行时间的增长，区块链系统存储的数据容量将高速增长，且数据的增长的速度甚至会超过存储介质容量增长的速度，从而限制区块链技术的发展。为此，平台实现了区块链数据归档，在不停机的情况下，将一部分线上数据迁移到线下存储。以此解决在有限存储空间下区块链数据的存储问题。平台也提供归档数据浏览器，支持用户查阅归档数据。平台也实现了归档数据恢复的功能，在不影响链上正常工作的情况下，支持运维人员将线下存储的数据恢复至线上。
+
+数据归档针对的主体是区块数据，同时包括区块对应的日志数据、索引数据、交易回执数据。平台支持用户自定义归档范围，用户可以直接指定一个已经被提交的区块号作为参数，创世区块到入参区块的数据将被归档至线下。另外，考虑到直接归档的流程较为耗时，直接归档的请求返回和归档流程将异步进行，用户可通过查询归档结果的接口查询归档是否成功。数据归档功能支持各节点自主定义归档范围，节点间无需同步归档。数据归档对区块链的变化如下图所示:
+
+|image0|
+
+数据索引
+-----------
+
+数据查询是区块链应用中最普遍的场景，但由于区块链独特的账本结构，一直以来都缺少一种高效安全的查询手段。
+
+区块链底层的账本数据以Key-Value键值对模型进行存储，目前只能提供基于key 的精确检索，而在实际应用场景存在更广泛的基于value（业务数据）的检索需求。比如在商品溯源场景中，我们可能要通过商品ID来检索出该商品在整个流通过程中的交易，受限于区块链底层数据的存储特点，只能通过遍历区块的方式来检索，效率十分低下。为了提高检索效率，目前有两种解决思路，一种是将商品ID到交易哈希的映射关系存储在外部数据库当中，但数据安全难以得到有效保障；另一种是将映射关系存储在智能合约中，但随着数据量增大，合约会遇到性能瓶颈，检索效率依然难以得到提升。
+
+为了解决上述问题，平台依托底层索引数据库，从区块中提取关键信息存储到索引数据库中，实现高效安全的业务数据自定义条件检索功能，极大简化了上层业务系统开发和维护复杂度。平台采用内嵌式索引数据库，保证检索结果可信的同时，极大提升了业务数据的检索效率，检索速度达毫秒级。为了更加贴合实际使用场景，平台支持自定义多条业务索引信息，满足更加精准的检索需求，同时支持精准、匹配（模糊）、多条件查询等多种检索模式，并支持大数据量分页查询，避免出现查询接口OOM问题。
+
+|image1|
+
+数据索引的应用十分广泛，特别是在查询频繁的存证类场景中。以茶品溯源场景为例，当茶品溯源平台将茶品采摘、加工、质检、物流、销售流程中的相关信息以交易的形式上链存证时，用户可在交易的ExtraID字段中输入茶品批次、类型、原产地、经销地点等自定义索引信息，这些索引信息将存储在底层专用索引数据库当中。随后，用户可调用相应接口，通过精确检索模式查询某一批次编号的产品全流程交易信息，或通过多条件检索模式查询云南产普洱茶的交易信息。
+
+可信文件共享
+---------------
+
+中心化的文件存储与共享存在易篡改、低可信、单点故障等问题，而区块链因其可信任、安全不可篡改、冗余备份、多方协作等特性在文件可信存储与共享方面具有天然的优势，但目前区块链对于商业化文件存储与共享存在成本高、容量小、性能差、结构单一等问题，具体表现在：
+
+- 文件容量大导致系统性能下降。目前的区块链技术架构，大容量的文本、文件由每个节点全量直接链上存储不仅需要消耗大量的存储资源，还会严重影响平台性能，无法满足商业场景的需求。
+
+- 链上存储结构单一。区块链的存储结构对结构化文件友好，但不适于图片、音视频等非结构化文件的直接存储，无法适应涉及大量非结构化文件的应用场景。
+
+为此，平台通过自研可信文件共享功能，通过链上存证、链下传输的文件分离存储模型，实现了文件可信存储、安全共享与高效查询。在保证平台性能和稳定性不受影响的情况下，能支持GB级别图片、音视频等非结构化文件的可信存储，并通过区块链网络定向流传输共享。向用户提供节点白名单和用户白名单，支持用户多维度自定义授权存储节点与用户下载权限，允许用户按需查询、下载文件，有效降低链上非结构性文件存储与共享的成本并增强可用性、可控性。可信文件共享由一方上传文件，多方同步文件索引信息、定向共享文件，功能示意图如下所示：
+
+|image2|
+
+可信数据源服务
+----------------
+
+在中国人民银行发布的《区块链能做什么？不能做什么？》的报告中，预言机定义如下：区块链外信息写入区块链内的机制，一般被成为预言机。预言机解决的是链外数据不可信、不确定而导致不可用的问题，由于区块链对于用户来说是一个黑盒，只了解输入和输出但不知晓内部的细节，系统内部为了满一致性要求，需保持合约运行结果的一致性和确定性，但如Web天气服务、航班动态信息、随机数等都是变化的数据，区块链想使用这些动态变化的数据就需要预言机。预言机作为区块链和外部世界的桥梁，通过可信计算技术以及建立信任的约束机制，让区块链系统打破了封闭，使区块链主动获取外部数据成为现实。
+
+预言机使用过程中首先需要事先部署oracle合约，负责与预言机服务交互，用户编写自己的用户合约去调用oracle合约对外部预言机合约请求数据，预言机服务向外部请求数据再将数据返回给oracle合约，最终返回给用户合约触发合约执行逻辑（详见下图预言机示例）。
+
+|image3|
+
+对于数据源获取：Oracle预言机可以从外部引入世界状态的信息，包括网站数据、传感器采集数据、随机数、跨链数据等实时、动态、可变的数据；     
+
+对于预言机服务：平台支持硬件TEE可信以及软件可信“双可信”预言机服务，保证预言机服务在数据处理，数据传输过程中的真实可信；
+
+对于数据安全：支持HTTPS、TLS等安全传输协议，保证数据传输过程中防篡改且真实性可查验。
+
+
+
+
+.. |image0| image:: ../../images/data1.png
+.. |image1| image:: ../../images/data2.png
+.. |image2| image:: ../../images/data3.png
+.. |image3| image:: ../../images/data4.png

docs/zh_CN/Ecological components.rst

@@ -0,0 +1,59 @@
+区块链生态组件
+^^^^^^^^^^^^^^^
+
+多语言SDK
+------------
+
+SDK作为与趣链区块链平台交互的工具，是上层应用和区块链平台连接的桥梁。SDK功能强大，用户不仅可以通过SDK快速访问区块链、开发合约编写业务逻辑，还可以通过SDK进行用户管理、事件订阅以及灵活配置。通常，SDK会提供外部API接口，将应用给出的参数进行封装、加密、签名等，形成http请求后发送给平台，平台收到请求后返回结果，然后SDK对返回的结果进行解析，返回给上层，形成上层应用与区块链一个完整的交互流程。为适应不同语言开发工程师管理区块链平台，平台具有多语言SDK支持，如JavaSDK、GoSDK、JSSDK、CSDK、C#SDK等，优先推荐使用JavaSDK。目前的SDK架构具有完成的功能接口支以及灵活易用的工具支持。
+
+|image0|
+
+SDK整体架构主要分为基本架构和扩展工具两大部分。基本架构可以支持完备高效的主流程操作，包括账户证书管理、合约部署调用、区块交易查询、数据编解码以及安全网络通讯，来进行合约开发的一系列工作；工具支持是基于SDK基本架构构建的一个完备的系统生态，对证书、日志级别、网络协议进行灵活的配置，支持合约、查询、日志、异常管理等基本工具，为了方便用户区块链数据的查询和管理，SDK提供了数据归档、消息订阅以及外部数据源等扩展功能，总而言之，SDK可以满足用户对区块链操作的各种需求。
+
+Archive-Reader浏览器
+----------------------
+
+当数据完成归档后，此部分数据将无法在区块链上查阅，因此平台提供了Archive-Reader浏览器用于查阅归档数据。该浏览器无需与区块链部署在同一服务器上，用户可在独立的服务器上运行Archive-Reader浏览器，并导入相关归档数据即可开始查阅。同时，Archive-Reader浏览器支持包括数据索引功能在内的快速数据检索服务。由此，平台实现了归档数据持续可查、灵活查阅的高易用性。
+
+消息订阅
+---------
+
+趣链区块链平台作为一个“共享状态”的区块链实现，其运转通过不断的状态变迁实现。每一次状态变迁，都会产生相应的一系列事件作为本次状态变迁的标志。
+
+为了方便外部业务系统捕获、监听区块链的状态变化，我们提供了消息订阅功能，现已支持rabbit MQ和KafKa双模式。外部可以监听到的事件类型包括：
+
+- **区块事件** ：每产生新的区块都将主动向订阅者推送最新区块信息；
+- **合约事件** ：合约相关的事件触发（比如合约上账户余额变动）将会向订阅者推送消息；
+- **交易事件** ：写入区块的交易的交易体与交易回执都会主动推送给订阅者；
+- **系统异常事件** ：当平台有异常抛出或者系统状态改变的时候，便会向订阅者主动推送消息。
+
+为保障消息推送内容及推送顺序的正确性，平台将在区块链达到共识稳定点前，将上一共识稳定点至今的待推送消息进行临时存储。当区块链达到共识稳定点后，将对待推送消息按区块顺序进行排序，并按顺序对外推送消息，保障了用户接收到的消息内容及顺序的正确性。
+
+HyperBench测试框架
+----------------------
+
+HyperBench是趣链科技自主研发的通用的区块链性能测试框架，支持趣链区块链平台、Fabric等主流联盟链性能测试。用户可自定义测试场景针对配置好的区块链网络进行性能测试，获取一系列的测试结果并生成测试报告，主要分为交易发送、数据统计、资源监控、报告生成四大功能。
+
+1.交易发送
+
+交易发送包括测试环境配置、测试用例设计、交易封装发送、受测平台适配四个步骤。
+
+- 测试环境配置：用户可通过测试参数配置以及平台连接配置自定义压力测试的环境。其中，测试参数配置主要涉及配置文件中各参数的设置，平台连接配置指对测试时的底层适配器进行配置。
+- 受测平台适配：性能测试框架只提供适配接口，受测平台在Hyperbench提供的统一SDK接口基础上，继承类Blockchain并重写相应方法进行底层适配。
+
+2.数据统计
+
+本地化数据统计，记录交易执行过程中系统各类型数据，压测结束之后，在visual/index.html页面有压测过程中统计的数据，可用浏览器打开进行可视化查阅（默认是关闭数据统计的，需要在配置文件中开启）。
+
+3.资源监控
+
+在区块链系统中植入资源监控的功能，对服务器进行资源、用量指标的监控和采样。
+
+4.报告生成
+
+性能测试框架在按照设定的测试时长正常退出之后会自动生成一份测试报告。报告分成Overview和Details两个部分。Overview中会记录测试的总体数据，并且大致展示压测交易的执行情况。Details会展示一些本地的总体统计数据，系统根据调用的函数名进行聚合统计。
+
+5.HyperBench 白皮书
+https://upload.hyperchain.cn/HyperBench%E7%99%BD%E7%9A%AE%E4%B9%A6.pdf
+
+.. |image0| image:: ../../images/ecological1.png