This site requires Javascript to be enabled.

Managing rewards

To get an overview of the Archway rewards system, please read the following Archway Rewards System Overview.

This guide will explain how rewards are managed on the Archway Network, detailing the operations needed to track and receive rewards.

Contract metadata

Contract metadata provides information to the Archway Network about the contract owner and the address to which rewards should be sent. The metadata has three specific parameters:

  • contract_address - The address of the deployed contract.
  • owner_address - The address of the contract's owner. This field can be both an account or contract address.
  • rewards_address - The account address that will receive the contract's rewards. This field can be either an account or a contract address. Tokens are sent to this address after executing the withdrawal function. If this field is not set, the contract will not receive rewards.

Setting the contract metadata

The contract metadata must be set or modified by using the MsgSetContractMetadata transaction which the contract admin must sign. After the initial transaction to set the metadata, only the owner address can update the metadata.

{  "contract_address": "archway14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9sy85n2u",  "owner_address": "archway12reqvcenxgv5s7z96pkytzajtl4lf2epyfman2",  "rewards_address": "archway12reqvcenxgv5s7z96pkytzajtl4lf2epyfman2"}

via Archway Developer CLI

To set contract metadata via the Archway Developer CLI, use the following command:

archway contracts metadata CONTRACT [--json] [--log-level debug|error|info|warn] [--owner-address <value>] [--rewards-address <value>][--keyring-backend file|os|test] [--keyring-path <value>] [-f <value>] [--fee <value>] [--no-confirm] [--gas-adjustment <value>]

A basic example would be:

archway contracts metadata increment --owner-address "archway12qj4v8jg5pxk6gsqct09sf9szhwql69xmf9fh4"  --rewards-address="archway12qj4v8jg5pxk6gsqct09sf9szhwql69xmf9fh4"

Arguments:

CONTRACT (required) Name of the contract

Example output:

archway contracts metadata increment2 --owner-address "archway12qj4v8jg5pxk6gsqct09sf9szhwql69xmf9fh4"  --rewards-address="archway12qj4v8jg5pxk6gsqct09sf9szhwql69xmf9fh4"✔ Enter the name or address of the account that will send the transaction … archway12qj4v8jg5pxk6gsqct09sf9szhwql69xmf9fh4Setting metadata for contract increment2  Chain: constantine-3  Contract: archway1aj4u4qdfqdnenmj4zn99wc8qev09wseytg0xr8eerwk7v0uhsevsqjf6zl  Rewards: archway12qj4v8jg5pxk6gsqct09sf9szhwql69xmf9fh4  Owner: archway12qj4v8jg5pxk6gsqct09sf9szhwql69xmf9fh4  Signer: mywallet✅ Metadata for the contract increment2-0.1.0 updated  Transaction: D7CBE945F9A464ACB6214FA7E710EB9A147983FE052D68A89FB97C0C5A50BE30

via archwayd

To set the contract's metadata via archwayd, execute the following command, substituting [contract-address], [owner-address], [rewards-address], and [mywallet]:

mainnet

testnet

archway tx rewards set-contract-metadata [contract-address] --owner-address [owner-address] --rewards-address [rewards-address] --from [mywallet] --node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --gas auto --gas-prices $(archwayd q rewards estimate-fees 1 --node 'https://rpc.mainnet.archway.io:443' --output json | jq -r '.gas_unit_price | (.amount + .denom)') --gas-adjustment 1.3 -y --output json

Set contract flat fee

Archway enables dapp developers to define a custom flat fee which we call a Contract Premium, for interacting with their smart contracts. These fees provide developers with a versatile alternative to monetize their contracts. For the user's experience, the Contract Premium will be paid alongside the gas fee.

via Archway Developer CLI

To set or nodify the flat fee via the Archway Developer CLI, use the following command, where CONTRACT is the name of the contract:

archway contracts premium [CONTRACT] --premium-fee [value]

Here's an example:

archway contracts premium my-contract --premium-fee "1aconst"

via archwayd

To set the contract's flat fee via archwayd, execute the following command, substituting [contract-address], [fee-amount] and [mywallet]:

archway tx rewards set-flat-fee [contract-address] [fee-amount] [flags]

mainnet

testnet

archway tx rewards set-flat-fee [contract-address] [fee-amount] --from [mywallet] --node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --gas auto --gas-prices $(archwayd q rewards estimate-fees 1 --node 'https://rpc.mainnet.archway.io:443' --output json | jq -r '.gas_unit_price | (.amount + .denom)') --gas-adjustment 1.3 -y --output json

Reward Storage

The rewards owed to a specific contract are stored as a separate record on the blockchain. To receive these rewards, a withdrawal operation must be executed. Developers can also track these rewards by using the RewardsRecord object.

Tracking Reward Amounts

The RewardsRecord object is used to track the rewards that have been calculated for a specific rewards_address.

Example Request - RewardsRecord

You can use the following command to query the rewards record for a specific address:

archwayd q rewards rewards-records "${rewards_address}" --node "${node_url}" --output json | jq .

mainnet

testnet

archwayd q rewards rewards-records archway12reqvcenxgv5s7z96pkytzajtl4lf2epyfman2 --node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --output json | jq .

Example Response

As a result, you would get a similar response:

mainnet

testnet

{  "id": "1",  "rewards_address": "archway12reqvcenxgv5s7z96pkytzajtl4lf2epyfman2",  "rewards": [    {      "denom": "aarch",      "amount": "10000"    }  ],  "calculated_height": 100,  "calculated_time": {    "seconds": 1660591975,    "nanos": 0  }}

Where you are able to see the following fields:

  • id - Each Reward Record has a unique ID. This can be used to only withdraw certain reward records.
  • rewards_address - The account address that will receive the contract's rewards. Tokens are sent to this address after executing a withdrawal function . If not set, the contract will not receive rewards.
  • denom- The token type/denmoination. uarch is the default token of the Archway Network.
  • amount- The calculated reward amount.
  • calculated_height - The block height of the rewards when the rewards were calculated.
  • calculated_time - The block time of when the rewards were calculated.

Withdrawing Rewards

After rewards are calculated, a withdrawal operation must be executed before they are sent to the rewards_address.

The withdrawal operation is completed by using the MsgWithdrawRewards message.

Only the address set in the rewards_address can claim the rewards.

Example Request

You can use the following command as a reference to how rewards can be withdrawn:

mainnet

testnet

archwayd tx rewards withdraw-rewards --records-limit 100000 --from "${rewards_address}" --node https://rpc.mainnet.archway.io:443 --chain-id archway-1

Where the following flags can be set:

  • record_limit - Is the maximum number of the Reward Records that be withdrawn. If the limit is 0, the default limit is used in the withdrawal.
  • record_ids - If you want to withdraw specific Reward Records, an array of those ids can be included.
  • reward_address - The reward address that has been set in the Contract Metadata.
  • node - Endpoint of the node to be connected to.
  • chain-id - The Archway Chain ID that the contract is on. A list of the available chain IDs can be found here.

Response

If the Withdraw Rewards operations is successful, the response will show the number of reward records processed and the total amount of rewards that have been transferred to the rewards_address.

Querying Outstanding Rewards

To track what rewards have not been withdrawn and sent to the rewards_adress, use the below command:

mainnet

testnet

archwayd q rewards outstanding-rewards "${rewards_address}" --node https://rpc.mainnet.archway.io:443 --chain-id archway-1 --output json | jq .

Go to the Rewards Reference page for more information on the availabled queries and parameters connected to the rewards.