[#105] balance: Add docs and fix naming

`CreateToken` method should not be public.
Fixed notification field names in `Mint` and `Burn`.

Signed-off-by: Alex Vanin <alexey@nspcc.ru>
This commit is contained in:
Alex Vanin 2021-07-06 18:55:04 +03:00 committed by Alex Vanin
parent f21c439e9c
commit a1a04f8a87
3 changed files with 139 additions and 6 deletions

View file

@ -22,6 +22,7 @@ type (
CirculationKey string CirculationKey string
} }
// Account structure stores metadata of each NeoFS balance account.
Account struct { Account struct {
// Active balance // Active balance
Balance int Balance int
@ -46,8 +47,7 @@ const (
var token Token var token Token
// CreateToken initializes the Token Interface for the Smart Contract to operate with. func createToken() Token {
func CreateToken() Token {
return Token{ return Token{
Symbol: symbol, Symbol: symbol,
Decimals: decimals, Decimals: decimals,
@ -56,7 +56,7 @@ func CreateToken() Token {
} }
func init() { func init() {
token = CreateToken() token = createToken()
} }
func _deploy(data interface{}, isUpdate bool) { func _deploy(data interface{}, isUpdate bool) {
@ -94,6 +94,8 @@ func _deploy(data interface{}, isUpdate bool) {
runtime.Log("balance contract initialized") runtime.Log("balance 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 { func Migrate(script []byte, manifest []byte, data interface{}) bool {
ctx := storage.GetReadOnlyContext() ctx := storage.GetReadOnlyContext()
@ -108,29 +110,49 @@ func Migrate(script []byte, manifest []byte, data interface{}) bool {
return true return true
} }
// Symbol is a NEP-17 standard method that returns NEOFS token symbol.
func Symbol() string { func Symbol() string {
return token.Symbol return token.Symbol
} }
// Decimals is a NEP-17 standard method that returns precision of NeoFS
// balances.
func Decimals() int { func Decimals() int {
return token.Decimals return token.Decimals
} }
// TotalSupply is a NEP-17 standard method that returns total amount of main
// chain GAS in the NeoFS network.
func TotalSupply() int { func TotalSupply() int {
ctx := storage.GetReadOnlyContext() ctx := storage.GetReadOnlyContext()
return token.getSupply(ctx) return token.getSupply(ctx)
} }
// BalanceOf is a NEP-17 standard method that returns NeoFS balance of specified
// account.
func BalanceOf(account interop.Hash160) int { func BalanceOf(account interop.Hash160) int {
ctx := storage.GetReadOnlyContext() ctx := storage.GetReadOnlyContext()
return token.balanceOf(ctx, account) return token.balanceOf(ctx, account)
} }
// Transfer is a NEP-17 standard method that transfers NeoFS balance from one
// account to other. Can be invoked only by account owner.
//
// Produces Transfer and TransferX notifications. TransferX notification
// will have empty details field.
func Transfer(from, to interop.Hash160, amount int, data interface{}) bool { func Transfer(from, to interop.Hash160, amount int, data interface{}) bool {
ctx := storage.GetContext() ctx := storage.GetContext()
return token.transfer(ctx, from, to, amount, false, nil) return token.transfer(ctx, from, to, amount, false, nil)
} }
// TransferX is a method for NeoFS balance transfers from one account to
// another. Can be invoked by account owner or by Alphabet nodes.
//
// Produces Transfer and TransferX notifications.
//
// TransferX method expands Transfer method by having extra details argument.
// Also TransferX method allows to transfer assets by Alphabet nodes of the
// Inner Ring with multi signature.
func TransferX(from, to interop.Hash160, amount int, details []byte) { func TransferX(from, to interop.Hash160, amount int, details []byte) {
ctx := storage.GetContext() ctx := storage.GetContext()
notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@ -180,6 +202,14 @@ func TransferX(from, to interop.Hash160, amount int, details []byte) {
runtime.Log("transferX: success") runtime.Log("transferX: success")
} }
// Lock is a method that transfers assets from user account to lock account
// related to the user. Can be invoked only by Alphabet nodes of the Inner Ring.
//
// Produces Lock, Transfer and TransferX notifications.
//
// Lock method invoked by Alphabet nodes of the Inner Ring when they process
// Withdraw notification from NeoFS contract. This should transfer assets
// to new lock account that won't be used for anything besides Unlock and Burn.
func Lock(txDetails []byte, from, to interop.Hash160, amount, until int) { func Lock(txDetails []byte, from, to interop.Hash160, amount, until int) {
ctx := storage.GetContext() ctx := storage.GetContext()
notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@ -234,6 +264,11 @@ func Lock(txDetails []byte, from, to interop.Hash160, amount, until int) {
runtime.Notify("Lock", txDetails, from, to, amount, until) runtime.Notify("Lock", txDetails, from, to, amount, until)
} }
// NewEpoch is a method that checks timeout on lock accounts and return assets
// if lock is not available anymore. Can be invoked only by NewEpoch method
// of Netmap contract.
//
// Produces Transfer and TransferX notifications.
func NewEpoch(epochNum int) { func NewEpoch(epochNum int) {
ctx := storage.GetContext() ctx := storage.GetContext()
notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@ -274,6 +309,15 @@ func NewEpoch(epochNum int) {
} }
} }
// Mint is a method that transfers assets to user account from empty account.
// Can be invoked only by Alphabet nodes of the Inner Ring.
//
// Produces Mint, Transfer and TransferX notifications.
//
// Mint method invoked by Alphabet nodes of the Inner Ring when they process
// Deposit notification from NeoFS contract. Before that Alphabet nodes should
// synchronize precision of main chain GAS contract and Balance contract.
// Mint increases total supply of NEP-17 compatible NeoFS token.
func Mint(to interop.Hash160, amount int, txDetails []byte) { func Mint(to interop.Hash160, amount int, txDetails []byte) {
ctx := storage.GetContext() ctx := storage.GetContext()
notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@ -322,6 +366,17 @@ func Mint(to interop.Hash160, amount int, txDetails []byte) {
runtime.Notify("Mint", to, amount) runtime.Notify("Mint", to, amount)
} }
// Burn is a method that transfers assets from user account to empty account.
// Can be invoked only by Alphabet nodes of the Inner Ring.
//
// Produces Burn, Transfer and TransferX notifications.
//
// Burn method invoked by Alphabet nodes of the Inner Ring when they process
// Cheque notification from NeoFS contract. It means that locked assets were
// transferred to user in main chain, therefore lock account should be destroyed.
// Before that Alphabet nodes should synchronize precision of main chain GAS
// contract and Balance contract. Burn decreases total supply of NEP-17
// compatible NeoFS token.
func Burn(from interop.Hash160, amount int, txDetails []byte) { func Burn(from interop.Hash160, amount int, txDetails []byte) {
ctx := storage.GetContext() ctx := storage.GetContext()
notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@ -374,6 +429,7 @@ func Burn(from interop.Hash160, amount int, txDetails []byte) {
runtime.Notify("Burn", from, amount) runtime.Notify("Burn", from, amount)
} }
// Version returns version of the contract.
func Version() int { func Version() int {
return version return version
} }

View file

@ -36,13 +36,13 @@ events:
type: ByteArray type: ByteArray
- name: Mint - name: Mint
parameters: parameters:
- name: from - name: to
type: Hash160 type: Hash160
- name: amount - name: amount
type: Integer type: Integer
- name: Burn - name: Burn
parameters: parameters:
- name: to - name: from
type: Hash160 type: Hash160
- name: amount - name: amount
type: Integer type: Integer

View file

@ -1,2 +1,79 @@
// Balance contract description. /*
Balance contract is a contract deployed in NeoFS side chain.
Balance contract stores all NeoFS account balances. It is NEP-17 compatible
contract so in can be tracked and controlled by N3 compatible network
monitors and wallet software.
This contract is used to store all micro transactions in the sidechain, such as
data audit settlements or container fee payments. It is inefficient to make such
small payment transactions in main chain. To process small transfers, balance
contract has higher (12) decimal precision than native GAS contract.
NeoFS balances are synchronized with main chain operations. Deposit produce
minting of NEOFS tokens in Balance contract. Withdraw locks some NEOFS tokens
in special lock account. When NeoFS contract transfers GAS assets back to the
user, lock account is destroyed with burn operation.
Contract notifications
Transfer notification. This is NEP-17 standard notification.
Transfer:
- name: from
type: Hash160
- name: to
type: Hash160
- name: amount
type: Integer
TransferX notification. This is enhanced transfer notification with details.
TransferX:
- name: from
type: Hash160
- name: to
type: Hash160
- name: amount
type: Integer
- name: details
type: ByteArray
Lock notification. This notification is produced when Lock account has been
created. It contains information about main chain transaction that produced
asset lock, address of lock account and NeoFS epoch number until lock account
is valid. Alphabet nodes of the Inner Ring catch notification and initialize
Cheque method invocation of the NeoFS contract.
Lock:
- name: txID
type: ByteArray
- name: from
type: Hash160
- name: to
type: Hash160
- name: amount
type: Integer
- name: until
type: Integer
Mint notification. This notification is produced when user balance is
replenished from deposit in the main chain.
Mint:
- name: to
type: Hash160
- name: amount
type: Integer
Burn notification. This notification is produced after user balance is reduced
when NeoFS contract transferred GAS assets back to the user.
Burn:
- name: from
type: Hash160
- name: amount
type: Integer
*/
package balance package balance