[#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>

balance/balance_contract.go

@@ -22,6 +22,7 @@ type (
 		CirculationKey string
 	}
 
+	// Account structure stores metadata of each NeoFS balance account.
 	Account struct {
 		// Active  balance
 		Balance int
@@ -46,8 +47,7 @@ const (
 
 var token Token
 
-// CreateToken initializes the Token Interface for the Smart Contract to operate with.
+func createToken() Token {
-func CreateToken() Token {
 	return Token{
 		Symbol:         symbol,
 		Decimals:       decimals,
@@ -56,7 +56,7 @@ func CreateToken() Token {
 }
 
 func init() {
-	token = CreateToken()
+	token = createToken()
 }
 
 func _deploy(data interface{}, isUpdate bool) {
@@ -94,6 +94,8 @@ func _deploy(data interface{}, isUpdate bool) {
 	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 {
 	ctx := storage.GetReadOnlyContext()
 
@@ -108,29 +110,49 @@ func Migrate(script []byte, manifest []byte, data interface{}) bool {
 	return true
 }
 
+// Symbol is a NEP-17 standard method that returns NEOFS token symbol.
 func Symbol() string {
 	return token.Symbol
 }
 
+// Decimals is a NEP-17 standard method that returns precision of NeoFS
+// balances.
 func Decimals() int {
 	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 {
 	ctx := storage.GetReadOnlyContext()
 	return token.getSupply(ctx)
 }
 
+// BalanceOf is a NEP-17 standard method that returns NeoFS balance of specified
+// account.
 func BalanceOf(account interop.Hash160) int {
 	ctx := storage.GetReadOnlyContext()
 	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 {
 	ctx := storage.GetContext()
 	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) {
 	ctx := storage.GetContext()
 	notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@@ -180,6 +202,14 @@ func TransferX(from, to interop.Hash160, amount int, details []byte) {
 	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) {
 	ctx := storage.GetContext()
 	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)
 }
 
+// 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) {
 	ctx := storage.GetContext()
 	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) {
 	ctx := storage.GetContext()
 	notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@@ -322,6 +366,17 @@ func Mint(to interop.Hash160, amount int, txDetails []byte) {
 	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) {
 	ctx := storage.GetContext()
 	notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@@ -374,6 +429,7 @@ func Burn(from interop.Hash160, amount int, txDetails []byte) {
 	runtime.Notify("Burn", from, amount)
 }
 
+// Version returns version of the contract.
 func Version() int {
 	return version
 }

balance/config.yml

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

balance/doc.go

@@ -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