# Staking Guide

### Summary

This guide describes the steps required to:
1. Register a cluster on the smart contract registry
2. Delegate POND and MPond to clusters
3. Update marlinctl and associate their instances with the cluster registered in Step 1

Points 1 and 3 are only meant for cluster operators. Token holders who do not operate their own cluster and only wish to delegate to other clusters can skip to the section associated with Point 2. This guide is best suited for folks with experience working directly with smart contracts. If you are not adept in the same, please wait for the frontend interface.

### Addresses required
The steps below are going to make references to a number of addresses. They are summarized below.
1. Controller address: This is the account that's registered in the Cluster Registry smart contracts, changes key parameters wrt the cluster (commission, commission address) and also the address to which POND/MPond holders delegate. This address need not have POND, MPond or any other tokens other than ETH to pay for gas.
2. Delegation address: This is the account that has POND and/or MPond tokens which are to be delegated to one or more Controller addresses. Cluster operators can use the address as the controller address as well as the one that holds tokens via which they delegate though this isn't recommended for privacy/security reasons.
3. Reward Address: Cluster operators can charge a commission from those who delegate to it on the fees that it generates. Such commissions are deposited into the reward address. This address may or may not be the same as controller or delegation address (no restriction).
4. Client key: This is an address whose keystore needs to be accessible on the client to sign receipts in the network. The controller address uses the client key as a parameter during registration to link the smart contract entry to the physical instances.

Only cluster operators need to generate a controller address, reward address and client key. They may or may not have a delegation address (you can operate a cluster solely via others' delegations without owning any POND/MPond yourself).

POND/MPond holders need to have a delegation address (the address which holds their tokens). They need to know the controller address they wish to delegate to even if they do not own it.

Note that for a cluster operator there's no difference between a self-delegation and external delegation.

### Cluster Registration

1) Go to the Cluster Registry address on Etherscan: [0x5B7B5632149653B974e75b18F7B02dEeEac38E47](https://etherscan.io/address/0x5B7B5632149653B974e75b18F7B02dEeEac38E47#writeProxyContract)
2) Click on the `Connect to Web3` button and connect to your ledger/metamask account using the address you want to be the Cluster controller.
3) Call the function `register` with parameters:
- networkid (hash of network ticker -- listed in the table below)
- commission (fee -- integer between 0 to 100)
- The fee the cluster operator wishes to receive from its delegators
- reward address (for commissions)
- Address to which commissions from delegators are deposited
- client key
- Address on the Marlin node that will be signing receipts etc
- Needs to be a hot wallet available as a [keystore file](https://medium.com/@julien.maffre/what-is-an-ethereum-keystore-file-86c8c5917b97) (can be generated using geth or MEW for example)


| Network | NetworkId |
| -------- | -------- |
| ETH | 0xaaaebeba3810b1e6b70781f14b2d72c1cb89c0b2b320c43bb67ff79f562f5ff4 |

### Steps to delegate POND or MPond

1) Users can currently delegate POND and/or MPond on Ethereum to a cluster registered above.
2) Go to the POND or MPond token address on Etherscan depending on the token you wish to delegate.

| Token | Address |
| -------- | -------- | ------- |
| POND | [0x57B946008913B82E4dF85f501cbAeD910e58D26C](https://etherscan.io/address/0x57B946008913B82E4dF85f501cbAeD910e58D26C#readProxyContract) |
| MPOND | [0x1C77d15857646687005dbbAfFf5873F4495a9731](https://etherscan.io/address/0x1C77d15857646687005dbbAfFf5873F4495a9731#writeProxyContract) |

3) Connect your metamask/WalletConnect account with POND or MPond tokens by clicking on `Connect to Web3` button and click on the `Contract` and `Write as Proxy` tabs.


4) Send an `approve` transaction with the amount you wish to delegate.
* Spender - 0xCBB94D13fB90C28368E4358f3EccE248ae4B6c82 ([StakeManager contract](https://etherscan.io/address/0xCBB94D13fB90C28368E4358f3EccE248ae4B6c82#code))
* Amount - number of tokens to be delegated (remember to add 18 zeroes)


5) Once approved, go to the StakeManager contract ([0xCBB94D13fB90C28368E4358f3EccE248ae4B6c82](https://etherscan.io/address/0xCBB94D13fB90C28368E4358f3EccE248ae4B6c82#writeProxyContract)) to create a stash and delegate to a cluster. Below are the 2 ways to do that. Go with any one.
a) Create stash and delegate in 2 different steps:
* Call the `createStash` function with parameters:
* Array of tokenids
* Hash of token addresses -- Refer from table below
* Array of amounts
* Corresponding tokens amounts to be added to stash

Note: This tx returns the stashId as part of the event emitted on creation of the Stash. Please refer [below](#Looking-up-stashId-from-stash-creation-TxHash) to know how to lookup stashId from Etherscan with transactionId.


| Token | TokenId |
| -------- | ------- |
| POND | 0x5802add45f8ec0a524470683e7295faacc853f97cf4a8d3ffbaaf25ce0fd87c4 |
| MPOND | 0x1635815984abab0dbb9afd77984dad69c24bf3d711bc0ddb1e2d53ef2d523e5e |

* Call the `delegateStash` function with parameters:
* stashId
* Received from stash creation step above
* cluster address to delegate to
* The Controller address registered in the section above


b) Make a `createStashAndDelegate` call with
* Array of tokenids
* Hash of token addresses -- Refer from the table above
* Array of amounts
* Corresponding tokens amounts to be added to stash
* Cluster address to delegate to
* The Controller address registered in the section above


Note: This tx returns the stashId as part of the event emitted on creation of the Stash. Please refer [below](#Looking-up-stashId-from-stash-creation-TxHash) to know how to lookup stashId from Etherscan with transactionId.

5) Tokens can be added to an existing stash by calling the `addToStash` function with parameters:
* stashId
* Received from stash creation step above
* Array of tokenids
* Hash of token address -- Refer to the table above
* Array of amounts
* Corresponding tokens amounts to be added to stash


Note: Any additions to the stash will auto delegate to the cluster chosen in the previous step. If only the `createStash` function was called and `delegateStash` was never called, the tokens that existed in the stash with the ones added later remain undelegated.

#### Figuring the stashId from the stash creation TxHash

1. Once stash creation transaction is completed, find the tx hash and open the page of the transaction by searching the txhash in Etherscan.
2. In the tx page, go to the `Logs` tab
3. Select the log with topic 0 as `0x614d6f8319493a3bb5dd50287615457dd869414d3d6b96136f80ac1c1ef2428d`
4. The first element in the data is the stashId of the created stash. In the above screenshot it is "0x277b2c05a202fecfc5164a3c3d1fc58cdf27b384a84e371cf62b5d30197830f7"

### Linking the cluster registered above to the clients

Cluster operators need to link their clusters (specifically, the beacon) to their client key.

Only for existing clusters:
- Destroy the old beacon using the old marlinctl
- Important: Needs to be done for sure and only with old marlinctl

    $ sudo marlinctl beacon destroy

For all clusters:
- Download and install the [new marlinctl](https://github.com/marlinprotocol/marlinctl2)
- Have the keystore file locally on disk
- Create a new text file with the passphrase used for the keystore above
- Run beacon with proper args as follows

    $ sudo marlinctl beacon create --discovery-addr "0.0.0.0:8002" --heartbeat-addr "0.0.0.0:8003" --bootstrap-addr "34.82.79.68:8003" --keystore-path /path/to/keystore --keystore-pass-path /path/to/passphrase

- Run relays as given in [Instructions](https://www.marlin.pro/docs/testnet/Instructions/)
- Existing clusters don't need to change existing relays

### Post-link checks
- See beacon logs using

    $ sudo marlinctl beacon logs

- Look for a line saying `Beacon: Identity is 0x<addr>`
- Check if the address matches the client key used while registering