Managing investor's extra information

app/model/db/__init__.py

@@ -97,7 +97,12 @@
 from .notification import Notification, NotificationType
 from .scheduled_events import ScheduledEvents, ScheduledEventType
 from .token import Token, TokenAttrUpdate, TokenCache, TokenType, TokenVersion
-from .token_holders import TokenHolder, TokenHolderBatchStatus, TokenHoldersList
+from .token_holder_extra_info import TokenHolderExtraInfo
+from .token_holders_collection import (
+    TokenHolder,
+    TokenHolderBatchStatus,
+    TokenHoldersList,
+)
 from .token_update_operation_log import (
     TokenUpdateOperationCategory,
     TokenUpdateOperationLog,

app/model/db/token_holder_extra_info.py

@@ -0,0 +1,77 @@
+"""
+Copyright BOOSTRY Co., Ltd.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+
+You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+"""
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class TokenHolderExtraInfo(Base):
+    """Additional attributes of token holders"""
+
+    __tablename__ = "token_holder_extra_info"
+
+    # token address
+    token_address: Mapped[str] = mapped_column(String(42), primary_key=True)
+    # account address
+    account_address: Mapped[str] = mapped_column(String(42), primary_key=True)
+    # the type of external-id-1
+    external_id_1_type: Mapped[str | None] = mapped_column(String(50))
+    # external-id-1
+    external_id_1: Mapped[str | None] = mapped_column(String(50))
+    # the type of external-id-2
+    external_id_2_type: Mapped[str | None] = mapped_column(String(50))
+    # external-id-2
+    external_id_2: Mapped[str | None] = mapped_column(String(50))
+    # the type of external-id-3
+    external_id_3_type: Mapped[str | None] = mapped_column(String(50))
+    # external-id-3
+    external_id_3: Mapped[str | None] = mapped_column(String(50))
+
+    def json(self):
+        return {
+            "token_address": self.token_address,
+            "account_address": self.account_address,
+            "external_id_1_type": self.external_id_1_type,
+            "external_id_1": self.external_id_1,
+            "external_id_2_type": self.external_id_2_type,
+            "external_id_2": self.external_id_2,
+            "external_id_3_type": self.external_id_3_type,
+            "external_id_3": self.external_id_3,
+        }
+
+    default_extra_info = {
+        "external_id_1_type": None,
+        "external_id_1": None,
+        "external_id_2_type": None,
+        "external_id_2": None,
+        "external_id_3_type": None,
+        "external_id_3": None,
+    }
+
+    def extra_info(self):
+        return {
+            "external_id_1_type": self.external_id_1_type,
+            "external_id_1": self.external_id_1,
+            "external_id_2_type": self.external_id_2_type,
+            "external_id_2": self.external_id_2,
+            "external_id_3_type": self.external_id_3_type,
+            "external_id_3": self.external_id_3,
+        }

app/model/db/token_holders.py → app/model/db/token_holders_collection.py

@@ -25,8 +25,16 @@
 from .base import Base
 
 
+class TokenHolderBatchStatus(StrEnum):
+    """The creation status of token holder snapshots"""
+
+    PENDING = "pending"
+    DONE = "done"
+    FAILED = "failed"
+
+
 class TokenHoldersList(Base):
-    """Token Holder List"""
+    """A list of token holder snapshots"""
 
     __tablename__ = "token_holders_list"
 
@@ -38,17 +46,11 @@ class TokenHoldersList(Base):
     # List id (UUID)
     list_id: Mapped[str | None] = mapped_column(String(36), index=False)
     # batch processing status
-    batch_status: Mapped[str | None] = mapped_column(String(256))
-
-
-class TokenHolderBatchStatus(StrEnum):
-    PENDING = "pending"
-    DONE = "done"
-    FAILED = "failed"
+    batch_status: Mapped[TokenHolderBatchStatus | None] = mapped_column(String(256))
 
 
 class TokenHolder(Base):
-    """Token Holder"""
+    """A snapshot of token holders at a specific block number"""
 
     __tablename__ = "token_holder"
 

app/model/schema/__init__.py

@@ -87,7 +87,12 @@
     RetrieveFreezeLogResponse,
     UpdateFreezeLogRequest,
 )
-from .holder import HolderCountResponse, HolderResponse, HoldersResponse
+from .holder import (
+    HolderCountResponse,
+    HolderResponse,
+    HoldersResponse,
+    RegisterHolderExtraInfoRequest,
+)
 from .index import BlockNumberResponse, E2EEResponse
 from .issue_redeem import IssueRedeemEvent, IssueRedeemHistoryResponse
 from .ledger import (
@@ -127,7 +132,10 @@
     ScheduledEventIdResponse,
     ScheduledEventResponse,
 )
-from .sealed_tx import SealedTxRegisterPersonalInfoRequest
+from .sealed_tx import (
+    SealedTxRegisterHolderExtraInfoRequest,
+    SealedTxRegisterPersonalInfoRequest,
+)
 from .settlement import (
     AbortDVPDeliveryRequest,
     CancelDVPDeliveryRequest,

app/model/schema/holder.py

@@ -20,21 +20,70 @@
 from datetime import datetime
 from typing import Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from app.model.schema.base import ResultSet
 
 from .personal_info import PersonalInfo
 
 
+############################
+# COMMON
+############################
+class HolderExtraInfo(BaseModel):
+    external_id_1_type: Optional[str] = Field(
+        ..., description="The type of external-id-1"
+    )
+    external_id_1: Optional[str] = Field(..., description="external-id-1")
+    external_id_2_type: Optional[str] = Field(
+        ..., description="The type of external-id-2"
+    )
+    external_id_2: Optional[str] = Field(..., description="external-id-2")
+    external_id_3_type: Optional[str] = Field(
+        ..., description="The type of external-id-3"
+    )
+    external_id_3: Optional[str] = Field(..., description="external-id-3")
+
+
+############################
+# REQUEST
+############################
+class RegisterHolderExtraInfoRequest(BaseModel):
+    """Schema for holder's extra information registration (REQUEST)"""
+
+    external_id_1_type: Optional[str] = Field(
+        None, description="The type of external-id-1", max_length=50
+    )
+    external_id_1: Optional[str] = Field(
+        None, description="external-id-1", max_length=50
+    )
+    external_id_2_type: Optional[str] = Field(
+        None, description="The type of external-id-2", max_length=50
+    )
+    external_id_2: Optional[str] = Field(
+        None, description="external-id-2", max_length=50
+    )
+    external_id_3_type: Optional[str] = Field(
+        None, description="The type of external-id-3", max_length=50
+    )
+    external_id_3: Optional[str] = Field(
+        None, description="external-id-3", max_length=50
+    )
+
+
 ############################
 # RESPONSE
 ############################
 class HolderResponse(BaseModel):
     """Holder schema (Response)"""
 
-    account_address: str
-    personal_information: PersonalInfo
+    account_address: str = Field(..., description="Holder's account address")
+    personal_information: PersonalInfo = Field(
+        ..., description="Holder's personal information"
+    )
+    holder_extra_info: HolderExtraInfo = Field(
+        ..., description="Holder's extra information"
+    )
     balance: int
     exchange_balance: int
     exchange_commitment: int

app/model/schema/sealed_tx.py

@@ -17,14 +17,16 @@
 SPDX-License-Identifier: Apache-2.0
 """
 
-from pydantic import BaseModel
+from typing import Optional
+
+from pydantic import BaseModel, Field
 
 from app.model import EthereumAddress
 from app.model.schema.personal_info import PersonalInfoInput
 
 
 ############################
-# REQUEST
+# COMMON
 ############################
 class SealedTxPersonalInfoInput(PersonalInfoInput):
     """Personal Information Input schema for sealed tx"""
@@ -36,7 +38,31 @@ class SealedTxPersonalInfoInput(PersonalInfoInput):
 # REQUEST
 ############################
 class SealedTxRegisterPersonalInfoRequest(BaseModel):
-    """Schema for personal information registration using sealed tx(REQUEST)"""
+    """Schema for personal information registration using sealed tx (REQUEST)"""
 
     link_address: EthereumAddress
     personal_information: SealedTxPersonalInfoInput
+
+
+class SealedTxRegisterHolderExtraInfoRequest(BaseModel):
+    """Schema for holder's extra information registration using sealed tx (REQUEST)"""
+
+    token_address: EthereumAddress
+    external_id_1_type: Optional[str] = Field(
+        None, description="The type of external-id-1", max_length=50
+    )
+    external_id_1: Optional[str] = Field(
+        None, description="external-id-1", max_length=50
+    )
+    external_id_2_type: Optional[str] = Field(
+        None, description="The type of external-id-2", max_length=50
+    )
+    external_id_2: Optional[str] = Field(
+        None, description="external-id-2", max_length=50
+    )
+    external_id_3_type: Optional[str] = Field(
+        None, description="The type of external-id-3", max_length=50
+    )
+    external_id_3: Optional[str] = Field(
+        None, description="external-id-3", max_length=50
+    )