Creating smart contracts for your ICO on Stellar

Background image by Nathan Anderson

Blockchain, whether you like it or not, is changing the landscape of technology every day, and it doesn’t look like it is going to stop anytime soon. And the more we rely on this distributed network architecture, we are actually relying on its ability to conduct trades or transaction in the most transparent and trustless way possible.

To achieve this, the blockchain technologies of today empower us with a very powerful tool — Smart Contracts.

Smart contracts come in various flavors depending on what blockchain you choose, the most famous being the Ethereum smart contracts on Solidity at the moment, primarily because of its versatility (as it is Turing Complete).

But there are other blockchain technologies out there which let you establish just as much… just in a different way.

One such technology is Stellar, and it is what we chose as the fundamental tool set of our product — TillBilly, and also to run its ICO.

There are multiple reasons why we chose Stellar, you can find out more in our whitepaper, but one major reason was its simplified smart contract, something that we had unanimously agreed on right from the very beginning is a must for running an ICO.

“Stellar smart contracts are still black magic for most” was what Johan Stén (our advisor) said when I was discussing Stellar smart contracts with him.

So hopefully this article will guide and possibly help others who wish to utilize SSC (Stellar Smart Contracts) and SDEX (Stellar Distributed Exchange) for running their ICOs.

Let’s jump in!

As the name suggests, this model deals with creating an intermediate account for every user who wishes to contribute towards the ICO.

The main highlight here is that there exists an account between the contributor and company which is partially controlled by both parties through Stellar multi-signature feature.

To make things simpler, let’s set up a few acronyms:

IM: Intermediary AccountCU: Contributing UserCO: COmpany conducting the ICOSDEX: Stellar Distributed ExchangeSSC: Stellar Smart Contract (or a fully formed unsubmitted transaction)GA: Genesis Account (token issuer)HA: ICO funds Holding AccountTP: Trusted Party

Key highlights:

• IM is the account where CU will transfer funds to
• The control of the secret key for IM resides fully with the CU and responsibility of funding (and activating) this account on Stellar remains in the hands of the CO
• CO is added as a signer on IM for partial control
• IM participates on (creates offer on) SDEX to buy the tokens and hold it for the duration of ICO
• On ICO success, CO no longer remains as a signer. This is handled via an SSC and full control of IM goes to CU
• On ICO failure, CO is still removed as a signer but the refund mechanism is handled by another SSC on HA

Issuing account (genesis account) setup:

One thing to note here — GA will need to have some control over the operations on itself, namely low threshold operations. This is because we want control over who can establish a trustline with our token and allowing trust is a low threshold operation.

1. GA sends a set number of tokens to HA
2. HA sets up its own sets of SSCs (explained later)
3. GA performs the following operations:

- Add TP as a signer with weight 1- Set its own weight to 1- Set authorization required flag- Set low threshold to 1- Set medium and high threshold to 2

This will allow GA to allow trustlines but will not allow it to make any more payment (token generation) transactions.

Note: Since we have to allow trustlines throughout the duration of ICO, we cannot have a pre signed time locked transaction for clearing the authorization required flag after the ICO.

After the ICO is concluded, the following transaction will be submitted (signed by both GA and TP):

- Clear authorization required flag- Reset thresholds- Remove TP as a signer- Set own weight to zero

Setting own weight to zero will effectively render the account as worthless and no more tokens can be generated. User’s, however, can establish trustlines freely to trade these tokens.

SSCs on ICO success or failure (key takeaways):

• HA will implement a multi signature with a TP on Stellar (could be a person, an organization etc.).
• HA holds all the tokens that are to be sold during the ICO.
• HA creates offer on SDEX to sell tokens for XLM
• A pre signed transaction with a set date determines the success or failure of ICO
• Success transaction will be time locked and with following operations (Seq number: M)

- Send SOFT_CAP_AMOUNT to CO- Remove TP as a signer- Reset thresholds- Clear the offer on SDEX

(If the ICO is not successful in raising the soft cap, this transaction will fail)

• Failure transaction, time locked (Seq number: M + 1)

- Create an offer on SDEX to buy back tokens for XLM

The challenge here is that we have to release all XLMs from HA in this case. Something that cannot be pre-written. So we’ll rely on TP again to create a transaction in this case or update the offer on SDEX with the right amount of XLMs.

We will assume that all other prerequisites are met including website account creation, email verification, KYC and AML checks etc.

1. User comes on to the dashboard and sees a button to create a wallet (IM).

2. Upon clicking, an offline Stellar keypair (only for the first time) is generated for the user. The secret is saved in the browser temporarily for the upcoming set of transactions.

3. User is prompted to save this keypair securely (An option can be given where we generate a keystore file locked with a password and save it on the server).

4. The user is then prompted to enter the secret key again in order to proceed with the next step. This is to ensure that user has saved the private key.

5. In the background (via xhr), we fund IM with 3 XLM thereby activating it (calculations later). The server responds with a success status along with CO’s public key.

6. Upon successful activation, we create a transaction with following operations on IM (this transaction envelope (XDR) is sent to server instead of Stellar)

- Request trustline for token- Add CO as a signer with weight 1- Set all thresholds to 2- Set own weight to 1

7. Server submits this transaction on Stellar and then approves the trustline from the token issuing account. Wallet is now set up to receive funds (XLM) from external sources and ready to buy tokens from SDEX.

8. User is now presented a button to buy tokens. On clicking, we ask user to deposit XLM in IM from anywhere they want. It could be their own Stellar wallet or an exchange as well.

9. Browser shows a waiting status while it waits for an incoming transaction. We check this by using Server-Sent Events (streaming) mode.

10. Upon receiving funds, we create the following transactions (partially signing it using the secret key saved in the browser):

Transaction #1: (N)

- Send 3 XLM to CO (recovering the account activation funds — one time only)- Create an offer on SDEX to buy tokens for all but 3 XLM in account

Transaction #2: (N + 1) Time locked for the duration of ICO

- Remove CO as a signer from this account- Reset thresholds

11. Both transactions are sent to the server. Transaction #1 is signed by CO and submitted directly to Stellar network. Transaction #2 is signed and its hash and transaction envelope are saved on server. Server also returns these to the user if they want to verify and save it with them.

12. Every time the user wants to transfer funds, steps 8 to 11 are repeated.

The server will post this transaction #2 in step 10 upon completion of the ICO regardless the ICO succeeds or not.

In case of when ICO is successful, the tokens are already in user’s account with full control of the account as well. The dashboard can provide quick and easy options to transfer these funds to a different account or merge it with another account etc.

In case of when it fails, we are locked by a different set of SSCs which keeps both us and our users protected. We will again provide simple options on the dashboard to claim the funds back.

Calculating minimum account balance for IM:

Minimum balance required:

0.5 x (2 + # of entries)

Every IM for ICO should have:

• 1 Trustline with the issuer’s token
• 1 Signer (CO)
• 1 Data entry (for handling bonus tokens, if required)

Putting these values in the equation:

0.5 x (2 + 3) = 2.5 XLM

Potential operations that IM will go through:

• Establish a trustline
• Set options (add signer, set thresholds, set own weight)
• Create offers on SDEX
• Transfer funds to user’s main account after ICO success
• Merge account with user’s main account

Since the cost of these operations is not too high, having 0.5 XLM for fees is safe enough. So in total, each IM should have a minimum of 3 XLM deposited by the CO initially which can later be recovered. The real world (fiat) value can change depending on what is the cost of XLM at that point.

That wraps it up!

Now there can be more ways through which this model could be enhanced. For example:

• This was again suggested by Johan, in steps 2 through 4 in ICO sale process, you could use BIP-39 Mnemonic Code to ensure that contributing users indeed remember their secret keys.
• Another SSC for when a user didn’t contribute at all and CO needs to recover the 3 XLMs transferred initially to activate the IM.

But this is something I’d leave up to you guys!

Originally published by Aditya Moghe , engineering director at TillBilly — a forward-looking startup working on an innovative solution to bring blockchain based point of sale payments solution to the mainstream retail.