container

Documentation

Overview

Container contract is a contract deployed in FrostFS sidechain.

Container contract stores and manages containers, extended ACLs and container size estimations. Contract does not perform sanity or signature checks of 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

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

Contract storage scheme

|   Key                                               | Value      |           Description            |
|-----------------------------------------------------------------------------------------------------|
| `netmapScriptHash`                                  | Hash160    | netmap contract hash             |
| `balanceScriptHash`                                 | Hash160    | balance contract hash            |
| `identityScriptHash`                                | Hash160    | frostfsID contract hash          |
| `nnsContractKey`                                    | Hash160    | nns contract hash                |
| `nnsRoot`                                           | string     | default value for domain zone    |
| `cnr` + epoch + containerID + publicKeyHash[:10]    | ByteArray  | estimated container size         |
| `est` + containerID + publicKeyHash                 | ByteArray  | serialized epochs array          |
| `o` + ownerID + containerID                         | ByteArray  | container ID                     |
| `x` + containerID                                   | ByteArray  | serialized container struct      |
| `nnsHasAlias` + containerID                         | string     | domain name                      |

Index

• Constants
• func ContainersOf(owner []byte) iterator.Iterator
• func Count() int
• func Delete(containerID interop.Hash256, signature interop.Signature, ...)
• func GetContainerSize(id []byte) containerSizes
• func IterateContainerSizes(epoch int) iterator.Iterator
• func List(owner []byte) [][]byte
• func ListContainerSizes(epoch int) [][]byte
• func NewEpoch(epochNum int)
• func OnNEP11Payment(a interop.Hash160, b int, c []byte, d any)
• func Owner(containerID []byte) []byte
• func Put(container []byte, signature interop.Signature, publicKey interop.PublicKey, ...)
• func PutContainerSize(epoch int, cid []byte, usedSize int, pubKey interop.PublicKey)
• func PutNamed(container []byte, signature interop.Signature, publicKey interop.PublicKey, ...)
• func SetAdmin(admin interop.Hash160)
• func SetEACL(eACL []byte, signature interop.Signature, publicKey interop.PublicKey, ...)
• func StartContainerEstimation(epoch int)
• func StopContainerEstimation(epoch int)
• func Update(script []byte, manifest []byte, data any)
• func Version() int
• type Container
  • func Get(containerID []byte) Container
• type DelInfo
  • func DeletionInfo(containerID []byte) DelInfo
• type ExtendedACL
  • func EACL(containerID []byte) ExtendedACL

Constants

const (

	// RegistrationFeeKey is a key in netmap config which contains fee for container registration.
	RegistrationFeeKey = "ContainerFee"
	// AliasFeeKey is a key in netmap config which contains fee for nice-name registration.
	AliasFeeKey = "ContainerAliasFee"

	// CleanupDelta contains the number of the last epochs for which container estimations are present.
	CleanupDelta = 3
	// TotalCleanupDelta contains the number of the epochs after which estimation
	// will be removed by epoch tick cleanup if any of the nodes hasn't updated
	// container size and/or container has been removed. It must be greater than CleanupDelta.
	TotalCleanupDelta = CleanupDelta + 1

	// NotFoundError is returned if container is missing.
	NotFoundError = "container does not exist"
)

Functions

func ContainersOf

func ContainersOf(owner []byte) iterator.Iterator

ContainersOf iterates over all container IDs owned by the specified owner. If owner is nil, it iterates over all containers.

func Count

func Count() int

Count method returns the number of registered containers.

func Delete

func Delete(containerID interop.Hash256, signature interop.Signature, publicKey interop.PublicKey, token []byte)

Delete method removes a container from the contract storage if it has been invoked by Alphabet nodes of the Inner Ring.

Signature is a RFC6979 signature of the container ID. Token is optional and should be a stable marshaled SessionToken structure from API.

If the container doesn't exist, it panics with NotFoundError.

func GetContainerSize

func GetContainerSize(id []byte) containerSizes

GetContainerSize method returns the container ID and a slice of container estimations. Container estimation includes the public key of the Storage Node that registered estimation and value of estimation.

Use the ID obtained from ListContainerSizes method. Estimations are removed from contract storage every epoch, see NewEpoch method; therefore, this method can return different results during different epochs.

func IterateContainerSizes

func IterateContainerSizes(epoch int) iterator.Iterator

IterateContainerSizes method returns iterator over container size estimations that have been registered for the specified epoch.

func List

func List(owner []byte) [][]byte

List method returns a list of all container IDs owned by the specified owner.

func ListContainerSizes

func ListContainerSizes(epoch int) [][]byte

ListContainerSizes method returns the IDs of container size estimations that have been registered for the specified epoch.

func NewEpoch

func NewEpoch(epochNum int)

NewEpoch method removes all container size estimations from epoch older than epochNum + 3. It can be invoked only by NewEpoch method of the Netmap contract.

func OnNEP11Payment

func OnNEP11Payment(a interop.Hash160, b int, c []byte, d any)

OnNEP11Payment is needed for registration with contract as the owner to work.

func Owner

func Owner(containerID []byte) []byte

Owner method returns a 25 byte Owner ID of the container.

If the container doesn't exist, it panics with NotFoundError.

func Put

func Put(container []byte, signature interop.Signature, publicKey interop.PublicKey, token []byte)

Put method creates a new container if it has been invoked by Alphabet nodes of the Inner Ring.

Container should be a stable marshaled Container structure from API. Signature is a RFC6979 signature of the Container. PublicKey contains the public key of the signer. Token is optional and should be a stable marshaled SessionToken structure from API.

func PutContainerSize

func PutContainerSize(epoch int, cid []byte, usedSize int, pubKey interop.PublicKey)

PutContainerSize method saves container size estimation in contract memory. It can be invoked only by Storage nodes from the network map. This method checks witness based on the provided public key of the Storage node.

If the container doesn't exist, it panics with NotFoundError.

func PutNamed

func PutNamed(container []byte, signature interop.Signature,
	publicKey interop.PublicKey, token []byte,
	name, zone string,
)

PutNamed is similar to put but also sets a TXT record in nns contract. Note that zone must exist.

func SetAdmin

func SetAdmin(admin interop.Hash160)

SetAdmin sets admin for root container domain.

func SetEACL

func SetEACL(eACL []byte, signature interop.Signature, publicKey interop.PublicKey, token []byte)

SetEACL method sets a new extended ACL table related to the contract if it was invoked by Alphabet nodes of the Inner Ring.

EACL should be a stable marshaled EACLTable structure from API. Signature is a RFC6979 signature of the Container. PublicKey contains the public key of the signer. Token is optional and should be a stable marshaled SessionToken structure from API.

If the container doesn't exist, it panics with NotFoundError.

func StartContainerEstimation

func StartContainerEstimation(epoch int)

StartContainerEstimation method produces StartEstimation notification. It can be invoked only by Alphabet nodes of the Inner Ring.

func StopContainerEstimation

func StopContainerEstimation(epoch int)

StopContainerEstimation method produces StopEstimation notification. It can be invoked only by Alphabet nodes of the Inner Ring.

func Update

func Update(script []byte, manifest []byte, data any)

Update method updates contract source code and manifest. It can be invoked by committee only.

func Version

func Version() int

Version returns the version of the contract.

Types

type Container

type Container struct {
	// contains filtered or unexported fields
}

func Get

func Get(containerID []byte) Container

Get method returns a structure that contains a stable marshaled Container structure, the signature, the public key of the container creator and a stable marshaled SessionToken structure if it was provided.

If the container doesn't exist, it panics with NotFoundError.

type DelInfo

type DelInfo struct {
	Owner []byte
	Epoch int
}

func DeletionInfo

func DeletionInfo(containerID []byte) DelInfo

DeletionInfo method returns container deletion info. If the container had never existed, NotFoundError is throwed. It can be used to check whether non-existing container was indeed deleted or does not yet exist at some height.

type ExtendedACL

type ExtendedACL struct {
	// contains filtered or unexported fields
}

func EACL

func EACL(containerID []byte) ExtendedACL

EACL method returns a structure that contains a stable marshaled EACLTable structure, the signature, the public key of the extended ACL setter and a stable marshaled SessionToken structure if it was provided.

If the container doesn't exist, it panics with NotFoundError.