@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

package/dist/proxy/manifest-builder.d.ts

@@ -0,0 +1,164 @@
+import { MantarayNode } from "@ethersphere/core-sdk";
+/**
+ * Result of building a /bzz/-compatible manifest.
+ *
+ * This is a FLAT manifest with no child nodes - just the root manifest.
+ * Bee's /bzz/ endpoint can directly resolve paths from this structure.
+ *
+ * IMPORTANT: The `data` field contains RAW manifest bytes (without span prefix).
+ * When uploaded via `uploadData()`, span will be added and the resulting address
+ * will match the pre-computed `address` field.
+ */
+export interface BzzCompatibleManifestResult {
+    /** The manifest chunk to upload. Raw bytes, no span. */
+    manifestChunk: {
+        data: Uint8Array;
+        address: string;
+    };
+}
+/**
+ * Build a /bzz/-compatible flat manifest with VALUE forks.
+ *
+ * Creates a flat manifest with two VALUE forks at root level:
+ * - "/" → VALUE fork with website-index-document metadata pointing to NULL
+ * - "index.bin" → VALUE fork pointing directly to content reference
+ *
+ * This is built manually because bee-js MantarayNode always creates EDGE forks
+ * with child nodes, which causes Bee to fail to resolve the content.
+ *
+ * When Bee accesses /bzz/manifest/:
+ * 1. Finds "/" fork, reads website-index-document metadata
+ * 2. Looks up "index.bin" fork at root level
+ * 3. "index.bin" is VALUE type → serves content directly
+ *
+ * Binary format (Mantaray v0.2):
+ * - obfuscationKey (32 bytes): All zeros for no obfuscation
+ * - versionHash (31 bytes): MANTARAY_VERSION_HASH
+ * - refBytesCount (1 byte): 32
+ * - entry (32 bytes): All zeros (root has no entry)
+ * - indexBitmap (32 bytes): Bits set for '/' (47) and 'i' (105)
+ * - fork1 (64+ bytes): "/" fork with metadata
+ * - fork2 (64+ bytes): "index.bin" fork with metadata
+ *
+ * @param contentReference - Reference to the actual content (32 bytes / 64 hex chars)
+ * @returns Single manifest chunk to upload
+ */
+export declare function buildBzzCompatibleManifest(contentReference: string | Uint8Array): Promise<BzzCompatibleManifestResult>;
+/**
+ * Result of building a /bzz/-compatible MantarayNode manifest.
+ */
+export interface BzzManifestNodeResult {
+    /** The MantarayNode to be uploaded with saveMantarayTreeRecursively */
+    manifestNode: MantarayNode;
+}
+/**
+ * Build a /bzz/-compatible manifest as a MantarayNode.
+ *
+ * This function creates a MantarayNode with the proper structure for /bzz/ access:
+ * - "/" fork with website-index-document metadata pointing to "index.bin"
+ * - "index.bin" fork pointing to the actual content reference
+ *
+ * IMPORTANT: After calling this function, use saveMantarayTreeRecursively() to
+ * upload the manifest. This ensures all child nodes are uploaded bottom-up and
+ * their addresses are correctly set from Bee's responses.
+ *
+ * Usage:
+ * ```typescript
+ * const { manifestNode } = buildBzzManifestNode(contentReference)
+ * const result = await saveMantarayTreeRecursively(manifestNode, async (data, isRoot) => {
+ *   const uploadResult = await uploadData(bee, stamper, data, uploadOptions)
+ *   return { reference: uploadResult.reference }
+ * })
+ * // result.rootReference is the /bzz/ compatible manifest address
+ * ```
+ *
+ * @param contentReference - Reference to the actual content (32 bytes / 64 hex chars)
+ * @returns MantarayNode ready for upload with saveMantarayTreeRecursively
+ */
+export declare function buildBzzManifestNode(contentReference: string | Uint8Array): BzzManifestNodeResult;
+/**
+ * @deprecated Use buildBzzManifestNode() with saveMantarayTreeRecursively() instead.
+ * This function manually builds binary format but doesn't upload child nodes,
+ * which causes Bee to fail to resolve content via /bzz/.
+ */
+/**
+ * @deprecated Use buildBzzCompatibleManifest() for /bzz/ compatibility.
+ * This function creates a manifest that won't work with Bee's /bzz/ endpoint
+ * because it embeds the content reference directly in the manifest instead
+ * of using the proper two-level structure (root → child → content).
+ *
+ * Build a minimal mantaray manifest for /bzz/ feed compatibility.
+ *
+ * This creates a manifest with a single "/" fork pointing to a content reference.
+ * The manifest is built manually (not using bee-js MantarayNode.marshal()) because
+ * bee-js doesn't embed the targetAddress correctly for value-type nodes.
+ *
+ * Binary format (Mantaray v0.2):
+ * - obfuscationKey (32 bytes): All zeros for no obfuscation
+ * - versionHash (31 bytes): MANTARAY_VERSION_HASH
+ * - refBytesCount (1 byte): 32 (size of entry reference)
+ * - entry (32 bytes): All zeros (root has no entry)
+ * - indexBitmap (32 bytes): Bitmap with bit 47 set (for '/')
+ * - fork (64+ bytes): flags + prefixLen + prefix(30) + reference(32) + metadata
+ *
+ * @param contentReference - Reference to the actual content (32 bytes / 64 hex chars)
+ * @returns Marshaled manifest bytes
+ */
+export declare function buildMinimalManifest(contentReference: string | Uint8Array): Uint8Array;
+/**
+ * Extract content reference from a minimal mantaray manifest.
+ *
+ * This is the reverse of buildMinimalManifest() - it parses the manifest
+ * binary format and extracts the "/" fork's targetAddress.
+ *
+ * Binary format (Mantaray v0.2):
+ * - Offset 0-31: obfuscationKey
+ * - Offset 32-62: versionHash (31 bytes)
+ * - Offset 63: refBytesCount
+ * - Offset 64-95: entry (refBytesCount bytes, assuming 32)
+ * - Offset 96-127: indexBitmap
+ * - Offset 128+: forks (flags + prefixLen + prefix + reference + metadata)
+ *
+ * For a minimal manifest with just "/" fork:
+ * - Fork flags at offset 128
+ * - Prefix length at offset 129
+ * - Prefix (30 bytes) at offset 130
+ * - Reference (32 bytes) at offset 160
+ *
+ * @param manifestData - Raw manifest bytes (from feed payload)
+ * @returns Content reference as 64 hex characters
+ */
+export declare function extractReferenceFromManifest(manifestData: Uint8Array): string;
+/**
+ * Extract entry (targetAddress) from a leaf manifest node.
+ *
+ * In Mantaray v0.2, leaf nodes store their targetAddress in the entry field
+ * (bytes 64-95), not in a fork. This is used for the second level of parsing
+ * when using buildBzzCompatibleManifest().
+ *
+ * Binary format (Mantaray v0.2):
+ * - Offset 0-31:   obfuscationKey
+ * - Offset 32-62:  versionHash (31 bytes)
+ * - Offset 63:     refBytesCount
+ * - Offset 64-95:  entry (32 bytes) ← targetAddress for leaf nodes
+ * - Offset 96-127: indexBitmap
+ * - Offset 128+:   forks
+ *
+ * @param manifestData - Raw manifest bytes (child chunk data from two-level structure)
+ * @returns Content reference as 64 hex characters
+ */
+export declare function extractEntryFromManifest(manifestData: Uint8Array): string;
+/**
+ * Extract content reference from a flat /bzz/-compatible manifest.
+ *
+ * In the flat structure, the manifest has:
+ * - "/" fork with NULL_ADDRESS and website-index-document metadata
+ * - "index.bin" fork with VALUE type pointing to content reference
+ *
+ * This function looks for the "index.bin" fork ('i' = ASCII 105) and
+ * extracts its reference.
+ *
+ * @param manifestData - Raw manifest bytes (flat manifest)
+ * @returns Content reference as 64 hex characters
+ */
+export declare function extractContentFromFlatManifest(manifestData: Uint8Array): string;

package/dist/proxy/mantaray.d.ts

@@ -0,0 +1,76 @@
+import { MantarayNode } from "@ethersphere/core-sdk";
+import type { Bee, BeeRequestOptions } from "@ethersphere/bee-js";
+/**
+ * Upload callback type for saveMantarayTreeRecursively
+ */
+export type UploadCallback = (data: Uint8Array, isRoot: boolean) => Promise<{
+    reference: string;
+    tagUid?: number;
+}>;
+/**
+ * Save a Mantaray tree by uploading bottom-up
+ *
+ * This mirrors MantarayNode.saveRecursively() but allows custom upload logic
+ * and uses Bee's returned references to avoid address mismatches.
+ *
+ * This is the variant that is safe to use from outside the proxy: the callback
+ * receives a marshaled node payload and hands back the reference it was stored
+ * under, so any uploader that wraps a payload in a chunk of its own fits.
+ * `SwarmIdClient.uploadData` is the one to reach for — `uploadChunk` fits the
+ * contract too, but a node payload over its 4 KB chunk limit (a wide directory)
+ * fails there, which is why the demo's feed upload uses `uploadData`.
+ */
+export declare function saveMantarayTreeRecursively(node: MantarayNode, uploadFn: UploadCallback): Promise<{
+    rootReference: string;
+    tagUid?: number;
+}>;
+/**
+ * Options for saveMantarayTree
+ */
+export interface SaveMantarayOptions {
+    /** Encrypt manifest chunks (64-byte references with address + key) */
+    encrypt?: boolean;
+}
+/**
+ * Upload callback for saveMantarayTree
+ *
+ * @param chunkData - A finished content-addressed chunk, span header included;
+ *   it must be stored exactly as given, not wrapped in another chunk
+ * @param isRoot - Whether this is the root node
+ * @returns Upload result with optional tag UID
+ */
+export type MantarayUploadCallback = (chunkData: Uint8Array, isRoot: boolean) => Promise<{
+    tagUid?: number;
+}>;
+/**
+ * Save a Mantaray tree by uploading bottom-up with unified encryption support
+ *
+ * Proxy-internal, and deliberately not part of the package's public API.
+ *
+ * Creates CAC or encrypted CAC internally based on encrypt option.
+ * Returns 64-byte reference (address + key) when encrypted, 32-byte otherwise.
+ *
+ * `uploadFn` receives a finished content-addressed chunk built here, span
+ * header included, and each node's address is computed locally from those same
+ * bytes. The callback must therefore store them as-is: an uploader that treats
+ * its argument as a payload and wraps it in a new chunk stores every node under
+ * a different address than the tree records, which fails silently and leaves the
+ * returned root reference pointing at nothing. `SwarmIdClient.uploadChunk` wraps
+ * its input that way and cannot be used here; no public client method accepts a
+ * finished chunk. Outside the proxy, use `saveMantarayTreeRecursively` instead.
+ *
+ * @param node - Root Mantaray node to save
+ * @param uploadFn - Callback that uploads each finished chunk verbatim
+ * @param options - Optional settings (encrypt: boolean)
+ * @returns Root reference and optional tag UID
+ */
+export declare function saveMantarayTree(node: MantarayNode, uploadFn: MantarayUploadCallback, options?: SaveMantarayOptions): Promise<{
+    rootReference: string;
+    tagUid?: number;
+}>;
+/**
+ * Load a Mantaray tree using only the chunk API.
+ *
+ * This avoids /bytes and supports encrypted references.
+ */
+export declare function loadMantarayTreeWithChunkAPI(bee: Bee, rootReference: string, requestOptions?: BeeRequestOptions): Promise<MantarayNode>;

package/dist/proxy/soc-restamp-slots.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Which slot each single-owner chunk an app had stamped went to. A chat sends
+ * every message as a new version of one inbox chunk, whose address never
+ * changes, and a mutable batch replaces a chunk stamped at the same slot with
+ * a newer timestamp. So stamping that address again reuses its slot instead
+ * of filling the bucket. The record is per app origin and per stamp, in the
+ * frame's own storage, and belongs to one lane of the stamp: when this device
+ * holds another lane the record starts empty, and a new slot is taken.
+ */
+import { z } from "zod";
+/** Single-owner chunk addresses remembered per app and stamp. Past it a new address takes a new slot each time */
+export declare const SOC_RESTAMP_SLOT_LIMIT = 256;
+/** One lane of the stamp: this device's partition and the account's partition count */
+export interface StampLane {
+    partition: number;
+    partitionCount: number;
+}
+declare const SocRestampSlotsSchema: z.ZodObject<{
+    partition: z.ZodNumber;
+    partitionCount: z.ZodNumber;
+    slots: z.ZodRecord<z.ZodString, z.ZodObject<{
+        slot: z.ZodNumber;
+        timestampMs: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The slots one app's single-owner chunks hold in one lane of one stamp */
+export type SocRestampSlots = z.infer<typeof SocRestampSlotsSchema>;
+export declare function emptySocRestampSlots(lane: StampLane): SocRestampSlots;
+/**
+ * The stored record for `lane`, or an empty one when there is none, it
+ * belongs to another lane, or it is malformed. Only the frame writes it, so a
+ * malformed one is a bug of ours and starts over, which only costs new slots.
+ */
+export declare function parseSocRestampSlots(raw: string | null, lane: StampLane): SocRestampSlots;
+/**
+ * The record once `addressHex` holds `slot` with a stamp at `timestampMs`.
+ * Unchanged when the record is full and the address is new.
+ */
+export declare function recordSocSlot(record: SocRestampSlots, addressHex: string, slot: number, timestampMs: number): SocRestampSlots;
+/**
+ * The timestamp for a stamp again at a slot whose last stamp had
+ * `previousMs`. Bee keeps the chunk with the newer stamp, so when the clock
+ * went back it is one millisecond past the last rather than now.
+ */
+export declare function restampTimestamp(previousMs: number, now: number): number;
+/** The slot in a stamp's 8-byte index, which is the bucket then the slot, big-endian */
+export declare function slotOfStampIndex(index: Uint8Array): number;
+export {};

package/dist/proxy/stamp-chunk.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Stamp and return: the frame stamps a chunk with the account's own stamp
+ * and hands the stamp back, so the app sends the chunk through the Swarm
+ * access it chose. The app sends the whole chunk and the frame computes its
+ * address, so a stamp is only ever issued for bytes the frame has seen, and a
+ * single-owner chunk is only ever one the frame signed in the same request.
+ */
+import { EthAddress } from "@ethersphere/bee-js";
+import type { EnvelopeWithBatchId, Signature } from "@ethersphere/bee-js";
+import type { StampChunkRequest } from "../types";
+/** What the frame stamps: the address it computed, and a SOC's owner and signature */
+export interface ChunkToStamp {
+    address: Uint8Array;
+    owner?: EthAddress;
+    signature?: Signature;
+}
+/** The account keys the internal owners are derived from */
+export interface InternalOwnerKeys {
+    /** The account's own address */
+    accountAddress: string;
+    derivationKey: string;
+    /** The resolved stamp's signer, which an imported stamp may not derive */
+    postageSignerKey?: string;
+}
+/**
+ * Every owner address the account's own chunks may carry, lowercase hex. A
+ * single-owner chunk owned by one of these is refused, so an app can never be
+ * handed a stamp for the account's lock, partition state, device state or
+ * roster chunks (owned by the backup signer), nor sign as any other key the
+ * frame holds for the account.
+ */
+export declare function accountInternalOwners(keys: InternalOwnerKeys): Set<string>;
+/**
+ * Compute the address of the chunk to stamp, and sign it when it is a
+ * single-owner chunk.
+ *
+ * @throws SwarmIdError `invalid-request` for a chunk of the wrong length, or a
+ *   single-owner chunk whose owner is one of `internalOwners`
+ */
+export declare function prepareChunkToStamp(chunk: StampChunkRequest, context: {
+    appSecret: string;
+    internalOwners: ReadonlySet<string>;
+}): ChunkToStamp;
+/** A stamp in the form Bee's `swarm-postage-stamp` upload header takes */
+export declare function marshalStamp(envelope: EnvelopeWithBatchId): string;

package/dist/proxy/stamp-worker-handler.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Message types for main thread ↔ worker communication.
+ */
+export interface StampWorkerInitMessage {
+    type: "init";
+    signerKeyHex: string;
+}
+export interface StampWorkerSignMessage {
+    type: "sign";
+    id: number;
+    message: Uint8Array;
+}
+export interface StampWorkerReadyResponse {
+    type: "ready";
+    issuerHex: string;
+}
+export interface StampWorkerSignedResponse {
+    type: "signed";
+    id: number;
+    signatureHex: string;
+}
+export type StampWorkerMessage = StampWorkerInitMessage | StampWorkerSignMessage;
+export type StampWorkerResponse = StampWorkerReadyResponse | StampWorkerSignedResponse;
+/**
+ * Handle an incoming message from the main thread.
+ *
+ * Replicates core-sdk's `PrivateKey.sign()`:
+ *   1. digest = concat(ETH_PREFIX, keccak256(message))
+ *   2. [r, s, v] = Elliptic.signMessage(digest, privateKey)
+ *   3. signature = concat(r[32], s[32], v[1])
+ */
+export declare function handleMessage(msg: StampWorkerMessage): StampWorkerResponse;

package/dist/proxy/stamp-worker-pool.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Web Worker pool for parallel stamp signing.
+ *
+ * Architecture:
+ * - Main thread: slot assignment (fast, stateful, sequential)
+ * - Workers: ECDSA signing (slow, stateless, parallel)
+ *
+ * The pool only signs. The slot comes from the stamper it was created for — a
+ * `SlotAssigner`'s `assignSlot()`, or a plain core-sdk `Stamper`'s `buckets` —
+ * so a pooled stamp lands where `stamper.stamp()` would have put it.
+ */
+import type { Stamper, EnvelopeWithBatchId } from "@ethersphere/bee-js";
+import type { SlotAssigner } from "../utils/batch-utilization";
+export declare class StampWorkerPool {
+    private workers;
+    private nextWorker;
+    private nextId;
+    private issuer;
+    private batchId;
+    private assignSlot;
+    readonly size: number;
+    /** The stamper this pool signs for: a pool must not outlive it. */
+    readonly stamper: Stamper | SlotAssigner;
+    private constructor();
+    /**
+     * Create a worker pool from an existing stamper.
+     *
+     * @param signerKeyHex - Signer private key as hex (proxy already has this)
+     * @param stamper - Stamper the pool signs for; it stays the slot owner
+     * @param workerCount - Number of workers (defaults to 4)
+     */
+    static create(signerKeyHex: string, stamper: Stamper | SlotAssigner, workerCount?: number): Promise<StampWorkerPool>;
+    /**
+     * Stamp a chunk address using parallel worker signing.
+     *
+     * Slot assignment happens on the main thread, before the first await, so
+     * concurrent calls cannot interleave inside it. ECDSA signing is dispatched
+     * to a worker (slow, parallel).
+     *
+     * Takes the same `timestampMs` as core-sdk's `Stamper.stamp`, and produces
+     * the same envelope for the same inputs — `stamp-worker-pool.test.ts` holds
+     * the two to that, field by field.
+     */
+    stampChunkData(address: Uint8Array, timestampMs?: number): Promise<EnvelopeWithBatchId>;
+    private dispatchSign;
+    /**
+     * Terminate all workers and release resources. Signs still in flight are
+     * rejected: a terminated worker never answers, and an upload awaiting one
+     * would hang.
+     */
+    terminate(): void;
+}

package/dist/proxy/stamp-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/proxy/types.d.ts

@@ -0,0 +1,38 @@
+import type { Bee, Stamper } from "@ethersphere/bee-js";
+import type { StampWorkerPool } from "./stamp-worker-pool";
+/**
+ * Upload context shared across handlers
+ */
+export interface UploadContext {
+    bee: Bee;
+    stamper: Stamper;
+    workerPool?: StampWorkerPool;
+}
+/**
+ * Upload progress information
+ */
+export interface UploadProgress {
+    total: number;
+    processed: number;
+}
+/**
+ * Chunk reference (32-byte address)
+ */
+export interface ChunkReference {
+    address: Uint8Array;
+    span?: bigint;
+}
+/**
+ * Encrypted chunk reference (64-byte reference: address + encryption key)
+ */
+export interface EncryptedChunkReference {
+    address: Uint8Array;
+    key: Uint8Array;
+}
+/**
+ * Options for WebSocket-based chunk upload
+ */
+export interface WebSocketUploadOptions {
+    /** WebSocket concurrency (in-flight chunks). Defaults to 32. */
+    concurrency?: number;
+}

package/dist/proxy/upload.d.ts

@@ -0,0 +1,207 @@
+import { Reference, PrivateKey, Identifier } from "@ethersphere/bee-js";
+import type { Bee, BeeRequestOptions, Stamper, UploadOptions, EnvelopeWithBatchId } from "@ethersphere/bee-js";
+import { type ContentAddressedChunk, type EncryptedChunk } from "../chunk";
+import type { ChunkReference, UploadProgress } from "./types";
+import type { StampWorkerPool } from "./stamp-worker-pool";
+/**
+ * Thrown when a SOC upload gets a non-OK HTTP response. Carries the numeric
+ * `status` so callers can distinguish a definitive stamp rejection (400) from a
+ * transient / not-yet-synced condition (404 "batch not found", 422 "not usable
+ * yet") without regex-matching the message — see `verifyBatchStampable`.
+ */
+export declare class SocUploadError extends Error {
+    readonly status: number;
+    /** What the node or gateway answered, for the bridge's `beeMessage` (#761) */
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+/**
+ * Upload target: stamper-based (user has postage batch) or subsidised gateway
+ */
+export type UploadTarget = {
+    mode: "stamper";
+    bee: Bee;
+    stamper: Stamper;
+    workerPool?: StampWorkerPool;
+} | {
+    mode: "subsidised";
+    gatewayUrl: string;
+};
+/**
+ * Type guard for stamper target
+ */
+export declare function isStamperTarget(target: UploadTarget): target is UploadTarget & {
+    mode: "stamper";
+};
+/**
+ * Type guard for subsidised target
+ */
+export declare function isSubsidisedTarget(target: UploadTarget): target is UploadTarget & {
+    mode: "subsidised";
+};
+/**
+ * Unified options for data upload
+ */
+export interface UploadDataOptions {
+    /**
+     * Encryption key: undefined = plain, Uint8Array = use this key, true =
+     * auto-generate. An explicit key only applies to single-chunk data
+     * (≤ 4096 bytes); larger data throws — pass true instead.
+     */
+    encryptionKey?: Uint8Array | true;
+    /** Pin the uploaded data (stamper mode only; a subsidised gateway never sees it, #752) */
+    pin?: boolean;
+    /** Use deferred upload mode */
+    deferred?: boolean;
+    /** Tag for tracking upload progress */
+    tag?: number;
+    /** WebSocket upload options (stamper mode only) */
+    webSocket?: {
+        concurrency?: number;
+    };
+    /** HTTP concurrency for parallel uploads */
+    httpConcurrency?: number;
+    /** Progress callback */
+    onProgress?: (progress: UploadProgress) => void;
+    /** Bee request options (stamper mode only) */
+    requestOptions?: BeeRequestOptions;
+}
+/**
+ * Result of uploading data
+ */
+export interface UploadDataResult {
+    /** Reference to the uploaded data (32-byte hex for plain, 64-byte for encrypted) */
+    reference: string;
+    /** Tag UID if one was created */
+    tagUid?: number;
+    /** Addresses of all uploaded chunks (encrypted mode only) */
+    chunkAddresses?: Uint8Array[];
+}
+/**
+ * Options for SOC upload
+ */
+export interface UploadSOCOptions {
+    /** Encryption key: undefined = plain SOC, Uint8Array = use this key, true = auto-generate */
+    encryptionKey?: Uint8Array | true;
+    /** Pin the uploaded SOC (stamper mode only; a subsidised gateway never sees it, #752) */
+    pin?: boolean;
+    /** Use deferred upload mode */
+    deferred?: boolean;
+    /** Tag for tracking */
+    tag?: number;
+    /** Bee request options (stamper mode only) */
+    requestOptions?: BeeRequestOptions;
+}
+/**
+ * Result of uploading a SOC
+ */
+export interface UploadSOCResult {
+    /** SOC address (32 bytes) */
+    socAddress: Uint8Array;
+    /** Encryption key (only for encrypted SOCs) */
+    encryptionKey?: Uint8Array;
+    /** Tag UID if one was created */
+    tagUid?: number;
+}
+/**
+ * Options for single chunk upload
+ */
+export interface UploadChunkOptions {
+    /** Pin the uploaded chunk (stamper mode only; a subsidised gateway never sees it, #752) */
+    pin?: boolean;
+    /** Use deferred upload mode */
+    deferred?: boolean;
+    /** Tag for tracking */
+    tag?: number;
+    /** Bee request options (stamper mode only) */
+    requestOptions?: BeeRequestOptions;
+}
+/**
+ * Result of uploading a chunk
+ */
+export interface UploadChunkResult {
+    /** Chunk reference (address) */
+    reference: string;
+}
+/**
+ * Async stamp function - abstraction over sync Stamper and parallel StampWorkerPool.
+ */
+type StampChunkFn = (address: Uint8Array) => Promise<EnvelopeWithBatchId>;
+/**
+ * Create a StampChunkFn from a Stamper and optional worker pool.
+ */
+declare function makeStampFn(stamper: Stamper, workerPool?: StampWorkerPool): StampChunkFn;
+interface EncryptedChunkRef {
+    address: Uint8Array;
+    key: Uint8Array;
+    span: bigint;
+}
+/**
+ * Encrypt all payloads into EncryptedChunks and collect their references.
+ *
+ * An explicit key is only valid for a single payload: every chunk of a
+ * multi-chunk upload carries its own key, so honouring one shared key is
+ * impossible and substituting random keys would silently break the caller's
+ * expectation of a key-addressed reference.
+ */
+declare function encryptChunkPayloads(payloads: Uint8Array[], encryptionKey?: Uint8Array): {
+    chunks: EncryptedChunk[];
+    refs: EncryptedChunkRef[];
+};
+/**
+ * Upload a single stamped chunk via HTTP (stamper mode).
+ */
+declare function uploadStampedChunkViaHttp(bee: Bee, stamp: StampChunkFn, chunkData: Uint8Array, address: Uint8Array, options: UploadOptions, requestOptions?: BeeRequestOptions): Promise<void>;
+/**
+ * Upload a chunk via subsidised gateway (no stamp required).
+ */
+declare function uploadChunkViaSubsidisedGatewayInternal(gatewayUrl: string, chunkData: Uint8Array, options?: {
+    deferred?: boolean;
+}): Promise<{
+    reference: string;
+}>;
+/**
+ * Build merkle tree from plain chunk references.
+ * Returns 32-byte root reference.
+ */
+declare function buildPlainMerkleTree(chunkRefs: ChunkReference[], uploadIntermediate: (chunk: ContentAddressedChunk) => Promise<void>): Promise<Reference>;
+/**
+ * Build merkle tree from encrypted chunk references.
+ * Returns 64-byte root reference (address + encryption key).
+ */
+declare function buildEncryptedMerkleTree(refs: EncryptedChunkRef[], uploadIntermediate: (chunkData: Uint8Array) => Promise<void>): Promise<Reference>;
+/**
+ * Upload data to Swarm.
+ *
+ * This is the unified entry point for all data uploads:
+ * - Plain or encrypted (via encryptionKey option)
+ * - Stamper-based or subsidised gateway (via target)
+ * - HTTP or WebSocket transport (via webSocket option)
+ *
+ * @param target - Upload target (stamper or subsidised gateway)
+ * @param data - Data to upload
+ * @param options - Upload options
+ * @returns Upload result with reference
+ */
+export declare function uploadData(target: UploadTarget, data: Uint8Array, options?: UploadDataOptions): Promise<UploadDataResult>;
+/**
+ * Upload a Single Owner Chunk (SOC).
+ *
+ * @param target - Upload target (stamper or subsidised gateway)
+ * @param signer - Private key for signing the SOC
+ * @param identifier - SOC identifier
+ * @param data - Chunk payload (1-4096 bytes)
+ * @param options - Upload options
+ * @returns SOC address and optional encryption key
+ */
+export declare function uploadSOC(target: UploadTarget, signer: PrivateKey, identifier: Identifier, data: Uint8Array, options?: UploadSOCOptions): Promise<UploadSOCResult>;
+/**
+ * Upload a single pre-built chunk.
+ *
+ * @param target - Upload target (stamper or subsidised gateway)
+ * @param chunkData - Full chunk data (span + payload)
+ * @param options - Upload options
+ * @returns Chunk reference
+ */
+export declare function uploadChunk(target: UploadTarget, chunkData: Uint8Array, options?: UploadChunkOptions): Promise<UploadChunkResult>;
+export { uploadChunkViaSubsidisedGatewayInternal, uploadStampedChunkViaHttp, makeStampFn, buildPlainMerkleTree, buildEncryptedMerkleTree, encryptChunkPayloads, type EncryptedChunkRef, type StampChunkFn, };