Colu Local Network Contracts Architecture layout

Hi my name is Tal Beja and I am the Blockchain team leader at Colu. We aim to create a vibrant developer ecosystem which is vital in order to ensure the long term adoption of the CLN as a means of access to the local payment network. Over the last few months our team has been hard at work to design and deploy a series of contracts that will provide the utility for the CLN and utilize it for liquidity for Community Currency issuance. Here we wanted to share an overview of the architecture design and we will follow it up with recurring updates and firsthand insights into the process of the development.

Let there be token

In the center of the Colu Local Network, there is a token, the CLN token, an ERC-20 token, improved with ERC-677 capabilities.

An ERC-677 token solves some of the issues where ERC-20 is lacking, mainly the two-step approve-call interaction with contracts. It is similar to ERC-223, only it does not overload the transfer method in order to carry the data of the recipient contract transaction, but uss a different method called transferAndCall which receives bytes data as an added param to the transfer. The added data is used to invoke any “token payable” method in the receiver contract.

All of our contracts are ERC-223/ERC-677 standard receivers, that can be interacted both with the old ERC-20 approve-call mechanism and with the new added data of the ERC-677 transferAndCall method or even with overloaded transfer method with added data of the ERC-223 tokens.

For further reading on the ERC-223 and ERC-677 you can refer to their EIP pages: ERC-677, ERC-223.

Token pools

The Colu Local Network advocates transparency. In order to achieve maximum transparency, pools with dedicated roles were created.
The pools are:

Community Pool: holds 450,000,000 CLN tokens. This pool will be used for bootstrapping communities. Its CLN tokens will be locked in market maker reserves in order to give value and liquidity to the current and future CLN communities. More on this in the Market Maker section.

Team Pool: holds 90,000,000 CLN tokens. This pool will be dedicated to incentivize the CLN team members using vesting plans. All vesting plans will be visible and transparent using a smart contract (the VestingTrustee).

Future Development Pool: This pool will hold 435,000,000 CLN tokens + any unsold CLN tokens from the crowd sale = about 759,924,627 CLN tokens. This pool doesn’t hold these tokens yet. The tokens are locked for three years in the VestingTrustee smart contract. This pool will be used in the future for further expansion and development.

Vesting and locking

Pre-sale investors got the same price as the crowd sale. They got discount options in return to a lockup period. The longer the lockup the bigger the discount. This way we could keep the sale fair for crowd-sale participants while having pre-sale investors that share our long term vision.
To lock the pre-sale investors tokens, team vesting plans and the future development pool we deployed a smart contract called VestingTrustee. This smart contract allows us to lock tokens in a vesting period with cliff and installment length. The future development pool, for instance, has a plan for three years with a three years cliff, so the tokens are basically locked for the whole three years. A pre-sale investment, on the other hand, has a one month cliff and one month installment length, so the investment releases monthly. Both of them are non-revokable, meaning that the owner of the contract can’t revoke the plan and release the tokens. Team member plans, in contrast to the previous plans, are revokable, so the owner of the vestingTrustee can revoke a vesting plan for an employee, if he stops being an employee.
All of these vesting plans are fully transparent on the block-chain.

Ellipse Market Maker

The Colu Local Network is a network of communities, each with its own crypto community currency. All of these community currencies (CCs) are connected to CLN using a Market Maker.

The Market Maker contract allow a community currency issuer, to give its CC value and liquidity by locking CLN tokens in the market maker reserve. The market maker works in a simple way, it has two reserves of tokens, usually CLN and a CC. If a user, any user, wants to buy CC, he transfers CLN tokens to the Market Maker smart contract and receives CCs on the other side of the transaction. The price ratio between the CLN-CC pair is raised a bit. If someone wants to sell his CCs, the opposite action takes place, and the price of the CC in relation to the CLN drops a little.

The Ellipse Market Maker follows the following rules:

1. Make sure that there will always be enough CC or CLN in the reservse for any user to buy\sell.
2. Is symmetrical, meaning that buying CC is the same operation as seling CLN and vice versa.
3. The relation between the CC and the CLN reserves determines the CLN-CC price. So buying X CCs and then immediately selling the same X CCs will result in the same reserves amount and thus the same CLN-CC price.
4. If all of the supply of one token is on one reserve then the second reserve will be zero and the price will be infinity.

Creating community currencies

The whole back bone of the Colu Local Network is its community currencies. Each currency is created to serve a specific community, to monetize it and to empower its members. The CC should be connected to a large network that will provide its value and liquidity.

The simplest way is just issue a simple ERC-20 token, but in that way of issuance, there is no value attached to the CC and no guarantee that it will hold it value.

When issuing a CC connected to the CLN with a market maker, its reserve promises both value and liquidity.

In order to help community managers issue Community Currencies we deployed two smart contracts:

CurrencyFactory

Using the CurrencyFactory smart contract, a community manager can issue a community currency and create a market maker connecting him to the Colu Local Network.

The issuer can choose a name, symbol and total supply of the Community Currency.

After the issuance, all the supply of the new CC sits in the market maker reserve (and not in the issuer hands) and the CLN reserve is empty. In order for the issuer to free the newly created tokens from market maker, the issuer needs to buy the tokens from the market maker by placing CLN tokens in the market maker reserve. This gives the newly issued CC its first value and backing. The market maker is locked for any user other than the issuer. This is because the first CCs bought from the market maker are the cheapest, so we want to give the issuer the opportunity to buy its tokens and back their value with CLN tokens without interference. After the issuer finishes, he opens the market maker for public, and anyone can now buy and sell its CC using the market maker.

IssuanceFactory

In the first scenario, the issuer needs to finance the backing of the CC using its own CLN tokens. There is another contract that allow the issuer to back its CC with the community CLN tokens in an crowdfunding fashion, the IssuanceFactory.

The issuer chooses the name, symbol and total supply of the Community Currency, same as before, and also start time, duration, hard cap and soft cap for the crowdfunding. The soft cap has a very important role here. First — the soft cap determines the success of the sale. If the soft cap is not reached, then the sale fails and any user can get refund for his CLN tokens. Second — the soft cap (also known as reserveAmount) is the amount of the CLN that sits in the market maker reserve. Third — it also determines the target price of the CC — the amount of CCs that each CLN participation will get. As all CLN tokens below the soft cap are entering the market maker to free the CCs, each CLN between the two caps is going to the issuer. There are mathematical constraints on the relation between the soft cap and the hard cap, but as a role of thumb, it is advised to use a relation of X2 between them.

The sale works in several automatic stages:

1. Start -> Soft cap:
   Each CLN raised goes into the market maker. CCs received from the market maker should be above target price. CLN * target price = CCs transferred to the participant, the rest is locked in the sale contract.
2. Soft cap -> Hard cap:
   Each CLN raised stays locked at the sale contract. CLN * target price = CCs transferred to the participant. The contract sale should have enough CCs from the excess CCs of stage 1.
3. Time ends and Soft \ Hard cap is reached:
   Sale is successful. The issuer finalizes the sale and receives all the CLN tokens and CCs locked in the sale contract (if any). Also the market making contract is opened for public.
4. Time ends and Soft cap isn’t reached:
   Sale is failed. Any participant can send its CCs and receive its CLN tokens back. Market maker contract will never be open for public. The issuer will get none of the CLN tokens nor any issued CCs.

To read more about our Ellipse Market maker and the issuance mathematics, you can read our white paper appendix.

Additional work

All of the smart contracts are deployed both on ropsten network and the main ethereum network.

All of the contracts are audited by several auditors with no critical issues found. Here is one of our audits.

Also, as said before, all of our contracts are standard ERC-677\ERC-223 receivers.

You can find more technical guides on how to create and issue a new Community Currency using the CurrencyFactory and IssuanceFactory and how to work with the market maker in this tutorials.

Join our Reddit to continue the conversation, or send feedback or questions to cln@colu.com