@snaha/swarm-id 0.0.1

package/src/proxy/feed-manifest.ts

@@ -0,0 +1,174 @@
+import { MantarayNode, NULL_ADDRESS } from "@ethersphere/bee-js"
+import type {
+  Bee,
+  Stamper,
+  UploadOptions,
+  BeeRequestOptions,
+} from "@ethersphere/bee-js"
+import {
+  makeEncryptedContentAddressedChunk,
+  makeContentAddressedChunk,
+} from "../chunk"
+import { uint8ArrayToHex } from "../utils/hex"
+import { uploadSingleChunk } from "./upload-data"
+import { uploadSingleEncryptedChunk } from "./upload-encrypted-data"
+
+/**
+ * Options for creating a feed manifest
+ */
+export interface CreateFeedManifestOptions {
+  /**
+   * Whether to encrypt the manifest.
+   * Default: true (encrypted)
+   */
+  encrypt?: boolean
+  /**
+   * Feed type: "Sequence" for sequential feeds, "Epoch" for epoch feeds.
+   * Default: "Sequence"
+   */
+  feedType?: "Sequence" | "Epoch"
+}
+
+/**
+ * Result of creating a feed manifest
+ */
+export interface CreateFeedManifestResult {
+  /**
+   * Reference to the feed manifest.
+   * - Encrypted: 128 hex chars (64 bytes = address + encryption key)
+   * - Unencrypted: 64 hex chars (32 bytes = address)
+   */
+  reference: string
+  /**
+   * Tag UID if a tag was created during upload
+   */
+  tagUid?: number
+}
+
+/**
+ * Create a feed manifest directly using chunk upload
+ *
+ * Instead of using bee.createFeedManifest() which calls the /feeds endpoint,
+ * this function builds the manifest locally as a MantarayNode and uploads it
+ * via the encrypted chunk endpoint (or plain chunk endpoint if encrypt=false).
+ *
+ * Feed manifests have a single "/" path with metadata:
+ * - swarm-feed-owner: Owner's ethereum address (40 hex chars, no 0x)
+ * - swarm-feed-topic: Topic hash (64 hex chars)
+ * - swarm-feed-type: "Sequence" for sequential feeds
+ *
+ * IMPORTANT: This function implements client-side "saveRecursively" logic:
+ * 1. Upload the "/" child node first and get its address
+ * 2. Set the child's selfAddress to the uploaded address
+ * 3. Then upload the root node (which references the child's address)
+ *
+ * Without this, Bee's /bzz/ endpoint returns 404 because the "/" child chunk
+ * doesn't exist (only its calculated hash was stored in the root manifest).
+ *
+ * @param bee - Bee client instance
+ * @param stamper - Stamper for client-side signing
+ * @param topic - Topic hex string (64 chars)
+ * @param owner - Owner hex string (40 chars, no 0x prefix)
+ * @param options - Options for creating the manifest (encrypt, etc.)
+ * @param uploadOptions - Upload options (tag, deferred, etc.)
+ * @param requestOptions - Bee request options
+ * @returns Reference to the feed manifest
+ */
+export async function createFeedManifestDirect(
+  bee: Bee,
+  stamper: Stamper,
+  topic: string,
+  owner: string,
+  options?: CreateFeedManifestOptions,
+  uploadOptions?: UploadOptions,
+  requestOptions?: BeeRequestOptions,
+): Promise<CreateFeedManifestResult> {
+  // Normalize owner (remove 0x prefix if present)
+  const normalizedOwner = owner.startsWith("0x") ? owner.slice(2) : owner
+
+  // DEBUG: Log what Bee will use for feed lookup
+
+  // 1. Create tag for upload if not provided
+  let tag = uploadOptions?.tag
+  if (!tag) {
+    const tagResponse = await bee.createTag()
+    tag = tagResponse.uid
+  }
+  const uploadOptionsWithTag = { ...uploadOptions, tag }
+
+  // 2. Create root MantarayNode with "/" fork containing feed metadata
+  const rootNode = new MantarayNode()
+  rootNode.addFork("/", NULL_ADDRESS, {
+    "swarm-feed-owner": normalizedOwner,
+    "swarm-feed-topic": topic,
+    "swarm-feed-type": options?.feedType ?? "Sequence",
+  })
+
+  // 3. Get the "/" child node (addFork created it, we need to access it)
+  // 47 is ASCII code for '/'
+  const slashFork = rootNode.forks.get(47)
+  if (!slashFork) {
+    throw new Error("[FeedManifest] Failed to create '/' fork")
+  }
+  const slashNode = slashFork.node
+
+  // 4. Marshal and upload the "/" child node FIRST (saveRecursively pattern)
+  // This is critical: Bee's /bzz/ needs this chunk to exist
+  const slashNodeData = await slashNode.marshal()
+  const slashChunk = makeContentAddressedChunk(slashNodeData)
+
+  await uploadSingleChunk(
+    bee,
+    stamper,
+    slashChunk,
+    uploadOptionsWithTag,
+    requestOptions,
+  )
+
+  // 5. Set the child's selfAddress to the uploaded chunk address
+  // This is used when marshaling the root node
+  slashNode.selfAddress = slashChunk.address.toUint8Array()
+
+  // 6. Now marshal and upload the root node
+  const rootNodeData = await rootNode.marshal()
+
+  // 7. Encrypt and upload OR upload directly
+  const shouldEncrypt = options?.encrypt !== false
+
+  if (shouldEncrypt) {
+    // Encrypted upload for root
+    const encryptedChunk = makeEncryptedContentAddressedChunk(rootNodeData)
+
+    await uploadSingleEncryptedChunk(
+      bee,
+      stamper,
+      encryptedChunk,
+      uploadOptionsWithTag,
+      requestOptions,
+    )
+
+    // Return 64-byte reference (address + key)
+    const ref = new Uint8Array(64)
+    ref.set(encryptedChunk.address.toUint8Array(), 0)
+    ref.set(encryptedChunk.encryptionKey, 32)
+    const reference = uint8ArrayToHex(ref)
+
+    return { reference, tagUid: tag }
+  } else {
+    // Unencrypted upload for root
+    const rootChunk = makeContentAddressedChunk(rootNodeData)
+
+    await uploadSingleChunk(
+      bee,
+      stamper,
+      rootChunk,
+      uploadOptionsWithTag,
+      requestOptions,
+    )
+
+    // Return 32-byte reference
+    const reference = rootChunk.address.toHex()
+
+    return { reference, tagUid: tag }
+  }
+}

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

@@ -0,0 +1,372 @@
+/**
+ * Async Epoch Feed Finder (Concurrent)
+ *
+ * Concurrent implementation for finding feed updates at specific timestamps
+ * using epoch-based indexing with parallel chunk fetching.
+ */
+
+import { Binary } from "cafe-utility"
+import type { Bee, BeeRequestOptions } from "@ethersphere/bee-js"
+import { EthAddress, Reference, Topic } from "@ethersphere/bee-js"
+import { EpochIndex, MAX_LEVEL } from "./epoch"
+import type { EpochFinder, EpochLookupResult } from "./types"
+import { downloadEncryptedSOC } from "../../download-data"
+import { findPreviousLeaf } from "./utils"
+
+const EPOCH_LOOKUP_TIMEOUT_MS = 2000
+
+/**
+ * Async concurrent finder for epoch-based feeds
+ *
+ * Launches parallel chunk fetches along the epoch tree path
+ * to find the feed update valid at a specific timestamp.
+ *
+ * Implements the EpochFinder interface.
+ */
+export class AsyncEpochFinder implements EpochFinder {
+  constructor(
+    private readonly bee: Bee,
+    private readonly topic: Topic,
+    private readonly owner: EthAddress,
+    private readonly encryptionKey?: Uint8Array,
+  ) {}
+
+  /**
+   * 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 tree traversal.
+    }
+
+    // Start from top epoch and traverse down
+    const traversed = await this.findAtEpoch(
+      at,
+      new EpochIndex(0n, MAX_LEVEL),
+      undefined,
+    )
+    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
+  }
+
+  /**
+   * Recursively find update at epoch, with parallel fetching
+   *
+   * @param at - Target timestamp
+   * @param epoch - Current epoch to check
+   * @param currentBest - Best result found so far
+   * @returns Reference if found, undefined otherwise
+   */
+  private async findAtEpoch(
+    at: bigint,
+    epoch: EpochIndex,
+    currentBest: Uint8Array | undefined,
+  ): Promise<Uint8Array | undefined> {
+    // Try to get chunk at this epoch.
+    // getEpochChunk throws when chunk is missing, returns undefined when
+    // chunk exists but timestamp is invalid for `at`.
+    let chunk: Uint8Array | undefined
+    try {
+      chunk = await this.getEpochChunk(at, epoch)
+    } catch (error) {
+      // Chunk missing at this epoch.
+      if (epoch.isLeft()) {
+        return currentBest
+      }
+      return this.findAtEpoch(epoch.start - 1n, epoch.left(), currentBest)
+    }
+
+    // If chunk found and valid
+    if (chunk) {
+      // If at finest resolution, this is our answer
+      if (epoch.level === 0) {
+        return chunk
+      }
+
+      // Continue to finer resolution
+      return this.findAtEpoch(at, epoch.childAt(at), chunk)
+    }
+
+    // Chunk exists but timestamp invalid.
+    // Keep descending towards the target epoch first, because finer epochs
+    // may still contain a valid update.
+    if (epoch.level > 0) {
+      const down = await this.findAtEpoch(at, epoch.childAt(at), currentBest)
+      if (down) {
+        return down
+      }
+    }
+
+    if (epoch.isLeft()) {
+      // Left child - return best we have so far
+      return currentBest
+    }
+
+    // Right child - need to search left sibling branch
+    return this.findAtEpoch(epoch.start - 1n, epoch.left(), currentBest)
+  }
+  /**
+   * Fetch chunk for a specific epoch
+   *
+   * @param at - Target timestamp for validation
+   * @param epoch - Epoch to fetch
+   * @returns Chunk payload
+   * @throws Error if chunk not found
+   */
+  private async getEpochChunk(
+    at: bigint,
+    epoch: EpochIndex,
+  ): Promise<Uint8Array | undefined> {
+    const result = await this.getEpochChunkWithMetadata(at, epoch)
+    return result?.reference
+  }
+
+  /**
+   * Find the feed update valid at time `at` with full metadata
+   * Used by updater to calculate next epoch when no hints provided
+   *
+   * @param at - Target unix timestamp (seconds)
+   * @returns EpochLookupResult with reference, epoch, and timestamp, or undefined if no update found
+   */
+  async findAtWithMetadata(at: bigint): Promise<EpochLookupResult | undefined> {
+    // Fast path: exact timestamp updates are written at level-0
+    const exactEpoch = new EpochIndex(at, 0)
+    try {
+      const exact = await this.getEpochChunkWithMetadata(at, exactEpoch)
+      if (exact) {
+        return {
+          reference: exact.reference,
+          epoch: exactEpoch,
+          timestamp: exact.timestamp,
+        }
+      }
+    } catch {
+      // Ignore and fall back to tree traversal
+    }
+
+    // Start from top epoch and traverse down, tracking found epoch
+    return this.findAtEpochWithMetadata(
+      at,
+      new EpochIndex(0n, MAX_LEVEL),
+      undefined,
+    )
+  }
+
+  /**
+   * Recursively find update at epoch with full metadata tracking
+   *
+   * @param at - Target timestamp
+   * @param epoch - Current epoch to check
+   * @param currentBest - Best result found so far
+   * @returns EpochLookupResult if found, undefined otherwise
+   */
+  private async findAtEpochWithMetadata(
+    at: bigint,
+    epoch: EpochIndex,
+    currentBest: EpochLookupResult | undefined,
+  ): Promise<EpochLookupResult | undefined> {
+    // Try to get chunk at this epoch
+    let chunkData: { reference: Uint8Array; timestamp: bigint } | undefined
+    try {
+      chunkData = await this.getEpochChunkWithMetadata(at, epoch)
+    } catch (error) {
+      // Chunk missing at this epoch
+      if (epoch.isLeft()) {
+        return currentBest
+      }
+      return this.findAtEpochWithMetadata(
+        epoch.start - 1n,
+        epoch.left(),
+        currentBest,
+      )
+    }
+
+    // If chunk found and valid
+    if (chunkData) {
+      const result: EpochLookupResult = {
+        reference: chunkData.reference,
+        epoch,
+        timestamp: chunkData.timestamp,
+      }
+
+      // If at finest resolution, this is our answer
+      if (epoch.level === 0) {
+        return result
+      }
+
+      // Continue to finer resolution
+      return this.findAtEpochWithMetadata(at, epoch.childAt(at), result)
+    }
+
+    // Chunk exists but timestamp invalid
+    // Keep descending towards the target epoch first
+    if (epoch.level > 0) {
+      const down = await this.findAtEpochWithMetadata(
+        at,
+        epoch.childAt(at),
+        currentBest,
+      )
+      if (down) {
+        return down
+      }
+    }
+
+    if (epoch.isLeft()) {
+      return currentBest
+    }
+
+    // Right child - need to search left sibling branch
+    return this.findAtEpochWithMetadata(
+      epoch.start - 1n,
+      epoch.left(),
+      currentBest,
+    )
+  }
+
+  /**
+   * Fetch chunk for a specific epoch and return full metadata
+   *
+   * @param at - Target timestamp for validation
+   * @param epoch - Epoch to fetch
+   * @returns Object with reference and timestamp, or undefined if timestamp > at
+   * @throws Error if chunk not found
+   */
+  private async getEpochChunkWithMetadata(
+    at: bigint,
+    epoch: EpochIndex,
+  ): Promise<{ reference: Uint8Array; timestamp: bigint } | 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),
+    )
+
+    let payload: Uint8Array
+    if (this.encryptionKey) {
+      const soc = await downloadEncryptedSOC(
+        this.bee,
+        this.owner,
+        identifier,
+        this.encryptionKey,
+        requestOptions,
+      )
+      payload = soc.payload
+    } else {
+      // 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)
+      const IDENTIFIER_SIZE = 32
+      const SIGNATURE_SIZE = 65
+      const SPAN_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
+      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 TIMESTAMP_SIZE = 8
+    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 and timestamp (skip timestamp and optional span prefix)
+    return {
+      reference: payload.slice(timestampOffset + TIMESTAMP_SIZE),
+      timestamp,
+    }
+  }
+
+  private findPreviousLeaf(
+    at: bigint,
+    after: bigint,
+  ): Promise<Uint8Array | undefined> {
+    return findPreviousLeaf(at, after, (targetAt, epoch) =>
+      this.getEpochChunk(targetAt, epoch),
+    )
+  }
+}