Skip to main content

Application Token Module Transactions (Beta)

Overview​

Application Token Module (ATM) is a fee-sharing mechanism on STABILITY that splits each transaction’s fee between the network validator and the smart contract (“dapp”) that the transaction interacts with​.

In traditional blockchains, validators (or miners) keep all transaction fees; ATM introduces a revenue-sharing model where dApp creators earn a portion of the fees generated by usage of their applications. This aligns incentives across the ecosystem – when a dapp attracts more users and transactions, its developer directly earns more, alongside the validator.

Validators may choose which tokens would be used for the fee payment. This opens up numerous possibilities and incentives for projects to utilize STABILITY.

How It Works​

Whenever a user makes a transaction on STABILITY, such as calling a smart contract function, the fee they pay is not entirely allocated to the block producer. Instead, the fee is split according to a preset percentage between the validator who included the transaction in a block, and the smart contract that was the target or “destination” of the transaction​.

For instance, if the split is 50/50 by default, half the fee goes to the validator and half to the smart contract. This split percentage is configurable by the protocol and may be adjusted. The mechanism provides continuous rewards to dapp owners.

ATM and the Ethereum Virtual Machine​

STABILITY is an EVM-compatible blockchain (built on Substrate), which means developers interact with ATM through familiar Ethereum-like interfaces.

The fee-sharing logic runs in the chain’s runtime, but it’s exposed to smart contracts and external applications via a precompiled system contract called the FeeRewardsVaultController. This precompile lives at a fixed STABILITY address at0x0000000000000000000000000000000000000807. The smart contract code is available on Github.

All ATM functions are accessible via the precompiled contract interface. Developers can use web3.js, ethers.js, or Solidity to call these functions exactly like a normal contract. For example, calling FeeRewardsVaultController.getValidatorPercentage() will return the current fee split percentage allocated to validators​. More importantly, the precompile allows claiming and querying accumulated fee shares through standard function calls, making ATM easy to use.

Earning and Claiming Fees as a Developer​

When a transaction involving a smart contract executes, the ATM mechanism will automatically allocate the validator's and the smart contract's share of the fee into the feeRewardsVaultController.

To claim your funds, your smart contract and dApp must be whitelisted. What this means for a developer is that after deploying a contract, you should apply for or await whitelisting by the protocol’s governance or admin. All contracts accrue their fee share regardless of whitelist status. Your dapp’s share is still recorded. However, only whitelisted contracts are permitted to actually withdraw the funds​.

If your dapp gets whitelisted later, you won’t lose past fees – the accumulated rewards that were held will become claimable once whitelisting is in place​.

From a developer perspective, whitelisting is essentially an approval step ensuring your contract is recognized as a legitimate participant in ATM. The act of whitelisting is done via an admin function (setWhitelisted(address dapp, bool) on the same FeeRewardsVaultController precompile, and it emits an event WhitelistStatusUpdated for transparency. This function is restricted to the contract’s owner – typically a governance or core team address – so developers themselves cannot arbitrarily whitelist.

Claimable rewards can be checked by calling the FeeRewardsVaultController using the getClaimableReward(address dapp, address token) function.

There are two methods for a contract to claim fees that developers should be mindful of when deploying.

The Contract Itself Claims​

Your smart contract can call the precompile’s claimReward(address dapp, address token) function, passing its own address as the dapp parameter and the fee token address. This will transfer any accumulated fee revenue (for that contract and token) from the protocol’s vault to the contract’s account. This approach requires the contract to invoke the claim (which could be done in a function or via a privileged call in your contract logic).

The Contract Owner Claims​

If your smart contract implements a standard owner() function (e.g., as in OpenZeppelin Ownable), the precompile can use it to determine the contract’s owner. The owner (EOA or multisig) can then call claimReward(contractAddress, token) from their external account. The precompile will recognize that the caller is the owner of the given contract (by internally calling owner() on the contract to verify)​

This allows the owner to withdraw the accumulated fees on the contract’s behalf.

Important Note​

If a contract doesn’t implement owner(), the protocol considers it to have no owner, meaning only the contract itself could claim its rewards (if it has some internal mechanism). If the project does not have an owner or a method for the contract itself to claim, then the funds are not retrievable.

Earning and Claiming Fees as a Validator​

Validators also claim their portion through the same vault system. Unlike developers, validators do not need to be whitelisted or approved; any active validator can claim its earned fees freely​.

A validator simply calls claimReward(validatorAddress, token) using its own address to withdraw the fees it has accumulated for that token. The protocol checks that the caller is indeed entitled (in other words, the address is currently an active validator in the consensus) and then pays out the amount. If a validator leaves the validator set, it can no longer claim new rewards. Any unclaimed rewards at that point remain in the vault inaccessible. Validators are expected to claim periodically while they are active.

Example​

Suppose a user calls a function on a DeFi contract on STABILITY and pays 10 XYZ token for the transaction fee. The network’s validator percentage is 50%. The runtime deducts 10 XYZ from the user and holds it in the vault.

After execution, suppose only 8 XYZ token was actually used - then 2 XYZ is refunded to the user from the vault.

Now 8 XYZ remains in the vault for that transaction’s fee. The split logic gives 4 XYZ(50%) to the validator and 4 XYZ (50%) to the dapp. The storage is updated so that the validator’s address now has +4 XYZ claimable and the dapp’s address has +4 XYZ claimable​. An event is emitted recording this split.

Later, the validator calls claimReward(myValidatorAddress, XYZAddress) from its account. The precompile checks that this address is indeed an active validator (allowed) and finds 4 XYZ claimable. It transfers 4 XYZ from the vault to the validator’s account and zeros out the record, emitting RewardClaimed(myValidatorAddress, myValidatorAddress, XYZAddress).

The DeFi contract’s developer (who is the owner of the contract) calls claimReward(dappContractAddress, XYZAddress) from his EOA. The precompile verifies the contract’s owner() is this EOA, and that the contract is whitelisted.

4 XYZ is then transfered from the vault to the EOA (owner) and clears the record, emitting RewardClaimed(dappContractAddress, developerEOA, XYZAddress). Both parties have now received their shares.

Throughout this process, the integrity is maintained by STABILITY, and the interactions are exposed in a familiar format to anyone monitoring or interacting via Ethereum-like tools.

Further Technical Reading​

The implementation details of ATM are documented in STABILITY’s code and ATM Readme available on Github.

The runtime code in Rust that shows the storage structures and fee-splitting logic is available on Github.

The FeeRewardsVaultController solidity code is available on Github, and is located at 0x0000000000000000000000000000000000000807.