frostfs

Documentation

Overview

FrostFS contract is a contract deployed in FrostFS mainchain.

FrostFS contract is an entry point to FrostFS users. This contract stores all FrostFS related GAS, registers new Inner Ring candidates and produces notifications to control the sidechain.

While mainchain committee controls the list of Alphabet nodes in native RoleManagement contract, FrostFS can't change more than 1\3 keys at a time. FrostFS contract contains the actual list of Alphabet nodes in the sidechain.

Network configuration is also stored in FrostFS contract. All changes in configuration are mirrored in the sidechain with notifications.

Contract notifications

Deposit notification. This notification is produced when user transfers native GAS to the FrostFS contract address. The same amount of FROSTFS token will be minted in Balance contract in the sidechain.

Deposit:
  - name: from
    type: Hash160
  - name: amount
    type: Integer
  - name: receiver
    type: Hash160
  - name: txHash
    type: Hash256

Withdraw notification. This notification is produced when a user wants to withdraw GAS from the internal FrostFS balance and has paid fee for that.

Withdraw:
  - name: user
    type: Hash160
  - name: amount
    type: Integer
  - name: txHash
    type: Hash256

Cheque notification. This notification is produced when FrostFS contract has successfully transferred assets back to the user after withdraw.

Cheque:
  - name: id
    type: ByteArray
  - name: user
    type: Hash160
  - name: amount
    type: Integer
  - name: lockAccount
    type: ByteArray

Bind notification. This notification is produced when a user wants to bind public keys with the user account (OwnerID). Keys argument is an array of ByteArray.

Bind:
  - name: user
    type: ByteArray
  - name: keys
    type: Array

Unbind notification. This notification is produced when a user wants to unbind public keys with the user account (OwnerID). Keys argument is an array of ByteArray.

Unbind:
  - name: user
    type: ByteArray
  - name: keys
    type: Array

SetConfig notification. This notification is produced when Alphabet nodes update FrostFS network configuration value.

SetConfig
  - name: id
    type: ByteArray
  - name: key
    type: ByteArray
  - name: value
    type: ByteArray

Contract storage scheme

|   Key                       | Value      |           Description            |
|-----------------------------------------------------------------------------|
| `processingScriptHash`      | Hash160    | processing contract hash         |
| `candidates` + candidateKey | ByteArray  | it flags inner ring candidate    |
| `config` + postfix          | ByteArray  | serialized config data           |

Index

• Constants
• func Bind(user []byte, keys []interop.PublicKey)
• func Cheque(id []byte, user interop.Hash160, amount int, lockAcc []byte)
• func Config(key []byte) any
• func InnerRingCandidateAdd(key interop.PublicKey)
• func InnerRingCandidateRemove(key interop.PublicKey)
• func InnerRingCandidates() []common.IRNode
• func ListConfig() []record
• func OnNEP17Payment(from interop.Hash160, amount int, data any)
• func SetConfig(id, key, val []byte)
• func Unbind(user []byte, keys []interop.PublicKey)
• func Update(script []byte, manifest []byte, data any)
• func Version() int
• func Withdraw(user interop.Hash160, amount int)

Constants

const (
	// CandidateFeeConfigKey contains fee for a candidate registration.
	CandidateFeeConfigKey = "InnerRingCandidateFee"
)

Functions

func Bind

func Bind(user []byte, keys []interop.PublicKey)

Bind method produces notification to bind the specified public keys in FrostFSID contract in the sidechain. It can be invoked only by specified user.

This method produces Bind notification. This method panics if keys are not 33 byte long. User argument must be a valid 20 byte script hash.

func Cheque

func Cheque(id []byte, user interop.Hash160, amount int, lockAcc []byte)

Cheque transfers GAS back to the user from the contract account, if assets were successfully locked in FrostFS balance contract. It can be invoked only by Alphabet nodes.

This method produces Cheque notification to burn assets in sidechain.

func Config

func Config(key []byte) any

Config returns configuration value of FrostFS configuration. If the key does not exists, returns nil.

func InnerRingCandidateAdd

func InnerRingCandidateAdd(key interop.PublicKey)

InnerRingCandidateAdd adds a key to a list of Inner Ring candidates. It can be invoked only by the candidate itself.

This method transfers fee from a candidate to the contract account. Fee value is specified in FrostFS network config with the key InnerRingCandidateFee.

func InnerRingCandidateRemove

func InnerRingCandidateRemove(key interop.PublicKey)

InnerRingCandidateRemove removes a key from a list of Inner Ring candidates. It can be invoked by Alphabet nodes or the candidate itself.

This method does not return fee back to the candidate.

func InnerRingCandidates

func InnerRingCandidates() []common.IRNode

InnerRingCandidates returns an array of structures that contain an Inner Ring candidate node key.

func ListConfig

func ListConfig() []record

ListConfig returns an array of structures that contain a key and a value of all FrostFS configuration records. Key and value are both byte arrays.

func OnNEP17Payment

func OnNEP17Payment(from interop.Hash160, amount int, data any)

OnNEP17Payment is a callback for NEP-17 compatible native GAS contract. It takes no more than 9000.0 GAS. Native GAS has precision 8, and FrostFS balance contract has precision 12. Values bigger than 9000.0 can break JSON limits for integers when precision is converted.

func SetConfig

func SetConfig(id, key, val []byte)

SetConfig key-value pair as a FrostFS runtime configuration value. It can be invoked only by Alphabet nodes.

func Unbind

func Unbind(user []byte, keys []interop.PublicKey)

Unbind method produces notification to unbind the specified public keys in FrostFSID contract in the sidechain. It can be invoked only by the specified user.

This method produces Unbind notification. This method panics if keys are not 33 byte long. User argument must be a valid 20 byte script hash.

func Update

func Update(script []byte, manifest []byte, data any)

Update method updates contract source code and manifest. It can be invoked only by sidechain committee.

func Version

func Version() int

Version returns version of the contract.

func Withdraw

func Withdraw(user interop.Hash160, amount int)

Withdraw initializes gas asset withdraw from FrostFS. It can be invoked only by the specified user.

This method produces Withdraw notification to lock assets in the sidechain and transfers withdraw fee from a user account to each Alphabet node. If notary is enabled in the mainchain, fee is transferred to Processing contract. Fee value is specified in FrostFS network config with the key WithdrawFee.