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

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

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()

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

wallet() → address payable

rate() → uint256

weiRaised() → uint256

buyTokens(address beneficiary)

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)

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)

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)

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)

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

_updatePurchasingState(address beneficiary, uint256 weiAmount)

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

_getTokenAmount(uint256 weiAmount) → uint256

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

_forwardFunds()

Determines how ETH is stored/forwarded on purchases.

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

Emission

AllowanceCrowdsale

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

Modifiers

constructor(address tokenWallet)

Constructor, takes token wallet address.

tokenWallet() → address

remainingTokens() → uint256

Checks the amount of tokens left in the allowance.

_deliverTokens(address beneficiary, uint256 tokenAmount)

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

_deliverTokens(address beneficiary, uint256 tokenAmount)

Overrides delivery by minting tokens upon purchase.

Validation

CappedCrowdsale

Crowdsale with a limit for total contributions.

Modifiers

constructor(uint256 cap)

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

cap() → uint256

capReached() → bool

Checks whether the cap has been reached.

_preValidatePurchase(address beneficiary, uint256 weiAmount)

Extend parent behavior requiring purchase to respect the funding cap.

IndividuallyCappedCrowdsale

Crowdsale with per-beneficiary caps.

setCap(address beneficiary, uint256 cap)

Sets a specific beneficiary’s maximum contribution.

getCap(address beneficiary) → uint256

Returns the cap of a specific beneficiary.

getContribution(address beneficiary) → uint256

Returns the amount contributed so far by a specific beneficiary.

_preValidatePurchase(address beneficiary, uint256 weiAmount)

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

_updatePurchasingState(address beneficiary, uint256 weiAmount)

Extend parent behavior to update beneficiary contributions.

TimedCrowdsale

Crowdsale accepting contributions only within a time frame.

onlyWhileOpen()

Reverts if not in crowdsale time range.

constructor(uint256 openingTime, uint256 closingTime)

Constructor, takes crowdsale opening and closing times.

openingTime() → uint256

closingTime() → uint256

isOpen() → bool

hasClosed() → bool

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

_preValidatePurchase(address beneficiary, uint256 weiAmount)

Extend parent behavior requiring to be within contributing period.

_extendTime(uint256 newClosingTime)

Extend crowdsale.

TimedCrowdsaleExtended(uint256 prevClosingTime, uint256 newClosingTime)

Distribution

FinalizableCrowdsale

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

constructor()

finalized() → bool

finalize()

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

_finalization()

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

CrowdsaleFinalized()

PostDeliveryCrowdsale

Crowdsale that locks tokens from withdrawal until it ends.

constructor()

withdrawTokens(address beneficiary)

Withdraw tokens only after crowdsale ends.

balanceOf(address account) → uint256

_processPurchase(address beneficiary, uint256 tokenAmount)

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.

constructor(uint256 goal)

Constructor, creates RefundEscrow.

goal() → uint256

claimRefund(address payable refundee)

Investors can claim refunds here if crowdsale is unsuccessful.

goalReached() → bool

Checks whether funding goal was reached.

_finalization()

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

_forwardFunds()

Overrides Crowdsale fund forwarding, sending funds to escrow.