Metadata-Version: 2.4
Name: iwa
Version: 0.6.1
Summary: A secure, modular, and plugin-based framework for crypto agents and ops
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: 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
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
Requires-Dist: multiformats>=0.3.1
Requires-Dist: requests>=2.32.0
Requires-Dist: fastmcp>=3.0.0
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/main/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.

- **MCP Server**: Expose all wallet and Olas operations as [Model Context Protocol](https://modelcontextprotocol.io) tools, enabling AI agents (Claude, Cursor, etc.) to interact with the blockchain directly.

- **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/          # Blockchain interface with rate limiting
│   ├── services/       # Service layer (accounts, balances, transactions)
│   └── contracts/      # Contract abstractions (ERC20, Safe)
├── mcp/                # MCP server (Model Context Protocol)
│   └── tools.py        # 23 core wallet tools
├── plugins/            # Protocol integrations
│   ├── gnosis/         # Safe multisig and CowSwap DEX
│   └── olas/           # Olas Registry, Services, Staking + 17 MCP tools
├── 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

# Testing mode (default: true uses Tenderly test RPCs)
TESTING=false

# 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

# Start MCP server (for AI agent integration)
iwa mcp --transport sse --port 18080
```

### MCP Agent Integration

The MCP server exposes 40 tools covering wallet operations, Olas service management, and staking. Example agent scripts for Claude, OpenAI GPT, and Gemini are in `scripts/mcp/`:

```bash
# Start the MCP server
iwa mcp --transport sse --port 18080

# Claude (pip install anthropic)
export ANTHROPIC_API_KEY=sk-ant-...
python scripts/mcp/claude_agent.py

# OpenAI GPT (pip install openai)
export OPENAI_API_KEY=sk-...
python scripts/mcp/openai_agent.py

# Gemini (pip install google-generativeai)
export GOOGLE_API_KEY=AIza...
python scripts/mcp/gemini_agent.py
```

See [MCP documentation](docs/interfaces/mcp.md) for the full tool reference and Claude Desktop configuration.

### Running Tests

```bash
just test
```

### Security Checks

```bash
just security      # Runs gitleaks, bandit, and pip-audit
just wallet-check  # Verifies password, keys, and mnemonic integrity
```

### 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.
