<p align="center">
  <img src="./brand/logo-full.png" alt="Vaultfire" width="420" />
</p>

# Vaultfire AgentKit

**On-chain trust infrastructure for [Coinbase AgentKit](https://docs.cdp.coinbase.com/agent-kit/welcome) agents.**

Give your AI agent a verified identity, stake-backed accountability, and on-chain reputation — in 3 lines of code.

```python
from vaultfire_agentkit import vaultfire_action_provider

agentkit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider,
    action_providers=[vaultfire_action_provider()],
))
```

Your agent can now:
- **Register an ERC-8004 identity** — permanent, verifiable agent identity on-chain
- **Stake an Accountability Bond** — put skin in the game to prove trustworthiness
- **Create Partnership Bonds** — mutual trust between collaborating agents
- **Check trust profiles** — verify any agent before interacting
- **Resolve VNS names** — Vaultfire Name Service for agent-readable identities
- **Read reputation scores** — on-chain reputation from verifiable metrics

## Supported Chains

| Chain | Network ID | Contracts |
|-------|-----------|-----------|
| Base | `base-mainnet` | Identity, Bonds, Reputation, VNS |
| Avalanche | `avalanche-mainnet` | Identity, Bonds, Reputation |
| Arbitrum | `arbitrum-mainnet` | Identity, Bonds, Reputation, VNS |
| Polygon | `polygon-mainnet` | Identity, Bonds, Reputation, VNS |

All 103 contracts are verified on their respective block explorers.

## Install

```bash
pip install vaultfire-agentkit
```

Requires `coinbase-agentkit >= 0.1.0`, `web3 >= 6.0.0`, and `pydantic >= 2.0.0`.

## Quick Start

### 1. Register Your Agent

```python
from coinbase_agentkit import (
    AgentKit,
    AgentKitConfig,
    CdpEvmWalletProvider,
    CdpEvmWalletProviderConfig,
    wallet_action_provider,
)
from vaultfire_agentkit import vaultfire_action_provider

# Set up wallet on Base mainnet
wallet_provider = CdpEvmWalletProvider(CdpEvmWalletProviderConfig(
    api_key_id="YOUR_CDP_KEY_ID",
    api_key_secret="YOUR_CDP_KEY_SECRET",
    wallet_secret="YOUR_WALLET_SECRET",
    network_id="base-mainnet",
))

# Create AgentKit with Vaultfire trust actions
agentkit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider,
    action_providers=[
        wallet_action_provider(),
        vaultfire_action_provider(),  # Adds 7 trust actions
    ],
))
```

### 2. Use With LangChain

```python
from langchain_openai import ChatOpenAI
from coinbase_agentkit_langchain import CoinbaseAgentKitToolkit

# Create tools from AgentKit (includes Vaultfire actions)
toolkit = CoinbaseAgentKitToolkit.from_agentkit(agentkit)
tools = toolkit.get_tools()

# The agent can now call:
# - register_agent(name="my-bot", agent_type="autonomous")
# - create_accountability_bond(amount="0.01")
# - create_partnership_bond(partner_address="0x...", amount="0.01")
# - get_trust_profile(agent_address="0x...")
# - get_reputation(agent_address="0x...")
# - resolve_vns(query="my-bot.vns")
# - get_bond(bond_id=1, bond_type="accountability")
```

## Actions Reference

### Write Actions (require gas)

| Action | Description | Parameters |
|--------|-------------|------------|
| `register_agent` | Register an ERC-8004 agent identity | `name`, `agent_type` |
| `create_accountability_bond` | Stake native tokens as accountability | `amount` |
| `create_partnership_bond` | Create mutual trust bond with another agent | `partner_address`, `amount` |

### Read Actions (free)

| Action | Description | Parameters |
|--------|-------------|------------|
| `get_trust_profile` | Full trust profile (identity + reputation + VNS) | `agent_address` |
| `get_reputation` | Reputation score and ratings | `agent_address` |
| `resolve_vns` | Resolve VNS name ↔ address | `query` |
| `get_bond` | Bond details by ID | `bond_id`, `bond_type` |

## How It Works

Vaultfire implements [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004), the first standard for AI agent identity on-chain. When your agent registers through this provider:

1. **Identity** — The agent's wallet address becomes a permanent, verifiable identity in the Vaultfire Identity Registry. Other protocols and agents can look this up.

2. **Accountability** — By staking native tokens (ETH, AVAX, POL) into bonds, the agent puts "skin in the game." Malicious behavior can result in bond slashing.

3. **Reputation** — As the agent operates and receives ratings, it builds an on-chain reputation score that follows it across all 4 chains.

4. **Partnership** — Two agents can create a mutual bond, proving on-chain that they trust each other and are collaborating.

## Testing

```bash
pip install pytest
pytest vaultfire_agentkit/tests/ -v
```

The test suite includes:
- Provider instantiation and action discovery
- Network support validation
- Schema validation for all 7 actions
- Contract address checksum verification
- **Security scan** — automated check for leaked secrets in all source files

## Architecture

```
vaultfire_agentkit/
├── __init__.py                    # Package entry point
├── constants.py                   # Contract addresses and ABIs (public data only)
├── schemas.py                     # Pydantic input schemas
├── vaultfire_action_provider.py   # Main provider (7 actions)
└── tests/
    └── test_vaultfire_provider.py # 33 tests including security scan
```

## Protocol Resources

- **Website:** [theloopbreaker.com](https://theloopbreaker.com)
- **Documentation:** [github.com/Ghostkey316/vaultfire-docs](https://github.com/Ghostkey316/vaultfire-docs)
- **Main Repository:** [github.com/Ghostkey316/ghostkey-316-vaultfire-init](https://github.com/Ghostkey316/ghostkey-316-vaultfire-init)
- **TypeScript SDK:** [`@vaultfire/agent-sdk`](https://www.npmjs.com/package/@vaultfire/agent-sdk)
- **Explorer:** [Vaultfire Explorer](https://github.com/Ghostkey316/vaultfire-explorer)

## Key Protection (VKP)

Agents registered through Vaultfire AgentKit can also protect their private keys with the **Vaultfire Key Protocol (VKP)** — on-chain spending policies, time-limited session keys, and identity-gated key delegation. VKP contracts are deployed on all 4 chains and integrate directly with the ERC-8004 identity layer used by this package.

See [`vaultfire-keyprotocol`](https://github.com/Ghostkey316/vaultfire-keyprotocol) for contracts, Python SDK, and deployment details.

## Security

- All contract addresses are for verified, deployed contracts on public mainnets
- No private keys, API secrets, or sensitive data are included in this package
- Automated security scan runs as part of the test suite
- The Vaultfire Protocol has completed 5 rounds of security auditing with 0 critical, 0 high, 0 medium, and 0 low findings remaining

## License

MIT
