How to build an ICO on NEO with the NEX ICO smart contract template

Chris Hager
Dec 19, 2017 · 8 min read

This post dives into the neo-ico-template of the Neon Exchange (NEX), and how to use it as an ICO developer to configure, compile, deploy and test the ICO smart contract.

The whole process includes the following steps:

  • Adapting the ICO template to your needs
  • Compiling the contract template into NEO bytecode (.avm file)
  • Deploying the compiled smart contract using neo-python
  • Invoking methods on the deployed contract (deploy, mintTokens, balanceOf, …)
  • For testing purposes we will use a private network of the NEO blockchain

About the NEX ICO Template

The smart contract template was released mid-December, and introduced in a blog post on the official neon-exchange Medium. The template has three particularly interesting innovations:

  • Full NEP5(.1) compatibility
  • KYC/AML enforcement (optional): the ICO operators can choose to require participants to get verified before contributing. This works by whitelisting participant addresses before they can successfully invoke the smart contract method mintTokens
  • Simplified refund and rejection mechanism: the template includes several methods to avoid invalid ICO contributions and to automatically process refunds (eg. when a participant is not yet whitelisted, or contributes outside the ICO window).

You can find a more in-depth description of those in the official blog post.

Preparations: Python 3.5 + neo-python

Make sure you have Python 3.5 installed, you can get it from the official Python downloads page or the package manager of your choice (on macOS it should be installed by default, else use homebrew do get it). You can check your Python version by using “python3.5 -V”.

This guide uses neo-python, therefore set that up as first step. Clone the repository, setup a virtualenv and install the requirements. The whole process is covered as a detailed step-by-step guide in the neo-python README. Follow this and you’ll have neo-python ready to go in no time.

Configuring the ICO Template

This section shows how to adapt the template to your specific ICO. The first step is cloning the ICO template repository, setting the virtual environment and installing the dependencies:

Now let’s dive into the configuration of the smart contract, in particular the name, symbol, ownership, supply and amount of tokens a participant gets for sending NEO or GAS.

All the important settings for the ICO can be configured in nex/token/mytoken.py.

Ownership

It is important to set the right owner, which has access to administrative methods of the contract.

  • For a live deployment you should create a wallet specifically for this ICO (in the neo-python prompt: “neo> create wallet ico.wallet”).
  • You need to get the “script hash” of the wallet and use this as value for the owner variable of the smart contract. When you open the wallet with neo-python and print the details (“neo> wallet”), it will print an info line with the script hash:
  • For testing purposes you can just use the wallet provided with the privatenet Docker image, which has this script hash:

Set the script hash as value for the “owner” variable in mytoken.py#16.

Settings for token, supply, token value, caps and ICO time window

  • Change name of the token and the symbol.
  • Decide on the total amount, and the initial amount held by the owners, and set it in the variables “total_supply” and “initial_amount”.
  • Then set how many tokens a participant will receive when sending NEO or GAS, and set this in the variables “tokens_per_neo” and “tokens_per_gas”.
  • If there should be a cap for participants, you can define this with “max_exchange_limited_round”.
  • Finally, set the start time of the ICO and the end time, based on NEO block height. For testing purposes, set the block_sale_start variable to 1 and the end to 1 + 100000.

Various

If you want to disable the KYC process, simply remove the KYC check at crowdsale.py#149 (“if not self.get_kyc_status(attachments.sender_addr, storage)”). See also the comments in the code.

If you want to enable users to send GAS in addition to NEO, you need to enable it by uncommenting the lines at crowdsale.py#136.

Testing and compiling the ICO template to NEO bytecode

While configuring and adapting the ICO template, it is immensely useful to continuously test the various methods. neo-python offers built-in functionality to build the smart contract and test method invocations with custom parameters.

For instance, let’s build the SC and test the “name” method. Open the neo-python prompt and use a command like this (replace path-to-template with the relative path to your template directory):

This step also compiles the Python code to NEO bytecode, producing a file with the name “ico_template.avm” (located in the template directory, next to the ico_template.py file).

Alternatively you can also manually compile the Python smart contract code, you can read more about this in the template README.

Starting a Private Network of the NEO Blockchain

The next step is to start a private network of the NEO blockchain to deploy the compiled smart contract with neo-python.

Running a private network is easy by using Docker with this image: https://hub.docker.com/r/metachris/neo-privnet-with-gas/. Just follow the instructions on the website to get it up and running (see also this post).

You can confirm that the private network is running with “docker ps”.

Now connect to the private network with neo-python. Starting prompt.py with the “-p” argument makes it use the local private net:

The block count at the bottom of the terminal should be around 2115 and increasing. Download and open the privatenet wallet.json (password: coz, see also the Docker hub description), and rebuild the wallet:

Now wait a few seconds, and verify that all the NEO and GAS is available by issuing the “wallet” command, which shows all the infos:

Deploying the Smart Contract

Now we have a compiled smart contract, a private network of the blockchain running, and neo-python fully set up with a wallet with lots of NEO and GAS. The next step is deploying the smart contract with neo-python.

For this example I’ve copied the compiled smart contract (ico_template.avm file) into the neo-python directory, which makes it easier to deploy deploy it into the blockchain:

The command we used was “import contract ico_template.avm 0710 05 True False”, which means to import the file ico_template.avm with the parameter types 0710 (string and array) and return type byte-array. The parameters “True False” at the end mean “Need storage” (yes) and “Support dynamic invoke” (no). See also the neo docs about SC parameter types.

At this point, the contract is being deployed. Wait for a few blocks until it shows up on the blockchain:

Replace <transaction-hash> with the actual hash at the end of the previous step. Once the transaction is found, you can search for the smart contract to get more information. In this example we search for “nex” because we used that in the smart contract deployment step:

In this case, the ICO smart contract has the hash 70b3f7098a9a3f2361a1f0c312e9842ec4ca6dc6, which we will need to use for all the method invocations.

Invoking Methods

The ICO smart contract has several methods, some of which have to be invoked by the owner and some which can be called by everyone.

This diagram provides a rough overview of the stages and relevant smart contract methods:

Image for post
Image for post
ICO stages and selected methods

Also take a look at NEP-5.1 and the Neon Exchange blog post for more information about the various available methods, including those not listed here in the diagram.

The first step is calling the “deploy” method of the smart contract, which stores the initial amount of tokens as “tokens in circulation” in the contract storage. With neo-python we use the command testinvoke with the smart contract hash to invoke the method deploy (without any arguments):

The empty brackets mean that there are no arguments to pass for the deploy method.

After the deploy method has been called and the transaction shows up on the blockchain, we can check the amount of tokens already in circulation with the circulation method:

In this case, the result is this byte array: b’\x00\xa01\xa9_\xe3\x00'. We can convert it into an integer with Python 3 like this:

As you can see, the byte array represents the integer value 250000000000000, which is 2500000.00000000 tokens, the initial amount of 2.5m tokens for the owners specified in mytoken.py.

The command crowdsale_available returns the remaining number of tokens available in this crowdsale:

In this case, all 7.5m tokens are still available.

There are a few special smart contract methods in this template: crowdsale_register and crowdsale_status.

The ICO operator has to whitelist addresses in order to allow them to participate. To whitelist an address like ATELFGeypfK15uwNvRdQe1zaD3vw38976L, you’d invoke crowdsale_register like this:

After this transaction went through, you can verify the crowdsale status of the address with this command:

Once an address is kyc_registered, users can participate in the ICO by invoking the mintTokens method with some attached NEO / GAS.

This is how that call would be issued from neo-python with 5 NEO attached:

Once this call went through, you can check the balance with the standard NEP-5 method balanceOf:

And this is it! We performed all the steps needed to run an ICO with the NEX ICO template. You can read up about further NEP-5 methods here.

Finally, in neo-python you’ll want to add this NEP-5 token to your wallet. You can do so with “import token <hash>”, and then you’ll see the balances in your wallet:

By the way, there will be an upcoming article which explains some of the nuances and pitfalls of the neo-boa smart contract compiler!

Thanks a lot to the people at Neon Exchange for open-sourcing such a great piece of software. It will be helpful for many projects to come!

If you have questions or feedback, reach out to the author via @metachris.

Proof of Working

COZ community magazine

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store