Document Class Hashes

CHANGELOG.md

@@ -6,3 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+### Added
+
+- Documentation for presets (#832)

docs/modules/ROOT/nav.adoc

@@ -30,4 +30,6 @@
 // * xref:udc.adoc[Universal Deployer Contract]
 // * xref:utilities.adoc[Utilities]
 
+* xref:/presets.adoc[Presets]
+
 * xref:contracts::index.adoc[Contracts for Solidity]

docs/modules/ROOT/pages/api/account.adoc

@@ -272,6 +272,14 @@ use openzeppelin::presets::Account;
 
 Basic account contract leveraging xref:#AccountComponent[AccountComponent].
 
+include::../utils/_class_hashes.adoc[]
+
+[.contract-index]
+.{class-hashes-page}
+--
+{account-class-hash}
+--
+
 [.contract-index]
 .Constructor
 --

docs/modules/ROOT/pages/api/erc20.adoc

@@ -484,6 +484,14 @@ use openzeppelin::presets::ERC20;
 
 Basic ERC20 contract leveraging xref:#ERC20Component[ERC20Component] with a fixed-supply mechanism for token distribution.
 
+include::../utils/_class_hashes.adoc[]
+
+[.contract-index]
+.{class-hashes-page}
+--
+{erc20-class-hash}
+--
+
 [.contract-index]
 .Constructor
 --
@@ -509,5 +517,4 @@ Basic ERC20 contract leveraging xref:#ERC20Component[ERC20Component] with a fixe
 [[ERC20-constructor]]
 ==== `[.contract-item-name]#++constructor++#++(ref self: ContractState, name: felt252, symbol: felt252, fixed_supply: u256, recipient: ContractAddress)++` [.item-kind]#constructor#
 
-Sets the `name` and `symbol`.
-Mints `fixed_supply` tokens to `recipient`.
+Sets the `name` and `symbol` and mints `fixed_supply` tokens to `recipient`.

docs/modules/ROOT/pages/api/erc721.adoc

@@ -69,18 +69,18 @@ Returns the owner address of `token_id`.
 
 Transfer ownership of `token_id` from `from` to `to`, checking first that `to` is aware of the ERC721 protocol to prevent tokens being locked forever.
 For information regarding how contracts communicate their awareness of the ERC721 protocol, see {receiving-tokens}.
-    
+
 Emits a <<IERC721-Transfer,Transfer>> event.
 
 [.contract-item]
 [[IERC721-transfer_from]]
 ==== `[.contract-item-name]#++transfer_from++#++(from: ContractAddress, to: ContractAddress, token_id: u256)++` [.item-kind]#external#
 
 Transfer ownership of `token_id` from `from` to `to`.
-    
+
 Note that the caller is responsible to confirm that the recipient is capable of receiving ERC721 transfers or else they may be permanently lost.
 Usage of <<IERC721-safe_transfer_from,IERC721::safe_transfer_from>> prevents loss, though the caller must understand this adds an external call which potentially creates a reentrancy vulnerability.
-    
+
 Emits a <<IERC721-Transfer,Transfer>> event.
 
 [.contract-item]
@@ -190,8 +190,8 @@ ERC721 component implementing <<IERC721,IERC721>> and <<IERC721Metadata,IERC721M
 
 NOTE: Implementing xref:api/introspection.adoc#SRC5Component[SRC5Component] is a requirement for this component to be implemented.
 
-[.contract-index]
-.External functions
+[.contract-index#ERC721Component-Embeddable-Impls]
+.Embeddable Implementations
 --
 .IERC721Impl
 * xref:#IERC721-balance_of[`++balance_of(self, account)++`]
@@ -209,8 +209,8 @@ NOTE: Implementing xref:api/introspection.adoc#SRC5Component[SRC5Component] is a
 * xref:#IERC721Metadata-token_uri[`++token_uri(self, token_id)++`]
 --
 
-[.contract-index]
-.camelCase support
+[.contract-index#ERC721Component-Embeddable-Impls-camelCase]
+.Embeddable implementations (camelCase)
 --
 .ER721CamelOnlyImpl
 * xref:#ERC721-balanceOf[`++balanceOf(self, account)++`]
@@ -550,19 +550,19 @@ Requirements:
 ==== Events
 
 [.contract-item]
-[[IERC721-Approval]]
+[[ERC721-Approval]]
 ==== `[.contract-item-name]#++Approval++#++(owner: ContractAddress, approved: ContractAddress, token_id: u256)++` [.item-kind]#event#
 
 See <<IERC721-Approval,Approval>>.
 
 [.contract-item]
-[[IERC721-ApprovalForAll]]
+[[ERC721-ApprovalForAll]]
 ==== `[.contract-item-name]#++ApprovalForAll++#++(owner: ContractAddress, operator: ContractAddress, approved: bool)++` [.item-kind]#event#
 
 See <<IERC721-ApprovalForAll,ApprovalForAll>>.
 
 [.contract-item]
-[[IERC721-Transfer]]
+[[ERC721-Transfer]]
 ==== `[.contract-item-name]#++Transfer++#++(from: ContractAddress, to: ContractAddress, token_id: u256)++` [.item-kind]#event#
 
 See <<IERC721-Transfer,Transfer>>.
@@ -597,3 +597,55 @@ Interface for contracts that support receiving `safe_transfer_from` transfers.
 ==== `[.contract-item-name]#++on_erc721_received++#++(operator: ContractAddress, from: ContractAddress, token_id: u256, data Span<felt252>) -> felt252++` [.item-kind]#external#
 
 Whenever an IERC721 `token_id` token is transferred to this non-account contract via <<IERC721-safe_transfer_from,IERC721::safe_transfer_from>> by `operator` from `from`, this function is called.
+
+== Presets
+
+[.contract]
+[[ERC721]]
+=== `++ERC721++` link:https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.8.0/src/presets/erc721.cairo[{github-icon},role=heading-link]
+
+```javascript
+use openzeppelin::presets::ERC721;
+```
+
+Basic ERC721 contract leveraging xref:#ERC721Component[ERC721Component].
+
+include::../utils/_class_hashes.adoc[]
+
+[.contract-index]
+.{class-hashes-page}
+--
+{erc721-class-hash}
+--
+
+[.contract-index]
+.Constructor
+--
+* xref:#ERC721-constructor[`++constructor(self, name, symbol, recipient, token_ids, token_uris)++`]
+--
+
+[.contract-index]
+.Embedded Implementations
+--
+.ERC721Component
+
+* xref:#ERC721Component-Embeddable-Impls[`++ERC721Impl++`]
+* xref:#ERC721Component-Embeddable-Impls[`++ERC721MetadataImpl++`]
+* xref:#ERC721Component-Embeddable-Impls-camelCase[`++ERC721CamelOnly++`]
+* xref:#ERC721Component-Embeddable-Impls-camelCase[`++ERC721MetadataCamelOnly++`]
+
+.SRC5Component
+
+* xref:api/introspection.adoc#SRC5Component-Embeddable-Impls[`++SRC5Impl++`]
+--
+
+[#ERC721-constructor-section]
+==== Constructor
+
+[.contract-item]
+[[ERC721-constructor]]
+==== `[.contract-item-name]#++constructor++#++(ref self: ContractState, name: felt252, symbol: felt252, recipient: ContractAddress, token_ids: Span<u256>, token_uris: Span<felt252>)++` [.item-kind]#constructor#
+
+Sets the `name` and `symbol`.
+
+Mints `token_ids` tokens with each corresponding URI from `token_uris` to `recipient`.

docs/modules/ROOT/pages/erc721.adoc

@@ -63,6 +63,7 @@ trait IERC721ABI {
 
 :erc165-storage: https://docs.openzeppelin.com/contracts/4.x/api/utils#ERC165Storage[ERC165Storage]
 :src5-api: xref:introspection.adoc#src5[SRC5]
+:introspection: xref:introspection.adoc[Introspection]
 :eip165: https://eips.ethereum.org/EIPS/eip-165[EIP165]
 
 Although Starknet is not EVM compatible, this implementation aims to be as close as possible to the ERC721 standard by utilizing Cairo's short strings to simulate `name` and `symbol`.

docs/modules/ROOT/pages/presets.adoc

@@ -0,0 +1,36 @@
+:scarb: https://docs.swmansion.com/scarb[scarb]
+
+= Presets
+
+include::utils/_class_hashes.adoc[]
+
+List of "ready-to-deploy" presets available and their corresponding class hashes.
+
+:account: xref:/api/account.adoc#Account[Account.cairo]
+:erc20: xref:/api/erc20.adoc#ERC20[ERC20.cairo]
+:erc721: xref:/api/erc721.adoc#ERC721[ERC721.cairo]
+:cairo-and-sierra: https://docs.starknet.io/documentation/architecture_and_concepts/Smart_Contracts/cairo-and-sierra/[Cairo and Sierra]
+
+NOTE: Class hashes were computed using {class-hash-cairo-version}.
+
+|===
+| Name | Compiled Class Hash
+
+| `{account}`
+| `{account-class-hash}`
+
+| `{erc20}`
+| `{erc20-class-hash}`
+
+| `{erc721}`
+| `{erc721-class-hash}`
+|===
+
+:starkli: https://book.starkli.rs/introduction[starkli]
+
+To understand the compiled class hash term, check {cairo-and-sierra}.
+
+TIP: {starkli} class-hash command can be used to compute the class hash from a compiled artifact.
+
+TIP: To obtain the artifact
+using {scarb}, set the `casm = true` option under `\[[target.starknet-contract]]` in the `Scarb.toml` file.

docs/modules/ROOT/pages/utils/_class_hashes.adoc

@@ -0,0 +1,10 @@
+// Version
+:class-hash-cairo-version: https://crates.io/crates/cairo-lang-compiler/2.3.1[cairo 2.3.1]
+
+// Class Hashes
+:account-class-hash: 0x016c6081eb34ad1e0c5513234ed0c025b3c7f305902d291bad534cd6474c85bc
+:erc20-class-hash: 0x01d7085cee580ba542cdb5709bda80ebfe8bdede664261a3e6af92994d9a1de7
+:erc721-class-hash: 0x04376782cbcd20a05f8e742e96150757383dab737ab3e791b8505ad856756907
+
+// Presets page
+:class-hashes-page: xref:presets.adoc[Compiled class hash]