Validator Revenue

Read installed bundle and configuration before running commands. Resolve paths from this loaded SKILL.md, not the session working directory.

Install the workspace dependencies from the resolved bundle root with bun install --frozen-lockfile when node_modules is absent.

Run from the resolved bundle root:

bun src/skills/validator-revenue/scripts/revenue.ts \
  --vote-account <VOTE_ACCOUNT> \
  --epochs 30

Use --validator <VOTE_OR_IDENTITY> for identity resolution, --include-current only when requested, and --format markdown|csv|json for output.

The helper uses the operator-selected mainnet RPC, JPool/SVT history, Trillium epoch-specific identity resolution, Jito's official validator rewards and JitoSOL/SOL ratio APIs, Jito's public BAM Boost Merkle distributions, and Marinade's validator-bonds API.

Trillium serves only recent epochs. For an epoch it does not cover, the helper uses the identity recorded in that epoch's JPool/SVT history row and reports the choice as bamBoostIdentitySource (trillium or svt-history) in JSON and CSV and as a note under the Markdown table. A JPool/SVT row records the identity used in its own epoch, not the validator's current one (checked on 2026-10-07 against Trillium's per-epoch data for 12 validators that changed identity), so not_allocated on an svt-history epoch is a real zero for that identity. The row holds one identity per epoch; an identity change inside an epoch is not represented. identity_missing means neither source supplied an identity, so that epoch's BAM Boost allocation is unknown, not zero; say so when it appears inside the reported window.

When JPool/SVT returns no rows for the first requested epochs, the helper shortens every source to the available epochs and states which requested epochs are unavailable (requestedFirstEpoch and firstEpoch in JSON; standard error for CSV). Repeat that scope whenever quoting totals. The helper cannot tell a validator that started later from rows missing upstream, so do not describe the first available epoch as the validator's first epoch without another source. A gap after the first available epoch still fails. skip_rate_pct is derived from leader-slot counts and is empty for an epoch without leader slots or without both counts.

For a Marinade bidding bond, when an epoch has no published ValidatorBond-funded Bidding events globally, estimate its pending bidding cost using that epoch's https://scoring.marinade.finance/api/v1/scores/sam?epoch=N row: effectiveBid × values.marinadeActivatedStakeSol / 1000. The API's effective bid is in SOL per 1,000 SOL per epoch and includes static/dynamic bid components; do not substitute configured CPMPE, target stake, total validator stake or another epoch's data, or add dynamic commissions a second time. Missing, duplicate, mismatched-epoch or invalid bid/stake data fails the estimate rather than becoming zero.

Keep marinadeBondPaymentSol as published payments and report marinadeBondEstimatedPaymentSol separately; deduct both from net revenue. Preserve the estimate's bid, activated stake and source URL in output and label affected net totals as provisional. Replace the estimate with published Bidding costs on subsequent queries, never add both for the same bidding obligation. Global Bidding publication is only an availability proxy: no_record means no matching published payment, not a verified zero liability, and publication can be partial. Auction-snapshot estimates exclude additional penalties/PSR and may differ from final settlement; existing published non-bidding costs remain included. Do not apply the SAM formula to institutional-only bonds. See Marinade settlement rules.

blockFeeRewardSol (block_fee_reward_sol, Markdown "Block Fees") is JPool/SVT votingReward, which is the validator identity's leader block fee rewards: the sum of getBlock rewards with rewardType Fee for the identity over its produced slots (verified to the lamport for epochs 1063-1066, TowerBFT and Alpenglow; JPool/SVT does not publicly document the field). It is not a vote reward. TowerBFT vote credits and Alpenglow vote rewards are paid through epoch inflation to stake accounts, and the operator's share appears only as commissionRewardSol. Never describe Block Fees as voting rewards. The JSON votingRewardSol key and the trailing CSV voting_reward_sol column are deprecated aliases with the same value, kept for one release so existing consumers can migrate; new consumers must read blockFeeRewardSol / block_fee_reward_sol.

Net revenue deducts vote transaction fees and the Alpenglow VAT. votingFeeSol (voting_fee_sol) is JPool/SVT's vote transaction fees, a TowerBFT cost; label it "vote transaction fees (TowerBFT; partial in 1064)", not a generic voting fee. From mainnet epoch 1064 (Alpenglow, 2026-10-21) a VAT of 0.8 SOL is debited from the vote account at the start of epoch N to admit it for epoch N+1. Attribute VAT to the epoch in which it is debited (epoch N), and repeat that convention when quoting VAT or net. vatSol (vat_sol) comes from JPool/SVT vatDebit (lamports) when published (vatStatus svt); otherwise from the vote account's VATDebit block reward in the first confirmed block of that epoch, read through getBlock rewards (rpc_block, block in vatBlock). Epochs before 1064 are pre_alpenglow with VAT 0 by definition. rpc_absent (first block has no VATDebit for this vote account) and missing (neither source available) are provisional: VAT is shown as 0 but not established, so say loudly that net for those epochs and the totals are provisional and may be overstated by up to 0.8 SOL per epoch. When JPool/SVT reports admissionFailure: true, report it; the vote account was not admitted for the next epoch.

Calculate validator-operator Jito MEV revenue from Jito's official validator rewards as floor(mev_revenue * mev_commission_bps / 10_000). Do not use JPool/SVT's raw jitoReward as revenue because that inflow can include returned Tip Distribution Account rent. Report the raw SVT inflow and excluded difference for reconciliation, but exclude the difference from gross and net revenue.

BAM Boost accounting follows JIP-31's epoch-lagged distribution: a subsidy earned in epoch N is read from claim distributor epoch N+1. Treat presence in Jito's Merkle tree as an allocation, not proof of receipt. Derive the official distributor and Claim Status PDAs and check them at finalized commitment through the operator-selected mainnet RPC. Mark an allocation claimed only when the Claim Status account exists and its owner, discriminator, claimant, and amount match; an absent Claim Status marks a positive published allocation unclaimed, while malformed or mismatched Claim Status data fails verification. Report allocated and claimed amounts separately in raw JitoSOL and historical SOL equivalent.

Convert allocated JitoSOL to SOL with Jito's latest official daily JitoSOL/SOL ratio at or before the first confirmed block of claim epoch N+1, retain the raw JitoSOL amount and rate timestamp in both UTC and local time for auditability, and include the allocated SOL amount in gross and net revenue. Use that same historical rate for the claimed SOL equivalent so allocated and claimed values are comparable; claiming is a receipt-state change and must not add the reward to revenue a second time. Never assume 1 JitoSOL equals 1 SOL.

Use JIP-31 for the earning-to-claim epoch convention, https://storage.googleapis.com/jito-bam-boost/mainnet/<CLAIM_EPOCH>/merkle_tree.json for published allocations, Jito's official jito-bam-boost-cli for PDA and Claim Status semantics, and Jito's jitosol_sol_ratio API for historical exchange ratios.

DoubleZero 2Z rewards are reported in 2Z token units by receipt epoch: the epoch containing the slot of the transaction that credited the validator identity. The helper finds every token account owned by the window's identities (JPool/SVT rows plus the live identity) for the 2Z mint J6pQQ3FAcJQeWPPGppWRb4nM8jU3wLyYbRrLh7feMfvd under both token programs, reads the mint's decimals on chain, lists signatures only back to the first slot of the window, and measures each transaction's identity-owned 2Z balance change from pre/post token balances. A credit counts as a reward only when the transaction invokes exactly one known distributor: Solana publisher rewards J9gupbyffs4XAoKn5NrJ4hrbdqW5ZfvMDaaas3FtH8yC (source publisher; the Distributed ... for YYYY-M log gives the reward month) or the shred oracle dzshrr3yL57SB13sJPYHYo3TV8Bo1i1FxkyrZr3bKNE (source shredOracle; the dz-shred-oracle: distribute_validator_rewards epoch=N sub_epoch=M memo gives the oracle period). Logs and memos only label rewards; they never set amounts. Every other 2Z balance change, including a debit inside a distributor transaction, is reported as unclassified inflow/outflow and is not a reward. Publisher rewards arrive in monthly batches, so receipt epochs are lumpy: most epochs are none and one epoch can hold a whole month. Do not describe a receipt epoch as the epoch in which the reward was earned.

Fields: doubleZeroReward2z (double_zero_reward_2z, exact decimal), doubleZeroReward2zRaw (double_zero_reward_2z_raw, base units), doubleZeroRewardStatus (none, received, unavailable), doubleZeroPublisher2z, doubleZeroShredOracle2z, doubleZeroRewardTxCount, doubleZeroRewardLabels, doubleZeroUnclassifiedInflow2z and doubleZeroUnclassifiedOutflow2z; JSON rows also carry doubleZeroSources (per-source raw amounts, transaction counts, rewardMonths / rewardEpochs) and doubleZeroTransactions, and the top-level doubleZero object records the mint, decimals, identities, token accounts, programs and slot window. Any RPC failure after bounded retries marks every epoch unavailable: unknown, not zero, and say so. A closed 2Z token account is not found by the owner lookup, so its history is not scanned. 2Z is never added to gross or net SOL and has no SOL-equivalent column, because no verified historical 2Z/SOL price source is used.

The Markdown report omits an optional source's columns and totals when it had no activity in any epoch of the window, and prints one line naming the omitted sources. Jito is inactive when operator commission and the raw JPool/SVT Jito inflow are zero in every epoch; BAM Boost when no epoch is allocated (an in-progress epoch's not_published placeholder is ignored, while not_published for a completed epoch or identity_missing keeps the columns because the allocation is unknown); voting compensation and vote transaction fees when zero in every epoch; Marinade bond when no Marinade validator bond exists; DoubleZero when no known distributor transaction credited the identity (an unavailable scan keeps it shown, and unclassified 2Z movements are still printed as notes). Block fees, commission, gross, VAT, net and blocks are always shown. JSON keeps every field and adds activeSources and omittedSources; CSV keeps a stable column set (the existing Marinade columns still appear only when a bond exists).

Report the completed epoch range, bond status, per-epoch revenue components, official Jito MEV commission, excluded SVT Jito inflows, BAM Boost allocated and claimed JitoSOL, historical allocated and claimed SOL equivalents, allocation and claim statuses, vote transaction fees, VAT with its status and attribution convention, admission failures, DoubleZero 2Z by receipt epoch with source and labels as a separate token line, omitted sources, totals, missing rows, and assumptions. Use validator-performance for credits, rank, skip rate, and block production.

Local profiles and first use

Read chain profile selection and first use. Use --profile NAME and optional --config PATH to reuse setup; resolve missing configuration through onboarding, then resume this check.