# StakeDrop Integration

StakeDrop in Marlin is a way to distribute marlin tokens among communities to ensure that the governance is distributed. It also ensures that marlin tokens are not a barrier for potential node runners.

StakeDrop is supported for a set of blockchain platforms initially decided by the Marlin team during launch, but later this decision lies with the governance where anyone with marlin tokens can participate.

StakeDrop for any given blockchain platform is designed in a way that users who have tokens of the blockchain, can earn rewards by delegating their tokens to validators who use Marlin network for Block propagation. This incentivizes validators to use Marlin protocol to increase tokens delegated to them, thus bootstrapping the supply and demand side for the bandwidth marketplace.

A fixed number of marlin tokens are rewarded to the users for a fixed period of time. Rewards are distributed based on the number of tokens delegated to validators who use the Marlin network.

## Architecture

Stakedrop is implemented in Marlin as a set of oracles which feed data to a distribution contract that calculates the rewards from the data feed from oracles. Users can claim their rewards by sending a transaction to the distribution contract.
Oracles

Stakedrop uses the following oracles to feed the data required to calculate rewards

* Address Registry
* Validator Registry
* Stake Registry
### Address Registry
Address registry contains the delegator address and their corresponding Ethereum addresses. The Ethereum address is used to reward marlin tokens (ERC20 on Eth), to delegators who delegate stake to validators using Marlin.

A delegator who wants to register for stakedrop will link their delegation address with a corresponding Ethereum address from our stakedrop portal. There are multiple approaches we use based on the availability of tools for the blockchain ecosystem and the simplest mechanism for the user to follow. Some of the approaches are verifying a signature generated by the delegator address on the Ethereum address or sending a transaction from the delegator address to a specific address generated based on the ethereum address.
### Validator Registry
Validator registry maintains the list of validators who use Marlin protocol for data propagation at any specific epoch. Validator list has to be feeded to this registry for each epoch and after entering all the validators for the epoch, the validator list has to be freezed, so that rewards can be equally distributed as we know the total stake eligible for rewards.
### Stake Registry
Stake Registry maintains the mapping of delegator and the amount of stake delegated by the delegator to validators using Marlin. Stake for each delegator has to be feeded to the registry for each epoch and based on this feed rewards are allocated to each delegator based on their delegated stake.
### Distribution Contract
Distribution contract maintains the amount of rewards claimed by the delegators and the rewards which are pending to be withdrawn. Delegators can claim their rewards from this contract. Delegators can withdraw rewards they have earned till the last epoch but the rewards for the current epoch can’t be withdrawn till the epoch ends.

## Feeder
A transaction feeder is developed by Marlin which can ease the integration of stakedrops for new blockchain platforms as the feeder does the job of converting the API calls made to the feeder into the Ethereum transactions necessary to feed the data into blockchain.

The following are API provided by the transaction feeder
* addValidator {epoch, validatorAddres}
* freezeEpoch {epoch}
* addTotalStake {epoch, stakeValue}
* addDelegator {epoch, stakingAddress, validatorAddress, amount}
* addAddress {stakingAddress, ethereumAddress}
* removeAddress {stakingAddress, ethereum}

Epoch here is the time period for which data is updated for rewards on the blockchain. This also is the frequency with which data is to be provided to the oracles.

The order in which these APIs needs to be called based on how the oracles work is as follows
* Add all the validators for a specific epoch by calling addValidator endpoint.
* Once all the validators are added, freeze the epoch by invoking freezeEpoch endpoint.
* Add total stake from the validators who are using marlin by using addTotalStake endpoint.
* Add the stake of each of the delegators for a specific epoch by using the addDelegator endpoint.
* addAddress and removeAddress to add delegators can be added at any point and the rewards will be calculated from the block that the addAddress transaction is sent.

**Note:** Ordering of the transactions is to be done before invoking the transaction feeder APIs and transaction feeder itself doesn’t validate the ordering.

### Integration
To integrate the stake drop for a new blockchain platform, the data source necessary for the feeder needs to be implemented. The data source can use feeder APIs to feed data to the oracles necessary for the stakedrop.

## UI Integration
We have developed a website for stakedrop which can be used by any of the new blockchain platforms integrating for the stakedrop.

### High level Flow
* User registers for stakedrop by linking the staking address to the reward address(ETH address).
* Staking address can be linked by sending a 0 value transaction from staking address to the random address, which is generated based on the combination of staking address and reward address.
* For example, random address can be generated with concatenation of staking address and reward address as seed.
* The above transaction should be made and transaction hash should be submitted within 24hrs of the transaction.
* If successful the user is added as a valid stakedrop participant.
* Validators of the base chain who support Marlin are whitelisted. Only the stake delegated to these validators by the registered delegators is considered for the reward.
### Interfaces
Swagger Docs - sd2.api.marlin.pro/polkadot/api-docs

Below are the APIs necessary to integrate with the existing User Interface. Ethereum address is the reward address in the following section.

**GET /getTotalValueLocked** -- Total stake delegated by registered users to whitelisted validators.
**GET /generateDepositAddress/:stakingAddress/:ethereumAddress** -- Generate a new address to send a 0 value tx to register staking address with ethereum address. The generated address should be unique for a given staking and ethereum address. “:stakingAddress” and “: ethereumAddress” are the parameters to be passed to the endpoint. Ethereum address and staking address are mapped one to one i.e multiple ethereum address cannot be linked to a single staking address or multiple staking address cannot be linked to a single ethereum address.

**GET /isEthereumAddressAvailable/:ethereumAddress** -- This endpoint is used to check if the ethereum address provided is already linked with any other staking address.

**GET /isStakingAddressAvailable/:stakingAddress** -- This endpoint is used to check if the staking address provided is already linked with any other ethereum address

**POST /register**
Data: {
stakingAddress
ethereumAddress
transactionHash
}
This endpoint is used to register a delegator by linking the delegator’s staking address to the Ethereum reward address. Below are some of the important checks we perform for reference.
* Validate data formats for the data received
* Check if staking address, reward address are valid
* Validate if the transaction hash is related to a tx within last 24hrs.
* Check if the sender is the staking address and receiver is the generated address based on staking and ethereum addresses and value is 0.
* Check if staking and ethereum addresses are not already registered.

The delegator can then be registered for stake drop.

**GET /contractAddress** -- This endpoint returns the contract address for the distribution contract for the user interface.

**GET /transaction/:hash** -- Check if the transaction hash is valid.

**POST /addWhiteListedValidator**
Data: {
key,
validatorAddress
}
This endpoint adds whitelisted validator addresses by the admin after confirmation that they use Marlin. Key represents the authorization data necessary to authenticate admin and validatorAddress is the address to be whitelisted.