From 47af5e3f9c42ae3a96de2be5d560ecdad62892eb Mon Sep 17 00:00:00 2001
From: Alex Vanin <alexey@nspcc.ru>
Date: Tue, 13 Jul 2021 21:08:27 +0300
Subject: [PATCH] [#105] neofsid: Add docs

Signed-off-by: Alex Vanin <alexey@nspcc.ru>
---
 neofsid/doc.go              | 20 +++++++++++++++++++-
 neofsid/neofsid_contract.go | 16 ++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/neofsid/doc.go b/neofsid/doc.go
index a0148fe..8323327 100644
--- a/neofsid/doc.go
+++ b/neofsid/doc.go
@@ -1,2 +1,20 @@
-// NeoFSID contract description.
+/*
+NeoFSID contract is a contract deployed in NeoFS side chain.
+
+NeoFSID contract used to store connection between OwnerID and it's public keys.
+OwnerID is a 25-byte N3 wallet address that can be produced from public key.
+It is one-way conversion. In simple cases NeoFS verifies ownership by checking
+signature and relation between public key and OwnerID.
+
+In more complex cases, user can use public keys unrelated to OwnerID to maintain
+secure access to the data. NeoFSID contract stores relation between OwnerID and
+arbitrary public keys. Data owner can bind or unbind public key with it's account
+by invoking Bind or Unbind methods of NeoFS contract in main chain. After that,
+Alphabet nodes produce multi signed AddKey and RemoveKey invocations of NeoFSID
+contract.
+
+Contract notifications
+
+NeoFSID contract does not produce notifications to process.
+*/
 package neofsid
diff --git a/neofsid/neofsid_contract.go b/neofsid/neofsid_contract.go
index 601770e..1772941 100644
--- a/neofsid/neofsid_contract.go
+++ b/neofsid/neofsid_contract.go
@@ -60,6 +60,8 @@ func _deploy(data interface{}, isUpdate bool) {
 	runtime.Log("neofsid 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()
 
@@ -74,6 +76,11 @@ func Migrate(script []byte, manifest []byte, data interface{}) bool {
 	return true
 }
 
+// AddKey binds list of provided public keys to OwnerID. Can be invoked only by
+// Alphabet nodes.
+//
+// This method panics if OwnerID is not 25 byte or public key is not 33 byte long.
+// If key is already bound, ignores it.
 func AddKey(owner []byte, keys []interop.PublicKey) {
 	if len(owner) != 25 {
 		panic("addKey: incorrect owner")
@@ -142,6 +149,11 @@ addLoop:
 	runtime.Log("addKey: key bound to the owner")
 }
 
+// RemoveKey unbinds provided public keys from OwnerID. Can be invoked only by
+// Alphabet nodes.
+//
+// This method panics if OwnerID is not 25 byte or public key is not 33 byte long.
+// If key is already unbound, ignores it.
 func RemoveKey(owner []byte, keys []interop.PublicKey) {
 	if len(owner) != 25 {
 		panic("removeKey: incorrect owner")
@@ -206,6 +218,9 @@ rmLoop:
 	common.SetSerialized(ctx, owner, info)
 }
 
+// Key method returns list of 33-byte public keys bound with OwnerID.
+//
+// This method panics if owner is not 25 byte long.
 func Key(owner []byte) [][]byte {
 	if len(owner) != 25 {
 		panic("key: incorrect owner")
@@ -218,6 +233,7 @@ func Key(owner []byte) [][]byte {
 	return info.Keys
 }
 
+// Version returns version of the contract.
 func Version() int {
 	return version
 }