diff --git a/container/container_contract.go b/container/container_contract.go index 874788b..746859e 100644 --- a/container/container_contract.go +++ b/container/container_contract.go @@ -131,6 +131,8 @@ func migrateEstimationStorage(ctx storage.Context) { } } +// 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() @@ -145,6 +147,14 @@ func Migrate(script []byte, manifest []byte, data interface{}) bool { return true } +// Put method creates new container if it was invoked by Alphabet nodes +// of the Inner Ring. Otherwise it produces containerPut notification. +// +// Container should be stable marshaled Container structure from API. +// Signature is a RFC6979 signature of Container. +// PublicKey contains public key of the signer. +// Token is optional and should be stable marshaled SessionToken structure from +// API. func Put(container []byte, signature interop.Signature, publicKey interop.PublicKey, token []byte) { ctx := storage.GetContext() notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) @@ -223,6 +233,13 @@ func Put(container []byte, signature interop.Signature, publicKey interop.Public runtime.Log("put: added new container") } +// Delete method removes container from contract storage if it was +// invoked by Alphabet nodes of the Inner Ring. Otherwise it produces +// containerDelete notification. +// +// Signature is a RFC6979 signature of container ID. +// Token is optional and should be stable marshaled SessionToken structure from +// API. func Delete(containerID []byte, signature interop.Signature, token []byte) { ctx := storage.GetContext() notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) @@ -268,16 +285,21 @@ func Delete(containerID []byte, signature interop.Signature, token []byte) { runtime.Log("delete: remove container") } +// Get method returns structure that contains stable marshaled Container structure, +// signature, public key of the container creator and stable marshaled SessionToken +// structure if it was provided. func Get(containerID []byte) Container { ctx := storage.GetReadOnlyContext() return getContainer(ctx, containerID) } +// Owner method returns 25 byte Owner ID of the container. func Owner(containerID []byte) []byte { ctx := storage.GetReadOnlyContext() return getOwnerByID(ctx, containerID) } +// List method returns list of all container IDs owned by specified owner. func List(owner []byte) [][]byte { ctx := storage.GetReadOnlyContext() @@ -296,6 +318,15 @@ func List(owner []byte) [][]byte { return list } +// SetEACL method sets new extended ACL table related to the contract +// if it was invoked by Alphabet nodes of the Inner Ring. Otherwise it produces +// setEACL notification. +// +// EACL should be stable marshaled EACLTable structure from API. +// Signature is a RFC6979 signature of Container. +// PublicKey contains public key of the signer. +// Token is optional and should be stable marshaled SessionToken structure from +// API. func SetEACL(eACL []byte, signature interop.Signature, publicKey interop.PublicKey, token []byte) { ctx := storage.GetContext() notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) @@ -356,6 +387,9 @@ func SetEACL(eACL []byte, signature interop.Signature, publicKey interop.PublicK runtime.Log("setEACL: success") } +// EACL method returns structure that contains stable marshaled EACLTable structure, +// signature, public key of the extended ACL setter and stable marshaled SessionToken +// structure if it was provided. func EACL(containerID []byte) ExtendedACL { ctx := storage.GetReadOnlyContext() @@ -367,6 +401,9 @@ func EACL(containerID []byte) ExtendedACL { return getEACL(ctx, containerID) } +// PutContainerSize method saves container size estimation in contract +// memory. Can be invoked only by Storage nodes from the network map. Method +// checks witness based on the provided public key of the Storage node. func PutContainerSize(epoch int, cid []byte, usedSize int, pubKey interop.PublicKey) { ctx := storage.GetContext() @@ -390,6 +427,13 @@ func PutContainerSize(epoch int, cid []byte, usedSize int, pubKey interop.Public runtime.Log("container: saved container size estimation") } +// GetContainerSize method returns container ID and slice of container +// estimations. Container estimation includes public key of the Storage Node +// that registered estimation and value of estimation. +// +// Use ID obtained from ListContainerSizes method. Estimations are removed +// from contract storage every epoch, see NewEpoch method, therefore method +// can return different results in different epochs. func GetContainerSize(id []byte) containerSizes { ctx := storage.GetReadOnlyContext() @@ -401,6 +445,8 @@ func GetContainerSize(id []byte) containerSizes { return getContainerSizeEstimation(ctx, id, cid) } +// ListContainerSizes method returns IDs of container size estimations +// that has been registered for specified epoch. func ListContainerSizes(epoch int) [][]byte { ctx := storage.GetReadOnlyContext() @@ -431,6 +477,8 @@ func ListContainerSizes(epoch int) [][]byte { return result } +// NewEpoch method removes all container size estimations from epoch older than +// epochNum + 3. Can be invoked only by NewEpoch method of the Netmap contract. func NewEpoch(epochNum int) { ctx := storage.GetContext() notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) @@ -457,6 +505,8 @@ func NewEpoch(epochNum int) { } } +// StartContainerEstimation method produces StartEstimation notification. +// Can be invoked only by Alphabet nodes of the Inner Ring. func StartContainerEstimation(epoch int) { ctx := storage.GetContext() notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) @@ -495,6 +545,8 @@ func StartContainerEstimation(epoch int) { runtime.Log("startEstimation: notification has been produced") } +// StopContainerEstimation method produces StopEstimation notification. +// Can be invoked only by Alphabet nodes of the Inner Ring. func StopContainerEstimation(epoch int) { ctx := storage.GetContext() notaryDisabled := storage.Get(ctx, notaryDisabledKey).(bool) @@ -533,6 +585,7 @@ func StopContainerEstimation(epoch int) { runtime.Log("stopEstimation: notification has been produced") } +// Version returns version of the contract. func Version() int { return version } diff --git a/container/doc.go b/container/doc.go index 3cb0688..94477fe 100644 --- a/container/doc.go +++ b/container/doc.go @@ -1,2 +1,68 @@ -// Container contract description. +/* +Container contract is a contract deployed in NeoFS side chain. + +Container contract stores and manages containers, extended ACLs and container +size estimations. Contract does not perform sanity or signature checks of the +containers or extended ACLs, it is done by Alphabet nodes of the Inner Ring. +Alphabet nodes approve it by invoking the same Put or SetEACL methods with +the same arguments. + +Contract notifications + +containerPut notification. This notification is produced when user wants to +create new container. Alphabet nodes of the Inner Ring catch notification and +validate container data, signature and token if it is present. + + containerPut: + - name: container + type: ByteArray + - name: signature + type: Signature + - name: publicKey + type: PublicKey + - name: token + type: ByteArray + +containerDelete notification. This notification is produced when container owner +wants to delete container. Alphabet nodes of the Inner Ring catch notification +and validate container ownership, signature and token if it is present. + + containerDelete: + - name: containerID + type: ByteArray + - name: signature + type: Signature + - name: token + type: ByteArray + +setEACL notification. This notification is produced when container owner wants +to update extended ACL of the container. Alphabet nodes of the Inner Ring catch +notification and validate container ownership, signature and token if it is +present. + + setEACL: + - name: eACL + type: ByteArray + - name: signature + type: Signature + - name: publicKey + type: PublicKey + - name: token + type: ByteArray + +StartEstimation notification. This notification is produced when Storage nodes +should exchange estimation values of container sizes among other Storage nodes. + + StartEstimation: + - name: epoch + type: Integer + +StopEstimation notification. This notification is produced when Storage nodes +should calculate average container size based on received estimations and store +it in Container contract. + + StopEstimation: + - name: epoch + type: Integer +*/ package container