*: Describe storage model of contracts

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

Refs #275

Signed-off-by: Leonard Lyubich <[email protected]>

alphabet/doc.go

@@ -20,3 +20,26 @@ for each alphabet contract.
 Alphabet contract does not produce notifications to process.
 */
 package alphabet
+
+/*
+Contract storage model.
+
+# Summary
+Key-value storage format:
+ - 'netmapScriptHash' -> interop.Hash160
+   Netmap contract reference
+ - 'proxyScriptHash' -> interop.Hash160
+   Proxy contract reference
+ - 'name' -> string
+   name (Glagolitic letter) of the contract
+ - 'index' -> int
+   member index in the Alphabet list
+ - 'threshold' -> int
+   currently unused value
+
+# Setting
+To handle some events, the contract refers to other contracts.
+
+# Membership
+Contracts are named and positioned in the Alphabet list of the NeoFS Sidechain.
+*/

audit/doc.go

@@ -21,3 +21,19 @@ they make a list and get these AuditResultStructures from the audit contract.
 Audit contract does not produce notifications to process.
 */
 package audit
+
+/*
+Contract storage model.
+
+# Summary
+Key-value storage format:
+ - [64]byte -> []byte
+   Data audit results encoded into NeoFS API binary protocol format. Results are
+   identified by triplet concatenation:
+    1. little-endian unsigned integer NeoFS epoch when audit was performed
+    2. 32-byte identifier of the NeoFS container under audit
+    3. 24-byte prefix of SHA-256 hash of the auditor's (Inner Ring) public key
+
+# Audit history
+Contracts stores results of the NeoFS data audits performed by the Inner Ring.
+*/

balance/doc.go

@@ -77,3 +77,17 @@ when NeoFS contract has transferred GAS assets back to the user.
 	    type: Integer
 */
 package balance
+
+/*
+Contract storage model.
+
+# Summary
+Key-value storage format:
+ - 'MainnetGAS' -> int
+   total amount of Mainchain GAS deployed in the NeoFS network
+ - interop.Hash160 -> std.Serialize(Account)
+   balance sheet of all NeoFS users (here Account is a structure defined in current package)
+
+# Accounting
+Contract stores information about all NeoFS accounts.
+*/

container/doc.go

@@ -67,3 +67,52 @@ 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>: little-endian unsigned integer NeoFS epoch
+
+Key-value storage format:
+ - '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
+To handle some events, the contract refers to other contracts.
+
+# Containers
+Contract stores information about all containers (incl. extended ACL tables)
+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.
+*/

neofs/doc.go

@@ -92,3 +92,36 @@ NeoFS network configuration value.
 	    type: ByteArray
 */
 package neofs
+
+/*
+Contract storage model.
+
+# Summary
+Key-value storage format:
+ - 'notary' -> bool
+   is notary mode disabled
+ - 'ballots' -> std.Serialize([]Ballot)
+   collected ballots for pending voting if notary disabled (here Ballot is a
+   structure defined in common package)
+ - 'processingScriptHash' -> interop.Hash160
+   Processing contract reference
+ - 'candidates' + interop.PublicKey -> 1
+   each participant who is considered for entry into the Inner Ring
+ - 'alphabet' -> []interop.PublicKey
+   list of the NeoFS Alphabet members
+
+# Setting
+Contract can be deployed in notary and notary-disabled mode.
+
+To handle some events, the contract refers to other contracts.
+
+# Network configuration
+Contract storage configuration of the NeoFS network within which the contract is
+deployed.
+
+# Inner Ring Contract accumulates candidates for the Inner Ring. It also holds
+current NeoFS Alphabet.
+
+# Voting
+Contract collects voting data in notary-disabled installation.
+*/

neofsid/doc.go

@@ -19,3 +19,18 @@ contract.
 NeoFSID contract does not produce notifications to process.
 */
 package neofsid
+
+/*
+Contract storage model.
+
+# Summary
+Key-value storage format:
+ - 'netmapScriptHash' -> interop.Hash160
+   Netmap contract reference (currently unused)
+ - 'o' + ID + interop.PublicKey -> 1
+   each key of the NeoFS user identified by 25-byte NEO3 account
+
+# Keychains
+Contract collects all keys of the NeoFS users except ones that may be directly
+resolved into user ID.
+*/

netmap/doc.go

@@ -54,17 +54,10 @@ Key-value storage format:
    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

processing/doc.go

@@ -21,3 +21,15 @@ execution.
 Processing contract does not produce notifications to process.
 */
 package processing
+
+/*
+Contract storage model.
+
+# Summary
+Key-value storage format:
+ - 'neofsScriptHash' -> interop.Hash160
+   NeoFS contract reference
+
+# Setting
+To handle some events, the contract refers to other contracts.
+*/

proxy/doc.go

@@ -20,3 +20,9 @@ verified, Proxy contract pays for the execution.
 Proxy contract does not produce notifications to process.
 */
 package proxy
+
+/*
+Contract storage model.
+
+At the moment, no data is stored in the contract.
+*/

reputation/doc.go

@@ -16,3 +16,22 @@ Inner Ring nodes if data audit succeeds.
 Reputation contract does not produce notifications to process.
 */
 package reputation
+
+/*
+Contract storage model.
+
+Current conventions:
+ <peer>: binary unique identifier of the NeoFS Reputation system participant
+ <epoch>: little-endian unsigned integer NeoFS epoch
+
+# Summary
+Key-value storage format:
+ - 'c<epoch><peer>' -> int
+   Number of values got from calculated by fixed peer at fixed NeoFS epoch
+ - 'r<epoch><peer>' + count -> []byte
+   binary-encoded global trust values submitted calculated at fixed epoch by
+   particular peer. All such values are counted starting from 0.
+
+# Trust
+Contract stores trust values collected within NeoFS Reputation system lifetime.
+*/

subnet/doc.go

@@ -36,3 +36,37 @@ by invoking RemoveNode method.
 	    type: PublicKey
 */
 package subnet
+
+/*
+Contract storage model.
+
+# Summary
+Current conventions:
+ <id>: binary-encoded unique identifier of the subnet
+
+Key-value storage format:
+ - 'o<id>' -> interop.PublicKey
+   public keys of the subnet owners
+ - 'i<id>' -> []byte
+   subnet descriptors encoded into NeoFS API binary protocol format
+ - 'n<id>' + interop.PublicKey -> 1
+   public keys of nodes forming the subnet cluster
+ - 'a<id>' + interop.PublicKey -> 1
+   public keys of administrators managing topology of the subnet cluster
+ - 'u<id>' + interop.PublicKey -> 1
+   public keys of clients using the subnet to store data
+ - 'm<id>' + interop.PublicKey -> 1
+   public keys of administrators managing clients of the subnet
+
+# Registration
+Contract stores information about all subnets and their owners presented in the
+NeoFS network for which the contract is deployed.
+
+# Topology management
+Contract records the parties responsible for managing subnets' cluster
+topology.
+
+# Client management
+Contract records the parties responsible for managing subnet clients which store
+data in the subnet cluster.
+*/