From f21c439e9ca17a09c013e063dae5942a4d352f25 Mon Sep 17 00:00:00 2001
From: Alex Vanin <alexey@nspcc.ru>
Date: Mon, 5 Jul 2021 19:25:29 +0300
Subject: [PATCH] [#105] audit: Add docs

Signed-off-by: Alex Vanin <alexey@nspcc.ru>
---
 audit/audit_contract.go | 20 ++++++++++++++++++++
 audit/doc.go            | 22 +++++++++++++++++++++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/audit/audit_contract.go b/audit/audit_contract.go
index aaeb028..fb02385 100644
--- a/audit/audit_contract.go
+++ b/audit/audit_contract.go
@@ -75,6 +75,8 @@ func _deploy(data interface{}, isUpdate bool) {
 	runtime.Log("audit contract initialized")
 }
 
+// Migrate method updates contract source code and manifest. Can be invoked
+// only by contract owner.
 func Migrate(script []byte, manifest []byte, data interface{}) bool {
 	ctx := storage.GetReadOnlyContext()
 
@@ -89,6 +91,12 @@ func Migrate(script []byte, manifest []byte, data interface{}) bool {
 	return true
 }
 
+// Put method stores stable marshalled `DataAuditResult` structure. Can be
+// invoked only by Inner Ring nodes.
+//
+// Inner Ring nodes perform audit of the containers and produce `DataAuditResult`
+// structures. They are being stored in audit contract and used for settlements
+// in later epochs.
 func Put(rawAuditResult []byte) {
 	ctx := storage.GetContext()
 	notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool)
@@ -123,11 +131,16 @@ func Put(rawAuditResult []byte) {
 	runtime.Log("audit: result has been saved")
 }
 
+// Get method returns stable marshaled DataAuditResult structure.
+//
+// ID of the DataAuditResult can be obtained from listing methods.
 func Get(id []byte) []byte {
 	ctx := storage.GetReadOnlyContext()
 	return storage.Get(ctx, id).([]byte)
 }
 
+// List method returns list of all available DataAuditResult IDs from
+// contract storage.
 func List() [][]byte {
 	ctx := storage.GetReadOnlyContext()
 	it := storage.Find(ctx, []byte{}, storage.KeysOnly)
@@ -135,6 +148,8 @@ func List() [][]byte {
 	return list(it)
 }
 
+// ListByEpoch method returns list of DataAuditResult IDs generated in
+// specified epoch.
 func ListByEpoch(epoch int) [][]byte {
 	ctx := storage.GetReadOnlyContext()
 	var buf interface{} = epoch
@@ -143,6 +158,8 @@ func ListByEpoch(epoch int) [][]byte {
 	return list(it)
 }
 
+// ListByCID method returns list of DataAuditResult IDs generated in
+// specified epoch for specified container.
 func ListByCID(epoch int, cid []byte) [][]byte {
 	ctx := storage.GetReadOnlyContext()
 
@@ -154,6 +171,8 @@ func ListByCID(epoch int, cid []byte) [][]byte {
 	return list(it)
 }
 
+// ListByNode method returns list of DataAuditResult IDs generated in
+// specified epoch for specified container by specified Inner Ring node.
 func ListByNode(epoch int, cid []byte, key interop.PublicKey) [][]byte {
 	ctx := storage.GetReadOnlyContext()
 	hdr := auditHeader{
@@ -191,6 +210,7 @@ loop:
 	return result
 }
 
+// Version returns version of the contract.
 func Version() int {
 	return version
 }
diff --git a/audit/doc.go b/audit/doc.go
index bb8d197..a37bdfe 100644
--- a/audit/doc.go
+++ b/audit/doc.go
@@ -1,2 +1,22 @@
-// Audit contract description.
+/*
+Audit contract is a contract deployed in NeoFS side chain.
+
+Inner Ring nodes perform an audit of the registered containers in every epoch.
+If container contains StorageGroup objects, then the Inner Ring node initializes
+a series of audit checks. Based on the results of these checks, the Inner Ring
+node creates a DataAuditResult structure for the container. The content of this
+structure makes it possible to determine which storage nodes were examined and
+the status of these checks. Based on this information, container owner is
+charged for data storage.
+
+Audit contract is used as reliable and verifiable storage for all
+DataAuditResult structures. At the end of the data audit routine, the Inner Ring
+nodes send a stable marshaled version of the DataAuditResult structure to the
+contract. When Alphabet nodes of the Inner Ring perform settlement operations,
+they list and get these AuditResultStructures from the audit contract.
+
+Contract notifications
+
+Alphabet contract does not produce notifications to process.
+*/
 package audit