chore: migration guide for upgrading to latest 0.6.0 version

README.md

@@ -22,6 +22,7 @@
 
 ## Table of Contents
 
+- [Table of Contents](#table-of-contents)
 - [📖 Overview](#-overview)
 - [🚀 Quickstart](#-quickstart)
   - [Node.js](#nodejs)
@@ -30,9 +31,15 @@
 - [🤝 Contributing](#-contributing)
 - [📜 Documentation](#-documentation)
 - [🌙 Nightly Builds](#-nightly-builds)
-- [🚨 Security and bug reports](#-security-and-bug-reports)
+  - [Typescript](#typescript)
+  - [Python](#python-1)
+- [🚨 Security and Bug Reports](#-security-and-bug-reports)
 - [📧 Contact](#-contact)
 - [🔗 Supported Wallets, Protocols, and Frameworks](#-supported-wallets-protocols-and-frameworks)
+  - [Wallets](#wallets)
+  - [Protocols](#protocols)
+  - [Frameworks](#frameworks)
+  - [Networks](#networks)
 - [📝 License](#-license)
 - [🔒 Legal and Privacy](#-legal-and-privacy)
 
@@ -194,6 +201,8 @@ agentkit/
 ## 📜 Documentation
 
 - [AgentKit Documentation](https://docs.cdp.coinbase.com/agentkit/docs/welcome)
+- Migration Guides
+  - [Upgrading from 0.4.0 to 0.6.0](./python/coinbase-agentkit/docs/upgrading-0.4-to-0.6.md)
 - Python API References
   - [AgentKit](https://coinbase.github.io/agentkit/coinbase-agentkit/python/index.html)
   - [AgentKit Langchain Extension](https://coinbase.github.io/agentkit/coinbase-agentkit-langchain/python/index.html)
@@ -309,4 +318,4 @@ AgentKit is licensed under the [Apache-2.0](LICENSE.md) license.
 
 ## 🔒 Legal and Privacy
 
-The AgentKit software is novel and experimental, and is therefore provided on an AS-IS basis. The software is intended to be used only for the purposes of assisting with designing blockchain transactions and enabling other API integrations using natural language inputs, and is not intended to provide (i) an offer, or solicitation of an offer, to invest in, or to buy or sell, any interests or shares, or to participate in any investment or trading strategy, (ii) accounting, legal, tax advice, investment recommendations or other professional advice or (iii) an official statement of Coinbase. Acts proposed or performed by an agent through AgentKit software are NOT acts of Coinbase. You should consult with a professional advisor before making any decisions based on the information provided by the software. You are not permitted to use the proceeds of loans or credit to purchase digital assets on or through coinbase.com, Coinbase's APIs, the Coinbase mobile application, or any other Coinbase website or product, including AgentKit. No representation or warranty is made, expressed or implied, with respect to the accuracy, completeness, reliability, security, or suitability of the software or to any information provided in connection with the software. The risk of loss through use of the software can be substantial, and you assume any and all risks of loss and liability. The software may produce output that is inaccurate, incorrect, unpredictable or undesirable, and it is the user’s exclusive responsibility to evaluate the output and the use-case and determine whether it is appropriate. The right to use the software is contingent on your agreement to the [CDP Terms of Service](https://www.coinbase.com/legal/developer-platform/terms-of-service) (except to the extent it conflicts with the Apache-2.0 license).
+The AgentKit software is novel and experimental, and is therefore provided on an AS-IS basis. The software is intended to be used only for the purposes of assisting with designing blockchain transactions and enabling other API integrations using natural language inputs, and is not intended to provide (i) an offer, or solicitation of an offer, to invest in, or to buy or sell, any interests or shares, or to participate in any investment or trading strategy, (ii) accounting, legal, tax advice, investment recommendations or other professional advice or (iii) an official statement of Coinbase. Acts proposed or performed by an agent through AgentKit software are NOT acts of Coinbase. You should consult with a professional advisor before making any decisions based on the information provided by the software. You are not permitted to use the proceeds of loans or credit to purchase digital assets on or through coinbase.com, Coinbase's APIs, the Coinbase mobile application, or any other Coinbase website or product, including AgentKit. No representation or warranty is made, expressed or implied, with respect to the accuracy, completeness, reliability, security, or suitability of the software or to any information provided in connection with the software. The risk of loss through use of the software can be substantial, and you assume any and all risks of loss and liability. The software may produce output that is inaccurate, incorrect, unpredictable or undesirable, and it is the user's exclusive responsibility to evaluate the output and the use-case and determine whether it is appropriate. The right to use the software is contingent on your agreement to the [CDP Terms of Service](https://www.coinbase.com/legal/developer-platform/terms-of-service) (except to the extent it conflicts with the Apache-2.0 license).

python/coinbase-agentkit/docs/upgrading-0.4-to-0.6.md

@@ -0,0 +1,179 @@
+# Upgrading from AgentKit 0.4.0 to 0.6.0
+
+This guide covers the migration process from AgentKit 0.4.0 to 0.6.0, with a focus on breaking changes and wallet compatibility.
+
+## Overview
+
+AgentKit 0.6.0 introduces significant changes to wallet management and API structure. The most notable changes affect:
+- Wallet provider classes and initialization
+- Environment variable naming
+- Wallet data storage format
+- Action provider functions
+
+## Breaking Changes
+
+### 1. Wallet Provider Updates
+```python
+# Before (0.4.0)
+from coinbase_agentkit import CdpWalletProvider, CdpWalletProviderConfig
+
+# After (0.6.0)
+from coinbase_agentkit import CdpEvmServerWalletProvider, CdpEvmServerWalletProviderConfig
+```
+
+### 2. Environment Variables
+```bash
+# New variables (0.6.0)
+export CDP_API_KEY_ID="your_key_id"           # Previously CDP_API_KEY_NAME
+export CDP_API_KEY_SECRET="your_private_key"  # Previously CDP_API_KEY_PRIVATE_KEY
+export CDP_WALLET_SECRET="your_wallet_secret" # New in 0.6.0
+```
+
+To obtain your `CDP_WALLET_SECRET`:
+1. Go to [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com)
+2. Click "Wallets" in the left navigation bar
+3. Select "Wallet API"
+4. Click "Generate Wallet Secret"
+
+This wallet secret is required for the new wallet provider in 0.6.0.
+
+### 3. Removed Functions
+The following functions have been removed:
+- `CdpWalletActionProvider_deploy_contract`
+- `CdpWalletActionProvider_deploy_nft`
+- `CdpWalletActionProvider_deploy_token`
+- `CdpWalletActionProvider_trade`
+
+## Wallet Compatibility
+
+### Data Structure Changes
+AgentKit 0.6.0 uses a different wallet data format:
+
+```json
+// 0.4.0 Format
+{
+  "default_address_id": "0x1234...",
+  "wallet_secret": "encrypted_data",
+  "account_data": { ... }
+}
+
+// 0.6.0 Format
+{
+  "default_address_id": "0x5678...",
+  "wallet_secret": "new_encrypted_format",
+  "provider_specific_data": { ... }
+}
+```
+
+### Migration Script
+Here's an example script to handle wallet compatibility issues:
+
+```python
+from coinbase_agentkit import CdpEvmServerWalletProvider, CdpEvmServerWalletProviderConfig
+import argparse
+import json
+import os
+
+def check_wallet_compatibility(wallet_address: str, config: dict) -> bool:
+    # Check if wallet is valid in 0.6.0
+    wallet_config = CdpEvmServerWalletProviderConfig(
+        api_key_id=config["cdp_api_key_id"],
+        api_key_secret=config["cdp_api_key_secret"],
+        network_id="base-mainnet",
+        address=wallet_address
+    )
+
+    try:
+        CdpEvmServerWalletProvider(wallet_config)
+        return True
+    except Exception as e:
+        if "not found" in str(e).lower():
+            return False
+        return True  # Assume valid for other errors
+
+def fix_invalid_wallets(wallet_file: str, dry_run: bool = True):
+    """Fix invalid wallet addresses in the wallet data file."""
+    with open(wallet_file, 'r') as f:
+        wallet_data = json.load(f)
+
+    config = {
+        "cdp_api_key_id": os.getenv("CDP_API_KEY_ID"),
+        "cdp_api_key_secret": os.getenv("CDP_API_KEY_SECRET")
+    }
+
+    fixed_count = 0
+    for wallet in wallet_data:
+        if not check_wallet_compatibility(wallet["address"], config):
+            print(f"Found invalid wallet: {wallet['address']}")
+            if not dry_run:
+                # Clear wallet data to trigger on-demand creation
+                wallet["address"] = None
+                wallet["provider_specific_data"] = {}
+                fixed_count += 1
+
+    if not dry_run and fixed_count > 0:
+        with open(wallet_file, 'w') as f:
+            json.dump(wallet_data, f, indent=2)
+        print(f"Fixed {fixed_count} invalid wallets")
+    else:
+        print(f"Would fix {fixed_count} wallets (dry run)")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--wallet-file", required=True, help="Path to wallet data file")
+    parser.add_argument("--dry-run", action="store_true", help="Don't make any changes")
+    args = parser.parse_args()
+
+    fix_invalid_wallets(args.wallet_file, args.dry_run)
+```
+
+Save this script as `fix_invalid_wallets.py` and run it:
+```bash
+# First do a dry run to see what would be changed
+python fix_invalid_wallets.py --wallet-file wallets.json --dry-run
+
+# Then run it for real to fix the wallets
+python fix_invalid_wallets.py --wallet-file wallets.json
+```
+
+## Migration Steps
+
+1. Update dependencies:
+   ```bash
+   pip install "coinbase-agentkit>=0.6.0" "coinbase-agentkit-langchain>=0.5.0"
+   ```
+
+2. Update environment variables
+3. Run wallet migration script:
+   ```bash
+   python scripts/fix_invalid_wallets.py --dry-run  # Test first
+   python scripts/fix_invalid_wallets.py            # Apply fixes
+   ```
+
+4. Update imports and function calls
+5. Test wallet functionality
+
+## Common Issues
+
+### Invalid Wallet Addresses
+If you encounter "EVM account not found" errors:
+1. Clear the wallet data to allow on-demand creation
+2. The agent will create a new compatible wallet automatically
+3. Existing balances will be preserved and accessible
+
+### Action Provider Changes
+- Remove any usage of deprecated wallet action providers
+- Use specialized providers for specific actions (deployment, trading)
+- Update function calls to match new signatures
+
+## Best Practices
+
+1. Use on-demand wallet creation instead of pre-storing addresses
+2. Implement proper error handling for wallet operations
+3. Test thoroughly after migration, especially wallet functions
+4. Keep wallet secret management updated to new format
+
+## Additional Resources
+
+- [AgentKit 0.6.0 Release Notes](https://docs.cdp.coinbase.com/agentkit/changelog)
+- [CDP Wallet Documentation](https://docs.cdp.coinbase.com/agentkit/docs/wallet)