diff --git a/docs/index.md b/docs/index.md index f475f90bfa..f6e218173d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,7 @@ userguides/clis userguides/data userguides/networks + userguides/forking_networks userguides/developing_plugins userguides/config userguides/transactions diff --git a/docs/methoddocs/cli.md b/docs/methoddocs/cli.md index 53dd7efa92..26130553e4 100644 --- a/docs/methoddocs/cli.md +++ b/docs/methoddocs/cli.md @@ -43,11 +43,3 @@ scripts. :members: :show-inheritance: ``` - -## Utilities - -```{eval-rst} -.. automodule:: ape.cli.utils - :members: - :show-inheritance: -``` diff --git a/docs/userguides/forking_networks.md b/docs/userguides/forking_networks.md new file mode 100644 index 0000000000..141c6d6945 --- /dev/null +++ b/docs/userguides/forking_networks.md @@ -0,0 +1,81 @@ +# Forking Networks + +You can fork live networks in Ape. +To do so, ensure you are using a provider plugin with forking features. +Some options are: + +1. [ApeWorX/ape-foundry](https://github.com/ApeWorX/ape-foundry) +2. [ApeWorX/ape-hardhat](https://github.com/ApeWorX/ape-hardhat) + +You can install one of these plugins by doing: + +```shell +ape plugins install +``` + +Ensure you have also configured your upstream network (the network you are forking). +For example, if forking `ethereum:mainnet` and using `alchemy`, set `alchemy` as the default mainnet provider: + +```yaml +ethereum: + mainnet: + default_provider: alchemy +``` + +Now, you can start and connect to your forked-network: + +```yaml +ape console --network ethereum:mainnet-fork:foundry +``` + +Learn more about setting up networks in the [the networks guide](./networks.html). + +## Forking Plugin Networks + +You can also fork L2 plugin networks. +For example, to fork a network such as Optimism, install the `ape-optimism` plugin: + +```shell +ape plugins install optimism +``` + +Then, just like you did for `ethereum`, configure `optimism`'s default mainnet provider: + +```yaml +optimism: + mainnet: + default_provider: alchemy +``` + +Now, you can start and connect to your forked-network: + +```yaml +ape console --network optimism:mainnet-fork:foundry +``` + +## Configure Default + +If you want to change the default network from `local` to your forked network, add the following config: + +```yaml +: + default_network: _fork +``` + +Where `ecosystem-name` is the ecosystem containing the network and `network-name` is the network you are forking. + +## Forked Context + +If you are already connected to a live network wish to temporarily fork it, use the [fork() context manager](../methoddocs/managers.html#ape.managers.networks.NetworkManager.fork): + +```python +from ape import networks + +def main(): + with networks.ethereum.mainnet.use_provider("alchemy") as alchemy: + print(alchemy.name) + with networks.fork(provider_name="foundry") as foundry: + print(foundry.name) +``` + +Learn more about the fork context manager [here](./networks.html#forked-context). diff --git a/docs/userguides/networks.md b/docs/userguides/networks.md index 09cf8bec4b..f24bdf7484 100644 --- a/docs/userguides/networks.md +++ b/docs/userguides/networks.md @@ -478,9 +478,11 @@ We can switch to a forked network by doing this: from ape import networks def main(): - with networks.fork("foundry"): + with networks.fork(provider_name="foundry"): ... # Do stuff on a local, forked version of mainnet # Switch back to mainnet. ``` + +Learn more about forking networks in the [forked-networks guide](./forking_networks.html).