Skip to content

O
openzeppelin-contracts-upgradeable
Unverified Commit 7acd60d1 by Nicolás Venturo Committed by GitHub
Options

Add notice about deprecated Crowdsales (#2116) 

* Remove crowdsales from sidebar documentation, add links to old version

* Remove mentions of Crowdsales from the documentation
parent 04490621
Showing with 12 additions and 261 deletions
contracts/payment/escrow/RefundEscrow.sol
...@@ -10,8 +10,7 @@ import "./ConditionalEscrow.sol"; ...@@ -10,8 +10,7 @@ import "./ConditionalEscrow.sol";
* @dev The primary account (that is, the contract that instantiates this * @dev The primary account (that is, the contract that instantiates this
* contract) may deposit, close the deposit period, and allow for either * contract) may deposit, close the deposit period, and allow for either
* withdrawal by the beneficiary, or refunds to the depositors. All interactions * withdrawal by the beneficiary, or refunds to the depositors. All interactions
* with `RefundEscrow` will be made through the primary contract. See the * with `RefundEscrow` will be made through the primary contract.
* `RefundableCrowdsale` contract for an example of `RefundEscrow`’s use.
*/ */
contract RefundEscrow is ConditionalEscrow { contract RefundEscrow is ConditionalEscrow {
enum State { Active, Refunding, Closed } enum State { Active, Refunding, Closed }
......
contracts/token/ERC20/ERC20Pausable.sol
...@@ -7,9 +7,9 @@ import "../../lifecycle/Pausable.sol"; ...@@ -7,9 +7,9 @@ import "../../lifecycle/Pausable.sol";
* @title Pausable token * @title Pausable token
* @dev ERC20 with pausable transfers and allowances. * @dev ERC20 with pausable transfers and allowances.
* *
* Useful if you want to stop trades until the end of a crowdsale, or have * Useful for scenarios such as preventing trades until the end of an evaluation
* an emergency switch for freezing all token transfers in the event of a large * period, or having an emergency switch for freezing all token transfers in the
* bug. * event of a large bug.
*/ */
contract ERC20Pausable is ERC20, Pausable { contract ERC20Pausable is ERC20, Pausable {
/** /**
......
docs/modules/ROOT/nav.adoc
...@@ -5,7 +5,6 @@ ...@@ -5,7 +5,6 @@
* xref:tokens.adoc[Tokens] * xref:tokens.adoc[Tokens]
** xref:erc20.adoc[ERC20] ** xref:erc20.adoc[ERC20]
*** xref:erc20-supply.adoc[Creating Supply] *** xref:erc20-supply.adoc[Creating Supply]
*** xref:crowdsales.adoc[Crowdsales]
** xref:erc721.adoc[ERC721] ** xref:erc721.adoc[ERC721]
** xref:erc777.adoc[ERC777] ** xref:erc777.adoc[ERC777]
......
docs/modules/ROOT/pages/crowdsales.adoc
= Crowdsales = Crowdsales
Crowdsales are a popular use for Ethereum; they let you allocate tokens to network participants in various ways, mostly in exchange for Ether. They come in a variety of shapes and flavors, so let's go over the various types available in OpenZeppelin Contracts and how to use them. 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.
Crowdsales have a bunch of different properties, but here are some important ones: They are however still available on the v2.5 release of OpenZeppelin Contracts, which you can install by running:
* Price & Rate Configuration ```console
* Does your crowdsale sell tokens at a fixed price? $ npm install @openzeppelin/contracts@v2.5
* Does the price change over time or as a function of demand? ```
* Emission
* How is this token actually sent to participants?
* Validation — Who is allowed to purchase tokens?
* Are there KYC / AML checks?
* Is there a max cap on tokens?
* What if that cap is per-participant?
* Is there a starting and ending time frame?
* Distribution
* Does distribution of funds happen in real-time or after the crowdsale?
* Can participants receive a refund if the goal is not met?
To manage all of the different combinations and flavors of crowdsales, Contracts provides a highly configurable xref:api:crowdsale.adoc#Crowdsale[`Crowdsale`] base contract that can be combined with various other functionalities to construct a bespoke crowdsale. Refer to the https://docs.openzeppelin.com/contracts/2.x/crowdsales[v2.x documentation] when working with them.
[[crowdsale-rate]]
== Crowdsale Rate
Understanding the rate of a crowdsale is super important, and mistakes here are a common source of bugs.
✨ *HOLD UP FAM THIS IS IMPORTANT* ✨
Firstly, *all currency math is done in the smallest unit of that currency and converted to the correct decimal places when _displaying_ the currency*.
This means that when you do math in your smart contracts, you need to understand that you're adding, dividing, and multiplying the smallest amount of a currency (like wei), _not_ the commonly-used displayed value of the currency (Ether).
In Ether, the smallest unit of the currency is wei, and `1 ETH === 10^18 wei`. In tokens, the process is _very similar_: `1 TKN === 10^(decimals) TKNbits`.
* The smallest unit of a token is "bits" or `TKNbits`.
* The display value of a token is `TKN`, which is `TKNbits * 10^(decimals)`
What people usually call "one token" is actually a bunch of TKNbits, displayed to look like `1 TKN`. This is the same relationship that Ether and wei have. And what you're _always_ doing calculations in is *TKNbits and wei*.
So, if you want to issue someone "one token for every 2 wei" and your decimals are 18, your rate is `0.5e18`. Then, when I send you `2 wei`, your crowdsale issues me `2 * 0.5e18 TKNbits`, which is exactly equal to `10^18 TKNbits` and is displayed as `1 TKN`.
If you want to issue someone "`1 TKN` for every `1 ETH`", and your decimals are 18, your rate is `1`. This is because what's actually happening with the math is that the contract sees a user send `10^18 wei`, not `1 ETH`. Then it uses your rate of 1 to calculate `TKNbits = rate * wei`, or `1 * 10^18`, which is still `10^18`. And because your decimals are 18, this is displayed as `1 TKN`.
One more for practice: if I want to issue "1 TKN for every dollar (USD) in Ether", we would calculate it as follows:
* assume 1 ETH == $400
* therefore, 10^18 wei = $400
* therefore, 1 USD is `10^18 / 400`, or `2.5 * 10^15 wei`
* we have a decimals of 18, so we'll use `10 ^ 18 TKNbits` instead of `1 TKN`
* therefore, if the participant sends the crowdsale `2.5 * 10^15 wei` we should give them `10 ^ 18 TKNbits`
* therefore the rate is `2.5 * 10^15 wei === 10^18 TKNbits`, or `1 wei = 400 TKNbits`
* therefore, our rate is `400`
(this process is pretty straightforward when you keep 18 decimals, the same as Ether/wei)
[[token-emission]]
== Token Emission
One of the first decisions you have to make is "how do I get these tokens to users?". This is usually done in one of three ways:
* (default) — The `Crowdsale` contract owns tokens and simply transfers tokens from its own ownership to users that purchase them.
* xref:api:crowdsale.adoc#MintedCrowdsale[`MintedCrowdsale`] — The `Crowdsale` mints tokens when a purchase is made.
* xref:api:crowdsale.adoc#AllowanceCrowdsale[`AllowanceCrowdsale`] — The `Crowdsale` is granted an allowance to another wallet (like a Multisig) that already owns the tokens to be sold in the crowdsale.
[[default-emission]]
=== Default Emission
In the default scenario, your crowdsale must own the tokens that are sold. You can send the crowdsale tokens through a variety of methods, but here's what it looks like in Solidity:
[source,solidity]
----
IERC20(tokenAddress).transfer(CROWDSALE_ADDRESS, SOME_TOKEN_AMOUNT);
----
Then when you deploy your crowdsale, simply tell it about the token
[source,solidity]
----
new Crowdsale(
1, // rate in TKNbits
MY_WALLET, // address where Ether is sent
TOKEN_ADDRESS // the token contract address
);
----
[[minted-crowdsale]]
=== Minted Crowdsale
To use a xref:api:crowdsale.adoc#MintedCrowdsale[`MintedCrowdsale`], your token must also be a xref:api:token/ERC20.adoc#ERC20Mintable[`ERC20Mintable`] token that the crowdsale has permission to mint from. This can look like:
[source,solidity]
----
contract MyToken is ERC20, ERC20Mintable {
// ... see "Tokens" for more info
}
contract MyCrowdsale is Crowdsale, MintedCrowdsale {
constructor(
uint256 rate, // rate in TKNbits
address payable wallet,
IERC20 token
)
MintedCrowdsale()
Crowdsale(rate, wallet, token)
public
{
}
}
contract MyCrowdsaleDeployer {
constructor()
public
{
// create a mintable token
ERC20Mintable token = new MyToken();
// create the crowdsale and tell it about the token
Crowdsale crowdsale = new MyCrowdsale(
1, // rate, still in TKNbits
msg.sender, // send Ether to the deployer
token // the token
);
// transfer the minter role from this contract (the default)
// to the crowdsale, so it can mint tokens
token.addMinter(address(crowdsale));
token.renounceMinter();
}
}
----
[[allowancecrowdsale]]
=== AllowanceCrowdsale
Use an xref:api:crowdsale.adoc#AllowanceCrowdsale[`AllowanceCrowdsale`] to send tokens from another wallet to the participants of the crowdsale. In order for this to work, the source wallet must give the crowdsale an allowance via the ERC20 xref:api:token/ERC20.adoc#IERC20-approve-address-uint256-[`approve`] method.
[source,solidity]
----
contract MyCrowdsale is Crowdsale, AllowanceCrowdsale {
constructor(
uint256 rate,
address payable wallet,
IERC20 token,
address tokenWallet // <- new argument
)
AllowanceCrowdsale(tokenWallet) // <- used here
Crowdsale(rate, wallet, token)
public
{
}
}
----
Then after the crowdsale is created, don't forget to approve it to use your tokens!
[source,solidity]
----
IERC20(tokenAddress).approve(CROWDSALE_ADDRESS, SOME_TOKEN_AMOUNT);
----
[[validation]]
== Validation
There are a bunch of different validation requirements that your crowdsale might be a part of:
* xref:api:crowdsale.adoc#CappedCrowdsale[`CappedCrowdsale`] — adds a cap to your crowdsale, invalidating any purchases that would exceed that cap
* xref:api:crowdsale.adoc#IndividuallyCappedCrowdsale[`IndividuallyCappedCrowdsale`] — caps an individual's contributions.
* xref:api:crowdsale.adoc#WhitelistCrowdsale[`WhitelistCrowdsale`] — only allow whitelisted participants to purchase tokens. this is useful for putting your KYC / AML whitelist on-chain!
* xref:api:crowdsale.adoc#TimedCrowdsale[`TimedCrowdsale`] — adds an xref:api:crowdsale.adoc#TimedCrowdsale-openingTime--[`openingTime`] and xref:api:Crowdsale.adoc#TimedCrowdsale-closingTime--[`closingTime`] to your crowdsale
Simply mix and match these crowdsale flavors to your heart's content:
[source,solidity]
----
contract MyCrowdsale is Crowdsale, CappedCrowdsale, TimedCrowdsale {
constructor(
uint256 rate, // rate, in TKNbits
address payable wallet, // wallet to send Ether
IERC20 token, // the token
uint256 cap, // total cap, in wei
uint256 openingTime, // opening time in unix epoch seconds
uint256 closingTime // closing time in unix epoch seconds
)
CappedCrowdsale(cap)
TimedCrowdsale(openingTime, closingTime)
Crowdsale(rate, wallet, token)
public
{
// nice, we just created a crowdsale that's only open
// for a certain amount of time
// and stops accepting contributions once it reaches `cap`
}
}
----
[[distribution]]
== Distribution
There comes a time in every crowdsale's life where it must relinquish the tokens it's been entrusted with. It's your decision as to when that happens!
The default behavior is to release tokens as participants purchase them, but sometimes that may not be desirable. For example, what if we want to give users a refund if we don't hit a minimum raised in the sale? Or, maybe we want to wait until after the sale is over before users can claim their tokens and start trading them, perhaps for compliance reasons?
OpenZeppelin Contracts is here to make that easy!
[[postdeliverycrowdsale]]
=== PostDeliveryCrowdsale
The xref:api:crowdsale.adoc#PostDeliveryCrowdsale[`PostDeliveryCrowdsale`], as its name implies, distributes tokens after the crowdsale has finished, letting users call xref:api:crowdsale.adoc#PostDeliveryCrowdsale-withdrawTokens_address-[`withdrawTokens`] in order to claim the tokens they've purchased.
[source,solidity]
----
contract MyCrowdsale is Crowdsale, TimedCrowdsale, PostDeliveryCrowdsale {
constructor(
uint256 rate, // rate, in TKNbits
address payable wallet, // wallet to send Ether
IERC20 token, // the token
uint256 openingTime, // opening time in unix epoch seconds
uint256 closingTime // closing time in unix epoch seconds
)
PostDeliveryCrowdsale()
TimedCrowdsale(openingTime, closingTime)
Crowdsale(rate, wallet, token)
public
{
// nice! this Crowdsale will keep all of the tokens until the end of the crowdsale
// and then users can `withdrawTokens()` to get the tokens they're owed
}
}
----
[[refundablecrowdsale]]
=== RefundableCrowdsale
The xref:api:crowdsale.adoc#RefundableCrowdsale[`RefundableCrowdsale`] offers to refund users if a minimum goal is not reached. If the goal is not reached, the users can xref:api:crowdsale.adoc#RefundableCrowdsale-claimRefund-address-payable-[`claimRefund`] to get their Ether back.
[source,solidity]
----
contract MyCrowdsale is Crowdsale, RefundableCrowdsale {
constructor(
uint256 rate, // rate, in TKNbits
address payable wallet, // wallet to send Ether
IERC20 token, // the token
uint256 goal // the minimum goal, in wei
)
RefundableCrowdsale(goal)
Crowdsale(rate, wallet, token)
public
{
// nice! this crowdsale will, if it doesn't hit `goal`, allow everyone to get their money back
// by calling claimRefund(...)
}
}
----
docs/modules/ROOT/pages/gsn.adoc
...@@ -6,7 +6,7 @@ If you're new to the GSN, you probably want to first take a look at the xref:lea ...@@ -6,7 +6,7 @@ If you're new to the GSN, you probably want to first take a look at the xref:lea
== Receiving a Relayed Call == Receiving a Relayed Call
The first step to writing a recipient is to inherit from our GSNRecipient contract. If you're also inheriting from other contracts, such as ERC20 or Crowdsale, this will work just fine: adding GSNRecipient to all of your token or crowdsale functions will make them GSN-callable. The first step to writing a recipient is to inherit from our GSNRecipient contract. If you're also inheriting from other contracts, such as ERC20, this will work just fine: adding GSNRecipient will make all of your token functions GSN-callable.
```solidity ```solidity
import "@openzeppelin/contracts/GSN/GSNRecipient.sol"; import "@openzeppelin/contracts/GSN/GSNRecipient.sol";
......
docs/modules/ROOT/pages/index.adoc
...@@ -47,7 +47,7 @@ To keep your system secure, you should **always** use the installed code as-is, ...@@ -47,7 +47,7 @@ To keep your system secure, you should **always** use the installed code as-is,
The guides in the sidebar will teach about different concepts, and how to use the related contracts that OpenZeppelin Contracts provides: The guides in the sidebar will teach about different concepts, and how to use the related contracts that OpenZeppelin Contracts provides:
* xref:access-control.adoc[Access Control]: decide who can perform each of the actions on your system. * xref:access-control.adoc[Access Control]: decide who can perform each of the actions on your system.
* xref:tokens.adoc[Tokens]: create tradeable assets or collectives, and distribute them via xref:crowdsales.adoc[Crowdsales]. * xref:tokens.adoc[Tokens]: create tradeable assets or collectibles, like the well known xref:erc20.adoc[ERC20] and xref:erc721.adoc[ERC721] standards.
* xref:gsn.adoc[Gas Station Network]: let your users interact with your contracts without having to pay for gas themselves. * xref:gsn.adoc[Gas Station Network]: let your users interact with your contracts without having to pay for gas themselves.
* xref:utilities.adoc[Utilities]: generic useful tools, including non-overflowing math, signature verification, and trustless paying systems. * xref:utilities.adoc[Utilities]: generic useful tools, including non-overflowing math, signature verification, and trustless paying systems.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment