[#89] frostfsid: Add description for FrostFS ID

Signed-off-by: Alexander Chuprov <a.chuprov@yadro.com>

frostfsid/frostfsid_contract.go

@@ -14,6 +14,13 @@ import (
 )
 
 type (
+	// Subject represents a subject entity.
+	//
+	// Fields:
+	//   - Namespace: a string representing the namespace of the subject.
+	//   - Name: a string representing the name of the subject.
+	//     The name must match the following regex pattern: ^[\w+=,.@-]{1,64}$
+	// The Subject is stored in the storage as a hash(namespace) + hash(name).
 	Subject struct {
 		PrimaryKey     interop.PublicKey
 		AdditionalKeys []interop.PublicKey
@@ -31,6 +38,15 @@ type (
 		Groups         []Group
 	}
 
+	// Namespace represents a namespace.
+	//
+	// Fields:
+	//   - Name: a string representing the name of the namespace.
+	//     The custom name must match the following regex pattern:
+	//     (^$)|(^[a-z0-9]{1,2}$)|(^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$)
+	//     An empty Name is considered the <root> namespace.
+	//
+	// The Namespace is stored in the storage as a hash(name).
 	Namespace struct {
 		Name string
 	}
@@ -41,6 +57,18 @@ type (
 		SubjectsCount int
 	}
 
+	// Group represents a group entity.
+	//
+	// Fields:
+	//   - ID: an integer representing the unique identifier of the group.
+	//     The ID is generated upon creation and is the sequential number of the group within the namespace.
+	//     It cannot be changed once set.
+	//   - Name: a string representing the name of the group.
+	//     The name must match the following regex pattern: [\w+=,.@-]{1,128}$
+	//   - Namespace: a string representing the namespace of the group.
+	//     A group exists only within one namespace.
+	//
+	// The group is stored in the storage as a hash(namespace) + hash(name).
 	Group struct {
 		ID        int
 		Name      string
@@ -90,6 +118,7 @@ func _deploy(data any, isUpdate bool) {
 	runtime.Log("frostfsid contract initialized")
 }
 
+// SetAdmin sets the admin address for the contract.
 func SetAdmin(addr interop.Hash160) {
 	ctx := storage.GetContext()
 	if !common.HasUpdateAccess() {
@@ -99,6 +128,7 @@ func SetAdmin(addr interop.Hash160) {
 	storage.Put(ctx, adminKey, addr)
 }
 
+// ClearAdmin removes the admin address from the contract storage.
 func ClearAdmin() {
 	ctx := storage.GetContext()
 	if !common.HasUpdateAccess() {
@@ -108,6 +138,7 @@ func ClearAdmin() {
 	storage.Delete(ctx, adminKey)
 }
 
+// GetAdmin retrieves the admin address from the contract storage.
 func GetAdmin() interop.Hash160 {
 	ctx := storage.GetReadOnlyContext()
 	return storage.Get(ctx, adminKey).(interop.Hash160)
@@ -129,6 +160,7 @@ func Version() int {
 	return common.Version
 }
 
+// CreateSubject creates a new subject in the specified namespace with the provided public key.
 func CreateSubject(ns string, key interop.PublicKey) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -169,6 +201,7 @@ func CreateSubject(ns string, key interop.PublicKey) {
 	runtime.Notify("CreateSubject", interop.Hash160(addr))
 }
 
+// AddSubjectKey adds an additional public key to a subject with the specified address.
 func AddSubjectKey(addr interop.Hash160, key interop.PublicKey) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -200,6 +233,7 @@ func AddSubjectKey(addr interop.Hash160, key interop.PublicKey) {
 	runtime.Notify("AddSubjectKey", addr, key)
 }
 
+// RemoveSubjectKey removes an additional public key from the subject with the specified address.
 func RemoveSubjectKey(addr interop.Hash160, key interop.PublicKey) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -238,6 +272,7 @@ func RemoveSubjectKey(addr interop.Hash160, key interop.PublicKey) {
 	runtime.Notify("RemoveSubjectKey", addr, key)
 }
 
+// SetSubjectName sets a new name for the subject with the specified address.
 func SetSubjectName(addr interop.Hash160, name string) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -262,6 +297,7 @@ func SetSubjectName(addr interop.Hash160, name string) {
 	runtime.Notify("SetSubjectName", addr, name)
 }
 
+// SetSubjectKV sets a key-value pair for the subject with the specified address.
 func SetSubjectKV(addr interop.Hash160, key, val string) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -286,6 +322,7 @@ func SetSubjectKV(addr interop.Hash160, key, val string) {
 	runtime.Notify("SetSubjectKV", addr, key, val)
 }
 
+// DeleteSubjectKV deletes a key-value pair from the subject with the specified address.
 func DeleteSubjectKV(addr interop.Hash160, key string) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -307,6 +344,7 @@ func DeleteSubjectKV(addr interop.Hash160, key string) {
 	runtime.Notify("DeleteSubjectKV", addr, key)
 }
 
+// DeleteSubject deletes the subject with the specified address.
 func DeleteSubject(addr interop.Hash160) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -333,6 +371,7 @@ func DeleteSubject(addr interop.Hash160) {
 	runtime.Notify("DeleteSubject", addr)
 }
 
+// GetSubject retrieves the subject with the specified address.
 func GetSubject(addr interop.Hash160) Subject {
 	if len(addr) != interop.Hash160Len {
 		panic("incorrect address length")
@@ -348,6 +387,7 @@ func GetSubject(addr interop.Hash160) Subject {
 	return std.Deserialize(data).(Subject)
 }
 
+// GetSubjectExtended retrieves the extended information of the subject with the specified address.
 func GetSubjectExtended(addr interop.Hash160) SubjectExtended {
 	subj := GetSubject(addr)
 	ctx := storage.GetReadOnlyContext()
@@ -379,6 +419,7 @@ func GetSubjectExtended(addr interop.Hash160) SubjectExtended {
 	return subjExt
 }
 
+// GetSubjectByKey retrieves the subject associated with the provided public key.
 func GetSubjectByKey(key interop.PublicKey) Subject {
 	if len(key) != interop.PublicKeyCompressedLen {
 		panic("incorrect key length")
@@ -407,12 +448,14 @@ func GetSubjectByKey(key interop.PublicKey) Subject {
 	panic("subject not found")
 }
 
+// GetSubjectByName retrieves the subject with the specified name within the given namespace.
 func GetSubjectByName(ns, name string) Subject {
 	key := GetSubjectKeyByName(ns, name)
 	addr := contract.CreateStandardAccount(key)
 	return GetSubject(addr)
 }
 
+// GetSubjectKeyByName retrieves the public key of the subject with the specified namespace and name.
 func GetSubjectKeyByName(ns, name string) interop.PublicKey {
 	if name == "" {
 		panic("invalid or name")
@@ -434,6 +477,7 @@ func ListSubjects() iterator.Iterator {
 	return storage.Find(ctx, []byte{subjectKeysPrefix}, storage.KeysOnly|storage.RemovePrefix)
 }
 
+// CreateNamespace creates a new namespace with the specified name.
 func CreateNamespace(ns string) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -452,6 +496,7 @@ func CreateNamespace(ns string) {
 	runtime.Notify("CreateNamespace", ns)
 }
 
+// GetNamespace retrieves the namespace with the specified name.
 func GetNamespace(ns string) Namespace {
 	ctx := storage.GetReadOnlyContext()
 	nsKey := namespaceKey(ns)
@@ -463,6 +508,7 @@ func GetNamespace(ns string) Namespace {
 	return std.Deserialize(data).(Namespace)
 }
 
+// GetNamespaceExtended retrieves extended information about the namespace.
 func GetNamespaceExtended(ns string) NamespaceExtended {
 	ctx := storage.GetReadOnlyContext()
 	nsKey := namespaceKey(ns)
@@ -499,6 +545,7 @@ func ListNamespaceSubjects(ns string) iterator.Iterator {
 	return storage.Find(ctx, namespaceSubjectPrefix(ns), storage.KeysOnly|storage.RemovePrefix)
 }
 
+// CreateGroup creates a new group within the specified namespace.
 func CreateGroup(ns, group string) int {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -533,6 +580,7 @@ func CreateGroup(ns, group string) int {
 	return groupCountID
 }
 
+// GetGroup retrieves the group with the specified ID within the given namespace.
 func GetGroup(ns string, groupID int) Group {
 	ctx := storage.GetReadOnlyContext()
 	gKey := groupKey(ns, groupID)
@@ -544,6 +592,7 @@ func GetGroup(ns string, groupID int) Group {
 	return std.Deserialize(data).(Group)
 }
 
+// GetGroupExtended retrieves extended information about the group, including the count of subjects in the group.
 func GetGroupExtended(ns string, groupID int) GroupExtended {
 	ctx := storage.GetReadOnlyContext()
 	gKey := groupKey(ns, groupID)
@@ -569,6 +618,7 @@ func GetGroupExtended(ns string, groupID int) GroupExtended {
 	return grExtended
 }
 
+// GetGroupIDByName retrieves the ID of the group with the specified name within the given namespace.
 func GetGroupIDByName(ns, name string) int {
 	if name == "" {
 		panic("invalid name")
@@ -585,6 +635,7 @@ func GetGroupIDByName(ns, name string) int {
 	return std.Deserialize(groupIDRaw).(int)
 }
 
+// GetGroupByName retrieves the group with the specified name within the given namespace.
 func GetGroupByName(ns, name string) Group {
 	groupID := GetGroupIDByName(ns, name)
 	gKey := groupKey(ns, groupID)
@@ -598,6 +649,7 @@ func GetGroupByName(ns, name string) Group {
 	return std.Deserialize(data).(Group)
 }
 
+// SetGroupName sets a new name for the group with the specified ID within the given namespace.
 func SetGroupName(ns string, groupID int, name string) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -618,6 +670,7 @@ func SetGroupName(ns string, groupID int, name string) {
 	runtime.Notify("SetGroupName", ns, groupID, name)
 }
 
+// SetGroupKV sets a key-value pair for the group with the specified ID within the given namespace.
 func SetGroupKV(ns string, groupID int, key, val string) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -638,6 +691,7 @@ func SetGroupKV(ns string, groupID int, key, val string) {
 	runtime.Notify("SetGroupKV", ns, groupID, key, val)
 }
 
+// DeleteGroupKV deletes a key-value pair from the group with the specified ID within the given namespace.
 func DeleteGroupKV(ns string, groupID int, key string) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -660,6 +714,7 @@ func ListGroups(ns string) iterator.Iterator {
 	return storage.Find(ctx, groupPrefix(ns), storage.ValuesOnly|storage.DeserializeValues)
 }
 
+// AddSubjectToGroup adds a subject to a group with the specified ID.
 func AddSubjectToGroup(addr interop.Hash160, groupID int) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -692,6 +747,7 @@ func AddSubjectToGroup(addr interop.Hash160, groupID int) {
 	runtime.Notify("AddSubjectToGroup", addr, subject.Namespace, groupID)
 }
 
+// RemoveSubjectFromGroup removes a subject from a group with the specified ID.
 func RemoveSubjectFromGroup(addr interop.Hash160, groupID int) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)
@@ -730,6 +786,7 @@ func ListGroupSubjects(ns string, groupID int) iterator.Iterator {
 	return storage.Find(ctx, groupSubjectPrefix(ns, groupID), storage.KeysOnly|storage.RemovePrefix)
 }
 
+// DeleteGroup deletes the group with the specified ID within the given namespace.
 func DeleteGroup(ns string, groupID int) {
 	ctx := storage.GetContext()
 	checkContractOwner(ctx)