AgentARC

# AgentARC - Security Layer for AI Blockchain Agents

[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](https://github.com/galaar-org/AgentARC)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![GitHub](https://img.shields.io/badge/github-galaar-org)](https://github.com/galaar-org)
[![PyPI version](https://img.shields.io/pypi/v/agentarc.svg)](https://pypi.org/project/agentarc/)

**Advanced security and policy enforcement layer for AI blockchain agents with multi-stage validation, transaction simulation, and threat detection across DeFi + smart-contract attack surfaces, with LLM-based risk analysis.**

---

## What is AgentARC?

AgentARC sits between your AI agent and the blockchain. Every transaction the agent wants to send passes through a 4-stage validation pipeline **before signing** — catching threats that would otherwise reach the chain.

```
Agent wants to send a transaction
          │
          ▼
┌─────────────────────────────────────┐
│         AgentARC Pipeline           │
│                                     │
│  Stage 1: Intent Analysis           │
│  → parse calldata, identify action  │
│                                     │
│  Stage 2: Policy Validation         │
│  → spending limits, allow/denylists │
│                                     │
│  Stage 3: Transaction Simulation    │
│  → Tenderly sandbox test            │
│                                     │
│  Stage 3.5: Honeypot Detection      │
│  → test buy + sell before buying    │
│                                     │
│  Stage 4: LLM Security Analysis     │
│  → AI threat detection (optional)   │
└──────────────┬──────────────────────┘
               │
      BLOCKED ─┤─ APPROVED
               │
               ▼
        Wallet executes
   (EOA / ERC-4337 / Safe / CDP)
```

Threats it catches:

- Unauthorized fund transfers and unexpected value movement
- Hidden or unlimited token approvals and allowance abuse
- Malicious smart contracts and hostile call chains
- Token traps (honeypots, sell-blocks, malicious fee mechanics)
- Liquidity and price-manipulation patterns
- Reentrancy-style execution hazards
- Suspicious fund-flow anomalies

---

## Key Features

- **Multi-Stage Validation Pipeline** — Intent → Policies → Simulation → Threat Detection
- **7 Policy Types** — ETH limits, address allow/denylists, per-asset limits, gas limits, function allowlists
- **Universal Wallet Support** — EOA, ERC-4337 smart wallets, Safe multisig, Coinbase CDP
- **Framework Adapters** — OpenAI SDK, LangChain, AgentKit — same API for all
- **Transaction Simulation** — Tenderly integration for full execution traces
- **Honeypot Detection** — Automatically test buy + sell before any token purchase
- **LLM Security Analysis** — AI-powered malicious pattern detection (optional)
- **Interactive CLI Wizard** — Scaffold a new project in under a minute

---

## Quick Start

### Installation

```bash
# Core install (EOA + CDP wallets, no framework adapters)
pip install agentarc

# With OpenAI SDK support
pip install agentarc[openai]

# With LangChain support
pip install agentarc[langchain]

# With ERC-4337 smart wallet support
pip install agentarc[smart-wallets]

# With Safe multisig support
pip install agentarc[safe]

# Everything
pip install agentarc[all]
```

### Scaffold a new project (recommended)

The interactive CLI wizard creates a complete project for your chosen wallet type and framework:

```bash
agentarc setup
```

```
==================================================
          AgentARC Setup Wizard
==================================================

Is this for an existing or new project? [existing/new]: new
Enter your project name [my-secure-agent]: my-agent
Choose your agent framework [openai/langchain]: openai
Choose wallet type [eoa/erc4337/safe/cdp]: eoa
Choose network (number or name) [1]: 1   (Base Sepolia)
Select policy templates: 1,2             (Spending Limits + Denylist)

Project created at: ./my-agent

Files created:
  agent.py            <- EOA + OPENAI agent
  policy.yaml         <- Off-chain policy config
  .env.example        <- Environment variables for EOA
  requirements.txt    <- Python dependencies
  .gitignore

Next steps:
  cd my-agent
  cp .env.example .env
  # Add your keys to .env
  pip install -r requirements.txt
  python agent.py
```

The wizard supports all combinations of wallet × framework and generates the correct `agent.py`, `policy.yaml`, `.env.example`, and `requirements.txt` for each.

---

## Wallet Support

AgentARC works with four wallet types. Your agent code changes by **one line**:

```python
from agentarc import WalletFactory, PolicyWallet, OpenAIAdapter

# EOA — normal private key wallet
wallet = WalletFactory.from_private_key(private_key, rpc_url)

# ERC-4337 — smart contract wallet, transactions go through a bundler
wallet = WalletFactory.from_erc4337(owner_key, bundler_url, rpc_url)

# Safe — Gnosis Safe multisig wallet
wallet = WalletFactory.from_safe(safe_address, signer_key, rpc_url)

# CDP — Coinbase Developer Platform wallet
wallet = WalletFactory.from_cdp(cdp_provider)

# Everything below is identical for all four wallet types
policy_wallet = PolicyWallet(wallet, config_path="policy.yaml")
adapter = OpenAIAdapter()
tools = adapter.create_all_tools(policy_wallet)
```

### Wallet type comparison

| | EOA | ERC-4337 | Safe | CDP |
|--|--|--|--|--|
| Wallet address | key address | smart contract | safe contract | CDP managed |
| Gas sponsorship | no | yes (Paymaster) | no | no |
| Multi-signature | no | no | yes | no |
| Requires bundler | no | yes | no | no |
| Best for | testing, simple agents | production agents | teams, DAOs | AgentKit |

### ERC-4337 specifics

The smart account address is **counterfactual** — derived from your owner key before the contract is deployed. Fund the smart account address and it auto-deploys on first transaction.

```python
wallet = WalletFactory.from_erc4337(
    owner_key=os.environ["OWNER_PRIVATE_KEY"],
    bundler_url="https://api.pimlico.io/v2/84532/rpc?apikey=...",
    rpc_url="https://sepolia.base.org",
)

wallet.get_address()        # smart account address (holds funds)
wallet.get_owner_address()  # owner EOA address (signs UserOps)
wallet.is_deployed()        # False until first transaction
```

Get a free bundler URL at [pimlico.io](https://pimlico.io) or [alchemy.com](https://alchemy.com).

### Safe specifics

```python
wallet = WalletFactory.from_safe(
    safe_address=os.environ["SAFE_ADDRESS"],
    signer_key=os.environ["SIGNER_PRIVATE_KEY"],
    rpc_url="https://sepolia.base.org",
    auto_execute=True,  # execute immediately if threshold == 1
)

wallet.get_address()      # Safe contract address (holds funds)
wallet.get_owner_address() # signer EOA address
wallet.get_threshold()    # number of required signatures
wallet.get_owners()       # list of all Safe owner addresses
```

Deploy a Safe for free at [app.safe.global](https://app.safe.global).

---

## Framework Support

AgentARC has adapters for OpenAI SDK and LangChain. Both work identically with any wallet type.

### OpenAI SDK

```python
from agentarc import WalletFactory, PolicyWallet
from agentarc.frameworks import OpenAIAdapter
from openai import OpenAI

wallet = WalletFactory.from_private_key(os.environ["PRIVATE_KEY"], os.environ["RPC_URL"])
policy_wallet = PolicyWallet(wallet, config_path="policy.yaml")

adapter = OpenAIAdapter()
tools = adapter.create_all_tools(policy_wallet)
# tools: send_transaction, get_wallet_balance, get_wallet_info, validate_transaction

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=tools)
tool_results = adapter.process_tool_calls(response, policy_wallet)
```

### LangChain + LangGraph

```python
from agentarc import WalletFactory, PolicyWallet
from agentarc.frameworks import LangChainAdapter
from langchain_op

[truncated…]