tapimo 0.14.0 → 0.15.0

package/src/internal/rewards/Campaigns.ts

@@ -0,0 +1,1205 @@
+import {
+  concatHex,
+  encodeAbiParameters,
+  getAddress,
+  keccak256,
+  parseAbiParameters,
+  stringToBytes,
+  zeroAddress,
+  type Address,
+  type Hex,
+} from 'viem'
+import * as z from 'zod/mini'
+
+import * as Schema from '../Schema.js'
+
+const maximumUint256 = (1n << 256n) - 1n
+// EarnVault permits at most one basis point of conversion-floor loss. Funding at least 10,001 raw
+// EarnShare units makes the loss of less than one raw unit strictly smaller than that bound.
+const minimumSettlementFundingEarnShares = 10_001n
+// Keeps the exact provider batch comfortably inside the signer's 28M gas envelope.
+const maximumFundingLegs = 8
+const leafParameters = parseAbiParameters('uint256,address,bytes32,address,uint256')
+const basisPoints = z
+  .number()
+  .check(
+    z.int(),
+    z.nonnegative(),
+    z.lte(10_000),
+    z.describe('Annual rate in basis points, where 10,000 is 100%.'),
+    z.meta({ examples: [700] }),
+  )
+const positiveBasisPoints = basisPoints.check(
+  z.positive(),
+  z.describe('Positive annual rate in basis points, where 10,000 is 100%.'),
+)
+const uint256 = Schema.DecimalString.check(
+  z.refine((value) => BigInt(value) <= maximumUint256, { error: 'value exceeds uint256' }),
+  z.describe('Unsigned 256-bit integer encoded as a decimal string.'),
+)
+const nonzeroAddress = Schema.Address.check(
+  z.refine((address) => address !== zeroAddress, { error: 'address must be nonzero' }),
+  z.describe('Nonzero Tempo account or contract address.'),
+)
+
+/** Zod schemas for Earn reward campaigns. */
+export namespace schema {
+  const AnnualRate = z
+    .union([
+      z.strictObject({ bps: positiveBasisPoints }).check(z.describe('Fixed annual target rate.')),
+      z
+        .strictObject({
+          maxBps: basisPoints,
+          minBps: basisPoints,
+          morphoVault: nonzeroAddress,
+          staleAfterSeconds: z
+            .number()
+            .check(
+              z.int(),
+              z.positive(),
+              z.describe('Maximum age in seconds of a reusable Morpho rate observation.'),
+              z.meta({ examples: [3_600] }),
+            ),
+        })
+        .check(
+          z.refine((rate) => rate.minBps <= rate.maxBps, {
+            error: 'Morpho minBps must not exceed maxBps',
+          }),
+          z.describe('Base Morpho vault rate source with configured safety bounds.'),
+        ),
+    ])
+    .check(
+      z.describe('Fixed annual rate or bounded Base Morpho vault rate source.'),
+      z.meta({ examples: [{ bps: 500 }] }),
+    )
+
+  const FundingLeg = z
+    .union([
+      z
+        .strictObject({
+          upToAnnualRate: z
+            .strictObject({ bps: positiveBasisPoints })
+            .check(z.describe('Cumulative annual target funded through this leg.')),
+          wallet: nonzeroAddress,
+        })
+        .check(z.describe('Funding wallet responsible up to one cumulative annual rate.')),
+      z
+        .strictObject({
+          remainder: z
+            .literal(true)
+            .check(
+              z.describe('Marks the final wallet as responsible for the remaining target.'),
+              z.meta({ examples: [true] }),
+            ),
+          wallet: nonzeroAddress,
+        })
+        .check(z.describe('Final funding wallet responsible for the remaining target yield.')),
+    ])
+    .check(z.describe('One ordered target-yield funding-waterfall leg.'))
+
+  /** Target-yield configuration for one vault. */
+  export const TargetYield = z
+    .strictObject({
+      annualRate: AnnualRate,
+      endTimestamp: z
+        .number()
+        .check(
+          z.int(),
+          z.positive(),
+          z.describe('Exclusive Unix timestamp when target-yield funding ends.'),
+          z.meta({ examples: [1_788_195_600] }),
+        ),
+      funding: z.array(FundingLeg).check(
+        z.minLength(1),
+        z.maxLength(maximumFundingLegs),
+        z.describe('Ordered funding waterfall ending in exactly one remainder wallet.'),
+        z.meta({
+          examples: [[{ remainder: true, wallet: '0x5000000000000000000000000000000000000005' }]],
+        }),
+      ),
+      intervalSeconds: z
+        .number()
+        .check(
+          z.int(),
+          z.gte(60),
+          z.lte(300),
+          z.describe('Target-yield accounting interval in seconds.'),
+          z.meta({ examples: [300] }),
+        ),
+      startTimestamp: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Inclusive Unix timestamp when target-yield funding starts.'),
+          z.meta({ examples: [1_788_192_000] }),
+        ),
+    })
+    .check(z.describe('Target-yield configuration for one verified Earn vault.'))
+
+  /** Automatic cumulative-payout schedule for one boost campaign. */
+  const PayoutSchedule = z
+    .strictObject({
+      intervalSeconds: z
+        .number()
+        .check(
+          z.int(),
+          z.positive(),
+          z.describe('Interval between automatic boost payouts, in seconds.'),
+          z.meta({ examples: [86_400] }),
+        ),
+      startTimestamp: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Unix timestamp after which the next settlement triggers the first payout.'),
+          z.meta({ examples: [1_788_220_800] }),
+        ),
+    })
+    .check(z.describe('Automatic boost payout schedule.'))
+
+  /** Registered-depositor boost configuration for one vault. */
+  export const BoostRewards = z
+    .strictObject({
+      enabled: z
+        .optional(z.boolean())
+        .check(
+          z.describe('Whether new depositor boost rewards accrue during the configured schedule.'),
+          z.meta({ examples: [true] }),
+        ),
+      endTimestamp: z
+        .number()
+        .check(
+          z.int(),
+          z.positive(),
+          z.describe('Exclusive Unix timestamp when boost rewards end.'),
+          z.meta({ examples: [1_788_195_600] }),
+        ),
+      excludedAddresses: z
+        .array(nonzeroAddress)
+        .check(
+          z.describe('Additional public holders excluded from boost rewards.'),
+          z.meta({ examples: [[]] }),
+        ),
+      funding: z.strictObject({ wallet: nonzeroAddress }).check(
+        z.describe('Wallet funding EarnShare boost settlements.'),
+        z.meta({
+          examples: [{ wallet: '0x5000000000000000000000000000000000000005' }],
+        }),
+      ),
+      intervalSeconds: z
+        .number()
+        .check(
+          z.int(),
+          z.gte(60),
+          z.lte(300),
+          z.describe('Boost-reward accounting interval in seconds.'),
+          z.meta({ examples: [300] }),
+        ),
+      payoutSchedule: z
+        .optional(PayoutSchedule)
+        .check(
+          z.describe('Optional schedule for automatically pushing accumulated boost rewards.'),
+        ),
+      perUserPrincipalCapAssets: uint256.check(
+        z.describe('Maximum qualifying principal per registered wallet in base-asset units.'),
+        z.meta({ examples: ['25000000000'] }),
+      ),
+      startTimestamp: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Inclusive Unix timestamp when boost rewards start.'),
+          z.meta({ examples: [1_788_192_000] }),
+        ),
+      targetAnnualRateBps: positiveBasisPoints.check(
+        z.describe('Target total annual rate for qualified principal, in basis points.'),
+      ),
+      totalPrincipalCapAssets: uint256.check(
+        z.describe('Campaign-wide qualifying principal cap in base-asset units.'),
+        z.meta({ examples: ['10000000000000'] }),
+      ),
+      treasury: nonzeroAddress.check(
+        z.describe('Immutable recipient of unclaimed EarnShare returned by the distributor.'),
+      ),
+    })
+    .check(z.describe('Registered-depositor EarnShare boost configuration for one vault.'))
+
+  /** Complete rewards configuration for one verified Earn vault. */
+  export const Config = z
+    .strictObject({
+      boostRewards: z
+        .optional(BoostRewards)
+        .check(z.describe('Optional registered-depositor EarnShare boost configuration.')),
+      targetYield: z
+        .optional(TargetYield)
+        .check(z.describe('Optional target-yield funding configuration.')),
+    })
+    .check(
+      z.refine((config) => Boolean(config.boostRewards || config.targetYield), {
+        error: 'targetYield or boostRewards is required',
+      }),
+      z.refine(
+        (config) =>
+          !config.targetYield ||
+          !config.boostRewards ||
+          config.targetYield.intervalSeconds === config.boostRewards.intervalSeconds,
+        { error: 'targetYield and boostRewards must use one intervalSeconds value' },
+      ),
+      z.refine(
+        (config) =>
+          !config.targetYield ||
+          !config.boostRewards ||
+          Math.abs(config.targetYield.startTimestamp - config.boostRewards.startTimestamp) %
+            config.targetYield.intervalSeconds ===
+            0,
+        { error: 'targetYield and boostRewards schedules must share one interval grid' },
+      ),
+      z.refine(
+        (config) =>
+          !config.targetYield ||
+          (config.targetYield.endTimestamp - config.targetYield.startTimestamp >=
+            config.targetYield.intervalSeconds &&
+            config.targetYield.funding.filter((leg) => 'remainder' in leg).length === 1 &&
+            config.targetYield.funding.every(
+              (leg, index) =>
+                !('remainder' in leg) || index === config.targetYield!.funding.length - 1,
+            ) &&
+            config.targetYield.funding.every((leg, index, funding) => {
+              if ('remainder' in leg || index === 0) return true
+              const previous = funding[index - 1]!
+              return (
+                'upToAnnualRate' in previous && leg.upToAnnualRate.bps > previous.upToAnnualRate.bps
+              )
+            }) &&
+            new Set(config.targetYield.funding.map((leg) => leg.wallet)).size ===
+              config.targetYield.funding.length),
+        { error: 'targetYield schedule or funding waterfall is invalid' },
+      ),
+      z.refine(
+        (config) =>
+          !config.boostRewards ||
+          (config.boostRewards.endTimestamp - config.boostRewards.startTimestamp >=
+            config.boostRewards.intervalSeconds &&
+            BigInt(config.boostRewards.perUserPrincipalCapAssets) > 0n &&
+            BigInt(config.boostRewards.perUserPrincipalCapAssets) <=
+              BigInt(config.boostRewards.totalPrincipalCapAssets) &&
+            new Set(config.boostRewards.excludedAddresses).size ===
+              config.boostRewards.excludedAddresses.length),
+        { error: 'boostRewards schedule or principal caps are invalid' },
+      ),
+      z.refine(
+        (config) => {
+          const boost = config.boostRewards
+          const payout = boost?.payoutSchedule
+          return (
+            !boost ||
+            !payout ||
+            (payout.intervalSeconds > boost.intervalSeconds &&
+              payout.startTimestamp > boost.startTimestamp &&
+              payout.startTimestamp <= boost.endTimestamp)
+          )
+        },
+        { error: 'boostRewards payoutSchedule must be slower than its accounting interval' },
+      ),
+      z.describe('Complete reward configuration for one verified Earn vault.'),
+    )
+}
+
+/** Returns the single accounting interval shared by the configured capabilities. */
+export function intervalSeconds(config: Config): number {
+  return config.targetYield?.intervalSeconds ?? config.boostRewards!.intervalSeconds
+}
+
+/** Returns the final complete accounting boundary, excluding a trailing partial interval. */
+export function finalBoundary(config: Config): number {
+  return Math.max(
+    ...[config.targetYield, config.boostRewards]
+      .filter((schedule): schedule is NonNullable<typeof schedule> => schedule !== undefined)
+      .map(
+        (schedule) =>
+          schedule.startTimestamp +
+          Math.floor((schedule.endTimestamp - schedule.startTimestamp) / schedule.intervalSeconds) *
+            schedule.intervalSeconds,
+      ),
+  )
+}
+
+/** Returns whether a completed accounting range overlaps one schedule's complete intervals. */
+export function overlapsCompleteIntervals(
+  schedule: NonNullable<Config['boostRewards'] | Config['targetYield']>,
+  options: overlapsCompleteIntervals.Options,
+): boolean {
+  const final =
+    schedule.startTimestamp +
+    Math.floor((schedule.endTimestamp - schedule.startTimestamp) / schedule.intervalSeconds) *
+      schedule.intervalSeconds
+  return options.endsAt > schedule.startTimestamp && options.startsAfter < final
+}
+
+export declare namespace overlapsCompleteIntervals {
+  /** Completed accounting range tested against one reward schedule. */
+  type Options = {
+    /** Inclusive closing accounting boundary. */
+    endsAt: number
+    /** Exclusive opening accounting boundary. */
+    startsAfter: number
+  }
+}
+
+/** Returns whether one completed run should automatically push accumulated boost rewards. */
+export function shouldPushPayout(
+  boost: NonNullable<Config['boostRewards']>,
+  options: shouldPushPayout.Options,
+): boolean {
+  const payout = boost.payoutSchedule
+  if (!payout) return true
+  const final = finalBoundary({ boostRewards: boost })
+  if (options.startsAfter < final && options.endsAt >= final) return true
+  // Later campaign runs retry recipients whose forced final transfer was temporarily unavailable.
+  if (options.startsAfter >= final) return true
+  if (options.endsAt < payout.startTimestamp) return false
+  const previous =
+    options.startsAfter < payout.startTimestamp
+      ? -1
+      : Math.floor((options.startsAfter - payout.startTimestamp) / payout.intervalSeconds)
+  const current = Math.floor((options.endsAt - payout.startTimestamp) / payout.intervalSeconds)
+  return current > previous
+}
+
+export declare namespace shouldPushPayout {
+  /** Completed accounting range considered for an automatic payout. */
+  type Options = {
+    /** Inclusive closing accounting boundary. */
+    endsAt: number
+    /** Exclusive opening accounting boundary. */
+    startsAfter: number
+  }
+}
+
+/** Converts base assets into EarnShare at the fee-inclusive vault NAV, rounding down. */
+export function assetsToEarnShares(options: {
+  assets: bigint
+  totalAssets: bigint
+  totalEarnShares: bigint
+}): bigint {
+  if (options.assets < 0n) throw new Error('assets must be nonnegative')
+  requirePositiveVaultQuote(options)
+  return (options.assets * options.totalEarnShares) / options.totalAssets
+}
+
+/** Converts EarnShare into the assets needed at the fee-inclusive vault NAV, rounding up. */
+export function earnSharesToAssets(options: {
+  earnShares: bigint
+  totalAssets: bigint
+  totalEarnShares: bigint
+}): bigint {
+  if (options.earnShares < 0n) throw new Error('EarnShare must be nonnegative')
+  requirePositiveVaultQuote(options)
+  if (options.earnShares === 0n) return 0n
+  return (
+    (options.earnShares * options.totalAssets + options.totalEarnShares - 1n) /
+    options.totalEarnShares
+  )
+}
+
+/** Returns the inventory mint needed to fund a missing liability without coarse conversion loss. */
+export function settlementFundingEarnShares(missingEarnShares: bigint): bigint {
+  if (missingEarnShares < 0n) throw new Error('missing EarnShare must be nonnegative')
+  if (missingEarnShares === 0n) return 0n
+  return missingEarnShares < minimumSettlementFundingEarnShares
+    ? minimumSettlementFundingEarnShares
+    : missingEarnShares
+}
+
+function requirePositiveVaultQuote(options: { totalAssets: bigint; totalEarnShares: bigint }) {
+  if (options.totalAssets <= 0n || options.totalEarnShares <= 0n)
+    throw new Error('vault quote requires positive assets and fee-inclusive EarnShare supply')
+}
+
+/** Removes explicit contributions from one interval's measured exchange-rate growth. */
+export function organicGrowth(options: organicGrowth.Options): bigint {
+  const change = organicChange(options)
+  return change > 0n ? change : 0n
+}
+
+/** Removes explicit contributions from signed exchange-rate changes, retaining losses for interval aggregation. */
+export function organicChange(options: organicChange.Options): bigint {
+  if (options.openingAssets === 0n && options.openingEarnShareSupply === 0n) return 0n
+  if (
+    options.openingAssets <= 0n ||
+    options.openingEarnShareSupply <= 0n ||
+    options.openingValuePerEarnShare <= 0n
+  )
+    throw new Error('opening target-yield state must be positive')
+  const gross =
+    (options.openingAssets *
+      (options.closingValuePerEarnShare - options.openingValuePerEarnShare)) /
+    options.openingValuePerEarnShare
+  const contributed = options.contributions.reduce((sum, contribution) => {
+    if (contribution.earnShareSupply <= 0n)
+      throw new Error('contribution EarnShare supply must be positive')
+    return (
+      sum + (contribution.assets * options.openingEarnShareSupply) / contribution.earnShareSupply
+    )
+  }, 0n)
+  return gross - contributed
+}
+
+export declare namespace organicChange {
+  /** Exchange-rate values and contributions whose signed change is measured. */
+  type Options = organicGrowth.Options
+}
+
+export declare namespace organicGrowth {
+  /** One contribution normalized against its post-contribution holder supply. */
+  type Contribution = {
+    /** Contributed base-asset units. */
+    assets: bigint
+    /** Fee-inclusive EarnShare supply after the contribution. */
+    earnShareSupply: bigint
+  }
+
+  /** Target-yield interval values. */
+  type Options = {
+    /** Closing base assets per fixed EarnShare quote. */
+    closingValuePerEarnShare: bigint
+    /** Explicit contributions included in the closing value. */
+    contributions: readonly Contribution[]
+    /** Opening active base assets. */
+    openingAssets: bigint
+    /** Fee-inclusive opening EarnShare supply used to normalize mid-interval contributions. */
+    openingEarnShareSupply: bigint
+    /** Opening base assets per fixed EarnShare quote. */
+    openingValuePerEarnShare: bigint
+  }
+}
+
+/** Allocates an interval's target shortfall using principal held between EarnShare supply changes. */
+export function targetFunding(options: targetFunding.Options): targetFunding.Result {
+  // Boundary blocks can change NAV without adding elapsed principal exposure.
+  const change = options.periods.reduce((sum, period) => sum + organicChange(period), 0n)
+  const growthAssets = change > 0n ? change : 0n
+  const principalAssetSeconds = options.periods.reduce((sum, period) => {
+    if (!Number.isSafeInteger(period.elapsedSeconds) || period.elapsedSeconds < 0)
+      throw new Error('target-yield period duration must be a nonnegative integer')
+    return sum + period.openingAssets * BigInt(period.elapsedSeconds)
+  }, 0n)
+  let funded = 0n
+  const remainders: bigint[] = []
+  const assets = options.funding.map((leg, index) => {
+    const annualRateBps =
+      'remainder' in leg
+        ? options.annualRateBps
+        : Math.min(options.annualRateBps, leg.upToAnnualRate.bps)
+    // Asset-seconds preserve sub-unit principal exposure without rounding an average balance.
+    const accrued = accrue({
+      annualRateBps,
+      elapsedSeconds: 1,
+      principalAssets: principalAssetSeconds,
+      remainder: options.remainders[index] ?? 0n,
+    })
+    remainders.push(accrued.remainder)
+    const amount =
+      accrued.amount > growthAssets + funded ? accrued.amount - growthAssets - funded : 0n
+    funded += amount
+    return amount
+  })
+  return { assets, remainders }
+}
+
+export declare namespace targetFunding {
+  /** One period with unchanged EarnShare supply. */
+  type Period = organicGrowth.Options & {
+    /** Seconds for which the opening principal remained active. */
+    elapsedSeconds: number
+  }
+
+  /** Target funding calculation for one complete accounting interval. */
+  type Options = {
+    /** Resolved target annual rate in basis points. */
+    annualRateBps: number
+    /** Ordered funding waterfall. */
+    funding: readonly NonNullable<Config['targetYield']>['funding'][number][]
+    /** Historical periods covering the complete interval. */
+    periods: readonly Period[]
+    /** Exact accrual remainders carried from the preceding interval. */
+    remainders: readonly bigint[]
+  }
+
+  /** Exact assets and accrual remainders for each funding leg. */
+  type Result = {
+    /** Assets requested from each funding wallet. */
+    assets: bigint[]
+    /** Accrual remainders retained for the next interval. */
+    remainders: bigint[]
+  }
+}
+
+/** Annualizes contribution-adjusted asset growth as a simple ACT/365 rate. */
+export function annualRateBps(options: annualRateBps.Options): number {
+  if (!Number.isSafeInteger(options.elapsedSeconds) || options.elapsedSeconds <= 0)
+    throw new Error('elapsed seconds must be positive')
+  if (options.growthAssets < 0n) throw new Error('growth assets must be nonnegative')
+  if (options.principalAssets < 0n) throw new Error('principal assets must be nonnegative')
+  if (options.principalAssets === 0n) return 0
+  const rate =
+    (options.growthAssets * 10_000n * 365n * 24n * 60n * 60n) /
+    (options.principalAssets * BigInt(options.elapsedSeconds))
+  if (rate > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('annual rate exceeds safe range')
+  return Number(rate)
+}
+
+export declare namespace annualRateBps {
+  /** Inputs for annualizing exact interval growth. */
+  type Options = {
+    /** Closed interval length in seconds. */
+    elapsedSeconds: number
+    /** Contribution-adjusted growth in base-asset units. */
+    growthAssets: bigint
+    /** Opening base-asset principal. */
+    principalAssets: bigint
+  }
+}
+
+/** Resolves the effective base and incremental boost rates for one interval. */
+export function rewardRates(options: rewardRates.Options): rewardRates.Result {
+  for (const rate of [
+    options.boostTargetRateBps,
+    options.organicRateBps,
+    options.targetRateBps ?? 0,
+  ])
+    if (!Number.isSafeInteger(rate) || rate < 0) throw new Error('reward rate is invalid')
+  const baseRateBps = Math.max(options.organicRateBps, options.targetRateBps ?? 0)
+  return {
+    baseRateBps,
+    boostRateBps: Math.max(options.boostTargetRateBps - baseRateBps, 0),
+  }
+}
+
+export declare namespace rewardRates {
+  /** Rate targets and observed growth for one closed interval. */
+  type Options = {
+    /** Total annual rate targeted for qualified depositors. */
+    boostTargetRateBps: number
+    /** Contribution-adjusted annual rate observed during the interval. */
+    organicRateBps: number
+    /** Active target-yield floor. */
+    targetRateBps?: number | undefined
+  }
+
+  /** Effective base and incremental boost rates for one closed interval. */
+  type Result = {
+    /** Higher of organic growth and the active target-yield floor. */
+    baseRateBps: number
+    /** Incremental depositor rate needed to reach the total target. */
+    boostRateBps: number
+  }
+}
+
+/** Complete rewards configuration for one verified Earn vault. */
+export type Config = z.output<typeof schema.Config>
+
+/** Ordered TIDX event cursor for one campaign projection. */
+export type EventCursor = {
+  /** Tempo block number. */
+  blockNumber: number
+  /** Log index within the transaction receipt. */
+  logIndex: number
+  /** Transaction index within the block. */
+  transactionIndex: number
+}
+
+/** One surviving public deposit lot used for boost qualification. */
+export type DepositLot = {
+  /** Principal allocated against campaign caps. */
+  allocatedPrincipalAssets: string
+  /** Original deposited base assets. */
+  depositedAssets: string
+  /** EarnShare minted by the deposit. */
+  depositedEarnShares: string
+  /** Event order used for deterministic qualification. */
+  event: EventCursor
+  /** Qualified EarnShare not consumed by an outgoing transfer or burn. */
+  remainingEarnShares: string
+}
+
+/** Calculation and delivery state retained while one run is active. */
+export type RunEvidence = {
+  /** Target annual rate applied to this run's intervals. */
+  appliedTargetRateBps?: number | undefined
+  /** Incremental boost annual rate selected for the run. */
+  boostRateBps?: number | undefined
+  /** Complete closing recipient projection used to resume payout after a crash. */
+  closingAccounts: readonly AccountSnapshot[]
+  /** Newly credited recipients retaining an unpaid entitlement after delivery. */
+  deferredRecipients?: number | undefined
+  /** Stable registration high-water mark consumed by the run. */
+  eligibilityCheckpoint?: string | undefined
+  /** Exact eligibility snapshot identity used by resumable calculation. */
+  eligibilityVersion?: Hex | undefined
+  /** Exact effective exclusion set identity used by resumable calculation. */
+  exclusionVersion?: Hex | undefined
+  /** Final TIDX event applied to the closing projection. */
+  eventCursor?: EventCursor | undefined
+  /** Rate sources using a bounded prior observation. */
+  staleRates?: readonly ('organic' | 'target')[] | undefined
+  /** Contribution-adjusted annual rate observed in the run's latest boost interval. */
+  organicRateBps?: number | undefined
+  /** Closing boundary of the interval supplying the organic rate. */
+  organicRateObservedAt?: string | undefined
+  /** Newly credited recipients whose cumulative entitlement is fully paid after delivery. */
+  paidRecipients?: number | undefined
+  /** Recipients receiving an EarnShare transfer during this run. */
+  payoutPaidRecipients?: number | undefined
+  /** Frozen automatic-payout recipients reused across delivery retries. */
+  payoutRecipients?: readonly Address[] | undefined
+  /** Recipients retaining an unpaid cumulative entitlement after automatic delivery. */
+  pendingRecipients?: number | undefined
+  /** Latest target annual rate observation retained for source fallback. */
+  targetRateBps?: number | undefined
+  /** Exact per-funder target-yield assets committed before signing. */
+  targetFundingAssets?: readonly string[] | undefined
+  /** Per-waterfall-threshold division remainders carried into the next run. */
+  targetFundingRemainders?: readonly string[] | undefined
+  /** Principal accounting method used for the committed funding amounts. */
+  targetPrincipalMethod?: 'time-weighted:v1' | undefined
+  /** When the selected external target rate was observed. */
+  targetRateObservedAt?: string | undefined
+  /** Per-interval calculation records in chronological order. */
+  intervals: readonly {
+    /** Fee-inclusive opening assets per EarnShare, scaled by 1e18. */
+    assetPerEarnShareWad: string
+    /** Per-recipient base-asset rewards for this interval. */
+    assetRewards: Readonly<Record<string, string>>
+    /** Final TIDX block included in the interval. */
+    blockNumber: number
+    /** Incremental boost annual rate applied to this interval. */
+    boostRateBps?: number | undefined
+    /** Exclusive interval end timestamp. */
+    endsAt: number
+    /** Contribution-adjusted annual rate observed in this interval. */
+    organicRateBps?: number | undefined
+    /** Inclusive interval start timestamp. */
+    startsAt: number
+  }[]
+  /** Explicit completed-state discriminator; absent on legacy completed evidence. */
+  kind?: 'complete' | undefined
+  /** Whether this run prepared and confirmed a new cumulative root. */
+  publishedRoot?: boolean | undefined
+  /** Base-asset units converted into the newly published entitlement. */
+  settledRewardAssets?: string | undefined
+  /** Recipients receiving a positive allocation in the new root. */
+  settlementRecipientAddresses?: readonly Address[] | undefined
+  /** Recipients receiving a positive allocation in the new root. */
+  settlementRecipients?: number | undefined
+  /** Closing account-state checksum. */
+  stateChecksum: Hex
+}
+
+/** Returns a stable identity for the complete eligibility snapshot. */
+export function eligibilityVersion(entries: readonly eligibilityVersion.Entry[]): Hex {
+  return keccak256(
+    stringToBytes(
+      JSON.stringify(
+        entries.map((entry) => [
+          entry.walletAddress.toLowerCase(),
+          entry.registrationOrder,
+          entry.latestRegisteredAt,
+        ]),
+      ),
+    ),
+  )
+}
+
+export declare namespace eligibilityVersion {
+  /** Eligibility fields that can change projection membership or replay. */
+  type Entry = {
+    /** Latest registration timestamp. */
+    latestRegisteredAt: string
+    /** Stable registration order. */
+    registrationOrder: string
+    /** Registered reward recipient. */
+    walletAddress: Address
+  }
+}
+
+/** Returns a stable identity for the effective reward exclusion set. */
+export function exclusionVersion(addresses: readonly Address[]): Hex {
+  return keccak256(
+    stringToBytes(
+      JSON.stringify([...new Set(addresses.map((address) => address.toLowerCase()))].sort()),
+    ),
+  )
+}
+
+/** Durable pagewise calculation state retained until complete evidence replaces it. */
+export type RunCheckpointEvidence = {
+  /** Final TIDX event included in this checkpoint. */
+  cursor?: EventCursor | undefined
+  /** Stored-evidence discriminator. */
+  kind: 'checkpoint'
+  /** Completed calculation progress needed to resume the run. */
+  progress: Partial<RunEvidence>
+  /** Serializable projection reducer state. */
+  projection: {
+    /** Recipient whose registration-ordered deposit page was last applied. */
+    allocationRecipient?: Address | undefined
+    /** Account projections after the checkpointed page. */
+    accounts: readonly AccountSnapshot[]
+    /** Last accrued timestamp keyed by normalized recipient. */
+    accruedThrough?: Readonly<Record<string, number>> | undefined
+    /** Remaining FIFO-consumed shares while allocating surviving deposits. */
+    consumedEarnShares?: Readonly<Record<string, string>> | undefined
+    /** Gross historical deposit shares keyed by normalized recipient. */
+    depositedEarnShares?: Readonly<Record<string, string>> | undefined
+    /** Historical reconciliation pass. */
+    pass?: 'allocation' | 'survival' | undefined
+    /** Final canonical event applied by the survival pass. */
+    replayedThrough?: EventCursor | undefined
+    /** Weighted EarnShare seconds keyed by normalized recipient. */
+    weightedEarnShareSeconds?: Readonly<Record<string, string>> | undefined
+  }
+  /** Calculation reducer that produced this checkpoint. */
+  stage: 'calculate' | 'reconcile'
+}
+
+/** Completed or resumable evidence stored on a reward run. */
+export type StoredRunEvidence = RunCheckpointEvidence | RunEvidence
+
+/** Narrows stored run evidence to resumable calculation state. */
+export function isRunCheckpointEvidence(
+  evidence: StoredRunEvidence | null | undefined,
+): evidence is RunCheckpointEvidence {
+  return evidence?.kind === 'checkpoint'
+}
+
+/** Restores funding amounts only when their saved principal accounting is safe to submit. */
+export function targetFundingAssets(evidence: RunEvidence): bigint[] {
+  const assets = (evidence.targetFundingAssets ?? []).map(BigInt)
+  // Legacy evidence can contain inflated spot-principal amounts, including on a signed retry.
+  if (assets.some((amount) => amount > 0n) && evidence.targetPrincipalMethod !== 'time-weighted:v1')
+    throw new Error('Stored target-yield funding requires principal accounting review.')
+  return assets
+}
+
+/** Removes active recipient calculation and payout state after a run is durably delivered. */
+export function compactEvidence(evidence: RunEvidence): RunEvidence {
+  const compacted: RunEvidence = {
+    ...evidence,
+    closingAccounts: [],
+    intervals: evidence.intervals.map((interval) => ({ ...interval, assetRewards: {} })),
+    payoutRecipients: [],
+    settlementRecipientAddresses: [],
+  }
+  return compacted
+}
+
+/** Serializable reward-account projection retained by an in-flight run. */
+export type AccountSnapshot = {
+  /** Arithmetic remainder carried across intervals. */
+  accrualRemainder: string
+  /** Principal allocated against campaign caps. */
+  allocatedPrincipalAssets: string
+  /** Cumulative EarnShare entitlement. */
+  cumulativeEntitlement: string
+  /** Cumulative EarnShare already paid. */
+  cumulativePaid: string
+  /** Current transfer deferral. */
+  deferral: string | null
+  /** Eligibility registration version consumed by this projection. */
+  eligibilityRegisteredAt: string | null
+  /** Surviving qualified deposits. */
+  lots: readonly DepositLot[]
+  /** Base-asset reward awaiting settlement. */
+  pendingRewardAssets: string
+  /** Current attributable public EarnShare. */
+  publicEarnShares: string
+  /** Current qualified EarnShare. */
+  qualifiedEarnShares: string
+  /** Registered recipient. */
+  recipient: Address
+  /** Monotonic registration order. */
+  registrationOrder: string
+}
+
+/** Typed signer intent persisted before transaction construction. */
+export type TransactionIntent = {
+  /** Deterministic content-addressed intent id. */
+  id: Hex
+  /** Operation accepted by the reward signer. */
+  operation: 'deploy' | 'targetYield' | 'settle' | 'publish' | 'push'
+  /** Operation-specific data validated by the signer. */
+  payload: Readonly<Record<string, unknown>>
+}
+
+/** Canonical receipt evidence retained after confirmation. */
+export type TransactionReceipt = {
+  /** Canonical receipt block hash. */
+  blockHash: Hex
+  /** Receipt block number. */
+  blockNumber: string
+  /** Gas consumed by the transaction. */
+  gasUsed: string
+  /** Receipt status. */
+  status: 'success' | 'reverted'
+  /** Transaction hash. */
+  transactionHash: Hex
+}
+
+/** One cumulative recipient entitlement. */
+export type Entitlement = {
+  /** EarnShare owed cumulatively. */
+  cumulativeAmount: string
+  /** Committed recipient. */
+  recipient: Address
+}
+
+/** One proof-bearing statement entry. */
+export type StatementEntry = Entitlement & {
+  /** Domain-separated leaf hash. */
+  leaf: Hex
+}
+
+/** One cumulative v2 Merkle statement. */
+export type Statement = {
+  /** Zero-padded EarnVault campaign id. */
+  campaignId: Hex
+  /** Tempo chain containing the distributor. */
+  chainId: number
+  /** EarnShare distributor address. */
+  distributor: Address
+  /** Sorted cumulative entries. */
+  entries: readonly StatementEntry[]
+  /** Merkle root. */
+  root: Hex
+  /** Statement schema version. */
+  schemaVersion: 2
+  /** Content hash of the statement payload. */
+  statementHash: Hex
+  /** Sum of all cumulative entitlements. */
+  totalEntitlement: string
+}
+
+/** One permissionless cumulative multiproof payout batch. */
+export type PayoutBatch = {
+  /** Cumulative amounts matching `recipients`. */
+  cumulativeAmounts: readonly string[]
+  /** StandardMerkleTree multiproof. */
+  multiproof: readonly Hex[]
+  /** OpenZeppelin multiproof queue flags. */
+  proofFlags: readonly boolean[]
+  /** Committed recipients in multiproof leaf order. */
+  recipients: readonly Address[]
+}
+
+/** Returns the next interval boundary relative to a schedule origin. */
+export function nextBoundary(options: nextBoundary.Options): number {
+  if (!Number.isSafeInteger(options.intervalSeconds) || options.intervalSeconds <= 0)
+    throw new Error('intervalSeconds is invalid')
+  if (!Number.isSafeInteger(options.origin) || options.origin < 0)
+    throw new Error('origin is invalid')
+  if (!Number.isSafeInteger(options.timestamp) || options.timestamp < options.origin)
+    throw new Error('timestamp is invalid')
+  return (
+    options.origin +
+    (Math.floor((options.timestamp - options.origin) / options.intervalSeconds) + 1) *
+      options.intervalSeconds
+  )
+}
+
+export declare namespace nextBoundary {
+  /** Inputs for locating a schedule-relative interval boundary. */
+  type Options = {
+    /** Accounting interval length in seconds. */
+    intervalSeconds: number
+    /** Unix timestamp anchoring the schedule's interval grid. */
+    origin: number
+    /** Unix timestamp after which the boundary must fall. */
+    timestamp: number
+  }
+}
+
+/** Calculates simple ACT/365 reward assets and the carried division remainder. */
+export function accrue(options: accrue.Options): accrue.Result {
+  const denominator = 10_000n * 365n * 24n * 60n * 60n
+  const numerator =
+    options.principalAssets * BigInt(options.annualRateBps) * BigInt(options.elapsedSeconds) +
+    options.remainder
+  return { amount: numerator / denominator, remainder: numerator % denominator }
+}
+
+export declare namespace accrue {
+  /** Inputs for one simple annual reward calculation. */
+  type Options = {
+    /** Annual reward rate in basis points. */
+    annualRateBps: number
+    /** Seconds covered by the calculation. */
+    elapsedSeconds: number
+    /** Base-asset principal earning rewards. */
+    principalAssets: bigint
+    /** Division remainder carried from earlier intervals. */
+    remainder: bigint
+  }
+
+  /** Exact integer result and its remainder. */
+  type Result = {
+    /** Whole base-asset units earned. */
+    amount: bigint
+    /** Numerator remainder carried into the next interval. */
+    remainder: bigint
+  }
+}
+
+/** Allocates every minted EarnShare unit by deterministic largest remainder. */
+export function allocate(options: allocate.Options): ReadonlyMap<Address, bigint> {
+  const rewards = [...options.rewards]
+    .filter((reward) => reward.assets > 0n)
+    .sort((left, right) =>
+      left.recipient.toLowerCase().localeCompare(right.recipient.toLowerCase()),
+    )
+  const total = rewards.reduce((sum, reward) => sum + reward.assets, 0n)
+  if (total === 0n) {
+    if (options.earnShares !== 0n) throw new Error('cannot allocate shares without rewards')
+    return new Map()
+  }
+  const rows = rewards.map((reward) => {
+    const numerator = reward.assets * options.earnShares
+    return { amount: numerator / total, recipient: reward.recipient, remainder: numerator % total }
+  })
+  let remaining = options.earnShares - rows.reduce((sum, row) => sum + row.amount, 0n)
+  rows.sort(
+    (left, right) =>
+      Number(right.remainder > left.remainder) - Number(right.remainder < left.remainder) ||
+      left.recipient.toLowerCase().localeCompare(right.recipient.toLowerCase()),
+  )
+  for (const row of rows) {
+    if (remaining === 0n) break
+    row.amount += 1n
+    remaining -= 1n
+  }
+  return new Map(rows.map((row) => [row.recipient, row.amount]))
+}
+
+export declare namespace allocate {
+  /** Inputs for exact minted-share allocation. */
+  type Options = {
+    /** Exact EarnShare units minted. */
+    earnShares: bigint
+    /** Per-recipient base-asset rewards. */
+    rewards: readonly { assets: bigint; recipient: Address }[]
+  }
+}
+
+/** Whether an unpaid EarnShare balance meets its base-asset payout floor. */
+export function meetsPayoutMinimum(options: meetsPayoutMinimum.Options): boolean {
+  const unpaid = options.cumulativeEntitlement - options.cumulativePaid
+  if (unpaid <= 0n) return false
+  if (options.minimumAssets < 0n) throw new Error('minimum assets must be nonnegative')
+  if (options.totalAssets < 0n || options.totalEarnShares <= 0n)
+    throw new Error('payout valuation requires nonnegative assets and positive EarnShare supply')
+  return unpaid * options.totalAssets >= options.minimumAssets * options.totalEarnShares
+}
+
+export declare namespace meetsPayoutMinimum {
+  /** Cumulative entitlement and current vault-value inputs. */
+  type Options = {
+    /** Recipient's cumulative EarnShare entitlement. */
+    cumulativeEntitlement: bigint
+    /** Recipient's cumulative paid EarnShare amount. */
+    cumulativePaid: bigint
+    /** Minimum base-asset value required for automatic payout. */
+    minimumAssets: bigint
+    /** Current fee-inclusive vault assets. */
+    totalAssets: bigint
+    /** Current fee-inclusive EarnShare supply. */
+    totalEarnShares: bigint
+  }
+}
+
+/** Builds an OpenZeppelin StandardMerkleTree-compatible cumulative statement. */
+export function buildStatement(options: buildStatement.Options): Statement {
+  if (options.entitlements.length === 0) throw new Error('statement requires an entitlement')
+  const entries = options.entitlements
+    .map((entry) => ({
+      cumulativeAmount: BigInt(entry.cumulativeAmount).toString(),
+      leaf: '' as Hex,
+      recipient: getAddress(entry.recipient),
+    }))
+    .sort((left, right) =>
+      left.recipient.toLowerCase().localeCompare(right.recipient.toLowerCase()),
+    )
+  let totalEntitlement = 0n
+  for (const [index, entry] of entries.entries()) {
+    const cumulativeAmount = BigInt(entry.cumulativeAmount)
+    if (cumulativeAmount <= 0n || cumulativeAmount > maximumUint256)
+      throw new Error(`invalid entitlement for ${entry.recipient}`)
+    if (index > 0 && entry.recipient === entries[index - 1]!.recipient)
+      throw new Error(`duplicate recipient ${entry.recipient}`)
+    totalEntitlement += cumulativeAmount
+    entry.leaf = rewardLeaf({ ...options, cumulativeAmount, recipient: entry.recipient })
+  }
+  if (totalEntitlement > maximumUint256) throw new Error('total entitlement exceeds uint256')
+  const tree = makeTree(entries.map((entry) => entry.leaf))
+  const payload = {
+    campaignId: options.campaignId,
+    chainId: options.chainId,
+    distributor: getAddress(options.distributor),
+    entries,
+    root: tree.nodes[0]!,
+    schemaVersion: 2 as const,
+    totalEntitlement: totalEntitlement.toString(),
+  }
+  return { ...payload, statementHash: keccak256(stringToBytes(JSON.stringify(payload))) }
+}
+
+export declare namespace buildStatement {
+  /** Domain and entitlement inputs for one statement. */
+  type Options = {
+    /** Zero-padded EarnVault campaign id. */
+    campaignId: Hex
+    /** Tempo chain containing the distributor. */
+    chainId: number
+    /** EarnShare distributor address. */
+    distributor: Address
+    /** Cumulative recipient entitlements. */
+    entitlements: readonly Entitlement[]
+  }
+}
+
+/** Splits a cumulative statement into contiguous multiproof payout batches. */
+export function buildPayoutBatches(
+  statement: Statement,
+  options: buildPayoutBatches.Options,
+): readonly PayoutBatch[] {
+  if (!Number.isSafeInteger(options.maximumSize) || options.maximumSize <= 0)
+    throw new Error('maximumSize must be a positive integer')
+  const entries = statement.entries.flatMap((entry, index) =>
+    !options.recipients || options.recipients.has(entry.recipient.toLowerCase())
+      ? [{ entry, index }]
+      : [],
+  )
+  const leaves = statement.entries.map((entry) => entry.leaf)
+  const tree = makeTree(leaves)
+  const byPosition = new Map(tree.positions.map((position, index) => [position, index]))
+  const result: PayoutBatch[] = []
+  for (let offset = 0; offset < entries.length; offset += options.maximumSize) {
+    const selected = entries.slice(offset, offset + options.maximumSize)
+    const positions = selected
+      .map(({ index }) => tree.positions[index]!)
+      .sort((left, right) => right - left)
+    const original = [...positions]
+    const stack = [...positions]
+    const multiproof: Hex[] = []
+    const proofFlags: boolean[] = []
+    while (stack.length > 0 && stack[0]! > 0) {
+      const current = stack.shift()!
+      const sibling = current % 2 === 0 ? current - 1 : current + 1
+      const parent = Math.floor((current - 1) / 2)
+      if (sibling === stack[0]) {
+        proofFlags.push(true)
+        stack.shift()
+      } else {
+        proofFlags.push(false)
+        multiproof.push(tree.nodes[sibling]!)
+      }
+      stack.push(parent)
+    }
+    const ordered = original.map((position) => statement.entries[byPosition.get(position)!]!)
+    result.push({
+      cumulativeAmounts: ordered.map((entry) => entry.cumulativeAmount),
+      multiproof,
+      proofFlags,
+      recipients: ordered.map((entry) => entry.recipient),
+    })
+  }
+  return result
+}
+
+/** Rebuilds one individual recovery proof from the current cumulative statement. */
+export function buildProof(statement: Statement, recipient: Address): readonly Hex[] | undefined {
+  const index = statement.entries.findIndex(
+    (entry) => entry.recipient.toLowerCase() === recipient.toLowerCase(),
+  )
+  if (index < 0) return undefined
+  return treeProof(makeTree(statement.entries.map((entry) => entry.leaf)), index)
+}
+
+export declare namespace buildPayoutBatches {
+  /** Runtime batch constraints. */
+  type Options = {
+    /** Maximum recipients in one bounded payout call. */
+    maximumSize: number
+    /** Optional preflight-authorized recipient set. */
+    recipients?: ReadonlySet<string> | undefined
+  }
+}
+
+/** Computes the distributor's domain-separated standard leaf. */
+export function rewardLeaf(options: rewardLeaf.Options): Hex {
+  return keccak256(
+    keccak256(
+      encodeAbiParameters(leafParameters, [
+        BigInt(options.chainId),
+        getAddress(options.distributor),
+        options.campaignId,
+        getAddress(options.recipient),
+        options.cumulativeAmount,
+      ]),
+      'bytes',
+    ),
+  )
+}
+
+export declare namespace rewardLeaf {
+  /** Domain and recipient inputs for one leaf. */
+  type Options = {
+    /** Zero-padded EarnVault campaign id. */
+    campaignId: Hex
+    /** Tempo chain containing the distributor. */
+    chainId: number
+    /** Cumulative EarnShare amount. */
+    cumulativeAmount: bigint
+    /** EarnShare distributor address. */
+    distributor: Address
+    /** Committed recipient. */
+    recipient: Address
+  }
+}
+
+type Tree = { nodes: Hex[]; positions: number[] }
+
+function makeTree(leaves: readonly Hex[]): Tree {
+  const sorted = leaves
+    .map((hash, index) => ({ hash, index }))
+    .sort((left, right) => left.hash.toLowerCase().localeCompare(right.hash.toLowerCase()))
+  const nodes = Array.from<Hex>({ length: 2 * leaves.length - 1 })
+  const positions = Array.from<number>({ length: leaves.length })
+  for (const [index, leaf] of sorted.entries()) {
+    const position = nodes.length - 1 - index
+    nodes[position] = leaf.hash
+    positions[leaf.index] = position
+  }
+  for (let index = nodes.length - 1 - leaves.length; index >= 0; index -= 1)
+    nodes[index] = nodeHash(nodes[2 * index + 1]!, nodes[2 * index + 2]!)
+  return { nodes, positions }
+}
+
+function nodeHash(left: Hex, right: Hex): Hex {
+  return keccak256(
+    concatHex(left.toLowerCase() < right.toLowerCase() ? [left, right] : [right, left]),
+  )
+}
+
+function treeProof(tree: Tree, leafIndex: number): Hex[] {
+  const result: Hex[] = []
+  let index = tree.positions[leafIndex]!
+  while (index > 0) {
+    const sibling = index % 2 === 0 ? index - 1 : index + 1
+    result.push(tree.nodes[sibling]!)
+    index = Math.floor((index - 1) / 2)
+  }
+  return result
+}