iwa 0.0.0__tar.gz → 0.0.1a2__tar.gz

iwa-0.0.1a2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Iwa Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iwa-0.0.1a2/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: iwa
+Version: 0.0.1a2
+Summary: Add your description here
+Requires-Python: <4.0,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bip-utils>=2.9.3
+Requires-Dist: cryptography>=46.0.2
+Requires-Dist: eth-account>=0.13.7
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: pydantic-settings>=2.11.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: tomli>=2.3.0
+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: safe-eth-py>=7.14.0
+Requires-Dist: twine>=6.2.0
+Requires-Dist: cowdao-cowpy>=1.0.1
+Requires-Dist: pytest>=9.0.1
+Requires-Dist: textual>=0.47.1
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: peewee>=3.17.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn>=0.32.0
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: cbor2==5.8.0
+Requires-Dist: slowapi>=0.1.9
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: pynacl>=1.6.2
+Requires-Dist: urllib3>=2.6.3
+Dynamic: license-file
+
+# Iwa
+
+[![PyPI version](https://badge.fury.io/py/iwa.svg)](https://badge.fury.io/py/iwa)
+[![Docker Pulls](https://img.shields.io/docker/pulls/dvilela/iwa.svg)](https://hub.docker.com/r/dvilela/iwa)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-672%20passed-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-86%25-brightgreen.svg)]()
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+*Iwa (岩), meaning "rock" in Japanese, symbolizes the unshakeable stability and immutable foundation required for secure financial infrastructure.*
+
+</br>
+<p align="center">
+  <img width="40%" src="https://raw.githubusercontent.com/dvilelaf/iwa/master/images/iwa.png">
+</p>
+</br>
+
+Iwa is a Python framework designed for managing crypto wallets and interacting with smart contracts and crypto protocols in a secure, modular, and extensible way. It's ideal for building autonomous agents and applications that require blockchain interactions.
+
+## Features
+
+- **Secure Key Storage**: Private keys are encrypted with AES-256-GCM and stored safely. They are never exposed to the application layer; signing happens internally via the `KeyStorage` class.
+
+- **Modularity (Plugins)**: Protocols and features are implemented as plugins, loaded dynamically. Currently supports Gnosis (Safe, CowSwap) and Olas (Registry, Services, Staking).
+
+- **Multi-Chain Support**: Native support for Gnosis Chain, Ethereum, and Base, with easy extensibility for others.
+
+- **Robust Transaction Management**:
+  - **RPC Rotation**: Automatically switches RPC providers if one fails or is rate-limited.
+  - **Rate Limiting**: Token bucket algorithm with automatic backoff.
+  - **Retry Logic**: Automatic retries with exponential backoff for transient failures.
+
+- **CLI & TUI Integration**: Interact with your wallet via a unified CLI or a beautiful Terminal User Interface built with Textual.
+
+- **Web API**: RESTful API built with FastAPI for web-based integrations.
+
+- **Modern Tooling**: Managed with `uv`, `Justfile` for automation, and ready for Docker deployment.
+
+## Architecture
+
+```
+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
+│   ├── services/       # Service layer (accounts, balances, transactions)
+│   └── contracts/      # Contract abstractions (ERC20, Safe)
+├── plugins/            # Protocol integrations
+│   ├── gnosis/         # Safe multisig and CowSwap DEX
+│   └── olas/           # Olas Registry, Services, Staking
+├── tui/                # Terminal User Interface (Textual)
+└── web/                # Web API (FastAPI)
+```
+
+### Key Components
+
+| Component | Description |
+|-----------|-------------|
+| `KeyStorage` | Encrypts/decrypts private keys, provides internal signing |
+| `Wallet` | Main high-level interface for user interactions |
+| `ChainInterface` | Manages Web3 connections with rate limiting and RPC rotation |
+| `TransactionService` | Handles transaction signing and sending with retry logic |
+| `PluginService` | Dynamically loads and manages protocol plugins |
+
+## Setup & Usage
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Installation
+
+```bash
+# Install from PyPI
+pip install iwa
+
+# Or using uv (recommended for tools)
+uv tool install iwa
+
+# Or from source
+git clone https://github.com/dvilelaf/iwa.git
+cd iwa
+just install
+```
+
+### Configuration
+
+Create a `secrets.env` file with your configuration:
+
+```bash
+WALLET_PASSWORD=your_secure_password
+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
+
+# Optional
+GNOSISSCAN_API_KEY=your_api_key
+COINGECKO_API_KEY=your_api_key
+```
+
+### Running
+
+```bash
+# Launch TUI
+just tui
+
+# Launch Web UI
+just web
+
+# Use CLI
+iwa wallet list --chain gnosis
+iwa wallet balance <address> --chain gnosis
+```
+
+### Running Tests
+
+```bash
+just test
+```
+
+### Security Checks
+
+```bash
+just security  # Runs gitleaks, bandit, and pip-audit
+```
+
+### Docker
+
+```bash
+# Pull from Docker Hub
+docker pull dvilelaf/iwa:latest
+
+# Build locally
+just docker-build
+just docker-run
+```
+
+## Plugins
+
+Plugins are located in `src/iwa/plugins`. Currently supported:
+
+### Gnosis Plugin
+- **Safe**: Create and manage Safe multisig wallets
+- **CowSwap**: Token swaps via CoW Protocol with MEV protection, Max balance support, and auto-refreshing UI
+
+### Olas Plugin
+- **Registry**: Interact with Olas service registry
+- **Services**: Create, deploy, and manage Olas services
+- **Staking**: Stake/unstake services and claim rewards
+
+## Transaction Flow
+
+1. **Preparation**: A high-level method prepares a raw transaction dictionary
+2. **Delegation**: The transaction is passed to `TransactionService`
+3. **Signing**: `KeyStorage` decrypts the key in memory, signs, and wipes the key
+4. **Sending**: The signed transaction is sent via `ChainInterface`
+5. **Recovery**: Automatic RPC rotation and gas bumping on failures
+6. **Receipt**: Transaction receipt is returned upon success
+
+## Documentation
+
+Full documentation is available in the `docs/` directory:
+
+```bash
+# Serve docs locally
+just docs-serve
+
+# Build static docs
+just docs-build
+```
+
+## Development
+
+```bash
+# Format code
+just format
+
+# Lint code
+just check
+
+# Type check
+just types
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

iwa-0.0.1a2/README.md

@@ -0,0 +1,197 @@
+# Iwa
+
+[![PyPI version](https://badge.fury.io/py/iwa.svg)](https://badge.fury.io/py/iwa)
+[![Docker Pulls](https://img.shields.io/docker/pulls/dvilela/iwa.svg)](https://hub.docker.com/r/dvilela/iwa)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-672%20passed-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-86%25-brightgreen.svg)]()
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+*Iwa (岩), meaning "rock" in Japanese, symbolizes the unshakeable stability and immutable foundation required for secure financial infrastructure.*
+
+</br>
+<p align="center">
+  <img width="40%" src="https://raw.githubusercontent.com/dvilelaf/iwa/master/images/iwa.png">
+</p>
+</br>
+
+Iwa is a Python framework designed for managing crypto wallets and interacting with smart contracts and crypto protocols in a secure, modular, and extensible way. It's ideal for building autonomous agents and applications that require blockchain interactions.
+
+## Features
+
+- **Secure Key Storage**: Private keys are encrypted with AES-256-GCM and stored safely. They are never exposed to the application layer; signing happens internally via the `KeyStorage` class.
+
+- **Modularity (Plugins)**: Protocols and features are implemented as plugins, loaded dynamically. Currently supports Gnosis (Safe, CowSwap) and Olas (Registry, Services, Staking).
+
+- **Multi-Chain Support**: Native support for Gnosis Chain, Ethereum, and Base, with easy extensibility for others.
+
+- **Robust Transaction Management**:
+  - **RPC Rotation**: Automatically switches RPC providers if one fails or is rate-limited.
+  - **Rate Limiting**: Token bucket algorithm with automatic backoff.
+  - **Retry Logic**: Automatic retries with exponential backoff for transient failures.
+
+- **CLI & TUI Integration**: Interact with your wallet via a unified CLI or a beautiful Terminal User Interface built with Textual.
+
+- **Web API**: RESTful API built with FastAPI for web-based integrations.
+
+- **Modern Tooling**: Managed with `uv`, `Justfile` for automation, and ready for Docker deployment.
+
+## Architecture
+
+```
+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
+│   ├── services/       # Service layer (accounts, balances, transactions)
+│   └── contracts/      # Contract abstractions (ERC20, Safe)
+├── plugins/            # Protocol integrations
+│   ├── gnosis/         # Safe multisig and CowSwap DEX
+│   └── olas/           # Olas Registry, Services, Staking
+├── tui/                # Terminal User Interface (Textual)
+└── web/                # Web API (FastAPI)
+```
+
+### Key Components
+
+| Component | Description |
+|-----------|-------------|
+| `KeyStorage` | Encrypts/decrypts private keys, provides internal signing |
+| `Wallet` | Main high-level interface for user interactions |
+| `ChainInterface` | Manages Web3 connections with rate limiting and RPC rotation |
+| `TransactionService` | Handles transaction signing and sending with retry logic |
+| `PluginService` | Dynamically loads and manages protocol plugins |
+
+## Setup & Usage
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Installation
+
+```bash
+# Install from PyPI
+pip install iwa
+
+# Or using uv (recommended for tools)
+uv tool install iwa
+
+# Or from source
+git clone https://github.com/dvilelaf/iwa.git
+cd iwa
+just install
+```
+
+### Configuration
+
+Create a `secrets.env` file with your configuration:
+
+```bash
+WALLET_PASSWORD=your_secure_password
+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
+
+# Optional
+GNOSISSCAN_API_KEY=your_api_key
+COINGECKO_API_KEY=your_api_key
+```
+
+### Running
+
+```bash
+# Launch TUI
+just tui
+
+# Launch Web UI
+just web
+
+# Use CLI
+iwa wallet list --chain gnosis
+iwa wallet balance <address> --chain gnosis
+```
+
+### Running Tests
+
+```bash
+just test
+```
+
+### Security Checks
+
+```bash
+just security  # Runs gitleaks, bandit, and pip-audit
+```
+
+### Docker
+
+```bash
+# Pull from Docker Hub
+docker pull dvilelaf/iwa:latest
+
+# Build locally
+just docker-build
+just docker-run
+```
+
+## Plugins
+
+Plugins are located in `src/iwa/plugins`. Currently supported:
+
+### Gnosis Plugin
+- **Safe**: Create and manage Safe multisig wallets
+- **CowSwap**: Token swaps via CoW Protocol with MEV protection, Max balance support, and auto-refreshing UI
+
+### Olas Plugin
+- **Registry**: Interact with Olas service registry
+- **Services**: Create, deploy, and manage Olas services
+- **Staking**: Stake/unstake services and claim rewards
+
+## Transaction Flow
+
+1. **Preparation**: A high-level method prepares a raw transaction dictionary
+2. **Delegation**: The transaction is passed to `TransactionService`
+3. **Signing**: `KeyStorage` decrypts the key in memory, signs, and wipes the key
+4. **Sending**: The signed transaction is sent via `ChainInterface`
+5. **Recovery**: Automatic RPC rotation and gas bumping on failures
+6. **Receipt**: Transaction receipt is returned upon success
+
+## Documentation
+
+Full documentation is available in the `docs/` directory:
+
+```bash
+# Serve docs locally
+just docs-serve
+
+# Build static docs
+just docs-build
+```
+
+## Development
+
+```bash
+# Format code
+just format
+
+# Lint code
+just check
+
+# Type check
+just types
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

iwa-0.0.1a2/pyproject.toml

@@ -0,0 +1,135 @@
+[project]
+name = "iwa"
+version = "0.0.1-alpha2"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+dependencies = [
+    "bip-utils>=2.9.3",
+    "cryptography>=46.0.2",
+    "eth-account>=0.13.7",
+    "loguru>=0.7.3",
+    "pydantic>=2.12.0",
+    "pydantic-settings>=2.11.0",
+    "rich>=14.2.0",
+    "tomli>=2.3.0",
+    "tomli-w>=1.2.0",
+    "typer>=0.19.2",
+    "web3>=7.13.0",
+    "pyyaml (>=6.0.3,<7.0.0)",
+    "safe-eth-py>=7.14.0",
+    "twine>=6.2.0",
+    "cowdao-cowpy>=1.0.1",
+    "pytest>=9.0.1",
+    "textual>=0.47.1",
+    "pyperclip>=1.8.2",
+    "peewee>=3.17.0",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.32.0",
+    "jinja2>=3.1.4",
+    "cbor2==5.8.0",
+    "slowapi>=0.1.9",
+    "nest-asyncio>=1.6.0",
+    "aiohttp>=3.13.3",
+    "pynacl>=1.6.2",
+    "urllib3>=2.6.3",
+]
+
+[project.scripts]
+iwa = "iwa.core.cli:iwa_cli"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.18.2",
+    "ruff>=0.14.1",
+    "twine>=6.2.0",
+    "pytest-cov>=6.0.0",
+    "pytest-asyncio>=0.23.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.5.49",
+    "mkdocstrings[python]>=0.27.0",
+    "bandit>=1.9.2",
+    "pip-audit>=2.10.0",
+    "djlint>=1.34.1",
+]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+line-length = 100
+target-version = "0.0.1-alpha2"
+fix = true
+
+[tool.ruff.lint]
+extend-select = ["I", "B", "C90", "N", "D"]  # imports, bugbear, complexity, naming, docstrings
+ignore = [
+    "E501",
+    "D203",
+    "D213",
+    "D400",  # First line should end with a period
+    "D401", # First line should be in imperative mood
+    "D415",  # First line should end with a period, question mark, or exclamation point
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/tests/**/*.py" = ["D", "E402"]
+"tests/**/*.py" = ["D", "E402"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+# strict = true
+[tool.mypy]
+check_untyped_defs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true
+follow_imports = "silent"
+exclude = [
+    "pydantic_core",
+    "typing_inspection",
+    "src/tests/.*",
+    "tests/.*",
+    "src/iwa/tools/.*",
+    "src/iwa/tui/.*", # TUI is often complex with types, delaying check for speed
+    "src/iwa/plugins/olas/scripts/.*", # Integration test scripts, not production code
+]
+
+[[tool.mypy.overrides]]
+module = [
+    "bip_utils.*",
+    "cowdao_cowpy.*",
+    "eth_account.*",
+    "loguru.*",
+    "peewee.*",
+    "playhouse.*",
+    "pydantic.*",
+    "pydantic_core.*",
+    "pyperclip.*",
+    "pytest.*",
+    "rich.*",
+    "safe_eth.*",
+    "textual.*",
+    "tomli_w.*",
+    "typer.*",
+    "web3.*",
+    "iwa.plugins.*",
+    "iwa.tui.*",
+    "iwa.core.*",
+    "iwa.*",
+    "iwa.tools.*",
+    "tests.*",
+]
+ignore_missing_imports = true
+ignore_errors = true
+follow_imports = "skip"
+
+[tool.bandit]
+exclude_dirs = ["tests", "src/tests", "src/iwa/plugins/olas/tests"]
+skips = ["B101", "B105", "B106", "B110", "B107", "B112"]
+[tool.djlint]
+profile = "jinja"
+extension = "html"
+indent = 4

iwa-0.0.1a2/src/conftest.py

@@ -0,0 +1,22 @@
+"""Pytest configuration."""
+
+import logging
+
+import pytest
+from loguru import logger
+
+
+@pytest.fixture(autouse=True)
+def caplog(caplog):
+    """Make loguru logs visible to pytest caplog."""
+
+    class PropagateHandler(logging.Handler):
+        def emit(self, record):
+            logging.getLogger(record.name).handle(record)
+
+    handler_id = logger.add(PropagateHandler(), format="{message}")
+    yield caplog
+    try:
+        logger.remove(handler_id)
+    except ValueError:
+        pass

iwa-0.0.1a2/src/iwa/__init__.py

@@ -0,0 +1 @@
+"""iwa package."""

iwa-0.0.1a2/src/iwa/__main__.py

@@ -0,0 +1,6 @@
+"""iwa main."""
+
+from iwa.core import cli
+
+if __name__ == "__main__":
+    cli.iwa_cli()

iwa-0.0.1a2/src/iwa/core/__init__.py

@@ -0,0 +1 @@
+"""iwa.core package."""

iwa-0.0.1a2/src/iwa/core/chain/__init__.py

@@ -0,0 +1,68 @@
+"""Chain interaction helpers.
+
+This package provides chain-related utilities for blockchain interactions:
+- ChainInterface: Main interface for interacting with a blockchain
+- ChainInterfaces: Singleton manager for all supported chains
+- SupportedChain: Base model for chain definitions
+- Rate limiting and error handling utilities
+
+All symbols are re-exported here for backward compatibility.
+Import from `iwa.core.chain` to use these utilities.
+"""
+
+from typing import TypeVar
+
+# Re-export all public symbols for backward compatibility
+from iwa.core.chain.errors import (
+    TenderlyQuotaExceededError,
+    sanitize_rpc_url,
+)
+from iwa.core.chain.interface import (
+    DEFAULT_RPC_TIMEOUT,
+    ChainInterface,
+)
+from iwa.core.chain.manager import ChainInterfaces
+from iwa.core.chain.models import (
+    Base,
+    Ethereum,
+    Gnosis,
+    SupportedChain,
+    SupportedChains,
+)
+from iwa.core.chain.rate_limiter import (
+    RateLimitedEth,
+    RateLimitedWeb3,
+    RPCRateLimiter,
+    get_rate_limiter,
+)
+
+# Backward compatibility alias
+_sanitize_rpc_url = sanitize_rpc_url
+
+# Expose type variable for retry decorator (used in type hints)
+T = TypeVar("T")
+
+__all__ = [
+    # Errors
+    "TenderlyQuotaExceededError",
+    "sanitize_rpc_url",
+    "_sanitize_rpc_url",
+    # Rate limiting
+    "RPCRateLimiter",
+    "RateLimitedEth",
+    "RateLimitedWeb3",
+    "get_rate_limiter",
+    # Models
+    "SupportedChain",
+    "Gnosis",
+    "Ethereum",
+    "Base",
+    "SupportedChains",
+    # Interface
+    "ChainInterface",
+    "DEFAULT_RPC_TIMEOUT",
+    # Manager
+    "ChainInterfaces",
+    # Types
+    "T",
+]