frostfs-node/docs/epoch.md

Epoch

The main purpose of the epoch in frostfs environment is to manipulate netmap. Each new epoch, ir service trigger revision content of the netmap by adding or removing nodes to or from it. node service trigger few internal processes each new epoch - for example, running GC. Epoch also used in an object lifecycle.

At the startup, ir service initializes an epoch timer which handles new epoch tick. Epoch timer is a block timer - which means that this timer ticks each block or set of blocks. The epoch duration stores in the configurable parameter EpochDuration in the blockchain. It is possible to get it via frostfs-adm:

> frostfs-adm morph dump-config -c config.yml -r http://morph-chain.frostfs.devenv:30333
...
EpochDuration:               240 (int)
...
>

Once epoch timer ticks, ir service call method NewEpoch of the netmap contract. Each ir instance can do this at the same time, but it is not an issue, because multiple call of this method with the same set of parameters will give us the same result.

Utility frostfs-adm have a command to trigger new epoch:

> frostfs-adm morph force-new-epoch -c config.yml -r http://morph-chain.frostfs.devenv:30333

Command goes directly to the netmap contract and call method NewEpoch. Method checks alphabet witness and stores candidates nodes which are not in the OFFLINE state as a current netmap. Then executes method NewEpoch in balance and container contracts. At the end it produces notification NewEpoch which is handled by node and ir services.

ir handler for NewEpoch updates internal state of the netmap, if it is necessary, updates state of the nodes or marks for exclusion from netmap in the blockchain.

node handler for NewEpoch executes method addPeer of the netmap contract. This method do nothing, but produces notification which handled by ir service. ir in handler for AddPeer may update node state in the netmap if it is necessary.

At the startup, node bootstraps with state ONLINE. From the online state, it is possible to move to MAINTENANCE or OFFLINE. Node moved to OFFLINE state automatically, when there is no bootstrap request from it for a number of epochs. This number stored in the ir config netmap_cleaner.threshold. From OFFLINE state node, once it bootstrapped, moves to ONLINE. MAINTENANCE state persists even if node rebooted or unavailable for a few epochs.