Merge pull request #493 from WeBankBlockchain/lab-dev

updat warehouse v3
WeBankBlockchain · Sep 26, 2022 · aba6a76 · aba6a76
2 parents 19b4622 + 4ce376a
commit aba6a76
Show file tree

Hide file tree

Showing 12 changed files with 905 additions and 1 deletion.
diff --git a/docs/WeBASE-Contract-Warehouse/Asset/BAC002.md b/docs/WeBASE-Contract-Warehouse/Asset/BAC002.md
@@ -0,0 +1,153 @@
+# 资产合约
+
+# BAC002 合约规范
+
+## 简介
+ BAC002 是区块链上定义非同质化资产的一种标准，可以用于唯一性资产类型，如房产、汽车、道具、版权等。，并可以做相应增发，销毁，暂停合约，黑白名单等权限控制。
+## 三个基本元素
+- description
+
+  资产的具体描述
+
+- shortName
+
+  资产简称
+
+- assetId
+
+  资产编号
+
+ ## 五个基本行为
+- 发行
+
+  调用合约的 deploy 方法，传入 description 和 shortName，即在区块链上发行指定名称的资产
+
+- 转账
+
+  调用 safeSendFrom 方法实现转账，调用 balance 方法可以查看自己的资产数量
+
+- 增发
+
+  调用 issueWithAssetURI 方法向资产地址增发指定资产编号和资产描述链接信息的资产。另外，可以通过 addIssuer 增加 有权限增发资产的人，也可以通过 renounceIssuer 方法移除增发权限
+
+- 销毁
+
+  调用 destroy 以及 destroyFrom 销毁自己地址下资产和特定地址下的资产
+
+- 暂停
+
+  遇到紧急状况，你可以调用 suspend 方法，暂停合约，这样任何人都不能调用 send 函数。故障修复后，可以调用 unSuspend 方法解除暂停。也可以通过 addSuspender 和 renounceSuspender 相应增加和移除暂停者权限
+
+
+## 接口说明
+
+- <b>shortName()</b>
+
+  资产简称
+
+- <b>description()</b>
+
+  资产描述
+
+- <b>balance(address owner)</b>
+
+  返回 owner 的资产总数
+
+- <b>totalSupply()</b>
+
+  获得当前合约总的资产数目
+
+- <b>ownerOf(uint256 assetId)</b>
+
+  返回资产持有者的地址
+
+- <b>approve(address to, uint256 assetId)</b>
+
+  授予地址to具有指定资产的控制权
+
+  - 此方法配合 getapproved 使用
+
+- <b>getApproved(uint256 assetId)</b>
+
+  获得资产授权的地址用户
+
+  - 此方法配合 approve 使用，注意不要配合 setapprovealforall 方法使用
+
+- <b>setApprovalForAll(address operator, bool approved)</b>
+
+  授予地址operator具有自己所有资产的控制权
+
+- <b>isApprovedForAll(address owner, address operator)</b>
+
+  查询授权
+
+- <b>sendFrom(address from, address to, uint256 assetId, bytes memory data)</b>
+
+  安全转账，防止你转到错误的合约地址 ( to如果是合约地址，必须实现接收接口 BAC002Holder 才可以接收转账 )，并可以带转账备注
+
+  - suspend 状态下无法执行此操作
+
+- <b>batchSendFrom(address from, address[] to, uint256[] assetId, bytes memory data)</b>
+
+  批量安全转账
+
+  - suspend 状态下无法执行此操作
+  - to 数组元素个数需要和 assetid 数组元素个数一致
+
+- <b>issueWithAssetURI(address to, uint256 assetId, string memory assetURI, bytes data)</b>
+
+  给地址 to 创建资产 assetId，data 是转账备注, assetURI  资产描述
+
+- <b>isIssuer(address account)</b>
+
+  检查account是否有增加资产的权限
+
+- <b>addIssuer(address account)</b>
+
+  使地址 account 拥有增加资产的权限
+
+- <b>renounceIssuer()</b>
+
+  移除增加资产的权限
+
+- <b>suspend()</b>
+
+  暂停合约
+
+  - suspend 后无法进行 safesendfrom / sendfrom / safeBatchSendFrom 操作
+
+- <b>unSuspend()</b>
+
+  重启合约
+
+  - 此方法配合 suspend 使用
+
+- <b>isSuspender(address account)</b>
+
+  是否有暂停合约权限
+
+  - 此方法配合  addsuspender 使用
+
+- <b>addSuspender(address account)</b>
+
+  增加暂停权限者
+
+  - 此方法配合 renouncesuspender / issuspender 放啊发使用
+
+- <b>renounceSuspender()</b>
+
+  移除暂停权限
+
+- <b>destroy(uint256 assetId, bytes data)</b>
+
+  减少自己的资产，data 是转账备注
+
+  - 调用时，value 值需要小于等于目前自己的资产总量
+
+- <b>assetOfOwnerByIndex(address owner, uint256 index)</b>
+
+  根据索引 index 获取 owner 的资产 ID
+
+- <b>assetByIndex(uint256 index)</b>
+
+  根据索引  index 获取当前合约的资产 ID
diff --git a/docs/WeBASE-Contract-Warehouse/Evidence/SmartDev-Evidence.md b/docs/WeBASE-Contract-Warehouse/Evidence/SmartDev-Evidence.md
@@ -0,0 +1,11 @@
+# Evidence存证
+
+## 简介
+
+存证操作，上传、审批、修改、删除等，详情查看[Smart-Dev Evidence Doc](https://toolkit-doc.readthedocs.io/zh_CN/latest/docs/WeBankBlockchain-SmartDev-Contract/api/business_template/Evidence.html)
+
+合约：
+1) EvidenceController 对外服务的唯一接口
+2) EvidenceRepository 辅助合约，用于数据和逻辑分离
+3) RequestRepository 辅助合约，用于数据和逻辑分离
+4) Authentication 辅助合约，用于数据和逻辑分离
diff --git a/docs/WeBASE-Contract-Warehouse/Proxy/Proxy.md b/docs/WeBASE-Contract-Warehouse/Proxy/Proxy.md
@@ -0,0 +1,52 @@
+# 代理合约模板
+
+本合约模板由深圳前海股权交易中心基于合约迭代升级的需要，研发合约应用开源实现参考，并基于拥抱开源的理念贡献给社区，包括合约接口层代理、合约数据层代理等主要功能。
+
+本合约模板社区贡献者：
+[xiaomdong]https://github.com/xiaomdong
+
+## 简介
+本合约模板由深圳前海股权交易中心贡献，针对数据上链编写的通用代理存储合约。
+
+代理合约利用solidity的fallback功能，包含EnrollProxy（代理合约），EnrollController（业务合约），EnrollStorage（存储合约）。
+
+- 代理合约对外交互接口
+- 业务合约实现业务逻辑
+- 存储合约完成数据存储
+
+EnrollProxy合约通过Fallback机制调用EnrollController合约的函数进行数据上链（通过EnrollProxy合约地址结合使用EnrollController合约的ABI，操作EnrollController合约的函数），其带来的优点包括：
+
+- 区块链应用的业务层只与EnrollProxy合约进行交互，EnrollProxy合约不会升级，地址不会变化。
+
+- 后续中业务或存储需求导致业务合约或存储合约需要升级，则升级EnrollController和EnrollStorage合约，达到数据、业务逻辑解耦的效果。
+
+*期待你一起完善合约模板中的权限控制逻辑*
+
+## 合约架构说明
+
+```java
+EnrollProxy
+        继承EnrollStorageStateful
+        继承Proxy（继承Ownable）　
+
+EnrollController
+        继承EnrollStorageStateful
+        继承Ownable
+
+EnrollStorageStateful
+        包含成员enrollStorage，EnrollStorage合约实例
+
+由于是继承的关系，EnrollProxy合约和EnrollController合约的存储空间排列是一样的，所以可通过EnrollProxy执行fallback操作。  
+
+enrollStorage是EnrollStorageStateful合约中的成员，所以enrollStorage合约与EnrollStorageStateful合约存储空间排布是不一样。
+```
+
+## 使用说明
+1. 编译部署EnrollProxy，EnrollController，EnrollStorage合约。
+2. 配置代理合约：
+   1. 存储合约合约：调用EnrollProxy合约setStorage函数，参数为EnrollStorage合约地址。
+   2. 配置业务合约：调用EnrollProxy合约upgradeTo函数，参数为：合约版本号，EnrollController合约地址。
+3. 设置存储合约的代理地址：调用EnrollStorage合约setProxy函数，参数为EnrollProxy合约地址。
+
+
+完成以上步骤后，就可以通过EnrollProxy合约地址，结合业务合约EnrollController合约的ABI，操作EnrollController合约的业务函数。
diff --git a/docs/WeBASE-Contract-Warehouse/Trace/Trace.md b/docs/WeBASE-Contract-Warehouse/Trace/Trace.md
@@ -0,0 +1,14 @@
+# 溯源合约模板
+本合约模板由世纪鼎利科技股份有限公司基于家禽溯源场景，贡献合约应用开源实现参考，包括种类注册、家禽注册、状态变更、溯源查询等主要合约功能。
+
+本合约模板社区贡献者：
+[fengqiao]https://github.com/fengqiao
+
+## 简介
+
+包含创建Traceability溯源类目、创建Goods溯源商品、更新溯源/商品状态、获取溯源/商品信息等
+
+合约：
+1) Goods 溯源商品
+2) Traceability 商品溯源类目
+3) TraceabilityFactory 溯源工厂类
diff --git a/docs/WeBASE-Contract-Warehouse/index.md b/docs/WeBASE-Contract-Warehouse/index.md
@@ -2,20 +2,29 @@
 
 合约仓库内置于[WeBASE-Front](../WeBASE-Install/developer.html)与[WeBASE管理平台](../WeBASE-Console-Suit/index.html)中。其中提供常用的工具合约和推荐应用合约模板，用户可将合约导入到自己目录进行引入。
 
-  ![](./contract.png)
+  <!-- ![](./contract.png) -->
+![](../../images/WeBASE/contract-warehouse/contract_warehouse.png)
 
 ## 合约仓库贡献者
 
 | 贡献者名称 | github账号 | 贡献工程 |
 | ---------- | ---------- | ---------- |
 |  刘明臻   |  https://github.com/mingzhenliu  |  存证合约仓库  |
 |  肖东    |  https://github.com/xiaomdong  |  代理合约仓库  |
+|  枫桥    |  https://github.com/fengqiao |  溯源合约仓库  |
+|  WeBASE    |  https://github.com/WeBankBlockchain/WeBASE  |  积分合约仓库  |
+|  WeBASE    |  https://github.com/WeBankBlockchain/WeBASE  |  资产合约仓库  |
+|  WeBankBlockchain-SmartDev    |  https://github.com/WeBankBlockchain/WeBankBlockchain-SmartDev  |  SmartDev存证合约仓库  |
 
 ```eval_rst
 .. toctree::
    :maxdepth: 1
 
    ./tools/index.md
    ./Evidence/Evidence.md
+   ./Proxy/Proxy.md
+   ./Trace/Trace.md
+   ./Asset/BAC002.md
    ./Points/BAC001.md
+   ./Evidence/SmartDev-Evidence.md
 ```
diff --git a/docs/WeBASE-Training-Class/index.md b/docs/WeBASE-Training-Class/index.md
@@ -0,0 +1,15 @@
+# WeBASE实训课程案例
+
+WeBASE智能合约的实训课程案例集，可结合WeBASE完成实训课程与题目设计。
+
+
+```eval_rst
+.. toctree::
+   :maxdepth: 1
+
+   ./index.md
+   ./training/01-HelloWorld.md
+   ./training/02-Transfer.md
+   ./training/03-Evidence.md
+
+```