Before you get too excited, this is not the Ravencoin network paying for staking. Ravencoin is still proof-of-work only.

The term dividend or reward can be used interchangeably as it relates to the Ravencoin network. This is a feature that was on the original roadmap. The purpose of this feature is to fairly distribute RVN or Tokens/Assets to token holders.

There are a few reasons that you might want to use this capability of the Ravencoin platform. Each of them is described below with the actual RPC calls you would make.

Profit Distribution

Let’s say you’ve created a corporation. Let’s say its a LEMONADE stand in Venezuela. Your very successful lemonade stand has made a profit of 10,000,000 Bolivars. At the time of this writing (Nov 22, 2019), that is 14,026 RVN.

Let’s say you have 21 holders of the 1000 LEMONADE tokens and that each token represents 1/1000 share of equity in your lemonade stand.

The Ravencoin blockchain knows exactly which addresses hold those LEMONADE tokens at any given block height and you’d like to distribute the profits to those LEMONADE token holders.

Step 1: Turn those volatile Bolivars into more stable RVN. (exercise left to the reader).

Step 2: Get the exact LEMONADE token distribution at a point in time. You can go back in time by setting block height in the past. Or set it to now by using the current block height. The code will be improved to default to the current block height if left blank (to be completed).

requestsnapshot LEMONADE [block_height]

Step 3: Distribute the value as RVN.

distributereward LEMONADE block_height RVN 14026

This will distribute RVN to the holders of the LEMONADE token such that each LEMONADE holder will get the same amount of RVN per LEMONADE token they hold. It will be a fair distribution.

Stock Split

Let’s say your lemonade empire has become so successful that each of the 1000 LEMONADE tokens is too expensive for a regular investor to afford. You want everyone to share in the success of your lemonade empire so you decide to do a stock split. All that does is make each token worth a smaller share of the lemonade empire, but it does bring the LEMONADE token into financial reach for more investors.

Your board of directors decides that instead of each LEMONADE token representing 1/1,000 of the lemonade empire, each token will represent 1/1,000,000 of the lemonade empire, making them 1,000 times more affordable.

Step 1: Get the exact LEMONADE distribution at a point in time.

requestsnapshot LEMONADE [block_height]

Step 2: Reissue 999,000 more LEMONADE tokens, bringing the total issued up to 1,000,000.

Step 3: Distribute the newly issued LEMONADE to the existing LEMONADE token holders.

distributereward LEMONADE block_height LEMONADE 999000

For every one LEMONADE token held, the holder will get 999 more. You’ve effectively done a stock split with a fair distribution to the existing holders.

Token Replacement

Let’s say you want to expand your LEMONADE stand into new jurisdictions that have strict rules for tokens. So you decide to give a $LEMONADE Restricted Asset to every holder of a non-restricted LEMONADE token.

Step 1: Issue 1000 $LEMONADE restricted tokens because you have 1000 outstanding LEMONADE regular tokens.

Step 2: Get the exact LEMONADE distribution at a point in time.

requestsnapshot LEMONADE [block_height]

Step 3: Distribute the $LEMONADE restricted tokens to the LEMONADE token holders.

distributereward LEMONADE block_height $LEMONADE 1000

This will distribute $LEMONADE to the holders of the LEMONADE token such that each LEMONADE holder will get one restricted $LEMONADE for each LEMONADE they hold. Now $LEMONADE can represent 1/1000 of your lemonade stand and you can use the tools provided for Restricted Assets to stay compliant as you move into new jurisdictions.

Voting

Note: This does not rely on the future feature on the roadmap for voting which can remove the vote tokens from the UTXO set after the vote expiration.

You’d like to hold a vote of your LEMONADE shareholders to determine where to expand the lemonade empire.

Step 1: Issue 1000 LEMONADE/VOTETOKEN

Step 2: Get the exact LEMONADE distribution at a point in time.

requestsnapshot LEMONADE [block_height]

Step 3: Distribute LEMONADE/VOTETOKEN to the LEMONADE token holders.

distributereward LEMONADE block_height LEMONADE/VOTE_TOKEN 1000

Step 4: Use the messaging feature to send a message to your LEMONADE token holders on how to vote. Add your message to IPFS and get an ipfs_hash

sendmessage LEMONADE <ipfs_hash> [optional_expire_time]

The message should tell the user which addresses to send their VOTE_TOKEN.

Message Example:

Send VOTE_TOKEN to RUF5wAQtVNxfoJdDCY6j9AwYsmjnnKCt3i to vote for expanding the lemonade empire into Chile.

Send VOTE_TOKEN to R9qN6rZQx8g13xzieMgzBwU2sKqwPXuvRg to vote for expanding the lemonade empire into Canada.

Send VOTE_TOKEN to RXS2FCnpULZPT5WDnyHtpyUQYJC8peaj7M to vote for expanding the lemonade empire into Malta.

FAQ

Q: What if there are leftover tokens because it does not divide evenly? Let’s say there are two token holders and sending three indivisible tokens to those two holders — what happens?

A: The algorithm is fair, so anything that can’t be sent out fairly will be returned as change. This might be just a few 1/100,000,000 of RVN, or it may be a few indivisible tokens.

Q: What if I don’t want to send a reward to all the addresses?

A: This can happen because you might have a treasury stock that is used to draw from, but isn’t actually distributed to shareholders. When distributing, you can add another optional parameter, which is a list of addresses to not distribute to, and the system will take those into account and re-calculate the distribution.

Q: Why does it take two steps to send a reward with a required snapshot and why does it have an option to pass in a block height?

A: There are two reasons. 1) The distribution could change at any time if the tokens are being sent around. By setting block height, the software has a fixed point in time that it can use to calculate the distribution. 2) It allows you to go back in time. For example, you might have a dividend distribution date like midnight on 11/22/2019. I expect that we’ll be able to combine the two steps into one step for the case where it is ok to do the snapshot on the last known block.

Q: How much does it cost in fees?

A: That depends on how many outputs are created. It does cost 0.01 RVN per byte to send transactions. The dividend/reward feature is optimized and it will try and put many outputs into a single transaction when it can to save space and transaction fees.

Q: What if the transaction is too large?

A: That is one of the big advantages of using rewards feature to create transactions instead of scripting them yourself. If a transaction is too large then it will break it into smaller pieces. If too many are chained together, it will wait until a block has been mined, and then continue.

Q: Can I send RVN to token holders or Restricted Asset token holders?

A: Yes

Q: Can I send a Restricted Token to token holders?

A: Yes, but the transaction will fail if the token holder’s addresses don’t have the right tags for the Restricted Asset. Solution: Temporarily set the rule-set for your Restricted Asset to ‘true’, then change it back after the distribution and the transactions are mined.