draft: moving towards new arkiv node specs

matthiaszimmermann · matthiaszimmermann · commit 109b1e61bcea · 2025-10-26T22:43:57.000Z
diff --git a/src/arkiv/contract.py b/src/arkiv/contract.py
@@ -15,28 +15,44 @@
 )
 
 
-CREATED_EVENT: Final[str] = "GolemBaseStorageEntityCreated"
-UPDATED_EVENT: Final[str] = "GolemBaseStorageEntityUpdated"
-EXTENDED_EVENT: Final[str] = "GolemBaseStorageEntityBTLExtended"
-DELETED_EVENT: Final[str] = "GolemBaseStorageEntityDeleted"
+CREATED_EVENT_LEGACY: Final[str] = "GolemBaseStorageEntityCreated"
+UPDATED_EVENT_LEGACY: Final[str] = "GolemBaseStorageEntityUpdated"
+EXTENDED_EVENT_LEGACY: Final[str] = "GolemBaseStorageEntityBTLExtended"
+DELETED_EVENT_LEGACY: Final[str] = "GolemBaseStorageEntityDeleted"
+
+CREATED_EVENT: Final[str] = "ArkivEntityCreated"
+UPDATED_EVENT: Final[str] = "ArkivEntityUpdated"
+DELETED_EVENT: Final[str] = "ArkivEntityDeleted"
+EXPIRED_EVENT: Final[str] = "ArkivEntityExpired"
+EXTENDED_EVENT: Final[str] = "ArkivEntityBTLExtended"
+OWNER_CHANGED_EVENT: Final[str] = "ArkivEntityOwnerChanged"
+
 
 EVENTS: dict[str, str] = {
+    "created_legacy": CREATED_EVENT_LEGACY,
+    "updated_legacy": UPDATED_EVENT_LEGACY,
+    "extended_legacy": EXTENDED_EVENT_LEGACY,
+    "deleted_legacy": DELETED_EVENT_LEGACY,
     "created": CREATED_EVENT,
     "updated": UPDATED_EVENT,
     "extended": EXTENDED_EVENT,
     "deleted": DELETED_EVENT,
+    "expired": EXPIRED_EVENT,
+    "owner_changed": OWNER_CHANGED_EVENT,
 }
 
 TYPE_EVENT = "event"
 TYPE_UINT = "uint256"
+TYPE_ADDRESS = "address"
+
 EVENTS_ABI: Final[Sequence[dict[str, Any]]] = [
     {
         "anonymous": False,
         "inputs": [
             {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
             {"indexed": False, "name": "expirationBlock", "type": TYPE_UINT},
         ],
-        "name": CREATED_EVENT,
+        "name": CREATED_EVENT_LEGACY,
         "type": TYPE_EVENT,
     },
     {
@@ -45,25 +61,88 @@
             {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
             {"indexed": False, "name": "expirationBlock", "type": TYPE_UINT},
         ],
-        "name": UPDATED_EVENT,
+        "name": UPDATED_EVENT_LEGACY,
         "type": TYPE_EVENT,
     },
     {
         "anonymous": False,
         "inputs": [{"indexed": True, "name": "entityKey", "type": TYPE_UINT}],
-        "name": DELETED_EVENT,
+        "name": DELETED_EVENT_LEGACY,
+        "type": TYPE_EVENT,
+    },
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": False, "name": "oldExpirationBlock", "type": TYPE_UINT},
+            {"indexed": False, "name": "newExpirationBlock", "type": TYPE_UINT},
+        ],
+        "name": EXTENDED_EVENT_LEGACY,
+        "type": TYPE_EVENT,
+    },
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": True, "name": "ownerAddress", "type": TYPE_ADDRESS},
+            {"indexed": False, "name": "expirationBlock", "type": TYPE_UINT},
+            {"indexed": False, "name": "cost", "type": TYPE_UINT},
+        ],
+        "name": CREATED_EVENT,
         "type": TYPE_EVENT,
     },
     {
         "anonymous": False,
         "inputs": [
             {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": True, "name": "ownerAddress", "type": TYPE_ADDRESS},
             {"indexed": False, "name": "oldExpirationBlock", "type": TYPE_UINT},
             {"indexed": False, "name": "newExpirationBlock", "type": TYPE_UINT},
+            {"indexed": False, "name": "cost", "type": TYPE_UINT},
+        ],
+        "name": UPDATED_EVENT,
+        "type": TYPE_EVENT,
+    },
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": True, "name": "ownerAddress", "type": TYPE_ADDRESS},
+        ],
+        "name": DELETED_EVENT,
+        "type": TYPE_EVENT,
+    },
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": True, "name": "ownerAddress", "type": TYPE_ADDRESS},
         ],
         "name": EXTENDED_EVENT,
         "type": TYPE_EVENT,
     },
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": True, "name": "ownerAddress", "type": TYPE_ADDRESS},
+            {"indexed": False, "name": "oldExpirationBlock", "type": TYPE_UINT},
+            {"indexed": False, "name": "newExpirationBlock", "type": TYPE_UINT},
+            {"indexed": False, "name": "cost", "type": TYPE_UINT},
+        ],
+        "name": EXPIRED_EVENT,
+        "type": TYPE_EVENT,
+    },
+    {
+        "anonymous": False,
+        "inputs": [
+            {"indexed": True, "name": "entityKey", "type": TYPE_UINT},
+            {"indexed": True, "name": "oldOwnerAddress", "type": TYPE_ADDRESS},
+            {"indexed": True, "name": "newOwnerAddress", "type": TYPE_ADDRESS},
+        ],
+        "name": OWNER_CHANGED_EVENT,
+        "type": TYPE_EVENT,
+    },
 ]
 
 
diff --git a/src/arkiv/events_base.py b/src/arkiv/events_base.py
@@ -130,6 +130,8 @@ def _extract_tx_hash(self, event_data: EventData) -> TxHash:
             tx_hash_hex = f"0x{tx_hash_hex}"
         return TxHash(HexStr(tx_hash_hex))
 
+    # TODO (1) check/match against utils.py::to_receipt
+    # TODO (2) update to new log/event definition in contract.py
     def _parse_event_data(self, event_data: EventData) -> tuple[EventObject, TxHash]:
         """
         Parse event data and create appropriate event object.
diff --git a/src/arkiv/module.py b/src/arkiv/module.py
@@ -295,6 +295,10 @@ def get_entity(self, entity_key: EntityKey, fields: int = ALL) -> Entity:
         """
         # Gather the requested data
         owner: ChecksumAddress | None = None
+        created_at_block: int | None = None
+        last_modified_at_block: int | None = None
+        transaction_index: int | None = None
+        operation_index: int | None = None
         expires_at_block: int | None = None
         payload: bytes | None = None
         annotations: Annotations | None = None
@@ -308,11 +312,28 @@ def get_entity(self, entity_key: EntityKey, fields: int = ALL) -> Entity:
             # get and decode annotations and/or metadata if requested
             if fields & METADATA or fields & ANNOTATIONS:
                 metadata_all = self._get_entity_metadata(entity_key)
+                logger.info(
+                    f"Fetched metadata for entity[{entity_key}]: {metadata_all}"
+                )
 
                 if fields & METADATA:
                     # Convert owner address to checksummed format
                     owner = self._get_owner(metadata_all)
-                    expires_at_block = self._get_expires_at_block(metadata_all)
+                    created_at_block = self._get_metadata_numeric_field(
+                        metadata_all, "createdAtBlock"
+                    )
+                    last_modified_at_block = self._get_metadata_numeric_field(
+                        metadata_all, "lastModifiedAtBlock"
+                    )
+                    expires_at_block = self._get_metadata_numeric_field(
+                        metadata_all, "expiresAtBlock"
+                    )
+                    transaction_index = self._get_metadata_numeric_field(
+                        metadata_all, "transactionIndex"
+                    )
+                    operation_index = self._get_metadata_numeric_field(
+                        metadata_all, "operationIndex"
+                    )
 
                 if fields & ANNOTATIONS:
                     annotations = merge_annotations(
@@ -327,7 +348,11 @@ def get_entity(self, entity_key: EntityKey, fields: int = ALL) -> Entity:
             entity_key=entity_key,
             fields=fields,
             owner=owner,
+            created_at_block=created_at_block,
+            last_modified_at_block=last_modified_at_block,
             expires_at_block=expires_at_block,
+            transaction_index=transaction_index,
+            operation_index=operation_index,
             payload=payload,
             annotations=annotations,
         )
diff --git a/src/arkiv/module_base.py b/src/arkiv/module_base.py
@@ -133,6 +133,15 @@ def _get_expires_at_block(self, metadata: dict[str, Any]) -> int:
             raise ValueError("Entity metadata missing required 'expiresAtBlock' field")
         return int(expires_at_block_metadata)
 
+    def _get_metadata_numeric_field(
+        self, metadata: dict[str, Any], field_name: str
+    ) -> int:
+        """Get a numeric field from the entity metadata."""
+        field_value = metadata.get(field_name)
+        if field_value is None:
+            raise ValueError(f"Entity metadata missing required '{field_name}' field")
+        return int(field_value)
+
     def _validate_query_entities_params(
         self,
         query: str | None,
diff --git a/src/arkiv/types.py b/src/arkiv/types.py
@@ -62,7 +62,11 @@ class Entity:
 
     # Populated when fields | METADATA returns true
     owner: ChecksumAddress | None
+    created_at_block: int | None
+    last_modified_at_block: int | None
     expires_at_block: int | None
+    transaction_index: int | None
+    operation_index: int | None
 
     # Populated when fields | PAYLOAD returns true
     payload: bytes | None
diff --git a/tests/test_entity_create.py b/tests/test_entity_create.py
@@ -148,7 +148,7 @@ def test_create_entity_simple(self, arkiv_client_http: Arkiv) -> None:
         check_tx_hash(label, tx_hash)
 
         entity = arkiv_client_http.arkiv.get_entity(entity_key)
-        logger.info(f"{label}: Retrieved entity: {entity}")
+        logger.info(f"{label}: Retrieved entity:\n{entity}")
 
         assert entity.entity_key == entity_key, f"{label}: Entity key should match"
         assert entity.payload == pl, f"{label}: Entity payload should match"
diff --git a/tests/test_entity_extend.py b/tests/test_entity_extend.py
@@ -32,6 +32,7 @@ def test_extend_entity_simple(self, arkiv_client_http: Arkiv) -> None:
 
         # Get initial expiration block
         entity_before = arkiv_client_http.arkiv.get_entity(entity_key)
+        logger.info(f"Entity before extension: {entity_before}")
         initial_expiration = entity_before.expires_at_block
         assert initial_expiration is not None, "Entity should have expiration block"
         logger.info(f"Initial expiration block: {initial_expiration}")
@@ -50,6 +51,7 @@ def test_extend_entity_simple(self, arkiv_client_http: Arkiv) -> None:
 
         # Verify the entity still exists and expiration increased
         entity_after = arkiv_client_http.arkiv.get_entity(entity_key)
+        logger.info(f"Entity after extension: {entity_after}")
         assert entity_after.expires_at_block == initial_expiration + number_of_blocks, (
             f"Expiration should increase by {number_of_blocks} blocks"
         )
