docs: document more fully the contract-creation metadata feature (Ape…

…WorX#2146)

docs/userguides/transactions.md

@@ -1,4 +1,4 @@
-# Making Transactions
+# Transactions
 
 Regardless of how you are using `ape`, you will likely be making transactions.
 There are various types of transactions you can make with `ape`. A simple example is deploying a contract.
@@ -15,32 +15,12 @@ The following example demonstrates a simple deployment script:
 ```python
 from ape import accounts, project
 
-
 def deploy():
     account = accounts.load("MyAccount")
     # Assume you have a contract named `MyContract` in your project's contracts folder.
     return account.deploy(project.MyContract)
 ```
 
-To get the receipt of a `deploy` transaction, use the [ContractInstance.creation_metadata](../methoddocs/contracts.html#ape.contracts.base.ContractInstance.creation_metadata) property:
-
-Additionally, you can find the `.deployer`, `.proxy` and whatever else on the creaton metadata which may come in handy.
-
-```{note}
-Use `ape-etherscan` or a node with Otterscan for increased support for these features.
-```
-
-```python
-from ape import accounts, project
-
-dev = accounts.load("dev")
-contract = project.MyContract.deploy(sender=dev)
-
-# The receipt is available on the contract instance and has the expected sender.
-receipt = contract.creation_metadata.receipt
-assert receipt.sender == dev
-```
-
 ### Deployment from Ape Console
 
 Deploying from [ape console](./console.html) allows you to interact with a contract in real time. You can also use the `--network` flag to connect a live network.
@@ -59,6 +39,27 @@ In [3]: token.contract_method_defined_in_contract()
 
 For an in depth tutorial on how to deploy, please visit [ApeAcademy](https://academy.apeworx.io/).
 
+### Deployment Metadata
+
+To get the receipt of a `deploy` transaction, use the [ContractInstance.creation_metadata](../methoddocs/contracts.html#ape.contracts.base.ContractInstance.creation_metadata) property:
+
+```{note}
+Use `ape-etherscan` or a node with Otterscan for increased support for these features.
+```
+
+```python
+from ape import accounts, project
+
+dev = accounts.load("dev")
+contract = project.MyContract.deploy(sender=dev)
+
+# The receipt is available on the contract instance and has the expected sender.
+receipt = contract.creation_metadata.receipt
+assert receipt.sender == dev
+```
+
+**NOTE**: The `creation_metadata` contains other information as well, such as `.factory` for factory-deployed contracts.
+
 ## Dynamic-Fee Transactions
 
 Before [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), all transactions used a `gas_price`.

src/ape/api/query.py

@@ -170,17 +170,56 @@ class ContractCreationQuery(_BaseQuery):
 
 
 class ContractCreation(BaseModel, BaseInterface):
+    """
+    Contract-creation metadata, such as the transaction
+    and deployer. Useful for contract-verification,
+    ``block_identifier=`` usage, and other use-cases.
+
+    To get contract-creation metadata, you need a query engine
+    that can provide it, such as the ``ape-etherscan`` plugin
+    or a node connected to the OTS namespace.
+    """
+
     txn_hash: str
+    """
+    The transaction hash of the deploy transaction.
+    """
+
     block: int
+    """
+    The block number of the deploy transaction.
+    """
+
     deployer: AddressType
+    """
+    The contract deployer address.
+    """
+
     factory: Optional[AddressType] = None
+    """
+    The address of the factory contract, if there is one
+    and it is known (depends on the query provider!).
+    """
 
     @property
-    def receipt(self):
+    def receipt(self) -> ReceiptAPI:
+        """
+        The deploy transaction :class:`~ape.api.transactions.ReceiptAPI`.
+        """
         return self.chain_manager.get_receipt(self.txn_hash)
 
     @classmethod
-    def from_receipt(cls, receipt: ReceiptAPI):
+    def from_receipt(cls, receipt: ReceiptAPI) -> "ContractCreation":
+        """
+        Create a metadata class.
+
+        Args:
+            receipt (:class:`~ape.api.transactions.ReceiptAPI`): The receipt
+              of the deploy transaction.
+
+        Returns:
+            :class:`~ape.api.query.ContractCreation`
+        """
         return cls(
             txn_hash=receipt.txn_hash,
             block=receipt.block_number,

src/ape/contracts/base.py

@@ -886,6 +886,10 @@ def from_receipt(cls, receipt: ReceiptAPI, contract_type: ContractType) -> "Cont
     def creation_metadata(self) -> Optional[ContractCreation]:
         """
         Contract creation details: txn_hash, block, deployer, factory, receipt.
+        See :class:`~ape.api.query.ContractCreation` for more details.
+        **NOTE**: Must be either connected to a node that provides this data,
+        such as a node with the ``ots_`` namespace enabled, or have a query-plugin
+        installed that can fetch this data, such as ``ape-etherscan``.
         """
         return self.chain_manager.contracts.get_creation_metadata(self.address)