NeoFS IR

[doubiliu]

Introduction

In order to facilitate understanding and review, the Fs C# ported version code will be divided into multiple PRs for submission. The PR submitted this time is the first part of it, mainly including the relevant functional modules of the IR node, and subsequent submissions about storage nodes and clients PR of the tool.

IR struct

The program will be released in the form of a plug-in.

After the NeoCli node installs this plug-in and is authorized to enable related functions, it will automatically become an IR node in the Fs system, assume the role of a connection bridge between the main network and the side chain, and work together with related smart contracts and storage nodes to provide users with distribution storage service.

The plugin will consist of 2 parts:

• FileStorageBase:contains public classes involved in functions such as IR, CLI, and storage nodes

• FileStorageIR: contains all functions needed for IR

FileStorageIR directly depend onFileStorageBase。

Runtime Process

Start

When the IR plugin starts, it will automatically create a side chain node, which is used to collect blocks and various contract events generated during the operation of the Fs system together with its own main network node.

At the same time, an InnerRingService service will be created to process the collected contract events.

InnerRingService mainly consists of the following components:

• Listener: mainEventListener , morphEventListener
• Processor processor: a total of 8, BalanceContractProcessor, ContainerContractProcessor, FsContractProcessor, NetMapContractProcessor, GovernanceProcessor, AlphabetContractProcessor, AuditContractProcessor, ReputationProcessor
• Invoker : MainInvoker , MorphInvoker
• Block timer: EpochTimer , EmissionTimer

Contract event handling

The IR plugin collects various notification events generated by the execution of the smart contract through the OnPersist function of the Plugin base class, and filters them. The filtered events will be sent to the InnerRingService service, and distributed and processed by its built-in Listener.

The Listener has a built-in event parser mapping table (Dictionary<ScriptHashWithType, Func<VM.Types.Array, ContractEvent>> parsers) and an event handler mapping table (Dictionary<ScriptHashWithType, List<Action<ContractEvent>> > handlers).

A contract event can be bound to an event parser and multiple event handlers, using ScriptHashWithType (calculated from the contract hash and event type) as the primary key association.

A smart contract event will be processed by the event parser and sent to all event handlers bound to it, and the event handler will call the action function of the relevant processor.

Contract event processing loop

New Epoch

Every time a new block is generated on the side chain, tick() of EpochTimer will be invoked, and the block timer's handle() will be executed after the specified conditions are met, and a BlockEvent will be generated.

After the BlockEvent is sent to the morphEventListener, it is forwarded to the HandleNewEpochTick() of NetMapContractProcessor for execution. When HandleNewEpochTick() is executed, a epoch update request is sent to NetMapContract. When a consensus is reached on the 2/3 IR epoch update request, the epoch recorded by NetMapContract will be updated and a NewEpochEventwill be generated.

After the NewEpochEvent is sent to the morphEventListener, it is forwarded to the HandleNewEpoch() of NetMapContractProcessor for execution. When HandleNewEpoch() is executed, the following operations will be performed:

1. Update local epoch status
2. Update NetmapSnapshot cache
3. Start a new round of audit audit and process the results of the previous round of audit
4. Sync committee aphabet changes

Alphabet Vote

After each epoch is generated or the mainnet committee changes the Alphabet node, an AlphabetSync event will be generated. After the event is sent to the mainEventListener , it is forwarded to HandleAlphabetSync() of GovernanceProcessor for processing. When HandleAlphabetSync() is executed, it will send an election Vote request to AlphabetContract. When the 2/3 IR Vote request reaches a consensus, AlphabetContract will directly call the Neo native contract to change the sidechain consensus. In addition,when HandleAlphabetSync() is executed, it will also send an Alphabet node change request to NetMapContract. When the 2/3 IR's Alphabet node change request reaches a consensus, NetMapContract will change the Alphabet node of the current epoch.

Note: One Alphabet node change can change up to 1/3 of the nodes

Capital circulation

Deposit

The user deposits gas to FsContract and generates a Deposit event. After the event is sent to the mainEventListener, it is forwarded to HandleDeposit() of FsContractProcessor for processing. When HandleDeposit() is executed, it will be sent to BalanceContract sends a Mint request. When 2/3 IR's Mint change request reaches a consensus, BalanceContract will update the balance of the user's side chain mapping account, and will also distribute a certain amount of gas to the user's side chain account address.

Withdraw

1. After the user calls the Withdraw() of FsContract to submit a withdrawal request and pays the withdraw fee to the IR main network address, the Withdraw event will occur.
2. After the Withdraw event is sent to the mainEventListener, it is forwarded to HandleWithdraw() of FsContractProcessor for processing. When HandleWithdraw() is processed, it will submit a lock request to BalanceContract. When 2/3 IR's lock request reaches a consensus, BalanceContract will freeze the corresponding amount of assets in the user's side chain mapping account and generate a lock event.
3. After the lock event is sent to the morphEventListener, it is forwarded to HandleLock() of BalanceContractProcessor for processing. When HandleLock() is executed, it will send a cheque request to FsContract. When 2/3 When IR's cheque request reaches a consensus, FsContract will release funds to the user's mainnet account address and generate a cheque event.
4. The cheque event will be sent to the mainEventListener, and then forwarded to HandleCheque() of FsContractProcessor for processing. When HandleCheque is executed, it will send a burn request to BalanceContract. When 2/3 IR's burn request reached a consensus, BalanceContract burned the user's frozen assets.

Audit Incentive

Each time the side chain generates a new epoch, a new epoch event will be generated. The event will be sent to the morphEventListener, and then forwarded to the HandleNewEpoch() of the NetMapContractProcessor for processing.HandleNewEpoch() processing .At that time, a new round of audit will be opened, and incentives will be calculated based on the results of the previous round of audits.

The new round of audit will be handed over to the HandleNewAuditRound() of AuditContractProcessor for execution. During the execution of HandleNewAuditRound(), the corresponding audit task (TzHash calculation matching result) will be generated according to the recorded container and storage node topology map, and collect audit data from the corresponding storage node, and record the audit results in AuditContract. (The audit results must be sent during the submission period)

The last round of audit results will be processed by the Handle() of SettlementProcessor. During the process of Handle(), the average value will be calculated for each storage node in the previous round of epoch. After the calculation is completed, submit the transferX request to BalancBaeContract. When the transferX request of 2/3 IR node reaches a consensus, BalancBaeContract will deduct the container holdings. The assets in the human side chain mapping account are used to pay the storage nodes and IR incentives.

In addition to complete the audit task to obtain incentives, each epoch of the side chain storage node will receive a basic reward based on the size of the data stored in the entire network container. The specified block height in each epoch of the side chain will trigger the EpochTimer timer to execute During the execution of HandleIncomeCollectionEvent() of settlementProcessor.HandleIncomeCollectionEvent() calculates the basic stimulus that each storage node should get for storing data in the previous round of Epoch according to the averaging method, and after the calculation is completed submit a transferX request to BalancBaeContract. When the transferX request of the 2/3 IR node reaches a consensus, BalancBaeContract will deduct the assets in the container holder's side chain mapping account and deposit it into the bank address for payment to the storage node for storing data excitation.

The specified block height in each epoch of the side chain will trigger the EpochTimer timer to execute the HandleIncomeDistributionEvent() of settlementProcessor, and when HandleIncomeDistributionEvent() is executed, it will submit a transferX request to BalancBaeContract, when the 2/3 IR node. After the transferX request reaches a consensus, BalancBaeContract will deduct the assets in the bank address and distribute it to each storage node.

Fuel cycle

When the system is deployed, all neo of the side chain will be transferred to the AlphabetContract, and the gas required for each round of Epoch system operation will be applied for and distributed from the AlphabetContract.

After the side chain generates a fixed number of blocks, the EmissionTimer timer is triggered to call the HandleGasEmission() of the AlphabetContractProcessor. When the HandleGasEmission() is executed, it will submit an Emit request to the AlphabetContract. When 2/3 When IR's Emit request reaches a consensus, AlphabetContract will distribute fuel gas to all IR node sidechain account addresses. In addition, IR will evenly distribute part of the fuel gas allocated in the previous round of Epoch to all storage nodes.

[ZhangTao1596]

First part of #582, there will be storage and client soon.

[doubiliu]

@erikzhang @shargon Can you help to review it?

[shargon]

@doubiliu Yes, I will, but I need more time please, it's big :)

[ZhangTao1596]

When neo-node load InnerRingPlugin, another NeoSystem instance will be created and run. So we have two neo system running after install InnerRingPlugin. One is in main chain another is in side chain called morph. InnerRingPlugin will relay messages which are actually contract excute notifications between these two blockchains.

[vncoelho]

@ZhangTao1596, what is the current status? Are we going to move forward?

[Jim8y]

close as inactive