Skip to content

Commit 9c884bf

Browse files
nksanthoshnksanthosh
authored
Update README.md
1 parent b7b4569 commit 9c884bf

File tree

1 file changed

+150
-13
lines changed

1 file changed

+150
-13
lines changed

‎README.md

Lines changed: 150 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,150 @@
1-
Dependencies:
2-
* [eosio v1.3.x](https://github.com/EOSIO/eos/releases/tag/v1.3.2)
3-
* [eosio.cdt v1.3.x](https://github.com/EOSIO/eosio.cdt/releases/tag/v1.4.0)
4-
5-
To build the contracts and the unit tests:
6-
* First, ensure that your __eosio__ is compiled to the core symbol for the EOSIO blockchain that intend to deploy to.
7-
* Second, make sure that you have ```sudo make install```ed __eosio__.
8-
* Then just run the ```build.sh``` in the top directory to build all the contracts and the unit tests for these contracts.
9-
10-
After build:
11-
* The unit tests executable is placed in the _build/tests_ and is named __unit_test__.
12-
* The contracts are built into a _bin/\<contract name\>_ folder in their respective directories.
13-
* Finally, simply use __cleos__ to _set contract_ by pointing to the previously mentioned directory.
1+
# Introduction
2+
The EOSIO Assert Contract is a security feature to reduce the need for users to trust blockchain apps when a user signs a transaction for a trusted blockchain network with a trusted wallet application. It is a solution aiming to:
3+
4+
- Allow blockchain networks to register the official chain name and chain icon
5+
- Allow app developers to register one or more manifests describing their application, and
6+
- Allow app developers to remove previously registered manifests
7+
- Allow users (via some user-agent) to include a “require” action in a transaction that will ensure that the entire transaction is rejected if the required pre-conditions are not valid.
8+
9+
# Feature Overview
10+
Assert will be a system contract within the EOSIO software.
11+
12+
## Actors
13+
### End-User
14+
The End User is the person who is interacting with a Blockchain Application, and uses a Trusted Wallet Application to sign blockchain transactions when needed.
15+
16+
### Blockchain Application
17+
The Blockchain Application is the interface that an End User uses to perform some task that will be represented as a blockchain transaction, requiring a signature from an End User, facilitated by a Trusted Wallet Application.
18+
19+
Some Blockchain Applications may appear to be trustworthy, but have malicious intent. Some examples of malicious intent include: a) attempting to trick a user into divulging their private keys, and b) attempting to deceive a user into signing a transaction that does not represent the user’s intended interaction.
20+
21+
### Trusted Wallet Application
22+
The Trusted Wallet Application is where a user stores their private keys, and the interface through which they securely use those private keys to sign blockchain transactions proposed by Blockchain Applications. It is trusted by implication that it is aware of the End User’s private keys. A Trusted Wallet Application should implement measures to protect the End User from potentially malicious Blockchain Applications.
23+
24+
### Trusted Blockchain Network
25+
The Trusted Blockchain Network is where smart contract code representing the execution of the signed transactions run to produce an agreed upon global state so that users can cooperate through the use of Blockchain Applications. It is the most trusted component because it is often public and decentralized, and because it represents the ultimate source of truth. So the Trusted Blockchain Network is the best place to perform final checks of validity that what is claimed by a Trusted Wallet Application to have been agreed upon by the End User, is accurate and valid in comparison to the current state of the chain.
26+
27+
## Flows
28+
The sequence diagrams in this section describe how and in what order different actors work together when performing actions regarding the Assert Contract.
29+
30+
### eosio.assert::set.chain
31+
32+
Block Producers set chain info for Trusted Blockchain Network
33+
34+
### eosio.assert::add.manifest
35+
36+
Blockchain App publishes manifest to the chain
37+
38+
### eosio.assert::del.manifest
39+
40+
Blockchain App removes a manifest from the chain
41+
42+
### eosio.assert::require
43+
44+
- End User perform an interaction on the Blockchain App that requires signing
45+
- Blockchain App builds eosio.assert::require action, which includes the following:
46+
- Chain Info Hash
47+
- Manifest Hash
48+
- Array of ABI Hashes
49+
- Array of Contract Actions
50+
- Blockchain App proposes the transaction to the Trusted Wallet App, which includes:
51+
- eosio.assert::require Action
52+
- Other actions pertaining to the user’s performed interaction
53+
- Declared domain
54+
- Chain Info
55+
- ABIs
56+
- Trusted Wallet App gets app manifest from the Blockchain App with the well known url on declared domain and do the following checks:
57+
- Domain in manifest must match Declared Domain
58+
- All actions in the transaction must be allowed in the manifest whitelist
59+
- Trusted Wallet App gets app metadata from the Blockchain App and do the following checks:
60+
- Hash must match app metadata url hash in manifest
61+
- Chain icon must match hash in metadata
62+
- App icon must match hash in metadata
63+
- Trusted Wallet App builds eosio.assert::require based on app manifest, app metadata, declared domain, chain info, and ABIs from the Blockchain App, and compares to the eosio.assert::require that is included in the transaction.
64+
- Trusted Wallet App renders and show the Ricardian contract to End User:
65+
- Render the header from App Metadata, and
66+
- Render each action from action params, template from ABIs
67+
- End User approve the transaction with Biometrics
68+
- Trusted Wallet App perform the authentication and sign the transaction
69+
- Trusted Wallet App return the signed transaction back to the Blockchain App
70+
- Blockchain App broadcasts the transaction to Trusted Blockchain Network
71+
- Trusted Blockchain Network validates the Assert:
72+
- Chain Info Accurate
73+
- Manifest Exists
74+
- ABIs Accurate
75+
- Actions in Whitelist
76+
77+
# Functional Specifications
78+
Each function of the EOSIO Assert Contract will be explained in detail in this section, including the actor, requirement, parameters and results.
79+
## eosio.assert::setchain
80+
Allows Block Producers to set chain metadata, so that a Trusted Wallet Application can display chain information to an End User, and ensure that the validity of the information will be validated by the Trusted Blockchain Network by enforcing the inclusion of a valid eosio.assert::require action in every transaction for which it signs a transaction with the private keys of an End User.
81+
82+
| Item | Description |
83+
| --- | --- |
84+
| Contract name | eosio.assert |
85+
| Action name | setchain |
86+
| Pre-conditions | Requires eosio authorization |
87+
88+
#### Parameters
89+
- chain_id checksum256 type
90+
- chain_name string
91+
- icon checksum256c
92+
#### Result
93+
- Initializes the global state which describes the chain and is required for the contract to work
94+
95+
## eosio.assert::add.manifest
96+
Allows a Blockchain Application to publish an app manifest to the Trusted Blockchain Network. The manifest allows a Trusted Wallet Application to ensure that: 1) the metadata claimed by a Blockchain Application matches that of a manifest previously registered by the Blockchain Application, 2) the actions included in a transaction proposed by a Blockchain Application are whitelisted in a manifest previously registered by the Blockchain Application.
97+
98+
| Item | Description |
99+
| --- | --- |
100+
| Contract name | eosio.assert |
101+
| Action name | add.manifest |
102+
| Pre-conditions | Action must be authorized by the account which owns the app. The added manifest doesn’t already exist. |
103+
104+
#### Parameters
105+
- account: the account which owns the app
106+
- domain: the domain the app is hosted on, appmeta: see the manifest spec at [https://github.com/EOSIO/manifest-specification](https://github.com/EOSIO/manifest-specification)
107+
- whitelist: array of (contract, action) pairs that the manifest allows. An empty contract or action indicates a wildcard match. e.g. an empty action name means all actions are allowed for that contract.
108+
109+
#### Result
110+
- The manifest is stored.
111+
- Checksum256 hash of the manifest data is generated and used as the manifest id.
112+
113+
## eosio.assert::del.manifest
114+
Allows a Blockchain Application to remove a previously published app manifest from the Trusted Blockchain Network.
115+
116+
| Item | Description |
117+
| --- | --- |
118+
| Contract name | eosio.assert |
119+
| Action name | del.manifest |
120+
| Pre-conditions | Action must be authorized by the account which owns the app. The manifest to be deleted exists.|
121+
#### Parameters
122+
- id: checksum256 id of the manifest. This id was generated upon adding the manifest
123+
#### Result
124+
- The manifest is deleted |
125+
126+
## eosio.assert::require
127+
When added to a transaction, ‘require’ action performs multiple security checks. If any of the checks fails, the transactions fails.
128+
129+
| Item | Description |
130+
| --- | --- |
131+
| Contract name | eosio.assert |
132+
| Action name | require |
133+
| Pre-conditions | |
134+
#### Parameters
135+
- chain_parameter_hash: identifies the chain. It’s the checksum256 hash of chain_id, chain_name, and icon. These parameters were set when the contract was initialized using setchain action.
136+
- manifest_id: identifies the manifest. It’s the checksum256 id generated when the manifest was registered.
137+
- actions: array of (contract, action) pairs in the transaction. Don’t include require action itself.
138+
- abi_hashes: to fill this field: 1) Create a sorted set of contracts that appear ‘action’ parameters described above. Remove duplicates. 2) For each of the sorted, unique contracts, hash the ABI and append the result to ‘abi_hashes’ parameter. Hash the ABIs in the raw on-chain form, not in the JSON form.
139+
140+
#### Result
141+
- ‘require’ action checks the following:
142+
- chain_params_hash must match the hash of the chain data registered with ‘setchain’ action.
143+
- manifest_id exists
144+
- The manifest identified by manifest_id whitelists all the provided actions. See parameter ‘actions’ above.
145+
- Contracts have matching ABI hashes
146+
- If any of the checks fails, then the transaction will fail.|
147+
148+
149+
150+

0 commit comments

Comments
 (0)