Skip to Content
Royalties (Barons)

ShareholderRoyalties (Barons)

ShareholderRoyalties distributes ETH from takeovers to veCLAIM holders.

ETH allocation

On every takeover, MineCore allocates ETH to ShareholderRoyalties:

  • genesis takeover (prevKing == 0x0): 100% of pricePaid
  • otherwise: 25% of pricePaid

The contract tracks:

  • pendingShareholderETH: ETH waiting to be indexed
  • ethPerVe: global index (ETH per ve unit), scaled by ACC = 1e18

Index formula (ethPerVe)

Constants:

  • ACC = 1e18
  • MIN_VE_FLUSH = 100e18 (minimum total ve to flush)

Flushing moves ETH from pendingShareholderETH into ethPerVe:

ve.checkpointTotalVe()  # REQUIRED before reading totalVeCached (prevents stale-low denom over-credit)
veTotal = ve.totalVeCached()
if veTotal < MIN_VE_FLUSH: do nothing

# delta = floor(pending * ACC / veTotal)
delta = floor(pendingShareholderETH * ACC / veTotal)
ethPerVe += delta

distributed = floor(delta * veTotal / ACC)
pendingShareholderETH -= distributed

Why MIN_VE_FLUSH exists:

  • avoids pathological ethPerVe spikes when ve supply is tiny
  • keeps rounding dust in pendingShareholderETH

Practical implication for UIs:

  • if total ve is below MIN_VE_FLUSH, ETH stays in pendingShareholderETH
  • it becomes available to Collect once the threshold is met and a flush occurs

User accounting

Per user:

  • userEthPerVePaid[user]
  • claimableEth[user] (ETH available to Collect)

checkpointUser(user):

  • accrues floor( userVe * (ethPerVe - paid) / ACC ) into claimableEth (available to Collect)
  • updates userEthPerVePaid

Marketplace integration:

  • MarketRouter calls checkpointTransfer(from,to) on buys

Collecting (claimShareholder)

ShareholderRoyalties exposes a single entry for users:

  • claimShareholder(mode, targetTokenId, durationSeconds, createAutoMax, minVeOut)

Modes:

  • mode 0: send ETH to user (UI verb: Collect)
  • mode 1: route ETH through Furnace.lockEthReward (ETH → CLAIM + Furnace bonus, locked to veCLAIM)

UI recommendation:

  • Default to mode 0 (Collect ETH).
  • Offer mode 1 (Collect & Lock) as optional compounding.

Notes:

  • The contract name and method names use “claim”. UI copy MUST use Collect for ETH.

Auto-compound (permissionless)

This is an opt-in config. Any caller may execute compounding for an opted-in user (the official keeper runs it in normal operation).

Config fields:

  • enabled
  • paused
  • tokenId destination
  • durationSeconds
  • minCadenceSeconds
  • minEthToCompound

Execution surfaces:

  • compoundFor(user)
  • compoundForMany(users[], minVeOut) (bounded per call)

Pause reasons (analytics codes, Constants):

  • 1 NOT_OWNER
  • 2 LISTED
  • 3 EXPIRED
  • 4 INVALID_TOKEN_ID

Integrator guidance:

  • Treat auto-compound as best-effort.
  • UIs should surface pause reasons and provide a one-click fix (delist, extend, update tokenId).
FurnaceMarket (MarketRouter)