ethswarm-deployments

Python library for managing Ethswarm smart contract deployment data across all versions and networks.

Overview

This library ingests Swarm smart contract deployment data from the ethersphere/storage-incentives GitHub repository and provides a clean Python interface for accessing deployment information across:

• Multiple contract versions (v0.4.0 through v0.9.4+)
• Multiple networks (mainnet, testnet)
• Both legacy and hardhat-deploy format contracts

Features

• Multi-network support: Query deployments on Gnosis Chain mainnet and Sepolia testnet
• Version tracking: Access any version of deployed contracts
• Backward compatible: Supports both legacy (staking) and canonical (StakeRegistry) contract names
• Persistent caching: Local cache with block timestamp optimization
• Rich metadata: Includes ABIs, bytecode, constructor args, and transaction hashes

Installation

pip install ethswarm-deployments

Quick Start

from ethswarm_deployments import DeploymentManager

# Initialize (uses cached data at ./.ethswarm-deployments/deployments.json)
mgr = DeploymentManager()

# Use a shared cache in your home directory instead of the project directory
mgr = DeploymentManager(location="user")  # ~/.cache/ethswarm-deployments

# Build the cache from GitHub on first use if it is missing
# (requires an RPC URL in the environment; see "Regenerating Cache" below)
mgr = DeploymentManager(auto_regenerate=True)

# Get latest deployment on mainnet (default)
deployment = mgr.deployment("StakeRegistry")
print(f"StakeRegistry at {deployment.address}")

# Get specific version on testnet
deployment = mgr.deployment("Redistribution", version="v0.9.2", network="testnet")

# List all versions
versions = mgr.versions()

# Get all deployments of a contract across versions
all_staking = mgr.all_deployments("StakeRegistry")

Cache Location

By default the cache lives in a project-local ./.ethswarm-deployments directory, so nothing is written to your home directory unless you ask for it.

To use a shared cache in your XDG cache home (~/.cache/ethswarm-deployments, or $XDG_CACHE_HOME/ethswarm-deployments):

from ethswarm_deployments import DeploymentManager

mgr = DeploymentManager(location="user")

Resolution precedence for the cache directory (first match wins):

1. An explicit cache_dir= path argument.
2. An explicit location= argument ("project" or "user").
3. The ETHSWARM_DEPLOYMENTS_CACHE environment variable — set it to project, user, or a directory path.
4. The default project location (./.ethswarm-deployments).

Regenerating Cache

If the cache is missing, DeploymentManager() raises CacheNotFoundError by default. Pass auto_regenerate=True to build it on demand instead (this requires an RPC URL in the environment and may take a while):

mgr = DeploymentManager(auto_regenerate=True)

The cache can also be regenerated explicitly from GitHub:

from ethswarm_deployments import regenerate_from_github

# Regenerate cache (requires RPC endpoints)
regenerate_from_github(
    mainnet_rpc_url="https://rpc.gnosischain.com",
    testnet_rpc_url="https://ethereum-sepolia-rpc.publicnode.com"
)

License

MIT