# 2023/02/23 Swarm Community Call - monSI Presentation

The Who, What, Where, Why, and How of monSI.


## Who

monSI was developed by ldeffenb as a natural expansion of the original [monBee](https://github.com/ldeffenb/monBee) individual node monitor. mfw78 forked it, cleaned it up, packaged it, and otherwise made it much more publicly palatable.

We're both historically very active in the Swarm Discord support channels.

## What

monSI is a monitor that extracts information from the storage incentives (SI) blockchain contracts and presents it in a user-friendly fashion. It displays:

- Stakes - Every node that has ever staked by overlay address
- Rounds - Historical and current, based on command line arguments
- Current round players along with phase details - More on phases later
- Transactions - All, even failed, transactions on the redistribution contract
- Gas pricing - For transactions and the blockchain

## Where

GitHub repository: https://github.com/rndlabs/monSI

Install via NPM:

npm install -g "@rndlabs/monsi"

The [README.md](https://github.com/rndlabs/monSI/blob/d349f805432c188e9a591f09fbb4173c277c6bca/README.md) is always good place to start reading!

## Why

When the storage incentives was under development, ldeffenb wanted to see how it operated, and see how the development was progressing. Reading the raw transactions on the gnosis blockchain explorer just wasn't helping to visualize it, so between ldeffenb and mfw, monSI was born. mfw provided the blockchain smarts and ldeffenb modified the monBee user interface to show what he wanted to see. Then mfw did the massive code organization and cleanup work leading to what is available today.

## How

monSI is written in TypeScript and uses typechain to generate ethers bindings for contract interaction. Information is extracted from the various storage incentives contracts transactions and events via a user-supplied blockchain RPC provider. This information is accumulated and displayed to the user using the curses-like [blessed](https://www.npmjs.com/package/blessed) text user interface.

But to understand what monSI is showing you, you need to understand how the storage incentives works and the phases of the *Schelling Game* that redistributes the actual compensation.

Five smart contracts make up the storage incentives. Everything that monSI displays comes from one of these contracts, mostly the *Redistribution* contract.

- Token - The BZZ token is at the base of it all

- Stamps - The postage stamps are the source of the compensation based on the current storage price

- Staking - In order to compete for the storage incentives, a node must stake a minimum of 10BZZ. This stake is normally non-refundable.

- Redistribution - This contract is the implementation of the Schelling Game and provides the actual movement of storage compensation from the stamp contract to the winner of each round.

- Price Oracle - The price oracle will dynamically adjust the storage price to maintain a balance between supply (number of active nodes or storage depth or size of neighborhoods, depending on how you look at it) and demand (total amount of stamped data currently resident in the swarm). Coming soon to a swarm near you!

## The Schelling Game - Rounds

A round lasts 152 blocks or almost 13 minutes on the gnosis chain and consists of three phases: `commit`, `reveal`, and `claim`, but I'm going to start at the last phase because that's where the action really starts inside each node.

### claim

At the beginning of the `claim` phase, the next round's neighborhood is published in the form of a "round anchor" which is simply a random overlay-looking address which selects the "neighborhood" to compete in the upcoming round. Each node determines if it is selected by looking at the left-most `N` bits of the anchor versus their own overlay. If `N` bits match, their node and neighborhood is selected. `N` is the current storage depth of the node as you can see in the *depthmonitor* logs. Currently the mainnet swarm has been running a depth of 8 which means the leading 2 hex characters of the overlay needs to match the anchor to compete.

**Note**: The mainnet storage depth may change (likely reduce) with the recent storage price increase!

If a node determines itself to be selected, then it will begin to calculate a hash of the current reserve, the chunks that the node is expected to be storing. This is when your node's disk and CPU spike.

More on the claim phase at the end of the round...

### commit

The `commit` phase is the first 38 blocks, or 1/4, of a new round. Once the node has calculated its reserve hash, it will `commit` with some cryptographic magic so that others cannot tell what the hash really is, but yet the contract can ensure that the node doesn't change the hash between the `commit` and `reveal` phases.

If a node doesn't finish calculating the reserve hash before the end of the `commit` phase, it will abort the calculation and not participate in the Schelling Game for this round, even though it was selected. Remember that the node started the hash in the `claim` phase, so it had 114 blocks or *over 9 minutes* of elapsed time on the gnosis blockchain to complete the calculation.

### reveal

The `reveal` phase is the next 38 blocks in the round and every node that committed will `reveal` the *actual* hash value. monSI shows these values so you can visually see if all of the playing nodes are in agreement or not. The storage depth that each node used for the hash is also shown.

If any node commits to a round but doesn't reveal a hash, its stake will be **frozen**. Originally, and *possibly* in the future, this situation caused a *complete slash of the stake*.

### claim

Which brings us back to `claim`. In this 76 block phase, or 1/2 the round's length, the contract code selects one of the revealed hashes as the "truth" and then randomly (with some stake weighting) selects one of the revealing nodes with that truth as the "winner". This winner will pay the transaction cost to transfer the accumulated BZZ collected from the postage stamps to its own address.

And of course a new round anchor is published which causes another neighborhood to start their reserve hash determination for the next round.

And so the play goes on and monSI let's you watch it near *realtime*!

## RPC Requirements

**WARNING**: If you use a free or limited blockchain RPC provider, you *should not* run monSI for extended time intervals. It does **LOTS** of RPC calls to gather the displayed data.

## Demo

Recording and Playback provided by [asciinema](https://asciinema.org)

Watch the stage-chat Discord channel for links to what I'll be talking about starting with:


http://142.132.214.211/asciinema/SI-long.html

If it doesn't start playing automatically, just click play while I keep talking. And don't panic, this playback is 100x so you're not expected to keep up with the details... yet.

When monSI starts, it queries all blocks from the staking contract original block to the current block to accumulate all of the stakes. You'll see this flash by at 100x speed when the playback starts. If you missed it, just Refresh your browser and it'll do it again.

Now I'll describe all of that "stuff" that you're seeing starting from the top right corner and going counter-clockwise around the screen.

### All Players

The top right corner shows the stake status of all players according to the active staking contract. As the game is played, each overlay's line will be updated to reflect wins/rounds winnings and then the original stake. Slashes (*future*) and Freezes (*currently*) are also shown for each overlay. The All Players box is scrollable on Ubuntu, but I haven't found a way to scroll it in Windows.

### Rounds

As the rounds progress, summary information is shown in the center box.

- Current rounds show the left-most 4 characters of the round anchor, but replayed rounds do not include this information.

- `n-m` is the number of *commits* and *reveals* in the round. As mentioned before, any node that commits but fails to reveal will be frozen for some (largish) number of rounds. This freeze was originally a slash of the stake and may go back to this behavior at some point in the future.

- `n` or `n+m=f` or `n^d+m^d=f` - Green is the count of nodes that matched the selected truth. Red is the count of nodes that did not match the truth. Blue `=f` is the count of nodes that were frozen for not matching the truth or failing to reveal. Note that since truth selection is random, it is possible to have an apparent "mistake" in that a single node may be truth and multiple nodes that match each other end up frozen for not matching the selection.

- `overlay...^d +nnn` is the overlay that "won" the round and received the indicated storage compensation (in *plur* or BZZ). `d` is the storage depth reported by that node.

Mainnet compensation was running around 12 trillion plur at the steeply-discounted storage price of 4 plur. Now that the price is 24,000, compensation per round seems to be between 1 and 2 BZZ, settling just before this call closer to 1. These numbers will vary depending on the amount of data stored in the swarm, stamp expirations, and certainly after the price oracle begins dyanamic storage pricing. Do **NOT** use these numbers to plan any sort of anticipated compensation calculations!

### Round Players

The top left box displays the ongoing status of the current round. Each overlay (node) that has posted a transaction to the blockchain is shown along with information about their most recent transaction. The top line shows the remaining blocks in the round, the round's anchor (leading 4 hex digits supporting up to a depth of 16) along with a % progress through the current phase. In the claim phase, the top line shows not only the current anchor, but also the next round's anchor (`xxxx->yyyy`).

For `reveal` and `claim`, the node's calculated reserve hash is also shown so that you can see if the neighborhood is in agreement.

### Transactions

The Transactions box shows the most recently logged redistribution contract transactions from the top down along with gas price and usage information. The base and priority components are shown for the [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) transactions.

### (unlabelled bottom left)

The bottom left box is just diagnostic and progress output. It may or may not be user-understandable, but at least the top line updates with each processed block so you can see activity when the phases aren't very active.

And don't ask me about the "7 wei" on the right side of that box. It actually shows different numbers on the goerli testnet than it does on the gnosis chain.

> mfw: "7 wei" is the actual base fee on Gnosis Chain (it _really_ is that low!).

Oh, but the delta time between blocks IS shown in that area with red coloration if a block takes longer than the established baseline for the chain (5 seconds on gnosis and 12 seconds on goerli).

## Some Actual Rounds

### 174840 - A Winner!


http://142.132.214.211/asciinema/174840-Winner.html

The first clip is from round `174840` which will show when one of our selected nodes (from the command line) plays and actually wins the round.

I'm wondering if the bee0... overlay was mined or just a coincidence? It's NOT one of my nodes! None of the highlighted nodes are mine but were selected as the first staked overlay for each leading hex digit, plus a few extras.

### 174940 - Reveal Failure Freeze


http://142.132.214.211/asciinema/174940-Freeze.html

The next clip shows round `174940` where two of the nodes that committed failed to reveal their hash and were therefore frozen.

### 174837 - Differing Hash Freeze


http://142.132.214.211/asciinema/174837-Freeze.html

And round `174837` shows a split decision on what the true hash value is. Five nodes, three different solutions, three frozen nodes. Freeze duration: 768 rounds or 116736 blocks or 6.75 DAYS of non-participation!

### 174939 - Differing Hash, Our Node Frozen


http://142.132.214.211/asciinema/174939-Freeze.html

And finally, the one you hope you don't see is round `174939` where one of our own nodes was selected, played, and ended up frozen due to a mismatched truth.

### PriceChange


http://142.132.214.211/asciinema/SI-PriceChange-2.html

This is a playback of the Schelling Game from a few rounds before the recent price increase to 21 hours or so after the change. It also plays back at 100X.

## Conclusion

Thank you for your time today, and the powers-that-bee for inviting me. I'm sure I haven't covered everything in monSI, but if you have any further questions, feel free to stop by the [Swarm Discord](https://discord.com/channels/799027393297514537/811553590170353685) and ask!

## Addendum

The following monSI command is basically what was used for all of the captures in this presentation. It uses my own private gnosis RPC provider on the mainnet and specifies a collection of overlays to highlight on the screen. These are not my overlays but were selected from a /topology capture to include nodes from each of the depth 4 (first hex character) neighborhoods.

`monsi --mainnet --rpc-endpoint ws://192.168.10.20:8546 007236683d69dd5ea8d694a54fbe36ccf474d200a3960ee353ac3ac67003e37e 1017f1c5cb6d7a4edd8df99efa3ad041eb1689dd2da4bac763690d230d0db74c 200bf693fa111e19c9fe5cd2ef1fc414fd58f8941e2dee754965ddfd69dd7cbe 305aedd0d51cc7271fa97c2b0c809791dadc83439ac8fb816c8055540f095e88 409120af0de18272fe6bab33790c1e35344d4c9450128f8d5853281b20c4036e 50aab2db778b426723fe32abf398c2d8c1f5010a5de1e7311879befe5b5ef447 6072e8388aa5252cc2df8efe39e463e38457423abe83cb600cf7c4f59c5fc86e 707bf1b571b6e8a6be25e02cf04814a81cc9d2a340f5f59d300df40c4121a09f 8050975113dc0e5b057f6f72ca1fd258d2c1ae315576d64b297aa1f5bd87f0fe 90df4f4da9d6e1cc0b441bbed864fe94c039fcda1af9e2acb84f544db2f4b340 a074a1fdba0b252f0d5c1c18db834ca734ef340c2d4749441ec0e17d8c3e1228 b0028148affa10d55273f8c7b5eca540463442293684b69b9665d2f39ec0438c c004b76d5ebde6dceaf488c00e092b5ba2ffd53612291f680e6c7fdaf564c8af d00671f2328bb3f7fae72b5e631bd92872942b5bd18a1c224ac1a0944f0bca26 e053c3e256b403b63dab276bf6b7a5aa9e9fb2c4e5de3f987e48c0b477391539 f029e0f0c252263c04079c5773a4a584138579d8987ab16d3a88f5183e3baf5b 80509750303ab6ef9872cdf6c3ee36b5b4401421e53ff8b79fd5ac0175b71db6 bee0e1cc9f3f0462d6340f181fdf9fbd411173adfbe0790685c3bc828462e8e4 9af83e91a7a6f3580d4595ce7e560e633627f7effea7158fc2f17b5956267f51`