You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In this repo you will find source code of the smart contract that make ULCDocuments. Moreover, you will find a full documentation of how smart contracts work in order to create personalised API or applications that use ULCDocuments.
3
+
In this repo you will find the source code of the smart contracts used by ULCDocuments. You will also find a full documentation of how smart contracts work in order to create personalised API or applications using ULCDocuments.
4
4
5
-
# Documentation URL
6
-
7
-
Full documention is avaiable here : https://ulcdocumentscore.readthedocs.io/en/latest/index.html
5
+
**Full documention is avaiable here : https://ulcdocumentscore.readthedocs.io/en/latest/index.html**
Copy file name to clipboardExpand all lines: docs/ULCDocKernel.rst
+3-3
Original file line number
Diff line number
Diff line change
@@ -5,10 +5,10 @@ ULCDocKernel
5
5
Summary
6
6
=======
7
7
8
-
Each organisation or individual has to publish his own **ULCDocKernel** smart contract. The kernel part is used to explicitly publish signatures to blockchain.
9
-
So, the owner of ULCDocKernel has a complete and independent way to certify documents.
8
+
Each organisation or individual has to publish its own **ULCDocKernel** smart contract. The kernel is used to explicitly publish signatures to the blockchain.
9
+
This way, the owner of the published ULCDocKernel smart contract has a complete and independent way to certify documents.
Copy file name to clipboardExpand all lines: docs/ULCDocKernel/MultiRoles.rst
+37-23
Original file line number
Diff line number
Diff line change
@@ -1,42 +1,42 @@
1
1
Multi-Owner and Multi-Operator ability
2
2
======================================
3
-
For most of important organization, only one person can't do dangerous actions alone, such as signing an official document. In this way, the kernel has the ability to wait for multiple **confirmations** before doing important stuff, like publishing a signature, or changing critical configuration parameters.
3
+
For most organization, one person cannot do dangerous actions alone, such as signing official documents. As such, the kernel has the ability to wait for multiple **confirmations** before doing anything, like publishing a signature, or changing critical configuration parameters.
4
4
5
5
6
6
Roles
7
7
-----
8
8
9
-
ULCDocKernel has 2 floors of administrative process :
9
+
ULCDocKernel has 2 levels of administrative rights:
10
10
11
-
* ``owners`` that are administrators of the Smart Contract. They can change sensible parameters.
12
-
* ``operators`` that can only push, confirm and revoke signatures.
11
+
* ``operators`` can only push, confirm and revoke signatures.
12
+
* ``owners`` are administrators of the Smart Contract. In addition to having operator's rights, they can also change sensible parameters.
13
13
14
-
.. note::
15
-
Owners have operators rights
16
14
17
-
In order to do something on the Smart Contract, like **signing** or **changing parameters**, you need to call every time a **requester** that will record you request and do it if it reaches ``operatorsForChange`` and respectively ``ownersForChange`` request count.
15
+
In order to do something on the Smart Contract, like **signing** or **changing parameters**, you need to call a **requester**. This requester will record you request and only process it if it reaches ``operatorsForChange`` (respectively ``ownersForChange``) request count.
18
16
19
17
.. warning::
20
18
An account can't be ``owner`` and ``operator`` at the same time.
21
19
22
-
By default, ULCDocKernel is configurated to work with one owner account. So, is you use the kernel with only one owner, the request part is totally transparent and then they are done immediately.
20
+
By default, ULCDocKernel is configurated to work with only one owner account (and no operators). If you use the kernel with only one owner, all your requests will be done immediately (as ``ownersForChange`` will be set to 1);.
23
21
24
22
25
-
How the requester works
23
+
Requester
26
24
-----------------------
27
25
28
-
When you want to do an action, all requesters will create a ``keccak256`` hash of the request and store it inside a mapping.
26
+
When you want to do an action, requesters will create a ``keccak256`` hash of the request and store it inside a mapping.
29
27
30
28
::
31
29
32
30
mapping(bytes32 => address[]) public doOwnerRequest;
33
31
mapping(bytes32 => address[]) public doOperatorRequest;
34
32
35
-
Then, each address who request the same thing will be added into an array and when it's length reaches ``operatorsForChange`` or ``ownersForChange``, the action requested is done.
33
+
Then, each time an address requests the same action, it will be added into an array. The action will be processed only when the array's length reaches the value ``operatorsForChange`` or ``ownersForChange``.
36
34
37
35
Constructor
38
36
-----------
39
37
38
+
By default, the creator of the smart contract is the owner, and everything is configurated to work with only one confirmation, as explained above.
39
+
40
40
::
41
41
42
42
constructor() public {
@@ -46,11 +46,13 @@ Constructor
46
46
operatorsForChange = 1;
47
47
}
48
48
49
-
By default, the creator of the smart contract is the owner and everything is configurated to work with only one confirmation.
50
49
51
-
Variables available
50
+
51
+
Variables
52
52
-------------------
53
53
54
+
Bellow are the variables used by the smart contract for operator management:
55
+
54
56
::
55
57
56
58
uint256 public ownerCount;
@@ -83,37 +85,49 @@ Variables available
83
85
address indexed newOperator
84
86
);
85
87
86
-
Functions available
88
+
Functions
87
89
-------------------
88
90
89
-
Basic setters
91
+
The ULCDocKernel smart contract lets you use different functions to interact with it, detailled bellow:
92
+
93
+
Setters (Requesters)
90
94
^^^^^^^^^^^^^
95
+
96
+
These functions allow you to manage owners and operators for this kernel. Keep in mind these behave like requesters, and as such need enough confirmations to work.
97
+
91
98
::
92
99
93
-
//Both need enough confirmations (they are requester too)
94
-
function setOperatorsForChange(uint256 _nb) external onlyOwner {}
100
+
// Set the number of operators needed for confirmation
101
+
function setOperatorsForChange(uint256 _nb) external onlyOwner {}
95
102
103
+
// Set the number of owners needed for confirmation
96
104
function setOwnersForChange(uint256 _nb) external onlyOwner {}
97
105
98
-
Requester
99
-
^^^^^^^^^
100
-
::
101
-
106
+
// Add a new kernel owner
102
107
function requestAddOwner(address _newOwner) external onlyOwner{}
103
108
109
+
// Add a new kernel operator
104
110
function requestAddOperator(address _newOperator) external onlyOwner {}
105
111
112
+
// Transfer kernel's ownership
106
113
function requestChangeOwner(address _oldOwner, address _newOwner) external onlyOwner{}
107
114
115
+
// Remove a kernel owner
108
116
function requestRemoveOwner(address _removableOwner) external onlyOwner{}
109
117
118
+
// Remove a kernel operator
110
119
function requestRemoveOperator(address _removableOperator) external onlyOwner{}
111
120
121
+
112
122
.. info::
113
-
Don't forget to update ``ownersForChange`` or ``operatorsForChange`` if you want to modify number of confirmations before doing an action.
123
+
Do not forget to update ``ownersForChange`` or ``operatorsForChange`` if you want to modify the number of confirmations before doing an action.
124
+
114
125
115
126
Getters
116
127
^^^^^^^
128
+
129
+
These functions allow you to get information on the kernel. As these are not requesters, you do not need to have enough confirmations to use them.
130
+
117
131
::
118
132
119
133
//Returns all adresses who approved the keccak256 operator request
@@ -125,5 +139,5 @@ Getters
125
139
//Returns all adresses who approved the keccak256 owner request
126
140
function getOwnerRequest(bytes32 _theKey) external view returns(address[] memory) {}
127
141
128
-
//Returns numbers of owners who confirmed the keccak256 request.
142
+
//Returns the number of owners who confirmed the keccak256 request.
129
143
function getOwnerRequestLength(bytes32 _theKey) external view returns(uint256) {}
ULCDocument is designed to resist in an attack with **minority key stealing.** That mean you need to have these conditions :
7
+
ULCDocument is designed to resist **minority key stealing** attacks, as long as you meet those requirements:
8
8
9
-
* Attacker has **less than** ``ownersForChange`` **and** ``operatorsForChange`` keys stolen
10
-
* You have at least ``ownersForChange`` keys available
9
+
* Attacker must have **less than** ``ownersForChange`` **and** ``operatorsForChange`` keys stolen
10
+
* You must have at least ``ownersForChange`` keys available
11
11
12
12
.. info::
13
-
We recommand you to have ``ownersForChange`` number of recovery *owner accounts* in cold storage and store all your accounts configurated at different physical servers, and if possible in a different network.
13
+
We recommend you to have ``ownersForChange`` number of recovery *owner accounts* in cold storage and store all your accounts configurated at different physical servers, and if possible in a different network.
14
14
15
15
.. warning::
16
-
If you are an organisation, don't give all *owner accounts* to the same person!
16
+
If you are an organisation, do not give all your *owner accounts* to the same person!
17
17
18
-
Possible recovery
18
+
Recovery
19
19
-----------------
20
20
21
-
Clean compromised accounts
21
+
Clean Compromised Accounts
22
22
^^^^^^^^^^^^^^^^^^^^^^^^^^
23
23
24
-
First remove all compromised ``owners`` and ``operators`` with associated functions (see :ref:`MultiRoles <MultiRoles>`).
24
+
First remove all compromised ``owners`` and ``operators`` using associated functions (see :ref:`MultiRoles <MultiRoles>` section).
25
25
26
-
You need now to have ``operatorsForChange`` available accounts.
26
+
Then, you need to have at least ``operatorsForChange`` available accounts.
27
27
28
-
Clean requests
28
+
Clean Requests
29
29
^^^^^^^^^^^^^^
30
30
31
-
If attacker started to sign documents (but can't confirm it, as he does't have enough accounts), then you need to clear it by using ``clearDocument`` function.
31
+
If an attacker started to sign documents (but can't confirm it, as he does't have enough accounts), then you need to clear it by using the ``clearDocument`` function below:
32
32
33
33
::
34
34
35
35
function clearDocument(bytes32 _SignatureHash) external atLeastOperator notUpgraded whenNotPaused {}
36
36
37
37
.. note::
38
-
You can't clear a document if it is already signed or revoked.
38
+
You can't clear a document if it has already been signed or revoked.
39
39
40
-
If attacker started to revoke documents you can also clear the request (and delete possible ``revoked_reason`` added)
40
+
If an attacker started to revoke documents you can also clear the request (and delete possible ``revoked_reason`` added with it) using the function below:
41
41
42
42
::
43
43
44
44
function clearRevokeProcess(bytes32 _SignatureHash) external atLeastOperator notUpgraded whenNotPaused {}
45
45
46
46
.. note::
47
-
You can't clear a document revoke if it is already revoked.
47
+
You can't clear a document revoke request if it has already revoked.
48
48
49
-
If attacker started to request a selfdestruct, you can clear the requester counter :
49
+
If an attacker started to request a selfdestruct, you can clear the requester counter using the function below:
50
50
51
51
::
52
52
53
53
//note : only a compromised owner account can request kill().
54
54
function clearKill() external onlyOwner {}
55
55
56
-
Contest other operations
56
+
Contest Other Operations
57
57
^^^^^^^^^^^^^^^^^^^^^^^^
58
58
59
-
Owners can also use a *lower level* of cleaning by reseting every requests that they want.
59
+
Owners can also use a *lower level* of cleaning by reseting every request that they want.
60
60
61
61
::
62
62
63
63
/**
64
64
* @dev Delete the request queue for that action. Used to save gaz if there is a lot of owners or
65
-
in security purpose to reset the action agreed counter.
65
+
for security purposes, to reset the action agreed counter.
66
66
*/
67
67
function requestOwnerContest(bytes32 _doRequestContest) external onlyOwner {}
68
68
69
69
function requestOperatorContest(bytes32 _doRequestContest) external atLeastOperator {}
70
70
71
71
.. note::
72
-
To reset a counter, you first need to know which requests has been created by attacker. Then you need to calculate ``bytes32`` hash of the request and call *contester functions*
72
+
To reset a counter, you first need to know which request has been created by the attacker. Then you need to calculate the ``bytes32`` hash of the request and call *contester functions*
0 commit comments