feat: rename btl into expires_in

Author: Matthias Zimmermann

PUBLISHING.md

@@ -192,7 +192,7 @@ Python session in interactive shell.
 ```python
 from arkiv import Arkiv
 client = Arkiv()
-entity_key, _ = client.arkiv.create_entity(payload=b'Hello world!', btl=1000)
+entity_key, _ = client.arkiv.create_entity(payload=b'Hello world!', expires_in=1000)
 client.arkiv.get_entity(entity_key)
 ```
 

README.md

@@ -41,7 +41,7 @@ entity_key, receipt = client.arkiv.create_entity(
     payload=b"Hello World!",
     content_type="text/plain",
     attributes={"type": "greeting", "version": 1},
-    btl=1000
+    expires_in=1000
 )
 
 # Check and print entity key
@@ -71,7 +71,7 @@ async def main():
         entity_key, tx_hash = await client.arkiv.create_entity(
             payload=b"Hello Async World!",
             attributes={"type": "greeting", "version": 1},
-            btl=1000
+            expires_in=1000
         )
 
         # Get entity and check existence
@@ -110,7 +110,7 @@ client = Arkiv(provider, account=account)
 entity_key, tx_hash = client.arkiv.create_entity(
     payload=b"Hello World!",
     attributes={"type": "greeting", "version": 1},
-    btl = 1000
+    expires_in = 1000
 )
 
 entity = client.arkiv.get_entity(entity_key)
@@ -398,60 +398,6 @@ client.arkiv.cleanup_filters()
 
 ## Arkiv Topics/Features
 
-### BTL
-
-BTL (Blocks-To-Live) should be replaced with explicit `expires_at_block` values for predictability and composability.
-
-Relative `BTL` depends on execution timing and creates unnecessary complexity:
-- An entity created with `btl=100` will have different expiration blocks depending on when the transaction is mined
-- Extending entity lifetimes requires fetching the entity, calculating remaining blocks, and adding more—a race-prone pattern
-- Creates asymmetry between write operations (which use `btl`) and read operations (which return `expires_at_block`)
-- Mempool management can accept any value
-
-Absolute `expires_at_block` is predictable, composable, and matches what you get when reading entities:
-- Deterministic regardless of execution timing
-- Maps directly to `Entity.expires_at_block` field returned by queries
-- Enables clean compositional patterns like `replace(entity, expires_at_block=entity.expires_at_block + 100)`
-- Aligns write API with read API, making the SDK more intuitive
-- Mempool needs to manage/delete tx with expires at values in the past
-
-It's complicated. Deterministic mempool management vs predictable tx management in mempool.
-
-```python
-from dataclasses import replace
-
-# Fetch entity
-entity = client.arkiv.get_entity(entity_key)
-
-# Modify payload and extend expiration by 100 blocks
-updated_entity = replace(
-    entity,
-    payload=b"new data",
-    expires_at_block=entity.expires_at_block + 100
-)
-
-# Update entity
-client.arkiv.update_entity(updated_entity)
-```
-
-### Sorting
-
-Querying entities should support sorting results by one or more fields.
-
-**Requirements:**
-- Sort by attributes (string and numeric)
-- Sort by metadata (owner, expires_at_block)
-- Support ascending and descending order
-- Multi-field sorting with priority
-
-**Example:**
-```python
-# SQL-style sorting
-results = client.arkiv.query(
-    "SELECT * FROM entities ORDER BY attributes.priority DESC, attributes.name ASC"
-)
-```
-
 ### Other Features
 
 - **Creation Flags**: Entities should support creation-time flags with meaningful defaults.

docs/MARKETING.md

@@ -348,7 +348,7 @@ Each record ("entity") contains:
 ### **Poor Use Cases (Don't Market These)**
 
 1. ❌ **Permanent Document Archive**
-   - Why: All data expires via BTL, not suitable for permanent legal records
+   - Why: All data expires via expires_in, not suitable for permanent legal records
    - Alternative: Extend important entities regularly, but acknowledge the maintenance
 
 2. ❌ **Real-Time Database Replacement**

docs/USE_CASES.md

@@ -30,7 +30,7 @@ entity_key, tx_hash = client.arkiv.create_entity(
         "trait_type": "beanie",
         "trait_eyes": "blue"
     },
-    btl=100_000_000  # a few years with 2s blocks
+    expires_in=100_000_000  # a few years with 2s blocks
 )
 
 # NFT contract points to entity_key
@@ -82,7 +82,7 @@ for i in range(0, len(file_data), CHUNK_SIZE):
     chunk_key, _ = client.arkiv.create_entity(
         payload=file_data[i:i + CHUNK_SIZE],
         attributes={"file_hash": file_hash, "chunk_index": i // CHUNK_SIZE},
-        btl=100_000_000
+        expires_in=100_000_000
     )
     chunk_keys.append(chunk_key)
 
@@ -94,7 +94,7 @@ manifest_key, _ = client.arkiv.create_entity(
         "file_name": "video.mp4",
         "chunk_keys": ",".join(chunk_keys),
     },
-    btl=100_000_000
+    expires_in=100_000_000
 )
 
 # Reconstruct file
@@ -243,15 +243,15 @@ proposal = client.arkiv.create_entity(
         "votes_against": 0,
         "quorum": 40000000
     },
-    btl=100_000_000  # Keep for historical record
+    expires_in=100_000_000  # Keep for historical record
 )
 
 # Update vote counts (cheap!)
 arkiv.update_entity(
     proposal_key,
     payload=proposal.payload,  # Same text
     attributes={"votes_for": 1234, "votes_against": 567, "status": "passed"},
-    btl=100_000_000  # Keep for historical record
+    expires_in=100_000_000  # Keep for historical record
 )
 
 # Query all active proposals
@@ -300,7 +300,7 @@ btc_price_data = client.arkiv.create_entity(
         "network_id": network_id,
         "market": "crypto"
     },
-    btl=100_000  # Keep 1 month
+    expires_in=100_000  # Keep 1 month
 )
 
 # Applications read latest or query history
@@ -342,7 +342,7 @@ shipment_key = client.arkiv.create_entity(
         "product_sku": "PROD-789",
         "status": "in_transit",
     },
-    btl=10_000_000  # Keep 6 months
+    expires_in=10_000_000  # Keep 6 months
 )
 
 status_key = client.arkiv.create_entity(
@@ -354,7 +354,7 @@ status_key = client.arkiv.create_entity(
         "location": "warehouse_b",
         "temperature": 5.0,
     }
-    btl=10_000_000  # Keep 6 months
+    expires_in=10_000_000  # Keep 6 months
 )
 
 delivery_key = client.arkiv.create_entity(
@@ -368,7 +368,7 @@ delivery_key = client.arkiv.create_entity(
         "delivery_timestamp": delivery_timestamp,
         "signature": customer_signature_hash,
     }
-    btl=10_000_000  # Keep 6 months
+    expires_in=10_000_000  # Keep 6 months
 )
 
 # Update status at each checkpoint
@@ -430,7 +430,7 @@ model_entity_key = client.arkiv.create_entity(
         "author": researcher_address,
         "framework": "pytorch"
     },
-    btl=10_000_000
+    expires_in=10_000_000
 )
 
 # Track experiments
@@ -446,7 +446,7 @@ experiment = client.arkiv.create_entity(
         "accuracy": 95,
         "f1_score": 93,
         },
-    btl=5_000_000
+    expires_in=5_000_000
 )
 
 # Provable model lineage

src/arkiv/contract.py

@@ -9,11 +9,10 @@
 from web3.types import RPCEndpoint
 
 # ArkivProcessorAddress
-STORAGE_ADDRESS: Final[ChecksumAddress] = Web3.to_checksum_address(
+ARKIV_ADDRESS: Final[ChecksumAddress] = Web3.to_checksum_address(
     "0x00000000000000000000000000000061726B6976"
 )
 
-
 CREATED_EVENT: Final[str] = "ArkivEntityCreated"
 UPDATED_EVENT: Final[str] = "ArkivEntityUpdated"
 EXPIRED_EVENT: Final[str] = "ArkivEntityExpired"

src/arkiv/module.py

@@ -75,13 +75,16 @@ def create_entity(
         payload: bytes | None = None,
         content_type: str | None = None,
         attributes: Attributes | None = None,
-        btl: int | None = None,
+        expires_in: int | None = None,
         tx_params: TxParams | None = None,
     ) -> tuple[EntityKey, TransactionReceipt]:
         # Docstring inherited from ArkivModuleBase.create_entity
         # Create operation and execute TX
         create_op = to_create_op(
-            payload=payload, content_type=content_type, attributes=attributes, btl=btl
+            payload=payload,
+            content_type=content_type,
+            attributes=attributes,
+            expires_in=expires_in,
         )
         operations = Operations(creates=[create_op])
         receipt = self.execute(operations, tx_params)
@@ -100,7 +103,7 @@ def update_entity(
         payload: bytes | None = None,
         content_type: str | None = None,
         attributes: Attributes | None = None,
-        btl: int | None = None,
+        expires_in: int | None = None,
         tx_params: TxParams | None = None,
     ) -> TransactionReceipt:
         # Docstring inherited from ArkivModuleBase.update_entity
@@ -110,7 +113,7 @@ def update_entity(
             payload=payload,
             content_type=content_type,
             attributes=attributes,
-            btl=btl,
+            expires_in=expires_in,
         )
         operations = Operations(updates=[update_op])
         receipt = self.execute(operations, tx_params)
@@ -403,33 +406,6 @@ def get_block_timing(self) -> Any:
 
         return block_timing_response
 
-    def to_blocks(
-        self, seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0
-    ) -> int:
-        """
-        Convert a time duration to number of blocks.
-
-        Useful for calculating blocks-to-live (BTL) parameters based on
-        desired entity lifetime.
-
-        Args:
-            seconds: Number of seconds
-            minutes: Number of minutes
-            hours: Number of hours
-            days: Number of days
-
-        Returns:
-            Number of blocks corresponding to the time duration
-        """
-        total_seconds = seconds + minutes * 60 + hours * 3600 + days * 86400
-
-        if not hasattr(self, "_block_duration"):
-            block_timing = self.get_block_timing()
-            self._block_duration = block_timing["duration"]
-
-        block_time = self._block_duration
-        return total_seconds // block_time if block_time else 0
-
     @property
     def active_filters(self) -> list[EventFilter]:
         """Get a copy of currently active event filters."""

src/arkiv/module_async.py

@@ -74,13 +74,16 @@ async def create_entity(  # type: ignore[override]
         payload: bytes | None = None,
         content_type: str | None = None,
         attributes: Attributes | None = None,
-        btl: int | None = None,
+        expires_in: int | None = None,
         tx_params: TxParams | None = None,
     ) -> tuple[EntityKey, TransactionReceipt]:
         # Docstring inherited from ArkivModuleBase.create_entity
         # Create the operation and execute TX
         create_op = to_create_op(
-            payload=payload, content_type=content_type, attributes=attributes, btl=btl
+            payload=payload,
+            content_type=content_type,
+            attributes=attributes,
+            expires_in=expires_in,
         )
         operations = Operations(creates=[create_op])
         receipt = await self.execute(operations, tx_params)
@@ -99,7 +102,7 @@ async def update_entity(  # type: ignore[override]
         payload: bytes | None = None,
         content_type: str | None = None,
         attributes: Attributes | None = None,
-        btl: int | None = None,
+        expires_in: int | None = None,
         tx_params: TxParams | None = None,
     ) -> TransactionReceipt:
         # Docstring inherited from ArkivModuleBase.update_entity
@@ -109,7 +112,7 @@ async def update_entity(  # type: ignore[override]
             payload=payload,
             content_type=content_type,
             attributes=attributes,
-            btl=btl,
+            expires_in=expires_in,
         )
         operations = Operations(updates=[update_op])
         receipt = await self.execute(operations, tx_params)
@@ -366,33 +369,6 @@ async def get_block_timing(self) -> Any:
 
         return block_timing_response
 
-    async def to_blocks(
-        self, seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0
-    ) -> int:
-        """
-        Convert a time duration to number of blocks.
-
-        Useful for calculating blocks-to-live (BTL) parameters based on
-        desired entity lifetime.
-
-        Args:
-            seconds: Number of seconds
-            minutes: Number of minutes
-            hours: Number of hours
-            days: Number of days
-
-        Returns:
-            Number of blocks corresponding to the time duration
-        """
-        total_seconds = seconds + minutes * 60 + hours * 3600 + days * 86400
-
-        if not hasattr(self, "_block_duration"):
-            block_timing = await self.get_block_timing()
-            self._block_duration = block_timing["duration"]
-
-        block_time = self._block_duration
-        return total_seconds // block_time if block_time else 0
-
     @property
     def active_filters(self) -> list[AsyncEventFilter]:
         """Get a copy of currently active async event filters."""