diff --git a/README.md b/README.md index 81ee9a664..426f687e8 100644 --- a/README.md +++ b/README.md @@ -79,9 +79,9 @@ For public blockchain, you must prepare some gas for transaction fee in advance. For consortium blockchain , you must consult the administrator to give you access permission on the blockchain. Or you may deploy your own consortium blockchain node for test purpose. See blockchain official website for details: -For [Ethereum](https://ethereum.org/) -For [Ganache: an Ethereum Simulator](https://www.trufflesuite.com/truffle/) -For [PlatON Enterprise](https://github.com/PlatONEnterprise/) ++ [Ethereum](https://ethereum.org/) ++ [Ganache: an Ethereum Simulator](https://www.trufflesuite.com/truffle/) ++ [PlatON Enterprise](https://github.com/PlatONEnterprise/) #### Deploy the smart contract The smart contracts used in the demo locate in ./contract. diff --git a/SUPPORTED_LIST.md b/SUPPORTED_LIST.md index be45e331e..f2fec5949 100644 --- a/SUPPORTED_LIST.md +++ b/SUPPORTED_LIST.md @@ -31,8 +31,9 @@ BF2 |跃昉LeapFive |WiFi |LeapFive B SLM320 |美格 MEIG |LTE Cat.1 |UNISOC UIS8910DM Yanfei CUIoT-MZ-6 |联通 China Unicom|LTE Cat.1 |UNISOC UIS8910DM MN316 |中移物联 China Mobile|NB-IoT |Xinyi XY1100 +BeagleV-StarLight星光 |seeed, StarFive and beagleboard|Ethernet|StarFive JH7100 |BeagleV-StarLight星光 is a development board -*Last update on April 4th, 2021* +*Last update on June 29th, 2021* NOTE: Some of the blockchains are not supported on some modules due to resource constraint. diff --git a/docs/en-us/BoAT_Overall_Design_en.md b/docs/en-us/BoAT_Overall_Design_en.md index c3e2e83c6..e198ab303 100644 --- a/docs/en-us/BoAT_Overall_Design_en.md +++ b/docs/en-us/BoAT_Overall_Design_en.md @@ -8,7 +8,7 @@ This article describes the overall design of the BoAT system, including architec The intended readers of this article are: BoAT SDK detailed designers. -### Abbreviated terms +### Abbreviated Terms |Term |Explanation | |:----- |:--------------------------- | |ABI |Application Binary Interface | @@ -19,7 +19,7 @@ The intended readers of this article are: BoAT SDK detailed designers. |TEE |Trusted Execution Environment| -## BoAT design goals +## BoAT Design Goals As a middleware of the IoT blockchain, BoAT should be easily and quickly transplanted to various IoT modules with minimal changes，The design of BoAT follows the following goals: + Hierarchical design + Multiple blockchain protocols are supported @@ -28,18 +28,18 @@ As a middleware of the IoT blockchain, BoAT should be easily and quickly transpl + Provide corresponding C language interface contract automatic generation tools for different blockchains -## The position of BoAT SDK in the entire blockchain network +## The Position of BoAT SDK in The Entire Blockchain Network As a middleware connecting IoT devices and blockchain, BoAT SDK's position in the entire interactive network is shown in Figure 3-1.
![BoAT position](./images/BoAT_Overall_Design_en-F3-1-Boat_Position.png)
Figure 3-1 The position of BoAT in the blockchain interactive network
-## BoAT implementation framework +## BoAT Implementation Framework BoAT follows a hierarchical design, which is divided into interface layer, protocol layer, RPC layer, hardware dependency layer, general tools and utility programs. among them: -+ The interface provided by the interface layer is for users to call to access the corresponding blockchain. -+ The protocol layer provides services to the interface layer. -+ The RPC layer provides services to the protocol layer. ++ The interface provided by the interface layer is for users to access the corresponding blockchain. ++ The protocol layer provides blockchain adpatation services to the interface layer. ++ The RPC layer provides remote process call services to the protocol layer. + The hardware dependency layer provides encryption, signature, storage and other services for the wallet at the interface layer. + The general tool layer is used to generate the C language interface of the smart contract and provide services such as data encoding and format conversion for the remaining layers. + The utility program provides services such as data format conversion, message encoding and decoding to each layer. @@ -47,7 +47,7 @@ The overall framework of BoAT is shown in Figure 4-1.
![BoAT overall framework diagram](./images/BoAT_Overall_Design_en-F4-1-BoAT_Overall_Framework_Diagram.png)
Figure 4-1 BoAT overall framework diagram
-### Interface layer +### Interface Layer #### Overview The interface layer is located at the top layer of BoAT and provides users with access to each blockchain. The interface layer consists of two parts: @@ -59,14 +59,14 @@ The interface layer is located at the top layer of BoAT and provides users with The wallet interface of the interface layer is supported by the hardware dependent layer. For the description of the hardware dependent layer, please refer to [Hardware dependency layer](#Hardware-dependency-layer). The transaction interface of the interface layer is supported by the protocol layer. For a description of the protocol layer, please refer to [Protocol layer](#Protocol-layer). -#### Wallet interface +#### Wallet Interface -##### The data structure and function implementation list of the wallet +##### The Data Structure and Function Implementation List of The Wallet The wallet is a container. In addition to storing the information necessary to access the blockchain, the container also contains a key management system, which corresponds to the data structure and implementation method of the wallet. -The BoAT SDK runs on the application processor of the cellular module, and the resources of its operating environment are limited. For example, some cellular modules may not provide non-volatile memory access interfaces; on the other hand,From the user's point of view, some users may just want to create a temporary wallet for testing, but don't want to store it for a long time.In view of this, in the design of BoAT SDK, wallets are divided into two categories: persistent wallets and one-time wallets. Persistent wallets are stored in the non-volatile memory of the operating environment and will not be lost when power is off; one-time wallets are stored in the RAM of the operating environment and will be lost when power is off. +The BoAT SDK runs on the application processor of the cellular module, and the resources of its operating environment are limited. For example, some cellular modules may not provide non-volatile memory access interfaces; on the other hand, from the user's point of view, some users may just want to create a temporary wallet for testing, but don't want to store it for a long time. In view of this, in the design of BoAT SDK, wallets are divided into two categories: persistent wallets and one-time wallets. Persistent wallets are stored in the non-volatile memory of the operating environment and will not be lost when power is off; one-time wallets are stored in the RAM of the operating environment and will be lost when power is off. -In the data structure of the wallet,It should contain at least the following elements: +In the data structure of the wallet, It should contain at least the following elements: + Account private key + Blockchain network information + RPC interface information @@ -79,20 +79,20 @@ The wallet should provide the following functions to achieve: + SDK de-initialization + Wallet creation + Delete wallet - + Wallet uninstall + + Wallet uninstalls + Query wallet information according to the index + Private key settings + Private key generation + Private key verification -##### Brief description of wallet interface function realization +##### Brief Description of Wallet Interface Function Realization -###### SDK initialization / de-initialization +###### SDK Initialization / De-initialization + SDK initialization: SDK initialization should be done before using BoAT SDK. The contents of this interface include: 1. Initialization of wallet list -The wallet list is a data structure that contains a fixed number of wallets and wallet-related usage information. The wallet-related usage information includes wallet usage identification, wallet name, and blockchain to which the wallet belongs.The wallet list is a global resource. The initialization of the wallet list means that each member in the data structure is initialized once, such as initializing the use identifier as unused, and initializing the wallet as a null pointer. +The wallet list is a data structure that contains a fixed number of wallets and wallet-related usage information. The wallet-related usage information includes wallet usage identification, wallet name, and blockchain to which the wallet belongs. The wallet list is a global resource. The initialization of the wallet list means that each member in the data structure is initialized once, such as initializing the use identifier as unused, and initializing the wallet as a null pointer. 2. Other global resource initialization If some third-party libraries used by the SDK need to be initialized before calling, they should be initialized here, such as the third-party library cURL used by the RPC layer. @@ -102,7 +102,7 @@ After using BoAT SDK, you should do SDK de-initialization to release resources. 2. Other global resource de-initialization If some third-party libraries used by the SDK need to be de-initialized before being called, they should be placed here for de-initialization, such as the third-party library cURL used by the RPC layer -###### Wallet operation +###### Wallet Operation + Wallet creation: This interface is used to realize the creation of a new wallet or the reading of an already created wallet. The contents of this interface include: @@ -115,14 +115,14 @@ This interface deletes a persistent wallet from non-volatile memory. Note: This interface does not uninstall the wallet from RAM. After the persistent wallet is deleted, it becomes a one-time wallet. The content implemented by this interface includes: 1. Delete the specified wallet file from the non-volatile memory + Unload wallet: -This interface is used to unload a wallet from RAM. +This interface is used to unloads a wallet from RAM. Note: This interface only unload the wallet from RAM and does not delete the wallet from non-volatile memory. The content implemented by this interface includes: 1. Perform wallet de-initialization of a certain blockchain according to specific input parameters, such as performing Ethereum wallet de-initialization, or performing PlatONE wallet de-initialization + Query wallet information according to the index: This interface is used to query the wallet. The content implemented by this interface includes: 1. Return the corresponding wallet information address according to the specific input parameters (input parameters can be storage serial number index value, wallet address, etc.) -###### Private key operation +###### Private Key Operation + Private key settings: This interface is used to set the private key of the wallet. The private key should be kept carefully. The content implemented by this interface includes: @@ -140,9 +140,9 @@ This interface is used to generate a valid private key. The content implemented This interface is used to check whether the given private key is valid. The content implemented by this interface includes: 1. Check whether the private key is in the valid private key range -#### Transaction interface +#### Transaction Interface -##### Transaction data structure and function realization list +##### Transaction Data Structure and Function Realization List A transaction is a signed message, transmitted through the blockchain network, and recorded on the blockchain. The functions of transaction interfaces provided by different blockchains are basically the same. For Ethereum/PlatONE/FISCO BCOS: @@ -163,7 +163,7 @@ The transaction should provide the following functions: -##### Brief description of Ethereum transaction interface function implementation +##### Brief Description of Ethereum Transaction Interface Function Implementation + Wallet initialization: The content implemented by this interface includes: 1. Set the blockchain contract address @@ -179,7 +179,7 @@ The transaction should provide the following functions: 1. Prepare message information required for account balance inquiry 2. Call the web3 interface provided by the protocol layer: get the account balance + Transaction initialization: - This interface is mainly implemented to initialize the fields in the transaction structure. In addition to the three fields of signature v, r, and s, the transaction structure of Ethereum also has six fields including nonce, gasPrice, gasLimit, recipient, value, and data.Please note that the setting of the Nonce field of the transaction is not implemented in this interface, but is set at the time the transaction is sent, because the user may create multiple transaction messages at the same time, and the order in which these messages are sent to the blockchain network is not sure. In addition, it should be noted that the Nonce and gasPrice fields should be obtained from the blockchain by calling the corresponding web3 interface of the protocol layer. This method requires access to the network and will generate a certain amount of network traffic. The content implemented by this interface includes: + This interface is mainly implemented to initialize the fields in the transaction structure. In addition to the three fields of signature v, r, and s, the transaction structure of Ethereum also has six fields including nonce, gasPrice, gasLimit, recipient, value, and data. Please note that the setting of the Nonce field of the transaction is not implemented in this interface, but is set at the time the transaction is sent, because the user may create multiple transaction messages at the same time, and the order in which these messages are sent to the blockchain network is not sure. In addition, it should be noted that the Nonce and gasPrice fields should be obtained from the blockchain by calling the corresponding web3 interface of the protocol layer. This method requires access to the network and will generate a certain amount of network traffic. The content implemented by this interface includes: 1. Set the GasPrice field of the transaction 2. Set the GasLimit field of the transaction 3. Set the Recipient field of the transaction @@ -205,7 +205,7 @@ The transaction should provide the following functions: 1. Prepare message information needed for stateless message call 2. Call the web3 interface "blockchain stateless call" provided by the protocol layer -##### Brief description of PlatONE transaction interface function implementation +##### Brief Description of PlatONE Transaction Interface Function Implementation Compared with Ethereum, the differences are listed below: + Transaction initialization In addition to the initialization steps described by Ethereum, PlatONE also: @@ -217,11 +217,11 @@ It can be seen from the foregoing that the difference between PlatONE and Ethere Figure 4-2 A possible design idea of data structure
Figure 4-2 describes a possible data structure design idea of PlatONE. Please note that the transaction type field of PlatONE should be placed at the end of the data structure, and the integrity of the data structure of the multiplexed Ethereum should not be destroyed. If the integrity of the data structure of Ethereum is destroyed, the implementation methods related to the data structure in Ethereum will not be reused. -##### Brief description of PlatONE transaction interface function implementation +##### Brief Description of PlatONE Transaction Interface Function Implementation Compared with Ethereum, the differences are listed below: @todo -##### Brief description of Fabric transaction interface function implementation +##### Brief Description of Fabric Transaction Interface Function Implementation + Wallet initialization: The content implemented by this interface includes: 1. Request space for the wallet structure. @@ -229,7 +229,7 @@ Compared with Ethereum, the differences are listed below: 3. Set up the certificate of the account. 4. If you need to support TLS, set the root certificate to be used when TLS verifies the identity of the server. 5. If TLS needs to support two-way authentication, the client's private key path/index and corresponding certificate should also be set. - 6. Set node information, such as endorsement node and sorting node numbers, address, host name.If TLS is enabled, the hostname field will be used to authenticate the server's identity, which is the same as the CN field in the server's TLS certificate.If TLS is not enabled, the host name is ignored. + 6. Set node information, such as endorsement node and sorting node numbers, address, host name. If TLS is enabled, the hostname field will be used to authenticate the server's identity, which is the same as the CN field in the server's TLS certificate. If TLS is not enabled, the host name is ignored. 7. Initialize the HTTP2 environment. + Wallet de-initialization: The content implemented by this interface includes: @@ -237,7 +237,7 @@ Compared with Ethereum, the differences are listed below: 2. Free the space applied for TLS client private key path/index and certificate (if TLS is enabled). 3. Free the space applied for the root certificate (if TLS is enabled). 4. Free the space applied for endorsement/sorting node information. - 5. Uninitialize the HTTP2 environment. + 5. Uninitialized the HTTP2 environment. 6. Free the space applied for the wallet structure. + Transaction initialization: The content implemented by this interface includes: @@ -258,20 +258,20 @@ Compared with Ethereum, the differences are listed below: 1. Send the submit messages. 2. Send the evaluate messages. -### Protocol layer +### Protocol Layer #### Overview The protocol layer is located in the second layer of the BoAT SDK, which mainly implements the protocol part of each blockchain. For Ethereum series blockchains, their protocols are very similar, such as Ethereum and PlatONE. The protocol layer is supported by the RPC layer. Please refer to [Protocol layer](#Protocol-layer). -#### Ethereum's protocol layer implementation -##### raw transaction interface +#### Ethereum's Protocol Layer Implementation +##### Raw Transaction Interface The raw transaction interface of the protocol layer provides services for "sending transactions" to the transaction interface of the interface layer.Raw transaction upwards should provide at least the following interfaces: + raw transaction sent asynchronously In addition, raw transaction can also choose to provide the following interfaces: + raw transaction sent synchronously -##### Brief description of raw transaction interface +##### Brief Description of Raw Transaction Interface + raw transaction sent asynchronously This interface implements the data encoding of raw transaction, such as RLP encoding of each field, hash calculation, signature, etc., and calls the web3 interface within the protocol layer to send it to the blockchain, and returns directly without waiting for the transaction be confirmed. Data encoding is divided into two parts: incompatible with EIP-155 specification and compatible with EIP-155 specification. The content implemented by this interface includes: @@ -296,7 +296,7 @@ This interface executes "raw transaction asynchronous sending" and waits for the 2. Execute query transaction receipt 3. Wait for the transaction to be confirmed or return after timeout -##### web3 interface +##### Web3 Interface In addition to the raw transaction interface, the protocol layer should also provide the following web3 interfaces to the upper layer: + web3 interface initialization + web3 interface de-initialization @@ -310,93 +310,94 @@ In addition to the raw transaction interface, the protocol layer should also pro Looking through the RPC-related documents of Ethereum, you can know that Ethereum provides about 64 RPC methods. In the BoAT SDK, we only implement the above. The reason is the same as the description in [Wallet interface](#Wallet-interface). The resources of the SDK operating environment are limited. The above-mentioned RPC methods are several methods commonly used in data on the blockchain. If customers need other RPC methods in the future, BoAT SDK will provide them in a customized way. -##### Brief description of web3 interface +##### Brief Description of Web3 Interface + web3 interface initialization The content implemented by this interface includes: - 1. Web3 interface resource application,Such as the memory space application of RPC content,Application for the memory space of the json string used to request or respond from the blockchain,Request for memory space of the parsed result of the response json string + 1. Web3 interface resource application, Such as the memory space application of RPC content, Application for the memory space of the json string used to request or respond from the blockchain, Request for memory space of the parsed result of the response json string 2. Initialize web3 message ID 3. Perform "RPC interface initialization" of the RPC layer + web3 interface de-initialization The content implemented by this interface includes: - 1. The release of web3 interface resources, such as the release of memory space for RPC content,It is used to release the memory space of the json string that requests or responds from the blockchain,The memory space of the parsed result of the response json string is released. + 1. The release of web3 interface resources, such as the release of memory space for RPC content,It is used to release the memory space of the json string that requests or responds from the blockchain, The memory space of the parsed result of the response json string is released. 2. Perform "RPC interface de-initialization" of the RPC layer + Get the content stored in the specified location of the blockchain The content implemented by this interface includes: 1. web3 message ID increment - 2. Package the request message of "Get the content stored in the specified location of the blockchain" - 3. Call the RPC method "web3_eth_getStorageAt" to send the request message to the blockchain - 4. Parse the received block chain response message and return the analysis result + 2. Package the request message of + 3. "Get the content stored in the specified location of the blockchain" + 4. Call the RPC method "web3_eth_getStorageAt" to send the request message to the blockchain + 5. Parse the received block chain response message and return the analysis result + Get the number of account transactions The content implemented by this interface includes: 1. web3 message ID increment - 2. Package the request message of "Get account transactions" + 2. Package the request message of "Get account transactions" 3. Call the RPC method "web3_eth_getTransactionCount" to send the request message to the blockchain 4. Parse the received blockchain response message and return the analysis result + Get the gasPrice of the blockchain The content implemented by this interface includes: 1. web3 message ID increment - 2. Package the request message of "Get the gasPrice of the blockchain" - 3. Call the RPC method " web3_eth_gasPrice " to send the request message to the blockchain + 2. Package the request message of "Get the gasPrice of the blockchain" + 3. Call the RPC method "web3_eth_gasPrice" to send the request message to the blockchain 4. Parse the received blockchain response message and return the analysis result + Get account balance The content implemented by this interface includes: 1. web3 message ID increment - 2. Package the request message of "Get account balance" - 3. Call the RPC method " web3_eth_getBalance " to send the request message to the blockchain + 2. Package the request message of "Get account balance" + 3. Call the RPC method "web3_eth_getBalance" to send the request message to the blockchain 4. Parse the received blockchain response message and return the analysis result + Get transaction receipt The content implemented by this interface includes: 1. web3 message ID increment - 2. Package the request message of "get transaction receipt" + 2. Package the request message of "get transaction receipt" 3. Call the RPC method " web3_eth_getTransactionReceiptStatus " to send the request message to the blockchain 4. Parse the received blockchain response message and return the analysis result + Blockchain stateless call The content implemented by this interface includes: 1. web3 message ID increment 2. Package the request message of "Blockchain stateless call" - 3. Call the RPC method " web3_eth_call " to send the request message to the blockchain + 3. Call the RPC method "web3_eth_call" to send the request message to the blockchain 4. Parse the received blockchain response message and return the analysis result + Send raw transaction The content implemented by this interface includes: 1. web3 message ID increment - 2. Package the request message of "Send raw transaction" + 2. Package the request message of "Send raw transaction" 3. Call the RPC method " web3_eth_sendRawTransaction " to send the request message to the blockchain 4. Parse the received blockchain response message and return the analysis result -#### Protocol layer implementation of PlatONE +#### Protocol Layer Implementation of PlatONE The implementation of PlatONE's protocol layer is almost the same as that of Ethereum. The only difference is that the data field of raw transaction is filled with one more transaction type encoding, and has one more transaction type field in the RLP process of raw transaction. Because the data field is filled by users who use BoAT SDK before calling BoAT SDK-related APIs, the protocol layer of PlatONE can reuse the protocol layer of Ethereum. -#### Protocol layer implementation of FISCO BCOS +#### Protocol Layer Implementation of FISCO BCOS @todo -#### Protocol layer implementation of Fabric -##### Brief description of Fabric protocol layer -The Fabric protocol layer mainly contains proposal protocol and transaction protocol, and the query protocol is the same as the proposal protocol.Proposal agreement and transaction agreement are respectively as follows Figure 4-3,Figure 4-4:
+#### Protocol Layer Implementation of Fabric +##### Brief Description of Fabric Protocol Layer +The Fabric protocol layer mainly contains proposal protocol and transaction protocol, and the query protocol is the same as the proposal protocol. Proposal agreement and transaction agreement are respectively as follows Figure 4-3,Figure 4-4:
![ Fabric proposal protocol struct](./images/BoAT_Overall_Design_en-F4-3-Fabric-Proposal.png)
Figure 4-3 Fabric proposal protocol struct
![ Fabric transaction protocol struct](./images/BoAT_Overall_Design_en-F4-4-Fabric-Transaction.png)
Figure 4-4 Fabric transaction protocol struct
-When Fabric client launches a deal,will first send proposal to endorse node, get the data of proposal signature returned after endorsed node signatures. then the Fabric client puts the data endor node signature together with transaction parameters according to the transaction message format and sends to order nodes. After order node check through, it will updating the state of the chain.The detailed transaction process is shown in Figure 4-5,This figure is taken from the document.For more information on Fabric, refer to the Fabric documentation
+When Fabric client launches a deal,will first send proposal to endorse node, get the data of proposal signature returned after endorse node signatures. then the Fabric client puts the data endorse signature together with transaction parameters according to the transaction message format and sends to order nodes. After order node check through, it will updating the state of the chain. The detailed transaction process is shown in Figure 4-5,This figure is taken from the document. For more information on Fabric, refer to the Fabric documentation: .
![ Fabric transaction flow](./images/BoAT_Overall_Design_en-F4-5-Fabric-Transaction-Flow.png)
Figure 4-5 Fabric transaction flow
##### Fabric protocol interface implementation -In the Fabric message, the fields in the protocol are serialized through ProtoBuf and then sent out through the HTTP2 protocol.As can be seen from the preface section, there are some duplicates and similarities between the proposal and transaction messages, and these duplicates can be split into a submodule for easier reuse.One possible split is listed as follows: +In the Fabric message, the fields in the protocol are serialized through ProtoBuf and then sent out through the HTTP2 protocol. As can be seen from the preface section, there are some duplicates and similarities between the proposal and transaction messages, and these duplicates can be split into a submodule for easier reuse. One possible split is listed as follows: - channelHeader packaging - signatureHeader packaging - proposal load packaging - transaction load packaging -### RPC layer +### RPC Layer #### Overview -The RPC layer implements the encapsulation of the specific link that sends data to the blockchain node,and provide services to the protocol layer.The RPC layer is an abstraction of the concrete realization of the sending link, so that the BoAT SDK can be transplanted to different operating environments more conveniently. +The RPC layer implements the encapsulation of the specific link that sends data to the blockchain node, and provide services to the protocol layer. The RPC layer is an abstraction of the concrete realization of the sending link, so that the BoAT SDK can be transplanted to different operating environments more conveniently. -#### Scalable design of RPC layer -The RPC layer expands down to implement different sending links according to the specific operating environment. For example, some environments provide the transmission tool cURL, you can use curl to send and receive messages. Some environments do not support cURL, but provide AT commands to send and receive messages. The RPC layer encapsulates these different implementations. The layer provides a unified interface, so that the protocol layer does not need to care about the specific transmission link, and only needs to call the unified interface when sending and receiving messages.The RPC layer's encapsulation of different links also facilitates the expansion of more link implementations. +#### Scalable Design of RPC Layer +The RPC layer expands down to implement different sending links according to the specific operating environment. For example, some environments provide the transmission tool cURL, you can use curl to send and receive messages. Some environments do not support cURL, but provide AT commands to send and receive messages. The RPC layer encapsulates these different implementations. The layer provides a unified interface, so that the protocol layer does not need to care about the specific transmission link, and only needs to call the unified interface when sending and receiving messages. The RPC layer's encapsulation of different links also facilitates the expansion of more link implementations. -##### Extension of RPC layer to cURL +##### Extension of RPC Layer to cURL cURL is a file transfer tool that uses URL syntax to work under the command line. It supports multiple communication protocols such as FTP, FTPS, HTTP, and HTTPS. When the RPC layer enables cURL support, in addition to the global resource initialization of cURL when the SDK is initialized, it must also be implemented at the RPC layer: 1. cURL session initialization 2. Set the URL format to\://:\ @@ -412,38 +413,38 @@ cURL is a file transfer tool that uses URL syntax to work under the command line -### Hardware dependency layer +### Hardware Dependency Layer #### Overview -BoAT SDK will run on different hardware platforms. In order to make better use of hardware resources, BoAT SDK provides a hardware dependency layer.The hardware dependency layer provides services for the wallet at the interface layer, providing services such as random number generators, secure storage,encryption and signature.Since the resources provided by different hardware platforms may be different, for example,some hardware provides the hardware implementation of the random number generator, some hardware platforms not only provide the hardware implementation of the random number generator, but also provide the TEE environment, which has hardware dependence Layer, BoAT SDK can make better use of these hardware resources. +BoAT SDK will run on different hardware platforms. In order to make better use of hardware resources, BoAT SDK provides a hardware dependency layer. The hardware dependency layer provides services for the wallet at the interface layer, providing services such as random number generators, secure storage, encryption and signature. Since the resources provided by different hardware platforms may be different, for example, some hardware provides the hardware implementation of the random number generator, some hardware platforms not only provide the hardware implementation of the random number generator, but also provide the TEE environment, which has hardware dependence Layer, BoAT SDK can make better use of these hardware resources. -#### Software implementation of the hardware dependent layer -BoAT SDK should provide a hardware-dependent full software implementation, so that BoAT can still run completely when the hardware cannot provide the required complete services.Hardware-dependent software implementation should be based on covering the necessary hardware services as a standard, and at least provide the following functional implementations: +#### Software Implementation of The Hardware Dependent Layer +BoAT SDK should provide a hardware-dependent full software implementation, so that BoAT can still run completely when the hardware cannot provide the required complete services. Hardware-dependent software implementation should be based on covering the necessary hardware services as a standard, and at least provide the following functional implementations: + Random number generator + Signature (such as ECDSA used by Ethereum) + Secure storage (such as storing private keys in an encrypted manner) + Hash algorithm (such as Keccak-256 used by Ethereum) -#### TEE support -The design of BoAT should consider the support of TEE environment.For hardware with a TEE environment, BoAT should be able to put sensitive information in the TEE environment with a small amount of modification.To meet this goal, the wallet is designed to meet the following criteria: +#### TEE Support +The design of BoAT should consider the support of TEE environment. For hardware with a TEE environment, BoAT should be able to put sensitive information in the TEE environment with a small amount of modification. To meet this goal, the wallet is designed to meet the following criteria: + Independent design of wallet-related data structure + Wallet related implementation independent design + Sensitive information related to the wallet is not reflected outside the wallet -### General tool implementation +### General Tool Implementation #### Overview -General tools exist independently of each layer and are used to generate C language interfaces for accessing blockchain smart contracts.General tools should be implemented in scripting languages.Common tools include: +General tools exist independently of each layer and are used to generate C language interfaces for accessing blockchain smart contracts. General tools should be implemented in scripting languages. Common tools include: + Tool used to generate C language interface of Ethereum smart contract + Tool used to generate C language interface of PlatONE smart contract -#### Brief description of general tools +#### Brief Description of General Tools -##### Tool for generating C language interface of Ethereum smart contract -The commonly used programming language for Ethereum smart contracts is solidity. After solidity is compiled, a JSON file describing the contract interface will be generated.The JSON format of the contract interface is given by an array of function and/or event descriptions.The description of a function is a JSON object with the following fields: +##### Tool for Generating C Language Interface of Ethereum Smart Contract +The commonly used programming language for Ethereum smart contracts is solidity. After solidity is compiled, a JSON file describing the contract interface will be generated. The JSON format of the contract interface is given by an array of function and/or event descriptions. The description of a function is a JSON object with the following fields: + type: "function" , "constructor" , "receive" (Function to receive Ether) or "fallback"( Default function) + name: Function name -+ inputs :Object array, each array object will contain: ++ inputs: Object array, each array object will contain: - name: parameter name； - type: Authoritative type of parameter - components: For tuple type @@ -511,20 +512,20 @@ For the generated C language contract interface, the corresponding relationship -##### Tool for generating C language interface of PlatONE smart contract +##### Tool for Generating C Language Interface of PlatONE Smart Contract The commonly used PlatONE smart contract development language is C++. Like Ethereum, the PlatONE smart contract will also generate a JSON file describing the contract interface after being compiled. Its JSON field is the same as Ethereum's JSON field, and the correspondence between C language interface and JSON field is also consistent with Ethereum. ### Application #### Overview -In the implementation of each layer of The BoAT SDK, more or less it involves the conversion of data formats, the codec of messages, and so on.These functions should be abstracted into independent modules to provide services for each layer. These functional blocks include: +In the implementation of each layer of The BoAT SDK, more or less it involves the conversion of data formats, the codec of messages, and so on. These functions should be abstracted into independent modules to provide services for each layer. These functional blocks include: + Data format conversion tool + RLP encoding + JSON encoding and decoding -#### Data format conversion tool -In the design of BoAT SDK, data format conversion is used in many places, such as converting the input ASCII code into a binary format, and converting the binary format data returned by the blockchain into an ASCII code format that is convenient for display. The Little-endian and big endian conversions involved in the contract ABI interface, etc. For ease of use, it is advisable to put the format conversion function implementations that may be used in the same file.The data conversions that may be used are: +#### Data Format Conversion Tool +In the design of BoAT SDK, data format conversion is used in many places, such as converting the input ASCII code into a binary format, and converting the binary format data returned by the blockchain into an ASCII code format that is convenient for display. The Little-Endian and Big-Endian conversions involved in the contract ABI interface, etc. For ease of use, it is advisable to put the format conversion function implementations that may be used in the same file. The data conversions that may be used are: + Convert binary stream to hexadecimal string + Convert a hexadecimal string to a binary stream + Convert uint32 type data to big endian @@ -532,11 +533,11 @@ In the design of BoAT SDK, data format conversion is used in many places, such a + convert byte order of a byte stream In addition, in order to adapt the SDK to more environments, you can also encapsulate the following functions into this file: -+ Heap memory application ++ Heap memory allocation + Heap memory release + Sleep waiting -#### RLP encoding +#### RLP Encoding ##### Structure of RLP RLP encoding is used in two places. One is that the protocol layer organizes transaction messages to use RLP encoding, and the other is that RLP encoding may be used in the generated C language contract interface code. @@ -544,17 +545,17 @@ The definition of RLP encoding only handles two types of data: one is a string a ![The structure of the RLP list](./images/BoAT_Overall_Design_en-F4-6-Structure_Of_RLP.png)
Figure 4-6 The structure of the RLP list
-##### RLP encoding rules +##### RLP Encoding Rules The encoding rules of RLP are described as follows: + If a string is 0-55 bytes long, the RLP encoding consists of a single byte with value 0x80 plus the length of the string followed by the string. The range of the first byte is thus [0x80, 0xb7]. + If a string is more than 55 bytes long, the RLP encoding consists of a single byte with value 0xb7 plus the length in bytes of the length of the string in binary form, followed by the length of the string, followed by the string. + If the total payload of a list (i.e. the combined length of all its items being RLP encoded) is 0-55 bytes long, the RLP encoding consists of a single byte with value 0xc0 plus the length of the list followed by the concatenation of the RLP encodings of the items. The range of the first byte is thus [0xc0, 0xf7]. + If the total payload of a list is more than 55 bytes long, the RLP encoding consists of a single byte with value 0xf7 plus the length in bytes of the length of the payload in binary form, followed by the length of the payload, followed by the concatenation of the RLP encodings of the items. The range of the first byte is thus [0xf8, 0xff]. -For a more detailed description of RLP encoding rules, please refer to the reference document Rlp wiki: https://eth.wiki/en/fundamentals/rlp +For a more detailed description of RLP encoding rules, please refer to the reference document RLP wiki: . -##### RLP encoding implementation +##### RLP Encoding Implementation RLP encoding can be implemented in many different ways. As can be seen from the foregoing chapters, a possible data structure composition description of RLP encoding is shown in Figure 4-7:
![A possible data structure of RLP encoding](./images/BoAT_Overall_Design_en-F4-7-Data_Structure_Of_RLP.png)
Figure 4-7 A possible data structure of RLP encoding
@@ -579,13 +580,13 @@ In summary, the implementation method of RLP should include at least: + Delete a string in the list Calculate RLP code length -#### JSON encoding and decoding +#### JSON Encoding and Decoding In the message that BoAT SDK accesses the blockchain, the encoding of JSON will be involved, and the response message of the blockchain to the BoAT SDK will involve the decoding of JSON. The encoding and decoding of JSON in the message can be implemented with a three-party library: cJSON. -cJSON is a lightweight JSON codec written in C language. It follows the ANSI-C standard and can adapt to more platforms and compilers. It is also very convenient to port cJSON into the SDK. Simply copy cJSON.h and cJSON.c to the SDK, and include the header file "cJSON.h" where you need to use cJSON to use it. For more description of cJSON, please refer to the reference document cJSON. +cJSON is a lightweight JSON codec written in C language. It follows the ANSI-C standard and can adapt to more platforms and compilers. It is also very convenient to port cJSON into the SDK. Simply copy cJSON.h and cJSON.c to the SDK, and include the header file "cJSON.h" where you need to use cJSON to use it. For more description of cJSON, please refer to the reference document cJSON: . -## The process of creating a blockchain transaction using BoAT +## The Process of Creating A Blockchain Transaction Using BoAT -### The process of creating an Ethereum transaction using BoAT +### The Process of Creating An Ethereum Transaction Using BoAT A typical process of using BoAT to create an Ethereum transaction is shown in Figure 5-1:
![The process of creating a transaction using BoAT](./images/BoAT_Overall_Design_en-F5-1-Create_Ttransaction.png)
Figure 5-1 The process of creating a transaction using BoAT
@@ -604,12 +605,12 @@ Please refer to the description of "send transaction" in [Ethereum transaction i + BoAT SDK de-initialization: Please refer to the description of "BoAT SDK de-initialization" in [SDK Initialization/Deinitialization](#SDK-Initialization-de-initialization) -### The process of creating an PlatONE transaction using BoAT +### The Process of Creating An PlatONE Transaction Using BoAT The process of creating a PlatONE transaction is similar to Ethereum. In addition to setting the Nonce field and the Data field, PlatONE also needs to set the transaction type field before sending the transaction. The rest of the process is consistent with Ethereum. For related description, please refer to [Process of creating an Ethereum transaction using BoAT](#The-process-of-creating-an-Ethereum-transaction-using-BoAT) ## Reference -[1]. cJSON -[2]. cURL -[3]. RLP wiki +[1]. cJSON +[2]. cURL +[3]. RLP wiki diff --git a/docs/en-us/BoAT_System_Requirements_en.md b/docs/en-us/BoAT_System_Requirements_en.md index 2f6466420..81b8e4d57 100644 --- a/docs/en-us/BoAT_System_Requirements_en.md +++ b/docs/en-us/BoAT_System_Requirements_en.md @@ -2,7 +2,7 @@ This technical paper describes the system requirements of the BoAT Framework (C language version) for cellular modules. BoAT is an SDK that runs on the module's application processor. For the OpenCPU cellular module, BoAT is linked and called by the application as a library. For non-OpenCPU cellular modules, BoAT's API needs to be extended to AT commands for applications on the upper MCU to call. -## Part One. Storage requirements +## Part One. Storage Requirements For Ethereum/PlatONE/FISCO BCOS, the storage requirements of the BoAT Framework (C language version) itself are: - Flash (code and read-only data): about 210kB @@ -17,13 +17,13 @@ For HyperLedger Fabric, the storage requirements of the BoAT Framework (C langua The above does not include the system libraries that the BoAT Framework (C language version) depends on. The exact values may vary with different blockchain protocols. -## Part Two. Processing power requirements +## Part Two. Computing Performance Requirements For supporting Ethereum, the BoAT Framework (C language version) takes about 1 second (excluding network communication time) to complete the cryptographic operations for a blockchain transaction or smart contract call, on an ARM Cortex M4 running at about 100MHz . The exact time can vary with different blockchain protocols. -The exact processing power requirements depend on the power consumption and latency requirements of the application calling (porting in) the BoAT Framework SDK. BoAT itself has no special requirements. +The exact computing performance requirements depend on the power consumption and latency requirements of the application calling (porting in) the BoAT Framework SDK. BoAT itself has no special requirements. -## Part Three. Operating system and communication requirements +## Part Three. Operating System and Communication Requirements There really are no special requirements for the operating system. Generally BoAT Framework (C language version) can be ported over most operating systems (e.g. linux, various RTOS), as long as the following capabilities (below) are supported: @@ -54,7 +54,7 @@ If the device can only connect to the IoT platform of a specific operator or ser 8. If the cellular IoT Module utilizes a Linux operating system, during debugging it should support adb or similar login mechanism and have root privileges. -## Part Four TEE and remote attestation(optional) +## Part Four TEE and Remote Attestation (optional) ### TEE @@ -64,7 +64,7 @@ If the application processor of the cellular module supports the TEE (Trusted Ex 2. Supporting Secure Boot, fuse, etc. 3. Support for secure storage -### Remote attestation +### Remote Attestation Remote attestation is a mechanism that uses the Root of Trust embedded in the chip to provide signature services for device data, and may probe device operating environment characteristic information. Remote attestation can help service providers remotely authenticate the authenticity of equipment. If the module's chip supports remote authentication, it should support at least the following capabilities: @@ -72,7 +72,7 @@ Remote attestation is a mechanism that uses the Root of Trust embedded in the ch 2. If the TEE is supported, the data should be signed in TEE (optional) -## Part Five. Cryptography hardware acceleration (optional) +## Part Five. Cryptography Hardware Acceleration (optional) If the hardware supports cryptographic hardware acceleration, utilizing this technology will improve the performance of cryptographic operations. diff --git a/docs/en-us/BoAT_User_Guide_en.md b/docs/en-us/BoAT_User_Guide_en.md index 3d8ce3a9f..b528fcd61 100644 --- a/docs/en-us/BoAT_User_Guide_en.md +++ b/docs/en-us/BoAT_User_Guide_en.md @@ -23,7 +23,7 @@ The intended readers of this article are customers who integrate the BoAT IoT Fr ## Function and architecture -BoAT IoT Framework is a C language blockchain client framework software for cellular modules, which is easy to be ported to various modules and helps IoT applications based on cellular modules connect to the blockchain and realize data on-chain services. The functions provided by the BoAT IoT Framework SDK to IoT applications include initiating on-chain transactions, automatic generation of smart contract C interface code, calling smart contracts, and managing blockchain keys. +BoAT IoT Framework is a C language blockchain client framework software for cellular modules, which is easy to be ported to various modules and helps IoT applications based on cellular modules connect to the blockchain and access on-chain services. The functions provided by the BoAT IoT Framework SDK to IoT applications include initiating on-chain transactions, automatic generation of smart contract C interface code, calling smart contracts, and managing blockchain keys. **Supported blockchain:** Ethereum @@ -33,12 +33,12 @@ Hyperledger Fabric **Supported Target Operating System:** -linux +Linux RTOS **Supported Build Operating System:** -linux/cygwin +Linux/Cygwin **Main features:** Blockchain account (wallet) parameter configuration @@ -72,7 +72,7 @@ The blockchain client interface protocol mainly implements transaction interface The remote procedure call(RPC) interface implements a warpper for different communication protocols. This component needs to be ported according to the specific communication method supported by the IoT device. Public components implement common functions such as RLP encoding, JSON codec, string processing, etc. Hardware dependent components are ported components involving different hardware, such as cryptography accelerators, secure storage, random numbers, etc. This component needs to be ported according to specific hardware. SDK also provides a set of default Hardware dependent components witch implementations by software. -The tool component provides a set of Python tools, that be used to generate C language contract call interface of smart contract ABI interface based on Solidity or WASM C++. +The tool component provides a set of Python tools, which are used to generate C language contract call interface of smart contract ABI interface based on Solidity or WASM C++. @@ -162,7 +162,7 @@ BOAT_PROTOCOL_USE_FISCOBCOS ?= 1 BOAT_PROTOCOL_USE_HLFABRIC ?= 1 ```` -As needed, change the value of the corresponding variable to `1` or `0` to enable or disable the corresponding blockchain protocol. Or when compiling the SDK, use make \=<1|0> to enable or disable the corresponding blockchain protocol. +As needed, change the value of the corresponding variable to `1` or `0` to enable or disable the corresponding blockchain protocol. Or while compiling the SDK, use make \=<1|0> to enable or disable the corresponding blockchain protocol. -Log printing level adjustment If necessary, adjust the value of `BOAT_LOG_LEVEL` in the path \/vendor/platform/\/src/log/boatlog.h to adjust the printer type of the log. @@ -291,7 +291,7 @@ Among them, boatiotsdk is the directory where the SDK is located, and the -C par *Note: In the Makefile, the command under target must start with a Tab (ASCII code 0x09), not a space.* -The above steps are only used to compile the SDK library. After the SDK library compile completed, the compiled library needs to be integrated into the module development environment. See the [Header Files and Libraries](###Header Files and Libraries) chapter for details. +The above steps are only used to compile the SDK library. After the SDK library compilation completes, the compiled library needs to be integrated into the module development environment. See the [Header Files and Libraries](###Header Files and Libraries) chapter for details. ###### The module development environment is compiled with non-GNU make Since BoAT IoT Framework SDK uses GNU make as the compilation project, if the module development environment uses non-GNU Make compilation projects (such as Ninja, ant, etc.), or uses the automatic generation tools of the compilation project (such as automake, CMake), it cannot Compile the SDK directly in the module development environment. @@ -363,14 +363,13 @@ The smart contract used by the demo and its ABI JSON file are placed in: | \/demo/demo_fiscobcos/demo_contract/HelloWorld.sol | \/demo/demo_fiscobcos/demo_contract/HelloWorld.json | FISCO-BCOS demo | -Before running Ethereum's Demo, you need to install the Ethereum node simulator ganache, as well as the Ethereum smart contract compilation deployment tool truffle. -Ganache and truffle tools can visit this website: https://truffleframework.com +Before running Ethereum's Demo, you need to install the Ethereum node simulator ganache, as well as the Ethereum smart contract compilation deployment tool truffle, could visit this website: https://truffleframework.com . + Ganache has a ganache-cli version of the command line interface, and a Ganache version of the graphical interface. The ganache-cli of the command line interface and the Ganache 1.x version of the graphical interface will not be saved. If the process of ganache-cli or Ganache 1.x is terminated, the deployed contract will be lost. The command truffle migrate - reset Redeploy the contract, the address of the redeployed contract may change. The Ganache 2.x version of the graphical interface can create a Workspace save state. After closing and reopening the Workspace next time, the deployed contract still does not need to be redeployed. In addition to using the ganache simulator, you can also use the Ethereum test network such as Ropsten (you need to apply for a free test token). -Before running the PlatONE Demo, you need to install the PlatONE node, as well as smart contract compilation and deployment tools. -PlatONE source code and tools can visit this website: https://platone.wxblockchain.com +Before running the PlatONE Demo, you need to install the PlatONE node, as well as smart contract compilation and deployment tools,could visit this website: https://platone.wxblockchain.com . Before running the FISCO-BCOS Demo, you need to install the FISCO-BCOS node and contract deployment. FISCO-BCOS source code and installation and deployment steps can visit this website: https://fisco-bcos-documentation.readthedocs.io @@ -458,15 +457,15 @@ After the SDK is compiled, only the following files are needed for the applicati 1. Refer to the SDK header file in the application - Add \/include to the header file search path of the application, or copy all header files under \/include to the application header file directory. - -In the application header file search path, add \/vendor/platform/include, or copy the boatconfig.h header file under \/vendor/platform/include to the application header file directory . - -In the application-related C code, add the following header files: +- In the application header file search path, add \/vendor/platform/include, or copy the boatconfig.h header file under \/vendor/platform/include to the application header file directory . +- In the application-related C code, add the following header files: ```` #include "boatiotsdk.h" //SDK entry header file #include "boatconfig.h" //SDK configuration header file ```` --The application does not need to include the other header file directories of the SDK into the search path. +- The application does not need to include the other header file directories of the SDK into the search path. If you use the automatically generated C interface code based on the contract ABI JSON file, you also need to include the generated smart contract C interface code header file, and add the generated `*.c` file to the application compilation script. @@ -690,15 +689,15 @@ In some contract programming languages, the two types of contract functions have For example, take the following Ethereum Solidity contract as an example: contract StoreRead { - bytes32[] eventList; + bytes32[] eventList; - function saveList(bytes32 newEvent) public { - eventList.push(newEvent); - } + function saveList(bytes32 newEvent) public { + eventList.push(newEvent); + } - function readListLength() public view returns (uint32 length_) { - length_ = uint32(eventList.length); - } + function readListLength() public view returns (uint32 length_) { + length_ = uint32(eventList.length); + } } @@ -739,7 +738,7 @@ After the contract is compiled, the ABI corresponding to the two functions are d In the above contract, eventList is a member variable of the contract. saveList() will change the value of eventList, which is a contract function that changes the state of the blockchain; readListLength() has a view modifier and only reads the attributes of eventList without changing its value. It is a contract function that does not change the state of the blockchain . -Pay special attention to the fact that although the contract function and C call interface function that change the state of the blockchain and do not change the state of the blockchain are very similar in prototype, the calling principles of the two are quite different. +In particular, there are significant differences in the principles of invoking between smart contract functions that update the ledger and those who don’t, even though the two types of functions are quite similar in prototype. The same is true for the interface functions in C language generated through the conversion tool. Any change to the state of the blockchain needs to be implemented through blockchain transactions and reach a consensus across the entire network. The contract function that changes the state of the blockchain is called asynchronously. When called, it only initiates the blockchain transaction, and the contract will not be executed before the blockchain network packs the transaction into blocks. Therefore, when the contract function that changes the state of the blockchain is called, the return value is only the hash value used to identify the transaction, not the return value in the form of the contract function. When designing a smart contract, the public interface function that changes the state of the blockchain, the information it tries to return should be stored in the contract member variable, and the receipt of the transaction is queried through BoatEthGetTransactionReceipt(). After success, use another Obtained in the form of a read function. @@ -1009,4 +1008,4 @@ A HEX string representing the recipient (payee) address. ## Reference BoAT API Reference Manual -[1].BoAT IoT Framework SDK Reference Manual, AITOS.20.70.100IF, V1.0.0 \ No newline at end of file +[1].BoAT IoT Framework SDK Reference Manual, AITOS.20.70.100IF, V1.0.0 diff --git a/docs/zh-cn/BoAT_Overall_Design_cn.md b/docs/zh-cn/BoAT_Overall_Design_cn.md index 966c3f7ee..9396637bf 100644 --- a/docs/zh-cn/BoAT_Overall_Design_cn.md +++ b/docs/zh-cn/BoAT_Overall_Design_cn.md @@ -410,7 +410,7 @@ BoAT SDK应提供一种硬件依赖的全软件实现，以使BoAT在硬件无 #### TEE支持 -BoAT的设计应考虑TE环境的支持。对于有TE环境的硬件，BoAT应可以通过少量的修改将敏感信息放到TE环境中。为满足此目标，钱包的设计满足以下标准： +BoAT的设计应考虑TEE环境的支持。对于有TEE环境的硬件，BoAT应可以通过少量的修改将敏感信息放到TEE环境中。为满足此目标，钱包的设计满足以下标准： + 钱包相关的数据结构独立设计 + 钱包相关的实现独立设计 + 钱包相关的敏感信息不在钱包以外的地方体现 diff --git a/docs/zh-cn/BoAT_User_Guide_cn.md b/docs/zh-cn/BoAT_User_Guide_cn.md index 965801924..d2022351c 100644 --- a/docs/zh-cn/BoAT_User_Guide_cn.md +++ b/docs/zh-cn/BoAT_User_Guide_cn.md @@ -324,7 +324,7 @@ set PATH=%PATH%;\\bin 注：上述命令可以编写在一个bat批处理文件中，或者直接加入Windows系统环境变量中，方便调用。注意，如果直接加入Windows系统环境变量，不得将Cygwin置于%SystemRoot%\System32路径之前，否则在其他场景中调用Windows的FIND命令时，将错误地调用Cygwin的find版本，这将影响其他场景中使用Windows自带命令。 -然后，修改`\/vendor/platform//external.env`，为依赖工具加上路径: +然后，修改`/vendor/platform//external.env`，为依赖工具加上路径: ``` # Commands CYGWIN_BASE := C:\cygwin64 # Modify to actual path to Cygwin @@ -725,7 +725,7 @@ contract StoreRead { ``` 上述合约中，eventList是合约的成员变量。saveList()会改变eventList的值，是改变区块链状态的合约函数；readListLength()有view修饰符，只读取eventList的属性，不改变它的值，是不改变区块链状态的合约函数。 -特别注意，尽管改变区块链状态和不改变区块链状态的合约函数和C调用接口函数在原型上非常相似，但两者的调用原理有很大差别。 +特别注意，尽管改变区块链状态和不改变区块链状态的合约函数在原型上非常相似，但两者的调用原理有很大差别。通过该工具生成的C接口函数也是同样情况。 对区块链状态的任何改变，都需要通过区块链交易实施并在全网达成共识。改变区块链状态的合约函数是异步调用，在调用时，只是发起该次区块链交易，而在区块链网络将该交易打包出块前，该合约不会被执行。因此，调用改变区块链状态的合约函数时，其返回值仅仅是用于标识该次交易的哈希值，而不是该合约函数形式上的返回值。在设计智能合约时，改变区块链状态的对外（public）接口函数，其试图返回的信息，应当保存在合约成员变量中，通过BoatEthGetTransactionReceipt()查询该次交易的回执，成功后，用另一个读函数的形式获取。