Stakes

Stakes are an integral part of the Clarity SDK and Agora. They are required for users to create or interact with proposals. Users will lock their governance tokens to a smart contract that will then give them a stake with voting power equivalent to the number of governance tokens they sent to the smart contract.

The users will then use this stake to create or vote on proposals. The user is free to destroy their stake and withdraw their governance tokens at any time.

Fetching Stakes (getStakes)

Retrieving stakes for a user is an extremely important part of the SDK. Information from this function call will be required in many of the other SDK functions.

If you decide to store the stake information returned from this function in some sort of frontend library such as redux, note that you will need to update stake information anytime an action involving a user's stake is performed.

So if a stake is edited, a stake is used to vote on a proposal, etc that stake's information will change and the stake information you are storing will need to be updated.

You can also just retrieve live stake information as needed rather than attempting to store it on the frontend. This will be up to the app developer to decide.

Create Stake (createStake)

The first step most users will need to do is create a stake. There are not really any restrictions on creating a stake.

The only thing to keep in mind is that you should always consider decimals. For example, if your token has 6 decimals then you need to add 6 zeroes to the actual amount of tokens you want for the stake. The Clarity SDK does not automatically handle decimals. It is up to the end user to properly handle it.

Example with a token with 6 decimals:

1000000000 passed into create stake function = Stake with 1000 voting power

Parameters:

• amount: The amount of the governance token to be deducted from the user's wallet and added to the stake. Keep the decimals in mind as specified above.

Edit a Stake (editStake)

Previously created stakes can be easily edited. Governance tokens can be added to or removed from an existing stake.

Note that a stake cannot be edited if it has any locks on it. A stake lock will occur if the stake was used to create a proposal or vote on a proposal. Once the active proposal has ended, the user can unlock their stakes.

The only thing to keep in mind is that you should always consider decimals. For example, if your token has 6 decimals then you need to add 6 zeroes to the actual amount of tokens you want for the stake. The Clarity SDK does not automatically handle decimals. It is up to the end user to properly handle it.

Example with a token with 6 decimals:

1000000000 passed into create stake function = Stake with 1000 voting power

Parameters:

• stakeTxOutRef: This is a property of the stake information returned from the getStakes function call.

• changeAmount: If positive, the amount to add to the stake. If negative, the amount to remove from the stake. Keep the decimals in mind as specified above.

Unlock Stakes (unlockStakes)

When a user uses their stake to create a proposal or vote on a proposal, a lock is added to the stake. These locks will need to be removed by the user if the stake create proposal limit for the DAO is reached or if they wish to delete their stake.

Locks can only be removed for one proposal at a time. Multiple stakes can be unlocked with one function call; however, all stakes MUST have locks from the same proposal. The locks can be from creating a proposal or voting on a proposal. It does not matter as long as the locks are from the same proposal.

Parameters:

• stakeTxOutRefs: Array of the txOutRef properties from the stake information returned from the getStakes function call. Only include stake txOutRefs that have locks from the same proposal.

• proposalTxOutRef: The txOutRef property of the proposal information returned from the getProposals function call. Needs to be for proposal that has an active lock on the stakes you wish to unlock.

Delete a Stake (deleteStake)

If the user wishes to receive back their governance tokens, they will need to delete their stake. The only requirement for deleting a stake is that the stake has no active locks.

Parameters:

• stakeTxOutRef: This is a property of the stake information returned from the getStakes function call.