eostarter/token-sale-platform

A token sale platform for EOS :rocket:

EOS Token Sale Platform

A decentralized Token Sale platform, which allows users to set up a token sale, determine the token sale parameters, and deploy their sale onto the EOS Mainnet.

• Project Description
• Technical Stack
• Installation
  • Before you Start
  • Project Setup
  • Quick Start
• File Structure
• Technical Specs
  • Infrastructure Diagram
  • Technologies Specification
    • Kubernetes Cluster
    • Web Application
    • Backend
      • Hasura GraphQL Server
      • Hapi REST Server
    • EOSIO Blockchain Technology Integration
• Contributing
• About EOStarter

Project Description

The token sale platform is a decentralized application based on two open-source smart contracts that any project can use to sell its tokens.

• Token Pool Contract

• Token Sale Contract

We are proposing to develop a Token Sale Smart Contract system that allows for the crowdsourcing of projects through a token sale that can be configured with different parameters like staking capabilities, whitelisting requirements, token vesting, etc.

You can read about the full specs of these 2 Smart Contracts here:

TOKENSALE PLATFORM - SCOPE OF WORK

Technical Features

This project features all the latest technologies and practices in the industry.

• Hapi
• Hasura
• React
• Kubernetes
• EOSIO

Installation

Before you Start

Somethings you need before getting started:

• git
• node.js
• docker
• docker-compose

Project Setup

Copy the .env.example then update the environment variables according to your needs.

cp .env.example .env

Quick Start

1. Clone this repo using git clone --depth=1 https://github.com/eostarter/token-sale-platform.git <YOUR_PROJECT_NAME>.
2. Move to the appropriate directory: cd <YOUR_PROJECT_NAME>.
3. Run make run in order to start the project using docker compose.

At this point you can navigate to http://localhost:3000.

File Structure

Within the download you'll find the following directories and files:

├── docs
│   └── img
├── hapi
│   └── src
│       ├── config
│       ├── routes
│       ├── services
│       └── utils
├── hasura
│   ├── metadata
│   ├── migrations
│   └── seeds
├── kubernetes
├── utils
├── wallet
│   └── config
└── webapp
    ├── public
    └── src
        ├── components
        │   ├── Footer
        │   ├── Header
        │   ├── Loader
        │   ├── Message
        │   ├── PageTitle
        │   └── Sidebar
        ├── config
        ├── context
        ├── gql
        ├── language
        ├── layouts
        │   └── Dashboard
        ├── routes
        │   ├── About
        │   ├── Help
        │   ├── Home
        │   └── Route404
        ├── theme
        └── utils

Technical Documentation

Infrastructure Diagram

Technologies Specification

Kubernetes Cluster

At EOS Costa Rica, we build software taking into consideration a high availability of the services that can integrate it. For this, we use Kubernetes, that allows to isolate modules in order to reduce the risk of the system collapsing. In the image above, you can take a look at our representation of the architecture we consider is more suitable to our purposes.

Web Application

This FullStack Template uses React.js as a Frontend Library which together with other tools like Apollo Client, GraphQL and Material UI brings a robust solution for building Single Page Applications out of the box.

Backend

Hasura GraphQL Server

Hasura technology maps a PostgreSQL database and provides a reliable and easy-to-use API. This allow us to focus on critical features of our projects, delegating mechanic CRUD (Create, Read, Update, Delete) operations. Hasura also enables custom REST handling capabilities with the possibility to integrate a custom REST server, that way we can extend the base CRUD functionalities and build custom business logic.

Hapi REST Server

We need to handle REST custom requests coming from the Hasura GraphQL server. For this, we use hapi.dev, which is a simple and easy-to-use backend framework.

EOSIO Blockchain Technology Integration

As a company that delivers EOSIO blockchain-based solutions, we build a template which contains EOSIO integration, specifically eosjs. This allow us to iterate quickly over the more challenging features of our projects.

Contributing

Please Read EOS Costa Rica's Open Source Contributing Guidelines.

Please report bugs big and small by opening an issue

About EOSstarter

EOStarter is a Community-powered Incubator and Gamified Launchpad for EOS projects.

eostarter.org

token-sale-platform's Issues

Login/SignUp

In our case, we want to be able to inform the user when a token sale that he/she subscribed to is launching, and what his/her allocation is based on the requirements (eg. Staked tokens + NFTs). However, the platform could also be built to work ONLY with the connection of the user’s EOS Account.

Not much to add here. User Logs In, connects EOS Account and is ready to go.

Add action to start sale

Add process to claim unsold tokens

Token deposit

Smart Contract Design

Design Smart Contract

• define situation an approach
• define user roles
• define data model
• define actions
• define pre and post conditions

Validate investor user on subscribe action

Reject pool

Allocation (account limit)

Allocation is calculated dynamically

depends on

• subscribed and whitelisted?
• has tart tokens and NFTS?

more tart tokens and staked NFTs = more allocation

More info:
https://medium.com/eostarter/introducing-the-tartiers-7b0680c19efb

Reject subscription

Token Claim / Vesting

User logs in and navigates to his/her pools. A list of participated pools will appear and the user selects the pool that he/she recently contributed to. A request for the available/total allocated tokens will be sent to the Smart Contract and with that response, the claimable tokens will be displayed to the user.

User can then choose how many tokens of the currently vested tokens he/she wants to claim, and sign the “CLAIM” transaction. Once signed, the smart contract will then transfer the claimed tokens to the user, and those tokens will then be deposited on the user’s EOS account.

Use github packages for docker images

Use native gitHub packages for docker images . so that the project is self contained in github , and no longer needs eoscr docker hub

update pool table fields

acceptance criteria:

• add project info (IPFS url)
• add project url (stirng)
• rename inmediate vesting to project inmediate vesting
• add pool name
• change price to decimals
• user pool name as index
• change approve pool to work with the pool name

Project Owner Immediate Vesting

Pool Subscription

Once a user is verified, he/she can subscribe to an active project pool. There will be a number of active pools (1 or more) to choose from. The subscription has to be done before the established deadline or it will be unavailable.

Once the user selects a project pool to subscribe to, a subscription request is made. This triggers a requirement check from the BackEnd to verify that the user meets the criteria established by the pool for participation. These requirements may be holding a certain amount of tokens, NFTs, being part of a whitelist, etc. Once the requirement verification is done, a Disclaimer and Agreement is displayed to the user which explains the terms of the investments and also any potential legal disclaimers or acknowledgment that states that the investment is the user’s responsibility. This agreement will be signed ON-CHAIN to provide ever-lasting proof that the account indeed agreed to the investment terms.

Once this transaction is signed, the user will be added to the whitelist of the smart contract, allowing the account to participate in the token sale once it is live. The user will then get an email confirmation that he/she has been added to the whitelist.

Approve pool subscription

when the pool subscription its approved the max_allocation field will set that will allow to the investor user to contribute in the pool

Admin can test token sale before launch date

a small amount of EOS can be sent to the contract to test

Integrate with eostarter existing user base

There is an existing mongoDB of EOS starter KYC accounts

This should be integrated so app admin can whitelist accounts in smart contract

Basic UI interact with smart contract actions

Pool Submission

The user will submit a request to submit a project. At this stage, ONLY approved accounts will be able to submit a project pool. This will allow us to verify the projects and filter out potential scams or fake pools.

If the request is approved, a form with the project details will be displayed to the user and should be filled in accordingly. Once details are submitted, the user can save or submit the project details. Once a user submits the project details, a new project pool will be created in the system, but there will not be a smart contract deployed yet.

Users can then submit a “Create Pool” Request. The specific terms and conditions are then fetched and sent the agreement to the user. The user then signs an “Approve and Create” transaction, which sends the confirmed transaction to the backend, which in turn creates the Token Pool Smart contract and deploys it to the EOS Mainnet. It is important to notice that in this design, project pools are owned by the BackEnd Account. This can later be modified to provide ownership of the smart contract to the project owner.

Pool participation / Contribution

When the Token Sale is live, the user logs in and connects with his/her EOS account. The “Live Pool” will immediately be presented and the option to contribute will appear.

User selects “Contribute” which triggers a “Contribution Request”. The smart contract then performs the following checks:
“Is the user whitelisted/allowed to contribute?”

“What is the maximum amount allowed for this user”?
The response from the smart contract will enable the system to show the user the amount he is allowed to contribute. The user can select LESS than the established allocation, but NOT MORE. Once the user selects the amount, a transaction is created for him/her to sign and once this transaction is signed, the respective EOS gets sent to the Project Pool Account.

Token Deposit

At the time of creation, the token pool is not receiving transactions and it is rejecting all transactions both for security concerns and to enable the contract to have exclusively the tokens that will be allocated during the token sale.

The project owner then sends a request to open the pool for deposits to the Pool Contract. Only the project owner can perform this action. once approved, the project owner can then transfer the desired tokens to the smart contract. Once the transaction is confirmed, the BackEnd registers the existing supply and marks the project pool as “Ready for Sale”.

Add pool

Add user table

user fields

• account
• username
• role
• verified
• referral

Approve pool

allow add and edit from user table

acceptance criteria:

• account its unique
• only verified field is editable

Proceeds Claim

Users contributing to the Token Sale deposited their EOS to the token sale smart contract, therefore it is not yet available for the project. The project Owner must claim the proceeds from the token sale from the smart contract.

The project owner then submits a request to claim the proceeds. Security checks are done and the vested amount is determined according to the token sale conditions. Once the vested proceeds are determined, the amount to claim is displayed to the user.

Users can now sign a “Claim” Transaction to the Token Sale smart contract, which will then transfer the EOS to the account established as the Token Sale beneficiary during the project pool definition.

Allow edit pool info

Accumulative Claiming

Investor Immediate Vesting

addpool validations

acceptance criteria:

• only verified user can add a pool
• pool name must be unique
• token_symbol and tokens_on_sale symbol must match

Dev Environment Setup

Configure initial instance of application as a dev environment

Account Verification

The Account verification does not fall under the scope of the Smart Contracts for this specific project, but it is important for us as we want to be fully compliant and avoid any potential issues.

Ideally, we would love to be able to leverage EDEN on EOS as our account verification and be completely autonomous within our community to verify who is participating in the sales. However, we don’t live in an ideal world and we still need to comply with regulators, and for that purpose, we will be using a 3rd party KYC provider to provide account verification services.