Harvesting

The process of creating new blocks is called harvesting.

In this process, the account that harvests a block—called the harvester—is rewarded with the transaction fees added in the block and the inflation tokens generated, if applicable.

Once an account harvests a block, the block recorded stores in its header the public key and signature generated by the harvesting account.

Eligibility criteria

The importance score determines the probability of an account to harvest the next block in case the account has harvesting turned on and all other accounts are harvesting too.

An account needs to hold a minimum amount of harvesting mosaics to have importance greater than zero. Eligible accounts can use their importance scores to create new blocks either by running a node or delegating it to a remote node.

Harvesting mosaic

Catapult software allows the definition of any mosaic for harvesting purposes to fit the business needs. The catapult test network names this mosaic cat.harvest.

For example, consortium networks can distribute harvesting mosaics between the companies that are running the infrastructure, while other participants need to pay fees in the form of currency mosaic to consume services.

By contrast, public networks might decide to use the same mosaic for paying transaction fees and running the network.

Local harvesting

An eligible account can harvest new blocks by running a node. To harvest locally, provide the private key in config-harvesting.properties file.

Besides, each node can set a beneficiary public key to share a percentage of the harvesting rewards (fees and inflation), being the sharing ratio configurable for each network. When the node does not define a beneficiary, all the rewards go to the block signer.

graph TD A(Node) --> |Harvests| B(Block) B --- |Reward| C(100.cat.currency) C --> | 90.cat.currency | D(Harvester Account) C --> | 10 cat.currency | E(Beneficiary Account)

Rewards division when the network’s sharing ratio equals 10%

Local harvesting is secure as long as no one accesses your node instance, which is storing the private key.

Delegated harvesting

An eligible account may also delegate its importance score to a remote node for harvesting.

Delegated harvesting enables an account to use a proxy private key that can be shared with a node securely. In other words, you can use the importance score of your account to create new blocks without running a node.

sequenceDiagram participant Account participant Network participant Node Account ->> Network: AccountLinkTransaction(remotePublicKey) activate Network Network -->> Account: Confirms transaction deactivate Network Account ->> Network: TransferTransaction(nodePublicKey, encryptedRemotePrivateKey) activate Network Network -->> Account: Confirms the transaction deactivate Network Network -->> Node: Sends notification opt eligible remote account Node ->> Node: Adds delegated harvester Node ->> Node: Saves remote private key on disk end

Delegated harvesting activation diagram

To enable delegated harvesting, the account owner has to link its importance score to a remote account announcing an AccountLinkTransaction.

Then, the account needs to send a special encrypted message to the node via a TransferTransaction. The message must contain the remote’s account proxy private key encrypted using AES, so that only the recipient will be able to decipher it.

The node receives an encrypted message using WebSockets. Once the node decrypts the private key of the potential delegated harvester, the node owner can add the remote account as a delegated harvester if the candidate meets the requirements.

As the remote private key is saved on disk, even if the node disconnects temporarily, the persistent delegated harvesters will be reestablished once the node reconnects to the network. Additionally, the use of encrypted message creates a backup of the information for the nodes. If the disk containing the delegated keys becomes corrupted or destroyed, the node owner can retrieve the data by querying the blockchain.

Security-wise, sharing a proxy private key does not compromise the original account since:

  • The remote account has zero balance.
  • The remote account by itself can’t transfer the importance to another account.
  • The original account receives the resulting fees.

Remote harvesters may not receive the entire reward if the following conditions are met:

  • The network harvesting sharing rate is greater than 0.
  • The node selected has defined a beneficiary account.
Comparison between local and delegated harvesting
  Local harvesting Delegated harvesting
Configuration Setup a catapult-server node. Activate remote harvesting.
Cost The node maintenance (electricity, cost VPN). AccountLinkTransaction + TransferTransaction announcement fees.
Security The node stores the private key. A proxy private key is shared with a node.
Reward Total reward. The node owner can share part of the reward with a beneficiary account. Total reward - node’s beneficiary share.

Schemas

AccountLinkTransaction

Announce an AccountLinkTransaction to delegate the account importance to a remote account.

In order for the remote account to be accepted for delegated harvesting, it needs to meet the following conditions:

  • It cannot own any mosaics.
  • It cannot be a cosignatory of any other account.
  • It cannot be a multisig account.
  • It cannot already be a remote account for another account.
  • It cannot be its own remote account.

Furthermore, for the duration that the account is used as a delegated account, it is restricted from:

  • initiating any transactions.
  • involvement with any type of transactions.

Version: 0x01

Entity type: 0x414C

Inlines:

Property Type Description
remotePublicKey Key Remote account public key.
linkAction LinkAction Account link action.

LinkAction

Enumeration: uint8

Id Description
0x00 Unlink account.
0x01 Link account.