From 4b9106331fb79ce25a8363fb0768971b11bc76e2 Mon Sep 17 00:00:00 2001 From: Leonard Lyubich Date: Wed, 1 Feb 2023 18:38:21 +0400 Subject: [PATCH] [#275] *: 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. Signed-off-by: Leonard Lyubich --- alphabet/doc.go | 23 ++++++++++++++++++++++ audit/doc.go | 16 ++++++++++++++++ balance/doc.go | 14 ++++++++++++++ container/doc.go | 49 +++++++++++++++++++++++++++++++++++++++++++++++ neofs/doc.go | 33 +++++++++++++++++++++++++++++++ neofsid/doc.go | 15 +++++++++++++++ netmap/doc.go | 7 ------- processing/doc.go | 12 ++++++++++++ proxy/doc.go | 6 ++++++ reputation/doc.go | 19 ++++++++++++++++++ 10 files changed, 187 insertions(+), 7 deletions(-) diff --git a/alphabet/doc.go b/alphabet/doc.go index 6c77ff93..2f0fd0a6 100644 --- a/alphabet/doc.go +++ b/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. +*/ diff --git a/audit/doc.go b/audit/doc.go index 55a45314..ccd18572 100644 --- a/audit/doc.go +++ b/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. 8-byte 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. +*/ diff --git a/balance/doc.go b/balance/doc.go index cada2122..254c68bd 100644 --- a/balance/doc.go +++ b/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. +*/ diff --git a/container/doc.go b/container/doc.go index 114c119c..35aa8881 100644 --- a/container/doc.go +++ b/container/doc.go @@ -67,3 +67,52 @@ it in Container contract. type: Integer */ package container + +/* +Contract storage model. + +# Summary +Current conventions: + : 32-byte container identifier (SHA-256 hashes of container data) + : 25-byte NEO3 account of owner of the particular container + : 8-byte 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' -> []byte + container descriptors encoded into NeoFS API binary protocol format + - 'o' -> + user-by-user containers + - 'nnsHasAlias' -> string + domains registered for containers in the NNS + - 'cnr' + [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 -> [] + 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. +*/ diff --git a/neofs/doc.go b/neofs/doc.go index 0583266c..8046776e 100644 --- a/neofs/doc.go +++ b/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. +*/ diff --git a/neofsid/doc.go b/neofsid/doc.go index 4b4f43b0..1c6cb3e7 100644 --- a/neofsid/doc.go +++ b/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. +*/ diff --git a/netmap/doc.go b/netmap/doc.go index 88505854..b0082e98 100644 --- a/netmap/doc.go +++ b/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' -> []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 diff --git a/processing/doc.go b/processing/doc.go index 002a0094..92c2e17b 100644 --- a/processing/doc.go +++ b/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. +*/ diff --git a/proxy/doc.go b/proxy/doc.go index 8effb041..ded826eb 100644 --- a/proxy/doc.go +++ b/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. +*/ diff --git a/reputation/doc.go b/reputation/doc.go index 0e582bf9..20ead6a9 100644 --- a/reputation/doc.go +++ b/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: + : binary unique identifier of the NeoFS Reputation system participant + : 8-byte little-endian unsigned integer NeoFS epoch + +# Summary +Key-value storage format: + - 'c' -> int + Number of values got from calculated by fixed peer at fixed NeoFS epoch + - 'r' + 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. +*/