Baj-Armero Dividend Logic: Is There a Better Way?

Hey everyone,

Today I want to talk about the dividend distribution tool for the Armero project, which I nicknamed Baj (it's Klingon for "reward," figured it fit!). Specifically, I want to walk through how it currently calculates the HIVE dividend paid out to ARMERO token holders and open the floor to see if there are smarter or better ways to handle this kind of distribution.

The Current Logic

The script aims to distribute a portion of the HIVE held in the @armero account to holders of the ARMERO token, based on how much ARMERO is circulating. Here's a breakdown of the calculation steps:

1. Get Available HIVE: First, it checks the available HIVE balance in the @armero account. This is the total pool of HIVE available for the dividend payout in this run. Let's call this DividendPool_HIVE.

2. Calculate Circulating ARMERO: It figures out how many ARMERO tokens are "in the wild". It does this by getting the total supply of ARMERO and subtracting the amount held by the @armero account itself (treasury/undistributed tokens). This gives the circulating supply held by users, let's call it Circulating_ARMERO.

3. Determine Funding "Units": It then calculates a "dividend unit" based on the circulating supply: divunit = Circulating_ARMERO / 1000. This divunit represents 0.1% of the circulating ARMERO or 0.001 Hive per WHOLE Armero.

4. Calculate How Many Units to Fund: Next, it sees how many of these divunit amounts can be fully funded by the available DividendPool_HIVE. It uses integer division: numdiv = DividendPool_HIVE // divunit. This numdiv essentially tells us how many "thousandths of the circulating supply" worth of HIVE we can afford to distribute right now. Looks something like this:

5. Calculate Reward Rate: Finally, it calculates the actual HIVE reward amount paid per ARMERO token held by a user. The code calculates this as reward = numdiv * 0.001 HIVE per ARMERO. (Mathematically, this works out: Total HIVE to distribute = numdiv * divunit; Reward per ARMERO = Total HIVE to distribute / Circulating_ARMERO = (numdiv * divunit) / Circulating_ARMERO = (numdiv * (Circulating_ARMERO / 1000)) / Circulating_ARMERO = numdiv / 1000).

6. Distribute: The script then gets the richlist and pays out UserHolding * reward HIVE to each user (excluding blacklisted accounts).

The Implementation

from nectar.account import Account
from nectar.hive import Hive
from nectarengine.api import Api
from nectarengine.tokenobject import Token
from nectarengine.wallet import Wallet as hwallet

# Initialize Hive blockchain instance with nodes
hv = Hive(nodes=["https://api.hive.blog"])
# Initialize API endpoint for Nectar Engine
api = Api(url="https://engine.thecrazygm.com/")
# Initialize wallet for user 'armero' connected to Nectar Engine API
hwallet = hwallet("armero", api=api)
# Create a Token instance for the "ARMERO" token
armero = Token("ARMERO")
# Get the balance of "ARMERO" tokens held by 'armero' wallet
abalance = hwallet.get_token("ARMERO")
# Get the available HIVE balance of the 'armero' account on the Hive blockchain
balance = float(Account("armero", blockchain_instance=hv).get_balance("available", "HIVE"))
# Get the total supply of "ARMERO" tokens
supply = float(armero["supply"])
# Get the amount of "ARMERO" tokens currently held by the wallet
held = float(abalance["balance"])
# Calculate the amount of tokens that are not held by 'armero' (tokens in the "wild")
wild = supply - held
# Calculate the dividend unit based on 'wild' tokens divided by 1000
divunit = wild / 1000
# Calculate how many dividend units the user's HIVE balance can cover (integer division)
numdiv = balance // divunit
# Calculate the reward by multiplying dividend units by 0.001 (dividend per unit)
reward = numdiv * 0.001

# Print all the variables to show the step-by-step math and output
print(f"Balance: {balance}")
print(f"Supply: {supply}")
print(f"Held: {held}")
print(f"Wild: {wild}")
print(f"Dividend Unit: {divunit}")
print(f"Dividend Units: {numdiv}")
print(f"Dividend: {reward}")

The Question:

So, the current method determines the HIVE-per-ARMERO payout rate based on how many 0.1% chunks of the circulating supply can be funded by the available HIVE balance. It works, and it ensures the @armero account doesn't try to pay out more HIVE than it has.

But is this the best or smartest way?

• Does tying the payout unit directly to Circulating_ARMERO / 1000 = 0.001 Hive per whole ARMERO, make the most sense?
• Are there fairer or more efficient distribution models for this kind of token dividend?
• Could we factor in other metrics?

I'm putting this out there to the community – especially those experienced with tokenomics, dividends, or smart contracts. What are your thoughts? Are there established patterns or clever mechanisms that might be a better fit for distributing HIVE dividends to token holders like this?

Looking forward to hearing your ideas and feedback!

EDIT: If you want to see what it calculated the last time it ran, it ran recently: Sanitorium Society Dividend Apr 17, 2025

As always,
Michael Garcia a.k.a. TheCrazyGM