polkamarkets-js 3.4.1 → 3.4.2

package/lib/openzeppelin-contracts-upgradeable.git/docs/modules/ROOT/pages/crosschain.adoc

@@ -1,210 +0,0 @@
-= Adding cross-chain support to contracts
-
-If your contract is targeting to be used in the context of multichain operations, you may need specific tools to identify and process these cross-chain operations.
-
-OpenZeppelin provides the xref:api:crosschain.adoc#CrossChainEnabled[`CrossChainEnabled`] abstract contract, that includes dedicated internal functions.
-
-In this guide, we will go through an example use case: _how to build an upgradeable & mintable ERC20 token controlled by a governor present on a foreign chain_.
-
-== Starting point, our ERC20 contract
-
-Let's start with a small ERC20 contract, that we bootstrapped using the https://wizard.openzeppelin.com/[OpenZeppelin Contracts Wizard], and extended with an owner that has the ability to mint. Note that for demonstration purposes we have not used the built-in `Ownable` contract.
-
-[source,solidity]
-----
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.4;
-
-import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
-import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
-import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
-
-contract MyToken is Initializable, ERC20Upgradeable, UUPSUpgradeable {
-    address public owner;
-
-    modifier onlyOwner() {
-        require(owner == _msgSender(), "Not authorized");
-        _;
-    }
-
-    /// @custom:oz-upgrades-unsafe-allow constructor
-    constructor() initializer {}
-
-    function initialize(address initialOwner) initializer public {
-        __ERC20_init("MyToken", "MTK");
-        __UUPSUpgradeable_init();
-
-        owner = initialOwner;
-    }
-
-    function mint(address to, uint256 amount) public onlyOwner {
-        _mint(to, amount);
-    }
-
-    function _authorizeUpgrade(address newImplementation) internal override onlyOwner {
-    }
-}
-----
-
-This token is mintable and upgradeable by the owner of the contract.
-
-== Preparing our contract for cross-chain operations.
-
-Let's now imagine that this contract is going to live on one chain, but we want the minting and the upgrading to be performed by a xref:governance.adoc[`governor`] contract on another chain.
-
-For example, we could have our token on xDai, with our governor on mainnet, or we could have our token on mainnet, with our governor on optimism
-
-In order to do that, we will start by adding xref:api:crosschain.adoc#CrossChainEnabled[`CrossChainEnabled`] to our contract. You will notice that the contract is now abstract. This is because `CrossChainEnabled` is an abstract contract: it is not tied to any particular chain and it deals with cross-chain interactions in an abstract way. This is what enables us to easily reuse the code for different chains. We will specialize it later by inheriting from a chain-specific implementation of the abstraction.
-
-```diff
- import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
-+import "@openzeppelin/contracts-upgradeable/crosschain/CrossChainEnabled.sol";
-
--contract MyToken is Initializable, ERC20Upgradeable, UUPSUpgradeable {
-+abstract contract MyTokenCrossChain is Initializable, ERC20Upgradeable, UUPSUpgradeable, CrossChainEnabled {
-```
-
-Once that is done, we can use the `onlyCrossChainSender` modifier, provided by `CrossChainEnabled` in order to protect the minting and upgrading operations.
-
-```diff
--    function mint(address to, uint256 amount) public onlyOwner {
-+    function mint(address to, uint256 amount) public onlyCrossChainSender(owner) {
-
--    function _authorizeUpgrade(address newImplementation) internal override onlyOwner {
-+    function _authorizeUpgrade(address newImplementation) internal override onlyCrossChainSender(owner) {
-```
-
-This change will effectively restrict the mint and upgrade operations to the `owner` on the remote chain.
-
-== Specializing for a specific chain
-
-Once the abstract cross-chain version of our token is ready we can easily specialize it for the chain we want, or more precisely for the bridge system that we want to rely on.
-
-This is done using one of the many `CrossChainEnabled` implementations.
-
-For example, if our token is on xDai, and our governor on mainnet, we can use the https://docs.tokenbridge.net/amb-bridge/about-amb-bridge[AMB] bridge available on xDai at https://blockscout.com/xdai/mainnet/address/0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59[0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59]
-
-[source,solidity]
-----
-[...]
-
-import "@openzeppelin/contracts-upgradeable/crosschain/amb/CrossChainEnabledAMB.sol";
-
-contract MyTokenXDAI is
-    MyTokenCrossChain,
-    CrossChainEnabledAMB(0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59)
-{}
-----
-
-If the token is on Ethereum mainnet, and our governor on Optimism, we use the Optimism https://community.optimism.io/docs/protocol/protocol-2.0/#l1crossdomainmessenger[CrossDomainMessenger] available on mainnet at https://etherscan.io/address/0x25ace71c97B33Cc4729CF772ae268934F7ab5fA1[0x25ace71c97B33Cc4729CF772ae268934F7ab5fA1].
-
-[source,solidity]
-----
-[...]
-
-import "@openzeppelin/contracts-upgradeable/crosschain/optimismCrossChainEnabledOptimism.sol";
-
-contract MyTokenOptimism is
-    MyTokenCrossChain,
-    CrossChainEnabledOptimism(0x25ace71c97B33Cc4729CF772ae268934F7ab5fA1)
-{}
-----
-
-== Mixing cross domain addresses is dangerous
-
-When designing a contract with cross-chain support, it is essential to understand possible fallbacks and the security assumption that are being made.
-
-In this guide, we are particularly focusing on restricting access to a specific caller. This is usually done (as shown above) using `msg.sender` or `_msgSender()`. However, when going cross-chain, it is not just that simple. Even without considering possible bridge issues, it is important to keep in mind that the same address can correspond to very different entities when considering a multi-chain space. EOA wallets can only execute operations if the wallet's private-key signs the transaction. To our knowledge this is the case in all EVM chains, so a cross-chain message coming from such a wallet is arguably equivalent to a non-cross-chain message by the same wallet. The situation is however very different for smart contracts.
-
-Due to the way smart contract addresses are computed, and the fact that smart contracts on different chains live independent lives, you could have two very different contracts live at the same address on different chains. You could imagine two multisig wallets with different signers using the same address on different chains. You could also see a very basic smart wallet live on one chain at the same address as a full-fledged governor on another chain. Therefore, you should be careful that whenever you give permissions to a specific address, you control with chain this address can act from.
-
-== Going further with access control
-
-In the previous example, we have both an `onlyOwner()` modifier and the `onlyCrossChainSender(owner)` mechanism. We didn't use the xref:access-control.adoc#ownership-and-ownable[`Ownable`] pattern because the ownership transfer mechanism in includes is not designed to work with the owner being a cross-chain entity. Unlike xref:access-control.adoc#ownership-and-ownable[`Ownable`], xref:access-control.adoc#role-based-access-control[`AccessControl`] is more effective at capturing the nuances and can effectively be used to build cross-chain-aware contracts.
-
-Using xref:api:access.adoc#AccessControlCrossChain[`AccessControlCrossChain`] includes both the xref:api:access.adoc#AccessControl[`AccessControl`] core and the xref:api:crosschain.adoc#CrossChainEnabled[`CrossChainEnabled`] abstraction. It also includes some binding to make role management compatible with cross-chain operations.
-
-In the case of the `mint` function, the caller must have the `MINTER_ROLE` when the call originates from the same chain. If the caller is on a remote chain, then the caller should not have the `MINTER_ROLE`, but the "aliased" version (`MINTER_ROLE ^ CROSSCHAIN_ALIAS`). This mitigates the danger described in the previous section by strictly separating local accounts from remote accounts from a different chain. See the xref:api:access.adoc#AccessControlCrossChain[`AccessControlCrossChain`] documentation for more details.
-
-
-```diff
- import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
- import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
-+import "@openzeppelin/contracts-upgradeable/access/AccessControlCrossChainUpgradeable.sol";
-
--abstract contract MyTokenCrossChain is Initializable, ERC20Upgradeable, UUPSUpgradeable, CrossChainEnabled {
-+abstract contract MyTokenCrossChain is Initializable, ERC20Upgradeable, UUPSUpgradeable, AccessControlCrossChainUpgradeable {
-
--    address public owner;
--    modifier onlyOwner() {
--        require(owner == _msgSender(), "Not authorized");
--        _;
--    }
-
-+    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
-+    bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
-
-     function initialize(address initialOwner) initializer public {
-         __ERC20_init("MyToken", "MTK");
-         __UUPSUpgradeable_init();
-+        __AccessControl_init();
-+        _grantRole(_crossChainRoleAlias(DEFAULT_ADMIN_ROLE), initialOwner); // initialOwner is on a remote chain
--        owner = initialOwner;
-     }
-
--    function mint(address to, uint256 amount) public onlyCrossChainSender(owner) {
-+    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
-
--    function _authorizeUpgrade(address newImplementation) internal override onlyCrossChainSender(owner) {
-+    function _authorizeUpgrade(address newImplementation) internal override onlyRole(UPGRADER_ROLE) {
-```
-
-This results in the following, final, code:
-
-[source,solidity]
-----
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.4;
-
-import "@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol";
-import "@openzeppelin/contracts-upgradeable/access/AccessControlCrossChainUpgradeable.sol";
-import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
-import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
-
-abstract contract MyTokenCrossChain is Initializable, ERC20Upgradeable, AccessControlCrossChainUpgradeable, UUPSUpgradeable {
-    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
-    bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
-
-    /// @custom:oz-upgrades-unsafe-allow constructor
-    constructor() initializer {}
-
-    function initialize(address initialOwner) initializer public {
-        __ERC20_init("MyToken", "MTK");
-        __AccessControl_init();
-        __UUPSUpgradeable_init();
-
-        _grantRole(_crossChainRoleAlias(DEFAULT_ADMIN_ROLE), initialOwner); // initialOwner is on a remote chain
-    }
-
-    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
-        _mint(to, amount);
-    }
-
-    function _authorizeUpgrade(address newImplementation) internal onlyRole(UPGRADER_ROLE) override {
-    }
-}
-
-import "@openzeppelin/contracts-upgradeable/crosschain/amb/CrossChainEnabledAMB.sol";
-
-contract MyTokenXDAI is
-    MyTokenCrossChain,
-    CrossChainEnabledAMB(0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59)
-{}
-
-import "@openzeppelin/contracts-upgradeable/crosschain/optimismCrossChainEnabledOptimism.sol";
-
-contract MyTokenOptimism is
-    MyTokenCrossChain,
-    CrossChainEnabledOptimism(0x25ace71c97B33Cc4729CF772ae268934F7ab5fA1)
-{}
-----

package/lib/openzeppelin-contracts-upgradeable.git/docs/modules/ROOT/pages/crowdsales.adoc

@@ -1,11 +0,0 @@
-= Crowdsales
-
-All crowdsale-related contracts were removed from the OpenZeppelin Contracts library on the https://forum.openzeppelin.com/t/openzeppelin-contracts-v3-0-beta-release/2256[v3.0.0 release] due to both a decline in their usage and the complexity associated with migrating them to Solidity v0.6.
-
-They are however still available on the v2.5 release of OpenZeppelin Contracts, which you can install by running:
-
-```console
-$ npm install @openzeppelin/contracts@v2.5
-```
-
-Refer to the https://docs.openzeppelin.com/contracts/2.x/crowdsales[v2.x documentation] when working with them.

package/lib/openzeppelin-contracts-upgradeable.git/docs/modules/ROOT/pages/drafts.adoc

@@ -1,19 +0,0 @@
-= Drafts
-
-All draft contracts were either moved into a different directory or removed from the OpenZeppelin Contracts library on the https://forum.openzeppelin.com/t/openzeppelin-contracts-v3-0-beta-release/2256[v3.0.0 release].
-
-* `ERC20Migrator`: removed.
-* xref:api:token/ERC20.adoc#ERC20Snapshot[`ERC20Snapshot`]: moved to `token/ERC20`.
-* `ERC20Detailed` and `ERC1046`: removed.
-* `TokenVesting`: removed. Pending a replacement that is being discussed in https://github.com/OpenZeppelin/openzeppelin-contracts/issues/1214[`#1214`].
-* xref:api:utils.adoc#Counters[`Counters`]: moved to xref:api:utils.adoc[`utils`].
-* xref:api:utils.adoc#Strings[`Strings`]: moved to xref:api:utils.adoc[`utils`].
-* xref:api:utils.adoc#SignedSafeMath[`SignedSafeMath`]: moved to xref:api:utils.adoc[`utils`].
-
-Removed contracts are still available on the v2.5 release of OpenZeppelin Contracts, which you can install by running:
-
-```console
-$ npm install @openzeppelin/contracts@v2.5
-```
-
-Refer to the xref:2.x@contracts:api:drafts.adoc[v2.x documentation] when working with them.

package/lib/openzeppelin-contracts-upgradeable.git/docs/modules/ROOT/pages/erc1155.adoc

@@ -1,153 +0,0 @@
-= ERC1155
-
-ERC1155 is a novel token standard that aims to take the best from previous standards to create a xref:tokens.adoc#different-kinds-of-tokens[*fungibility-agnostic*] and *gas-efficient* xref:tokens.adoc#but_first_coffee_a_primer_on_token_contracts[token contract].
-
-TIP: ERC1155 draws ideas from all of xref:erc20.adoc[ERC20], xref:erc721.adoc[ERC721], and xref:erc777.adoc[ERC777]. If you're unfamiliar with those standards, head to their guides before moving on.
-
-[[multi-token-standard]]
-== Multi Token Standard
-
-The distinctive feature of ERC1155 is that it uses a single smart contract to represent multiple tokens at once. This is why its xref:api:token/ERC1155.adoc#IERC1155-balanceOf-address-uint256-[`balanceOf`] function differs from ERC20's and ERC777's: it has an additional `id` argument for the identifier of the token that you want to query the balance of.
-
-This is similar to how ERC721 does things, but in that standard a token `id` has no concept of balance: each token is non-fungible and exists or doesn't. The ERC721 xref:api:token/ERC721.adoc#IERC721-balanceOf-address-[`balanceOf`] function refers to _how many different tokens_ an account has, not how many of each. On the other hand, in ERC1155 accounts have a distinct balance for each token `id`, and non-fungible tokens are implemented by simply minting a single one of them.
-
-This approach leads to massive gas savings for projects that require multiple tokens. Instead of deploying a new contract for each token type, a single ERC1155 token contract can hold the entire system state, reducing deployment costs and complexity.
-
-[[batch-operations]]
-== Batch Operations
-
-Because all state is held in a single contract, it is possible to operate over multiple tokens in a single transaction very efficiently. The standard provides two functions, xref:api:token/ERC1155.adoc#IERC1155-balanceOfBatch-address---uint256---[`balanceOfBatch`] and xref:api:token/ERC1155.adoc#IERC1155-safeBatchTransferFrom-address-address-uint256---uint256---bytes-[`safeBatchTransferFrom`], that make querying multiple balances and transferring multiple tokens simpler and less gas-intensive.
-
-In the spirit of the standard, we've also included batch operations in the non-standard functions, such as xref:api:token/ERC1155.adoc#ERC1155-_mintBatch-address-uint256---uint256---bytes-[`_mintBatch`].
-
-== Constructing an ERC1155 Token Contract
-
-We'll use ERC1155 to track multiple items in our game, which will each have their own unique attributes. We mint all items to the deployer of the contract, which we can later transfer to players. Players are free to keep their tokens or trade them with other people as they see fit, as they would any other asset on the blockchain!  
-
-For simplicity we will mint all items in the constructor but you could add minting functionality to the contract to mint on demand to players. 
-
-TIP: For an overview of minting mechanisms check out xref:erc20-supply.adoc[Creating ERC20 Supply].
-
-Here's what a contract for tokenized items might look like:
-
-[source,solidity]
-----
-// contracts/GameItems.sol
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
-
-import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
-
-contract GameItems is ERC1155 {
-    uint256 public constant GOLD = 0;
-    uint256 public constant SILVER = 1;
-    uint256 public constant THORS_HAMMER = 2;
-    uint256 public constant SWORD = 3;
-    uint256 public constant SHIELD = 4;
-
-    constructor() ERC1155("https://game.example/api/item/{id}.json") {
-        _mint(msg.sender, GOLD, 10**18, "");
-        _mint(msg.sender, SILVER, 10**27, "");
-        _mint(msg.sender, THORS_HAMMER, 1, "");
-        _mint(msg.sender, SWORD, 10**9, "");
-        _mint(msg.sender, SHIELD, 10**9, "");
-    }
-}
-----
-
-Note that for our Game Items, Gold is a fungible token whilst Thor's Hammer is a non-fungible token as we minted only one.
-
-The xref:api:token/ERC1155.adoc#ERC1155[`ERC1155`] contract includes the optional extension xref:api:token/ERC1155.adoc#IERC1155MetadataURI[`IERC1155MetadataURI`]. That's where the xref:api:token/ERC1155.adoc#IERC1155MetadataURI-uri-uint256-[`uri`] function comes from: we use it to retrieve the metadata uri.
-
-Also note that, unlike ERC20, ERC1155 lacks a `decimals` field, since each token is distinct and cannot be partitioned.
-
-Once deployed, we will be able to query the deployer’s balance:
-[source,javascript]
-----
-> gameItems.balanceOf(deployerAddress,3)
-1000000000
-----
-
-We can transfer items to player accounts:
-[source,javascript]
-----
-> gameItems.safeTransferFrom(deployerAddress, playerAddress, 2, 1, "0x0")
-> gameItems.balanceOf(playerAddress, 2)
-1
-> gameItems.balanceOf(deployerAddress, 2)
-0
-----
-
-We can also batch transfer items to player accounts and get the balance of batches:
-[source,javascript]
-----
-> gameItems.safeBatchTransferFrom(deployerAddress, playerAddress, [0,1,3,4], [50,100,1,1], "0x0")
-> gameItems.balanceOfBatch([playerAddress,playerAddress,playerAddress,playerAddress,playerAddress], [0,1,2,3,4])
-[50,100,1,1,1]
-----
-
-The metadata uri can be obtained:
-
-[source,javascript]
-----
-> gameItems.uri(2)
-"https://game.example/api/item/{id}.json"
-----
-
-The `uri` can include the string `++{id}++` which clients must replace with the actual token ID, in lowercase hexadecimal (with no 0x prefix) and leading zero padded to 64 hex characters.
-
-For token ID `2` and uri `++https://game.example/api/item/{id}.json++` clients would replace `++{id}++` with `0000000000000000000000000000000000000000000000000000000000000002` to retrieve JSON at `https://game.example/api/item/0000000000000000000000000000000000000000000000000000000000000002.json`.
-
-The JSON document for token ID 2 might look something like:
-
-[source,json]
-----
-{
-    "name": "Thor's hammer",
-    "description": "Mjölnir, the legendary hammer of the Norse god of thunder.",
-    "image": "https://game.example/item-id-8u5h2m.png",
-    "strength": 20
-}
-----
-
-For more information about the metadata JSON Schema, check out the https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1155.md#erc-1155-metadata-uri-json-schema[ERC-1155 Metadata URI JSON Schema].
-
-NOTE: You'll notice that the item's information is included in the metadata, but that information isn't on-chain! So a game developer could change the underlying metadata, changing the rules of the game! 
-
-TIP: If you'd like to put all item information on-chain, you can extend ERC721 to do so (though it will be rather costly) by providing a xref:utilities.adoc#base64[`Base64`] Data URI with the JSON schema encoded. You could also leverage IPFS to store the URI information, but these techniques are out of the scope of this overview guide
-
-[[sending-to-contracts]]
-== Sending Tokens to Contracts
-
-A key difference when using xref:api:token/ERC1155.adoc#IERC1155-safeTransferFrom-address-address-uint256-uint256-bytes-[`safeTransferFrom`] is that token transfers to other contracts may revert with the following message:
-
-[source,text]
-----
-ERC1155: transfer to non ERC1155Receiver implementer
-----
-
-This is a good thing! It means that the recipient contract has not registered itself as aware of the ERC1155 protocol, so transfers to it are disabled to *prevent tokens from being locked forever*. As an example, https://etherscan.io/token/0xa74476443119A942dE498590Fe1f2454d7D4aC0d?a=0xa74476443119A942dE498590Fe1f2454d7D4aC0d[the Golem contract currently holds over 350k `GNT` tokens], worth multiple tens of thousands of dollars, and lacks methods to get them out of there. This has happened to virtually every ERC20-backed project, usually due to user error.
-
-In order for our contract to receive ERC1155 tokens we can inherit from the convenience contract xref:api:token/ERC1155.adoc#ERC1155Holder[`ERC1155Holder`] which handles the registering for us.  Though we need to remember to implement functionality to allow tokens to be transferred out of our contract:
-
-[source,solidity]
-----
-// contracts/MyContract.sol
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
-
-import "@openzeppelin/contracts/token/ERC1155/utils/ERC1155Holder.sol";
-
-contract MyContract is ERC1155Holder {
-}
-----
-
-We can also implement more complex scenarios using the xref:api:token/ERC1155.adoc#IERC1155Receiver-onERC1155Received-address-address-uint256-uint256-bytes-[`onERC1155Received`] and xref:api:token/ERC1155.adoc#IERC1155Receiver-onERC1155BatchReceived-address-address-uint256---uint256---bytes-[`onERC1155BatchReceived`] functions.
-
-[[Presets]]
-== Preset ERC1155 contract
-A preset ERC1155 is available, https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v4.7/contracts/token/ERC1155/presets/ERC1155PresetMinterPauser.sol[`ERC1155PresetMinterPauser`]. It is preset to allow for token minting (create) - including batch minting, stop all token transfers (pause) and allow holders to burn (destroy) their tokens. The contract uses xref:access-control.adoc[Access Control] to control access to the minting and pausing functionality.  The account that deploys the contract will be granted the minter and pauser roles, as well as the default admin role.
-
-This contract is ready to deploy without having to write any Solidity code.  It can be used as-is for quick prototyping and testing, but is also suitable for production environments.
-
-NOTE: Contract presets are now deprecated in favor of https://wizard.openzeppelin.com[Contracts Wizard] as a more powerful alternative.

package/lib/openzeppelin-contracts-upgradeable.git/docs/modules/ROOT/pages/erc20-supply.adoc

@@ -1,113 +0,0 @@
-= Creating ERC20 Supply
-
-In this guide you will learn how to create an ERC20 token with a custom supply mechanism. We will showcase two idiomatic ways to use OpenZeppelin Contracts for this purpose that you will be able to apply to your smart contract development practice.
-
-The standard interface implemented by tokens built on Ethereum is called ERC20, and Contracts includes a widely used implementation of it: the aptly named xref:api:token/ERC20.adoc[`ERC20`] contract. This contract, like the standard itself, is quite simple and bare-bones. In fact, if you try to deploy an instance of `ERC20` as-is it will be quite literally useless... it will have no supply! What use is a token with no supply?
-
-The way that supply is created is not defined in the ERC20 document. Every token is free to experiment with its own mechanisms, ranging from the most decentralized to the most centralized, from the most naive to the most researched, and more.
-
-[[fixed-supply]]
-== Fixed Supply
-
-Let's say we want a token with a fixed supply of 1000, initially allocated to the account that deploys the contract. If you've used Contracts v1, you may have written code like the following:
-
-[source,solidity]
-----
-contract ERC20FixedSupply is ERC20 {
-    constructor() {
-        totalSupply += 1000;
-        balances[msg.sender] += 1000;
-    }
-}
-----
-
-Starting with Contracts v2 this pattern is not only discouraged, but disallowed. The variables `totalSupply` and `balances` are now private implementation details of `ERC20`, and you can't directly write to them. Instead, there is an internal xref:api:token/ERC20.adoc#ERC20-_mint-address-uint256-[`_mint`] function that will do exactly this:
-
-[source,solidity]
-----
-contract ERC20FixedSupply is ERC20 {
-    constructor() ERC20("Fixed", "FIX") {
-        _mint(msg.sender, 1000);
-    }
-}
-----
-
-Encapsulating state like this makes it safer to extend contracts. For instance, in the first example we had to manually keep the `totalSupply` in sync with the modified balances, which is easy to forget. In fact, we omitted something else that is also easily forgotten: the `Transfer` event that is required by the standard, and which is relied on by some clients. The second example does not have this bug, because the internal `_mint` function takes care of it.
-
-[[rewarding-miners]]
-== Rewarding Miners
-
-The internal xref:api:token/ERC20.adoc#ERC20-_mint-address-uint256-[`_mint`] function is the key building block that allows us to write ERC20 extensions that implement a supply mechanism.
-
-The mechanism we will implement is a token reward for the miners that produce Ethereum blocks. In Solidity we can access the address of the current block's miner in the global variable `block.coinbase`. We will mint a token reward to this address whenever someone calls the function `mintMinerReward()` on our token. The mechanism may sound silly, but you never know what kind of dynamic this might result in, and it's worth analyzing and experimenting with!
-
-[source,solidity]
-----
-contract ERC20WithMinerReward is ERC20 {
-    constructor() ERC20("Reward", "RWD") {}
-
-    function mintMinerReward() public {
-        _mint(block.coinbase, 1000);
-    }
-}
-----
-
-As we can see, `_mint` makes it super easy to do this correctly.
-
-[[modularizing-the-mechanism]]
-== Modularizing the Mechanism
-
-There is one supply mechanism already included in Contracts: `ERC20PresetMinterPauser`. This is a generic mechanism in which a set of accounts is assigned the `minter` role, granting them the permission to call a `mint` function, an external version of `_mint`.
-
-This can be used for centralized minting, where an externally owned account (i.e. someone with a pair of cryptographic keys) decides how much supply to create and for whom. There are very legitimate use cases for this mechanism, such as https://medium.com/reserve-currency/why-another-stablecoin-866f774afede#3aea[traditional asset-backed stablecoins].
-
-The accounts with the minter role don't need to be externally owned, though, and can just as well be smart contracts that implement a trustless mechanism. We can in fact implement the same behavior as the previous section.
-
-[source,solidity]
-----
-contract MinerRewardMinter {
-    ERC20PresetMinterPauser _token;
-
-    constructor(ERC20PresetMinterPauser token) {
-        _token = token;
-    }
-
-    function mintMinerReward() public {
-        _token.mint(block.coinbase, 1000);
-    }
-}
-----
-
-This contract, when initialized with an `ERC20PresetMinterPauser` instance, and granted the `minter` role for that contract, will result in exactly the same behavior implemented in the previous section. What is interesting about using `ERC20PresetMinterPauser` is that we can easily combine multiple supply mechanisms by assigning the role to multiple contracts, and moreover that we can do this dynamically.
-
-TIP: To learn more about roles and permissioned systems, head to our xref:access-control.adoc[Access Control guide].
-
-[[automating-the-reward]]
-== Automating the Reward
-
-So far our supply mechanisms were triggered manually, but `ERC20` also allows us to extend the core functionality of the token through the xref:api:token/ERC20.adoc#ERC20-_beforeTokenTransfer-address-address-uint256-[`_beforeTokenTransfer`] hook (see xref:extending-contracts.adoc#using-hooks[Using Hooks]).
-
-Adding to the supply mechanism from previous sections, we can use this hook to mint a miner reward for every token transfer that is included in the blockchain.
-
-[source,solidity]
-----
-contract ERC20WithAutoMinerReward is ERC20 {
-    constructor() ERC20("Reward", "RWD") {}
-
-    function _mintMinerReward() internal {
-        _mint(block.coinbase, 1000);
-    }
-
-    function _beforeTokenTransfer(address from, address to, uint256 value) internal virtual override {
-        if (!(from == address(0) && to == block.coinbase)) {
-          _mintMinerReward();
-        }
-        super._beforeTokenTransfer(from, to, value);
-    }
-}
-----
-
-[[wrapping-up]]
-== Wrapping Up
-
-We've seen two ways to implement ERC20 supply mechanisms: internally through `_mint`, and externally through `ERC20PresetMinterPauser`. Hopefully this has helped you understand how to use OpenZeppelin Contracts and some of the design principles behind it, and you can apply them to your own smart contracts.

package/lib/openzeppelin-contracts-upgradeable.git/docs/modules/ROOT/pages/erc20.adoc

@@ -1,85 +0,0 @@
-= ERC20
-
-An ERC20 token contract keeps track of xref:tokens.adoc#different-kinds-of-tokens[_fungible_ tokens]: any one token is exactly equal to any other token; no tokens have special rights or behavior associated with them. This makes ERC20 tokens useful for things like a *medium of exchange currency*, *voting rights*, *staking*, and more.
-
-OpenZeppelin Contracts provides many ERC20-related contracts. On the xref:api:token/ERC20.adoc[`API reference`] you'll find detailed information on their properties and usage.
-
-[[constructing-an-erc20-token-contract]]
-== Constructing an ERC20 Token Contract
-
-Using Contracts, we can easily create our own ERC20 token contract, which will be used to track _Gold_ (GLD), an internal currency in a hypothetical game.
-
-Here's what our GLD token might look like.
-
-[source,solidity]
-----
-// contracts/GLDToken.sol
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
-
-import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
-
-contract GLDToken is ERC20 {
-    constructor(uint256 initialSupply) ERC20("Gold", "GLD") {
-        _mint(msg.sender, initialSupply);
-    }
-}
-----
-
-Our contracts are often used via https://solidity.readthedocs.io/en/latest/contracts.html#inheritance[inheritance], and here we're reusing xref:api:token/ERC20.adoc#erc20[`ERC20`] for both the basic standard implementation and the xref:api:token/ERC20.adoc#ERC20-name--[`name`], xref:api:token/ERC20.adoc#ERC20-symbol--[`symbol`], and xref:api:token/ERC20.adoc#ERC20-decimals--[`decimals`] optional extensions. Additionally, we're creating an `initialSupply` of tokens, which will be assigned to the address that deploys the contract.
-
-TIP: For a more complete discussion of ERC20 supply mechanisms, see xref:erc20-supply.adoc[Creating ERC20 Supply].
-
-That's it! Once deployed, we will be able to query the deployer's balance:
-
-[source,javascript]
-----
-> GLDToken.balanceOf(deployerAddress)
-1000000000000000000000
-----
-
-We can also xref:api:token/ERC20.adoc#IERC20-transfer-address-uint256-[transfer] these tokens to other accounts:
-
-[source,javascript]
-----
-> GLDToken.transfer(otherAddress, 300000000000000000000)
-> GLDToken.balanceOf(otherAddress)
-300000000000000000000
-> GLDToken.balanceOf(deployerAddress)
-700000000000000000000
-----
-
-[[a-note-on-decimals]]
-== A Note on `decimals`
-
-Often, you'll want to be able to divide your tokens into arbitrary amounts: say, if you own `5 GLD`, you may want to send `1.5 GLD` to a friend, and keep `3.5 GLD` to yourself. Unfortunately, Solidity and the EVM do not support this behavior: only integer (whole) numbers can be used, which poses an issue. You may send `1` or `2` tokens, but not `1.5`.
-
-To work around this, xref:api:token/ERC20.adoc#ERC20[`ERC20`] provides a xref:api:token/ERC20.adoc#ERC20-decimals--[`decimals`] field, which is used to specify how many decimal places a token has. To be able to transfer `1.5 GLD`, `decimals` must be at least `1`, since that number has a single decimal place.
-
-How can this be achieved? It's actually very simple: a token contract can use larger integer values, so that a balance of `50` will represent `5 GLD`, a transfer of `15` will correspond to `1.5 GLD` being sent, and so on.
-
-It is important to understand that `decimals` is _only used for display purposes_. All arithmetic inside the contract is still performed on integers, and it is the different user interfaces (wallets, exchanges, etc.) that must adjust the displayed values according to `decimals`. The total token supply and balance of each account are not specified in `GLD`: you need to divide by `10 ** decimals` to get the actual `GLD` amount.
-
-You'll probably want to use a `decimals` value of `18`, just like Ether and most ERC20 token contracts in use, unless you have a very special reason not to. When minting tokens or transferring them around, you will be actually sending the number `num GLD * (10 ** decimals)`.
-
-NOTE: By default, `ERC20` uses a value of `18` for `decimals`. To use a different value, you will need to override the `decimals()` function in your contract.
-
-```solidity
-function decimals() public view virtual override returns (uint8) {
-  return 16;
-}
-```
-
-So if you want to send `5` tokens using a token contract with 18 decimals, the method to call will actually be:
-
-```solidity
-transfer(recipient, 5 * (10 ** 18));
-```
-
-[[Presets]]
-== Preset ERC20 contract
-A preset ERC20 is available, https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v4.7/contracts/token/ERC20/presets/ERC20PresetMinterPauser.sol[`ERC20PresetMinterPauser`]. It is preset to allow for token minting (create), stop all token transfers (pause) and allow holders to burn (destroy) their tokens. The contract uses xref:access-control.adoc[Access Control] to control access to the minting and pausing functionality.  The account that deploys the contract will be granted the minter and pauser roles, as well as the default admin role.
-
-This contract is ready to deploy without having to write any Solidity code.  It can be used as-is for quick prototyping and testing, but is also suitable for production environments.
-
-NOTE: Contract presets are now deprecated in favor of https://wizard.openzeppelin.com[Contracts Wizard] as a more powerful alternative.