From af909ec3ebc50b1208694dc0917c74b5d4dd103d Mon Sep 17 00:00:00 2001
From: Stanislav Bogatyrev <stanislav@nspcc.ru>
Date: Tue, 13 Oct 2020 19:37:14 +0300
Subject: [PATCH] Add well-known attributes for storage nodes

Adding the list of currently well-known node attributes. More to come later.

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>
---
 netmap/types.proto | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/netmap/types.proto b/netmap/types.proto
index e7f0ae7..dd5bfe3 100644
--- a/netmap/types.proto
+++ b/netmap/types.proto
@@ -121,7 +121,42 @@ message NodeInfo {
   // Ways to connect to a node
   string address = 2;
 
-  // Attributes of the NeoFS node.
+  // Administrator-defined Attributes of the NeoFS Storage Node.
+  //
+  // 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.
   message Attribute {
     // Key of the node attribute.
     string key = 1;
@@ -129,8 +164,8 @@ message NodeInfo {
     // Value of the node attribute.
     string value = 2;
 
-    // Parent keys, if any
-    // Example: For City it can be Region or Country
+    // Parent keys, if any. For example for `City` it could be `Region` and
+    // `Country`.
     repeated string parents = 3;
   }
   // Carries list of the NeoFS node attributes in a string key-value format.