From 20c01b9fadd554c1623beb0c1052a56fb7bdd602 Mon Sep 17 00:00:00 2001
From: Leonard Lyubich <ctulhurider@gmail.com>
Date: Fri, 30 Sep 2022 15:24:28 +0400
Subject: [PATCH] [#275] netmap: Document contract storage model

Add comments (outside the docs) with key-value storage structure and
some explanations. The memory mode will allow to more precisely
understand and migrate the contract storage.

Signed-off-by: Leonard Lyubich <ctulhurider@gmail.com>
---
 netmap/doc.go | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/netmap/doc.go b/netmap/doc.go
index f19d0620..65bbc88d 100644
--- a/netmap/doc.go
+++ b/netmap/doc.go
@@ -32,3 +32,55 @@ in the network by invoking NewEpoch method.
 	    type: Integer
 */
 package netmap
+
+/*
+Contract storage model.
+
+# Summary
+Key-value storage format:
+ - 'snapshotEpoch' -> int
+   current epoch
+ - 'snapshotBlock' -> int
+   block which "ticked" the current epoch
+ - 'snapshotCount' -> int
+   number of stored network maps including current one
+ - 'snapshot_<ID>' -> std.Serialize([]storageNode)
+   network map by snapshot ID
+ - 'snapshotCurrent' -> int
+   ID of the snapshot representing current network map
+ - 'candidate<public_key>' -> std.Serialize(netmapNode)
+   information about the particular network map candidate
+ - 'containerScriptHash' -> 20-byte script hash
+   Container contract reference
+ - 'balanceScriptHash' -> 20-byte script hash
+   Balance contract reference
+ - 'notary' -> bool
+   is notary mode disabled
+ - 'innerring' -> []interop.PublicKey
+   public keys of the Inner Ring members
+ - 'config<name>' -> []byte
+   value of the particular NeoFS network parameter
+
+# Setting
+Contract can be deployed in notary and notary-disabled mode. In notary-disabled
+mode contract stores the Inner Ring members.
+
+To handle some events, the contract refers to other contracts.
+
+# Epoch
+Contract stores the current (last) NeoFS timestamp for the network within which
+the contract is deployed.
+
+# Network maps
+Contract records set of network parties representing the network map. Current
+network map is updated on each epoch tick. Contract also holds limited number of
+previous network maps (SNAPSHOT_LIMIT). Timestamped network maps are called
+snapshots. Snapshots are identified by the numerical ring [0:SNAPSHOT_LIMIT).
+
+# Network map candidates
+Contract stores information about the network parties which were requested to be
+added to the network map.
+
+# Network configuration
+Contract stores NeoFS network configuration declared in the NeoFS API protocol.
+*/