Skip to content

Commit 6a5ca38

Browse files
eanzhaoeanzhao
committed
Initial commit of genesis contract doc.
1 parent 233e63b commit 6a5ca38

File tree

1 file changed

+112
-0
lines changed

1 file changed

+112
-0
lines changed

‎docs-sphinx/reference/smart-contract/genesis-contract.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,115 @@ message SmartContractRegistration {
2626
bool is_user_contract = 8;
2727
}
2828
```
29+
Smart Contract code is store in the `code` field.
30+
31+
However, each `SmartContractRegistration` entity is not a one-to-one correspondence with the contract, and its storage structure is:
32+
33+
```C#
34+
public MappedState<Hash, SmartContractRegistration> SmartContractRegistrations { get; set; }
35+
```
36+
37+
`SmartContractRegistration` entity can be fetched by the hash value of the contract code. In fact, it is only written once when deploying the contract.
38+
39+
The data structure that corresponds one-to-one with contracts is called `ContractInfo`.
40+
Structure `ContractInfo` is defined in `acs0.proto`.
41+
42+
```C#
43+
message ContractInfo
44+
{
45+
// The serial number of the contract.
46+
int64 serial_number = 1;
47+
// The author of the contract, this is the person who deployed the contract.
48+
aelf.Address author = 2;
49+
// The category of contract code(0: C#).
50+
sint32 category = 3;
51+
// The hash of the contract code.
52+
aelf.Hash code_hash = 4;
53+
// Whether it is a system contract.
54+
bool is_system_contract = 5;
55+
// The version of the current contract.
56+
int32 version = 6;
57+
string contract_version = 7;
58+
// Indicates if the contract is the user contract.
59+
bool is_user_contract = 8;
60+
}
61+
```
62+
63+
We use the MappedState to store related instances.
64+
65+
```C#
66+
public MappedState<Address, ContractInfo> ContractInfos { get; set; }
67+
```
68+
69+
From the `code_hash` field of `ContractInfo`, it is not difficult to guess:
70+
71+
1. When trying to retrieve the contract code, the `code_hash` of ContractInfo is first read, and then the contract code itself is read from `State.SmartContractRegistrations` mapped state.
72+
2. Upgrading a contract on aelf is actually replacing the `code_hash` of `ContractInfo`.
73+
74+
# Calculation of contract address
75+
76+
The contract address is actually calculated through a field that increases with the number of contract deployments.
77+
78+
```C#
79+
public Int64State ContractSerialNumber { get; set; }
80+
```
81+
82+
Its calculation process is located in the `DeploySmartContract` method:
83+
84+
```C#
85+
var contractAddress = AddressHelper.BuildContractAddress(Context.ChainId, serialNumber);
86+
```
87+
88+
- The contract address of each chain of aelf is different.
89+
- The contract address is not related to the contract code, but only to the order in which it is deployed on this chain.
90+
- Therefore, when testing newly written contracts in `aelf-boilerplate` or `aelf-developer-tools`, the new contract always has a fixed address.
91+
92+
After the 1.6.0 version, Salt is added to the imported parameter of the deployment/upgrade contract. The contract address is calculated by using the Deployer address of the deployment account and the hash value Salt.
93+
94+
```C#
95+
var contractAddress = AddressHelper.ComputeContractAddress(deployer, salt);
96+
```
97+
98+
- Deploying contracts with the same account and using the same Salt can make the contract address of each chain of aelf the same.
99+
100+
# Contract deployment and update process
101+
102+
## Deploy contract with audit
103+
104+
The current pipeline starts with Propose, which generates a parliamentary proposal.
105+
When more than 2/3 of the BPs agree to deploy/update, a new proposal is released to request code inspection.
106+
Finally, after the code inspection is passed, the real contract deployment/upgrade will be achieved through the proposal of releasing code inspection.
107+
108+
## Deploy contract without audit
109+
110+
Developers send deployment/update user contract transactions, generate a parliamentary CodeCheck proposal, and when more than 2/3 of the BPs conduct code checks and pass, achieve real contract deployment/upgrade through the proposal of automatically releasing code checks.
111+
112+
## Contract deployment and upgrade new version number
113+
114+
When upgrading a contract, check the contract version information
115+
- If the contract version is less than or equal to the original contract version, the upgrade contract transaction fails
116+
The old version of the contract only has a version number after being upgraded.
117+
- If the version number is increasing , the upgrade contract transaction is successful.
118+
119+
In the updateSmartContract method, increase the version number judgment:
120+
121+
```C#
122+
var contractInfo = Context.UpdateSmartContract(contractAddress, reg, null, info.ContractVersion);
123+
Assert(contractInfo.IsSubsequentVersion,
124+
$"The version to be deployed is lower than the effective version({info.ContractVersion}), please correct the version number.");
125+
```
126+
127+
# Contract error message
128+
129+
130+
| Method | Error message | Note |
131+
| --- | --- | --- |
132+
| DeployUserSmartContract | No permission. | Trying to deploy smart contract to an aelf private sidechain, and the transaction sender is not in allowlist. |
133+
| | contract code has already been deployed before. | Contract code deployed |
134+
| | Already proposed. | Duplicate deployment request |
135+
| UpdateUserSmartContract | Contract not found. | Contract does not exist |
136+
| | No permission. | The updated contract author is not myself |
137+
| | Code is not changed. | The contract code has not changed |
138+
| | contract code has already been deployed before. | Contract code deployed |
139+
| | The version to be deployed is lower than the effective version({currentVersion}), please correct the version number. | Updated contract version number is too low |
140+
| | Already proposed. | Duplicate update request |

0 commit comments

Comments
 (0)