@snaha/swarm-id 0.0.1

package/src/proxy/feeds/epochs/epoch.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Unit tests for epoch structure and tree navigation
+ */
+
+import { describe, it, expect } from "vitest"
+import { EpochIndex, lca, next, MAX_LEVEL } from "./epoch"
+
+describe("EpochIndex", () => {
+  describe("constructor", () => {
+    it("should create epoch with valid level", () => {
+      const epoch = new EpochIndex(0n, 0)
+      expect(epoch.start).toBe(0n)
+      expect(epoch.level).toBe(0)
+    })
+
+    it("should throw error for negative level", () => {
+      expect(() => new EpochIndex(0n, -1)).toThrow()
+    })
+
+    it("should throw error for level > MAX_LEVEL", () => {
+      expect(() => new EpochIndex(0n, MAX_LEVEL + 1)).toThrow()
+    })
+  })
+
+  describe("length", () => {
+    it("should return 1 for level 0", () => {
+      const epoch = new EpochIndex(0n, 0)
+      expect(epoch.length()).toBe(1n)
+    })
+
+    it("should return 2^level", () => {
+      expect(new EpochIndex(0n, 1).length()).toBe(2n)
+      expect(new EpochIndex(0n, 2).length()).toBe(4n)
+      expect(new EpochIndex(0n, 3).length()).toBe(8n)
+      expect(new EpochIndex(0n, 10).length()).toBe(1024n)
+    })
+
+    it("should handle MAX_LEVEL", () => {
+      const epoch = new EpochIndex(0n, MAX_LEVEL)
+      expect(epoch.length()).toBe(1n << BigInt(MAX_LEVEL))
+    })
+  })
+
+  describe("parent", () => {
+    it("should calculate parent epoch", () => {
+      const child = new EpochIndex(0n, 0)
+      const parent = child.parent()
+      expect(parent.level).toBe(1)
+      expect(parent.start).toBe(0n)
+    })
+
+    it("should normalize start to parent boundary", () => {
+      const child = new EpochIndex(3n, 0)
+      const parent = child.parent()
+      expect(parent.level).toBe(1)
+      expect(parent.start).toBe(2n) // 3/2*2 = 2
+    })
+
+    it("should handle multiple levels", () => {
+      let epoch = new EpochIndex(0n, 0)
+      epoch = epoch.parent()
+      expect(epoch.level).toBe(1)
+      epoch = epoch.parent()
+      expect(epoch.level).toBe(2)
+      epoch = epoch.parent()
+      expect(epoch.level).toBe(3)
+    })
+  })
+
+  describe("left", () => {
+    it("should return left sibling at same level", () => {
+      const epoch = new EpochIndex(2n, 1)
+      const left = epoch.left()
+      expect(left.level).toBe(1) // Same level
+      expect(left.start).toBe(0n) // 2 - 2 = 0
+    })
+
+    it("should calculate left sibling correctly", () => {
+      const epoch = new EpochIndex(8n, 2)
+      const left = epoch.left()
+      expect(left.level).toBe(2) // Same level
+      expect(left.start).toBe(4n) // 8 - 4 = 4
+    })
+  })
+
+  describe("childAt", () => {
+    it("should return left child when at is in left half", () => {
+      const parent = new EpochIndex(0n, 2)
+      const child = parent.childAt(1n)
+      expect(child.level).toBe(1)
+      expect(child.start).toBe(0n)
+    })
+
+    it("should return right child when at is in right half", () => {
+      const parent = new EpochIndex(0n, 2)
+      const child = parent.childAt(3n)
+      expect(child.level).toBe(1)
+      expect(child.start).toBe(2n)
+    })
+
+    it("should handle multiple descents", () => {
+      let epoch = new EpochIndex(0n, 3)
+      epoch = epoch.childAt(5n)
+      expect(epoch.level).toBe(2)
+      expect(epoch.start).toBe(4n)
+      epoch = epoch.childAt(5n)
+      expect(epoch.level).toBe(1)
+      expect(epoch.start).toBe(4n)
+      epoch = epoch.childAt(5n)
+      expect(epoch.level).toBe(0)
+      expect(epoch.start).toBe(5n)
+    })
+  })
+
+  describe("isLeft", () => {
+    it("should return true for left child", () => {
+      const parent = new EpochIndex(0n, 2)
+      const left = parent.childAt(0n)
+      expect(left.isLeft()).toBe(true)
+    })
+
+    it("should return false for right child", () => {
+      const parent = new EpochIndex(0n, 2)
+      const right = parent.childAt(3n)
+      expect(right.isLeft()).toBe(false)
+    })
+
+    it("should handle level 0", () => {
+      expect(new EpochIndex(0n, 0).isLeft()).toBe(true)
+      expect(new EpochIndex(1n, 0).isLeft()).toBe(false)
+      expect(new EpochIndex(2n, 0).isLeft()).toBe(true)
+      expect(new EpochIndex(3n, 0).isLeft()).toBe(false)
+    })
+  })
+
+  describe("marshalBinary", () => {
+    it("should produce 32-byte hash", async () => {
+      const epoch = new EpochIndex(0n, 0)
+      const hash = await epoch.marshalBinary()
+      expect(hash.length).toBe(32)
+    })
+
+    it("should produce different hashes for different epochs", async () => {
+      const epoch1 = new EpochIndex(0n, 0)
+      const epoch2 = new EpochIndex(1n, 0)
+      const epoch3 = new EpochIndex(0n, 1)
+
+      const hash1 = await epoch1.marshalBinary()
+      const hash2 = await epoch2.marshalBinary()
+      const hash3 = await epoch3.marshalBinary()
+
+      expect(hash1).not.toEqual(hash2)
+      expect(hash1).not.toEqual(hash3)
+      expect(hash2).not.toEqual(hash3)
+    })
+
+    it("should produce same hash for same epoch", async () => {
+      const epoch1 = new EpochIndex(42n, 10)
+      const epoch2 = new EpochIndex(42n, 10)
+
+      const hash1 = await epoch1.marshalBinary()
+      const hash2 = await epoch2.marshalBinary()
+
+      expect(hash1).toEqual(hash2)
+    })
+  })
+
+  describe("toString", () => {
+    it("should format as start/level", () => {
+      expect(new EpochIndex(0n, 0).toString()).toBe("0/0")
+      expect(new EpochIndex(42n, 10).toString()).toBe("42/10")
+      expect(new EpochIndex(1000n, 20).toString()).toBe("1000/20")
+    })
+  })
+})
+
+describe("lca (Lowest Common Ancestor)", () => {
+  it("should return top epoch when after is 0", () => {
+    const result = lca(100n, 0n)
+    expect(result.level).toBe(MAX_LEVEL)
+    expect(result.start).toBe(0n)
+  })
+
+  it("should return level 1 for adjacent timestamps", () => {
+    const result = lca(5n, 4n)
+    expect(result.level).toBe(1) // Spans [4, 6), contains both 4 and 5
+    expect(result.start).toBe(4n)
+  })
+
+  it("should return level 2 for timestamps 2 apart", () => {
+    const result = lca(6n, 4n)
+    expect(result.level).toBe(2) // Spans [4, 8), contains both 4 and 6
+    expect(result.start).toBe(4n)
+  })
+
+  it("should return level 4 for timestamps 4 apart", () => {
+    const result = lca(8n, 4n)
+    expect(result.level).toBe(4) // Spans [0, 16), contains both 4 and 8
+    expect(result.start).toBe(0n)
+  })
+
+  it("should handle same timestamp", () => {
+    const result = lca(5n, 5n)
+    expect(result.level).toBe(0)
+    expect(result.start).toBe(5n)
+  })
+
+  it("should handle large gaps", () => {
+    const result = lca(1000n, 100n)
+    expect(result.level).toBeGreaterThan(8) // 2^9 = 512, 2^10 = 1024
+  })
+})
+
+describe("next", () => {
+  it("should return top epoch for first update", () => {
+    const result = next(undefined, 0n, 100n)
+    expect(result.level).toBe(MAX_LEVEL)
+    expect(result.start).toBe(0n)
+  })
+
+  it("should calculate next epoch within same parent", () => {
+    // Last update was at time 0 in epoch (0, 2)
+    const last = new EpochIndex(0n, 2)
+    // New update at time 1, which is within [0, 4)
+    const result = next(last, 0n, 1n)
+    // Should descend to child at time 1
+    expect(result.start).toBe(0n)
+    expect(result.level).toBe(1)
+  })
+
+  it("should handle updates spanning different epochs", () => {
+    // Last update was at time 100 in some epoch
+    const last = new EpochIndex(100n, 0)
+    // New update at time 200
+    const result = next(last, 100n, 200n)
+    // Should use lca(200, 100) and descend
+    expect(result.start).toBeLessThanOrEqual(200n)
+    expect(result.level).toBeGreaterThanOrEqual(0)
+  })
+
+  it("proxy-style seeded parent state should descend to exact level-0 epoch", () => {
+    for (let at = 1n; at < 128n; at++) {
+      const seededParent = new EpochIndex(at & ~1n, 1)
+      const result = next(seededParent, at - 1n, at)
+      expect(result.level).toBe(0)
+      expect(result.start).toBe(at)
+    }
+  })
+})

package/src/proxy/feeds/epochs/epoch.ts

@@ -0,0 +1,181 @@
+/**
+ * Epoch-based Feed Indexing
+ *
+ * Implements time-based indexing using a binary tree structure where each epoch
+ * represents a time range with start time and level (0-32).
+ *
+ * Based on the Swarm Book of Feeds and Bee's epochs implementation.
+ */
+
+import { Binary } from "cafe-utility"
+
+/** Maximum epoch level (2^32 seconds ≈ 136 years) */
+export const MAX_LEVEL = 32
+
+/**
+ * Epoch interface - represents a time slot in the epoch tree
+ */
+export interface Epoch {
+  start: bigint // Unix timestamp (seconds)
+  level: number // 0-32, where length = 2^level
+}
+
+/**
+ * EpochIndex class - implements epoch-based feed indexing
+ *
+ * Each epoch represents a time range:
+ * - start: beginning timestamp of the epoch
+ * - level: determines the epoch's time span (2^level seconds)
+ *
+ * Epochs form a binary tree structure for efficient sparse updates.
+ */
+export class EpochIndex implements Epoch {
+  constructor(
+    public readonly start: bigint,
+    public readonly level: number,
+  ) {
+    if (level < 0 || level > MAX_LEVEL) {
+      throw new Error(
+        `Epoch level must be between 0 and ${MAX_LEVEL}, got ${level}`,
+      )
+    }
+  }
+
+  /**
+   * Marshal epoch to binary format for hashing
+   * Returns Keccak256 hash of start (8 bytes big-endian) + level (1 byte)
+   */
+  async marshalBinary(): Promise<Uint8Array> {
+    const buffer = new Uint8Array(9)
+    const view = new DataView(buffer.buffer)
+
+    // Write start as 8-byte big-endian
+    view.setBigUint64(0, this.start, false) // false = big-endian
+
+    // Write level as 1 byte
+    buffer[8] = this.level
+
+    return Binary.keccak256(buffer)
+  }
+
+  /**
+   * Calculate the next epoch for a new update
+   * @param last - Timestamp of last update
+   * @param at - Timestamp of new update
+   */
+  next(last: bigint, at: bigint): EpochIndex {
+    if (this.start + this.length() > at) {
+      return this.childAt(at)
+    }
+    return lca(at, last).childAt(at)
+  }
+
+  /**
+   * Calculate epoch length in seconds (2^level)
+   */
+  length(): bigint {
+    return 1n << BigInt(this.level)
+  }
+
+  /**
+   * Get parent epoch
+   * UNSAFE: Do not call on top-level epoch (level 32)
+   */
+  parent(): EpochIndex {
+    const length = this.length() << 1n
+    const start = (this.start / length) * length
+    return new EpochIndex(start, this.level + 1)
+  }
+
+  /**
+   * Get left sibling epoch
+   * UNSAFE: Do not call on left sibling (when start is aligned to 2*length)
+   */
+  left(): EpochIndex {
+    return new EpochIndex(this.start - this.length(), this.level)
+  }
+
+  /**
+   * Get child epoch containing timestamp `at`
+   * UNSAFE: Do not call with `at` outside this epoch's range
+   */
+  childAt(at: bigint): EpochIndex {
+    const newLevel = this.level - 1
+    const length = 1n << BigInt(newLevel)
+    let start = this.start
+
+    // If `at` falls in right half, adjust start
+    if ((at & length) > 0n) {
+      start |= length
+    }
+
+    return new EpochIndex(start, newLevel)
+  }
+
+  /**
+   * Check if this epoch is a left child of its parent
+   */
+  isLeft(): boolean {
+    return (this.start & this.length()) === 0n
+  }
+
+  /**
+   * String representation: "start/level"
+   */
+  toString(): string {
+    return `${this.start}/${this.level}`
+  }
+}
+
+/**
+ * Calculate Lowest Common Ancestor epoch for two timestamps
+ *
+ * The LCA is the smallest epoch that contains both `at` and `after`.
+ * This is used to find the optimal starting point for feed lookups.
+ *
+ * @param at - Target timestamp
+ * @param after - Reference timestamp (0 if no previous update)
+ * @returns LCA epoch
+ */
+export function lca(at: bigint, after: bigint): EpochIndex {
+  // If no previous update, start from top-level epoch
+  if (after === 0n) {
+    return new EpochIndex(0n, MAX_LEVEL)
+  }
+
+  const diff = at - after
+  let length = 1n
+  let level = 0
+
+  // Find the smallest epoch level where both timestamps fall in different epochs
+  // OR at and after are in the same epoch
+  while (
+    level < MAX_LEVEL &&
+    (length < diff || at / length !== after / length)
+  ) {
+    length <<= 1n
+    level++
+  }
+
+  // Calculate start of the epoch containing both timestamps
+  const start = (after / length) * length
+
+  return new EpochIndex(start, level)
+}
+
+/**
+ * Helper function to get next epoch for update, handling null previous epoch
+ * @param prevEpoch - Previous epoch (null if first update)
+ * @param last - Timestamp of last update
+ * @param at - Timestamp of new update
+ */
+export function next(
+  prevEpoch: EpochIndex | undefined,
+  last: bigint,
+  at: bigint,
+): EpochIndex {
+  if (!prevEpoch) {
+    return new EpochIndex(0n, MAX_LEVEL)
+  }
+  return prevEpoch.next(last, at)
+}

package/src/proxy/feeds/epochs/finder.ts

@@ -0,0 +1,282 @@
+/**
+ * Synchronous Epoch Feed Finder
+ *
+ * Recursive implementation for finding feed updates at specific timestamps
+ * using epoch-based indexing.
+ */
+
+import { Binary } from "cafe-utility"
+import type { Bee, BeeRequestOptions } from "@ethersphere/bee-js"
+import { EthAddress, Reference, Topic } from "@ethersphere/bee-js"
+import { EpochIndex, lca, MAX_LEVEL } from "./epoch"
+import type { EpochFinder } from "./types"
+import { findPreviousLeaf } from "./utils"
+
+const EPOCH_LOOKUP_TIMEOUT_MS = 2000
+
+/**
+ * Synchronous recursive finder for epoch-based feeds
+ *
+ * Traverses the epoch tree recursively to find the feed update
+ * valid at a specific timestamp.
+ *
+ * Implements the EpochFinder interface.
+ */
+export class SyncEpochFinder implements EpochFinder {
+  constructor(
+    private readonly bee: Bee,
+    private readonly topic: Topic,
+    private readonly owner: EthAddress,
+  ) {}
+
+  /**
+   * Find the feed update valid at time `at`
+   * @param at - Target unix timestamp (seconds)
+   * @param after - Hint of latest known update timestamp (0 if unknown)
+   * @returns 32-byte Swarm reference, or undefined if no update found
+   */
+  async findAt(
+    at: bigint,
+    after: bigint = 0n,
+  ): Promise<Uint8Array | undefined> {
+    // Fast path: exact timestamp updates are written at level-0 and should be
+    // retrievable without traversing potentially poisoned ancestors.
+    const exactEpoch = new EpochIndex(at, 0)
+    try {
+      const exact = await this.getEpochChunk(at, exactEpoch)
+      if (exact) {
+        return exact
+      }
+    } catch {
+      // Ignore and fall back to standard traversal.
+    }
+
+    const { epoch, chunk } = await this.common(at, after)
+
+    if (!chunk && epoch.level === MAX_LEVEL) {
+      // No update found at all
+      return undefined
+    }
+
+    const traversed = await this.atEpoch(at, epoch, chunk)
+    if (traversed) {
+      return traversed
+    }
+
+    // Recovery fallback for poisoned-ancestor histories: only enable bounded
+    // leaf back-scan when root epoch exists but is invalid for `at`.
+    try {
+      const rootProbe = await this.getEpochChunk(
+        at,
+        new EpochIndex(0n, MAX_LEVEL),
+      )
+      if (rootProbe === undefined) {
+        return this.findPreviousLeaf(at, after)
+      }
+    } catch {
+      // Root missing - no evidence of poisoned ancestors.
+    }
+
+    return undefined
+  }
+
+  /**
+   * Find the lowest common ancestor epoch with an existing chunk
+   *
+   * Traverses UP the epoch tree from the LCA until finding a chunk,
+   * or reaching the top level.
+   *
+   * @param at - Target timestamp
+   * @param after - Reference timestamp
+   * @returns Epoch and chunk found at that epoch (if any)
+   */
+  private async common(
+    at: bigint,
+    after: bigint,
+  ): Promise<{ epoch: EpochIndex; chunk?: Uint8Array }> {
+    let epoch = lca(at, after)
+
+    while (true) {
+      try {
+        const chunk = await this.getEpochChunk(at, epoch)
+
+        // getEpochChunk validates timestamp and returns undefined if invalid
+        if (chunk) {
+          return { epoch, chunk }
+        }
+
+        // Chunk found but timestamp invalid, continue searching up
+      } catch (error) {
+        // Chunk not found, continue searching up
+      }
+
+      // Check if at top before trying to go to parent
+      if (epoch.level === MAX_LEVEL) {
+        // Reached top without finding anything
+        return { epoch }
+      }
+
+      // Move to parent epoch
+      epoch = epoch.parent()
+    }
+  }
+
+  /**
+   * Recursive descent to find exact update at timestamp
+   *
+   * Traverses DOWN the epoch tree, handling left/right branches
+   * to find the most recent update not later than `at`.
+   *
+   * @param at - Target timestamp
+   * @param epoch - Current epoch being examined
+   * @param currentChunk - Best chunk found so far
+   * @returns Final chunk reference, or undefined
+   */
+  private async atEpoch(
+    at: bigint,
+    epoch: EpochIndex,
+    currentChunk?: Uint8Array,
+  ): Promise<Uint8Array | undefined> {
+    let chunk: Uint8Array | undefined
+
+    try {
+      chunk = await this.getEpochChunk(at, epoch)
+    } catch (error) {
+      // Epoch chunk not found
+      if (epoch.isLeft()) {
+        // No lower resolution available, return what we have
+        return currentChunk
+      }
+
+      // Traverse earlier branch (left sibling)
+      return this.atEpoch(epoch.start - 1n, epoch.left(), currentChunk)
+    }
+
+    // Chunk validation (timestamp) is handled by getEpochChunk
+    if (!chunk) {
+      // Timestamp invalid (update too recent)
+      if (epoch.level > 0) {
+        const down = await this.atEpoch(at, epoch.childAt(at), currentChunk)
+        if (down) {
+          return down
+        }
+      }
+      if (epoch.isLeft()) {
+        return currentChunk
+      }
+
+      // Traverse earlier branch
+      return this.atEpoch(epoch.start - 1n, epoch.left(), currentChunk)
+    }
+
+    // Update is valid
+    if (epoch.level === 0) {
+      // Finest resolution - this is our answer
+      return chunk
+    }
+
+    // Continue traversing down to finer resolution
+    return this.atEpoch(at, epoch.childAt(at), chunk)
+  }
+
+  /**
+   * Fetch chunk for a specific epoch
+   *
+   * Calculates the chunk address from topic, epoch, and owner,
+   * then downloads it from the Bee node.
+   *
+   * @param at - Target timestamp for validation
+   * @param epoch - Epoch to fetch
+   * @returns Chunk reference (32 or 64 bytes), or undefined if timestamp invalid
+   * @throws Error if chunk not found or network error
+   */
+  private async getEpochChunk(
+    at: bigint,
+    epoch: EpochIndex,
+  ): Promise<Uint8Array | undefined> {
+    const requestOptions: BeeRequestOptions = {
+      timeout: EPOCH_LOOKUP_TIMEOUT_MS,
+    }
+    // Calculate epoch identifier: Keccak256(topic || Keccak256(start || level))
+    const epochHash = await epoch.marshalBinary()
+    const identifier = Binary.keccak256(
+      Binary.concatBytes(this.topic.toUint8Array(), epochHash),
+    )
+
+    // Calculate chunk address: Keccak256(identifier || owner)
+    const address = new Reference(
+      Binary.keccak256(
+        Binary.concatBytes(identifier, this.owner.toUint8Array()),
+      ),
+    )
+
+    // Download chunk
+    const chunkData = await this.bee.downloadChunk(
+      address.toHex(),
+      undefined,
+      requestOptions,
+    )
+
+    // Extract payload from SOC (Single Owner Chunk)
+    // SOC structure: [identifier (32 bytes)][signature (65 bytes)][span (8 bytes)][payload]
+    const IDENTIFIER_SIZE = 32
+    const SIGNATURE_SIZE = 65
+    const SPAN_SIZE = 8
+    const TIMESTAMP_SIZE = 8
+    const SOC_HEADER_SIZE = IDENTIFIER_SIZE + SIGNATURE_SIZE
+
+    // Read span to get payload length
+    const spanStart = SOC_HEADER_SIZE
+    const span = chunkData.slice(spanStart, spanStart + SPAN_SIZE)
+    const spanView = new DataView(span.buffer, span.byteOffset, span.byteLength)
+    const payloadLength = Number(spanView.getBigUint64(0, true)) // little-endian
+
+    // Extract full payload (timestamp + reference)
+    const payloadStart = spanStart + SPAN_SIZE
+    const payload = chunkData.slice(payloadStart, payloadStart + payloadLength)
+
+    // Detect payload format based on length:
+    // - 40 bytes: timestamp(8) + reference(32) - from /soc endpoint
+    // - 48 bytes: span(8) + timestamp(8) + reference(32) - from /chunks with v1 format
+    // - 72 bytes: timestamp(8) + encrypted_reference(64) - from /soc endpoint
+    // - 80 bytes: span(8) + timestamp(8) + encrypted_reference(64) - from /chunks with v1 format
+    const VALID_PAYLOAD_LENGTHS = [40, 48, 72, 80]
+    if (!VALID_PAYLOAD_LENGTHS.includes(payload.length)) {
+      console.warn(
+        `Unexpected feed payload length: ${payload.length}. Expected 40, 48, 72, or 80 bytes.`,
+      )
+      return undefined
+    }
+
+    const hasSpanPrefix = payload.length === 48 || payload.length === 80
+
+    const timestampOffset = hasSpanPrefix ? 8 : 0
+    const timestampBytes = payload.slice(
+      timestampOffset,
+      timestampOffset + TIMESTAMP_SIZE,
+    )
+    const timestampView = new DataView(
+      timestampBytes.buffer,
+      timestampBytes.byteOffset,
+      timestampBytes.byteLength,
+    )
+    const timestamp = timestampView.getBigUint64(0, false) // big-endian
+
+    // Validate timestamp - update must be at or before target time
+    if (timestamp > at) {
+      return undefined
+    }
+
+    // Return reference only (skip timestamp and optional span prefix)
+    return payload.slice(timestampOffset + TIMESTAMP_SIZE)
+  }
+
+  private findPreviousLeaf(
+    at: bigint,
+    after: bigint,
+  ): Promise<Uint8Array | undefined> {
+    return findPreviousLeaf(at, after, (targetAt, epoch) =>
+      this.getEpochChunk(targetAt, epoch),
+    )
+  }
+}