From 6ea669c29f81f679381168dd8934ac6cb9144ebd Mon Sep 17 00:00:00 2001 From: Juliya Smith Date: Mon, 17 Jun 2024 10:51:48 -0500 Subject: [PATCH] docs: document more creation stuff --- docs/userguides/transactions.md | 43 +++++++++++++++++---------------- src/ape/api/query.py | 43 +++++++++++++++++++++++++++++++-- src/ape/contracts/base.py | 4 +++ 3 files changed, 67 insertions(+), 23 deletions(-) diff --git a/docs/userguides/transactions.md b/docs/userguides/transactions.md index af5f00f0dd..51b69e1288 100644 --- a/docs/userguides/transactions.md +++ b/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`. diff --git a/src/ape/api/query.py b/src/ape/api/query.py index dc0609e51f..b5c6c7f388 100644 --- a/src/ape/api/query.py +++ b/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, diff --git a/src/ape/contracts/base.py b/src/ape/contracts/base.py index 46aca9ad43..97175e55dc 100644 --- a/src/ape/contracts/base.py +++ b/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)