From 28dee5e7b787c741578c56d20d775827ede83b2b Mon Sep 17 00:00:00 2001
From: Florian Pellissier <111426680+flopell@users.noreply.github.com>
Date: Tue, 20 Aug 2024 11:32:01 +0200
Subject: [PATCH] docs(indexing): add special notice for `pool_id`

---
 docs/indexing/reserved-attributes.md | 42 +++++++++++++++-------------
 1 file changed, 22 insertions(+), 20 deletions(-)

diff --git a/docs/indexing/reserved-attributes.md b/docs/indexing/reserved-attributes.md
index a65a7ea..8fea91e 100644
--- a/docs/indexing/reserved-attributes.md
+++ b/docs/indexing/reserved-attributes.md
@@ -6,26 +6,6 @@ Certain attribute names are reserved exclusively for specific purposes. Please u
 
 The following attributes names are reserved and must be given using `ProtocolComponent.static_att`. These attributes MUST be immutable. If it can ever change, it should be given as a state attribute (see below) for this component id.
 
-- ### <u>**pool_id**</u>
-
-#### Description
-
-The `pool_id` static attribute is used to specify the identifier of the pool when it differs from the `ProtocolComponent.id`. For example, Balancer pools have a component ID that corresponds to their contract address, and a separate pool ID used for registration on the Balancer Vault contract.
-
-#### Type
-
-This attribute value must be provided as a UTF-8 encoded string in bytes.
-
-#### Example Usage
-
-```rust
-Attribute {
-name: "pool_id".to_string(),
-value: format!("0x{}", hex::encode(pool_registered.pool_id)).as_bytes(),
-change: ChangeType::Creation.into(),
-}
-```
-
 - ### <u>**manual_updates**</u>
 
 #### Description
@@ -48,6 +28,28 @@ change: ChangeType::Creation.into(),
 }
 ```
 
+- ### <u>**pool_id**</u>
+
+#### Description
+
+The `pool_id` static attribute is used to specify the identifier of the pool when it differs from the `ProtocolComponent.id`. For example, Balancer pools have a component ID that corresponds to their contract address, and a separate pool ID used for registration on the Balancer Vault contract.
+
+**Notice**: In most of the cases, using `ProtocolComponent.id` directly is preferred over `pool_id`.
+
+#### Type
+
+This attribute value must be provided as a UTF-8 encoded string in bytes.
+
+#### Example Usage
+
+```rust
+Attribute {
+name: "pool_id".to_string(),
+value: format!("0x{}", hex::encode(pool_registered.pool_id)).as_bytes(),
+change: ChangeType::Creation.into(),
+}
+```
+
 ## State Attributes
 
 The following attributes names are reserved and must be given using `EntityChanges`. Unlike [Static Attributes](#static-attributes), state attributes are used for dynamic attributes and are allowed to change at anytime.