[#105] alphabet: Add docs

Signed-off-by: Alex Vanin <alexey@nspcc.ru>
This commit is contained in:
Alex Vanin 2021-07-04 16:32:13 +03:00 committed by Alex Vanin
parent b6b3f17cd1
commit 2a6a46d462
2 changed files with 45 additions and 2 deletions

View file

@ -25,7 +25,8 @@ const (
version = 1
)
// OnNEP17Payment is a callback for NEP-17 compatible native GAS and NEO contracts.
// OnNEP17Payment is a callback for NEP-17 compatible native GAS and NEO
// contracts.
func OnNEP17Payment(from interop.Hash160, amount int, data interface{}) {
caller := runtime.GetCallingScriptHash()
if !common.BytesEqual(caller, []byte(gas.Hash)) && !common.BytesEqual(caller, []byte(neo.Hash)) {
@ -74,6 +75,8 @@ func _deploy(data interface{}, isUpdate bool) {
runtime.Log(name + " contract initialized")
}
// Migrate method updates contract source code and manifest. Can be invoked
// only by contract owner.
func Migrate(script []byte, manifest []byte, data interface{}) bool {
ctx := storage.GetReadOnlyContext()
@ -88,10 +91,12 @@ func Migrate(script []byte, manifest []byte, data interface{}) bool {
return true
}
// GAS returns amount of side chain GAS stored in contract account.
func Gas() int {
return gas.BalanceOf(runtime.GetExecutingScriptHash())
}
// NEO returns amount of side chain NEO stored in contract account.
func Neo() int {
return neo.BalanceOf(runtime.GetExecutingScriptHash())
}
@ -121,6 +126,16 @@ func checkPermission(ir []common.IRNode) bool {
return runtime.CheckWitness(node.PublicKey)
}
// Emit method produces side chain GAS and distributes it among Inner Ring nodes
// and proxy contract. Can be invoked only by Alphabet node of the Inner Ring.
//
// To produce GAS, alphabet contract transfers all available NEO from contract
// account to itself. If notary enabled, then 50% of the GAS in the contract account
// transferred to proxy contract. 43.75% of the GAS are equally distributed
// among all Inner Ring nodes. Remaining 6.25% of the GAS stays in the contract.
//
// If notary disabled, then 87.5% of the GAS are equally distributed among all
// Inner Ring nodes. Remaining 12.5% of the GAS stays in the contract.
func Emit() {
ctx := storage.GetReadOnlyContext()
notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@ -171,6 +186,13 @@ func Emit() {
}
}
// Vote method votes for side chain committee. Requires multisignature from
// Alphabet nodes of the Inner Ring.
//
// This method is used when governance changes list of Alphabet nodes of the
// Inner Ring. Alphabet nodes share keys with side chain validators, therefore
// it is required to change them as well. To do that NEO holders, which are
// alphabet contracts, should vote for new committee.
func Vote(epoch int, candidates []interop.PublicKey) {
ctx := storage.GetContext()
notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@ -240,11 +262,13 @@ func voteID(epoch interface{}, args []interop.PublicKey) []byte {
return crypto.Sha256(result)
}
// Name returns Glagolitic name of the contract.
func Name() string {
ctx := storage.GetReadOnlyContext()
return name(ctx)
}
// Version returns version of the contract.
func Version() int {
return version
}

View file

@ -1,2 +1,21 @@
// Alphabet contract description.
/*
Alphabet contract is a contract deployed in NeoFS side chain.
Alphabet contract is designed to support GAS producing and voting for new
validators in the side chain. NEO token is required to produce GAS and vote for
a new committee. If can be distributed among alphabet nodes of Inner Ring.
However, some of them may be malicious and some NEO can be lost. It will lead
to side chain economic destabilization. To avoid it, all 100 000 000 NEO are
distributed among all alphabet contracts.
To identify alphabet contracts, they are named with letters of the Glagolitic.
Names are set at contract deploy. Alphabet nodes of Inner Ring communicate with
one of the alphabetical contracts to emit GAS. To vote for a new list of side
chain committee, alphabet nodes of Inner Ring create multisignature transactions
for each alphabet contract.
Contract notifications
Alphabet contract does not produce notifications to process.
*/
package alphabet