Crowdsale Program Mechanics

Introduction

A public offering to help build brand-new cryptocurrency or other digital assets through crowd contributions is known as a cryptocurrency crowdsale. A crowdsale can be used by new projects to mobilize resources for development and other purposes. It is a time-limited campaign during which crypto owners can exchange their cryptocurrencies for newly proposed tokens, as defined in the campaign. These new tokens are promoted as future functional units once the crowdsale's goal is met and the project launches.

The example of a crowdsale program implementation described in this article is just one of many decentralized applications that can be implemented and launched on Gear. This article explains the programming interface, data structure, basic functions, and their purposes. It can be used as-is or modified to suit specific scenarios. Anyone can easily create a crowdsale application and run it on the Vara network.

The initial resources used to acquire tokens are determined by the Vara fungible tokens contract - VFT. The program's source code is available on GitHub.

Interface

Source Files

1. messages.rs - contains functions for the fungible token contract. The crowdsale program interacts with the fungible token contract through the transfer_tokens function:

crowdsale/src/messages.rs

pub async fn transfer_tokens(
    transaction_id: u64,
    token_address: &ActorId,
    from: &ActorId,
    to: &ActorId,
    amount_tokens: u128,
) -> Result<(), ()>

• transaction_id - identifier of the associated transaction
• from - the sender's account
• to - recipient account
• amount_tokens - number of tokens

This function sends a message (the action is defined in the enum FTokenAction) and gets a reply (the reply is defined in the enum FTokenEvent):

crowdsale/src/messages.rs

let reply = msg::send_for_reply_as::<FTokenAction, FTokenEvent>(
        *token_address,
        FTokenAction::Message {
            transaction_id,
            payload: LogicAction::Transfer {
                sender: *from,
                recipient: *to,
                amount: amount_tokens,
            },
        },
        0,
        0,
    )
    .expect("Error in sending a message `FTokenAction::Message`")
    .await;

match reply {
    Ok(FTokenEvent::Ok) => Ok(()),
    _ => Err(()),
}

2. asserts.rs - contains assert functions: owner_message and not_zero_address.

• owner_message checks if msg::source() is equal to owner. Otherwise, it panics:

crowdsale/src/asserts.rs

pub fn owner_message(owner: &ActorId, message: &str) {
    if msg::source() != *owner {
        panic!("{}: Not owner message", message)
    }
}

• not_zero_address checks if address is not equal to ZERO_ID. Otherwise, it panics:

crowdsale/src/asserts.rs

pub fn not_zero_address(address: &ActorId, message: &str) {
    if address == &ZERO_ID {
        panic!("{}: Zero address", message)
    }
}

3. lib.rs - defines the program logic.

Structs

The program has the following structs:

crowdsale/src/lib.rs

struct IcoContract {
    ico_state: IcoState,
    start_price: u128,
    price_increase_step: u128,
    time_increase_step: u128,
    tokens_sold: u128,
    tokens_goal: u128,
    owner: ActorId,
    token_address: ActorId,
    token_holders: HashMap<ActorId, u128>,
    transaction_id: u64,
    transactions: HashMap<ActorId, u64>,
}

where:

• ico_state is IcoState struct which consists of:

crowdsale/io/src/lib.rs

pub struct IcoState {
    pub ico_started: bool, // true if ICO was started
    pub start_time: u64,   // time when ICO was started, otherwise is zero
    pub duration: u64,     // duration of the ICO, otherwise is zero
    pub ico_ended: bool,   // true if ICO was ended
}

• start_price - initial price of tokens
• price_increase_step - how much the price increases
• time_increase_step - the period of time after which the price increases
• tokens_sold - how many tokens were sold
• tokens_goal - how many tokens are going to be sold
• owner - program owner
• token_address - fungible token address
• token_holders - the list of buyers and the number of tokens they bought

Functions

• Starts the ICO. Only the owner can call it:

crowdsale/src/lib.rs

async fn start_ico(&mut self, config: IcoAction)

replies with:

crowdsale/src/lib.rs

IcoEvent::SaleStarted {
    transaction_id: current_transaction_id,
    duration,
    start_price,
    tokens_goal,
    price_increase_step,
    time_increase_step,
}

• Purchase of tokens. Anyone with enough balance can call and buy tokens:

crowdsale/src/lib.rs

pub fn buy_tokens(&mut self, tokens_cnt: u128)

replies with:

crowdsale/src/lib.rs

IcoEvent::Bought {
    buyer: msg::source(),
    amount: tokens_cnt,
    change,
}

• Ends the ICO. Only the owner can call it:

crowdsale/src/lib.rs

async fn end_sale(&mut self)

replies with:

crowdsale/src/lib.rs

IcoEvent::SaleEnded(current_transaction_id)

Program Metadata and State

Metadata interface description:

crowdsale/io/src/lib.rs

pub struct CrowdsaleMetadata;

impl Metadata for CrowdsaleMetadata {
    type Init = In<IcoInit>;
    type Handle = InOut<IcoAction, IcoEvent>;
    type Others = ();
    type Reply = ();
    type Signal = ();
    type State = Out<State>;
}

To display the full program state information, the state() function is used:

crowdsale/src/lib.rs

#[no_mangle]
extern fn state() {
    let staking = unsafe {
        ICO_CONTRACT
            .take()
            .expect("Unexpected error in taking state")
    };
    msg::reply::<State>(staking.into(), 0)
        .expect("Failed to encode or reply with `State` from `state()`");
}

To display only specific values from the state, write a separate crate. In this crate, specify functions that will return the desired values from the State state. For example, see gear-foundation/dapps/crowdsale/state:

crowdsale/state/src/lib.rs

#[gmeta::metawasm]
pub mod metafns {
    pub type State = crowdsale_io::State;

    pub fn current_price(state: State) -> u128 {
        state.get_current_price()
    }

    pub fn tokens_left(state: State) -> u128 {
        state.get_balance()
    }

    pub fn balance_of(state: State, address: ActorId) -> u128 {
        state.balance_of(&address)
    }
}

Conclusion

The source code of this example of an ICO program and the example of an implementation of its testing is available on Github.

For more details about testing programs written on Vara, refer to the Program Testing article.