netmap

Documentation

Overview

Package netmap contains implementation of the Netmap contract for NeoFS systems.

Netmap contract stores and manages NeoFS network map, Storage node candidates and epoch number counter. In notary disabled environment, contract also stores a list of Inner Ring node keys.

Contract notifications

AddPeer notification. This notification is produced when a Storage node sends a bootstrap request by invoking AddPeer method.

AddPeer
  - name: nodeInfo
    type: ByteArray

UpdateState notification. This notification is produced when a Storage node wants to change its state (go offline) by invoking UpdateState method. Supported states: (2) -- offline.

UpdateState
  - name: state
    type: Integer
  - name: publicKey
    type: PublicKey

NewEpoch notification. This notification is produced when a new epoch is applied in the network by invoking NewEpoch method.

NewEpoch
  - name: epoch
    type: Integer

Index

• Constants
• func AddPeer(nodeInfo []byte)
• func AddPeerIR(nodeInfo []byte)
• func Config(key []byte) any
• func Epoch() int
• func InnerRingList() []common.IRNode
• func LastEpochBlock() int
• func ListConfig() []record
• func NewEpoch(epochNum int)
• func SetConfig(id, key, val []byte)
• func SubscribeForNewEpoch(contract interop.Hash160)
• func Update(script []byte, manifest []byte, data any)
• func UpdateSnapshotCount(count int)
• func UpdateState(state NodeState, publicKey interop.PublicKey)
• func UpdateStateIR(state NodeState, publicKey interop.PublicKey)
• func Version() int
• type Node
  • func Netmap() []Node
  • func NetmapCandidates() []Node
  • func Snapshot(diff int) []Node
  • func SnapshotByEpoch(epoch int) []Node
• type NodeState

Constants

const (
	// DefaultSnapshotCount contains the number of previous snapshots stored by this contract.
	// Must be less than 255.
	DefaultSnapshotCount = 10
)

Functions

func AddPeer

func AddPeer(nodeInfo []byte)

AddPeer proposes a node for consideration as a candidate for the next-epoch network map. Information about the node is accepted in NeoFS API binary format. Call transaction MUST be signed by the public key sewn into the parameter (compressed 33-byte array starting from 3rd byte), i.e. by candidate itself. If the signature is correct, the Notary service will submit a request for signature by the NeoFS Alphabet. After collecting a sufficient number of signatures, the node will be added to the list of candidates for the next-epoch network map ('AddPeerSuccess' notification is thrown after that).

Note that if the Alphabet needs to complete information about the candidate, it will be added with AddPeerIR.

func AddPeerIR

func AddPeerIR(nodeInfo []byte)

AddPeerIR is called by the NeoFS Alphabet instead of AddPeer when signature of the network candidate is inaccessible. For example, when information about the candidate proposed via AddPeer needs to be supplemented. In such cases, a new transaction will be required and therefore the candidate's signature is not verified by AddPeerIR. Besides this, the behavior is similar.

func Config

func Config(key []byte) any

Config returns configuration value of NeoFS configuration. If key does not exist, returns nil.

func Epoch

func Epoch() int

Epoch method returns the current epoch number.

func InnerRingList

func InnerRingList() []common.IRNode

InnerRingList method returns a slice of structures that contains the public key of an Inner Ring node. It should be used in notary disabled environment only.

If notary is enabled, look to NeoFSAlphabet role in native RoleManagement contract of the sidechain.

Deprecated: since non-notary settings are no longer supported, refer only to the RoleManagement contract only. The method will be removed in one of the future releases.

func LastEpochBlock

func LastEpochBlock() int

LastEpochBlock method returns the block number when the current epoch was applied.

func ListConfig

func ListConfig() []record

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

func NewEpoch

func NewEpoch(epochNum int)

NewEpoch method changes the epoch number up to the provided epochNum argument. It can be invoked only by Alphabet nodes. If provided epoch number is less than the current epoch number or equals it, the method throws panic.

When epoch number is updated, the contract sets storage node candidates as the current network map. The contract also invokes NewEpoch method on Balance and Container contracts.

It produces NewEpoch notification.

func SetConfig

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

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

func SubscribeForNewEpoch

func SubscribeForNewEpoch(contract interop.Hash160)

SubscribeForNewEpoch registers passed contract as a NewEpoch event subscriber. Such a contract must have a `NewEpoch` method with a single numeric parameter. Transactions that call SubscribeForNewEpoch must be witnessed by the Alphabet. Produces `NewEpochSubscription` notification event with a just registered recipient in a success case.

func Update

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

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

func UpdateSnapshotCount

func UpdateSnapshotCount(count int)

UpdateSnapshotCount updates the number of the stored snapshots. If a new number is less than the old one, old snapshots are removed. Otherwise, history is extended with empty snapshots, so `Snapshot` method can return invalid results for `diff = new-old` epochs until `diff` epochs have passed.

Count MUST NOT be negative.

func UpdateState

func UpdateState(state NodeState, publicKey interop.PublicKey)

UpdateState proposes a new state of candidate for the next-epoch network map. The candidate is identified by the given public key. Call transaction MUST be signed by the provided public key, i.e. by node itself. If the signature is correct, the Notary service will submit a request for signature by the NeoFS Alphabet. After collecting a sufficient number of signatures, the candidate's state will be switched to the given one ('UpdateStateSuccess' notification is thrown after that).

UpdateState panics if requested candidate is missing in the current candidate set. UpdateState drops candidate from the candidate set if it is switched to NodeStateOffline.

State MUST be from the NodeState enum. Public key MUST be interop.PublicKeyCompressedLen bytes.

func UpdateStateIR

func UpdateStateIR(state NodeState, publicKey interop.PublicKey)

UpdateStateIR is called by the NeoFS Alphabet instead of UpdateState when signature of the network candidate is inaccessible. In such cases, a new transaction will be required and therefore the candidate's signature is not verified by UpdateStateIR. Besides this, the behavior is similar.

func Version

func Version() int

Version returns the version of the contract.

Types

type Node

type Node struct {
	// Information about the node encoded according to the NeoFS binary
	// protocol.
	BLOB []byte

	// Current node state.
	State NodeState
}

Node groups data related to NeoFS storage nodes registered in the NeoFS network. The information is stored in the current contract.

func Netmap

func Netmap() []Node

Netmap returns set of information about the storage nodes representing a network map in the current epoch.

Current state of each node is represented in the State field. It MAY differ with the state encoded into BLOB field, in this case binary encoded state MUST NOT be processed.

func NetmapCandidates

func NetmapCandidates() []Node

NetmapCandidates returns set of information about the storage nodes representing candidates for the network map in the coming epoch.

Current state of each node is represented in the State field. It MAY differ with the state encoded into BLOB field, in this case binary encoded state MUST NOT be processed.

func Snapshot

func Snapshot(diff int) []Node

Snapshot returns set of information about the storage nodes representing a network map in (current-diff)-th epoch.

Diff MUST NOT be negative. Diff MUST be less than maximum number of network map snapshots stored in the contract. The limit is a contract setting, DefaultSnapshotCount by default. See UpdateSnapshotCount for details.

Current state of each node is represented in the State field. It MAY differ with the state encoded into BLOB field, in this case binary encoded state MUST NOT be processed.

func SnapshotByEpoch

func SnapshotByEpoch(epoch int) []Node

SnapshotByEpoch returns set of information about the storage nodes representing a network map in the given epoch.

Behaves like Snapshot: it is called after difference with the current epoch is calculated.

type NodeState

type NodeState int

NodeState is an enumeration for node states.

const (

	// NodeStateOnline stands for nodes that are in full network and
	// operational availability.
	NodeStateOnline NodeState

	// NodeStateOffline stands for nodes that are in network unavailability.
	NodeStateOffline

	// NodeStateMaintenance stands for nodes under maintenance with partial
	// network availability.
	NodeStateMaintenance
)

Various Node states