iwa 0.0.33__tar.gz → 0.0.58__tar.gz

{iwa-0.0.33/src/iwa.egg-info → iwa-0.0.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iwa
-Version: 0.0.33
+Version: 0.0.58
 Summary: A secure, modular, and plugin-based framework for crypto agents and ops
 Requires-Python: <4.0,>=3.12
 Description-Content-Type: text/markdown
@@ -17,6 +17,7 @@ Requires-Dist: tomli-w>=1.2.0
 Requires-Dist: typer>=0.19.2
 Requires-Dist: web3>=7.13.0
 Requires-Dist: pyyaml<7.0.0,>=6.0.3
+Requires-Dist: ruamel.yaml>=0.18.0
 Requires-Dist: safe-eth-py>=7.14.0
 Requires-Dist: twine>=6.2.0
 Requires-Dist: cowdao-cowpy>=1.0.1
@@ -82,7 +83,7 @@ iwa/
 ├── core/               # Core wallet functionality
 │   ├── keys.py         # KeyStorage - Encrypted key management
 │   ├── wallet.py       # Wallet - High-level interface
-│   ├── chain.py        # ChainInterface - Blockchain interaction with rate limiting
+│   ├── chain/          # Blockchain interface with rate limiting
 │   ├── services/       # Service layer (accounts, balances, transactions)
 │   └── contracts/      # Contract abstractions (ERC20, Safe)
 ├── plugins/            # Protocol integrations
@@ -134,6 +135,9 @@ GNOSIS_RPC=https://rpc.gnosis.io,https://gnosis.drpc.org
 ETHEREUM_RPC=https://mainnet.infura.io/v3/YOUR_KEY
 BASE_RPC=https://mainnet.base.org
 
+# Testing mode (default: true uses Tenderly test RPCs)
+TESTING=false
+
 # Optional
 GNOSISSCAN_API_KEY=your_api_key
 COINGECKO_API_KEY=your_api_key
@@ -150,7 +154,6 @@ just web
 
 # Use CLI
 iwa wallet list --chain gnosis
-iwa wallet balance <address> --chain gnosis
 ```
 
 ### Running Tests

{iwa-0.0.33 → iwa-0.0.58}/README.md

@@ -43,7 +43,7 @@ iwa/
 ├── core/               # Core wallet functionality
 │   ├── keys.py         # KeyStorage - Encrypted key management
 │   ├── wallet.py       # Wallet - High-level interface
-│   ├── chain.py        # ChainInterface - Blockchain interaction with rate limiting
+│   ├── chain/          # Blockchain interface with rate limiting
 │   ├── services/       # Service layer (accounts, balances, transactions)
 │   └── contracts/      # Contract abstractions (ERC20, Safe)
 ├── plugins/            # Protocol integrations
@@ -95,6 +95,9 @@ GNOSIS_RPC=https://rpc.gnosis.io,https://gnosis.drpc.org
 ETHEREUM_RPC=https://mainnet.infura.io/v3/YOUR_KEY
 BASE_RPC=https://mainnet.base.org
 
+# Testing mode (default: true uses Tenderly test RPCs)
+TESTING=false
+
 # Optional
 GNOSISSCAN_API_KEY=your_api_key
 COINGECKO_API_KEY=your_api_key
@@ -111,7 +114,6 @@ just web
 
 # Use CLI
 iwa wallet list --chain gnosis
-iwa wallet balance <address> --chain gnosis
 ```
 
 ### Running Tests

{iwa-0.0.33 → iwa-0.0.58}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "iwa"
-version = "0.0.33"
+version = "0.0.58"
 description = "A secure, modular, and plugin-based framework for crypto agents and ops"
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
@@ -17,6 +17,7 @@ dependencies = [
     "typer>=0.19.2",
     "web3>=7.13.0",
     "pyyaml (>=6.0.3,<7.0.0)",
+    "ruamel.yaml>=0.18.0",
     "safe-eth-py>=7.14.0",
     "twine>=6.2.0",
     "cowdao-cowpy>=1.0.1",
@@ -71,7 +72,7 @@ where = ["src"]
 
 [tool.ruff]
 line-length = 100
-target-version = "0.0.33"
+target-version = "0.0.58"
 fix = true
 
 [tool.ruff.lint]

{iwa-0.0.33 → iwa-0.0.58}/src/iwa/core/chain/interface.py

@@ -34,9 +34,11 @@ class ChainInterface:
             chain: SupportedChain = getattr(SupportedChains(), chain.lower())
 
         self.chain = chain
-        self._rate_limiter = get_rate_limiter(chain.name)
+        # Enforce strict 1.0 RPS limit to prevent synchronization issues
+        self._rate_limiter = get_rate_limiter(chain.name, rate=1.0, burst=1)
         self._current_rpc_index = 0
         self._rpc_failure_counts: Dict[int, int] = {}
+        self._last_rotation_time = 0.0  # Monotonic timestamp of last rotation
 
         if self.chain.rpc and self.chain.rpc.startswith("http://"):
             logger.warning(
@@ -213,12 +215,24 @@ class ChainInterface:
         ]
         return any(signal in err_text for signal in server_error_signals)
 
+    def _is_gas_error(self, error: Exception) -> bool:
+        """Check if error is related to gas limits or fees."""
+        err_text = str(error).lower()
+        gas_signals = [
+            "intrinsic gas too low",
+            "feetoolow",
+            "gas limit",
+            "underpriced",
+        ]
+        return any(signal in err_text for signal in gas_signals)
+
     def _handle_rpc_error(self, error: Exception) -> Dict[str, Union[bool, int]]:
         """Handle RPC errors with smart rotation and retry logic."""
         result: Dict[str, Union[bool, int]] = {
             "is_rate_limit": self._is_rate_limit_error(error),
             "is_connection_error": self._is_connection_error(error),
             "is_server_error": self._is_server_error(error),
+            "is_gas_error": self._is_gas_error(error),
             "is_tenderly_quota": self._is_tenderly_quota_exceeded(error),
             "rotated": False,
             "should_retry": False,
@@ -242,9 +256,11 @@ class ChainInterface:
 
         if should_rotate:
             error_type = "rate limit" if result["is_rate_limit"] else "connection"
+            # Extract the original URL from the error message for clarity
+            error_msg = str(error)
             logger.warning(
                 f"RPC {error_type} error on {self.chain.name} "
-                f"(RPC #{self._current_rpc_index}): {error}"
+                f"(current RPC #{self._current_rpc_index}): {error_msg}"
             )
 
             if self.rotate_rpc():
@@ -253,27 +269,49 @@ class ChainInterface:
                 logger.info(f"Rotated to RPC #{self._current_rpc_index} for {self.chain.name}")
             else:
                 if result["is_rate_limit"]:
-                    self._rate_limiter.trigger_backoff(seconds=5.0)
+                    # Rotation was skipped (cooldown or single RPC) - still allow retry with current RPC
+                    # We don't trigger backoff here because that would block ALL threads.
+                    # Instead, we let the individual thread retry (which has its own exponential backoff).
                     result["should_retry"] = True
-                    logger.warning("No other RPCs available, triggered backoff")
+                    logger.info(
+                        f"RPC rotation skipped, retrying with current RPC #{self._current_rpc_index}"
+                    )
 
         elif result["is_server_error"]:
             logger.warning(f"Server error on {self.chain.name}: {error}")
             result["should_retry"] = True
 
+        elif result["is_gas_error"]:
+            logger.warning(f"Gas/Fee error detected: {error}. Allowing retry for adjustment.")
+            result["should_retry"] = True
+
         return result
 
     def rotate_rpc(self) -> bool:
         """Rotate to the next available RPC."""
+        # Minimum time between rotations to prevent cascade rotations from parallel requests
+        # failing simultaneously
+        cooldown_seconds = 2.0
+
         with self._rotation_lock:
             if not self.chain.rpcs or len(self.chain.rpcs) <= 1:
                 return False
 
+            # Cooldown: prevent cascade rotations from in-flight requests
+            now = time.monotonic()
+            if now - self._last_rotation_time < cooldown_seconds:
+                logger.debug(
+                    f"RPC rotation skipped for {self.chain.name} (cooldown active, "
+                    f"{cooldown_seconds - (now - self._last_rotation_time):.1f}s remaining)"
+                )
+                return False
+
             # Simple Round Robin rotation
             self._current_rpc_index = (self._current_rpc_index + 1) % len(self.chain.rpcs)
             # Internal call to _init_web3 already expects to be under lock if called from here,
             # but _init_web3 itself doesn't have a lock. Let's make it consistent.
             self._init_web3_under_lock()
+            self._last_rotation_time = now
 
             logger.info(
                 f"Rotated RPC for {self.chain.name} to index {self._current_rpc_index}: {self.chain.rpcs[self._current_rpc_index]}"
@@ -423,18 +461,88 @@ class ChainInterface:
             return 500_000
 
     def calculate_transaction_params(
-        self, built_method: Callable, tx_params: Dict[str, Union[str, int]]
+        self, built_method: Optional[Callable], tx_params: Dict[str, Union[str, int]]
     ) -> Dict[str, Union[str, int]]:
-        """Calculate transaction parameters for a contract function call."""
+        """Calculate transaction parameters for a contract function call or native transfer."""
+        # Baseline parameters
         params = {
             "from": tx_params["from"],
             "value": tx_params.get("value", 0),
             "nonce": self.web3.eth.get_transaction_count(tx_params["from"]),
-            "gas": self.estimate_gas(built_method, tx_params),
-            "gasPrice": self.web3.eth.gas_price,
         }
+
+        # Add 'to' only for native transfers (built_method is None)
+        # Contract calls already have the target address in the contract object
+        if not built_method and "to" in tx_params:
+            params["to"] = tx_params["to"]
+        elif not built_method and "to" in params: # Fallback if added to params earlier (though not here yet)
+             pass
+
+        # Determine gas
+        if built_method:
+            # Contract function call
+            params["gas"] = self.estimate_gas(built_method, tx_params)
+        elif "gas" in tx_params:
+            # Manual gas override
+            params["gas"] = tx_params["gas"]
+        else:
+            # Native transfer - dynamic estimation
+            try:
+                # web3.eth.estimate_gas returns gas for the dict it receives
+                est_params = {
+                    "from": params["from"],
+                    "to": params["to"],
+                    "value": params["value"]
+                }
+                # Remove None 'to' for contract creation simulation if needed, but usually send() has to
+                if not est_params["to"]:
+                    est_params.pop("to")
+
+                estimated = self.web3.eth.estimate_gas(est_params)
+                # Apply 10% buffer for safety
+                params["gas"] = int(estimated * 1.1)
+                logger.debug(f"[GAS] Estimated native transfer gas: {params['gas']} (raw: {estimated})")
+            except Exception as e:
+                logger.debug(f"[GAS] Native estimation failed, fallback to 21000: {e}")
+                params["gas"] = 21_000
+
+        # Add EIP-1559 or Legacy fees
+        params.update(self.get_suggested_fees())
         return params
 
+    def get_suggested_fees(self) -> Dict[str, int]:
+        """Calculate suggested fees for a transaction (EIP-1559 or legacy)."""
+        try:
+            # Check for EIP-1559 support
+            latest_block = self.web3.eth.get_block("latest")
+            base_fee = latest_block.get("baseFeePerGas")
+
+            if base_fee is not None:
+                # EIP-1559 logic
+                max_priority_fee = int(self.web3.eth.max_priority_fee)
+
+                # Gnosis specific: ensure min priority fee (critical for validation)
+                if self.chain.name.lower() == "gnosis":
+                    if max_priority_fee < 1:
+                        max_priority_fee = 1  # Network minimum is 1 wei
+
+                # Global minimum for EIP-1559
+                if max_priority_fee < 1:
+                    max_priority_fee = 1
+
+                # Buffer max_fee to handle base fee expansion
+                max_fee = int(base_fee * 1.5) + max_priority_fee
+
+                return {
+                    "maxFeePerGas": max_fee,
+                    "maxPriorityFeePerGas": max_priority_fee
+                }
+        except Exception as e:
+            logger.debug(f"Failed to calculate EIP-1559 fees: {e}, falling back to legacy")
+
+        # Legacy fallback
+        return {"gasPrice": self.web3.eth.gas_price}
+
     def wait_for_no_pending_tx(
         self, from_address: EthereumAddress, max_wait_seconds: int = 60, poll_interval: float = 2.0
     ):

{iwa-0.0.33 → iwa-0.0.58}/src/iwa/core/chain/models.py

@@ -26,6 +26,9 @@ class SupportedChain(BaseModel):
 
     def get_token_address(self, token_address_or_name: str) -> Optional[EthereumAddress]:
         """Get token address"""
+        if not token_address_or_name:
+            return None
+
         try:
             address = EthereumAddress(token_address_or_name)
         except Exception:
@@ -35,9 +38,18 @@ class SupportedChain(BaseModel):
             return address
 
         if address is None:
-            return self.tokens.get(token_address_or_name, None)
-
-        return None
+            # Try direct lookup
+            token_addr = self.tokens.get(token_address_or_name, None)
+            if token_addr:
+                return token_addr
+
+            # Try case-insensitive lookup
+            target_lower = token_address_or_name.lower()
+            for name, addr in self.tokens.items():
+                if name.lower() == target_lower:
+                    return addr
+
+            return None
 
     def get_token_name(self, token_address: str) -> Optional[str]:
         """Get token name from address."""

{iwa-0.0.33 → iwa-0.0.58}/src/iwa/core/chain/rate_limiter.py

@@ -108,12 +108,11 @@ def get_rate_limiter(chain_name: str, rate: float = None, burst: int = None) ->
 class RateLimitedEth:
     """Wrapper around web3.eth that applies rate limiting transparently."""
 
-    RPC_METHODS = {
+    READ_METHODS = {
         "get_balance",
         "get_code",
         "get_transaction_count",
         "estimate_gas",
-        "send_raw_transaction",
         "wait_for_transaction_receipt",
         "get_block",
         "get_transaction",
@@ -122,6 +121,16 @@ class RateLimitedEth:
         "get_logs",
     }
 
+    WRITE_METHODS = {
+        "send_raw_transaction",
+    }
+
+    # Helper sets for efficient lookup
+    RPC_METHODS = READ_METHODS | WRITE_METHODS
+
+    DEFAULT_READ_RETRIES = 3
+    DEFAULT_READ_RETRY_DELAY = 0.5
+
     def __init__(self, web3_eth, rate_limiter: RPCRateLimiter, chain_interface: "ChainInterface"):
         """Initialize RateLimitedEth wrapper."""
         object.__setattr__(self, "_eth", web3_eth)
@@ -133,7 +142,7 @@ class RateLimitedEth:
         attr = getattr(self._eth, name)
 
         if name in self.RPC_METHODS and callable(attr):
-            return self._wrap_with_rate_limit(attr, name)
+            return self._wrap_with_retry(attr, name)
 
         return attr
 
@@ -151,23 +160,56 @@ class RateLimitedEth:
         else:
             delattr(self._eth, name)
 
-    def _wrap_with_rate_limit(self, method, method_name):
-        """Wrap a method with rate limiting.
+    @property
+    def block_number(self):
+        """Get block number with retry."""
+        return self._execute_with_retry(lambda: self._eth.block_number, "block_number")
 
-        Note: Error handling (rotation, retry) is NOT done here.
-        It is the responsibility of `ChainInterface.with_retry()` to handle
-        errors and rotate RPCs as needed. This wrapper only ensures
-        rate limiting.
-        """
+    @property
+    def gas_price(self):
+        """Get gas price with retry."""
+        return self._execute_with_retry(lambda: self._eth.gas_price, "gas_price")
+
+    def _wrap_with_retry(self, method, method_name):
+        """Wrap method with rate limiting and retry for reads."""
 
         def wrapper(*args, **kwargs):
             if not self._rate_limiter.acquire(timeout=30.0):
-                raise TimeoutError(f"Rate limit timeout waiting for {method_name}")
+                raise TimeoutError(f"Rate limit timeout for {method_name}")
+
+            # Writes: no auto-retry (handled by caller or not safe)
+            if method_name in self.WRITE_METHODS:
+                return method(*args, **kwargs)
 
-            return method(*args, **kwargs)
+            # Reads: with retry
+            return self._execute_with_retry(method, method_name, *args, **kwargs)
 
         return wrapper
 
+    def _execute_with_retry(self, method, method_name, *args, **kwargs):
+        """Execute read operation with retry logic."""
+        last_error = None
+        for attempt in range(self.DEFAULT_READ_RETRIES + 1):
+            try:
+                return method(*args, **kwargs)
+            except Exception as e:
+                last_error = e
+                # Use chain interface to handle error (logging, rotation, etc.)
+                result = self._chain_interface._handle_rpc_error(e)
+
+                if not result["should_retry"] or attempt >= self.DEFAULT_READ_RETRIES:
+                    raise
+
+                delay = self.DEFAULT_READ_RETRY_DELAY * (2**attempt)
+                logger.debug(
+                    f"{method_name} attempt {attempt + 1} failed, retrying in {delay:.1f}s..."
+                )
+                time.sleep(delay)
+
+        if last_error:
+            raise last_error
+        raise RuntimeError(f"{method_name} failed unexpectedly")
+
 
 class RateLimitedWeb3:
     """Wrapper around Web3 instance that applies rate limiting transparently."""

{iwa-0.0.33 → iwa-0.0.58}/src/iwa/core/cli.py

@@ -40,7 +40,7 @@ def account_create(
     """Create a new wallet account"""
     key_storage = KeyStorage()
     try:
-        key_storage.create_account(tag)
+        key_storage.generate_new_account(tag)
     except ValueError as e:
         typer.echo(f"Error: {e}")
         raise typer.Exit(code=1) from e

{iwa-0.0.33 → iwa-0.0.58}/src/iwa/core/ipfs.py

@@ -7,13 +7,20 @@ direct HTTP API calls, avoiding heavy dependencies like open-aea.
 import hashlib
 import json
 import uuid
-from typing import Any, Dict, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
 
 import aiohttp
 from multiformats import CID
 
 from iwa.core.models import Config
 
+if TYPE_CHECKING:
+    import requests
+
+# Global session for sync requests
+_SYNC_SESSION: Optional["requests.Session"] = None
+
+
 
 def _compute_cid_v1_hex(data: bytes) -> str:
     """Compute CIDv1 hex representation from raw data.
@@ -84,6 +91,21 @@ def push_to_ipfs_sync(
     :return: Tuple of (CIDv1 string, CIDv1 hex representation).
     """
     import requests
+    from requests.adapters import HTTPAdapter
+    from urllib3.util.retry import Retry
+
+    global _SYNC_SESSION
+
+    if _SYNC_SESSION is None:
+        _SYNC_SESSION = requests.Session()
+        retry_strategy = Retry(
+            total=3,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        _SYNC_SESSION.mount("http://", adapter)
+        _SYNC_SESSION.mount("https://", adapter)
 
     url = api_url or Config().core.ipfs_api_url
     endpoint = f"{url}/api/v0/add"
@@ -92,7 +114,7 @@ def push_to_ipfs_sync(
 
     files = {"file": ("data", data, "application/octet-stream")}
 
-    response = requests.post(endpoint, files=files, params=params, timeout=60)
+    response = _SYNC_SESSION.post(endpoint, files=files, params=params, timeout=60)
     response.raise_for_status()
     result = response.json()
 

{iwa-0.0.33 → iwa-0.0.58}/src/iwa/core/keys.py

@@ -210,14 +210,14 @@ class KeyStorage(BaseModel):
         if not self.get_address_by_tag("master"):
             logger.info("Master account not found. Creating new 'master' account...")
             try:
-                self.create_account("master")
+                self.generate_new_account("master")
             except Exception as e:
                 logger.error(f"Failed to create master account: {e}")
 
     @property
-    def master_account(self) -> EncryptedAccount:
+    def master_account(self) -> Optional[Union[EncryptedAccount, StoredSafeAccount]]:
         """Get the master account"""
-        master_account = self.get_account("master")
+        master_account = self.find_stored_account("master")
 
         if not master_account:
             return list(self.accounts.values())[0]
@@ -231,19 +231,34 @@ class KeyStorage(BaseModel):
             # Use backup directory relative to wallet path (supports tests with tmp_path)
             backup_dir = self._path.parent / "backup"
             backup_dir.mkdir(parents=True, exist_ok=True)
+            try:
+                os.chmod(backup_dir, 0o700)
+            except OSError as e:
+                logger.debug(f"Could not chmod backup dir (expected in some Docker setups): {e}")
             timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
             backup_path = backup_dir / f"wallet.json.{timestamp}.bkp"
             shutil.copy2(self._path, backup_path)
+            try:
+                os.chmod(backup_path, 0o600)
+            except OSError as e:
+                logger.debug(f"Could not chmod backup file: {e}")
             logger.debug(f"Backed up wallet to {backup_path}")
 
         # Ensure directory exists
         self._path.parent.mkdir(parents=True, exist_ok=True)
 
         with open(self._path, "w", encoding="utf-8") as f:
-            json.dump(self.model_dump(), f, indent=4)
+            # Use mode='json' to ensure all types (EthereumAddress) are correctly serialized
+            json.dump(self.model_dump(mode='json'), f, indent=4)
+            f.flush()
+            os.fsync(f.fileno())  # Force write to disk (critical for Docker volumes)
 
-        # Enforce read/write only for the owner
-        os.chmod(self._path, 0o600)
+        try:
+            os.chmod(self._path, 0o600)
+        except OSError as e:
+            logger.debug(f"Could not chmod wallet file: {e}")
+
+        logger.info(f"[KeyStorage] Wallet saved to {self._path} ({len(self.accounts)} accounts)")
 
     @staticmethod
     def _encrypt_mnemonic(mnemonic: str, password: str) -> dict:
@@ -328,21 +343,20 @@ class KeyStorage(BaseModel):
         encrypted_acct = EncryptedAccount.encrypt_private_key(
             private_key_hex, self._password, "master"
         )
-        self.accounts[encrypted_acct.address] = encrypted_acct
-        self.save()
-
+        self.register_account(encrypted_acct)
         return encrypted_acct, mnemonic_str
 
-    def create_account(self, tag: str) -> EncryptedAccount:
-        """Create account. Master is derived from mnemonic, others are random."""
+    def generate_new_account(self, tag: str) -> EncryptedAccount:
+        """Generate a brand new EOA account and register it with the given tag."""
+        # Note: register_account(tag) check is inside, but we handle 'master' logic here
         tags = [acct.tag for acct in self.accounts.values()]
         if not tags:
             tag = "master"  # First account is always master
-        if tag in tags:
-            raise ValueError(f"Tag '{tag}' already exists in wallet.")
 
         # Master account: derive from mnemonic
         if tag == "master":
+            if "master" in tags:
+                raise ValueError("Master account already exists in wallet.")
             encrypted_acct, mnemonic = self._create_master_from_mnemonic()
             self._pending_mnemonic = mnemonic  # Store temporarily for display
             return encrypted_acct
@@ -350,10 +364,24 @@ class KeyStorage(BaseModel):
         # Non-master: random key as before
         acct = Account.create()
         encrypted = EncryptedAccount.encrypt_private_key(acct.key.hex(), self._password, tag)
-        self.accounts[acct.address] = encrypted
-        self.save()
+        self.register_account(encrypted)
         return encrypted
 
+    def register_account(self, account: Union[EncryptedAccount, StoredSafeAccount]):
+        """Register an account (EOA or Safe) in the storage with strict tag uniqueness checks."""
+        if not account.tag:
+            # Allow untagged accounts (rare but possible)
+            pass
+        else:
+            # Check for duplicate tags
+            for existing in self.accounts.values():
+                if existing.tag == account.tag and existing.address != account.address:
+                    raise ValueError(f"Tag '{account.tag}' is already used by address {existing.address}")
+
+        self.accounts[account.address] = account
+        logger.info(f"[KeyStorage] Registering account: tag='{account.tag}', address={account.address}")
+        self.save()
+
     def get_pending_mnemonic(self) -> Optional[str]:
         """Get and clear the pending mnemonic (for one-time display).
 
@@ -419,6 +447,22 @@ class KeyStorage(BaseModel):
         del self.accounts[account.address]
         self.save()
 
+    def rename_account(self, address_or_tag: str, new_tag: str):
+        """Rename an account's tag with uniqueness check."""
+        account = self.find_stored_account(address_or_tag)
+        if not account:
+            raise ValueError(f"Account '{address_or_tag}' not found.")
+
+        # Check if new tag is already used by a DIFFERENT account
+        for existing in self.accounts.values():
+            if existing.tag == new_tag and existing.address != account.address:
+                raise ValueError(f"Tag '{new_tag}' is already used by address {existing.address}")
+
+        old_tag = account.tag
+        account.tag = new_tag
+        logger.info(f"[KeyStorage] Renaming account: '{old_tag}' -> '{new_tag}' (address={account.address})")
+        self.save()
+
     def _get_private_key(self, address: str) -> Optional[str]:
         """Get private key (Internal)"""
         account = self.accounts.get(EthereumAddress(address))