The hourly reward evaluator

Half of this addon's commission rules are not paid by the code that processed the transaction. They are paid by one hourly cron job, and when that job is not running, or is running and quietly refusing to pay, nothing on any affiliate screen says so. The referrals still list, the conditions still show their rates, the dashboard still totals what it paid last month. Only the number stops growing.

This page is how to find that job, read what it said, and work out which of the six things it needs is missing.

Where it lives

Admin → System → Scheduled Tasks (/admin/system/cron), category filter MLM.

What one run does

The job is read-only on transactions and creates only reward rows. It never credits a wallet and never records a platform loss — that happens when the member presses Claim. Its one write outside mlm_referral_reward is creating the referrer's empty payout wallet.

The skip list — 19 rules this job never touches

Conditions whose commission is paid at the moment of the trade are skipped here by name, so no activity is ever paid twice. Each one logs Skipping <NAME>: it is paid when the transaction happens, not on a schedule.

WELCOME_BONUS · ECOMMERCE_PURCHASE · ICO_CONTRIBUTION · STAKING · STAKING_LOYALTY · AI_INVESTMENT · INVESTMENT · GENERAL_INVESTMENT · FOREX_INVESTMENT · NFT_PURCHASE · NFT_SALE · P2P_TRADE · P2P_TRADE_COMPLETION · COPY_TRADING · FUTURES_TRADE · BINARY_WIN · BINARY_TRADE_VOLUME · FX_TRADE_COMMISSION · FX_TRADE_VOLUME

Seeing your rule in that list is the answer to "the cron ran and my condition was not evaluated". It was not meant to be. If that rule is not paying, the problem is in the addon that owns the trade, not here. Nothing on the conditions screen labels a rule EVENT or CRON — the sidebar rows carry the condition's title, its rate and its wallet type, and that is all. The way to tell is to open the condition and read the System name in its banner (WELCOME_BONUS, SPOT_TRADE, …) against the list above. The one place the split is written out is the overlap warning card, which annotates each other condition competing for the same activity as "paid at the moment of the event" or "paid by the periodic evaluator" — never the condition you have open. Commission conditions covers the split.

The evaluation window, and the period key

A condition's period — DAILY, WEEKLY or MONTHLY — is a fixed calendar window in UTC, not a rolling lookback. The window and the idempotency key are derived from the same boundaries, so a transaction can never fall into two different keys across runs.

Every condition is evaluated twice per run: once over the in-progress period, then again over the period that just closed. Without the second pass, a qualifying transaction landing after a period's final hourly tick but before the calendar boundary would fall into no window at all — the next run starts fresh at the new boundary and never looks back. Re-evaluating the closed period is harmless because the key already exists.

Idempotency — and why a deleted reward never comes back

Every reward this job creates carries a deterministic sourceId:

${conditionId}_${referrerId}_${referredId}_${periodKey}

mlm_referral_reward.sourceId has a unique index (mlmReferralRewardSourceIdUnique), and the existence check runs with paranoid: false — it reads soft-deleted rows too.

The same key is what makes a manual Run now safe: a second run inside the same period re-reads the same volume, computes the same keys, finds them all present and creates nothing. A concurrent run that loses the race is caught by the unique constraint and logged as Reward already exists for <sourceId> (unique constraint).

Currency — the conversion happens before the sum

A Bicrypto transaction row carries no currency of its own; the amount is denominated by the wallet it sits on. The reward, however, is credited verbatim in the condition's rewardCurrency at claim time. So every amount is converted into that currency before it is summed and before it is compared to minAmount:

• Rates are built with getConversionRates, which prices both legs through USD. exchangeCurrency.price is USD per unit and multiplies; currency.price (fiat) is units per USD and inverts.
• minAmount is converted into each wallet's currency so the threshold stays in SQL, per transaction. Applying it after SUM() would let ten sub-threshold trades qualify as one.
• A currency neither price table can quote is excluded, never counted 1:1 — counting an unpriced token at parity is how 0.4 BTC becomes 0.40.

Two consequences an operator has to know:

If the reward currency itself cannot be priced, that condition pays nobody — including activity already denominated in that currency. With no denominator there is nothing to value against, so the whole condition is skipped.

If a referred user's wallet currency cannot be priced, that volume silently does not count. The member traded, the condition is fine, and the reward is smaller than it should be. The job says which currencies it dropped.

Reading the run — and the two different logs

This is the single most misunderstood part of the job, and it is worth being blunt about.

The live log is produced only while somebody has the cron screen open. The job checks whether the dashboard has an audience before it builds a log message at all; with nobody watching, those lines are never created. So "read the cron log" means: open Admin → System → Scheduled Tasks, press Run now on Process MLM Referral Conditions, and watch. Reading it after the fact is not possible for anything except the error and warning lines, which also go to pm2 logs cron. See Logs for where those files live.

The lines that mean something is wrong

Why a broken condition produces one line, not thirty-five

The two rate warnings go through a deduplicator. Each is keyed on the problem, not the condition — thirty-five conditions paying in one unpriceable currency are one misconfiguration — and is emitted:

• at most once per run (in-memory), and
• at most once per four hours across runs, using the Redis key mlm:cron:warn:<key> with NX and a 4-hour expiry. The key is shared across processes, so a split deployment does not multiply it.

The live console still gets one line every run, because that view is ephemeral and an operator watching it should see the current state. Only the persistent log is throttled.

The payout wallet the job creates

When a reward is created, the job checks whether the referrer holds a wallet of the condition's rewardWalletType and rewardCurrency, and creates one through the wallet creation service if not. On success it logs Created SPOT USDT wallet for referrer <id> so the reward can be claimed.

This is a head start, not a dependency. If creation fails — an ECO wallet generates an on-chain address and can fail for reasons that have nothing to do with the reward, such as a missing master wallet or a dead RPC — the job logs Could not pre-create the … wallet for referrer <id>: <reason>. The claim endpoint will retry it. and carries on. The reward is still created. The claim endpoint does the same get-or-create when the member presses Claim, so the consequence of a failure here is that the failure resurfaces at claim time instead of being visible to you now.

Wallets are created for the referrer only, never for referred users. An empty wallet has no transactions to sum, so creating them would silence the "nobody holds a wallet" diagnostic without making one person qualify.

Run states, and what a failure costs

The job broadcasts its state twice per run — running when it starts, then completed or failed when it ends. The cron screen renders that in three places: the job row's badge, the Attention tab count, and the detail modal's recent-runs strip with its success rate.

A failed run is not a lost period. The failure is raised before or during evaluation, so the run's rewards were never created — and because the window is a calendar period, not "the last hour", the next successful tick re-evaluates the same period and creates them. A single failure costs an hour of delay, not a day of commission.

Each run also re-evaluates the period that has just closed, so a job that fails for a whole day and recovers the next still picks up yesterday's DAILY rewards. What it does not reach is two periods back. A job that has been failing across two consecutive periods — two days on a DAILY condition, two months on a MONTHLY one — has permanently lost the older of them, because the window only ever looks back one boundary. That is the point at which a stuck cron becomes unrecoverable money rather than a delay, and it is the reason the Attention tab's count is worth alerting on.

Individual conditions fail independently. An error inside one condition is caught, logged as Error evaluating condition <id>: …, and the run continues with the next condition — so a single broken rule does not stop the other thirty-four, and the run still reports completed.

Running it by hand

Manual runs are safe to repeat: the sourceId makes a second run inside the same period a no-op.

"Nobody is being paid" — the check order

Work down this list. Each step is cheap and rules out everything below it.

What this job cannot explain

• A reward that exists but cannot be claimed. That is the payout threshold or the withdraw_affiliate KYC gate — see Rewards and payouts.
• A referral that never attached. Attribution happens at registration and is nothing to do with this job — see Troubleshooting.
• A tree that looks wrong. Placement and spillover are display-only and do not change who is paid — see Referral structures.