feat: allow configuring Safes for cloud use (#76)

* refactor(Config): use model for cache data file under `~/.ape/safe`

* feat(Config): add way to configure required Safes (if they don't exist)

* docs: add `pyproject.toml` and environment variable usage to docs

* refactor(Account): cache `.address` call on `SafeAccount`

* docs(Account): fix note

Co-authored-by: antazoey <admin@antazoey.me>

* docs(Account): add a note about not overwriting existing Safes

* refactor(Account): specify encoding for file

---------

Co-authored-by: antazoey <admin@antazoey.me>

Author: fubuloubu

README.md

@@ -60,6 +60,19 @@ safe:
   default_safe: my-safe
 ```
 
+or via `pyproject.toml`:
+
+```toml
+[tool.ape.safe]
+default_safe = "my-safe"
+```
+
+To specify via environment variable, do:
+
+```sh
+APE_SAFE_DEFAULT_SAFE="my-safe"
+```
+
 **NOTE**: Also, to avoid always needing to specify `--network`, you can set a default ecosystem, network, and provider in your config file.
 The rest of the guide with not specify `--network` on each command but assume the correct one is set in the config file.
 Here is an example:
@@ -152,6 +165,38 @@ txn.add(vault.deposit, amount)
 txn(sender=safe,gas=0)
 ```
 
+## Cloud Usage
+
+To use this plugin in a cloud environment, such as with the [Silverback Platform](https://silverback.apeworx.io), you will need to make sure that you have configured your Safe to exist within the environment.
+The easiest way to do this is to use the `require` configuration item.
+To specify a required Safe in your `ape-config.yaml` (which adds it into your `~/.ape/safe` folder if it doesn't exist), use:
+
+```yaml
+safe:
+  require:
+    my-safe:
+      address: "0x1234...AbCd"
+      deployed_chain_ids: [1, ...]
+```
+
+or in `pyproject.toml`:
+
+```toml
+[tool.ape.safe.require."my-safe"]
+address = "0x1234...AbCd"
+deployed_chain_ids = [1, ...]
+```
+
+To specify via environment variable, do:
+
+```sh
+APE_SAFE_REQUIRE='{"my-safe":{"address":"0x1234...AbCd","deployed_chain_ids":[1,...]}}'
+```
+
+```{notice}
+If a safe with the same alias as an entry in `require` exists in your local environment, this will skip adding it, even if the existing alias points to a different address than the one in the config item.
+```
+
 ## Development
 
 Please see the [contributing guide](CONTRIBUTING.md) to learn more how to contribute to this project.

ape_safe/accounts.py

@@ -22,6 +22,7 @@
 from packaging.version import Version
 
 from .client import BaseSafeClient, MockSafeClient, SafeClient, SafeTx, SafeTxConfirmation, SafeTxID
+from .config import SafeConfig
 from .exceptions import (
     ApeSafeError,
     NoLocalSigners,
@@ -32,6 +33,7 @@
 )
 from .factory import SafeFactory
 from .packages import PackageType
+from .types import SafeCacheData
 from .utils import get_safe_tx_hash, order_by_signer
 
 if TYPE_CHECKING:
@@ -42,9 +44,23 @@
 class SafeContainer(AccountContainerAPI):
     _accounts: dict[str, "SafeAccount"] = {}
 
+    @property
+    def config(self) -> SafeConfig:
+        return cast(SafeConfig, self.config_manager["safe"])
+
     @property
     def _account_files(self) -> Iterator[Path]:
-        yield from self.data_folder.glob("*.json")
+        account_files = list(self.data_folder.glob("*.json"))
+
+        # NOTE: Make sure these Safes exist in our local cache
+        for required_safe, safe_cache_data in self.config.require.items():
+            # NOTE: If alias `required_safe` already exists, skip overwriting it
+            if required_safe not in map(lambda p: p.stem, account_files):
+                safe_cache_file = self.data_folder / f"{required_safe}.json"
+                safe_cache_file.write_text(safe_cache_data.model_dump_json(), encoding="utf-8")
+                account_files.append(safe_cache_file)
+
+        yield from account_files
 
     @property
     def aliases(self) -> Iterator[str]:
@@ -204,17 +220,17 @@ def alias(self) -> str:
         return self.account_file_path.stem
 
     @property
-    def account_file(self) -> dict:
-        return json.loads(self.account_file_path.read_text())
+    def account_file(self) -> SafeCacheData:
+        return SafeCacheData.model_validate_json(self.account_file_path.read_text(encoding="utf-8"))
 
-    @property
+    @cached_property
     def address(self) -> AddressType:
         try:
             ecosystem = self.provider.network.ecosystem
         except ProviderNotConnectedError:
             ecosystem = self.network_manager.ethereum
 
-        return ecosystem.decode_address(self.account_file["address"])
+        return ecosystem.decode_address(self.account_file.address)
 
     @cached_property
     def contract(self) -> "ContractInstance":
@@ -280,15 +296,15 @@ def client(self) -> BaseSafeClient:
         if self.provider.network.is_local:
             return MockSafeClient(contract=self.contract)
 
-        elif chain_id in self.account_file["deployed_chain_ids"]:
+        elif chain_id in self.account_file.deployed_chain_ids:
             return SafeClient(
                 address=self.address, chain_id=self.provider.chain_id, override_url=override_url
             )
 
         elif (
             self.provider.network.name.endswith("-fork")
             and isinstance(self.provider.network, ForkedNetworkAPI)
-            and self.provider.network.upstream_chain_id in self.account_file["deployed_chain_ids"]
+            and self.provider.network.upstream_chain_id in self.account_file.deployed_chain_ids
         ):
             return SafeClient(
                 address=self.address,

ape_safe/config.py

@@ -1,8 +1,16 @@
 from typing import Optional
 
 from ape.api import PluginConfig
+from pydantic_settings import SettingsConfigDict
+
+from .types import SafeCacheData
 
 
 class SafeConfig(PluginConfig):
     default_safe: Optional[str] = None
     """Alias of the default safe."""
+
+    require: dict[str, SafeCacheData] = {}
+    """Safes that are required to exist for the project. Useful for cloud-based usage."""
+
+    model_config = SettingsConfigDict(env_prefix="APE_SAFE_")

ape_safe/types.py

@@ -0,0 +1,12 @@
+from ape.types.address import AddressType
+from pydantic import BaseModel
+
+
+class SafeCacheData(BaseModel):
+    """Model for cached Safe data under `~/.ape/safe/*.json`"""
+
+    address: AddressType
+    """Address of the Safe"""
+
+    deployed_chain_ids: list[int] = []
+    """Networks (by chain ID) this Safe is deployed on"""