iwa 0.0.10__py3-none-any.whl → 0.0.12__py3-none-any.whl

iwa/plugins/olas/contracts/service.py

@@ -213,3 +213,53 @@ class ServiceManagerContract(ContractInstance):
             tx_params={"from": from_address},
         )
         return tx
+
+
+class ServiceRegistryTokenUtilityContract(ContractInstance):
+    """Class to interact with the service registry token utility contract.
+
+    This contract manages token-bonded services, tracking agent bonds and
+    security deposits for services that use ERC20 tokens (like OLAS) instead
+    of native currency.
+    """
+
+    name = "service_registry_token_utility"
+    abi_path = OLAS_ABI_PATH / "service_registry_token_utility.json"
+
+    def get_agent_bond(self, service_id: int, agent_id: int) -> int:
+        """Get the agent bond for a specific agent in a service.
+
+        Args:
+            service_id: The service ID.
+            agent_id: The agent ID within the service.
+
+        Returns:
+            The bond amount in wei.
+
+        """
+        return self.call("getAgentBond", service_id, agent_id)
+
+    def get_operator_balance(self, operator: str, service_id: int) -> int:
+        """Get the operator balance for a service.
+
+        Args:
+            operator: The operator address.
+            service_id: The service ID.
+
+        Returns:
+            The balance amount in wei.
+
+        """
+        return self.call("getOperatorBalance", operator, service_id)
+
+    def get_service_token_deposit(self, service_id: int) -> tuple:
+        """Get the token deposit info for a service.
+
+        Args:
+            service_id: The service ID.
+
+        Returns:
+            Tuple of (token_address, security_deposit).
+
+        """
+        return self.call("mapServiceIdTokenDeposit", service_id)

iwa/plugins/olas/service_manager/lifecycle.py

@@ -1,4 +1,61 @@
-"""Lifecycle manager mixin."""
+"""Lifecycle manager mixin for OLAS service lifecycle operations.
+
+OLAS Service Lifecycle & Token Flow
+====================================
+
+This module handles the first 4 steps of the service lifecycle (staking is in staking.py).
+Each step involves specific token movements as detailed below.
+
+STEP 1: CREATE SERVICE
+    - What happens:
+        * Service is registered on-chain with metadata (config hash, agent IDs)
+        * Service ownership NFT (ERC-721) is minted to service owner
+        * Bond parameters are recorded but NO tokens move yet
+    - Token Movement: None
+    - Approval: Service Owner → Token Utility (for 2 × bond_amount OLAS)
+    - Next State: PRE_REGISTRATION
+
+STEP 2: ACTIVATE REGISTRATION
+    - What happens:
+        * Service Owner signals readiness to accept agent registrations
+        * Token Utility pulls min_staking_deposit OLAS from owner via transferFrom()
+    - Token Movement:
+        * 5,000 OLAS: Service Owner → Token Utility (for 10k contract)
+    - Native value sent: 1 wei (not 5k OLAS!)
+        * This is MIN_AGENT_BOND, a placeholder for native-bonded services
+        * For OLAS-bonded services, tokens move via Token Utility, not via msg.value
+    - Next State: ACTIVE_REGISTRATION
+
+STEP 3: REGISTER AGENT
+    - What happens:
+        * Agent instance address is registered to the service
+        * Token Utility pulls agent_bond OLAS from owner via transferFrom()
+    - Token Movement:
+        * 5,000 OLAS: Service Owner → Token Utility (for 10k contract)
+    - Native value sent: 1 wei per agent
+        * Same logic as activation - tokens move via Token Utility
+    - Next State: FINISHED_REGISTRATION
+
+STEP 4: DEPLOY
+    - What happens:
+        * Safe multisig is created with agent instances as owners
+        * Service transitions to operational state
+    - Token Movement: None
+    - Next State: DEPLOYED
+
+After DEPLOYED, see staking.py for STEP 5: STAKE
+
+Token Utility Contract:
+    The Token Utility (0xa45E64d13A30a51b91ae0eb182e88a40e9b18eD8 on Gnosis) is the
+    intermediary that holds OLAS deposits. When you call activateRegistration() or
+    registerAgents() on the Service Manager, it internally calls Token Utility's
+    transferFrom() to move OLAS from the service owner.
+
+    This is why:
+    1. We approve Token Utility BEFORE activation/registration
+    2. We send 1 wei native value (not the OLAS amount) in TX
+    3. The actual OLAS moves via transferFrom(), not msg.value
+"""
 
 from typing import List, Optional, Union
 
@@ -20,7 +77,26 @@ from iwa.plugins.olas.models import Service
 
 
 class LifecycleManagerMixin:
-    """Mixin for service lifecycle operations."""
+    """Mixin for OLAS service lifecycle operations.
+
+    Handles the CREATE → ACTIVATE → REGISTER → DEPLOY flow for OLAS services.
+    Each method transitions the service to the next state.
+
+    Token Movement Summary:
+        ┌───────────────┬────────────────────────────────────────────────────┐
+        │ Step          │ OLAS Movement                                      │
+        ├───────────────┼────────────────────────────────────────────────────┤
+        │ create()      │ None (just approval to Token Utility)              │
+        │ activate()    │ 5k OLAS → Token Utility (via transferFrom)         │
+        │ register()    │ 5k OLAS → Token Utility (via transferFrom)         │
+        │ deploy()      │ None (just creates Safe multisig)                  │
+        └───────────────┴────────────────────────────────────────────────────┘
+
+    Usage:
+        manager = ServiceManager(wallet)
+        service_id = manager.create(chain_name="gnosis", token_address_or_tag="OLAS")
+        manager.spin_up(bond_amount_wei=5000e18, staking_contract=staking)
+    """
 
     def create(
         self,
@@ -192,7 +268,22 @@ class LifecycleManagerMixin:
         service_owner_account,
         bond_amount_wei: Wei,
     ) -> None:
-        """Approve token utility if a token address is provided."""
+        """Approve Token Utility to spend OLAS tokens (called during create).
+
+        Why 2× bond amount?
+            - Activation requires min_staking_deposit (= bond_amount)
+            - Registration requires agent_bond (= bond_amount)
+            - Total = 2 × bond_amount
+
+        Token Movement: None (this is just an approval, not a transfer)
+
+        Args:
+            token_address: OLAS token address (or None for native).
+            chain_name: Chain to operate on.
+            service_owner_account: Account that owns the OLAS tokens.
+            bond_amount_wei: Bond amount per agent in wei.
+
+        """
         if not token_address:
             return
 
@@ -204,7 +295,7 @@ class LifecycleManagerMixin:
             logger.error(f"OLAS Service Registry Token Utility not found for chain: {chain_name}")
             return
 
-        # Approve the token utility to move tokens (2 * bond amount as per Triton reference)
+        # Approve the token utility to move tokens (2 * bond amount: activation + registration)
         logger.info(f"Approving Token Utility {utility_address} for {2 * bond_amount_wei} tokens")
         approve_success = self.transfer_service.approve_erc20(
             owner_address_or_tag=service_owner_account.address,
@@ -218,7 +309,28 @@ class LifecycleManagerMixin:
             logger.error("Failed to approve Token Utility")
 
     def activate_registration(self) -> bool:
-        """Activate registration for the service."""
+        """Activate registration for the service (Step 2 of lifecycle).
+
+        What This Does:
+            Transitions service from PRE_REGISTRATION → ACTIVE_REGISTRATION.
+            Signals that the service owner is ready to accept agent registrations.
+
+        Token Movement:
+            5,000 OLAS (for 10k contract): Service Owner → Token Utility
+            - Moved internally by Token Utility via transferFrom()
+            - NOT sent as msg.value (that's just 1 wei)
+
+        Native Value Sent:
+            1 wei (MIN_AGENT_BOND placeholder, not the actual deposit)
+
+        Prerequisites:
+            - Service must be in PRE_REGISTRATION state
+            - Token Utility must be approved to spend owner's OLAS
+
+        Returns:
+            True if activation succeeded, False otherwise.
+
+        """
         service_id = self.service.service_id
         logger.info(f"[ACTIVATE] Starting activation for service {service_id}")
 
@@ -266,29 +378,50 @@ class LifecycleManagerMixin:
     def _ensure_token_approval_for_activation(
         self, token_address: str, security_deposit: Wei
     ) -> bool:
-        """Ensure token approval for activation if not native token."""
+        """Ensure token approval for activation if not native token.
+
+        For token-bonded services (e.g., OLAS), we need to approve the
+        ServiceRegistryTokenUtility contract to spend the security deposit
+        (agent bond) on our behalf.
+
+        IMPORTANT: We query the exact bond amount from the Token Utility contract
+        rather than approving a fixed amount, to match the official OLAS middleware.
+        """
         is_native = str(token_address).lower() == str(ZERO_ADDRESS).lower()
         if is_native:
             return True
 
         try:
-            # Check Master Balance first
+            # Get the exact agent bond from Token Utility contract
+            bond_amount = self._get_agent_bond_from_token_utility()
+            if bond_amount is None or bond_amount == 0:
+                logger.warning(
+                    "[ACTIVATE] Could not get agent bond from Token Utility, using security_deposit"
+                )
+                bond_amount = security_deposit
+
+            logger.info(f"[ACTIVATE] Agent bond from Token Utility: {bond_amount} wei")
+
+            # Check owner balance
             balance = self.wallet.balance_service.get_erc20_balance_wei(
                 account_address_or_tag=self.service.service_owner_address,
                 token_address_or_name=token_address,
                 chain_name=self.chain_name,
             )
 
-            if balance < security_deposit:
+            if balance < bond_amount:
                 logger.error(
-                    f"[ACTIVATE] FAIL: Owner balance {balance} < required {security_deposit}"
+                    f"[ACTIVATE] FAIL: Owner balance {balance} < required {bond_amount}"
                 )
+                return False
 
             protocol_contracts = OLAS_CONTRACTS.get(self.chain_name.lower(), {})
             utility_address = protocol_contracts.get("OLAS_SERVICE_REGISTRY_TOKEN_UTILITY")
 
             if utility_address:
-                required_approval = Web3.to_wei(1000, "ether")  # Approve generous amount to be safe
+                # Approve exactly the bond amount (not 1000 OLAS fixed!)
+                # This matches the official OLAS middleware behavior
+                required_approval = bond_amount
 
                 # Check current allowance
                 allowance = self.wallet.transfer_service.get_erc20_allowance(
@@ -298,9 +431,10 @@ class LifecycleManagerMixin:
                     chain_name=self.chain_name,
                 )
 
-                if allowance < Web3.to_wei(10, "ether"):  # Min threshold check
+                if allowance < required_approval:
                     logger.info(
-                        f"Low allowance ({allowance}). Approving Token Utility {utility_address}"
+                        f"[ACTIVATE] Allowance ({allowance}) < required ({required_approval}). "
+                        f"Approving Token Utility {utility_address}"
                     )
                     success_approve = self.wallet.transfer_service.approve_erc20(
                         owner_address_or_tag=self.service.service_owner_address,
@@ -310,27 +444,87 @@ class LifecycleManagerMixin:
                         chain_name=self.chain_name,
                     )
                     if not success_approve:
-                        logger.warning("Token approval transaction returned failure.")
+                        logger.error("[ACTIVATE] Token approval failed")
                         return False
+                    logger.info(f"[ACTIVATE] Approved {required_approval} wei to Token Utility")
+                else:
+                    logger.debug(
+                        f"[ACTIVATE] Sufficient allowance ({allowance} >= {required_approval})"
+                    )
             return True
         except Exception as e:
-            logger.warning(f"Failed to check/approve tokens: {e}")
-            return False  # Return False only if we are strict, or True if we want to try anyway?
-            # Original code swallowed exception but continued.
-            # If we want to return early, we should return False.
-            # However, if we swallow, we return True. Let's stick to original behavior,
-            # BUT original code didn't return False here, it just logged and continued.
-            # To be safer with clean code, if token approval fails, we should probably stop.
-            # Let's assume we return True to match original "swallow" behavior but log it.
-            return True
+            logger.error(f"[ACTIVATE] Failed to check/approve tokens: {e}")
+            return False
+
+    def _get_agent_bond_from_token_utility(self) -> Optional[int]:
+        """Get the agent bond from the ServiceRegistryTokenUtility contract.
+
+        This queries the on-chain Token Utility contract to get the exact bond
+        amount required for the service, matching the official OLAS middleware.
+
+        Returns:
+            The agent bond in wei, or None if the query fails.
+
+        """
+        from iwa.plugins.olas.contracts.service import ServiceRegistryTokenUtilityContract
+
+        try:
+            protocol_contracts = OLAS_CONTRACTS.get(self.chain_name.lower(), {})
+            utility_address = protocol_contracts.get("OLAS_SERVICE_REGISTRY_TOKEN_UTILITY")
+
+            if not utility_address:
+                logger.warning("[ACTIVATE] Token Utility address not found for chain")
+                return None
+
+            # Get agent ID (first agent in the service)
+            service_info = self.registry.get_service(self.service.service_id)
+            agent_ids = service_info.get("agent_ids", [])
+            if not agent_ids:
+                logger.warning("[ACTIVATE] No agent IDs found for service")
+                return None
+            agent_id = agent_ids[0]
+
+            # Use the ServiceRegistryTokenUtilityContract with official ABI
+            token_utility = ServiceRegistryTokenUtilityContract(
+                address=str(utility_address),
+                chain_name=self.chain_name,
+            )
+
+            bond = token_utility.get_agent_bond(self.service.service_id, agent_id)
+
+            logger.debug(
+                f"[ACTIVATE] Token Utility getAgentBond({self.service.service_id}, {agent_id}) = {bond}"
+            )
+            return bond
+
+        except Exception as e:
+            logger.warning(f"[ACTIVATE] Failed to get agent bond from Token Utility: {e}")
+            return None
 
     def _send_activation_transaction(self, service_id: int, security_deposit: Wei) -> bool:
-        """Send the activation transaction."""
-        logger.debug(f"[ACTIVATE] Preparing tx: service_id={service_id}, value={security_deposit}")
+        """Send the activation transaction.
+
+        For token-bonded services (e.g., OLAS), we pass MIN_AGENT_BOND (1 wei) as native value.
+        The Token Utility handles OLAS transfers internally based on the service configuration.
+        For native currency services, we pass the full security_deposit.
+        """
+        # Determine if this is a token-bonded service
+        token_address = self._get_service_token(service_id)
+        is_native = str(token_address).lower() == str(ZERO_ADDRESS).lower()
+
+        # For token services, use MIN_AGENT_BOND (1 wei) as native value
+        # The OLAS token approval was done in _ensure_token_approval_for_activation
+        activation_value = security_deposit if is_native else 1
+        logger.info(
+            f"[ACTIVATE] Token={token_address}, is_native={is_native}, "
+            f"activation_value={activation_value} wei"
+        )
+
+        logger.debug(f"[ACTIVATE] Preparing tx: service_id={service_id}, value={activation_value}")
         activate_tx = self.manager.prepare_activate_registration_tx(
             from_address=self.wallet.master_account.address,
             service_id=service_id,
-            value=security_deposit,
+            value=activation_value,
         )
         logger.debug(f"[ACTIVATE] TX prepared: to={activate_tx.get('to')}")
 
@@ -441,7 +635,12 @@ class LifecycleManagerMixin:
     def _ensure_agent_token_approval(
         self, agent_account_address: str, bond_amount_wei: Optional[Wei]
     ) -> bool:
-        """Ensure token approval for agent registration if needed."""
+        """Ensure token approval for agent registration if needed.
+
+        For token-bonded services, the service owner must approve the Token Utility
+        contract to transfer the agent bond. We query the exact bond from the
+        Token Utility contract to match the official OLAS middleware.
+        """
         service_id = self.service.service_id
         token_address = self._get_service_token(service_id)
         is_native = str(token_address) == str(ZERO_ADDRESS)
@@ -449,38 +648,75 @@ class LifecycleManagerMixin:
         if is_native:
             return True
 
+        # Get exact bond from Token Utility if not explicitly provided
         if not bond_amount_wei:
-            logger.warning("No bond amount provided for token bonding. Agent might fail to bond.")
-            # We don't return False here, similar to original logic, just warn.
-            # But approval will fail if we try to approve None.
-            return True
+            bond_amount_wei = self._get_agent_bond_from_token_utility()
+            if not bond_amount_wei:
+                logger.warning(
+                    "[REGISTER] Could not get bond from Token Utility, skipping approval"
+                )
+                return True
 
-        # 1. Service Owner Approves Token Utility (for Bond)
-        # The service owner (operator) pays the bond, not the agent.
-        logger.info(f"Service Owner approving Token Utility for bond: {bond_amount_wei} wei")
+        logger.info(f"[REGISTER] Service Owner approving Token Utility for bond: {bond_amount_wei} wei")
 
         utility_address = str(
             OLAS_CONTRACTS[self.chain_name]["OLAS_SERVICE_REGISTRY_TOKEN_UTILITY"]
         )
 
+        # Check current allowance first
+        allowance = self.wallet.transfer_service.get_erc20_allowance(
+            owner_address_or_tag=self.service.service_owner_address,
+            spender_address=utility_address,
+            token_address_or_name=token_address,
+            chain_name=self.chain_name,
+        )
+
+        if allowance >= bond_amount_wei:
+            logger.debug(
+                f"[REGISTER] Sufficient allowance ({allowance} >= {bond_amount_wei})"
+            )
+            return True
+
+        # Use service owner which holds the OLAS tokens (not necessarily master)
         approve_success = self.wallet.transfer_service.approve_erc20(
             token_address_or_name=token_address,
             spender_address_or_tag=utility_address,
             amount_wei=bond_amount_wei,
-            owner_address_or_tag=agent_account_address,
+            owner_address_or_tag=self.service.service_owner_address,
             chain_name=self.chain_name,
         )
         if not approve_success:
-            logger.error("Failed to approve token for agent registration")
+            logger.error("[REGISTER] Failed to approve token for agent registration")
             return False
+
+        logger.info(f"[REGISTER] Approved {bond_amount_wei} wei to Token Utility")
         return True
 
     def _send_register_agent_transaction(self, agent_account_address: str) -> bool:
-        """Send the register agent transaction."""
+        """Send the register agent transaction.
+
+        For token-bonded services (e.g., OLAS), we pass MIN_AGENT_BOND (1 wei) as native value.
+        The Token Utility handles OLAS transfers internally via transferFrom.
+        For native currency services, we pass the full security_deposit * num_agents.
+        """
         service_id = self.service.service_id
-        service_info = self.registry.get_service(service_id)
-        security_deposit = service_info["security_deposit"]
-        total_value = security_deposit * len(self.service.agent_ids)
+        token_address = self._get_service_token(service_id)
+        is_native = str(token_address).lower() == str(ZERO_ADDRESS).lower()
+
+        # For token services, use MIN_AGENT_BOND (1 wei) per agent
+        # For native services, use security_deposit * num_agents
+        if is_native:
+            service_info = self.registry.get_service(service_id)
+            security_deposit = service_info["security_deposit"]
+            total_value = security_deposit * len(self.service.agent_ids)
+        else:
+            # MIN_AGENT_BOND = 1 wei per agent
+            total_value = 1 * len(self.service.agent_ids)
+
+        logger.info(
+            f"[REGISTER] Token={token_address}, is_native={is_native}, "
+            f"total_value={total_value} wei"
+        )
 
         logger.debug(
             f"[REGISTER] Preparing tx: agent={agent_account_address}, "