From ba4ef7bd22e8fc75d3eb4b6647bd40fed059259b Mon Sep 17 00:00:00 2001 From: Alexander Chuprov Date: Fri, 24 May 2024 21:32:20 +0300 Subject: [PATCH] [#89] frostfsid: Add description for FrostFS ID Signed-off-by: Alexander Chuprov --- frostfsid/frostfsid_contract.go | 57 +++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/frostfsid/frostfsid_contract.go b/frostfsid/frostfsid_contract.go index 9362465..d7c2f38 100644 --- a/frostfsid/frostfsid_contract.go +++ b/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 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)