agentarc 0.1.0__tar.gz

agentarc-0.1.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes to AgentArc will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-02
+
+### 🎉 Initial Release
+
+First stable release of AgentArc - A comprehensive security and policy enforcement layer for AI blockchain agents.
+
+### ✨ Features
+
+#### Core Security Pipeline
+- **Multi-Stage Validation Pipeline**: 4-stage validation (Intent Judge → Policy Validation → Simulation → LLM Analysis)
+- **Zero Agent Modifications**: Pure wrapper pattern for seamless AgentKit integration
+- **3-Line Integration**: Simple API for wrapping any wallet provider
+
+#### Policy Engine (7 Policy Types)
+- **ETH Value Limit**: Prevent large ETH transfers per transaction
+- **Address Denylist**: Block transactions to sanctioned/malicious addresses
+- **Address Allowlist**: Whitelist mode - only allow pre-approved addresses
+- **Per-Asset Limits**: Token-specific spending limits (USDC, DAI, etc.)
+- **Token Amount Limit**: Global ERC20 token transfer limits
+- **Gas Limit**: Prevent expensive transactions
+- **Function Allowlist**: Only allow specific function calls
+
+#### Transaction Simulation
+- **Tenderly Integration**: Advanced simulation with full execution traces
+- **Asset Change Tracking**: Monitor balance changes before execution
+- **Gas Estimation**: Accurate gas predictions
+- **Revert Detection**: Catch failures before broadcasting
+- **Detailed Trace Output**: Optional `print_trace` for debugging
+
+#### Honeypot Detection (Stage 3.5)
+- **Automatic Buy/Sell Testing**: Simulates token purchase then sale
+- **Zero Manual Blacklisting**: Detects unknown honeypots via simulation
+- **Transfer Event Validation**: Verifies actual token movement
+- **Balance Verification**: Ensures balance changes match expectations
+- **Known Token Whitelist**: Skips checks for WETH, USDC, DAI, etc.
+
+#### LLM-based Security Analysis (Stage 4)
+- **AI-Powered Threat Detection**: GPT-4/Claude analysis of transactions
+- **Pattern Recognition**: Detects hidden approvals, unusual fund flows, reentrancy
+- **Risk Scoring**: Confidence levels and risk ratings (LOW/MEDIUM/HIGH/CRITICAL)
+- **Configurable Thresholds**: Block at 70%, warn at 40% (customizable)
+- **Multiple Providers**: Support for OpenAI and Anthropic
+
+#### Logging & Observability
+- **Three Logging Levels**: minimal, info, debug
+- **Structured Output**: Clear stage-by-stage validation results
+- **Asset Change Reporting**: Show balance changes inline
+- **Error Context**: Detailed failure reasons and recommendations
+
+#### Examples & Documentation
+- **Basic Usage Example**: Mock wallet demonstration
+- **OnChain Agent**: Production-ready AgentKit chatbot
+- **Autonomous Portfolio Agent**: AI portfolio manager with honeypot protection
+- **Comprehensive README**: Complete setup and configuration guide
+- **Policy Templates**: Ready-to-use YAML configurations
+
+### 🛠️ Technical Implementation
+
+#### Architecture
+- **PolicyEngine**: Core validation orchestrator
+- **PolicyWalletProvider**: Transparent wallet wrapper
+- **CalldataParser**: ABI decoding for ERC20 and custom functions
+- **TenderlySimulator**: Advanced simulation client
+- **LLMJudge**: AI security analysis engine
+- **Rule Validators**: Modular policy enforcement
+
+#### Compatibility
+- ✅ CDP EVM Wallet Provider
+- ✅ CDP Smart Wallet Provider
+- ✅ Ethereum Account Wallet Provider
+- ✅ Base, Base Sepolia, Ethereum Mainnet, Arbitrum, Optimism
+
+### 📦 Dependencies
+
+#### Required
+- Python 3.10+
+- web3.py
+- pyyaml
+- cdp-sdk (for CDP wallet integration)
+
+#### Optional
+- requests (for Tenderly simulation)
+- openai / anthropic (for LLM validation)
+
+### 🔧 Configuration
+
+Default `policy.yaml` includes:
+- ETH limit: 1 ETH per transaction
+- Per-asset limits for USDC (10) and DAI (100)
+- Gas limit: 500k
+- Simulation enabled
+- LLM validation disabled by default
+
+### 🐛 Known Issues
+
+- None reported in initial release
+
+### 📝 Breaking Changes
+
+- N/A (initial release)
+
+### 🔒 Security
+
+- All transactions validated before execution
+- No credentials stored in logs
+- Simulation uses read-only `eth_call`
+- Tenderly API keys required for advanced features
+
+### 📚 Documentation
+
+- Comprehensive README with examples
+- Inline code documentation
+- Example projects with setup guides
+- Policy configuration templates

agentarc-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,209 @@
+# Contributing to AgentARC
+
+Thank you for your interest in contributing to AgentARC! This document provides guidelines for contributing to the project.
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10 or higher
+- pip or poetry
+
+### Installation for Development
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/agentarc.git
+cd agentarc
+
+# Install in editable mode with development dependencies
+pip install -e ".[dev]"
+
+# Or with poetry
+poetry install --with dev
+```
+
+## Project Structure
+
+```
+agentarc/
+├── agentarc/           # Main package source code
+│   ├── __init__.py        # Package exports
+│   ├── __main__.py        # CLI entry point
+│   ├── policy_engine.py   # Core validation engine
+│   ├── wallet_wrapper.py  # Wallet provider wrapper
+│   ├── calldata_parser.py # Transaction parsing
+│   ├── simulator.py       # Transaction simulation
+│   ├── logger.py          # Logging system
+│   └── rules/             # Policy validators
+│       ├── __init__.py
+│       └── validators.py  # All policy validators
+├── tests/                 # Test suite
+├── examples/              # Usage examples
+├── docs/                  # Documentation
+└── pyproject.toml         # Package configuration
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+cd tests
+python test_complete_system.py
+
+# Run specific test
+python test_fix.py
+```
+
+### Writing Tests
+
+When adding new features, please include tests:
+
+1. Create test file in `tests/`
+2. Test all success and failure cases
+3. Verify logging output
+4. Check edge cases
+
+## Code Style
+
+- Follow PEP 8 style guidelines
+- Use type hints where applicable
+- Write docstrings for all public functions and classes
+- Keep functions focused and single-purpose
+
+### Example
+
+```python
+def validate_transaction(self, tx: Dict[str, Any], from_address: str) -> tuple[bool, str]:
+    """
+    Validate transaction against all configured policies.
+
+    Args:
+        tx: Transaction dictionary with to, value, data, etc.
+        from_address: Sender address for simulation
+
+    Returns:
+        Tuple of (passed: bool, reason: str)
+    """
+    # Implementation
+    pass
+```
+
+## Adding New Policy Types
+
+To add a new policy validator:
+
+1. Create validator class in `agentarc/rules/validators.py`
+2. Inherit from `PolicyValidator` base class
+3. Implement `validate()` method
+4. Register in `PolicyEngine._create_validators()`
+5. Add configuration example to default policy.yaml
+6. Write tests
+7. Update documentation
+
+### Example
+
+```python
+class MyCustomValidator(PolicyValidator):
+    """Description of what this validator does"""
+
+    def validate(self, parsed_tx: ParsedTransaction) -> ValidationResult:
+        if not self.enabled:
+            return ValidationResult(passed=True)
+
+        # Your validation logic here
+        if some_condition:
+            return ValidationResult(
+                passed=False,
+                reason="Description of why it failed",
+                rule_name="my_custom_rule"
+            )
+
+        return ValidationResult(passed=True)
+```
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Update documentation
+6. Run tests to ensure they pass
+7. Commit your changes (`git commit -m 'Add amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+### Pull Request Guidelines
+
+- Provide a clear description of the changes
+- Reference any related issues
+- Include test coverage for new features
+- Update CHANGELOG.md
+- Ensure all tests pass
+- Follow existing code style
+
+## Documentation
+
+When adding new features:
+
+1. Update README.md if needed
+2. Add examples to `examples/`
+3. Update CHANGELOG.md
+4. Add inline code documentation
+5. Update configuration examples
+
+## Reporting Issues
+
+### Bug Reports
+
+Include:
+- Clear description of the issue
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- AgentARC version
+- Python version
+- Error messages/logs
+
+### Feature Requests
+
+Include:
+- Clear description of the feature
+- Use case / motivation
+- Proposed implementation (if any)
+- Examples
+
+## Code of Conduct
+
+### Our Standards
+
+- Be respectful and inclusive
+- Focus on constructive feedback
+- Accept differing viewpoints
+- Prioritize community benefit
+
+### Unacceptable Behavior
+
+- Harassment or discriminatory language
+- Personal attacks
+- Trolling or insulting comments
+- Publishing private information
+
+## Questions?
+
+- Open an issue for questions
+- Check existing documentation
+- Review examples in `examples/`
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to AgentARC! 🎉

agentarc-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Galaar Authors
+
+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.
+
+---
+Portions of this software were originally released under the MIT License, Copyright (c) 2025 BuildBear Labs.

agentarc-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+# Include documentation
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+
+# Include package data
+recursive-include agentarc *.py
+
+# Exclude compiled files
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude *.so
+global-exclude .DS_Store