feat: test provider implementation

.github/workflows/commitlint.yaml

@@ -9,14 +9,14 @@ jobs:
         runs-on: ubuntu-latest
 
         steps:
-        - uses: actions/checkout@v2
+        - uses: actions/checkout@v4
           with:
               fetch-depth: 0
 
         - name: Setup Python
-          uses: actions/setup-python@v2
+          uses: actions/setup-python@v5
           with:
-              python-version: 3.8
+              python-version: "3.10"
 
         - name: Install Dependencies
           run: pip install .[dev]

.github/workflows/publish.yaml

@@ -10,12 +10,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
 
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.8
+        python-version: "3.10"
 
     - name: Install dependencies
       run: |

.github/workflows/test.yaml

@@ -7,12 +7,12 @@ jobs:
         runs-on: ubuntu-latest
 
         steps:
-        - uses: actions/checkout@v2
+        - uses: actions/checkout@v4
 
         - name: Setup Python
-          uses: actions/setup-python@v2
+          uses: actions/setup-python@v5
           with:
-              python-version: 3.8
+              python-version: "3.10"
 
         - name: Install Dependencies
           run: |
@@ -32,12 +32,12 @@ jobs:
         runs-on: ubuntu-latest
 
         steps:
-        - uses: actions/checkout@v2
+        - uses: actions/checkout@v4
 
         - name: Setup Python
-          uses: actions/setup-python@v2
+          uses: actions/setup-python@v5
           with:
-              python-version: 3.8
+              python-version: "3.10"
 
         - name: Install Dependencies
           run: |
@@ -53,13 +53,13 @@ jobs:
         strategy:
             matrix:
                 os: [ubuntu-latest, macos-latest]   # eventually add `windows-latest`
-                python-version: [3.8, 3.9, "3.10"]
+                python-version: ["3.10", "3.11", "3.12", "3.13"]
 
         steps:
-        - uses: actions/checkout@v2
+        - uses: actions/checkout@v4
 
         - name: Setup Python
-          uses: actions/setup-python@v2
+          uses: actions/setup-python@v5
           with:
               python-version: ${{ matrix.python-version }}
 
@@ -68,8 +68,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:
@@ -79,12 +87,12 @@ jobs:
 #            fail-fast: true
 #
 #        steps:
-#        - uses: actions/checkout@v2
+#        - uses: actions/checkout@v4
 #
 #        - name: Setup Python
-#          uses: actions/setup-python@v2
+#          uses: actions/setup-python@v5
 #          with:
-#              python-version: 3.8
+#              python-version: "3.10"
 #
 #        - name: Install Dependencies
 #          run: pip install .[test]

.github/workflows/title.yaml

@@ -12,12 +12,12 @@ jobs:
         runs-on: ubuntu-latest
 
         steps:
-        - uses: actions/checkout@v2
+        - uses: actions/checkout@v4
 
         - name: Setup Python
-          uses: actions/setup-python@v2
+          uses: actions/setup-python@v5
           with:
-              python-version: 3.8
+              python-version: "3.10"
 
         - name: Install Dependencies
           run: pip install commitizen

.pre-commit-config.yaml

@@ -1,31 +1,38 @@
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.2.0
+    rev: v5.0.0
     hooks:
     -   id: check-yaml
 
--   repo: https://github.com/pre-commit/mirrors-isort
-    rev: v5.10.1
+-   repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
     hooks:
       - id: isort
 
 -   repo: https://github.com/psf/black
-    rev: 22.6.0
+    rev: 24.10.0
     hooks:
       - id: black
         name: black
 
--   repo: https://gitlab.com/pycqa/flake8
-    rev: 4.0.1
+-   repo: https://github.com/pycqa/flake8
+    rev: 7.1.1
     hooks:
     -   id: flake8
+        additional_dependencies: [flake8-breakpoint, flake8-print, flake8-pydantic, flake8-type-checking]
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.971
+    rev: v1.14.1
     hooks:
     -   id: mypy
-        additional_dependencies: [types-requests]
+        additional_dependencies: [types-requests, types-setuptools]
+
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.21
+    hooks:
+    -   id: mdformat
+        additional_dependencies: [mdformat-gfm, mdformat-frontmatter, mdformat-pyproject]
 
 
 default_language_version:
-    python: python3.8
+    python: python3.9

CONTRIBUTING.md

@@ -46,4 +46,4 @@ A pull request represents the start of a discussion, and doesn't necessarily nee
 If you are opening a work-in-progress pull request to verify that it passes CI tests, please consider
 [marking it as a draft](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests).
 
-Join the Ethereum Python [Discord](https://discord.gg/PcEJ54yX) if you have any questions.
+Join the ApeWorX [Discord](https://discord.gg/apeworx) if you have any questions.

README.md

@@ -1,10 +1,10 @@
 # Quick Start
 
-Titanoboa integration and pytest runner
+Use Titanoboa as a provider in Ape.
 
 ## Dependencies
 
-* [python3](https://www.python.org/downloads) version 3.8 or greater, python3-dev
+* [python3](https://www.python.org/downloads) version 3.9 or greater, python3-dev
 
 ## Installation
 
@@ -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).
+    """