Add database model documentation

Author: Uxio0

safe_transaction_service/account_abstraction/models.py

@@ -113,6 +113,8 @@ def to_safe_operation(self) -> SafeOperationClass:
 
 
 class UserOperationReceipt(models.Model):
+    """Stores the on-chain receipt metadata produced when a user operation executes."""
+
     user_operation = models.OneToOneField(
         UserOperation, on_delete=models.CASCADE, related_name="receipt"
     )
@@ -141,6 +143,8 @@ def without_confirmations(self):
 
 
 class SafeOperation(TimeStampedModel):
+    """Represents a Safe account-abstraction operation built from a user operation."""
+
     objects = SafeOperationQuerySet.as_manager()
     hash = Keccak256Field(primary_key=True)  # safeOperationHash
     user_operation = models.OneToOneField(
@@ -194,6 +198,8 @@ def build_signature(self) -> bytes:
 
 
 class SafeOperationConfirmation(TimeStampedModel):
+    """Signature provided by a Safe owner to authorize a Safe operation."""
+
     safe_operation = models.ForeignKey(
         SafeOperation,
         on_delete=models.CASCADE,

safe_transaction_service/contracts/models.py

@@ -149,7 +149,9 @@ def trusted_addresses_for_delegate_call(self):
         return self.trusted_for_delegate_call().values_list("address", flat=True)
 
 
-class Contract(models.Model):  # Known contract addresses by the service
+class Contract(models.Model):
+    """Tracks known contract addresses with optional ABI and branding metadata."""
+
     objects = ContractManager.from_queryset(ContractQuerySet)()
     address = EthereumAddressBinaryField(primary_key=True)
     name = models.CharField(max_length=200, blank=True, default="")

safe_transaction_service/history/models.py

@@ -206,6 +206,8 @@ def set_erc20_721_indexing_status(
 
 
 class IndexingStatus(models.Model):
+    """Records the latest processed block for each indexing pipeline."""
+
     objects = IndexingStatusManager()
     indexing_type = models.PositiveSmallIntegerField(
         primary_key=True,
@@ -318,6 +320,8 @@ def until_block(self, block_number: int):
 
 
 class EthereumBlock(models.Model):
+    """Ethereum block header and metadata used for indexing and reorg handling."""
+
     objects = EthereumBlockManager.from_queryset(EthereumBlockQuerySet)()
     number = models.PositiveIntegerField(primary_key=True)
     gas_limit = Uint256Field()
@@ -411,6 +415,8 @@ def account_abstraction_txs(self) -> RawQuerySet:
 
 
 class EthereumTx(TimeStampedModel):
+    """Ethereum transaction enriched with receipt data and indexer bookkeeping."""
+
     objects = EthereumTxManager()
     block = models.ForeignKey(
         EthereumBlock,
@@ -571,6 +577,8 @@ def fast_count(self, address: ChecksumAddress) -> int:
 
 
 class TokenTransfer(models.Model):
+    """Abstract base model normalizing token transfer events across standards."""
+
     objects = TokenTransferManager.from_queryset(TokenTransferQuerySet)()
     ethereum_tx = models.ForeignKey(EthereumTx, on_delete=models.CASCADE)
     timestamp = models.DateTimeField(db_index=True)
@@ -651,6 +659,8 @@ def token_txs(self):
 
 
 class ERC20Transfer(TokenTransfer):
+    """ERC-20 `Transfer` event captured for a tracked Safe-related transaction."""
+
     objects = TokenTransferManager.from_queryset(ERC20TransferQuerySet)()
     value = Uint256Field()
 
@@ -767,6 +777,8 @@ def token_txs(self):
 
 
 class ERC721Transfer(TokenTransfer):
+    """ERC-721 `Transfer` event including the non-fungible token identifier."""
+
     objects = ERC721TransferManager.from_queryset(ERC721TransferQuerySet)()
     token_id = Uint256Field()
 
@@ -1111,6 +1123,11 @@ def can_be_decoded(self):
 
 
 class InternalTx(models.Model):
+    """
+    Represents an internal call trace produced while executing a Safe-related transaction.
+    For L2 networks, as traces are not available, they are "simulated" from events.
+    """
+
     objects = InternalTxManager.from_queryset(InternalTxQuerySet)()
     ethereum_tx = models.ForeignKey(
         EthereumTx, on_delete=models.CASCADE, related_name="internal_txs"
@@ -1326,6 +1343,8 @@ def safes_pending_to_be_processed(self) -> QuerySet[ChecksumAddress]:
 
 
 class InternalTxDecoded(models.Model):
+    """Holds decoded Safe contract call data for an internal transaction."""
+
     objects = InternalTxDecodedManager.from_queryset(InternalTxDecodedQuerySet)()
     internal_tx = models.OneToOneField(
         InternalTx,
@@ -1586,6 +1605,8 @@ def queued(self, safe_address: str):
 
 
 class MultisigTransaction(TimeStampedModel):
+    """Safe multisig transaction with execution status, gas parameters, and signatures."""
+
     objects = MultisigTransactionManager.from_queryset(MultisigTransactionQuerySet)()
     safe_tx_hash = Keccak256Field(primary_key=True)
     safe = EthereumAddressBinaryField(db_index=True)
@@ -1707,6 +1728,8 @@ def not_indexed_metadata_contract_addresses(self):
 
 
 class ModuleTransaction(TimeStampedModel):
+    """Safe module execution derived from an internal transaction trace."""
+
     objects = ModuleTransactionManager()
     internal_tx = models.OneToOneField(
         InternalTx, on_delete=models.CASCADE, related_name="module_tx", primary_key=True
@@ -1781,6 +1804,8 @@ def with_transaction(self):
 
 
 class MultisigConfirmation(TimeStampedModel):
+    """Owner confirmation or signature associated with a multisig transaction."""
+
     objects = MultisigConfirmationManager.from_queryset(MultisigConfirmationQuerySet)()
     ethereum_tx = models.ForeignKey(
         EthereumTx,
@@ -1847,6 +1872,8 @@ def to_dict(self) -> dict:
 
 
 class MonitoredAddress(models.Model):
+    """Abstract base storing indexing progress for addresses we continuously monitor."""
+
     address = EthereumAddressBinaryField(primary_key=True)
     initial_block_number = models.IntegerField(
         default=0
@@ -1867,6 +1894,8 @@ def __str__(self):
 
 
 class ProxyFactory(MonitoredAddress):
+    """Safe Proxy Factory contract whose emitted events are tracked for deployments."""
+
     class Meta:
         verbose_name_plural = "Proxy factories"
         ordering = ["tx_block_number"]
@@ -1912,6 +1941,8 @@ def relevant(self):
 
 
 class SafeMasterCopy(MonitoredAddress):
+    """Indexed Safe master copy contract including version and deployment metadata."""
+
     objects = SafeMasterCopyManager.from_queryset(SafeMasterCopyQueryset)()
     version = models.CharField(max_length=20, validators=[validate_version])
     deployer = models.CharField(max_length=50, default="Safe")
@@ -1955,6 +1986,8 @@ def banned(
 
 
 class SafeContract(models.Model):
+    """Represents a deployed Safe smart contract and its creation transaction."""
+
     objects = SafeContractManager.from_queryset(SafeContractQuerySet)()
     created = models.DateTimeField(auto_now_add=True, db_index=True)
     address = EthereumAddressBinaryField(primary_key=True)
@@ -2135,6 +2168,8 @@ def from_erc20_721_event(
 
 
 class SafeStatusBase(models.Model):
+    """Shared Safe state representation produced after processing an internal transaction."""
+
     internal_tx = models.OneToOneField(
         InternalTx,
         on_delete=models.CASCADE,
@@ -2255,6 +2290,8 @@ def addresses_for_owner(self, owner_address: str) -> QuerySet[str]:
 
 
 class SafeLastStatus(SafeStatusBase):
+    """Latest known Safe state cached for quick access."""
+
     objects = SafeLastStatusManager()
 
     class Meta:
@@ -2330,6 +2367,8 @@ def last_for_address(self, address: str) -> Optional["SafeStatus"]:
 
 
 class SafeStatus(SafeStatusBase):
+    """Historical Safe state snapshot for each processed configuration change."""
+
     objects = SafeStatusManager.from_queryset(SafeStatusQuerySet)()
     internal_tx = models.OneToOneField(
         InternalTx,

safe_transaction_service/tokens/models.py

@@ -208,6 +208,8 @@ def without_logo(self):
 
 
 class Token(models.Model):
+    """Stores metadata about ERC-20 and ERC-721 tokens handled by the service."""
+
     objects = TokenManager.from_queryset(TokenQuerySet)()
     pool_tokens = PoolTokenManager()
     address = EthereumAddressBinaryField(primary_key=True)
@@ -334,6 +336,8 @@ class TokenListToken(TypedDict):
 
 
 class TokenList(models.Model):
+    """References an external token list that should be ingested into the service."""
+
     url = models.URLField(unique=True)
     description = models.CharField(max_length=200)