container

package
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 10, 2025 License: GPL-3.0, Apache-2.0 Imports: 14 Imported by: 2

Documentation

Overview

Package container implements Container contract which is deployed to FS chain.

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

containerPut notification. This notification is produced when a user wants to create a new container. Alphabet nodes of the Inner Ring catch the notification and validate container data, signature and token if 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 a container owner wants to delete a container. Alphabet nodes of the Inner Ring catch the notification and validate container ownership, signature and token if present. 

containerDelete:
  - name: containerID
    type: ByteArray
  - name: signature
    type: Signature
  - name: token
    type: ByteArray

nodesUpdate notification. This notification is produced when a container roster is changed. Triggered only by the Alphabet at the beginning of epoch. 

name: NodesUpdate
  - name: ContainerID
    type: hash256

setEACL notification. This notification is produced when a container owner wants to update an extended ACL of a container. Alphabet nodes of the Inner Ring catch the notification and validate container ownership, signature and token if 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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddNextEpochNodes 

func AddNextEpochNodes(cID interop.Hash256, placementVector uint8, publicKeys []interop.PublicKey)

AddNextEpochNodes accumulates passed nodes as container members for the next epoch to be committed using CommitContainerListUpdate. Nodes must be grouped by selector index from placement policy (SELECT clauses). Results of the call operation can be received via Nodes. This method must be called only when a container list is changed, otherwise nothing should be done. Call must be signed by the Alphabet nodes.

func Alias 

func Alias(cid []byte) string

Alias method returns a string with an alias of the container if it's set (Null otherwise).

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

func CommitContainerListUpdate 

func CommitContainerListUpdate(cID interop.Hash256, replicas []uint8)

CommitContainerListUpdate commits container list changes made by AddNextEpochNodes calls in advance. Replicas must correspond to ordered placement policy (REP clauses). If no AddNextEpochNodes have been made, it clears container list. Makes "ContainerUpdate" notification with container ID after successful list change. Call must be signed by the Alphabet nodes.

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 Create added in v0.22.0 

func Create(cnr []byte, invocScript, verifScript, sessionToken []byte, name, zone string, metaOnChain bool)

Create saves container descriptor serialized according to the NeoFS API binary protocol. Created containers are content-addressed: they may be accessed by SHA-256 checksum of their data. On success, Create throws 'Created' notification event.

Created containers are disposable: if they are deleted, they cannot be created again. Create throws cst.ErrorDeleted exception on recreation attempts.

Domain name is optional. If specified, it is used to register 'name.zone' domain for given container. Domain zone is optional: it defaults to the 6th contract deployment parameter which itself defaults to 'container'.

Meta-on-chain boolean flag specifies whether meta information about objects from this container can be collected for it.

The operation is paid. Container owner pays per-container fee (global chain configuration) to each committee member. If domain registration is requested, additional alias fee (also a configuration) is added to each payment.

Create must have chain's committee multi-signature witness. Invocation script, verification script and session token parameters are owner credentials. They are transmitted in notary transactions carrying original users' requests. IR verifies requests and approves them via multi-signature. Once creation is approved, container is persisted and becomes accessible. Credentials are disposable and do not persist in the chain.

func Delete 

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

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

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. Deprecated: use Remove instead.

func GetContainerData added in v0.22.0 

func GetContainerData(id []byte) []byte

GetContainerData returns binary of the container it was created with by ID.

If the container is missing, GetContainerData throws cst.NotFoundError exception.

func GetEACLData added in v0.22.0 

func GetEACLData(id []byte) []byte

GetEACLData returns binary of container eACL it was put with by the container ID.

If the container is missing, GetEACLData throws cst.NotFoundError exception.

func IterateAllContainerSizes 

func IterateAllContainerSizes(epoch int) iterator.Iterator

IterateAllContainerSizes method returns iterator over all container size estimations that have been registered for the specified epoch. Items returned from this iterator are key-value pairs with keys having container ID as a prefix and values being Estimation structures.

func IterateContainerSizes 

func IterateContainerSizes(epoch int, cid interop.Hash256) iterator.Iterator

IterateContainerSizes method returns iterator over specific container size estimations that have been registered for the specified epoch. The iterator items are Estimation structures.

func List 

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

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

func ListContainerSizes deprecated 

func ListContainerSizes(epoch int) [][]byte

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

Deprecated: please use IterateAllContainerSizes API, this one is not convenient to use and limited in the number of items it can return. It will be removed in future versions.

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 Nodes 

func Nodes(cID interop.Hash256, placementVector uint8) iterator.Iterator

Nodes returns iterator over members of the container. The list is handled by the Alphabet nodes and must be updated via AddNextEpochNodes and CommitContainerListUpdate calls.

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. Otherwise, it produces containerPut notification.

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. Deprecated: use Create instead.

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 PutEACL added in v0.22.0 

func PutEACL(eACL []byte, invocScript, verifScript, sessionToken []byte)

PutEACL puts given eACL serialized according to the NeoFS API binary protocol for the container it is referenced to. Operation must be allowed in the container's basic ACL. If container does not exist, PutEACL throws cst.NotFoundError exception. On success, PutEACL throws 'EACLChanged' notification event.

See Create for details.

func PutMeta 

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

PutMeta is the same as Put and PutNamed (and exposed as put from the contract via overload), but allows named containers and container's meta-information be handled and notified using the chain. If name and zone are non-empty strings, it behaves the same as PutNamed; empty strings make a regular Put call. Deprecated: use Create instead.

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. DEPRECATED: use Create instead.

func PutNamedOverloaded 

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

PutNamedOverloaded is the same as Put (and exposed as put from the contract via overload), but allows named container creation via NNS contract. Deprecated: use Create instead.

func Remove added in v0.22.0 

func Remove(id []byte, invocScript, verifScript, sessionToken []byte)

Remove removes all data for the referenced container. Remove is no-op if container does not exist. On success, Remove throws 'Removed' notification event.

See Create for details.

func ReplicasNumbers 

func ReplicasNumbers(cID interop.Hash256) iterator.Iterator

ReplicasNumbers returns iterator over saved by CommitContainerListUpdate container's replicas from placement policy.

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. Otherwise, it produces setEACL notification.

EACL should be a stable marshaled EACLTable structure from API. Protocol version and container reference must be set in 'version' and 'container_id' fields respectively. 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. Deprecated: use PutEACL instead.

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 SubmitObjectPut 

func SubmitObjectPut(metaInformation []byte, sigs [][]interop.Signature)

SubmitObjectPut registers successful object PUT operation and notifies about it. metaInformation must be signed by container nodes according to container's placement, see VerifyPlacementSignatures. metaInformation must contain information about an object placed to a container that was created using Put (PutMeta) with enabled meta-on-chain option.

func Update 

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

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

func VerifyPlacementSignatures 

func VerifyPlacementSignatures(cid interop.Hash256, msg []byte, sigs [][]interop.Signature) bool

VerifyPlacementSignatures verifies that message has been signed by container members according to container's placement policy: there should be at least REP number of signatures for every placement vector. sigs must be container's number of SELECTs length.

func Version 

func Version() int

Version returns the version of the contract.

Types

type Container 

type Container struct {
	Value []byte
	Sig   interop.Signature
	Pub   interop.PublicKey
	Token []byte
}

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. Deprecated: use GetContainerData instead.

type ContainerSizes 

type ContainerSizes struct {
	CID         []byte
	Estimations []Estimation
}

func GetContainerSize deprecated 

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.

Deprecated: please use IterateContainerSizes API, this one is not convenient to use and limited in the number of items it can return. It will be removed in future versions.

type Estimation 

type Estimation struct {
	From interop.PublicKey
	Size int
}

Estimation contains the public key of the estimator (storage node) and the size this estimator has for the container.

type ExtendedACL 

type ExtendedACL struct {
	Value []byte
	Sig   interop.Signature
	Pub   interop.PublicKey
	Token []byte
}

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. Deprecated: use GetEACLData instead.

type StorageNode 

type StorageNode struct {
	Info []byte
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.