區(qū)塊鏈可裝配系統(tǒng)模塊編程接口規(guī)范

1區(qū)塊鏈可裝配系統(tǒng)模塊編程接口規(guī)范本文件主要內(nèi)容包括：a）規(guī)定了可裝配區(qū)塊鏈各模塊的最小接口集合；b）規(guī)定了可裝配區(qū)塊鏈各模塊的各個接口的具體功能。本文件適用于：a）指導(dǎo)區(qū)塊鏈服務(wù)提供方進行各模塊的具體開發(fā)工作；b）指導(dǎo)對可裝配區(qū)塊鏈各模塊具體實現(xiàn)進行評估。2規(guī)范性引用文件下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，僅該日期對應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。T/CESA6001-2016區(qū)塊鏈參考架構(gòu)T/CESAxxxx區(qū)塊鏈可裝配系統(tǒng)裝配規(guī)范T/CESAxxxx區(qū)塊鏈可裝配系統(tǒng)流程規(guī)范3術(shù)語和定義T/CESA6001-2016，T/CESAxxxx和T/CESAxxxx界定的術(shù)語和定義適用于本文件。3.1區(qū)塊block區(qū)塊鏈中存儲交易和交易相關(guān)的數(shù)據(jù)的單元，通常由區(qū)塊頭和區(qū)塊體組成。3.2區(qū)塊頭blockhead應(yīng)包含當前區(qū)塊的屬性信息和鏈接信息。屬性信息通常包括時間戳、區(qū)塊版本等。鏈接信息通常包括能唯一標識前一個區(qū)塊特征的哈希值和能唯一標識區(qū)塊體特征的哈希值。3.3區(qū)塊體blockbody區(qū)塊中存儲交易和交易相關(guān)的數(shù)據(jù)的主要部分。23.4交易transaction也稱為事務(wù)，區(qū)塊鏈上的一次原子性賬本數(shù)據(jù)狀態(tài)變更及其過程和結(jié)果記錄,。3.5讀寫集read-writeset區(qū)塊鏈上的一條交易執(zhí)行過程中，被讀取和被修改或?qū)懭氲臓顟B(tài)數(shù)據(jù)的集合。3.6交易快照transactionsnapshot記錄區(qū)塊鏈某一高度的狀態(tài)數(shù)據(jù)集合。4接口描述4.1交易緩存模塊接口4.1.1數(shù)據(jù)類型定義組件類型Transaction為復(fù)合類型，描述一條交易。其包括：contractId合約ID字段method調(diào)用合約的方法parameters交易參數(shù)refTxType，交易類型其余內(nèi)容可依據(jù)區(qū)塊鏈場景或應(yīng)用需求進行定義。組件類型TxSource為枚舉類型，描述交易來源?？扇≈禐椋篟PC服務(wù)接收端口P2PP2P廣播INTERNAL內(nèi)部4.1.2交易緩存接口繼承：無屬性：無方法：anyAddTx(inTransactiontx,inTxSourcesource)說明：增加一條交易。參數(shù)：tx為需加入緩存的交易，source為交易來源。返回：錯誤對象。sequence<*Transaction>FetchTxBatch(inshortblockHeight);說明：獲取供打包的一批交易。參數(shù)：blockHeight為區(qū)塊高度。返回：一批交易。anyRemoveTxs(sequence<*Transaction>removeTxs);3說明：移除已打包過的一批交易。參數(shù)：removeTxs為要移除的交易集合。返回：錯誤對象。4.2區(qū)塊提議模塊接口4.2.1數(shù)據(jù)類型定義組件類型TxPoolSignal為復(fù)合類型，描述交換緩存提議信號結(jié)構(gòu)。其包含：signalType信號類型chainTag鏈標識4.2.2區(qū)塊提議接口繼承：無屬性：無方法：TxPoolSignal(in*TxPoolSignalproposeSignal);說明：響應(yīng)來自交易緩存模塊的區(qū)塊提議信號，進行打包規(guī)則驗證，通過后執(zhí)行打包操作。參數(shù)：proposeSignal為從交易緩存模塊接收到的區(qū)塊提議信號。返回：無。ProposeStatusChange(inbooleanproposeStatus);說明：處理來自共識算法模塊的區(qū)塊提議狀態(tài)通知。參數(shù)：proposeStatus為是否進入?yún)^(qū)塊提議狀態(tài)。返回：無。4.3交易調(diào)度模塊接口4.3.1數(shù)據(jù)類型定義組件類型Block為復(fù)合類型，描述區(qū)塊結(jié)構(gòu)，其包括：header區(qū)塊頭Transactions交易集組件類型Snapshot為復(fù)合類型，區(qū)塊鏈交易快照保存只讀的世界狀態(tài)數(shù)據(jù)，其包括：status世界狀態(tài)數(shù)據(jù)。4.3.2交易調(diào)度接口繼承：無屬性：無方法：anySchedule(in*Blockb,insequence<*Transaction>txBatch,inSnapshotsnapshot);說明：調(diào)度交易的執(zhí)行，并修改候選區(qū)塊，由區(qū)塊提議模塊調(diào)用。4參數(shù)：b為候選區(qū)塊（已含部分字段txBatch為待調(diào)度執(zhí)行的一批交易，snapshot為交易快返回：結(jié)果讀寫集，錯誤對象。anySimulateWithDag(in*Blockb,inSnapshotsnapshot);說明：參照候選區(qū)塊里的DAG，按序驗證執(zhí)行其中的交易，由區(qū)塊驗證模塊調(diào)用。參數(shù)：b為候選區(qū)塊，snapshot為交易快照。返回：結(jié)果讀寫集，錯誤對象。anyGetRWSet(in*Blockb);說明：返回讀寫集。參數(shù)：b為區(qū)塊。返回：讀寫集，錯誤對象。4.4智能合約模塊接口4.4.1數(shù)據(jù)類型定義組件類型ContractId為復(fù)合類型，合約標識結(jié)構(gòu)，其包括：name合約名稱version合約版本openv合約運行環(huán)境組件類型TxSimContext為any類型。交易執(zhí)行上下文，用于緩存交易讀寫集。組件類型TxType為枚舉類型，描述交易類型，取值可為：USERINVOKE用戶合約調(diào)用USERQUERY用戶合約查詢組件類型ContractResult為復(fù)合類型，描述合約執(zhí)行結(jié)果，其包括：responseCode結(jié)果返回碼message返回消息result結(jié)果數(shù)據(jù)resource資源消耗4.4.2智能合約接口繼承：無屬性：無方法：*ContractResultRunContract(in*ContractIdcid,instringmethod,insequence<octet>byteCode,inmap<string,string>parameters,inTxSimContexttxContext,inlonggasUsed,inTxTyperefTxType)說明：運行合約以執(zhí)行交易驗證。參數(shù)：cid為合約ID，method為調(diào)用的合約方法，byteCode為合約字節(jié)碼，parameters為交易參數(shù)，txContext為上下文，gasUsed為資源消耗量，refTxType為交易類型。其中，cid、method、parameters和refTxType來自一條交易，byteCode和txContext來自鏈上，gasUsed來自字節(jié)碼命令集的計算。5返回：交易驗證結(jié)果。4.5共識算法模塊接口4.5.1數(shù)據(jù)類型定義組件類型NetMsg為復(fù)合類型，描述網(wǎng)絡(luò)消息結(jié)構(gòu)，其包括：messageType消息類型message交易消息體targetNodeID目標節(jié)點標識4.5.2共識算法接口繼承：無屬性：無方法：OnProposedBlock(in*Blockb);說明：響應(yīng)來自區(qū)塊提議模塊的通知，對候選區(qū)塊進行共識。共識時須驗證提議節(jié)點和候選區(qū)塊的合法性，并在共識節(jié)點間執(zhí)行共識算法。參數(shù)：b為候選區(qū)塊。返回：無。ConsensusMsg(in*NetMsgnmsg);說明：處理對等網(wǎng)絡(luò)模塊發(fā)來的消息。參數(shù)：nmsg為共識消息。返回：無。4.6對等網(wǎng)絡(luò)模塊接口4.6.1數(shù)據(jù)類型定義消息類型NetMsg_MsgType為枚舉類型，取值可為：TRANSACTION_MESSAGE交易消息BLOCK_MESSAGE區(qū)塊消息CONSENSUS_MESSAGE共識消息4.6.2對等網(wǎng)絡(luò)接口繼承：無。屬性：無。方法：errorBroadcastMsg(insequence<octet>msg,inNetMsg_MsgTypemsgType)說明：將消息（交易）廣播到網(wǎng)絡(luò)中所有節(jié)點。參數(shù)：msg為要廣播的消息字節(jié)數(shù)組，msgType為消息類型。6返回：錯誤對象。errorConsensusBroadcastMsg(insequence<octet>msg,inNetMsg_MsgTypemsgType)說明：將消息（區(qū)塊）廣播給共識節(jié)點。參數(shù)：msg為要廣播的消息字節(jié)數(shù)組，msgType為消息類型。返回：錯誤對象。errorOnReceiveNetMsg(instringfrom,in*NetMsgnmsg,inNetMsg_MsgTypemsgType)說明：接收來自共識算法模塊或?qū)Φ染W(wǎng)絡(luò)模塊的消息。參數(shù)：from為消息來源，nmsg為消息內(nèi)容，msgType為消息類型。返回：錯誤對象。4.7區(qū)塊驗證模塊接口4.7.1數(shù)據(jù)類型定義候選區(qū)塊驗證類型VerifyMode為枚舉類型，取值可為：CONSENSUS_VERIFY_MODE共識驗證模式SYNC_VERIFY_MODE同步驗證模式4.7.2區(qū)塊驗證接口繼承：無。屬性：無。方法：errorVerifyBlock(in*Blockbb,inVerifyModemode)說明：候選區(qū)塊合法性驗證。參數(shù)：b為要驗證的候選區(qū)塊，mode為驗證模式。返回：錯誤對象。4.8區(qū)塊執(zhí)行模塊接口4.8.1區(qū)塊執(zhí)行接口繼承：無。屬性：無。方法：errorAddBlock(in*Blockbb)說明：將已共識區(qū)塊寫入數(shù)據(jù)存儲模塊，并清理交易緩存模塊中對應(yīng)的交易集。參數(shù)：b為已共識的區(qū)塊。返回：錯誤對象。4.9數(shù)據(jù)存儲模塊接口4.9.1數(shù)據(jù)存儲接口繼承：無。屬性：無。方法：errorPutBlock(in*Blockb,insequence<*TxRWSet>txRWSets)說明：保存區(qū)塊和對應(yīng)讀寫集，并保證事務(wù)原子性。參數(shù)：b為要保存的區(qū)塊，txRWSets為一組交易讀寫集。返回：錯誤對象。anyGetBlock(inlongblockHeight)說明：讀取區(qū)塊。參數(shù)：blockHeight為區(qū)塊高度。返回：讀到的區(qū)塊對象，錯誤對象。anyGetTx(instringtxId)說明：讀取交易。參數(shù)：txId為交易標識。返回：讀到的交易對象，錯誤對象。anyReadObject(instringcontractName,insequence<octet>key)說明：讀取賬本上指定合約數(shù)據(jù)項的最新世界狀態(tài)。參數(shù)：contractName為合約名稱，key為數(shù)據(jù)項關(guān)鍵字。返回：世界狀態(tài)數(shù)據(jù)，錯誤對象。4.10數(shù)據(jù)快照模塊接口4.10.1數(shù)據(jù)快照接口繼承：無。屬性：無。方法：anyGetKey(inlongtxExecSeq,instringcontractName,insequence<octet>key)說明：讀取快照。參數(shù)：txExecSeq為交易執(zhí)行序號，constractName為合約名稱，key為關(guān)鍵字。返回：快照數(shù)據(jù)，錯誤對象。4.11加密組件庫接口4.11.1數(shù)據(jù)類型定義組件類型KeyType為枚舉類型，密鑰類型，可取值為：SM4、AES、SM2、RSA1024、RSA2048、ECC_Secp256k1、ECC_Ed25519、ECC_NISTP256等組件類型PrivateKey為any類型，私鑰組件類型HashType為枚舉類型，哈希算法類型，可取值為：SM3、SHA256、SHA3_256等4.11.2加密組件庫接口8繼承：無。屬性：無。方法：anySign(insequence<octet>data)說明：私鑰簽名。參數(shù)：data為待簽數(shù)據(jù)。返回：簽名，錯誤對象。anyVerify(insequence<octet>data,insequence<octet>sig)說明：簽名驗證。參數(shù)：data為待驗數(shù)據(jù)，sig為簽名。返回：是否通過驗簽，錯誤對象。anyGenerateKeyPair(inKeyTypektype)說明：生成非對稱密鑰。參數(shù)：kType為密鑰類型。返回：私鑰，錯誤對象。anyHash(insequence<octet>data,inHashTypehtype)說明：生成哈希。參數(shù)：data為原始數(shù)據(jù),hType為哈希類別。返回：哈希數(shù)據(jù)，錯誤對象。4.12身份和權(quán)限管理模塊接口4.12.1數(shù)據(jù)類型定義組件類型EndorsementEntry為復(fù)合類型，描述背書信息，其包括：signerIdentity簽名者標識message簽名信息4.12.2身份和權(quán)限管理接口繼承：無。屬性：無。方法：anyCreatePrincipal(instringresourceName,insequence<EndorsementEntry*>endorsements,insequence<octet>message)說明：為一次性授權(quán)創(chuàng)建規(guī)則。參數(shù)：resourceName為資源名稱，endorsements為背書列表，message為消息。返回：新建規(guī)則，錯誤對象。anyVerifyPrincipal(inPrincipalprin)說明：驗證規(guī)則是否匹配資源的使用策略。參數(shù)：prin為規(guī)則。返回：是否匹配，錯誤對象。4.13調(diào)參模塊接口4.13.1數(shù)據(jù)類型定義組件類型ChainConfig為any類型，描述鏈配置參數(shù)4.13.2調(diào)參接口繼承：無。屬性：無。方法：ChainConfig*ChainConfig()說明：獲取鏈的最新配置。參數(shù)：無。返回：最新配置。errorCompleteBlock(Block*b)說明：區(qū)塊插入數(shù)據(jù)庫后的回調(diào)函數(shù)，更新鏈的配置。參數(shù)：b為區(qū)塊。返回：錯誤對象。4.14跨鏈模塊接口4.14.1數(shù)據(jù)類型定義組件類型srcChain為字符串類型，表示源鏈標識組件類型srcTxId為字符串類型，表示原鏈交易編號組件類型srcTxData為字節(jié)數(shù)組類型，表示原鏈交易信息組件類型dstChain為字符串類型，表示目標鏈標識組件類型dstTxId為字符串類型，表示目標鏈交易編號組件類型dstTxData為字節(jié)數(shù)組類型，表示目標鏈交易信息組件類型XTransaction為復(fù)合類型，定義跨鏈交易結(jié)構(gòu)，其包括：srcTxIdsrcTxDatadstChaindstTxIddstTxData定義如上定義如上定義如上定義如上定義如上4.14.2跨鏈接口繼承：無。屬性：無。方法：errorProposeXTransaction(instringxid,inXTransactiondata)說明：提議一個跨鏈交易。參數(shù)：xid為跨鏈交易標識，data為跨鏈交易數(shù)據(jù)。返回：錯誤對象。errorXAction(instringfrom,instringtxId,inXTransactiondata)說明：跨鏈交易執(zhí)行。參數(shù)：提議鏈標識，提議鏈交易標識，data為跨鏈交易數(shù)據(jù)。返回：錯誤對象。（資料性）各模塊接口定義示例A.1txcache.idlmoduletx_cache{typedefanyerror;//交易結(jié)構(gòu)typedefstruct{longcontractId;stringmethod;stringparameters;shortrefTxType;}Transaction;//本模塊定義接口interfaceITxCache;//交易緩存模塊接口interfaceITxCache{//交易來源enumTxSource{RPC,P2P,INTERNAL,//增加一條交易errorAddTx(inTransactiontx,inTxSourcesource);//獲取供打包的一批交易sequence<*Transaction>FetchTxBatch(inshortblockHeight);//移除已打包過的一批交易errorRemoveTxs(insequence<*Transaction>removeTxs);}}A.2blockproposal.idlmoduleblock_proposal{//信號類型//交換緩存提議信號結(jié)構(gòu)typedefenum{ISEMPTY,UNTHRESHOLD,THRESHOLD,}SignalType;typedefstruct{SignalTypesignaltype;stringchainTag;}TxPoolSignal;//本模塊定義接口interfaceIBlockProposal//區(qū)塊提議模塊接口interfaceIBlockProposal{//響應(yīng)來自交易緩存模塊的區(qū)塊提議信號，進行打包規(guī)則驗證，通過后執(zhí)行打包操作。TxPoolSignal(in*TxPoolSignalproposeSignal);//處理來自共識算法模塊的區(qū)塊提議狀態(tài)通知ProposeStatusChange(inbooleanproposeStatus);}}A.3txschedule.idl#include"txcache.idl"moduletx_schedule{typedeftx_cache::TransactionTransactiontypedefanyTxRWSet;//交換緩存提議信號結(jié)構(gòu)typedefstruct{stringheader;sequence<Transaction>Transactions;}Block;//區(qū)塊鏈交易快照typedefstruct{readonlyanystatus;}Snapshot;//本模塊定義接口interfaceITxSchedule;//交易調(diào)度模塊接口interfaceITxSchedule{//調(diào)度交易的執(zhí)行anySchedule(in*Blockb,insequence<*Transaction>txBatch,inSnapshotsnapshot);//參照候選區(qū)塊里的DAG，按序驗證執(zhí)行其中的交易anySimulateWithDag(in*Blockb,inSnapshotsnapshot);//返回讀寫集anyGetRWSet(in*Blockb);}}A.4smartcontract.idlmodulesmart_contract{//合約標識結(jié)構(gòu)體typedefstruct{stringname;stringversion;anyopenv;}ContractId;//交易執(zhí)行上下文typedefanyTxSimContext;//交易類型enumTxType{USERINVOKE,USERQUERY,//合約執(zhí)行結(jié)果typedefstruct{anyresponseCode;anymessage;anyresult;anyresource;}ContractResult;//本模塊定義接口interfaceISmartContract;//智能合約模塊接口interfaceISmartContract{//運行合約以執(zhí)行交易驗證*ContractResultRunContract(in*ContractIdcid,instringmethod,insequence<octet>byteCode,inmap<string,string>parameters,inTxSimContexttxContext,inlonggasUsed,inTxTyperefTxType);}}A.5consensus.idl#include"txschedule.idl"moduleconsensus{typedeftx_schedule::BlockBlock;//網(wǎng)絡(luò)消息結(jié)構(gòu)typedefstruct{stringmessageType;anymessage;anytargetNodeID;}NetMsg;//本模塊定義接口interfaceIConsensus;//共識算法模塊接口interfaceIConsensus{//響應(yīng)來自區(qū)塊提議模塊的通知OnProposedBlock(in*Blockb);//處理對等網(wǎng)絡(luò)模塊發(fā)來的消息ConsensusMsg(in*NetMsgmsg);}}A.6peernetwork.idl//peernetwork.idlmodulepeer_network{typedefanyNetMsg;//消息類型enumNetMsg_MsgType{//交易消息TRANSACTION_MESSAGE,//區(qū)塊消息BLOCK_MESSAGE,//共識消息CONSENSUS_MESSAGE//本模塊定義的接口interfaceIPeerNetwork;//對等網(wǎng)絡(luò)接口interfaceIPeerNetwork{//將消息（交易）廣播到網(wǎng)絡(luò)中所有節(jié)點errorBroadcastMsg(insequence<octet>msg,inNetMsg_MsgTypemsgType);//將消息（區(qū)塊）廣播給共識節(jié)點errorConsensusBroadcastMsg(insequence<octet>msg,inNetMsg_MsgTypemsgType)//接收來自共識算法模塊或?qū)Φ染W(wǎng)絡(luò)模塊的消息errorOnReceiveNetMsg(instringfrom,in*NetMsgnmsg,inNetMsg_MsgTypemsgType)A.7blockverify.idl#include"txschedule.idl"http://blockverify.idlModuleblock_verify{typedeftx_schedule::BlockBlock;//候選區(qū)塊驗證類型enumVerifyMode{//共識驗證模式CONSENSUS_VERIFY_MODE,//同步驗證模式SYNC_VERIFY_MODE//本模塊定義的接口interfaceIBlockVerify;//區(qū)塊驗證接口interfaceIBlockVerify{//候選區(qū)塊合法性驗證errorVerifyBlock(in*Blockb,inVerifyModemode);A.8blockexec.idl#include"txschedule.idl"http://blockexec.idlModuleblock_exec{typedeftx_schedule::BlockBlock;//本模塊定義的接口interfaceIBlockExec;//區(qū)塊執(zhí)行接口interfaceIBlockExec{//將已共識區(qū)塊寫入數(shù)據(jù)存儲模塊，并清理交易緩存模塊中對應(yīng)的交易集errorAddBlock(in*Blockb);A.9datastore.idl#include"txschedule.idl"http://datastore.idlModuledata_store{typedeftx_schedule::BlockBlock;typedefanyTxRWSet;//本模塊定義的接口interfaceIDataStore;//數(shù)據(jù)存儲接口interfaceIDataStore{//保存區(qū)塊和對應(yīng)讀寫集，并保證事務(wù)原子性errorPutBlock(in*Blockb,insequence<*TxRWSet>txRWSets);//讀取區(qū)塊anyGetBlock(inlongtxId);//讀取交易anyGetTx(instringtxId);//讀取賬本上指定合約數(shù)據(jù)項的最新世界狀態(tài)anyReadObject(instringcontractName,insequence<octet>key);A.10datasnapshot.idl//datasnapshot.idlModuledata_snapshot{//本模塊定義的接口interfaceIDataSnapshot;//數(shù)據(jù)快照接口InterfaceIDataSnapshot{anyGetKey(inlongtxExecSeq,insequence<octet>key);A.11encrypt.idlmoduleencrypt{//數(shù)據(jù)類型定義//私鑰typedefanyPrivateKey;//模塊接口定義interfaceIEncrypt;//加密組件接口interfaceIEncrypt{//秘鑰類型，枚舉類型，包括：SM4、AES、SM2、RSA1024、RSA2048、//ECC_Secp256k1、ECC_Ed25519、ECC_NISTP256等enumKeyType{SM4,AES,SM2,RSA1024,RSA2048,ECC_Secp256k1,ECC_Ed25519,ECC_NTSTP256//哈希算法類型，枚舉類型，包括：SM3、SHA256、SHA3_256等enumHashType{SM3,SHA256,SHA3_256}//私鑰簽名anySign(insequence<octet>data);//簽名驗簽anyVerify(insequence<octet>data,insequence<octet>sig);//生成非對稱密鑰anyGenerateKeyPair(inKeyTypektype);//生成哈希anyHash(insequence<octet>data,inHashTypehtype);}}moduleidentify{//數(shù)據(jù)類型定義//背書信息，有其他機構(gòu)或個人確認的信息，通常為數(shù)字簽名形式。//包括：簽名者標識、簽名信息typedefstruct{anysignerIdentity;anymessage;}EndorsementEntry;//規(guī)則對象typedefanyPrincipal;//模塊接口定義interfaceIIdentity;//身份與權(quán)限管理接口interfaceIIdentity{//為一次性授權(quán)創(chuàng)建規(guī)則anyCreatePrincipal(instringresourceName,insequence<*Endors