/
api.go
596 lines (489 loc) · 20.6 KB
/
api.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
// Package api implements the staking backend API.
package api
import (
"fmt"
"github.com/oasisprotocol/oasis-core/go/common/crypto/hash"
"github.com/oasisprotocol/oasis-core/go/common/quantity"
beacon "github.com/oasisprotocol/nexus/coreapi/v21.1.1/beacon/api"
"github.com/oasisprotocol/nexus/coreapi/v21.1.1/consensus/api/transaction"
)
const (
// ModuleName is a unique module name for the staking module.
ModuleName = "staking"
// LogEventGeneralAdjustment is a log event value that signals adjustment
// of an account's general balance due to a roothash message.
LogEventGeneralAdjustment = "staking/general_adjustment"
)
// removed var block
// Backend is a staking implementation.
// removed interface
// ThresholdQuery is a threshold query.
type ThresholdQuery struct {
Height int64 `json:"height"`
Kind ThresholdKind `json:"kind"`
}
// OwnerQuery is an owner query.
type OwnerQuery struct {
Height int64 `json:"height"`
Owner Address `json:"owner"`
}
// AllowanceQuery is an allowance query.
type AllowanceQuery struct {
Height int64 `json:"height"`
Owner Address `json:"owner"`
Beneficiary Address `json:"beneficiary"`
}
// TransferEvent is the event emitted when stake is transferred, either by a
// call to Transfer or Withdraw.
type TransferEvent struct {
From Address `json:"from"`
To Address `json:"to"`
Amount quantity.Quantity `json:"amount"`
}
// BurnEvent is the event emitted when stake is destroyed via a call to Burn.
type BurnEvent struct {
Owner Address `json:"owner"`
Amount quantity.Quantity `json:"amount"`
}
// EscrowEvent is an escrow event.
type EscrowEvent struct {
Add *AddEscrowEvent `json:"add,omitempty"`
Take *TakeEscrowEvent `json:"take,omitempty"`
DebondingStart *DebondingStartEscrowEvent `json:"debonding_start,omitempty"` // Only emitted at _some_ heights; introduced in oasis-core v21.3.0 mid-Cobalt.
Reclaim *ReclaimEscrowEvent `json:"reclaim,omitempty"`
}
// Event signifies a staking event, returned via GetEvents.
type Event struct {
Height int64 `json:"height,omitempty"`
TxHash hash.Hash `json:"tx_hash,omitempty"`
Transfer *TransferEvent `json:"transfer,omitempty"`
Burn *BurnEvent `json:"burn,omitempty"`
Escrow *EscrowEvent `json:"escrow,omitempty"`
AllowanceChange *AllowanceChangeEvent `json:"allowance_change,omitempty"`
}
// AddEscrowEvent is the event emitted when stake is transferred into an escrow
// account.
type AddEscrowEvent struct {
Owner Address `json:"owner"`
Escrow Address `json:"escrow"`
Amount quantity.Quantity `json:"amount"`
NewShares quantity.Quantity `json:"new_shares"` // Only emitted at _some_ heights; introduced in oasis-core v21.2.0 mid-Cobalt.
}
// TakeEscrowEvent is the event emitted when stake is taken from an escrow
// account (i.e. stake is slashed).
type TakeEscrowEvent struct {
Owner Address `json:"owner"`
Amount quantity.Quantity `json:"amount"`
}
// DebondingStartEvent is the event emitted when the debonding process has
// started and the given number of active shares have been moved into the
// debonding pool and started debonding.
//
// Note that the given amount is valid at the time of debonding start and
// may not correspond to the final debonded amount in case any escrowed
// stake is subject to slashing.
type DebondingStartEscrowEvent struct {
Owner Address `json:"owner"`
Escrow Address `json:"escrow"`
Amount quantity.Quantity `json:"amount"`
ActiveShares quantity.Quantity `json:"active_shares"`
DebondingShares quantity.Quantity `json:"debonding_shares"`
}
// ReclaimEscrowEvent is the event emitted when stake is reclaimed from an
// escrow account back into owner's general account.
type ReclaimEscrowEvent struct {
Owner Address `json:"owner"`
Escrow Address `json:"escrow"`
Amount quantity.Quantity `json:"amount"`
Shares quantity.Quantity `json:"shares"` // Only emitted at _some_ heights; introduced in oasis-core v21.2.0 mid-Cobalt.
}
// AllowanceChangeEvent is the event emitted when allowance is changed for a beneficiary.
type AllowanceChangeEvent struct { // nolint: maligned
Owner Address `json:"owner"`
Beneficiary Address `json:"beneficiary"`
Allowance quantity.Quantity `json:"allowance"`
Negative bool `json:"negative,omitempty"`
AmountChange quantity.Quantity `json:"amount_change"`
}
// Transfer is a stake transfer.
type Transfer struct {
To Address `json:"to"`
Amount quantity.Quantity `json:"amount"`
}
// PrettyPrint writes a pretty-printed representation of Transfer to the given
// writer.
// removed func
// PrettyType returns a representation of Transfer that can be used for pretty
// printing.
// removed func
// NewTransferTx creates a new transfer transaction.
// removed func
// Burn is a stake burn (destruction).
type Burn struct {
Amount quantity.Quantity `json:"amount"`
}
// PrettyPrint writes a pretty-printed representation of Burn to the given
// writer.
// removed func
// PrettyType returns a representation of Burn that can be used for pretty
// printing.
// removed func
// NewBurnTx creates a new burn transaction.
// removed func
// Escrow is a stake escrow.
type Escrow struct {
Account Address `json:"account"`
Amount quantity.Quantity `json:"amount"`
}
// PrettyPrint writes a pretty-printed representation of Escrow to the given
// writer.
// removed func
// PrettyType returns a representation of Escrow that can be used for pretty
// printing.
// removed func
// NewAddEscrowTx creates a new add escrow transaction.
// removed func
// ReclaimEscrow is a reclamation of stake from an escrow.
type ReclaimEscrow struct {
Account Address `json:"account"`
Shares quantity.Quantity `json:"shares"`
}
// PrettyPrint writes a pretty-printed representation of ReclaimEscrow to the
// given writer.
// removed func
// PrettyType returns a representation of Transfer that can be used for pretty
// printing.
// removed func
// NewReclaimEscrowTx creates a new reclaim escrow transaction.
// removed func
// AmendCommissionSchedule is an amendment to a commission schedule.
type AmendCommissionSchedule struct {
Amendment CommissionSchedule `json:"amendment"`
}
// PrettyPrint writes a pretty-printed representation of AmendCommissionSchedule
// to the given writer.
// removed func
// PrettyType returns a representation of AmendCommissionSchedule that can be
// used for pretty printing.
// removed func
// NewAmendCommissionScheduleTx creates a new amend commission schedule transaction.
// removed func
// Allow is a beneficiary allowance configuration.
type Allow struct {
Beneficiary Address `json:"beneficiary"`
Negative bool `json:"negative,omitempty"`
AmountChange quantity.Quantity `json:"amount_change"`
}
// PrettyPrint writes a pretty-printed representation of Allow to the given writer.
// removed func
// PrettyType returns a representation of Allow that can be used for pretty printing.
// removed func
// NewAllowTx creates a new beneficiary allowance configuration transaction.
// removed func
// Withdraw is a withdrawal from an account.
type Withdraw struct {
From Address `json:"from"`
Amount quantity.Quantity `json:"amount"`
}
// PrettyPrint writes a pretty-printed representation of Withdraw to the given writer.
// removed func
// PrettyType returns a representation of Withdraw that can be used for pretty printing.
// removed func
// NewWithdrawTx creates a new beneficiary allowance configuration transaction.
// removed func
// SharePool is a combined balance of several entries, the relative sizes
// of which are tracked through shares.
type SharePool struct {
Balance quantity.Quantity `json:"balance,omitempty"`
TotalShares quantity.Quantity `json:"total_shares,omitempty"`
}
// PrettyPrint writes a pretty-printed representation of SharePool to the given
// writer.
// removed func
// PrettyType returns a representation of SharePool that can be used for pretty
// printing.
// removed func
// sharesForStake computes the amount of shares for the given amount of base units.
// removed func
// Deposit moves stake into the combined balance, raising the shares.
// If an error occurs, the pool and affected accounts are left in an invalid state.
// removed func
// StakeForShares computes the amount of base units for the given amount of shares.
// removed func
// Withdraw moves stake out of the combined balance, reducing the shares.
// If an error occurs, the pool and affected accounts are left in an invalid state.
// removed func
// ThresholdKind is the kind of staking threshold.
type ThresholdKind int
const (
KindEntity ThresholdKind = 0
KindNodeValidator ThresholdKind = 1
KindNodeCompute ThresholdKind = 2
KindNodeStorage ThresholdKind = 3
KindNodeKeyManager ThresholdKind = 4
KindRuntimeCompute ThresholdKind = 5
KindRuntimeKeyManager ThresholdKind = 6
KindMax = KindRuntimeKeyManager
KindEntityName = "entity"
KindNodeValidatorName = "node-validator"
KindNodeComputeName = "node-compute"
KindNodeStorageName = "node-storage"
KindNodeKeyManagerName = "node-keymanager"
KindRuntimeComputeName = "runtime-compute"
KindRuntimeKeyManagerName = "runtime-keymanager"
)
// String returns the string representation of a ThresholdKind.
func (k ThresholdKind) String() string {
switch k {
case KindEntity:
return KindEntityName
case KindNodeValidator:
return KindNodeValidatorName
case KindNodeCompute:
return KindNodeComputeName
case KindNodeStorage:
return KindNodeStorageName
case KindNodeKeyManager:
return KindNodeKeyManagerName
case KindRuntimeCompute:
return KindRuntimeComputeName
case KindRuntimeKeyManager:
return KindRuntimeKeyManagerName
default:
return "[unknown threshold kind]"
}
}
// MarshalText encodes a ThresholdKind into text form.
func (k ThresholdKind) MarshalText() ([]byte, error) {
return []byte(k.String()), nil
}
// UnmarshalText decodes a text slice into a ThresholdKind.
func (k *ThresholdKind) UnmarshalText(text []byte) error {
switch string(text) {
case KindEntityName:
*k = KindEntity
case KindNodeValidatorName:
*k = KindNodeValidator
case KindNodeComputeName:
*k = KindNodeCompute
case KindNodeStorageName:
*k = KindNodeStorage
case KindNodeKeyManagerName:
*k = KindNodeKeyManager
case KindRuntimeComputeName:
*k = KindRuntimeCompute
case KindRuntimeKeyManagerName:
*k = KindRuntimeKeyManager
default:
return fmt.Errorf("%w: %s", fmt.Errorf("invalid threshold"), string(text))
}
return nil
}
// StakeClaim is a unique stake claim identifier.
type StakeClaim string
// StakeThreshold is a stake threshold as used in the stake accumulator.
type StakeThreshold struct {
// Global is a reference to a global stake threshold.
Global *ThresholdKind `json:"global,omitempty"`
// Constant is the value for a specific threshold.
Constant *quantity.Quantity `json:"const,omitempty"`
}
// String returns a string representation of a stake threshold.
func (st StakeThreshold) String() string {
switch {
case st.Global != nil:
return fmt.Sprintf("<global: %s>", *st.Global)
case st.Constant != nil:
return fmt.Sprintf("<constant: %s>", st.Constant)
default:
return "<malformed>"
}
}
// PrettyPrint writes a pretty-printed representation of StakeThreshold to the
// given writer.
// removed func
// PrettyType returns a representation of StakeThreshold that can be used for
// pretty printing.
// removed func
// Equal compares vs another stake threshold for equality.
// removed func
// Value returns the value of the stake threshold.
// removed func
// GlobalStakeThreshold creates a new global StakeThreshold.
// removed func
// GlobalStakeThresholds creates a new list of global StakeThresholds.
// removed func
// StakeAccumulator is a per-escrow-account stake accumulator.
type StakeAccumulator struct {
// Claims are the stake claims that must be satisfied at any given point. Adding a new claim is
// only possible if all of the existing claims plus the new claim is satisfied.
Claims map[StakeClaim][]StakeThreshold `json:"claims,omitempty"`
}
// PrettyPrint writes a pretty-printed representation of StakeAccumulator to the
// given writer.
// removed func
// PrettyType returns a representation of StakeAccumulator that can be used for
// pretty printing.
// removed func
// AddClaimUnchecked adds a new claim without checking its validity.
// removed func
// RemoveClaim removes a given stake claim.
//
// It is an error if the stake claim does not exist.
// removed func
// TotalClaims computes the total amount of stake claims in the accumulator.
// removed func
// GeneralAccount is a general-purpose account.
type GeneralAccount struct {
Balance quantity.Quantity `json:"balance,omitempty"`
Nonce uint64 `json:"nonce,omitempty"`
Allowances map[Address]quantity.Quantity `json:"allowances,omitempty"`
}
// PrettyPrint writes a pretty-printed representation of GeneralAccount to the
// given writer.
// removed func
// PrettyType returns a representation of GeneralAccount that can be used for
// pretty printing.
// removed func
// EscrowAccount is an escrow account the balance of which is subject to
// special delegation provisions and a debonding period.
type EscrowAccount struct {
Active SharePool `json:"active,omitempty"`
Debonding SharePool `json:"debonding,omitempty"`
CommissionSchedule CommissionSchedule `json:"commission_schedule,omitempty"`
StakeAccumulator StakeAccumulator `json:"stake_accumulator,omitempty"`
}
// PrettyPrint writes a pretty-printed representation of EscrowAccount to the
// given writer.
// removed func
// PrettyType returns a representation of EscrowAccount that can be used for
// pretty printing.
// removed func
// CheckStakeClaims checks whether the escrow account balance satisfies all the stake claims.
// removed func
// AddStakeClaim attempts to add a stake claim to the given escrow account.
//
// In case there is insufficient stake to cover the claim or an error occurrs, no modifications are
// made to the stake accumulator.
// removed func
// RemoveStakeClaim removes a given stake claim.
//
// It is an error if the stake claim does not exist.
// removed func
// Account is an entry in the staking ledger.
//
// The same ledger entry can hold both general and escrow accounts. Escrow
// accounts are used to hold funds delegated for staking.
type Account struct {
General GeneralAccount `json:"general,omitempty"`
Escrow EscrowAccount `json:"escrow,omitempty"`
}
// PrettyPrint writes a pretty-printed representation of Account to the given
// writer.
// removed func
// PrettyType returns a representation of Account that can be used for pretty
// printing.
// removed func
// Delegation is a delegation descriptor.
type Delegation struct {
Shares quantity.Quantity `json:"shares"`
}
// DelegationInfo is a delegation descriptor with additional information.
//
// Additional information contains the share pool the delegation belongs to.
type DelegationInfo struct {
Delegation
Pool SharePool `json:"pool"`
}
// DebondingDelegation is a debonding delegation descriptor.
type DebondingDelegation struct {
Shares quantity.Quantity `json:"shares"`
DebondEndTime beacon.EpochTime `json:"debond_end"`
}
// Merge merges debonding delegations with same debond end time by summing
// the shares amounts.
// removed func
// DebondingDelegationInfo is a debonding delegation descriptor with additional
// information.
//
// Additional information contains the share pool the debonding delegation
// belongs to.
type DebondingDelegationInfo struct {
DebondingDelegation
Pool SharePool `json:"pool"`
}
// Genesis is the initial staking state for use in the genesis block.
type Genesis struct {
// Parameters are the staking consensus parameters.
Parameters ConsensusParameters `json:"params"`
// TokenSymbol is the token's ticker symbol.
// Only upper case A-Z characters are allowed.
TokenSymbol string `json:"token_symbol"`
// TokenValueExponent is the token's value base-10 exponent, i.e.
// 1 token = 10**TokenValueExponent base units.
TokenValueExponent uint8 `json:"token_value_exponent"`
// TokenSupply is the network's total amount of stake in base units.
TotalSupply quantity.Quantity `json:"total_supply"`
// CommonPool is the network's common stake pool.
CommonPool quantity.Quantity `json:"common_pool"`
// LastBlockFees are the collected fees for previous block.
LastBlockFees quantity.Quantity `json:"last_block_fees"`
// GovernanceDeposits are network's governance deposits.
GovernanceDeposits quantity.Quantity `json:"governance_deposits"`
// Ledger is a map of staking accounts.
Ledger map[Address]*Account `json:"ledger,omitempty"`
// Delegations is a nested map of staking delegations of the form:
// DELEGATEE-ACCOUNT-ADDRESS: DELEGATOR-ACCOUNT-ADDRESS: DELEGATION.
Delegations map[Address]map[Address]*Delegation `json:"delegations,omitempty"`
// DebondingDelegations is a nested map of staking delegations of the form:
// DEBONDING-DELEGATEE-ACCOUNT-ADDRESS: DEBONDING-DELEGATOR-ACCOUNT-ADDRESS: list of DEBONDING-DELEGATIONs.
DebondingDelegations map[Address]map[Address][]*DebondingDelegation `json:"debonding_delegations,omitempty"`
}
// ConsensusParameters are the staking consensus parameters.
type ConsensusParameters struct { // nolint: maligned
Thresholds map[ThresholdKind]quantity.Quantity `json:"thresholds,omitempty"`
DebondingInterval beacon.EpochTime `json:"debonding_interval,omitempty"`
RewardSchedule []RewardStep `json:"reward_schedule,omitempty"`
SigningRewardThresholdNumerator uint64 `json:"signing_reward_threshold_numerator,omitempty"`
SigningRewardThresholdDenominator uint64 `json:"signing_reward_threshold_denominator,omitempty"`
CommissionScheduleRules CommissionScheduleRules `json:"commission_schedule_rules,omitempty"`
Slashing map[SlashReason]Slash `json:"slashing,omitempty"`
GasCosts transaction.Costs `json:"gas_costs,omitempty"`
MinDelegationAmount quantity.Quantity `json:"min_delegation"`
DisableTransfers bool `json:"disable_transfers,omitempty"`
DisableDelegation bool `json:"disable_delegation,omitempty"`
UndisableTransfersFrom map[Address]bool `json:"undisable_transfers_from,omitempty"`
// AllowEscrowMessages can be used to allow runtimes to perform AddEscrow
// and ReclaimEscrow via runtime messages.
AllowEscrowMessages bool `json:"allow_escrow_messages,omitempty"`
// MaxAllowances is the maximum number of allowances an account can have. Zero means disabled.
MaxAllowances uint32 `json:"max_allowances,omitempty"`
// FeeSplitWeightPropose is the proportion of block fee portions that go to the proposer.
FeeSplitWeightPropose quantity.Quantity `json:"fee_split_weight_propose"`
// FeeSplitWeightVote is the proportion of block fee portions that go to the validator that votes.
FeeSplitWeightVote quantity.Quantity `json:"fee_split_weight_vote"`
// FeeSplitWeightNextPropose is the proportion of block fee portions that go to the next block's proposer.
FeeSplitWeightNextPropose quantity.Quantity `json:"fee_split_weight_next_propose"`
// RewardFactorEpochSigned is the factor for a reward distributed per epoch to
// entities that have signed at least a threshold fraction of the blocks.
RewardFactorEpochSigned quantity.Quantity `json:"reward_factor_epoch_signed"`
// RewardFactorBlockProposed is the factor for a reward distributed per block
// to the entity that proposed the block.
RewardFactorBlockProposed quantity.Quantity `json:"reward_factor_block_proposed"`
}
const (
// GasOpTransfer is the gas operation identifier for transfer.
GasOpTransfer transaction.Op = "transfer"
// GasOpBurn is the gas operation identifier for burn.
GasOpBurn transaction.Op = "burn"
// GasOpAddEscrow is the gas operation identifier for add escrow.
GasOpAddEscrow transaction.Op = "add_escrow"
// GasOpReclaimEscrow is the gas operation identifier for reclaim escrow.
GasOpReclaimEscrow transaction.Op = "reclaim_escrow"
// GasOpAmendCommissionSchedule is the gas operation identifier for amend commission schedule.
GasOpAmendCommissionSchedule transaction.Op = "amend_commission_schedule"
// GasOpAllow is the gas operation identifier for allow.
GasOpAllow transaction.Op = "allow"
// GasOpWithdraw is the gas operation identifier for withdraw.
GasOpWithdraw transaction.Op = "withdraw"
)