# Protocol Documentation ## Table of Contents - [netmap/service.proto](#netmap/service.proto) - Services - [NetmapService](#neo.fs.v2.netmap.NetmapService) - Messages - [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) - [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) - [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) - [LocalNodeInfoResponse.Body](#neo.fs.v2.netmap.LocalNodeInfoResponse.Body) - [netmap/types.proto](#netmap/types.proto) - Messages - [Filter](#neo.fs.v2.netmap.Filter) - [NodeInfo](#neo.fs.v2.netmap.NodeInfo) - [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) - [PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) - [Replica](#neo.fs.v2.netmap.Replica) - [Selector](#neo.fs.v2.netmap.Selector) - [Scalar Value Types](#scalar-value-types)

Top

## netmap/service.proto ### Service "neo.fs.v2.netmap.NetmapService" `NetmapService` provides methods to work with `Network Map` and information required to build it. The resulting `Network Map` is stored in sidechain `Netmap` smart contract, while related information can be obtained from other NeoFS nodes. ``` rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse); ``` #### Method LocalNodeInfo Get NodeInfo structure from the particular node directly. Node information can be taken from `Netmap` smart contract, but in some cases the one may want to get recent information directly, or to talk to the node not yet present in `Network Map` to find out what API version can be used for further communication. Can also be used to check if node is up and running. | Name | Input | Output | | ---- | ----- | ------ | | LocalNodeInfo | [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) | [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) | ### Message LocalNodeInfoRequest Get NodeInfo structure from the particular node directly | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | body | [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) | | Body of the LocalNodeInfo request message | | meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | | verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | ### Message LocalNodeInfoRequest.Body LocalNodeInfo request body is empty. ### Message LocalNodeInfoResponse Local Node Info, including API Version in use | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | body | [LocalNodeInfoResponse.Body](#neo.fs.v2.netmap.LocalNodeInfoResponse.Body) | | Body of the balance response message. | | meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect response execution. | | verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | ### Message LocalNodeInfoResponse.Body Local Node Info, including API Version in use. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest NeoFS API version in use | | node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo structure with recent information from node itself |

Top

## netmap/types.proto ### Message Filter Filter will return the subset of nodes from `NetworkMap` or another filter's results, that will satisfy filter's conditions. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | name | [string](#string) | | Name of the filter or a reference to the named filter. '*' means application to the whole unfiltered NetworkMap. At top level it's used as a filter name. At lower levels it's considered to be a reference to another named filter | | key | [string](#string) | | Key to filter | | op | [Operation](#neo.fs.v2.netmap.Operation) | | Filtering operation | | value | [string](#string) | | Value to match | | filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of inner filters. Top level operation will be applied to the whole list. | ### Message NodeInfo NeoFS node description | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | public_key | [bytes](#bytes) | | Public key of the NeoFS node in a binary format. | | address | [string](#string) | | Ways to connect to a node | | attributes | [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) | repeated | Carries list of the NeoFS node attributes in a key-value form. Key name must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo structures with duplicated attribute names or attributes with empty values will be considered invalid. | | state | [NodeInfo.State](#neo.fs.v2.netmap.NodeInfo.State) | | Carries state of the NeoFS node. | ### Message NodeInfo.Attribute Administrator-defined Attributes of the NeoFS Storage Node. `Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8 string. Value can't be empty. Node's attributes are mostly used during Storage Policy evaluation to calculate object's placement and find a set of nodes satisfying policy requirements. There are some "well-known" node attributes common to all the Storage Nodes in the network and used implicitly with default values if not explicitly set: * Capacity \ Total available disk space in Gigabytes. * Price \ Price in GAS tokens for storing one GB of data during one Epoch. In node attributes it's a string presenting floating point number with comma or point delimiter for decimal part. In the Network Map it will be saved as 64-bit unsigned integer representing number of minimal token fractions. * Subnet \ String ID of Node's storage subnet. There can be only one subnet served by the Storage Node. * Locode \ Node's geographic location in [UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html) format approximated to the nearest point defined in standard. * Country \ Country code in [ISO 3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. Calculated automatically from `Locode` attribute * Region \ Country's administative subdivision where node is located. Calculated automatically from `Locode` attribute based on `SubDiv` field. Presented in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. * City \ City, town, village or rural area name where node is located written without diacritics . Calculated automatically from `Locode` attribute. For detailed description of each well-known attribute please see the corresponding section in NeoFS Technical specification. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | key | [string](#string) | | Key of the node attribute. | | value | [string](#string) | | Value of the node attribute. | | parents | [string](#string) | repeated | Parent keys, if any. For example for `City` it could be `Region` and `Country`. | ### Message PlacementPolicy Set of rules to select a subset of nodes from `NetworkMap` able to store container's objects. The format is simple enough to transpile from different storage policy definition languages. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | replicas | [Replica](#neo.fs.v2.netmap.Replica) | repeated | Rules to set number of object replicas and place each one into a named bucket | | container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container's nodes subset | | selectors | [Selector](#neo.fs.v2.netmap.Selector) | repeated | Set of Selectors to form the container's nodes subset | | filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of named filters to reference in selectors | ### Message Replica Number of object replicas in a set of nodes from the defined selector. If no selector set the root bucket containing all possible nodes will be used by default. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | count | [uint32](#uint32) | | How many object replicas to put | | selector | [string](#string) | | Named selector bucket to put replicas | ### Message Selector Selector chooses a number of nodes from the bucket taking the nearest nodes to the provided `ContainerID` by hash distance. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | name | [string](#string) | | Selector name to reference in object placement section | | count | [uint32](#uint32) | | How many nodes to select from the bucket | | clause | [Clause](#neo.fs.v2.netmap.Clause) | | Selector modifier showing how to form a bucket | | attribute | [string](#string) | | Attribute bucket to select from | | filter | [string](#string) | | Filter reference to select from | ### Clause Selector modifier shows how the node set will be formed. By default selector just groups nodes into a bucket by attribute, selecting nodes only by their hash distance. | Name | Number | Description | | ---- | ------ | ----------- | | CLAUSE_UNSPECIFIED | 0 | No modifier defined. Will select nodes from bucket randomly. | | SAME | 1 | SAME will select only nodes having the same value of bucket attribute | | DISTINCT | 2 | DISTINCT will select nodes having different values of bucket attribute | ### NodeInfo.State Represents the enumeration of various states of the NeoFS node. | Name | Number | Description | | ---- | ------ | ----------- | | UNSPECIFIED | 0 | Unknown state. | | ONLINE | 1 | Active state in the network. | | OFFLINE | 2 | Network unavailable state. | ### Operation Operations on filters | Name | Number | Description | | ---- | ------ | ----------- | | OPERATION_UNSPECIFIED | 0 | No Operation defined | | EQ | 1 | Equal | | NE | 2 | Not Equal | | GT | 3 | Greater then | | GE | 4 | Greater or equal | | LT | 5 | Less then | | LE | 6 | Less or equal | | OR | 7 | Logical OR | | AND | 8 | Logical AND | ## Scalar Value Types | .proto Type | Notes | C++ Type | Java Type | Python Type | | ----------- | ----- | -------- | --------- | ----------- | | double | | double | double | float | | float | | float | float | float | | int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | | int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | | uint32 | Uses variable-length encoding. | uint32 | int | int/long | | uint64 | Uses variable-length encoding. | uint64 | long | int/long | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | | sfixed32 | Always four bytes. | int32 | int | int | | sfixed64 | Always eight bytes. | int64 | long | int/long | | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |