container

package
v0.26.0 Latest Latest
Warning

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

Go to latest
Published: Jan 23, 2026 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

ContainerQuotaSet notification. This notification is produced when container's owner sets (updates) size limitation for storage used for all objects in this container.

ContainerQuotaSet
  - name: ContainerID
	type: Hash256
  - name: LimitValue
	type: Integer
  - name: Hard
	type: Boolean

UserQuotaSet notification. This notification is produced when container's owner sets (updates) size limitation for storage used for all objects in _all_ containers he owns.

UserQuotaSet
  - name: UserID
	type: ByteArray # 25 byte N3 address
  - name: LimitValue
	type: Integer
  - name: Hard
	type: Boolean

AttributeChanged notification. Produced on successful setAttribute or removeAttribute invocations when mentioned attribute is affected.

AttributeChanged
  - name: containerID
    type: Hash256
  - name: attribute
    type: String # Name of attribute

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 AddStructs added in v0.26.0

func AddStructs() bool

AddStructs makes and saves structures for up to 10 existing containers. Returns true if not all stored containers have been structurized. Recall continues the process. Returning false means all containers have been processed.

AddStructs requires Alphabet witness.

AddStructs throws NEP-11 'Transfer' event representing token mint for each handled container.

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 BalanceOf added in v0.26.0

func BalanceOf(owner interop.Hash160) int

BalanceOf returns number of containers owner by given account.

BalanceOf implements NEP-11 method.

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 deprecated

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.

Deprecated: use TokensOf for non-empty and Tokens for empty owner correspondingly.

func Count deprecated

func Count() int

Count method returns the number of registered containers.

Deprecated: use TotalSupply instead.

func Create deprecated 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.

Deprecated: use CreateV2 with instead.

func CreateV2 added in v0.26.0

func CreateV2(cnr Info, invocScript, verifScript, sessionToken []byte) interop.Hash256

CreateV2 creates container with given info in the contract. Created containers are content-addressed: they may be accessed by SHA-256 checksum of their data. On success, CreateV2 throws 'Created' notification event.

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

If '__NEOFS__NAME' and '__NEOFS__ZONE' attributes are set, they are 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'.

If '__NEOFS__METAINFO_CONSISTENCY' attribute is set, meta information about objects from this container can be collected for it.

If cnr contains '__NEOFS__LOCK_UNTIL' attribute, its value must be a valid Unix Timestamp later the current one. On success, referenced container becomes locked for removal until specified time.

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.

CreateV2 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 Decimals added in v0.26.0

func Decimals() int

Decimals returns static zero meaning containers are Non-divisible NFTs.

Decimals implements NEP-11 method.

func Delete deprecated

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 deprecated 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.

Deprecated: use GetInfo instead.

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 GetTakenSpaceByUser added in v0.24.0

func GetTakenSpaceByUser(user []byte) int

GetTakenSpaceByUser returns total load space in all containers user owns. If user have no containers, it returns 0.

func IterateAllReportSummaries added in v0.24.0

func IterateAllReportSummaries() iterator.Iterator

IterateAllReportSummaries method returns iterator over all total container sizes 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 NodeReportSummary structures.

func IterateBillingStats added in v0.25.0

func IterateBillingStats(cid interop.Hash256) iterator.Iterator

IterateBillingStats method returns iterator over container's billing statistics made based on NodeReport.

func IterateReports added in v0.24.0

func IterateReports(cid interop.Hash256) iterator.Iterator

IterateReports method returns iterator over nodes' reports that were claimed for specified epoch and container.

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 deprecated

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.

Deprecated: use OwnerOf instead.

func OwnerOf added in v0.26.0

func OwnerOf(tokenID []byte) interop.Hash160

OwnerOf returns owner of the container identified by tokenID.

If referenced container does not exist, OwnerOf throws cst.NotFoundError exception. If the container has already been removed, OwnerOf throws cst.ErrorDeleted exception.

OwnerOf implements NEP-11 method.

func Properties added in v0.26.0

func Properties(tokenID []byte) map[string]any

Properties returns properties of referenced container. The properties are 'name' and all KV attributes.

The 'name' property is set to 'Name' attribute value if exists. In this case, 'Name' attribute itself is not included. Otherwise, if 'Name' attribute is missing, 'name' is set to Base58-encoded tokenID. Note that container 'name' attribute is always overlapped if any.

If referenced container does not exist, OwnerOf throws cst.NotFoundError exception. If the container has already been removed, OwnerOf throws cst.ErrorDeleted exception.

Properties implements optional NEP-11 method.

func Put deprecated

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 CreateV2 instead.

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 CreateV2 for details.

func PutMeta deprecated

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 CreateV2 instead.

func PutNamed deprecated

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 CreateV2 instead.

func PutNamedOverloaded deprecated

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 CreateV2 instead.

func PutReport added in v0.24.0

func PutReport(cid interop.Hash256, sizeBytes, objsNumber int, pubKey interop.PublicKey)

PutReport method saves container's state report in contract memory. It must be invoked only by Storage nodes that belong to reported container. This method checks witness based on the provided public key of the Storage node. sizeBytes is a total storage that is used by storage node for storing all marshaled objects that belong to the specified container. objsNumber is a total number of container's object storage node have.

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

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.

If the container has '__NEOFS__LOCK_UNTIL' attribute with timestamp that has not passed yet, Remove throws exception containing cst.ErrorLocked.

See CreateV2 for details.

func RemoveAttribute added in v0.26.0

func RemoveAttribute(cID interop.Hash256, name string, validUntil int, invocScript, verifScript, sessionToken []byte)

RemoveAttribute removes container attribute. Not all container attributes can be removed with RemoveAttribute. The supported list of attributes:

  • CORS
  • __NEOFS__LOCK_UNTIL
  • S3_TAGS
  • S3_SETTINGS
  • S3_NOTIFICATIONS

If name is '__NEOFS__LOCK_UNTIL', current time must be later than the currently set one if any.

The validUntil must be Unix Timestamp which has not yet pass.

RemoveAttribute must have Alphabet witness. Invocation and verification scripts must authenticate either container owner or session subject if any. If session token is set, it must be issued by the container owner and have at least one context with referenced container and `REMOVEATTRIBUTE` verb. The sessionToken parameter must be encoded according to NeoFS API binary protocol.

If container is missing, RemoveAttribute throws cst.NotFoundError exception.

func ReplicasNumbers

func ReplicasNumbers(cID interop.Hash256) iterator.Iterator

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

func SetAttribute added in v0.26.0

func SetAttribute(cID interop.Hash256, name, value string, validUntil int, invocScript, verifScript, sessionToken []byte)

SetAttribute sets container attribute. Not all container attributes can be changed with SetAttribute. The supported list of attributes:

  • CORS
  • NEOFS__LOCK_UNTIL
  • S3_TAGS
  • S3_SETTINGS
  • S3_NOTIFICATIONS

CORS attribute gets JSON encoded `[]CORSRule` as value.

If name is '__NEOFS__LOCK_UNTIL', value must a valid Unix Timestamp later the current and already set (if any) ones. On success, referenced container becomes locked for removal until specified time.

If the name is 'S3_TAGS', the value must be a valid JSON map, where the key is the tag name and the value is the tag value. It is an S3 gate-specific attribute. For instance: {"my-tag":"my-value"}.

If the name is 'S3_SETTINGS', the value is not validated by the contract, but must be valid JSON. It is an S3 gate-specific attribute. The structure of it is controlled by the gate itself.

If the name is 'S3_NOTIFICATIONS', the value is not validated by the contract, but must be valid JSON. It is an S3 gate-specific attribute. The structure of it is controlled by the gate itself.

The validUntil must be Unix Timestamp which has not yet pass.

SetAttribute must have Alphabet witness. Invocation and verification scripts must authenticate either container owner or session subject if any. If session token is set, it must be issued by the container owner and have at least one context with referenced container and `SETATTRIBUTE` verb. The sessionToken parameter must be encoded according to NeoFS API binary protocol.

If container is missing, SetAttribute throws cst.NotFoundError exception.

func SetEACL deprecated

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 SetHardContainerQuota added in v0.24.0

func SetHardContainerQuota(cID interop.Hash256, size int)

SetHardContainerQuota sets hard size quota that limits all space used for storing objects in cID (including object replicas). Non-positive size sets no limitation. After exceeding the limit nodes will refuse any further PUTs. Call must be signed by cID's owner. Limit can be changed with a repeated call. See also SetSoftContainerQuota. Panics if cID is incorrect or container does not exist.

func SetHardUserQuota added in v0.24.0

func SetHardUserQuota(user []byte, size int)

SetHardUserQuota sets size quota that limits all space used for storing objects in all containers that belong to user (including object replicas). Non-positive size sets no limitation. After exceeding the limit nodes will refuse any further PUTs. Call must be signed by user. Limit can be changed with a repeated call. See also SetSoftUserQuota. Panics if user is incorrect.

func SetSoftContainerQuota added in v0.24.0

func SetSoftContainerQuota(cID interop.Hash256, size int)

SetSoftContainerQuota sets soft size quota that limits all space used for storing objects in cID (including object replicas). Non-positive size sets no limitation. After exceeding the limit nodes are instructed to warn only, without denial of service. Call must be signed by cID's owner. Limit can be changed with a repeated call. See also SetHardContainerQuota. Panics if cID is incorrect or container does not exist.

func SetSoftUserQuota added in v0.24.0

func SetSoftUserQuota(user []byte, size int)

SetSoftUserQuota sets size quota that limits all space used for storing objects in all containers that belong to user (including object replicas). Non-positive size sets no limitation. After exceeding the limit nodes are instructed to warn only, without denial of service. Call must be signed by user. Limit can be changed with a repeated call. See also SetHardUserQuota. Panics if user is incorrect.

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 Symbol added in v0.26.0

func Symbol() string

Symbol returns static 'FSCNTR'.

Symbol implements NEP-11 method.

func Tokens added in v0.26.0

func Tokens() iterator.Iterator

Tokens returns iterator over IDs of all existing containers.

Tokens implements optional NEP-11 method.

func TokensOf added in v0.26.0

func TokensOf(owner interop.Hash160) iterator.Iterator

TokensOf returns iterator over IDs of all containers owned by given account.

TokensOf implements NEP-11 method.

func TotalSupply added in v0.26.0

func TotalSupply() int

TotalSupply returns total number of existing containers.

TotalSupply implements NEP-11 method.

func Transfer added in v0.26.0

func Transfer(to interop.Hash160, tokenID []byte, data any) bool

Transfer makes to an owner of the container identified by tokenID.

If referenced container does not exist, Transfer throws cst.NotFoundError exception. If the container has already been removed, Transfer throws cst.ErrorDeleted exception.

Transfer implements NEP-11 method.

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 APIVersion added in v0.26.0

type APIVersion struct {
	Major uint32
	Minor uint32
}

APIVersion represents NeoFS API protocol version.

type Attribute added in v0.26.0

type Attribute struct {
	Key   string
	Value string
}

Attribute represents container attribute.

type Container

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

func Get deprecated

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 GetInfo instead.

type EpochBillingStat added in v0.25.0

type EpochBillingStat struct {
	Account interop.Hash160

	LatestContainerSize    int
	LatestEpoch            int
	LastUpdateTime         int
	LatestEpochAverageSize int

	PreviousContainerSize    int
	PreviousEpoch            int
	PreviousEpochAverageSize int
}

EpochBillingStat represents container statistics for a certain epoch.

func GetBillingStatByNode added in v0.25.0

func GetBillingStatByNode(cid interop.Hash256, pubKey interop.PublicKey) EpochBillingStat

GetBillingStatByNode method returns billing statistics based on submitted reports made with PutReport.

If the container doesn't exist, it panics with cst.NotFoundError. If no reports were claimed, it returns zero values.

type ExtendedACL

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

func EACL deprecated

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 Info added in v0.26.0

type Info struct {
	Version       APIVersion
	Owner         interop.Hash160
	Nonce         []byte // 16 byte UUID
	BasicACL      uint32
	Attributes    []Attribute
	StoragePolicy []byte
}

Info represents information about container.

func GetInfo added in v0.26.0

func GetInfo(id interop.Hash256) Info

GetInfo reads container by ID. If the container is missing, GetInfo throws cst.NotFoundError exception.

type NodeReport added in v0.24.0

type NodeReport struct {
	PublicKey       interop.PublicKey
	ContainerSize   int
	NumberOfObjects int
	NumberOfReports int
	LastUpdateEpoch int
}

NodeReport is a report by a certain storage node about its storage engine's volume it uses for a certain container.

func GetReportByAccount added in v0.26.0

func GetReportByAccount(cid interop.Hash256, acc interop.Hash160) NodeReport

GetReportByAccount method returns the latest report, that node with the given account reported for the specified container via PutReport.

If the container doesn't exist, it panics with cst.NotFoundError. If no reports were claimed, it returns zero values.

func GetReportByNode added in v0.24.0

func GetReportByNode(cid interop.Hash256, pubKey interop.PublicKey) NodeReport

GetReportByNode method returns the latest report, that node with pubKey reported for the specified container via PutReport.

If the container doesn't exist, it panics with cst.NotFoundError. If no reports were claimed, it returns zero values.

type NodeReportSummary added in v0.24.0

type NodeReportSummary struct {
	ContainerSize   int
	NumberOfObjects int
}

NodeReportSummary is the summary of all NodeReport claimed by all storage nodes.

func GetNodeReportSummary added in v0.24.0

func GetNodeReportSummary(cid interop.Hash256) NodeReportSummary

GetNodeReportSummary method returns a sum of object count and occupied volume as reported by storage nodes provided via PutReport.

If the container doesn't exist, it panics with cst.NotFoundError. If no reports were claimed, it returns zero values.

type Quota added in v0.24.0

type Quota struct {
	SoftLimit int
	HardLimit int
}

Quota describes size limitation for a container or for a user as a sum of all objects in all his containers.

func ContainerQuota added in v0.24.0

func ContainerQuota(cID interop.Hash256) Quota

ContainerQuota returns container size quota set by cID's owner. If no limitation has been set, returns empty values (both limitations are set to 0). Non-positive limitation must be treated as no limits. Panics if cID is incorrect or container does not exist.

func UserQuota added in v0.24.0

func UserQuota(user []byte) Quota

UserQuota returns user size quota for every container he owns. If no limitation has been set, returns empty values (both limitations are set to 0). Non-positive limitation must be treated as no limits. Panics if user is incorrect.

type StorageNode

type StorageNode struct {
	Info []byte
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL