Merge branch 'main' into chore/dust-off

.github/workflows/test.yaml

@@ -52,8 +52,10 @@ jobs:
 
         strategy:
             matrix:
-                os: [ubuntu-latest, macos-latest]   # eventually add `windows-latest`
-                python-version: [3.9, "3.10", "3.11", "3.12", "3.13"]
+                # TODO: Can add macos-latest once https://github.com/ApeWorX/github-action/pull/37
+                #   is released.
+                os: [ubuntu-latest]   # eventually add `windows-latest`
+                python-version: ["3.10", "3.11", "3.12", "3.13"]
 
         steps:
         - uses: actions/checkout@v4
@@ -68,8 +70,16 @@ jobs:
             python -m pip install --upgrade pip
             pip install .[test]
 
+        - name: Ape Set-up
+          uses: ApeWorX/github-action@fix/mkdir-fail
+          with:
+            python-version: ${{ matrix.python-version }}
+
         - name: Run Tests
-          run: pytest -m "not fuzzing" -n 0 -s --cov
+          run: ape test
+          env:
+            WEB3_ALCHEMY_API_KEY: ${{ secrets.WEB3_ALCHEMY_API_KEY }}
+            ETHERSCAN_API_KEY: ${{ secrets.ETHERSCAN_API_KEY }}
 
 # NOTE: uncomment this block after you've marked tests with @pytest.mark.fuzzing
 #    fuzzing:

.pre-commit-config.yaml

@@ -22,13 +22,13 @@ repos:
         additional_dependencies: [flake8-breakpoint, flake8-print, flake8-pydantic, flake8-type-checking]
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.13.0
+    rev: v1.14.1
     hooks:
     -   id: mypy
         additional_dependencies: [types-requests, types-setuptools]
 
 -   repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.19
+    rev: 0.7.21
     hooks:
     -   id: mdformat
         additional_dependencies: [mdformat-gfm, mdformat-frontmatter, mdformat-pyproject]

README.md

@@ -1,6 +1,6 @@
 # Quick Start
 
-Titanoboa integration and pytest runner
+Use Titanoboa as a provider in Ape.
 
 ## Dependencies
 
@@ -28,7 +28,52 @@ python3 setup.py install
 
 ## Quick Usage
 
-TODO: Describe library overview in code
+Use titanoboa as your development or simulation provider (testing).
+For example, run your project's tests using the `--network` flag and `boa` as the name of the provider:
+
+```shell
+ape test --network ethereum:local:boa
+```
+
+Boa works the same as other Ape testing providers such as `ape-foundry` or the Ethereum tester that comes with `ape-test` by default.
+
+### Fork Mode
+
+You can for networks using `ape-titanoba` to simulate actions.
+For example, let's say you are in a console session with mainnet:
+
+```shell
+ape console --network ethereum:mainnet:alchemy
+```
+
+Fork mainnet into `boa` to run simulations:
+
+```python
+from ape import Contract, accounts, networks
+
+with networks.fork():
+    # Reference a contract from Ethereum mainnet in your fork.
+    contract = Contract("0x388C818CA8B9251b393131C08a736A67ccB19297")
+    # Impersonate any relevant accounts needed for the simulation.
+    owner = accounts["0xdb65702a9b26f8a643a31a4c84b9392589e03d7c"]
+    # Attempt to call methods on the contract using the impersonated accounts.
+    contract.recoverERC20("0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84", 10, sender=owner)
+```
+
+You can also connect to a forked-network directly using the `--network` flag:
+
+```shell
+ape console --network ethereum:mainnet-fork:boa
+```
+
+Or in Python:
+
+```python
+from ape import chain, networks
+
+with networks.ethereum.mainnet_fork.use_provider("boa"):
+    print(chain.provider.chain_id)
+```
 
 ## Development
 

ape_titanoboa/__init__.py

@@ -1 +1,20 @@
-# Add module top-level imports here
+from ape import plugins
+
+
+@plugins.register(plugins.Config)
+def config_class():
+    from ape_titanoboa.config import BoaConfig
+
+    return BoaConfig
+
+
+@plugins.register(plugins.ProviderPlugin)
+def providers():
+    from evmchains import PUBLIC_CHAIN_META
+
+    from ape_titanoboa.provider import ForkTitanoboaProvider, TitanoboaProvider
+
+    for ecosystem, networks in PUBLIC_CHAIN_META.items():
+        yield ecosystem, "local", TitanoboaProvider
+        for network in networks:
+            yield ecosystem, f"{network}-fork", ForkTitanoboaProvider

ape_titanoboa/config.py

@@ -0,0 +1,45 @@
+from typing import Literal, Optional, Union
+
+from ape.api.config import PluginConfig
+from ape.types import BlockID
+
+# TODO: https://github.com/ApeWorX/ape/issues/2454 is resolved,
+#   can use `ape.utils.testing.DEFAULT_TEST_CHAIN_ID`, but for
+#   now we want this to be the same as ape-foundry's default.
+DEFAULT_TEST_CHAIN_ID = 31337
+ForkBlockIdentifier = Union[BlockID, Literal["safe"]]
+
+
+class BoaForkConfig(PluginConfig):
+    """
+    Configure forked networks.
+    """
+
+    upstream_provider: Optional[str] = None
+    """
+    The value to use, such as plugin name or URL, for the
+    upstream network. Defaults to the default provider
+    for that network.
+    """
+
+    block_identifier: ForkBlockIdentifier = "safe"
+    """
+    The block ID, such as block number of hash, to fork from (recommended).
+    Defaults to the literal "safe" (same as boa).
+    """
+
+
+class BoaConfig(PluginConfig):
+    """
+    Configure the titanoboa plugin.
+    """
+
+    chain_id: int = DEFAULT_TEST_CHAIN_ID
+    """
+    Change the chain ID for your development "chain".
+    """
+
+    fork: dict[str, dict[str, BoaForkConfig]] = {}
+    """
+    Maps ecosystem name -> network name -> fork configuration (e.g. block number).
+    """