Skip to content

Commit 42a48d8

Browse files
foriequal0majecty
foriequal0
authored and
majecty
committed
Revise docs for staking
1 parent f2c226a commit 42a48d8

File tree

2 files changed

+112
-142
lines changed

2 files changed

+112
-142
lines changed

‎spec/Dynamic-Validator.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@
4343
9. No *SELF_NOMINATE* during **RELEASE_PERIOD**
4444

4545
## Term
46-
The term is a period when one elected validator set works, and lasts for almost an hour.
46+
A term is a period when one elected validator set works, and lasts for almost an hour.
4747
The block that has a different generation hour from the parent block's is the last block of a term.
4848
CodeChain elects a new validator set after all rewards of the block is given.
4949

@@ -220,7 +220,7 @@ The transaction fails when the delegator revokes more than it delegates.
220220
* next_delegatee
221221
* quantity
222222

223-
This is an atomic version of `REVOKE (previous_delegatee, quantity)` + `DELEGATE (next_delegatee, quantity)`. It works as if two transactions are applied in a sequence, but the effect is atomic. The restrictions of the transaction are the same with both `REVOKE` and `DELGATE`.
223+
This is an atomic version of `REVOKE (previous_delegatee, quantity)` + `DELEGATE (next_delegatee, quantity)`. It works as if two transactions are applied in a sequence, but the effect is atomic. The restrictions of the transaction are the same with both `REVOKE` and `DELEGATE`.
224224

225225
### REPORT_DOUBLE_VOTE
226226
* message1

‎spec/Staking.md

Lines changed: 110 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ It is implemented as a custom action in CodeChain and enabled for the Tendermint
88
```
99
STAKING_CUSTOM_ACTION_ID = 2;
1010
11-
makeKey(...fragments) = rlp([
11+
makeKey(...fragments) = blake256(rlp([
1212
"ActionData",
1313
STAKING_CUSTOM_ACTION_ID,
1414
[...fragments]
15-
])
15+
]))
1616
```
1717

1818
## List of CCS holders
@@ -47,16 +47,48 @@ makeKey(...fragments) = rlp([
4747
A `delegatee` is an `AccountId`, and the `quantity` is a non-zero `u64` amount of CCS that a `delegator` delegated to a `delegatee`.
4848
The RLP-encoded non-empty list should be sorted by a `delegatee` in ascending order, and every `delegatee` should be unique.
4949

50-
## Pending Revocations
50+
## List of Candidates
5151

52-
* State Key: `makeKey("Revocations")`
52+
* State Key: `makeKey("Candidates")`
53+
* Value: `rlp(list of [pubkey, deposit, nominations_ends_at, metadata])`
5354

54-
* Value: `rlp(list of [delegator, delegatee, endTime, quantity])`
55+
The `pubkey` is a public key of a self-nominated candidate.
56+
The `deposit` is a `u64` amount of CCS deposited by the candidate and `nomination_ends_at` is a `u64` term id when the entry will expire.
57+
The `metadata` is a `bytes` that can store a short amount of data that expresses or advertises themselves.
58+
The order of it is constantly changed as the candidates send a self-nominate transaction and the term finishes.
59+
See the 'Candidate prioritizing' section of [dynamic validator](./Dynamic-Validator.md#Candidate-prioritizing).
5560

56-
A `delegator` is an `AccountId` who has delegated CCS to a `delegatee`, which is also an `AccountId`.
57-
`endTime` is a Unix time in UTC that specifies when the revocation will finally end. `quantity` is the `u64` amount of CCC that is going to be revoked.
58-
The RLP-encoded non-empty list should be sorted by `endTime` in ascending order.
59-
When multiple revocations have the same `endTime`, then the revocation created earlier (a block number is smaller, a transaction index is smaller) must have a smaller index.
61+
## List of jailed accounts
62+
63+
* State Key: `makeKey("Jailed")`
64+
* Value: `rlp(list of [account, deposit, custody_until, released_at])`
65+
66+
The `account` is an `AccountId`, and the `deposit` is a `u64` amount of CCS deposited before the candidate is jailed.
67+
A jailed candidate can self-nominate and be removed from the list after the term id is greater or equal than a `u64` value of `custody_until`, and it is automatically removed when the term id is greater or equal than a `u64` value of `released_at`.
68+
The RLP-encoded non-empty list should be sorted by `account` in ascending order, and every `account` should be unique.
69+
70+
## List of banned accounts
71+
72+
* State Key: `makeKey("Banned")`
73+
* Value: `rlp(list of account)`
74+
75+
The `account` is an `AccountId`.
76+
77+
## Current validator set
78+
79+
* State Key: `makeKey("Validators")`
80+
* Value: `rlp(list of [weight, delegation, deposit, pubkey])`
81+
82+
See 'How to update validators' section in [dynamic validator](./Dynamic-Validator.md#How-to-update-validators).
83+
84+
## Intermediate rewards
85+
86+
* State Key: `makeKey("IntermediateRewards")`
87+
* Value: `rlp([list of [account,quantity], list of [account,quantity]])`
88+
89+
The `address` is an `AccountId`, and `quantity` is a `u64` value of CCC. The value is an RLP encoded list of two lists.
90+
The first list is the rewards of the previous term, and the second list is the rewards of the current term.
91+
Each list is sorted by `account` in ascending order, and every `account` in a list should be unique.
6092

6193
# Staking Actions
6294

@@ -187,7 +219,7 @@ state = {
187219
188220
```
189221

190-
## RequestRevoke
222+
## Revoke
191223

192224
### Action
193225

@@ -196,14 +228,11 @@ state = {
196228
- A `delegatee` is an `AccountId`.
197229
- `quantity` is a non-zero `u64` amount of CCS to revoke from `delegatee`.
198230

199-
This action will queue a pending revocation rather than revoke immediately.
200-
A pending revocation is `[delegator, delegatee, endTime, quantity]`, where `endTime` is set as the `timestamp of a block + REVOKE_PENDING_DURATION`.
201-
A `delegator` cannot `RequestRevoke` more than the amount of delegated CCS to a `delegatee` minus the sum of the pending revocations between them.
231+
This action will revoke delegated CCS from a `delegatee` immediately.
232+
A `delegator` cannot `Revoke` more than the amount of delegated CCS to a `delegatee`.
202233

203234
### Example
204235

205-
`REVOKE_PENDING_DURATION` is 500 in this example.
206-
207236
```
208237
state = {
209238
stakeholders: [ "0x23..45", "0xAB..CD" ],
@@ -216,143 +245,132 @@ state = {
216245
}
217246
}
218247
219-
> "0xAB..CD" sends staking action [3, "0x01..23", 100] at block timestamp 123400
248+
> "0xAB..CD" sends staking action [3, "0x01..23", 100]
220249
221250
state = {
222251
stakeholders: [ "0x23..45", "0xAB..CD" ],
223252
balance: {
224-
"0xAB..CD": 690,
253+
"0xAB..CD": 790,
225254
},
226255
delegation: {
227256
"0x23..45": [ ["0x01..23", 500] ],
228-
"0xAB..CD": [ ["0x01..23", 200], ["0x23..45", 110] ]
257+
"0xAB..CD": [ ["0x01..23", 200], ["0x23..45", 10] ]
229258
},
230-
revocations: [ ["0xAB..CD", "0x01..23", 123900, 100] ]
231259
}
232260
233-
> "0xAB..CD" sends staking action [3, "0x01..23", 50"] at block timestamp 123500
261+
> "0xAB..CD" sends staking action [3, "0x01..23", 50"]
234262
235263
state = {
236264
stakeholders: [ "0x23..45", "0xAB..CD" ],
237265
balance: {
238-
"0xAB..CD": 690,
266+
"0xAB..CD": 840,
239267
},
240268
delegation: {
241269
"0x23..45": [ ["0x01..23", 500] ],
242-
"0xAB..CD": [ ["0x01..23", 200], ["0x23..45", 110] ]
270+
"0xAB..CD": [ ["0x01..23", 150], ["0x23..45", 10] ]
243271
},
244-
revocations: [
245-
["0xAB..CD", "0x01..23", 123900, 100],
246-
["0xAB..CD", "0x01..23", 124000, 50],
247-
]
248272
}
249273
250-
> "0x23..45" sends staking action [3, "0x01..23", 500"] at block timestamp 123600
274+
> "0x23..45" sends staking action [3, "0x01..23", 500"]
251275
252276
state = {
253277
stakeholders: [ "0x23..45", "0xAB..CD" ],
254278
balance: {
255-
"0xAB..CD": 690,
279+
"0xAB..CD": 1340,
256280
},
257281
delegation: {
258-
"0x23..45": [ ["0x01..23", 500] ],
259282
"0xAB..CD": [ ["0x01..23", 200], ["0x23..45", 110] ]
260-
},
261-
revocations: [
262-
["0xAB..CD", "0x01..23", 123900, 100],
263-
["0xAB..CD", "0x01..23", 124000, 50],
264-
["0x23..45", "0x01..23", 124100, 500],
265-
]
283+
}
266284
}
285+
```
267286

268-
> after a block with timestamp 123900
269287

270-
state = {
271-
stakeholders: [ "0x23..45", "0xAB..CD" ],
272-
balance: {
273-
"0xAB..CD": 790,
274-
},
275-
delegation: {
276-
"0x23..45": [ ["0x01..23", 500] ],
277-
"0xAB..CD": [ ["0x01..23", 100], ["0x23..45", 110] ]
278-
},
279-
revocations: [
280-
["0xAB..CD", "0x01..23", 124000, 50],
281-
["0x23..45", "0x01..23", 124100, 500],
282-
]
283-
}
288+
## RedelegateCCS
284289

285-
> after a block with timestamp 124000
290+
### Action
286291

292+
* Format: `[6, prev_delegatee, next_delegatee, quantity]`
293+
- A `prev_delegatee` is an `AccountId`.
294+
- A `next_delegatee` is an `AccountId`.
295+
- `quantity` is a `u64` amount of CCS to redelegate to `next_delegatee` from `prev_delegatee`.
296+
297+
Executing this action is the same as executing the revoke action and the delegate action. The `quantity` should be less than the delegated quantity of `prev_delegatee` from the sender.
298+
299+
### Example
300+
301+
```
287302
state = {
288303
stakeholders: [ "0x23..45", "0xAB..CD" ],
289304
balance: {
290-
"0xAB..CD": 840,
305+
"0x23..45": 500,
306+
"0xAB..CD": 900,
291307
},
292308
delegation: {
293-
"0x23..45": [ ["0x01..23", 500] ],
294-
"0xAB..CD": [ ["0x01..23", 50], ["0x23..45", 110] ]
295-
},
296-
revocations: [
297-
["0x23..45", "0x01..23", 124100, 500],
298-
]
309+
"0xAB..CD": [ ["0x23..45", 100] ]
310+
}
299311
}
300312
301-
> after a block with timestamp 124100
313+
> "0xAB..CD" sends staking action [ 6, "0x23..45", "0x67..89", 10 ]
302314
303315
state = {
304316
stakeholders: [ "0x23..45", "0xAB..CD" ],
305317
balance: {
306318
"0x23..45": 500,
307-
"0xAB..CD": 840,
319+
"0xAB..CD": 900,
308320
},
309321
delegation: {
310-
"0xAB..CD": [ ["0x01..23", 50], ["0x23..45", 110] ]
322+
"0xAB..CD": [ ["0x23..45", 90], ["0x67..89", 10] ]
311323
}
312324
}
313325
```
314326

327+
## SelfNominate
315328

316-
## RedelegateCCS
329+
### Action
330+
331+
* Format: `[ 4, deposit, metadata ]`
332+
333+
See SELF_NOMINATE section in [Dynamic Validator](./Dynamic-Validator.md#SELF_NOMINATE)
334+
335+
## ReportDoubleVote
317336

318337
### Action
319338

320-
* Format: `[6, prev_delegatee, next_delegatee, quantity]`
321-
- A `prev_delegatee` is an `AccountId`.
322-
- A `next_delegatee` is an `AccountId`.
323-
- `quantity` is a `u64` amount of CCS to redelegate to `next_delegatee` from `prev_delegatee`.
339+
* Format: `[ 5, metadata_seq, params, ...signatrues ]`
324340

325-
Executing this action is the same as executing the revoke action and the delegate action. The `quantity` should be less than the delegated quantity of `prev_delegatee` from the sender.
341+
See REPORT_DOUBLE_VOTE section in [Dynamic Validator](./Dynamic-Validator.md#REPORT_DOUBLE_VOTE)
326342

327-
### Example
343+
## ChangeParameters
344+
This transaction will change the common parameters when more than half of the stakeholders agree.
345+
It does not change other fields of the scheme file because there are fields related to the genesis block.
328346

329-
```
347+
It also does not provide a voting feature.
348+
The vote initiator should collect the signatures through the off-chain.
349+
350+
This transaction increases the `seq` of `Metadata` and changes the `params` of `Metadata`.
351+
The changed parameters are applied from the next block that the changing transaction is included in.
352+
353+
The new parameters are used from the next block.
354+
355+
### Action
356+
`[ 0xFF, metadata_seq, new_parameters, ...signatures ]`
357+
358+
#### metadata_seq
359+
The transaction fails if the metadata_seq is different from the `seq` of `Metadata` and is introduced to prevent replay attacks.
330360

331-
state = {
332-
stakeholders: [ "0x23..45", "0xAB..CD" ],
333-
balance: {
334-
"0x23..45": 500,
335-
"0xAB..CD": 900,
336-
},
337-
delegation: {
338-
"0xAB..CD": [ ["0x23..45", 100] ]
339-
}
340-
}
341-
342-
> "0xAB..CD" sends staking action [ 6, "0x23..45", "0x67..89", 10 ]
343-
344-
state = {
345-
stakeholders: [ "0x23..45", "0xAB..CD" ],
346-
balance: {
347-
"0x23..45": 500,
348-
"0xAB..CD": 900,
349-
},
350-
delegation: {
351-
"0xAB..CD": [ ["0x23..45", 90], ["0x67..89", 10] ]
352-
}
353-
}
361+
#### new_parameters
362+
```
363+
new_parameters := [ (value,)* ]
354364
365+
value := usize | u64 | boolean | string
355366
```
367+
It is the list of the values that the transaction changes.
368+
The stakeholder MUST NOT sign the transaction when the type of value is not a type that the key expected.
369+
370+
#### signatures
371+
`signatures` are the ECDSA signatures of stakeholders.
372+
The stakeholders should send the signature of `blake256(rlp_encode([ 0xFF, metadata_seq, new_parameters ]))` to the vote initiator if they agree to the change.
373+
The transaction is valid only if more than half of the stakeholders agree.
356374

357375
# Fee distribution
358376

@@ -392,51 +410,3 @@ share of "0x23..45" = Math.floor(35 * ( 500 / (500 + 1000))) = 11
392410
share of "0xAB..CD" = Math.floor(35 * (1000 / (500 + 1000))) = 23
393411
remaing share (of author) = 110 - (11 + 23) = 76
394412
```
395-
396-
## ChangeParameters
397-
This transaction will change the common parameters when more than half of the stakeholders agree.
398-
It does not change other fields of the scheme file because there are fields related to the genesis block.
399-
400-
It also does not provide a voting feature.
401-
The vote initiator should collect the signatures through the off-chain.
402-
403-
This transaction increases the `seq` of `Metadata` and changes the `params` of `Metadata`.
404-
The changed parameters are applied from the next block that the changing transaction is included.
405-
406-
The new parameters are used from the next block.
407-
408-
### Action
409-
`[ 0xFF, metadata_seq, new_parameters, ...signatures ]`
410-
411-
#### metadata_seq
412-
The transaction fails if the metadata_seq is different from the `seq` of `Metadata` and is introduced to prevent replay attacks.
413-
414-
#### new_parameters
415-
```
416-
new_parameters := [ (value,)* ]
417-
418-
value := usize | u64 | boolean | string
419-
```
420-
It is the list of the values that the transaction changes.
421-
The stakeholder MUST NOT sign the transaction when the type of value is not a type that the key expected.
422-
423-
#### signatures
424-
`signatures` are the ECDSA signatures of stakeholders.
425-
The stakeholders should send the signature of `blake256(rlp_encode([ 0xFF, metadata_seq, new_parameters ]))` to the vote initiator if they agree to the change.
426-
The transaction is valid only if more than half of the stakeholders agree.
427-
428-
# Revocation
429-
430-
`RequestRevoke` will queue a pending revocation instead of revoking a delegation immediately.
431-
The revocation will be delayed by a certain amount of time (`REVOKE_PENDING_DURATION`) to prevent abuse.
432-
It will be processed when a block whose timestamp is greater than or equal to the time when `endTime` is created.
433-
The amount of undelegated CCS of the `delegator` will be increased by `quantity` upon revocation, and the amount of delegated CCS that the `delegator` has delegated to the `delegatee` will be decreased by `quantity`, and the pending revocation will be removed from the revocation queue.
434-
Queues and delegations that become empty should be removed from the state.
435-
436-
## `REVOKE_PENDING_DURATION`
437-
438-
It is 3 weeks in mainnet (1814400 seconds)
439-
440-
## Example
441-
442-
See Example of RequestRevoke in Staking Actions

0 commit comments

Comments
 (0)