From e8afd6e5f5c621b2ddf73a50da7223c57dd1a7a6 Mon Sep 17 00:00:00 2001
From: Aleksey Savchuk <a.savchuk@yadro.com>
Date: Thu, 5 Sep 2024 14:21:02 +0300
Subject: [PATCH] [#50] netmap: Clarify MaxObjectSize parameter implication on
 object size

Signed-off-by: Aleksey Savchuk <a.savchuk@yadro.com>
---
 netmap/types.proto | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/netmap/types.proto b/netmap/types.proto
index 99724c2..dfaac13 100644
--- a/netmap/types.proto
+++ b/netmap/types.proto
@@ -289,6 +289,37 @@ message NetworkConfig {
   // - **MaxObjectSize** \
   //   Maximum size of physically stored NeoFS object measured in bytes.
   //   Value: little-endian integer. Default: 0.
+  //
+  //   This value refers to the maximum size of a **physically** stored object
+  //   in NeoFS. However, from a user's perspective, the **logical** size of a
+  //   stored object can be significantly larger. The relationship between the
+  //   physical and logical object sizes is governed by the following formula
+  //
+  //   ```math
+  //   \mathrm{Stored\ Object\ Size} \le
+  //   \frac{
+  //     \left(\mathrm{Max\ Object\ Size}\right)^2
+  //   }{
+  //     \mathrm{Object\ ID\ Size}
+  //   }
+  //   ```
+  //
+  //   This arises from the fact that a tombstone, also being an object, stores
+  //   the IDs of inhumed objects and cannot be divided into smaller objects,
+  //   thus having an upper limit for its size.
+  //
+  //   For example, if:
+  //   * Max Object Size Size = 64 MiB;
+  //   * Object ID Size = 32 B;
+  //
+  //   then:
+  //   ```math
+  //     \mathrm{Stored\ Object\ Size} \le
+  //     \frac{\left(64\ \mathrm{MiB}\right)^2}{32\ \mathrm{B}} =
+  //     \frac{2^{52}}{2^5}\ \mathrm{B} =
+  //     2^{47}\ \mathrm{B} =
+  //     128\ \mathrm{TiB}
+  //   ```
   // - **WithdrawFee** \
   //   Fee paid for withdrawal of funds paid by the account owner.
   //   Value: little-endian integer. Default: 0.