@snaha/swarm-id 0.0.1

package/src/proxy/feeds/epochs/test-utils.ts

@@ -0,0 +1,274 @@
+/**
+ * Test utilities for epoch feeds
+ *
+ * Provides mock storage and helpers for testing epoch feed operations
+ */
+
+import { Binary } from "cafe-utility"
+import { PrivateKey, Topic, EthAddress } from "@ethersphere/bee-js"
+
+/**
+ * In-memory chunk storage for testing
+ */
+export class MockChunkStore {
+  private chunks = new Map<string, Uint8Array>()
+
+  async put(address: string, data: Uint8Array): Promise<void> {
+    this.chunks.set(address.toLowerCase(), data)
+  }
+
+  async get(address: string): Promise<Uint8Array> {
+    const data = this.chunks.get(address.toLowerCase())
+    if (!data) {
+      throw new Error(`Chunk not found: ${address}`)
+    }
+    return data
+  }
+
+  has(address: string): boolean {
+    return this.chunks.has(address.toLowerCase())
+  }
+
+  clear(): void {
+    this.chunks.clear()
+  }
+
+  size(): number {
+    return this.chunks.size
+  }
+}
+
+/**
+ * Mock Bee instance for testing
+ */
+export class MockBee {
+  public readonly url = "http://localhost:1633"
+  private store: MockChunkStore
+  private tagCounter = 0
+
+  constructor(store?: MockChunkStore) {
+    this.store = store || new MockChunkStore()
+  }
+
+  async createTag(): Promise<{
+    uid: number
+    split: number
+    seen: number
+    stored: number
+    sent: number
+    synced: number
+    address: string
+    startedAt: string
+  }> {
+    this.tagCounter++
+    return {
+      uid: this.tagCounter,
+      split: 0,
+      seen: 0,
+      stored: 0,
+      sent: 0,
+      synced: 0,
+      address: "",
+      startedAt: new Date().toISOString(),
+    }
+  }
+
+  async downloadChunk(reference: string): Promise<Uint8Array> {
+    return this.store.get(reference)
+  }
+
+  async uploadChunk(
+    data: Uint8Array,
+    _postageBatchId: string,
+  ): Promise<{ reference: string }> {
+    const address = Binary.keccak256(data)
+    const reference = Binary.uint8ArrayToHex(address)
+    await this.store.put(reference, data)
+    return { reference }
+  }
+
+  getStore(): MockChunkStore {
+    return this.store
+  }
+}
+
+/**
+ * Create test signer with a deterministic private key
+ */
+export function createTestSigner(): PrivateKey {
+  // Use a fixed private key for deterministic tests
+  const privateKeyHex =
+    "634fb5a872396d9693e5c9f9d7233cfa93f395c093371017ff44aa9ae6564cdd"
+  return new PrivateKey(privateKeyHex)
+}
+
+/**
+ * Create test topic
+ */
+export function createTestTopic(name: string = "testtopic"): Topic {
+  const encoder = new TextEncoder()
+  const hash = Binary.keccak256(encoder.encode(name))
+  return new Topic(hash)
+}
+
+/**
+ * Create test owner address
+ */
+export function createTestOwner(): EthAddress {
+  return createTestSigner().publicKey().address()
+}
+
+/**
+ * Create test reference (32 bytes)
+ */
+export function createTestReference(value: number | bigint): Uint8Array {
+  const ref = new Uint8Array(32)
+  const view = new DataView(ref.buffer)
+  view.setBigUint64(0, BigInt(value), false) // big-endian
+  return ref
+}
+
+/**
+ * Create test payload with timestamp
+ */
+export function createTestPayload(at: bigint): Uint8Array {
+  const payload = new Uint8Array(8)
+  const view = new DataView(payload.buffer)
+  view.setBigUint64(0, at, false) // big-endian
+  return payload
+}
+
+const BATCH_ID_LENGTH = 32
+const INDEX_LENGTH = 8
+const TIMESTAMP_LENGTH = 8
+const SIGNATURE_LENGTH = 65
+const ISSUER_LENGTH = 20
+const SOC_IDENTIFIER_LENGTH = 32
+
+/**
+ * Create a mock Stamper for testing
+ *
+ * Returns an object with a stamp() method that produces a valid-looking
+ * EnvelopeWithBatchId without performing real cryptographic operations.
+ */
+export function createMockStamper() {
+  return {
+    stamp(_chunk: any) {
+      return {
+        batchId: {
+          toUint8Array: () => new Uint8Array(BATCH_ID_LENGTH),
+        },
+        index: new Uint8Array(INDEX_LENGTH),
+        timestamp: new Uint8Array(TIMESTAMP_LENGTH),
+        signature: new Uint8Array(SIGNATURE_LENGTH),
+        issuer: new Uint8Array(ISSUER_LENGTH),
+      }
+    },
+  }
+}
+
+/**
+ * Mock fetch for SOC and chunk uploads
+ *
+ * Intercepts fetch calls to /soc/ and /chunks endpoints, storing data
+ * in the provided MockChunkStore.
+ *
+ * @param store - Mock chunk store for persisting uploaded data
+ * @param owner - Owner address for computing SOC addresses on /chunks uploads
+ */
+export function mockFetch(store?: MockChunkStore, owner?: EthAddress): void {
+  const originalFetch = global.fetch
+
+  global.fetch = async (url: string | URL | Request, init?: RequestInit) => {
+    // Parse URL
+    const urlStr = typeof url === "string" ? url : url.toString()
+
+    // Check if it's a SOC upload
+    if (urlStr.includes("/soc/")) {
+      // Extract body data and SOC info from URL
+      const body = init?.body as Uint8Array
+      if (!body) {
+        throw new Error("Missing body in SOC upload")
+      }
+
+      // Parse URL: /soc/{owner}/{id}?sig={signature}
+      const parts = urlStr.split("/soc/")[1].split("/")
+      const socOwner = parts[0]
+      const idAndSig = parts[1].split("?sig=")
+      const identifier = idAndSig[0]
+
+      // Calculate SOC address: Keccak256(identifier || owner)
+      const identifierBytes = Binary.hexToUint8Array(identifier)
+      const ownerBytes = Binary.hexToUint8Array(socOwner)
+      const socAddress = Binary.keccak256(
+        Binary.concatBytes(identifierBytes, ownerBytes),
+      )
+      const reference = Binary.uint8ArrayToHex(socAddress)
+
+      // Build full SOC chunk data (identifier + signature + span + payload)
+      // For mock purposes, we need to reconstruct the full SOC
+      const signatureHex = idAndSig[1]
+      const signatureBytes = Binary.hexToUint8Array(signatureHex)
+      const fullSOCData = Binary.concatBytes(
+        identifierBytes,
+        signatureBytes,
+        body, // This is span + payload
+      )
+
+      // Store in mock store if provided
+      if (store) {
+        await store.put(reference, fullSOCData)
+      }
+
+      return new Response(JSON.stringify({ reference }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      })
+    }
+
+    // Check if it's a chunk upload (used by uploadChunkWithFetch)
+    if (urlStr.includes("/chunks") && init?.method === "POST") {
+      const body = init?.body as Uint8Array
+      if (!body) {
+        throw new Error("Missing body in chunk upload")
+      }
+
+      // SOC data starts with identifier (32 bytes)
+      // Compute SOC address: Keccak256(identifier + owner)
+      if (store && owner) {
+        const identifier = body.slice(0, SOC_IDENTIFIER_LENGTH)
+        const socAddress = Binary.keccak256(
+          Binary.concatBytes(identifier, owner.toUint8Array()),
+        )
+        const reference = Binary.uint8ArrayToHex(socAddress)
+        await store.put(reference, body)
+        return new Response(JSON.stringify({ reference }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+      }
+
+      // Fallback: store by content hash
+      const address = Binary.keccak256(body)
+      const reference = Binary.uint8ArrayToHex(address)
+      if (store) {
+        await store.put(reference, body)
+      }
+      return new Response(JSON.stringify({ reference }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      })
+    }
+
+    // Fall back to original fetch for other URLs
+    return originalFetch(url, init)
+  }
+}
+
+/**
+ * Restore original fetch
+ */
+export function restoreFetch(): void {
+  // This is a simplified version - in production you'd want to properly restore
+  // For now, tests should use the mocked version throughout
+}

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

@@ -0,0 +1,128 @@
+/**
+ * Types for Epoch-Based Feeds
+ */
+
+import type {
+  Bee,
+  EthAddress,
+  Topic,
+  PrivateKey,
+  Stamper,
+} from "@ethersphere/bee-js"
+import type { EpochIndex } from "./epoch"
+
+/**
+ * Options for creating an epoch feed reader
+ */
+export interface EpochFeedOptions {
+  /** Bee instance for chunk operations */
+  bee: Bee
+
+  /** Feed topic (32 bytes) */
+  topic: Topic
+
+  /** Feed owner address */
+  owner: EthAddress
+
+  /** Optional encryption key for encrypted feed updates */
+  encryptionKey?: Uint8Array
+}
+
+/**
+ * Options for creating an epoch feed writer
+ */
+export interface EpochFeedWriterOptions extends EpochFeedOptions {
+  /** Private key for signing chunks */
+  signer: PrivateKey
+}
+
+/**
+ * Result from an epoch feed lookup
+ */
+export interface EpochLookupResult {
+  /** Swarm reference (32 bytes) */
+  reference: Uint8Array
+
+  /** Epoch where the update was found */
+  epoch: EpochIndex
+
+  /** Timestamp of the update */
+  timestamp: bigint
+}
+
+/**
+ * Hints for calculating the next epoch in a stateless manner.
+ * Callers should store these after each update and pass them to subsequent updates.
+ */
+export interface EpochUpdateHints {
+  /** Previous epoch (for calculating next) */
+  lastEpoch?: { start: bigint; level: number }
+  /** Timestamp of last update */
+  lastTimestamp?: bigint
+}
+
+/**
+ * Result from an epoch feed update, including epoch info for subsequent updates.
+ */
+export interface EpochUpdateResult {
+  /** SOC address of the uploaded chunk */
+  socAddress: Uint8Array
+  /** Epoch used for this update (for caller to store as hint) */
+  epoch: { start: bigint; level: number }
+  /** Timestamp used (for caller to store as hint) */
+  timestamp: bigint
+}
+
+/**
+ * Interface for epoch feed finders (readers)
+ *
+ * Implementations: SyncEpochFinder, AsyncEpochFinder
+ */
+export interface EpochFinder {
+  /**
+   * 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 or 64-byte Swarm reference, or undefined if no update found
+   */
+  findAt(at: bigint, after?: bigint): Promise<Uint8Array | undefined>
+}
+
+/**
+ * Interface for epoch feed updaters (writers)
+ *
+ * Implementation: BasicEpochUpdater
+ *
+ * Implements Bee-compatible stateless epoch calculation.
+ * Each update uses hints from the previous update to calculate the next epoch,
+ * creating a proper epoch tree that Bee's finder can traverse.
+ */
+export interface EpochUpdater {
+  /**
+   * Update feed with a reference at given timestamp
+   *
+   * Calculates the appropriate epoch based on hints:
+   * - First update (no hints): uses root epoch (level 32, start 0)
+   * - Subsequent updates: calculates next epoch using LCA-based algorithm
+   *
+   * @param at - Unix timestamp for this update (seconds)
+   * @param reference - 32 or 64-byte Swarm reference to store
+   * @param stamper - Stamper object for stamping
+   * @param encryptionKey - Optional encryption key for the update
+   * @param hints - Optional hints from previous update for calculating epoch
+   * @returns Update result with SOC address and epoch info for next update
+   */
+  update(
+    at: bigint,
+    reference: Uint8Array,
+    stamper: Stamper,
+    encryptionKey?: Uint8Array,
+    hints?: EpochUpdateHints,
+  ): Promise<EpochUpdateResult>
+
+  /**
+   * Get the owner address (derived from signer)
+   */
+  getOwner(): EthAddress
+}

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

@@ -0,0 +1,192 @@
+/**
+ * Basic Epoch Feed Updater
+ *
+ * Handles writing updates to epoch-based feeds by calculating the next
+ * epoch and uploading chunks.
+ */
+
+import { Binary } from "cafe-utility"
+import type { Bee, Stamper } from "@ethersphere/bee-js"
+import { EthAddress, Topic, PrivateKey, Identifier } from "@ethersphere/bee-js"
+import { EpochIndex, MAX_LEVEL } from "./epoch"
+import {
+  uploadEncryptedSOC,
+  uploadSOCViaSocEndpoint,
+} from "../../upload-encrypted-data"
+import type { EpochUpdater, EpochUpdateHints, EpochUpdateResult } from "./types"
+import { AsyncEpochFinder } from "./async-finder"
+
+/**
+ * Basic updater for epoch-based feeds
+ *
+ * Implements Bee-compatible stateless epoch calculation.
+ * Each update uses hints from the previous update to calculate the next epoch,
+ * creating a proper epoch tree that Bee's finder can traverse.
+ *
+ * - First update (no hints): uses root epoch (level 32, start 0)
+ * - Subsequent updates: calculates next epoch using the standard algorithm:
+ *   - If new timestamp within previous epoch's range: dive to child
+ *   - Else: jump to LCA(newTimestamp, prevTimestamp) and dive to child
+ *
+ * Implements the EpochUpdater interface.
+ */
+export class BasicEpochUpdater implements EpochUpdater {
+  constructor(
+    private readonly bee: Bee,
+    private readonly topic: Topic,
+    private readonly signer: PrivateKey,
+  ) {}
+
+  /**
+   * Update feed with a reference at given timestamp
+   *
+   * @param at - Unix timestamp for this update (seconds)
+   * @param reference - 32 or 64-byte Swarm reference to store
+   * @param stamper - Stamper object for stamping
+   * @param encryptionKey - Optional encryption key for the update
+   * @param hints - Optional hints from previous update for calculating epoch
+   * @returns Update result with SOC address and epoch info for next update
+   */
+  async update(
+    at: bigint,
+    reference: Uint8Array,
+    stamper: Stamper,
+    encryptionKey?: Uint8Array,
+    hints?: EpochUpdateHints,
+  ): Promise<EpochUpdateResult> {
+    if (reference.length !== 32 && reference.length !== 64) {
+      throw new Error(
+        `Reference must be 32 or 64 bytes, got ${reference.length}`,
+      )
+    }
+
+    // Calculate epoch - auto-lookup if no hints provided
+    const epoch = await this.calculateEpoch(at, hints, encryptionKey)
+
+    // Upload the chunk with timestamp + reference
+    const socAddress = await this.uploadEpochChunk(
+      epoch,
+      at,
+      reference,
+      stamper,
+      encryptionKey,
+    )
+
+    // Return result with hints for next update
+    return {
+      socAddress,
+      epoch: { start: epoch.start, level: epoch.level },
+      timestamp: at,
+    }
+  }
+
+  /**
+   * Calculate the epoch for this update based on hints or auto-lookup
+   *
+   * When hints are provided, uses them for fast epoch calculation.
+   * When no hints are provided, looks up the current feed state to calculate
+   * the next epoch, preventing overwrites of previous updates.
+   *
+   * @param at - Timestamp for this update
+   * @param hints - Optional hints from previous update
+   * @param encryptionKey - Optional encryption key for looking up encrypted feeds
+   * @returns Epoch to use for this update
+   */
+  private async calculateEpoch(
+    at: bigint,
+    hints?: EpochUpdateHints,
+    encryptionKey?: Uint8Array,
+  ): Promise<EpochIndex> {
+    // Fast path: use provided hints
+    if (hints?.lastEpoch && hints.lastTimestamp !== undefined) {
+      const prevEpoch = new EpochIndex(
+        hints.lastEpoch.start,
+        hints.lastEpoch.level,
+      )
+      return prevEpoch.next(hints.lastTimestamp, at)
+    }
+
+    // Slow path: lookup current state
+    const owner = this.signer.publicKey().address()
+    const finder = new AsyncEpochFinder(
+      this.bee,
+      this.topic,
+      owner,
+      encryptionKey,
+    )
+
+    // Use findAtWithMetadata to get both reference AND epoch info
+    const current = await finder.findAtWithMetadata(at)
+
+    if (!current) {
+      // First update ever - use root epoch
+      return new EpochIndex(0n, MAX_LEVEL)
+    }
+
+    // Calculate next epoch based on found state
+    return current.epoch.next(current.timestamp, at)
+  }
+
+  /**
+   * Get the owner address (derived from signer)
+   */
+  getOwner(): EthAddress {
+    return this.signer.publicKey().address()
+  }
+
+  /**
+   * Upload a chunk for a specific epoch
+   *
+   * @param epoch - Epoch to upload to
+   * @param at - Timestamp of this update
+   * @param reference - 32 or 64-byte reference to store
+   * @param stamper - Stamper object for stamping
+   * @returns SOC chunk address for utilization tracking
+   */
+  private async uploadEpochChunk(
+    epoch: EpochIndex,
+    at: bigint,
+    reference: Uint8Array,
+    stamper: Stamper,
+    encryptionKey?: Uint8Array,
+  ): Promise<Uint8Array> {
+    // Calculate epoch identifier: Keccak256(topic || Keccak256(start || level))
+    const epochHash = await epoch.marshalBinary()
+    const identifier = new Identifier(
+      Binary.keccak256(
+        Binary.concatBytes(this.topic.toUint8Array(), epochHash),
+      ),
+    )
+
+    // Timestamp: 8-byte big-endian
+    const timestamp = new Uint8Array(8)
+    const tsView = new DataView(timestamp.buffer)
+    tsView.setBigUint64(0, at, false) // big-endian
+
+    // Payload: timestamp + reference = 40 or 72 bytes
+    // The upload function will wrap this in a CAC (adding span) to get 48 or 80 bytes
+    // which is the v1 format Bee expects for /bzz/ compatibility
+    const payload = Binary.concatBytes(timestamp, reference)
+
+    const result = encryptionKey
+      ? await uploadEncryptedSOC(
+          this.bee,
+          stamper,
+          this.signer,
+          identifier,
+          payload,
+          encryptionKey,
+          { deferred: false }, // deferred setting is NOT the cause of /bzz/ timeout
+        )
+      : await uploadSOCViaSocEndpoint(
+          this.bee,
+          stamper,
+          this.signer,
+          identifier,
+          payload,
+          { deferred: false }, // deferred setting is NOT the cause of /bzz/ timeout
+        )
+
+    return result.socAddress
+  }
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Shared utilities for epoch feed finders
+ */
+
+import { EpochIndex } from "./epoch"
+
+const MAX_LEAF_BACKSCAN = 128n
+
+/**
+ * Type for the chunk fetcher callback used by findPreviousLeaf.
+ * This allows both sync and async finders to share the same logic.
+ */
+export type EpochChunkFetcher = (
+  at: bigint,
+  epoch: EpochIndex,
+) => Promise<Uint8Array | undefined>
+
+/**
+ * Find a previous leaf chunk by scanning backwards from the target timestamp.
+ *
+ * This is a recovery fallback for poisoned-ancestor histories where the tree
+ * traversal fails but valid leaf nodes exist.
+ *
+ * @param at - Target unix timestamp (seconds)
+ * @param after - Hint of latest known update timestamp (0 if unknown)
+ * @param getEpochChunk - Callback function to fetch epoch chunks
+ * @returns 32-byte Swarm reference, or undefined if no update found
+ */
+export async function findPreviousLeaf(
+  at: bigint,
+  after: bigint,
+  getEpochChunk: EpochChunkFetcher,
+): Promise<Uint8Array | undefined> {
+  if (at === 0n) {
+    return undefined
+  }
+
+  const minAt = after > 0n ? after : 0n
+  const lowerBound =
+    at > MAX_LEAF_BACKSCAN && at - MAX_LEAF_BACKSCAN > minAt
+      ? at - MAX_LEAF_BACKSCAN
+      : minAt
+
+  let probe = at - 1n
+  while (probe >= lowerBound) {
+    try {
+      const leaf = await getEpochChunk(at, new EpochIndex(probe, 0))
+      if (leaf) {
+        return leaf
+      }
+    } catch {
+      // Missing leaf at probe timestamp.
+    }
+
+    if (probe === 0n) {
+      break
+    }
+    probe--
+  }
+
+  return undefined
+}

package/src/proxy/feeds/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Feed utilities and implementations
+ */
+
+export * from "./epochs"

package/src/proxy/feeds/sequence/async-finder.ts

@@ -0,0 +1,31 @@
+/**
+ * Async Sequential Feed Finder
+ *
+ * Currently delegates to the sync finder to match Go behavior
+ * while keeping an async interface.
+ */
+
+import type {
+  Bee,
+  EthAddress,
+  Topic,
+  BeeRequestOptions,
+} from "@ethersphere/bee-js"
+import type { SequentialFinder, SequentialLookupResult } from "./types"
+import { SyncSequentialFinder } from "./finder"
+
+export class AsyncSequentialFinder implements SequentialFinder {
+  private readonly syncFinder: SyncSequentialFinder
+
+  constructor(bee: Bee, topic: Topic, owner: EthAddress) {
+    this.syncFinder = new SyncSequentialFinder(bee, topic, owner)
+  }
+
+  async findAt(
+    at: bigint,
+    after: bigint = 0n,
+    requestOptions?: BeeRequestOptions,
+  ): Promise<SequentialLookupResult> {
+    return this.syncFinder.findAt(at, after, requestOptions)
+  }
+}