Add udc docs (OpenZeppelin#954)

* add headers and contract deployment example * start precomputing section * move udc helpers to utils * fix formatting * start changelog entry * add changelog entry * add udc and udc api in nav * move udc utils to udc module * update udc utils import * update udc doc * update utils * add udc api doc * fix formatting * Apply suggestions from code review Co-authored-by: Eric Nordelo <[email protected]> * Apply suggestions from code review Co-authored-by: Eric Nordelo <[email protected]> * remove duplicate link * use pedersen trait in compute fn * update util func names * fix formatting * add salt modification to deploy_contract description * add declare tx link * add udc to sidebar-collapse * remove first iteration NOTE * change function order * add interfaces mod * simplify import using interfaces mod * fix formatting * update comments * update interface import * add link to event * fix precomputing section * update universal_deployer api section in utils * fix deploy_syscall link * fix use statement * change util mod to deployments * change mod name to deployments, update links * fix formatting * add comment * add new udc contract address * Apply suggestions from code review Co-authored-by: Eric Nordelo <[email protected]> * Apply suggestions from code review Co-authored-by: Eric Nordelo <[email protected]> * fix fn * consolidate calculate udc fns, add DeployerInfo struct * update udc docs * move udc doc to modules * link udc util * fix calculate util name * update calculate util fn names * remove unused attr * update udc preset link --------- Co-authored-by: Eric Nordelo <[email protected]>
andrew-fleming · Apr 16, 2024 · afd683f · afd683f
1 parent cbd76fc
commit afd683f
Show file tree

Hide file tree

Showing 15 changed files with 365 additions and 248 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - before_update and after_update hooks to ERC20Component (#951)
 - INSUFFICIENT_BALANCE and INSUFFICIENT_ALLOWANCE errors to ERC20Component (#951)
 - ERC20Votes component (#951)
+- UDC docs (#954)
+- Util functions to precompute addresses (#954)
 
 ### Changed
 

diff --git a/docs/antora.yml b/docs/antora.yml
@@ -5,4 +5,4 @@ nav:
   - modules/ROOT/nav.adoc
 asciidoc:
   attributes:
-    page-sidebar-collapse-default: 'Access,Accounts,Introspection,Security,ERC20,ERC721,ERC1155,Upgrades'
+    page-sidebar-collapse-default: 'Access,Accounts,Introspection,Security,ERC20,ERC721,ERC1155,Upgrades,Universal Deployer Contract'
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -36,6 +36,9 @@
 *** xref:erc1155.adoc[ERC1155]
 **** xref:/api/erc1155.adoc[API Reference]
 
+** xref:udc.adoc[Universal Deployer Contract]
+*** xref:/api/udc.adoc[API Reference]
+
 ** xref:upgrades.adoc[Upgrades]
 *** xref:/api/upgrades.adoc[API Reference]
 

diff --git a/docs/modules/ROOT/pages/api/udc.adoc b/docs/modules/ROOT/pages/api/udc.adoc
@@ -0,0 +1,87 @@
+:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
+
+= Universal Deployer
+
+Reference of the Universal Deployer Contract (UDC) interface and preset.
+
+== Core
+
+[.contract]
+[[IUniversalDeployer]]
+=== `++IUniversalDeployer++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.10.0/src/utils/universal_deployer/interface.cairo#L7[{github-icon},role=heading-link]
+
+```javascript
+use openzeppelin::utils::interfaces::IUniversalDeployer;
+```
+
+[.contract-index]
+.Functions
+--
+* xref:#IUniversalDeployer-deploy_contract[`++deploy_contract(class_hash, salt, from_zero, calldata)++`]
+--
+
+[.contract-index]
+.Events
+--
+* xref:#IUniversalDeployer-ContractDeployed[`++ContractDeployed(address, deployer, from_zero, class_hash, calldata, salt)++`]
+--
+
+[#IUniversalDeployer-Functions]
+==== Functions
+
+[.contract-item]
+[[IUniversalDeployer-deploy_contract]]
+==== `[.contract-item-name]#++deploy_contract++#++(class_hash: ClassHash, salt: felt252, from_zero: bool, calldata: Span<felt252>) → ContractAddress++` [.item-kind]#external#
+
+Deploys a contract through the Universal Deployer Contract.
+
+[#IUniversalDeployer-Events]
+==== Events
+
+[.contract-item]
+[[IUniversalDeployer-ContractDeployed]]
+==== `[.contract-item-name]#++ContractDeployed++#++(address: ContractAddress, deployer: ContractAddress, from_zero: bool, class_hash: ClassHash, calldata: Span<felt252>, salt: felt252)++` [.item-kind]#event#
+
+Emitted when `deployer` deploys a contract through the Universal Deployer Contract.
+
+== Presets
+
+:origin-dependent: xref:/udc.adoc#origin_dependent[origin-dependent]
+:origin-independent: xref:/udc.adoc#origin_independent[origin-independent]
+
+[.contract]
+[[UniversalDeployer]]
+=== `++UniversalDeployer++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.10.0/src/presets/universal_deployer.cairo[{github-icon},role=heading-link]
+
+```javascript
+use openzeppelin::presets::UniversalDeployer;
+```
+
+The standard Universal Deployer Contract.
+
+include::../utils/_class_hashes.adoc[]
+
+[.contract-index]
+.{presets-page}
+--
+{UniversalDeployer-class-hash}
+--
+
+[.contract-index]
+.Embedded Implementations
+--
+.UniversalDeployerImpl
+* xref:#UniversalDeployer-deploy_contract[`++deploy_contract(self, address, deployer, from_zero, class_hash, calldata, salt)++`]
+--
+
+[.contract-item]
+[[UniversalDeployer-deploy_contract]]
+==== `[.contract-item-name]#++deploy_contract++#++(ref self: ContractState, address: ContractAddress, deployer: ContractAddress, from_zero: bool, class_hash: ClassHash, calldata: Span<felt252>, salt: felt252) -> ContractAddress++` [.item-kind]#external#
+
+Deploys a contract through the Universal Deployer Contract.
+
+When `from_zero` is `false`, `salt` is hashed with the caller address and the modified salt is passed to the inner `deploy_syscall`. This type of deployment is {origin-dependent}.
+
+When `from_zero` is `true`, the deployment type is {origin-independent}.
+
+Emits an <<IUniversalDeployer-ContractDeployed,ContractDeployed>> event.
diff --git a/docs/modules/ROOT/pages/api/utilities.adoc b/docs/modules/ROOT/pages/api/utilities.adoc
@@ -1,5 +1,7 @@
 = Utilities
 
+:deploy_syscall: link:https://docs.starknet.io/documentation/architecture_and_concepts/Smart_Contracts/system-calls-cairo1/#deploy[deploy_syscall]
+
 The following documentation provides reasoning and examples for functions and constants found in `openzeppelin::utils`
 and `openzeppelin::tests::utils`.
 
@@ -28,6 +30,7 @@ Module containing core utilities of the library.
 
 .Inner modules
 * xref:#utils-cryptography[`++cryptography++`]
+* xref:#utils-deployments[`++deployments++`]
 * xref:#utils-math[`++math++`]
 * xref:#utils-selectors[`++selectors++`]
 * xref:#utils-serde[`++serde++`]
@@ -101,6 +104,12 @@ Note that it can be automatically casted to any type implementing the `Serde` tr
 
 See xref:#cryptography[`openzeppelin::utils::cryptography`].
 
+[.contract-item]
+[[utils-deployments]]
+==== `[.contract-item-name]#++deployments++#` [.item-kind]#module#
+
+See xref:#deployments[`openzeppelin::utils::deployments`].
+
 [.contract-item]
 [[utils-math]]
 ==== `[.contract-item-name]#++math++#` [.item-kind]#module#
@@ -154,6 +163,68 @@ See xref:#NoncesComponent[`openzeppelin::utils::cryptography::nonces::NoncesComp
 
 See xref:#snip12[`openzeppelin::utils::cryptography::snip12`].
 
+[.contract]
+[[deployments]]
+=== `++deployments++`
+
+:udc-doc: xref:/udc.adoc[Universal Deployer Contract]
+
+```javascript
+use openzeppelin::utils::deployments;
+```
+
+Module containing utility functions for calculating contract addresses through {deploy_syscall} and the {udc-doc} (UDC).
+
+[.contract-index]
+.Members
+--
+.Structs
+* xref:deployments-DeployerInfo[`++DeployerInfo(caller_address, udc_address)++`]
+
+.Functions
+* xref:deployments-calculate_contract_address_from_deploy_syscall[`++calculate_contract_address_from_deploy_syscall(salt, class_hash, constructor_calldata, deployer_address)++`]
+* xref:deployments-compute_hash_on_elements[`++compute_hash_on_elements(data)++`]
+* xref:deployments-calculate_contract_address_from_udc[`++calculate_contract_address_from_udc(salt, class_hash, constructor_calldata, deployer_info)++`]
+--
+
+[#deployments-Structs]
+==== Structs
+
+:calculate_contract_address_from_udc: xref:deployments-calculate_contract_address_from_udc[utils::calculate_contract_address_from_udc]
+
+[.contract-item]
+[[deployments-DeployerInfo]]
+==== `[.contract-item-name]#++DeployerInfo++#++(caller_address: ContractAddress, udc_address: ContractAddress)++` [.item-kind]#struct#
+
+Struct containing arguments necessary in {calculate_contract_address_from_udc} for origin-dependent deployment calculations.
+
+[#deployments-Functions]
+==== Functions
+
+:deployer-info: xref:deployments-DeployerInfo[DeployerInfo]
+
+[.contract-item]
+[[deployments-calculate_contract_address_from_deploy_syscall]]
+==== `[.contract-item-name]#++calculate_contract_address_from_deploy_syscall++#++(salt: felt252, class_hash: ClassHash, constructor_calldata: Span<felt252>, deployer_address: ContractAddress) → ContractAddress++` [.item-kind]#function#
+
+Returns the contract address when passing the given arguments to {deploy_syscall}.
+
+[.contract-item]
+[[deployments-compute_hash_on_elements]]
+==== `[.contract-item-name]#++compute_hash_on_elements++#++(mut data: Span<felt252>) → felt252++` [.item-kind]#function#
+
+Creates a Pedersen hash chain with the elements of `data` and returns the finalized hash.
+
+[.contract-item]
+[[deployments-calculate_contract_address_from_udc]]
+==== `[.contract-item-name]#++calculate_contract_address_from_udc++#++(salt: felt252, class_hash: ClassHash, constructor_calldata: Span<felt252>, deployer_info: Option<DeployerInfo>) → ContractAddress++` [.item-kind]#function#
+
+Returns the calculated contract address for UDC deployments.
+
+Origin-independent deployments (deployed from zero) should pass `Option::None` as `deployer_info`.
+
+Origin-dependent deployments hash `salt` with `caller_address` (member of {deployer-info}) and pass the hashed salt to the inner {deploy_syscall} as the `contract_address_salt` argument.
+
 [.contract]
 [[math]]
 === `++math++`
@@ -344,8 +415,6 @@ Module containing utilities for testing the library.
 [[testutils-deploy]]
 ==== `[.contract-item-name]#++deploy++#++(contract_class_hash: felt252, calldata: Array<felt252>) → ContractAddress++` [.item-kind]#function#
 
-:deploy_syscall: https://docs.starknet.io/documentation/architecture_and_concepts/Smart_Contracts/system-calls/#deploy[deploy_syscall]
-
 Uses the `{deploy_syscall}` to deploy an instance of the contract given the class hash and the calldata.
 
 The `contract_address_salt` is always set to zero, and `deploy_from_zero` is set to false.

diff --git a/docs/modules/ROOT/pages/presets.adoc b/docs/modules/ROOT/pages/presets.adoc
@@ -3,7 +3,7 @@
 :erc721: xref:/api/erc721.adoc#ERC721[ERC721]
 :erc1155: xref:/api/erc1155.adoc#ERC1155[ERC1155]
 :eth-account-upgradeable: xref:/api/account.adoc#EthAccountUpgradeable[EthAccountUpgradeable]
-:udc: https://github.com/starknet-io/starknet-docs/blob/v0.1.479/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/universal-deployer.adoc[UniversalDeployer]
+:udc: xref:/api/udc.adoc#UniversalDeployer[UniversalDeployer]
 :sierra-class-hashes: https://docs.starknet.io/documentation/architecture_and_concepts/Smart_Contracts/class-hash[Sierra class hashes]
 :starkli: https://book.starkli.rs/introduction[starkli]
 :wizard: https://wizard.openzeppelin.com[Wizard for Cairo]