foundry.forge

Documentation for eth_defi.foundry.forge Python module.

Forge smart contract development toolchain integration.

  • Compile and deploy smart contracts using Forge

  • Verify smart contracts on Etherscan, Blockscout, Sourcify, or OKLink

  • See Foundry book for more information.

Module Attributes

DEFAULT_TIMEOUT

Crash unless forge completes in 4 minutes

Functions

deploy_contract_with_forge(web3, ...[, ...])

Deploy and verify smart contract with Forge.

Exceptions

ForgeFailed

Forge command failed.
DEFAULT_TIMEOUT = 240

Crash unless forge completes in 4 minutes

exception ForgeFailed

Bases: Exception

Forge command failed.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

deploy_contract_with_forge(web3, project_folder, contract_file, contract_name, deployer, constructor_args=None, etherscan_api_key=None, verifier=None, verifier_url=None, register_for_tracing=True, timeout=240, wait_for_block_confirmations=0, verify_delay=20, verify_retries=9, verbose=False, contract_file_out=None)

Deploy and verify smart contract with Forge.

  • The smart contracts must be developed with Foundry tool chain and its forge command

  • Uses Forge to verify the contract on Etherscan

  • For normal use deploy_contract() is much easier

Example:

guard, tx_hash = deploy_contract_with_forge(
    web3,
    CONTRACTS_ROOT / "guard",  # Foundry projec path
    "GuardV0.sol",  # src/GuardV0.sol
    f"GuardV0",  # GuardV0 is the smart contract name
    deployer,  # Local account with a private key we use for the deployment
    etherscan_api_key=etherscan_api_key,  # Etherscan API key we use for the verification
)
logger.info("GuardV0 is %s deployed at %s", guard.address, tx_hash.hex())

# Test the deployed contract
assert guard.functions.getInternalVersion().call() == 1

Assumes standard Foundry project layout with foundry.toml, src and out.

See

Parameters

  • web3 (web3.main.Web3) – Web3 instance

  • deployer (eth_defi.hotwallet.HotWallet | eth_account.signers.local.LocalAccount) –

    Deployer tracked as a hot wallet.

    We need to be able to manually track the nonce across multiple contract deployments.

  • project_folder (pathlib.Path) – Foundry project with foundry.toml in the root.

  • contract_file (pathlib.Path | str) –

    Contract path relative to the project folder.

    E.g. TermsOfService.sol.

  • contract_name (str) –

    The smart contract name within the file.

    E.g. TermsOfService.

  • constructor_args (list[str] | None) –

    Other arguments to pass to the contract’s constructor.

    Need to be able to stringify these for forge.

  • etherscan_api_key (str | None) –

    API key for Etherscan-compatible verification services.

    Required when using verifier="etherscan" or verifier="oklink".

    Not needed for Blockscout or Sourcify.

    E.g. 3F3H8…..

  • verifier (Optional[Literal['etherscan', 'blockscout', 'sourcify', 'oklink']]) –

    The contract verification provider to use.

    Supported values:

    • "etherscan": Etherscan and compatible explorers (requires API key)

    • "blockscout": Blockscout explorers (requires verifier_url)

    • "sourcify": Sourcify verification (no API key required)

    • "oklink": OKLink explorer (requires API key)

    If None but etherscan_api_key is provided, defaults to "etherscan" for backward compatibility.

  • verifier_url (str | None) –

    Custom verifier URL for Blockscout or other custom verification endpoints.

    Required when verifier="blockscout".

    Example: "https://base.blockscout.com/api/"

  • register_for_tracing –

    Make the symbolic contract information available on web3 instance.

    See get_contract_registry()

  • wait_for_block_confirmations – Currently not used.

  • verbose – Try to be extra verbose with Forge output to pin point errors

  • contract_file_out (pathlib.Path | str | None) –

Raises

ForgeFailed –

In the case we could not deploy the contract.

  • Running forge failed

  • Transaction could not be confirmed

Returns

Contract and deployment tx hash.

Return type

Tuple[web3.contract.contract.Contract, hexbytes.main.HexBytes]