Server-side SDK Pydantic v2 Upgrade

This guide provides information about the Pydantic v2 upgrade for the Server-side Python SDKs for developer-controlled wallets, user-controlled wallets, and Contracts. Pydantic is a Python library for data modeling and validation that uses type hints to enforce structure, parse input, and serialize output.

As of version 9.0.0, the Server-side Circle SDKs are upgrading to Pydantic v2 because the new pydantic-core package is built with Rust and delivers significant performance improvements, better correctness, and more consistent classes, methods, decorators and settings.

If you are using the Circle Python SDK and don't want to migrate your code, you should not upgrade your SDK version past major version 8. Version 8 is in maintenance mode and will only receive essential updates such as fixes for critical security flaws.

If you want to upgrade to major version 9 and above, you may need to make some changes to your code. Review the following sections to see if you are affected.

Unless noted in the following section, function signatures in the Python SDK are unchanged, including:

• API methods
• Core features such as wallet creation and transaction processing

For example, the following usage is unaffected between versions 8 and 9 of the SDK:

from circle.web3.developer_controlled_wallets.api.wallets_api import WalletsApi
from circle.web3.developer_controlled_wallets.models.create_wallet_request import CreateWalletRequest
from circle.web3.developer_controlled_wallets.models.blockchain import Blockchain
from circle.web3.developer_controlled_wallets.models.account_type import AccountType
# These patterns are NOT affected
api_instance = WalletsApi(api_client=client)
request = CreateWalletRequest(
      blockchains=[Blockchain.ETH_MINUS_SEPOLIA],
      wallet_set_id="550e8400-e29b-41d4-a716-446655440002",
      account_type=AccountType.SCA,
      count=1
  )
response = api_instance.create_wallet(request)
wallet_id = response.data.wallet.actual_instance.id
result = api_instance.get_wallet(id=wallet_id)

The method names of model serialization methods that convert between model objects and data formats are changing to match the Pydantic v2 naming pattern. Deserialization methods are typically used to build API request payloads, where serialization methods are used to parse API responses:

• model.from_dict(): deserialize a Python dictionary into a model instance
• model.from_json(): deserialize a JSON string into a model instance
• model.to_dict(): serialize a model instance to a Python dictionary
• model.to_json(): serialize a model instance to a JSON string

The following example shows how to use the new model serialization methods:

from circle.web3.developer_controlled_wallets.models.eoa_wallet import EOAWallet
from circle.web3.developer_controlled_wallets.models.blockchain import Blockchain
from circle.web3.developer_controlled_wallets.models.custody_type import CustodyType
from circle.web3.developer_controlled_wallets.models.wallet_state import WalletState


wallet_model = EOAWallet(
    id="550e8400-e29b-41d4-a716-446655440009",
    address="0x9876543210fedcba9876543210fedcba98765432",
    blockchain=Blockchain.ETH_MINUS_SEPOLIA,
    custody_type=CustodyType.DEVELOPER,
    state=WalletState.LIVE,
    wallet_set_id="550e8400-e29b-41d4-a716-446655440002",
    account_type="EOA",
    create_date="2023-01-01T10:00:00Z",
    update_date="2023-01-01T11:00:00Z"
)


wallet_dict = wallet_model.to_dict()
wallet_json = wallet_model.to_json()
wallet_from_dict = EOAWallet.from_dict(wallet_dict)
wallet_from_json = EOAWallet.from_json(wallet_json)