Merge pull request #2739 from AElfProject/update-docs

Update docs of Protocol and Smart Contract

docs/architecture/implementations.md

@@ -24,7 +24,7 @@ Conceptually, AElf is built on two main layers: OS and Kernel. The OS contains t
 
 AElf has a native runtime for smart contracts which is implemented in C# and for contracts written in C#. The implementation is the AElf.Runtime.CSharp.* projects.
 
-A big part of AElf is the side chain framework. It is mainly implemented in the AElf.CrossChain namespace and defines the main abstractions in the **core** project and an implementation with grpc in the AElf.Crosschain.Communication.Grpc project.
+A big part of AElf is the side chain framework. It is mainly implemented in the AElf.CrossChain namespace and defines the main abstractions in the **core** project and an implementation with grpc in the AElf.Crosschain.Grpc project.
 
 The AElf.Test solution folder contains all the tests, coverage of the main functional aspects must be at a maximum to ensure the quality of our system.
 

docs/contract/acs.md

@@ -1,6 +1,6 @@
 # AElf Contract Standard (ACS)
 
-Think about **Interface Segregation Principle**. In AElf, smart contract can choose to inherit from one or more **ACSs**. To implement an ACS a contract must specify the ACS as a base, you can see in the code snippet below how to do this:
+Think about **Interface Segregation Principle**. In AElf, a smart contract can choose to inherit from one or more **ACSs**. To implement an ACS, developers need to specify ACSs as bases of the contract.The code snippet below shows how to do this:
 
 ```Proto
 
@@ -30,7 +30,7 @@ When doing this you can `override` (implement) the ACS's methods in your contrac
     ...
 ```
 
-As you can see it is mainly used for managing smart contracts.
+As you can see, it is mainly used for managing smart contracts.
 
 ## ACS1 - Fee information
 
@@ -43,14 +43,14 @@ As you can see it is mainly used for managing smart contracts.
     rpc GetMethodFee (google.protobuf.StringValue) returns (MethodFees) { }
 ```
 
-This ACS is essential for the economic system as it defines chargeable method. The `GetMethodFee` method will take effects before executing related transactions.
+This ACS is essential for the economic system as it defines the chargeable method. The `GetMethodFee` method will take effects before executing related transactions.
 
 ## ACS2 - Parallel resource information
 
 [standard](https://github.com/AElfProject/AElf/blob/dev/protobuf/acs2.proto)
 
 **Description:**
-For smart contracts to set and provide resource information to support parallel executing.
+Smart contracts can use this interface to inform the parallel executing mechanism resources usage of specific methods in this contract.
 
 ```Protobuf
     rpc GetResourceInfo (aelf.Transaction) returns (ResourceInfo) { }
@@ -60,7 +60,7 @@ For smart contracts to set and provide resource information to support parallel
 
 [standard](https://github.com/AElfProject/AElf/blob/dev/protobuf/acs3.proto)
 
-**Description:** This ACS defines proposal and approval functionalities. With ACS3, contract can design specific multi-sign mechanisms.
+**Description:** This ACS defines proposal and approval functionalities. With ACS3, a contract can design specific multi-sign mechanisms.
 
 
 ``` Protobuf
@@ -70,7 +70,7 @@ For smart contracts to set and provide resource information to support parallel
     rpc GetProposal(aelf.Hash) returns (ProposalOutput) { }
 ```
 
-As you can see in the code snippet above, the standard defines creation, approval and release functionality. In AElf three contracts implement this functionality, the referendum, association and parliament contract. 
+As you can see in the code snippet above, the standard defines creation, approval, and release functionality. In AElf three contracts implement this functionality, the referendum, association, and parliament contract. 
 
 
 ## ACS4 - Consensus
@@ -87,7 +87,7 @@ As you can see in the code snippet above, the standard defines creation, approva
     rpc ValidateConsensusAfterExecution (google.protobuf.BytesValue) returns (ValidationResult) { }
 ```
 
-For now only AElf's AEDPoSContract implements this interface. If one system contract deployed with it's contract address can be bind to `ConsensusContractSystemName` (by Contract Zero), then the consensus process of current blockchain will use the logic provided by this system contract.
+For now, only AElf's AEDPoSContract implements this interface. If one system contract deployed with its contract address can be bind to `ConsensusContractSystemName` (by Contract Zero), then the consensus process of the current blockchain will use the logic provided by this system contract.
 
 ## ACS5 - Method calling threshold
 
@@ -104,16 +104,16 @@ For now only AElf's AEDPoSContract implements this interface. If one system cont
 
 [standard](https://github.com/AElfProject/AElf/blob/dev/protobuf/acs6.proto)
 
-**Description:** ACS6 is aiming at providing two standard interfaces for requesting and getting random numbers. It implies using commit-reveal schema during random number generation and verification, though other solutions can also expose their services via these two interfaces. For now only AEDPoSContract implements this in AElf.
+**Description:** ACS6 is aiming at providing two standard interfaces for requesting and getting random numbers. It implies using commit-reveal schema during random number generation and verification, though other solutions can also expose their services via these two interfaces. For now, only AEDPoSContract implements this in AElf.
 
 ```Protobuf
     rpc RequestRandomNumber (google.protobuf.Empty) returns (RandomNumberOrder) { }
     rpc GetRandomNumber (aelf.Hash) returns (aelf.Hash) { }
 ```
 
 In the **commit-reveal schema**, the user needs to call `RequestRandomNumberInput` on his initiative as well as provide a block height number as the minimum height to enable the query of random number. Then the contract implemented ACS6 needs to returns:
-1) a hash value as the token for querying random number.
-2) a negotiated block height to enable related query. When the chain reaches the block height, the user can use that token, which is a hash value, call `GetRandomNumber` to query the random number.
+1) a hash value as the token for querying random numbers.
+2) a negotiated block height to enable related queries. When the chain reaches the block height, the user can use that token, which is a hash value, call `GetRandomNumber` to query the random number.
 
 The implementation of ACS6 in the `AEDPoS Contract` shows how **commit-reveal schema** works.
 
@@ -138,7 +138,7 @@ The cross-chain ACS is mainly used for managing side-chains.
 [standard](https://github.com/AElfProject/AElf/blob/dev/protobuf/acs8.proto)
 
 **Description:**
-If one contract choose to inherit from ACS8, the execution of every transaction of this contract will consume resource tokens of current contract.
+If one contract chooses to inherit from ACS8, the execution of every transaction of this contract will consume resource tokens of the current contract.
 
 ``` Protobuf
     rpc BuyResourceToken (BuyResourceTokenInput) returns (google.protobuf.Empty) { }

docs/contract/architecture.md

@@ -1,50 +1,52 @@
 ## Smart contract architecture
 
-At its core, a blockchain platform can be viewed as a distributed multi-tenant database which holds the state of all the smart contracts deployed on it. After deployment, each smart contract will have a unique address. The address is used to scope the state and as the identifier for state queries and updates. The methods defined in smart contract code provides the permission checks and logics for queries and updates.
+At its core, a blockchain platform can be viewed as a distributed multi-tenant database that holds the state of all the smart contracts deployed on it. After deployment, each smart contract will have a unique address. The address is used to scope the state and as the identifier for state queries and updates. The methods defined in the smart contract code provides the permission checks and logics for queries and updates.
 
-In aelf, a smart contract essentially has three parts: the interface, the state, and the business logics.
+In aelf, a smart contract essentially has three parts: the interface, the state, and the business logic.
 
-1. the interface - aelf supports smart contracts coded in multiple languages. Protobuf format is adopted as the cross-language definition of the contract.
+1. **the interface** - aelf supports smart contracts coded in multiple languages. Protobuf format is adopted as the cross-language definition of the contract.
 
-2. the state - the language specific SDK's provide some prototypes for the state of different types.
+2. **the state** - the language specific SDK provides some prototypes for the state of different types, after the defination of properties of certain prototype, developers could query and update *state database* via accessing the properties directly.
 
-3. the business logic - aelf provides protobuf plugins to generate the smart contract skeleton from the contract's proto definition. Developers just need to fill the logics for each method.
+3. **the business logic** - aelf provides protobuf plugins to generate the smart contract skeleton from the contract's proto definition. Developers just need to fill the logics for each method by override.
 
 Smart contracts in AElf are spread across the Kernel, the runtime and the SDK. The kernel defines the fundamental components and infrastructure associated with smart contracts. It also defines the abstractions for execution. Smart contract also heavily rely on the runtime modules and the sdk project.
 
 Smart contracts, along with the blockchain's data, form the heart of a blockchain system. They define through some predefined logic how and according to what rules the state of the blockchain is modified. 
-A smart contract is a collection of methods that each act upon a certain set of state variables.
 
-The logic contained in smart contracts is triggered by transactions. If a user of the blockchain wants to modify some state, he needs to build a transaction that will call a specific methods on some contract. When the transaction is included in a block and this block is executed, the modifications will be executed.
+A smart contract is a collection of methods that each act upon a particular set of state variables.
 
-Smart contracts a part of what makes dApps possible. They implement part of the buisness layer: the part that gets included in the blockchain.
+Transactions trigger the logic contained in smart contracts. If a user of the blockchain wants to modify some state, he needs to build a transaction that will call a specific method on some contract. When the transaction is included in a block and this block is executed, the modifications will be executed.
+
+Smart contracts are a part of what makes dApps possible. They implement a part of the business layer: the part that gets included in the blockchain.
 
 What follows in this section will give you a general overview of how AElf implements smart contracts. The other sections will walk you through different notions more specifically.
 
 ## Architecture overview
 
-In AElf, Smart Contracts are defined like micro-services. This makes Smart Contracts independent of specific programming language. This implies for example that our Consensus Protocol essentially becomes a service, because it is defined through Smart Contract.
+In AElf, Smart Contracts are defined like micro-services. This makes Smart Contracts independent of specific programming languages. This implies, for example, that our Consensus Protocol essentially becomes a service because it is defined through Smart Contract.
 
 <p align="center">
   <img src="sc-as-service.png" width="300">
 </p>
 
-As showed in the diagram above, smart contracts functionality is defined within the kernel. The kernel defines the fundamental components and infrastructure associated with defining smart contracts as a service:
-* SDK abstracts - high level entities that provide hook for smart contract services to interact with the chain.
-* Execution - high level primitives defined for execution
+As showed in the diagram above, smart contracts functionality is defined within the kernel. The kernel defines the fundamental components and infrastructure associated with establishing smart contracts as a service:
+* SDK abstracts - high-level entities that provide a hook for smart contract services to interact with the chain.
+* Execution - high-level primitives defined for execution
 
 ### Chain interactions
 
-Smart contract need to interact with the chain and have access to contextual information. For this AElf defines a bridge and a bridge host. Usually the programming SDK corresponding to specific language will implement features to communicate with/through the bridge.
+Smart contract need to interact with the chain and have access to contextual information. For this AElf defines a bridge and a bridge host. Usually the programming SDK corresponding to the specific language will implement features to communicate with/through the bridge.
 
 One of the major functionalities provided by the bridge is the ability to provide contextual information to the smart contract being executed. Here are a few:
 * the **Self** field represents the address of the current contract being called.
-* the **Sender** is the address that sent the transaction that executed the contract and **TransactionId** which is the ID of the transaction.
+* the **Sender** is the address that sent the transaction that executed the contract, and **Origin** is the address that signed the transaction. Sometimes **Sender** and **Origin** are equal.
+* the **OriginTransactionId** is the ID of the transaction fetch from transaction pool or generated by the current miner, and **TransactionId** is the Id of the transaction is executing, which means this transaction could be an inline one.
 
 The bridge also exposes extra functionality:
-* contracts can fire **Events** which are in a way similar to logging.
+* contracts can fire **Events**, which are in a way similar to logging.
 * contracts can call a method on another contract in a read-only manner. Any state change will not be persisted to the blockchain.
-* send inline - this actually creates a transaction to call another method. As opposed to call the changes to the state - if any - will be persisted. 
+* send inline - this actually creates a transaction to call another method. As opposed to calling the changes to the state - if any - will be persisted. 
 
 #### State 
 
@@ -60,9 +62,9 @@ When a block's transactions are executed, every transaction will generate a trac
 
 ### Sdk
 
-AElf comes with a native C# SDK that give smart contract developers the necessary tools to develop smart contracts in C#. It contains helpers to communicate with the bridge. By using the SDK you can also take advantage of the type infrastructure defined in the library:
-* ContractState: an interface that is implemented by a classes that are destined to be containers for state field.
+AElf comes with a native C# SDK that gives smart contract developers the necessary tools to develop smart contracts in C#. It contains helpers to communicate with the bridge. By using the SDK, you can also take advantage of the type infrastructure defined in the library:
+* ContractState: an interface that is implemented by a class that is destined to be containers for the state field.
 * MappedState: a base type that defines **collections** a key-value mapping, generic subclasses are available to enable multi-key scenarios.
 * SingletonState: this defines **non-collection** types with a 
 
-Any developer or company can develop an sdk and a runtime for a specific languages by creating an adapter to communicate with the bridge through gRPC.
+Any developer or company can develop an sdk and a runtime for a specific language by creating an adapter to communicate with the bridge through gRPC.

docs/contract/definition.md

@@ -1,7 +1,7 @@
 ## Defining a smart contract
 
 
-When writing a smart contract in AElf the first thing that need to be done is to define it so it can then be generate by our tools. AElf contracts are defined as services that are currently defined and generated with gRPC and protobuf.
+When writing a smart contract in AElf, the first thing that needs to be done is to define it so it can then be generated by our tools. AElf contracts are defined as services that are currently defined and generated with gRPC and protobuf.
 
 As an example, here is part of the definition of our multi-token contract. Each functionality will be explained more in detail in their respective section. Note that for simplicity, the contract has been simplified to show only the essential.
 
@@ -45,7 +45,7 @@ message Transferred {
 }
 ```
 
-For message and service definitions we the **proto3** version of the protobuf language. You probably won't need to use most of the features that are provided, but here's the [full reference](https://developers.google.com/protocol-buffers/docs/proto3) for the language.
+For message and service definitions, we the **proto3** version of the protobuf language. You probably won't need to use most of the features that are provided, but here's the [full reference](https://developers.google.com/protocol-buffers/docs/proto3) for the language.
 
 ### Service
 
@@ -57,7 +57,7 @@ For the service we have two different types of methods:
 rpc Create (CreateInput) returns (google.protobuf.Empty) { }
 ```
 
-The services takes protobuf messages as input and also returns protobuf messages. Note that here it returns a special message - google.protobuf.Empty - that signifies returning nothing. As a convention we append Input to any protobuf type that is destined to be a parameter to a service.
+The services take protobuf messages as input and also return protobuf messages. Note that here it returns a special message - google.protobuf.Empty - that signifies returning nothing. As a convention, we append `Input` to any protobuf type that is destined to be a parameter to a service.
 
 #### View option
 
@@ -79,7 +79,7 @@ This service is annotated with a view option. This signifies that this is a read
 
 ### Messages
 
-Here we define the concept of message as defined by the protobuf language. We heavily use these messages for calling the smart contracts and serializing their state. The following is the definition of a simple message:
+Here we define the concept of the message as defined by the protobuf language. We heavily use these messages for calling the smart contracts and serializing their state. The following is the definition of a simple message:
 
 ```json
 message CreateInput {