achuprov/frostfs-contract
1
0
Fork 0
forked from TrueCloudLab/frostfs-contract
Code Pull requests Activity

[#89] frostfsid: Add description for FrostFS ID

Browse source 
Signed-off-by: Alexander Chuprov <a.chuprov@yadro.com>
This commit is contained in:
Alexander Chuprov 2024-05-24 21:32:20 +03:00
parent db36131800
commit ba4ef7bd22
1 changed files with 57 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
frostfsid/frostfsid_contract.go
View file

@ -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)