Update v0.8.0 docs (#854)

* bump to 0.8.0 (#834) * Update PULL_REQUEST_TEMPLATE.md (#827) * Update PULL_REQUEST_TEMPLATE.md * Update PULL_REQUEST_TEMPLATE.md * Update PULL_REQUEST_TEMPLATE.md * Update RELEASING and CONTRIBUTING (#828) * update RELEASING * fix linting * update CONTRIBUTING * fix emphasis * add changelog to releasing.md * improve live testing guidelines * Update CONTRIBUTING.md Co-authored-by: Andrew Fleming <[email protected]> --------- Co-authored-by: Andrew Fleming <[email protected]> * Add `ERC721ABI` and fix other abis (#761) * fix account abi * fix erc20 abi * fix erc721 abi * reorder internal fns * reorder internal fns * fix comment * reorder fns * fix casing * fix casing * reorder api fns * add dual interfaces link * add camel methods to api * remove imports * re-add src5_state * Apply suggestions from code review Co-authored-by: Eric Nordelo <[email protected]> * add deployer trait/impl * change non-standard to impls in fn list * fix in-code doc style * fix comments * fix interface order * remove unused impl --------- Co-authored-by: Eric Nordelo <[email protected]> * Update utility docs (#825) * fix: link (#545) * feat: add utility docs * Update docs/modules/ROOT/pages/utilities.adoc Co-authored-by: Andrew Fleming <[email protected]> * Update docs/modules/ROOT/pages/utilities.adoc Co-authored-by: Andrew Fleming <[email protected]> * Update docs/modules/ROOT/pages/utilities.adoc Co-authored-by: Andrew Fleming <[email protected]> * feat: apply review updates * Update docs/modules/ROOT/pages/utilities.adoc Co-authored-by: Andrew Fleming <[email protected]> * feat: apply review updates * fix: remove drop events * feat: update CHANGELOG * feat: apply review udpates --------- Co-authored-by: Andrew Fleming <[email protected]> * Add in-code docs (#822) * add in-code comment * normalize in-code comments * fix comment * fix comments * fix comments * add double back ticks for comment possessives * add missing reqs * add missing reqs, fix _burn description * fix __execute__ reqs * remove double backticks * remove unused imports * fix: implementation name (#840) * Improve component tests with ComponentState (#836) * refactor: component state in tests * feat: update CHANGELOG * Update CHANGELOG.md Co-authored-by: Martín Triay <[email protected]> * feat: apply review updates * fix: CHANGELOG --------- Co-authored-by: Martín Triay <[email protected]> * Document SRC5 migration (#821) * start migration guide * add links, add register_interfaces example * add supports_interfaces * add supports_interfaces to docs * fix formatting * revert change * Apply suggestions from code review Co-authored-by: Martín Triay <[email protected]> * remove upgrade fn from code block * remove supports_interfaces * add deregister_erc165_interface * change src5 migration title * fix src5 migration doc * fix how-to section * fix formatting * add deregister_erc165_interface * update interface registration section * add link to register_interface * update CHANGELOG * Apply suggestions from code review Co-authored-by: Martín Triay <[email protected]> * remove register_erc165_interface * remove deregister_erc165_interface from utilities * remove deregister from guide * fix import * remove register_interfaces fn from API * remove unused var * add initializable warning --------- Co-authored-by: Martín Triay <[email protected]> * Document Class Hashes (#832) * fix: link (#545) * feat: add page * feat: finish UI * Update docs/modules/ROOT/pages/api/erc721.adoc Co-authored-by: Andrew Fleming <[email protected]> * feat: apply review updates * fix: remove trailing space * feat: update CHANGELOG * Update CHANGELOG.md Co-authored-by: Martín Triay <[email protected]> * feat: apply review updates * feat: apply review updates --------- Co-authored-by: Andrew Fleming <[email protected]> Co-authored-by: Martín Triay <[email protected]> * Update extensibility docs (#823) * add extensibility docs * start setup guide * change file name * Apply suggestions from code review Co-authored-by: Eric Nordelo <[email protected]> * fix name * change title * change title to component impl * update changelog * add comp storage section * finish new structure * finish edits, add customization section * simplify titles * finish custom impl section * Apply suggestions from code review Co-authored-by: Martín Triay <[email protected]> * fix comp storage section * change section title to setup, minor edits * add cmp storage link, clean up impl section * add cairo book link * add api design tip * Apply suggestions from code review --------- Co-authored-by: Eric Nordelo <[email protected]> Co-authored-by: Martín Triay <[email protected]> * Update docs navbar (#838) * update docs navbar * complete navbar * fix navbar * fix navbar * update changelog * update changelog * fix changelog * update wizard and rename usage -> components * fix broken links * reordered changelog * fix default collapsed sections --------- Co-authored-by: Andrew Fleming <[email protected]> Co-authored-by: Eric Nordelo <[email protected]> Co-authored-by: Andrew Fleming <[email protected]>
OpenZeppelin · Dec 13, 2023 · 6f72a52 · 6f72a52
1 parent c23e8e9
commit 6f72a52
Show file tree

Hide file tree

Showing 47 changed files with 3,579 additions and 2,453 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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 SRC5 migration (#821)
+- Usage docs (#823)
+- Utilities documentation (#825)
+- Documentation for presets (#832)
+
+### Changed
+
+- Use ComponentState in tests (#836)
+- Docsite navbar (#838)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -37,15 +37,17 @@ As a contributor, you are expected to fork this repository, work on your own for
     git checkout -b fix/some-bug-short-description-#123
     ```
 
-3. Make your changes, add your files, update documentation ([see Documentation section](#documentation)), commit, and push to your fork.
+3. Make your changes, add your files, and [update the documentation](#documentation). Make sure to update the [CHANGELOG](CHANGELOG.md) (*[learn how](https://keepachangelog.com/en/1.1.0/)*).
+
+4. Commit and push to your fork.
 
     ```sh
     git add src/file.cairo
     git commit "Fix some bug short description #123"
     git push origin fix/some-bug-short-description-#123
     ```
 
-4. Run tests and linter. This can be done by running local continuous integration and make sure it passes.
+5. Run tests and linter. This can be done by running local continuous integration and make sure it passes.
 
     ```bash
     # run tests
@@ -55,12 +57,12 @@ As a contributor, you are expected to fork this repository, work on your own for
     scarb fmt --check
     ```
 
-5. Go to [OpenZeppelin/cairo-contracts](https://github.com/OpenZeppelin/cairo-contracts) in your web browser and issue a new pull request.
+6. Go to [OpenZeppelin/cairo-contracts](https://github.com/OpenZeppelin/cairo-contracts) in your web browser and issue a new pull request.
     Begin the body of the PR with "Fixes #123" or "Resolves #123" to link the PR to the issue that it is resolving.
     *IMPORTANT* Read the PR template very carefully and make sure to follow all the instructions. These instructions
     refer to some very important conditions that your PR must meet in order to be accepted, such as making sure that all PR checks pass.
 
-6. Maintainers will review your code and possibly ask for changes before your code is pulled in to the main repository. We'll check that all tests pass, review the coding style, and check for general code correctness. If everything is OK, we'll merge your pull request and your code will be part of OpenZeppelin Contracts for Cairo.
+7. Maintainers will review your code and possibly ask for changes before your code is pulled in to the main repository. We'll check that all tests pass, review the coding style, and check for general code correctness. If everything is OK, we'll merge your pull request and your code will be part of OpenZeppelin Contracts for Cairo.
 
     *IMPORTANT* Please pay attention to the maintainer's feedback, since it's a necessary step to keep up with the standards OpenZeppelin Contracts attains to.
 
@@ -82,11 +84,16 @@ If you want to run the documentation UI locally:
     npm run docs:watch
     ```
 
+## Class hashes
+
+Every time there's a language bump or a change in a preset or component used by one, new class hashes should be checked and updated in the presets doc page.
+
 ## Integration tests
 
 Currently, Starknet's test suite has important differences with public networks. We strongly suggest testing new features against a testnet before submitting the PR, to make sure that everything works as expected in a real environment.
 
-We are looking into defining a better process for these integration tests, but for now the PR author/contributor must suggest an approach to test the feature when applicable, which has to be agreed and reproduced by the reviewer.
+We are looking into defining a better process for these integration tests, but in the meantime the PR author/contributor must test the feature in a live network and then share a link to a reviewable transaction.
+Ideally, the transaction should come from a verified contract whose execution can be traced, for the reviewer to evaluate and possibly reproduce.
 
 ## All set
 

diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md
@@ -15,5 +15,6 @@ Fixes #??? <!-- Fill in with issue number -->
 <!-- Some of the items may not apply. -->
 
 - [ ] Tests
-- [ ] Tried the feature on a public network
 - [ ] Documentation
+- [ ] Added entry to CHANGELOG.md <!-- [learn how](https://keepachangelog.com/en/1.1.0/) -->
+- [ ] Tried the feature on a public network <!-- Please share some tx link or proof to confirm proper behavior. -->
diff --git a/RELEASING.md b/RELEASING.md
@@ -1,34 +1,29 @@
 # Releasing
 
-Releasing checklist:
+(1) Checkout the branch to be released. This will usually be `main` except in the event of a hotfix. For hotfixes, checkout the release branch you want to fix.
 
-(1) Write a changelog.
-
-(2) Run version bump script with the new version as an argument and open a PR.
+(2) Create a new release branch.
 
 ```sh
-python scripts/update_version.py v0.5.1
+git checkout -b release-v0.8.0
 ```
 
-(3) Create and push a release branch.
-
-```txt
-git checkout -b release-v0.5.1
-git push release-v0.5.1
-```
+(3) Search and replace the current release version with the one to be released (e.g. `0.7.0` to `0.8.0`, or `0.8.0-beta.0` to `0.8.0-beta.1`).
 
-(4) Checkout the branch to be released. This should be `main` except in the event of a hotfix. For hotfixes, checkout the latest release branch.
+(4) Create the release entry in [the changelog](CHANGELOG.md) with the contents of the _Unreleased_ section, which should be left empty.
 
-(5) Create a tag for the release.
+(5) Push and open a PR targeting `main` to carefully review the release changes.
 
 ```sh
-git tag v0.5.1
+git push release-v0.8.0
 ```
 
-(6) Push the tag to the main repository, [triggering the CI and release process](https://github.com/OpenZeppelin/cairo-contracts/blob/b27101eb826fae73f49751fa384c2a0ff3377af2/.github/workflows/python-app.yml#L60).
+(6) Once merged, create a tag on the release branch and push it to the main repository.
 
 ```sh
-git push origin v0.5.1
+git tag v0.8.0
+git push origin v0.8.0
 ```
 
-(7) Finally, go to the repo's [releases page](https://github.com/OpenZeppelin/cairo-contracts/releases/) and [create a new one](https://github.com/OpenZeppelin/cairo-contracts/releases/new) with the new tag and the base branch as target (which should be `main` except in the event of a hotfix).
+(7) Finally, go to the repo's [releases page](https://github.com/OpenZeppelin/cairo-contracts/releases/) and [create a new one](https://github.com/OpenZeppelin/cairo-contracts/releases/new) with the new tag and the base branch as target (`main` except in the event of a hotfix).
+Make sure to write a detailed release description and a short changelog.
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: true
+    page-sidebar-collapse-default: 'Access Control,Accounts,Introspection,Security,ERC20,ERC721,Upgrades'
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -1,33 +1,40 @@
 * xref:index.adoc[Overview]
-//* xref:wizard.adoc[Wizard]
-//* xref:extensibility.adoc[Extensibility]
-* xref:interfaces.adoc[Interfaces and Dispatchers]
-* xref:upgrades.adoc[Upgrades]
-** xref:/api/upgrades.adoc[API Reference]
+* xref:wizard.adoc[Wizard]
 
-* xref:accounts.adoc[Accounts]
-** xref:/guides/deployment.adoc[Counterfactual deployments]
-** xref:/api/account.adoc[API Reference]
+* Learn
 
-* xref:access.adoc[Access Control]
-** xref:/api/access.adoc[API Reference]
+** xref:components.adoc[Components]
+** xref:presets.adoc[Presets]
+** xref:interfaces.adoc[Interfaces and Dispatchers]
+** xref:guides/deployment.adoc[Counterfactual deployments]
+// ** xref:udc.adoc[Universal Deployer Contract]
 
-* Tokens
-** xref:erc20.adoc[ERC20]
-*** xref:/guides/erc20-supply.adoc[Creating Supply]
-*** xref:/api/erc20.adoc[API Reference]
+* Modules
 
-** xref:erc721.adoc[ERC721]
-*** xref:/api/erc721.adoc[API Reference]
-// ** xref:erc1155.adoc[ERC1155]
+** xref:access.adoc[Access Control]
+*** xref:/api/access.adoc[API Reference]
 
-* xref:security.adoc[Security]
-** xref:/api/security.adoc[API Reference]
+** xref:accounts.adoc[Accounts]
+*** xref:/api/account.adoc[API Reference]
 
-* xref:introspection.adoc[Introspection]
-** xref:/api/introspection.adoc[API Reference]
+** xref:introspection.adoc[Introspection]
+*** xref:/guides/src5-migration.adoc[Migrating ERC165 to SRC5]
+*** xref:/api/introspection.adoc[API Reference]
 
-// * xref:udc.adoc[Universal Deployer Contract]
-// * xref:utilities.adoc[Utilities]
+** xref:security.adoc[Security]
+*** xref:/api/security.adoc[API Reference]
+
+** Tokens
+*** xref:erc20.adoc[ERC20]
+**** xref:/guides/erc20-supply.adoc[Creating Supply]
+**** xref:/api/erc20.adoc[API Reference]
+*** xref:erc721.adoc[ERC721]
+**** xref:/api/erc721.adoc[API Reference]
+// *** xref:erc1155.adoc[ERC1155]
+
+** xref:upgrades.adoc[Upgrades]
+*** xref:/api/upgrades.adoc[API Reference]
+
+** xref:utilities.adoc[Utilities]
 
 * xref:contracts::index.adoc[Contracts for Solidity]
diff --git a/docs/modules/ROOT/pages/accounts.adoc b/docs/modules/ROOT/pages/accounts.adoc
@@ -1,7 +1,7 @@
 :test-signers: https://github.com/OpenZeppelin/cairo-contracts/blob/release-v0.6.1/tests/signers.py
 :snip-5: https://github.com/starknet-io/SNIPs/blob/main/SNIPS/snip-5.md
 :snip-6: https://github.com/ericnordelo/SNIPs/blob/feat/standard-account/SNIPS/snip-6.md
-:counterfactual: xref:/guides/deployment.adoc[Counterfactual deployments]
+:counterfactual: xref:/guides/deployment.adoc[counterfactual deployments]
 
 = Accounts
 

diff --git a/docs/modules/ROOT/pages/api/account.adoc b/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]
+.{presets-page}
+--
+{account-class-hash}
+--
+
 [.contract-index]
 .Constructor
 --

diff --git a/docs/modules/ROOT/pages/api/erc20.adoc b/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]
+.{presets-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`.
diff --git a/docs/modules/ROOT/pages/api/erc721.adoc b/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]
+.{presets-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`.