Crowdsales

This page is incomplete. We’re working to improve it for the next release. Stay tuned!

Core

Crowdsale

Crowdsale is a base contract for managing a token crowdsale, allowing investors to purchase tokens with ether. This contract implements such functionality in its most fundamental form and can be extended to provide additional functionality and/or custom behavior. The external interface represents the basic interface for purchasing tokens, and conforms the base architecture for crowdsales. It is not intended to be modified / overridden. The internal interface conforms the extensible and modifiable surface of crowdsales. Override the methods to add functionality. Consider using 'super' where appropriate to concatenate behavior.

Modifiers
ReentrancyGuard

constructor(uint256 rate, address payable wallet, contract IERC20 token) public

The rate is the conversion between wei and the smallest and indivisible token unit. So, if you are using a rate of 1 with a ERC20Detailed token with 3 decimals called TOK, 1 wei will give you 1 unit, or 0.001 TOK.

fallback() external

fallback function DO NOT OVERRIDE Note that other contracts will transfer funds with a base gas stipend of 2300, which is not enough to call buyTokens. Consider calling buyTokens directly when purchasing tokens from a contract.

token() → contract IERC20 public

wallet() → address payable public

rate() → uint256 public

weiRaised() → uint256 public

buyTokens(address beneficiary) public

low level token purchase DO NOT OVERRIDE This function has a non-reentrancy guard, so it shouldn’t be called by another nonReentrant function.

_preValidatePurchase(address beneficiary, uint256 weiAmount) internal

Validation of an incoming purchase. Use require statements to revert state when conditions are not met. Use super in contracts that inherit from Crowdsale to extend their validations. Example from CappedCrowdsale.sol’s _preValidatePurchase method: super._preValidatePurchase(beneficiary, weiAmount); require(weiRaised().add(weiAmount) ⇐ cap);

_postValidatePurchase(address beneficiary, uint256 weiAmount) internal

Validation of an executed purchase. Observe state and use revert statements to undo rollback when valid conditions are not met.

_deliverTokens(address beneficiary, uint256 tokenAmount) internal

Source of tokens. Override this method to modify the way in which the crowdsale ultimately gets and sends its tokens.

_processPurchase(address beneficiary, uint256 tokenAmount) internal

Executed when a purchase has been validated and is ready to be executed. Doesn’t necessarily emit/send tokens.

_updatePurchasingState(address beneficiary, uint256 weiAmount) internal

Override for extensions that require an internal state to check for validity (current user contributions, etc.)

_getTokenAmount(uint256 weiAmount) → uint256 internal

Override to extend the way in which ether is converted to tokens.

_forwardFunds() internal

Determines how ETH is stored/forwarded on purchases.

TokensPurchased(address purchaser, address beneficiary, uint256 value, uint256 amount) event

Price

IncreasingPriceCrowdsale

Extension of Crowdsale contract that increases the price of tokens linearly in time. Note that what should be provided to the constructor is the initial and final rates, that is, the amount of tokens per wei contributed. Thus, the initial rate must be greater than the final rate.

Modifiers
TimedCrowdsale
ReentrancyGuard

constructor(uint256 initialRate, uint256 finalRate) public

Constructor, takes initial and final rates of tokens received per wei contributed.

rate() → uint256 public

initialRate() → uint256 public

finalRate() → uint256 public

getCurrentRate() → uint256 public

Returns the rate of tokens per wei at the present time. Note that, as price increases with time, the rate decreases.

_getTokenAmount(uint256 weiAmount) → uint256 internal

Overrides parent method taking into account variable rate.

Emission

AllowanceCrowdsale

Extension of Crowdsale where tokens are held by a wallet, which approves an allowance to the crowdsale.

Modifiers
ReentrancyGuard

constructor(address tokenWallet) public

Constructor, takes token wallet address.

tokenWallet() → address public

remainingTokens() → uint256 public

Checks the amount of tokens left in the allowance.

_deliverTokens(address beneficiary, uint256 tokenAmount) internal

Overrides parent behavior by transferring tokens from wallet.

MintedCrowdsale

Extension of Crowdsale contract whose tokens are minted in each purchase. Token ownership should be transferred to MintedCrowdsale for minting.

Modifiers
ReentrancyGuard

_deliverTokens(address beneficiary, uint256 tokenAmount) internal

Overrides delivery by minting tokens upon purchase.

Validation

CappedCrowdsale

Crowdsale with a limit for total contributions.

Modifiers
ReentrancyGuard

constructor(uint256 cap) public

Constructor, takes maximum amount of wei accepted in the crowdsale.

cap() → uint256 public

capReached() → bool public

Checks whether the cap has been reached.

_preValidatePurchase(address beneficiary, uint256 weiAmount) internal

Extend parent behavior requiring purchase to respect the funding cap.

IndividuallyCappedCrowdsale

Crowdsale with per-beneficiary caps.

Modifiers
CapperRole
ReentrancyGuard

setCap(address beneficiary, uint256 cap) external

Sets a specific beneficiary’s maximum contribution.

getCap(address beneficiary) → uint256 public

Returns the cap of a specific beneficiary.

getContribution(address beneficiary) → uint256 public

Returns the amount contributed so far by a specific beneficiary.

_preValidatePurchase(address beneficiary, uint256 weiAmount) internal

Extend parent behavior requiring purchase to respect the beneficiary’s funding cap.

_updatePurchasingState(address beneficiary, uint256 weiAmount) internal

Extend parent behavior to update beneficiary contributions.

PausableCrowdsale

Extension of Crowdsale contract where purchases can be paused and unpaused by the pauser role.

Modifiers
PauserRole
ReentrancyGuard

_preValidatePurchase(address _beneficiary, uint256 _weiAmount) internal

Validation of an incoming purchase. Use require statements to revert state when conditions are not met. Use super to concatenate validations. Adds the validation that the crowdsale must not be paused.

TimedCrowdsale

Crowdsale accepting contributions only within a time frame.

Modifiers

onlyWhileOpen() modifier

Reverts if not in crowdsale time range.

constructor(uint256 openingTime, uint256 closingTime) public

Constructor, takes crowdsale opening and closing times.

openingTime() → uint256 public

closingTime() → uint256 public

isOpen() → bool public

hasClosed() → bool public

Checks whether the period in which the crowdsale is open has already elapsed.

_preValidatePurchase(address beneficiary, uint256 weiAmount) internal

Extend parent behavior requiring to be within contributing period.

_extendTime(uint256 newClosingTime) internal

Extend crowdsale.

TimedCrowdsaleExtended(uint256 prevClosingTime, uint256 newClosingTime) event

Distribution

FinalizableCrowdsale

Extension of TimedCrowdsale with a one-off finalization action, where one can do extra work after finishing.

Modifiers
TimedCrowdsale
ReentrancyGuard

constructor() internal

finalized() → bool public

finalize() public

Must be called after crowdsale ends, to do some extra finalization work. Calls the contract’s finalization function.

_finalization() internal

Can be overridden to add finalization logic. The overriding function should call super._finalization() to ensure the chain of finalization is executed entirely.

CrowdsaleFinalized() event

PostDeliveryCrowdsale

Crowdsale that locks tokens from withdrawal until it ends.

Modifiers
TimedCrowdsale
ReentrancyGuard

withdrawTokens(address beneficiary) public

Withdraw tokens only after crowdsale ends.

balanceOf(address account) → uint256 public

_processPurchase(address beneficiary, uint256 tokenAmount) internal

Overrides parent by storing due balances, and delivering tokens to the vault instead of the end user. This ensures that the tokens will be available by the time they are withdrawn (which may not be the case if _deliverTokens was called later).

RefundableCrowdsale

Extension of FinalizableCrowdsale contract that adds a funding goal, and the possibility of users getting a refund if goal is not met.

Deprecated, use RefundablePostDeliveryCrowdsale instead. Note that if you allow tokens to be traded before the goal is met, then an attack is possible in which the attacker purchases tokens from the crowdsale and when they sees that the goal is unlikely to be met, they sell their tokens (possibly at a discount). The attacker will be refunded when the crowdsale is finalized, and the users that purchased from them will be left with worthless tokens.

Modifiers
TimedCrowdsale
ReentrancyGuard

constructor(uint256 goal) public

Constructor, creates RefundEscrow.

goal() → uint256 public

claimRefund(address payable refundee) public

Investors can claim refunds here if crowdsale is unsuccessful.

goalReached() → bool public

Checks whether funding goal was reached.

_finalization() internal

Escrow finalization task, called when finalize() is called.

_forwardFunds() internal

Overrides Crowdsale fund forwarding, sending funds to escrow.

RefundablePostDeliveryCrowdsale

Extension of RefundableCrowdsale contract that only delivers the tokens once the crowdsale has closed and the goal met, preventing refunds to be issued to token holders.

Modifiers
TimedCrowdsale
ReentrancyGuard

withdrawTokens(address beneficiary) public