@xyo-network/xl1-protocol-sdk 1.17.7 → 1.18.0

package/src/primitives/chain/step/stepRewardTotal.ts

@@ -0,0 +1,45 @@
+import { assertEx, isDefined } from '@xylabs/sdk-js'
+import type {
+  AttoXL1, StepIdentity, XL1BlockRange, XL1RangeMultipliers,
+} from '@xyo-network/xl1-protocol'
+import {
+  asAttoXL1, asXL1BlockRange, isTransfer,
+  XYO_STEP_REWARD_ADDRESS,
+} from '@xyo-network/xl1-protocol'
+
+import { type ChainContextRead, withContextCacheResponse } from '../../../model/index.ts'
+import { netTransfersForPayloads } from '../../../payloads/index.ts'
+import { stepBlockRange, stepTransferIndex } from '../../step/index.ts'
+import { stepRewardBlock } from './stepRewardBlock.ts'
+
+function stepInRange(step: StepIdentity, range: XL1BlockRange): boolean {
+  const stepRange = stepBlockRange(step)
+  return ((stepRange[0] >= range[0]) && (stepRange[1] <= range[1]))
+}
+
+export async function stepRewardTotal(context: ChainContextRead, { block, step }: StepIdentity, multipliers: XL1RangeMultipliers): Promise<AttoXL1> {
+  const cacheKey = `${block}|${step}|${isDefined(multipliers)}`
+  return await withContextCacheResponse(context, 'stepRewardTotal', cacheKey, async () => {
+    const [blockBw, payloads] = await stepRewardBlock(context, { block, step })
+    assertEx(blockBw.block === block, () => `Block Mismatch: expected ${block}, got ${blockBw.block}`)
+    const [transferIndex] = stepTransferIndex(block, step)
+    const stepTransfer = assertEx(
+      payloads.find(p => isTransfer(p) && p.from === XYO_STEP_REWARD_ADDRESS),
+      () => `No step transfer found for step ${step} at block ${block} (${blockBw._hash})`,
+    )
+    const rewards = assertEx(
+      netTransfersForPayloads([stepTransfer])[XYO_STEP_REWARD_ADDRESS],
+      () => `No rewards found for step reward address ${XYO_STEP_REWARD_ADDRESS} at block ${block} (${blockBw._hash})`,
+    )
+    const sortedTransfers = (Object.entries(rewards)).toSorted(([,a], [,b]) => a > b ? -1 : a < b ? 1 : 0)
+    let result = asAttoXL1(sortedTransfers[transferIndex][1] * -1n)
+    for (const [rangeKey, [numerator, denominator]] of Object.entries(multipliers)) {
+      const rangeParts = rangeKey.split('|').map(Number)
+      const range: XL1BlockRange = asXL1BlockRange([rangeParts[0], rangeParts[1]], { name: 'stepRewardTotal' })
+      if (stepInRange({ block, step }, range)) {
+        result = asAttoXL1(result + result * numerator / denominator)
+      }
+    }
+    return result
+  })
+}

package/src/primitives/chain/step/stepsRewardTotal.ts

@@ -0,0 +1,34 @@
+import type {
+  AttoXL1, StepIdentity, XL1BlockRange,
+  XL1RangeMultipliers,
+} from '@xyo-network/xl1-protocol'
+import { asAttoXL1, asXL1BlockRange } from '@xyo-network/xl1-protocol'
+
+import { XL1_NETWORK_STAKING_GENESIS_PERIOD_END_XL1_BLOCK } from '../../../constants.ts'
+import type { ChainContextRead } from '../../../model/index.ts'
+import { blockRangeSteps } from '../../block/index.ts'
+import { stepRewardTotal } from './stepRewardTotal.ts'
+
+export async function stepsRewardTotalGenesisPeriod(context: ChainContextRead, multipliers: XL1RangeMultipliers, stepSizes?: number[]): Promise<AttoXL1> {
+  const range = asXL1BlockRange([0, XL1_NETWORK_STAKING_GENESIS_PERIOD_END_XL1_BLOCK], { name: 'stepsRewardTotalGenesisPeriod' })
+  return await stepsRewardTotalRange(context, range, stepSizes, multipliers)
+}
+
+export async function stepsRewardTotalRange(
+  context: ChainContextRead,
+  range: XL1BlockRange,
+  stepSizes: number[] = [3, 4, 5, 6],
+  multipliers: XL1RangeMultipliers,
+): Promise<AttoXL1> {
+  const steps = blockRangeSteps(range, stepSizes)
+  return await stepsRewardTotal(context, steps, multipliers)
+}
+
+export async function stepsRewardTotal(context: ChainContextRead, steps: StepIdentity[], multipliers: XL1RangeMultipliers): Promise<AttoXL1> {
+  let totalRewards = 0n
+  for (const step of steps) {
+    const stepTotal = await stepRewardTotal(context, step, multipliers)
+    totalRewards += stepTotal
+  }
+  return asAttoXL1(totalRewards)
+}

package/src/primitives/chain/time/externalBlockNumberFromXL1BlockNumber.ts

@@ -0,0 +1,31 @@
+import { assertEx, isArray } from '@xylabs/sdk-js'
+import type { BlockNumber, XL1BlockNumber } from '@xyo-network/xl1-protocol'
+import {
+  asBlockNumber, asTimePayload, isTimePayload,
+} from '@xyo-network/xl1-protocol'
+
+import { type BaseContext, withContextCacheResponse } from '../../../model/index.ts'
+import type { BlockViewer } from '../../../viewers/index.ts'
+
+const functionName = 'externalBlockNumberFromXL1BlockNumber' as const
+
+export async function externalBlockNumberFromXL1BlockNumber(
+  context: BaseContext,
+  blockViewer: BlockViewer,
+  xl1BlockNumber: XL1BlockNumber,
+  externalTimeName: 'ethereum' | 'epoch',
+  externalGenesisTime?: BlockNumber,
+  timeBudgetMs = 2000,
+): Promise<BlockNumber> {
+  const cacheKey = `${xl1BlockNumber}-${externalTimeName}-${externalGenesisTime ?? 'default'}`
+  return await withContextCacheResponse(context, functionName, cacheKey, async () => {
+    const [, payloads = []] = await blockViewer.blockByNumber(xl1BlockNumber) ?? []
+    assertEx(isArray(payloads))
+    const timePayload = asTimePayload(payloads.find(isTimePayload))
+    // the default here is the block number we know where the xl1 chain started running (first external staking - 1)
+    return asBlockNumber(
+      timePayload?.[externalTimeName] ?? externalGenesisTime ?? 23_372_716,
+      { name: functionName },
+    ) // default is xl1 mainnet genesis time
+  }, { timeBudgetMs })
+}

package/src/primitives/chain/time/externalBlockRangeFromStep.ts

@@ -0,0 +1,19 @@
+import type { BlockRange, StepIdentity } from '@xyo-network/xl1-protocol'
+
+import { toStepIdentityString } from '../../../block/index.ts'
+import { type BaseContext, withContextCacheResponse } from '../../../model/index.ts'
+import type { BlockViewer } from '../../../viewers/index.ts'
+import { stepBlockRange } from '../../step/index.ts'
+import { externalBlockRangeFromXL1BlockRange } from './externalBlockRangeFromXL1BlockRange.ts'
+
+export async function externalBlockRangeFromStep(
+  context: BaseContext,
+  blockViewer: BlockViewer,
+  stepIdentity: StepIdentity,
+): Promise<BlockRange> {
+  const cacheKey = toStepIdentityString(stepIdentity)
+  return await withContextCacheResponse(context, 'externalBlockRangeFromStep', cacheKey, async () => {
+    const xl1BlockRange = stepBlockRange(stepIdentity)
+    return await externalBlockRangeFromXL1BlockRange(context, blockViewer, xl1BlockRange)
+  }, { timeBudgetMs: 1000 })
+}

package/src/primitives/chain/time/externalBlockRangeFromXL1BlockRange.ts

@@ -0,0 +1,16 @@
+import type { BlockRange, XL1BlockRange } from '@xyo-network/xl1-protocol'
+
+import type { BaseContext } from '../../../model/index.ts'
+import type { BlockViewer } from '../../../viewers/index.ts'
+import { externalBlockNumberFromXL1BlockNumber } from './externalBlockNumberFromXL1BlockNumber.ts'
+
+export async function externalBlockRangeFromXL1BlockRange(
+  context: BaseContext,
+  blockViewer: BlockViewer,
+  xl1BlockRange: XL1BlockRange,
+  externalTimeName: 'ethereum' = 'ethereum',
+): Promise<BlockRange> {
+  const start = await externalBlockNumberFromXL1BlockNumber(context, blockViewer, xl1BlockRange[0], externalTimeName)
+  const end = await externalBlockNumberFromXL1BlockNumber(context, blockViewer, xl1BlockRange[1], externalTimeName)
+  return [start, end]
+}

package/src/primitives/chain/time/index.ts

@@ -0,0 +1,3 @@
+export * from './externalBlockNumberFromXL1BlockNumber.ts'
+export * from './externalBlockRangeFromStep.ts'
+export * from './externalBlockRangeFromXL1BlockRange.ts'

package/src/primitives/index.ts

@@ -1,6 +1,13 @@
+export * from './block/index.ts'
+export * from './chain/index.ts'
+export * from './mapToMapType.ts'
+export * from './payload/index.ts'
 export * from './readPayloadMapFromStore.ts'
 export * from './rewardFromBlockNumber.ts'
+export * from './rewards/index.ts'
+export * from './stake/index.ts'
 export * from './state/index.ts'
 export * from './step/index.ts'
 export * from './timeBudget.ts'
 export * from './transaction/index.ts'
+export * from './uncle/index.ts'

package/src/primitives/mapToMapType.ts

@@ -0,0 +1,35 @@
+import { isDefined } from '@xylabs/sdk-js'
+
+import type { SyncIterableMap } from '../map/index.ts'
+
+export function mapToMapType<K extends {}, V extends {}>(map: Map<K, V> | SyncIterableMap<K, V>): SyncIterableMap<K, V> {
+  return {
+    get: (key: K) => map.get(key),
+    has: (key: K) => map.has(key),
+    set: (key: K, value: V) => {
+      map.set(key, value)
+    },
+    setMany: (entries: [K, V][]) => {
+      for (const [key, value] of entries) {
+        map.set(key, value)
+      }
+    },
+    delete: (key: K) => map.delete(key),
+    clear: () => map.clear(),
+    getMany: (keys: K[]) => {
+      const result: V[] = []
+      for (const key of keys) {
+        const value = map.get(key)
+        if (isDefined(value)) {
+          result.push(value)
+        }
+      }
+      return result
+    },
+    [Symbol.iterator]: function* (): Iterator<[K, V]> {
+      for (const entry of map) {
+        yield entry
+      }
+    },
+  }
+}

package/src/primitives/payload/index.ts

@@ -0,0 +1 @@
+export * from './mergeTransfers.ts'

package/src/primitives/payload/mergeTransfers.ts

@@ -0,0 +1,15 @@
+import type { Address } from '@xylabs/sdk-js'
+import { hexToBigInt, toAddress } from '@xylabs/sdk-js'
+import type { Transfer } from '@xyo-network/xl1-protocol'
+
+export function mergeTransfers(transfers: Transfer[]): Record<Address, Record<Address, bigint>> {
+  const result: Record<Address, Record<Address, bigint>> = {}
+  for (const transfer of transfers) {
+    result[transfer.from] = result[transfer.from] ?? {}
+    for (const [to, value] of Object.entries(transfer.transfers)) {
+      const typedTo = toAddress(to)
+      result[transfer.from][typedTo] = (result[transfer.from][typedTo] ?? 0n) + (hexToBigInt(value))
+    }
+  }
+  return result
+}

package/src/primitives/readPayloadMapFromStore.ts

@@ -1,24 +1,54 @@
 import type { Hash } from '@xylabs/sdk-js'
 import { isDefined } from '@xylabs/sdk-js'
-import type { ReadArchivist } from '@xyo-network/archivist-model'
-import type { Payload } from '@xyo-network/payload-model'
+import type { ReadArchivist, ReadWriteArchivist } from '@xyo-network/archivist-model'
+import type { Payload, WithStorageMeta } from '@xyo-network/payload-model'
 
-import { isReadArchivist } from '../block/index.ts'
-import type { PayloadMapRead } from '../model/index.ts'
+import { isReadArchivist, isReadWriteArchivist } from '../block/index.ts'
+import type { PayloadMap, PayloadMapRead } from '../model/index.ts'
 
-export function readPayloadMapFromStore<T extends Payload>(store: ReadArchivist<T> | PayloadMapRead<T>): PayloadMapRead<T> {
+export function readPayloadMapFromStore<T extends Payload>(store: ReadArchivist<T> | PayloadMapRead<WithStorageMeta<T>>): PayloadMapRead<WithStorageMeta<T>> {
   if (isReadArchivist(store)) {
     return {
-      get: async (hash: Hash): Promise<T | undefined> => {
+      get: async (hash: Hash) => {
         return (await store.get([hash]))[0]
       },
-      getMany: async (hashes: Hash[]): Promise<T[]> => {
+      getMany: async (hashes: Hash[]) => {
         return (await store.get(hashes))
       },
-      has: async (hash: Hash): Promise<boolean> => {
+      has: async (hash: Hash) => {
         return isDefined((await store.get([hash]))[0])
       },
     }
   }
   return store
 }
+
+export function payloadMapFromStore<T extends Payload>(store: ReadWriteArchivist<T> | PayloadMap<WithStorageMeta<T>>): PayloadMap<WithStorageMeta<T>> {
+  if (isReadWriteArchivist(store)) {
+    return {
+      get: async (hash: Hash) => {
+        return (await store.get([hash]))[0]
+      },
+      getMany: async (hashes: Hash[]) => {
+        return (await store.get(hashes))
+      },
+      has: async (hash: Hash) => {
+        return isDefined((await store.get([hash]))[0])
+      },
+      clear: async () => {
+        return await store.clear()
+      },
+      delete: async (id: Hash) => {
+        await store.delete([id])
+        return true
+      },
+      set: async (_id: Hash, data: T) => {
+        await store.insert([data])
+      },
+      setMany: async (entries: [Hash, T][]) => {
+        await store.insert(entries.map(e => e[1]))
+      },
+    } satisfies PayloadMap<WithStorageMeta<T>>
+  }
+  return store
+}

package/src/primitives/rewards/index.ts

@@ -0,0 +1 @@
+export * from './networkStakeStepRewardPositionWeight.ts'

package/src/primitives/rewards/networkStakeStepRewardPositionWeight.ts

@@ -0,0 +1,21 @@
+import { type StepIdentity } from '@xyo-network/xl1-protocol'
+
+import type { StakedChainContextRead } from '../../model/index.ts'
+import type { BlockViewer } from '../../viewers/index.ts'
+import { externalBlockRangeFromStep } from '../chain/time/index.ts'
+import { weightedStakeForRangeByPosition } from '../stake/index.ts'
+
+export async function networkStakeStepRewardPositionWeight(
+  context: StakedChainContextRead,
+  blockViewer: BlockViewer,
+  stepContext: StepIdentity,
+  position: number,
+): Promise<bigint> {
+  const result = await weightedStakeForRangeByPosition(
+    context,
+    blockViewer,
+    await externalBlockRangeFromStep(context, blockViewer, stepContext),
+    position,
+  )
+  return result
+}

package/src/primitives/stake/activeStakeAtTimeByAddress.ts

@@ -0,0 +1,26 @@
+import type { Address } from '@xylabs/sdk-js'
+import { isDefined } from '@xylabs/sdk-js'
+
+import type { StakeEventsViewer } from '../../viewers/index.ts'
+import { mergedAddRemoveStakeEventsByStaker } from './mergedAddRemoveStakeEventsByStaker.ts'
+
+export async function activeStakeAtTimeByAddress(
+  chain: StakeEventsViewer,
+  staked: Address,
+  time: number,
+  staker?: Address,
+): Promise<bigint> {
+  const stakeEvents = (await mergedAddRemoveStakeEventsByStaker(chain, [0, time], staked, staker)).toSorted((a, b) => a.time - b.time)
+  let result = 0n
+  for (const event of stakeEvents) {
+    if (event.time > time) break
+    if (event.args.staked !== staked) continue
+    if (isDefined(staker) && (event.args.staker !== staker)) continue
+    if (event.name === 'StakeAdded') {
+      result += event.args.amount
+    } else if (event.name === 'StakeRemoved') {
+      result -= event.args.amount
+    }
+  }
+  return result
+}

package/src/primitives/stake/activeStakeAtTimeByPosition.ts

@@ -0,0 +1,24 @@
+import { isUndefined } from '@xylabs/sdk-js'
+
+import type { StakeEventsViewer } from '../../viewers/index.ts'
+import { mergedAddRemoveStakeEventsByPosition } from './mergedAddRemoveStakeEventsByPosition.ts'
+
+export async function activeStakeAtTimeByPosition(
+  chainStakeEvents: StakeEventsViewer,
+  externalTime: number,
+  position?: number,
+): Promise<bigint> {
+  const stakeEvents = (await mergedAddRemoveStakeEventsByPosition(chainStakeEvents, [0, externalTime], position)).toSorted((a, b) => a.time - b.time)
+  let result = 0n
+  for (const event of stakeEvents) {
+    if (event.time > externalTime) break
+    if (isUndefined(position) || position === Number(event.args.id)) {
+      if (event.name === 'StakeAdded') {
+        result += event.args.amount
+      } else if (event.name === 'StakeRemoved') {
+        result -= event.args.amount
+      }
+    }
+  }
+  return result
+}

package/src/primitives/stake/allStakersForRange.ts

@@ -0,0 +1,31 @@
+import {
+  type Address,
+  toAddress,
+} from '@xylabs/sdk-js'
+
+import type { StakeEventsViewer } from '../../viewers/index.ts'
+import { mergedAddRemoveStakeEventsByStaker } from './mergedAddRemoveStakeEventsByStaker.ts'
+
+export async function allStakersForRange(
+  chain: StakeEventsViewer,
+  externalRange: [number, number],
+  staked: Address,
+): Promise<Record<Address, bigint>> {
+  const mergedEvents = await mergedAddRemoveStakeEventsByStaker(chain, [0, externalRange[1]], staked)
+  const resultWithZeros: Record<Address, bigint> = {}
+  for (const event of mergedEvents) {
+    const staker = toAddress(event.args.staker)
+    resultWithZeros[staker] = resultWithZeros[staker] ?? 0n
+    if (event.name === 'StakeAdded') {
+      resultWithZeros[staker] += event.args.amount
+    } else if (event.name === 'StakeRemoved') {
+      resultWithZeros[staker] -= event.args.amount
+    }
+  }
+  const nonZero = Object.entries(resultWithZeros).filter(([, amount]) => amount > 0n).map(([address]) => address)
+  const result: Record<Address, bigint> = {}
+  for (const address of nonZero) {
+    result[toAddress(address)] = resultWithZeros[toAddress(address)]
+  }
+  return result
+}

package/src/primitives/stake/allStakersForStep.ts

@@ -0,0 +1,22 @@
+import { type Address } from '@xylabs/sdk-js'
+import type { StepIdentity } from '@xyo-network/xl1-protocol'
+
+import type { StakedChainContextRead } from '../../model/index.ts'
+import type { BlockViewer } from '../../viewers/index.ts'
+import { externalBlockRangeFromXL1BlockRange } from '../chain/time/index.ts'
+import { stepBlockRange } from '../step/index.ts'
+import { allStakersForRange } from './allStakersForRange.ts'
+
+export async function allStakersForStep(
+  context: StakedChainContextRead,
+  blockViewer: BlockViewer,
+  stepContext: StepIdentity,
+  staked: Address,
+): Promise<Record<Address, bigint>> {
+  const xl1BlockRange = stepBlockRange(stepContext)
+  return await allStakersForRange(
+    context.stake.stakeEvents,
+    await externalBlockRangeFromXL1BlockRange(context, blockViewer, xl1BlockRange),
+    staked,
+  )
+}

package/src/primitives/stake/index.ts

@@ -0,0 +1,6 @@
+export * from './activeStakeAtTimeByAddress.ts'
+export * from './activeStakeAtTimeByPosition.ts'
+export * from './allStakersForRange.ts'
+export * from './allStakersForStep.ts'
+export * from './mergedAddRemoveStakeEventsByPosition.ts'
+export * from './weightedStakeForRangeByPosition.ts'

package/src/primitives/stake/mergedAddRemoveStakeEventsByPosition.ts

@@ -0,0 +1,14 @@
+import type { StakeEvent, StakeEventsViewer } from '../../viewers/index.ts'
+
+export async function mergedAddRemoveStakeEventsByPosition(
+  chainEvents: StakeEventsViewer,
+  range: [number, number],
+  position?: number,
+): Promise<(StakeEvent<'StakeAdded'> | StakeEvent<'StakeRemoved'>)[]> {
+  const [addedEvents, removedEvents] = await Promise.all([
+    chainEvents.stakeEvents(range, { name: 'StakeAdded', args: { id: position } }),
+    chainEvents.stakeEvents(range, { name: 'StakeRemoved', args: { id: position } }),
+  ])
+  const result = [...addedEvents, ...removedEvents].toSorted((a, b) => a.time - b.time)
+  return result
+}

package/src/primitives/stake/mergedAddRemoveStakeEventsByStaker.ts

@@ -0,0 +1,17 @@
+import type { Address } from '@xylabs/sdk-js'
+
+import type { StakeEvent, StakeEventsViewer } from '../../viewers/index.ts'
+
+export async function mergedAddRemoveStakeEventsByStaker(
+  chainEvents: StakeEventsViewer,
+  range: [number, number],
+  staked: Address,
+  staker?: Address,
+): Promise<(StakeEvent<'StakeAdded'> | StakeEvent<'StakeRemoved'>)[]> {
+  const [addedEvents, removedEvents] = await Promise.all([
+    chainEvents.stakeEvents(range, { name: 'StakeAdded', args: { staked, staker } }),
+    chainEvents.stakeEvents(range, { name: 'StakeRemoved', args: { staked, staker } }),
+  ])
+  const result = [...addedEvents, ...removedEvents].toSorted((a, b) => a.time - b.time)
+  return result
+}

package/src/primitives/stake/weightedStakeForRangeByPosition.ts

@@ -0,0 +1,54 @@
+import { isDefined } from '@xylabs/sdk-js'
+import { asBlockNumber, type BlockRange } from '@xyo-network/xl1-protocol'
+
+import { type StakedChainContextRead, withContextCacheResponse } from '../../model/index.ts'
+import type { BlockViewer } from '../../viewers/index.ts'
+import { mergedAddRemoveStakeEventsByPosition } from './mergedAddRemoveStakeEventsByPosition.ts'
+
+export async function weightedStakeForRangeByPosition(
+  context: StakedChainContextRead,
+  blockViewer: BlockViewer,
+  externalRange: BlockRange, // first to last block of step
+  positionId?: number,
+): Promise<bigint> {
+  const cacheKey = isDefined(positionId) ? `${externalRange[0]}-${externalRange[1]}-${positionId}` : `${externalRange[0]}-${externalRange[1]}-all`
+  return await withContextCacheResponse(context, 'weightedStakeForRangeByPosition', cacheKey, async () => {
+    let weightedStakeSum = 0n
+    if (isDefined(positionId)) {
+      const mergedEvents = (await mergedAddRemoveStakeEventsByPosition(
+        context.stake.stakeEvents,
+        [0, externalRange[1]],
+        positionId,
+      )).toSorted((a, b) => a.time - b.time)
+      let currentTime = externalRange[0]
+      let currentStake = 0n // await activeStakeAtTimeByPosition(chainEvents, pos.staked, currentTime - 1, position)
+      for (const event of mergedEvents) {
+        if (event.time > currentTime) {
+          // Add the weighted stake for the period between the range start or previous event and this event
+          weightedStakeSum += currentStake * BigInt(event.time - currentTime)
+        }
+        if (event.name === 'StakeAdded') {
+          currentStake += event.args.amount
+        } else if (event.name === 'StakeRemoved') {
+          currentStake -= event.args.amount
+        }
+        // seems that sometimes we get multiple remove events, so ensure stake doesn't go negative
+        currentStake = currentStake < 0n ? 0n : currentStake
+        currentTime = asBlockNumber(event.time, { name: 'weightedStakeForRangeByPosition' })
+        if (currentTime > externalRange[1]) {
+          break
+        }
+      }
+      if (externalRange[1] > currentTime) {
+        // Add the weighted stake for the period between the last event and the end of the range
+        weightedStakeSum += currentStake * BigInt(externalRange[1] - currentTime)
+      }
+    } else {
+      const positionCount = await context.stake.stakeEvents.positionCount(externalRange)
+      for (let pos = 0; pos < positionCount; pos++) {
+        weightedStakeSum += await weightedStakeForRangeByPosition(context, blockViewer, externalRange, pos)
+      }
+    }
+    return weightedStakeSum
+  })
+}

package/src/primitives/uncle/findBestUncle.ts

@@ -0,0 +1,8 @@
+import type { SignedHydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol'
+
+import { scoreUncle } from './scoreUncle.ts'
+
+export function findBestUncle(finalizedWindowedChain: SignedHydratedBlockWithHashMeta[], uncles: SignedHydratedBlockWithHashMeta[][]) {
+  const scores = uncles.map(uncle => ([scoreUncle(finalizedWindowedChain, uncle), uncle] as const)).toSorted((a, b) => b[0] - a[0])
+  return scores[0]?.[1] ?? finalizedWindowedChain
+}

package/src/primitives/uncle/findUncles.ts

@@ -0,0 +1,75 @@
+import {
+  assertEx,
+  exists, type Hash,
+} from '@xylabs/sdk-js'
+import { isTransactionBoundWitness, type SignedHydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol'
+
+import type { BaseContext } from '../../model/index.ts'
+
+function blocksToChains(blocks: SignedHydratedBlockWithHashMeta[]) {
+  const chains: SignedHydratedBlockWithHashMeta[][] = []
+  const map = new Map<Hash, SignedHydratedBlockWithHashMeta>()
+  for (const block of blocks) {
+    map.set(block[0]._hash, block)
+  }
+  for (const block of blocks) {
+    let uncle: SignedHydratedBlockWithHashMeta[] = [block]
+    let previous = block[0].previous ? map.get(block[0].previous) : undefined
+    while (previous) {
+      if (previous[0].block === (uncle[0][0].block - 1)) {
+        uncle.unshift(previous)
+        previous = previous[0].previous ? map.get(previous[0].previous) : undefined
+      } else {
+        // block number sequence is off
+        uncle = []
+        break
+      }
+    }
+    if (uncle.length > 0) {
+      chains.push(uncle)
+    }
+  }
+  return chains
+}
+
+function toValidUncle(
+  _context: BaseContext,
+  finalizedWindowedChain: SignedHydratedBlockWithHashMeta[],
+  possibleUncle: SignedHydratedBlockWithHashMeta[],
+) {
+  const finalizedWindowStartBlockNumber = finalizedWindowedChain.at(0)?.[0].block ?? -1
+  const finalizedHead = assertEx(finalizedWindowedChain.at(-1), () => 'finalizedWindowedChain is empty')
+  // prune the chain to match the finalized head
+
+  const prunedPossibleUncle = possibleUncle.filter(b => b[0].block > finalizedHead[0].block)
+
+  if (prunedPossibleUncle.length === 0) {
+    return
+  }
+
+  if (prunedPossibleUncle[0][0].block !== finalizedHead[0].block + 1) {
+    // uncle does not build on finalized head (block number mismatch)
+    return
+  }
+  if (prunedPossibleUncle[0][0].previous !== finalizedHead[0]._hash) {
+    // uncle does not build on finalized head (previous hash mismatch)
+    return
+  }
+  const allUncleTransactions = prunedPossibleUncle.flatMap(b => b[1]).filter(isTransactionBoundWitness)
+  const allFinalizedTransactions = finalizedWindowedChain.flatMap(b => b[1]).filter(isTransactionBoundWitness)
+  const txPossiblyBeforeWindow = allUncleTransactions.find(tx => tx.nbf < finalizedWindowStartBlockNumber)
+  if (txPossiblyBeforeWindow) {
+    // uncle has a transaction that is valid before the finalized window
+    return
+  }
+  const txExistsInWindow = allUncleTransactions.find(tx => allFinalizedTransactions.find(finalTx => finalTx._hash === tx._hash))
+  if (txExistsInWindow) {
+    // uncle has a transaction that is already in the finalized window
+    return
+  }
+  return prunedPossibleUncle
+}
+
+export function findUncles(context: BaseContext, finalizedWindowedChain: SignedHydratedBlockWithHashMeta[], blocks: SignedHydratedBlockWithHashMeta[]) {
+  return blocksToChains(blocks).map(chain => toValidUncle(context, finalizedWindowedChain, chain)).filter(exists)
+}

package/src/primitives/uncle/index.ts

@@ -0,0 +1,3 @@
+export * from './findBestUncle.ts'
+export * from './findUncles.ts'
+export * from './scoreUncle.ts'

package/src/primitives/uncle/scoreUncle.ts

@@ -0,0 +1,6 @@
+import type { SignedHydratedBlockWithHashMeta } from '@xyo-network/xl1-protocol'
+
+export function scoreUncle(finalizedWindowedChain: SignedHydratedBlockWithHashMeta[], blocks: SignedHydratedBlockWithHashMeta[]) {
+  // TODO: More than length check
+  return blocks.length
+}

package/src/provider/DataLake.ts

@@ -2,24 +2,25 @@ import type { Hash } from '@xylabs/sdk-js'
 import type { Payload, Schema } from '@xyo-network/payload-model'
 
 import type { MapType } from '../map/index.ts'
+import type { Provider } from '../model/index.ts'
 
 export type DataLakeData = Payload | ArrayBuffer
 
-export type DataLakeViewerMethods = Pick<MapType<Hash, DataLakeData>, 'get' | 'getMany' | 'has'>
-
-export interface DataLakeViewer extends DataLakeViewerMethods {
-  allowedSchemas?: Schema[]
-  disallowedSchemas?: Schema[]
-}
-
 export const DataLakeViewerMoniker = 'DataLakeViewer' as const
 export type DataLakeViewerMoniker = typeof DataLakeViewerMoniker
 
-export type DataLakeRunnerMethods = Pick<MapType<Hash, DataLakeData>, 'set' | 'delete' | 'clear'> & {
-  setMany(entries: [Hash, DataLakeData][]): Promise<void>
-}
+export interface DataLakeViewerMethods extends
+  Pick<MapType<Hash, DataLakeData>, 'get' | 'getMany' | 'has'> {}
 
-export interface DataLakeRunner extends DataLakeRunnerMethods {}
+export interface DataLakeViewer extends DataLakeViewerMethods, Provider<DataLakeViewerMoniker> {
+  allowedSchemas?: Schema[]
+  disallowedSchemas?: Schema[]
+}
 
 export const DataLakeRunnerMoniker = 'DataLakeRunner' as const
 export type DataLakeRunnerMoniker = typeof DataLakeRunnerMoniker
+
+export interface DataLakeRunnerMethods extends Pick<MapType<Hash, DataLakeData>, 'setMany' | 'set' | 'delete' | 'clear'>,
+  DataLakeViewerMethods {}
+
+export interface DataLakeRunner extends DataLakeRunnerMethods, Provider<DataLakeRunnerMoniker> {}