The Technical ins and outs of the token conversion & distribution

Learn how the process will work technically

6 min readNov 11, 2020

So, want to know specifically how you will claim your tokens? Keep reading.

Summary

A website will be deployed where you will be able to exchange your Testnet tokens to the tradable GEOs. This website will allow you to connect your Metamask browser extension or your mobile wallet through WalletConnect. There you will make a transaction to claim your tokens in the Ethereum Mainnet. After this transaction is confirmed, you will have full custody of your tokens. Be sure to have some $ETH loaded into your wallet so that you can pay for your transaction. The interface will be fairly simple, ala Uniswap UNI tokens distribution.

The amount of tokens that you will receive depends on 2 factors:

The number of GEOs that you have harvested through GeoCash. (We hope you have been using it!)
A vesting period: the longer you wait to claim your tokens, the more you will receive.

Architecture

The system architecture is based on the frontend, smart contracts, and common libraries for method calls and transactions.

This architecture depends on a snapshot of the balances of the Testnet tokens that will be obtained on a specific date.

Swap

So, exactly how are we going to allow you and thousands of other users to claim tokens on the Ethereum Mainnet chain? Given that those are a good amount of transfers, fee expenditure would be quite high for us to assume it.

We will be using a “Merkle tree”. The Merkle tree or hash tree is a data structure that is often used in peer-to-peer networks to ensure data blocks are not corrupted or fake. Each non-leaf node of the tree is the hash of its child nodes, and each leaf node is a data block. This method has been used before by renowned platforms. Think Uniswap!

In our case, it enables a smart contract to securely validate token withdrawals to millions of users without having to store the full list of balances for each account, which would be prohibitively expensive to do in the Ethereum Mainnet chain. The only thing stored in the smart contract is the Merkle root, which is the root hash of the tree from which every child can be validated. For this validation, each transaction will need to recreate the full tree locally and create a proof for the smart contract to be able to verify it, and then transfer the assigned tokens.

At the bottom, you will find the tree‘s leaves, which store the amount of balance of each user. The top hash, alias the Merkle root, is stored in the smart contract. If you can provide a full branch from the leaf to the top, in very few (and cheap!) operations, you will be able to validate a token allocation.

So, the flow of events would be as follows:

We as GeoDB will deploy a smart contract containing a Merkle root, which summarizes in an immutable way the token distribution for GeoCash users. Afterward, we will deposit the total amount of tokens to be distributed to the contract.
Users will use their account to validate their token allocation. Users will get the full tree of allocations, a small file that we will store in our backend, to build the branch from leaf to root that corresponds to their own token allocation.
Once a valid branch has been provided, the contract will send from its internal escrow the validated allocation directly to the wallet. If tokens are claimed before the vesting period ends, the user will have the right to access a portion of the tokens. The rest will be sent back to GeoDB.

How is the Merkle tree built?

When the time comes, GeoDB will crawl the balances stored in our private Testnet (where GeoCash is connected) and make a snapshot of them. All these balances will be used to compute the Merkle root to be stored in the smart contract. The full Merkle tree will be publicly available for the frontend to be able to recreate the Merkle tree and create validation proofs from your local browser.

Notice that the Merkle Tree published will be static. Once we upload the smart contract with the Merkle root and load it with tokens, it cannot be changed, and it is immutable. This means that the balance snapshot from which the Merkle tree is built must be performed at a specific time. Thus, tokens received on the Testnet after this time are not going to be available to be swapped. We can assure you that these will amount to a negligible quantity.

How will my allocation be calculated?

Vesting period

There is also a vesting period that will directly affect the number of tokens that each account can withdraw at a specific time. This vesting period will establish a date in which all users could withdraw all their tokens. If some users want to do their swap before this period, the amount will be proportional to the elapsed time.

The vesting will be computed as follows. All users will start with an entitlement of 5% over the tokens stored in the Merkle tree. The entitlement will increase following the biquadratic curve up to 100%:

Percentage (%) = b + a*x4

Where:

The chart below shows the token unlocking ratio over a period of time.

Note: after the 365 days have passed, the unlocked tokens will remain constant at 100% until you decide to claim them.

Note: the numbers shown might have slight modifications to accommodate for the best computation of fractions in the smart contract.

Swap example:
A user has 730 testnet GEO tokens. The vesting period is 365 days, and the user makes the swap exactly 182 days after the contract creation. The Mainnet tokens received will be: