From bbe1162217c542813e41ae6eac298248e9189ab7 Mon Sep 17 00:00:00 2001
From: Leonard Lyubich <ctulhurider@gmail.com>
Date: Thu, 2 Feb 2023 13:03:35 +0400
Subject: [PATCH] [#275] container: 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>
---
 container/doc.go | 52 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/container/doc.go b/container/doc.go
index 114c119c..a6c7beef 100644
--- a/container/doc.go
+++ b/container/doc.go
@@ -67,3 +67,55 @@ it in Container contract.
 	    type: Integer
 */
 package container
+
+/*
+Contract storage model.
+
+# Summary
+Current conventions:
+ <cid>: 32-byte container identifier (SHA-256 hashes of container data)
+ <owner>: 25-byte NEO3 account of owner of the particular container
+ <epoch>: 8-byte little-endian unsigned integer NeoFS epoch
+Key-value storage format:
+ - 'notary' -> bool
+   is notary mode disabled
+ - 'netmapScriptHash' -> interop.Hash160
+   Netmap contract reference
+ - 'balanceScriptHash' -> interop.Hash160
+   Balance contract reference
+ - 'identityScriptHash' -> interop.Hash160
+   NeoFSID contract reference
+ - 'nnsScriptHash' -> interop.Hash160
+   NNS contract reference
+ - 'nnsRoot' -> interop.Hash160
+   NNS root domain zone for containers
+ - 'x<cid>' -> []byte
+   container descriptors encoded into NeoFS API binary protocol format
+ - 'o<owner><cid>' -> <cid>
+   user-by-user containers
+ - 'nnsHasAlias<cid>' -> string
+   domains registered for containers in the NNS
+ - 'cnr<epoch><cid>' + [10]byte -> std.Serialize(estimation)
+   estimation of the container size sent by the storage node. Key suffix is first
+   10 bytes of RIPEMD-160 hash of the storage node's public key
+   (interop.PublicKey). Here estimation is a type.
+ - 'est' + [20]byte -> []<epoch>
+   list of NeoFS epochs when particular storage node sent estimations. Suffix is
+   RIPEMD-160 hash of the storage node's public key (interop.PublicKey).
+
+# Setting
+Contract can be deployed in notary and notary-disabled mode.
+
+To handle some events, the contract refers to other contracts.
+
+# Containers
+Contract stores information about all containers presented in the NeoFS network
+for which the contract is deployed. For performance optimization, container
+are additionally indexed by their owners.
+
+# NNS
+Contract tracks container-related domains registered in the NNS.
+
+# Size estimations
+Contract stores containers' size estimations came from NeoFS storage nodes.
+*/