@ethersphere/bee-js 10.2.0 → 10.3.0

package/dist/mjs/bee.js

@@ -1,6 +1,6 @@
 import { Binary, Objects, System, Types } from 'cafe-utility';
-import { makeContentAddressedChunk } from "./chunk/cac.js";
-import { downloadSingleOwnerChunk, makeSOCAddress, makeSingleOwnerChunk, uploadSingleOwnerChunkData } from "./chunk/soc.js";
+import { makeContentAddressedChunk, unmarshalContentAddressedChunk } from "./chunk/cac.js";
+import { downloadSingleOwnerChunk, makeSOCAddress, makeSingleOwnerChunk, unmarshalSingleOwnerChunk, uploadSingleOwnerChunkData } from "./chunk/soc.js";
 import { makeFeedReader, makeFeedWriter } from "./feed/index.js";
 import { areAllSequentialFeedsUpdateRetrievable } from "./feed/retrievable.js";
 import * as bytes from "./modules/bytes.js";
@@ -37,7 +37,7 @@ import { ResourceLocator } from "./utils/resource-locator.js";
 import { getAmountForDuration, getDepthForSize, getStampCost } from "./utils/stamps.js";
 import { BZZ, DAI } from "./utils/tokens.js";
 import { asNumberString, assertData, assertFileData, makeTagUid, prepareAllTagsOptions, prepareBeeRequestOptions, prepareCollectionUploadOptions, prepareDownloadOptions, prepareFileUploadOptions, prepareGsocMessageHandler, preparePostageBatchOptions, preparePssMessageHandler, prepareRedundantUploadOptions, prepareTransactionOptions, prepareUploadOptions } from "./utils/type.js";
-import { BatchId, EthAddress, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Span, Topic, TransactionId } from "./utils/typed-bytes.js";
+import { BatchId, EthAddress, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Signature, Span, Topic, TransactionId } from "./utils/typed-bytes.js";
 import { assertBeeUrl, stripLastSlash } from "./utils/url.js";
 /**
  * The main component that abstracts operations available on the Bee API.
@@ -158,7 +158,7 @@ export class Bee {
    * Chunks uploaded with this method should be retrieved with the {@link downloadChunk} method.
    *
    * @param stamp Postage Batch ID or an Envelope created with the {@link createEnvelope} method.
-   * @param data    Raw chunk to be uploaded
+   * @param data    Raw chunk to be uploaded (Content Addressed Chunk or Single Owner Chunk)
    * @param options Additional options like tag, encryption, pinning, content-type and request options
    * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
    *
@@ -167,6 +167,7 @@ export class Bee {
    * @see [Bee API reference - `POST /chunks`](https://docs.ethswarm.org/api/#tag/Chunk/paths/~1chunks/post)
    */
   async uploadChunk(stamp, data, options, requestOptions) {
+    const isSOC = 'identifier' in data && 'signature' in data && 'owner' in data;
     data = data instanceof Uint8Array ? data : data.data;
     if (options) {
       options = prepareUploadOptions(options);
@@ -174,8 +175,11 @@ export class Bee {
     if (data.length < Span.LENGTH) {
       throw new BeeArgumentError(`Chunk has to have size of at least ${Span.LENGTH}.`, data);
     }
-    if (data.length > CHUNK_SIZE + Span.LENGTH) {
-      throw new BeeArgumentError(`Chunk has to have size of at most ${CHUNK_SIZE + Span.LENGTH}.`, data);
+    if (!isSOC && data.length > CHUNK_SIZE + Span.LENGTH) {
+      throw new BeeArgumentError(`Content Addressed Chunk must not exceed ${CHUNK_SIZE + Span.LENGTH} bytes.`, data);
+    }
+    if (isSOC && data.length > CHUNK_SIZE + Span.LENGTH + Signature.LENGTH + Identifier.LENGTH) {
+      throw new BeeArgumentError(`Single Owner Chunk must not exceed ${CHUNK_SIZE + Span.LENGTH + Signature.LENGTH + Identifier.LENGTH} bytes.`, data);
     }
     return chunk.upload(this.getRequestOptionsForCall(requestOptions), data, stamp, options);
   }
@@ -810,7 +814,7 @@ export class Bee {
     signer = new PrivateKey(signer);
     identifier = new Identifier(identifier);
     const cac = makeContentAddressedChunk(data);
-    const soc = makeSingleOwnerChunk(cac, identifier, signer);
+    const soc = cac.toSingleOwnerChunk(identifier, signer);
     return gsoc.send(this.getRequestOptionsForCall(requestOptions), soc, postageBatchId, options);
   }
   /**
@@ -940,6 +944,70 @@ export class Bee {
     owner = new EthAddress(owner);
     return fetchLatestFeedUpdate(this.getRequestOptionsForCall(requestOptions), owner, topic);
   }
+  /**
+   * Creates a Content Addressed Chunk.
+   *
+   * To be uploaded with the {@link uploadChunk} method.
+   *
+   * Payload size must be between 1 and 4096 bytes.
+   *
+   * @param rawPayload Data to be stored in the chunk. If the data is a string, it will be converted to UTF-8 bytes.
+   * @param span       Optional span for the chunk. If not provided, it will be set to the length of the payload.
+   *
+   * @example
+   *
+   */
+  makeContentAddressedChunk(rawPayload, span) {
+    return makeContentAddressedChunk(rawPayload, span);
+  }
+  /**
+   * Attempts to unmarshal arbitrary data into a Content Addressed Chunk.
+   * Throws an error if the data is not a valid CAC.
+   *
+   * @param data The chunk data (`span` and `payload`)
+   */
+  unmarshalContentAddressedChunk(data) {
+    return unmarshalContentAddressedChunk(data);
+  }
+  /**
+   * Creates a Single Owner Chunk.
+   *
+   * To be uploaded with the {@link uploadChunk} method.
+   *
+   * Identical to chaining `makeContentAddressedChunk` and `toSingleOwnerChunk`.
+   *
+   * Payload size must be between 1 and 4096 bytes.
+   *
+   * @param address     Address of the Content Addressed Chunk
+   * @param span        Span of the Content Addressed Chunk
+   * @param payload     Payload of the Content Addressed Chunk
+   * @param identifier  The identifier of the chunk
+   * @param signer      The signer interface for signing the chunk
+   */
+  makeSingleOwnerChunk(address, span, payload, identifier, signer) {
+    return makeSingleOwnerChunk(address, span, payload, identifier, signer);
+  }
+  /**
+   * Calculates the address of a Single Owner Chunk based on its identifier and owner address.
+   *
+   * @param identifier
+   * @param address
+   */
+  calculateSingleOwnerChunkAddress(identifier, address) {
+    return makeSOCAddress(identifier, address);
+  }
+  /**
+   * Attempts to unmarshal arbitrary data into a Single Owner Chunk.
+   * Throws an error if the data is not a valid SOC.
+   *
+   * @param data    The chunk data
+   * @param address The address of the single owner chunk
+   *
+   * @returns a single owner chunk or throws error
+   */
+  unmarshalSingleOwnerChunk(data, address) {
+    return unmarshalSingleOwnerChunk(data, address);
+  }
   /**
    * Returns an object for reading single owner chunks
    *
@@ -1535,7 +1603,7 @@ export class Bee {
     const blockTime = this.network === 'gnosis' ? 5 : 15;
     const additionalAmount = getAmountForDuration(duration, chainState.currentPrice, blockTime);
     const currentAmount = getAmountForDuration(batch.duration, chainState.currentPrice, blockTime);
-    const targetAmount = duration.isZero() ? currentAmount * multiplier : currentAmount + additionalAmount * multiplier;
+    const targetAmount = duration.isZero() ? currentAmount * multiplier : (currentAmount + additionalAmount) * multiplier;
     const amountDelta = targetAmount - currentAmount;
     const transactionId = await this.topUpBatch(batch.batchID, amountDelta, requestOptions);
     if (depthDelta > 0) {

package/dist/mjs/chunk/cac.js

@@ -1,41 +1,32 @@
-import { Binary } from 'cafe-utility';
+import { Binary, Types } from 'cafe-utility';
 import { Bytes } from "../utils/bytes.js";
 import { Span } from "../utils/typed-bytes.js";
 import { calculateChunkAddress } from "./bmt.js";
+import { makeSingleOwnerChunk } from "./soc.js";
 export const MIN_PAYLOAD_SIZE = 1;
 export const MAX_PAYLOAD_SIZE = 4096;
-const ENCODER = new TextEncoder();
-/**
- * Creates a content addressed chunk and verifies the payload size.
- *
- * @param payloadBytes the data to be stored in the chunk
- */
-export function makeContentAddressedChunk(payloadBytes) {
-  if (!(payloadBytes instanceof Uint8Array)) {
-    payloadBytes = ENCODER.encode(payloadBytes);
-  }
-  if (payloadBytes.length < MIN_PAYLOAD_SIZE || payloadBytes.length > MAX_PAYLOAD_SIZE) {
-    throw new RangeError(`payload size ${payloadBytes.length} exceeds limits [${MIN_PAYLOAD_SIZE}, ${MAX_PAYLOAD_SIZE}]`);
-  }
-  const span = Span.fromBigInt(BigInt(payloadBytes.length));
-  const data = Binary.concatBytes(span.toUint8Array(), payloadBytes);
-  return {
-    data,
-    span,
-    payload: Bytes.fromSlice(data, Span.LENGTH),
-    address: calculateChunkAddress(data)
-  };
+export function unmarshalContentAddressedChunk(data) {
+  data = new Bytes(data);
+  return makeContentAddressedChunk(data.toUint8Array().slice(Span.LENGTH), Span.fromSlice(data.toUint8Array(), 0));
 }
-export function asContentAddressedChunk(chunkBytes) {
-  if (chunkBytes.length < MIN_PAYLOAD_SIZE + Span.LENGTH || chunkBytes.length > MAX_PAYLOAD_SIZE + Span.LENGTH) {
-    throw new RangeError(`chunk size ${chunkBytes.length} exceeds limits [${MIN_PAYLOAD_SIZE + Span.LENGTH}, ${Span.LENGTH}]`);
+export function makeContentAddressedChunk(rawPayload, span) {
+  if (Types.isString(rawPayload)) {
+    rawPayload = Bytes.fromUtf8(rawPayload);
+  }
+  if (rawPayload.length < MIN_PAYLOAD_SIZE || rawPayload.length > MAX_PAYLOAD_SIZE) {
+    throw new RangeError(`payload size ${rawPayload.length} exceeds limits [${MIN_PAYLOAD_SIZE}, ${MAX_PAYLOAD_SIZE}]`);
   }
-  const span = Span.fromSlice(chunkBytes, 0);
-  const data = Binary.concatBytes(span.toUint8Array(), chunkBytes.slice(Span.LENGTH));
+  const typedSpan = span ? typeof span === 'bigint' ? Span.fromBigInt(span) : span : Span.fromBigInt(BigInt(rawPayload.length));
+  const payload = new Bytes(rawPayload);
+  const data = Binary.concatBytes(typedSpan.toUint8Array(), payload.toUint8Array());
+  const address = calculateChunkAddress(data);
   return {
     data,
-    span,
-    payload: Bytes.fromSlice(data, Span.LENGTH),
-    address: calculateChunkAddress(data)
+    span: typedSpan,
+    payload,
+    address,
+    toSingleOwnerChunk: (identifier, signer) => {
+      return makeSingleOwnerChunk(address, typedSpan, payload, identifier, signer);
+    }
   };
 }

package/dist/mjs/chunk/soc.js

@@ -5,10 +5,10 @@ import { Bytes } from "../utils/bytes.js";
 import { BeeError } from "../utils/error.js";
 import { EthAddress, Identifier, PrivateKey, Reference, Signature, Span } from "../utils/typed-bytes.js";
 import { calculateChunkAddress } from "./bmt.js";
-import { asContentAddressedChunk, makeContentAddressedChunk } from "./cac.js";
+import { makeContentAddressedChunk } from "./cac.js";
 const SOC_SIGNATURE_OFFSET = Identifier.LENGTH;
-const SOC_SPAN_OFFSET = SOC_SIGNATURE_OFFSET + Signature.LENGTH;
-const SOC_PAYLOAD_OFFSET = SOC_SPAN_OFFSET + Span.LENGTH;
+const SOC_SPAN_OFFSET = Identifier.LENGTH + Signature.LENGTH;
+const SOC_PAYLOAD_OFFSET = Identifier.LENGTH + Signature.LENGTH + Span.LENGTH;
 function recoverChunkOwner(data) {
   const cacData = data.slice(SOC_SPAN_OFFSET);
   const chunkAddress = calculateChunkAddress(cacData);
@@ -19,21 +19,22 @@ function recoverChunkOwner(data) {
   return ownerAddress;
 }
 /**
- * Verifies if the data is a valid single owner chunk
+ * Unmarshals arbitrary data into a Single Owner Chunk.
+ * Throws an error if the data is not a valid SOC.
  *
  * @param data    The chunk data
  * @param address The address of the single owner chunk
  *
  * @returns a single owner chunk or throws error
  */
-export function makeSingleOwnerChunkFromData(data, address) {
+export function unmarshalSingleOwnerChunk(data, address) {
   data = data instanceof Bytes ? data.toUint8Array() : data;
   address = new Reference(address);
   const ownerAddress = recoverChunkOwner(data);
   const identifier = Bytes.fromSlice(data, 0, Identifier.LENGTH);
   const socAddress = new Reference(Binary.keccak256(Binary.concatBytes(identifier.toUint8Array(), ownerAddress.toUint8Array())));
   if (!Binary.equals(address.toUint8Array(), socAddress.toUint8Array())) {
-    throw new BeeError('SOC Data does not match given address!');
+    throw new BeeError('SOC data does not match given address!');
   }
   const signature = Signature.fromSlice(data, SOC_SIGNATURE_OFFSET);
   const span = Span.fromSlice(data, SOC_SPAN_OFFSET);
@@ -58,21 +59,19 @@ export function makeSOCAddress(identifier, address) {
  * @param identifier  The identifier of the chunk
  * @param signer      The signer interface for signing the chunk
  */
-export function makeSingleOwnerChunk(chunk, identifier, signer) {
+export function makeSingleOwnerChunk(address, span, payload, identifier, signer) {
   identifier = new Identifier(identifier);
   signer = new PrivateKey(signer);
-  const address = makeSOCAddress(identifier, signer.publicKey().address());
-  const signature = signer.sign(Binary.concatBytes(identifier.toUint8Array(), chunk.address.toUint8Array()));
-  const data = Binary.concatBytes(identifier.toUint8Array(), signature.toUint8Array(), chunk.data);
-  const span = Span.fromSlice(chunk.data, 0);
-  const payload = Bytes.fromSlice(chunk.data, Span.LENGTH);
+  const socAddress = makeSOCAddress(identifier, signer.publicKey().address());
+  const signature = signer.sign(Binary.concatBytes(identifier.toUint8Array(), address.toUint8Array()));
+  const data = Binary.concatBytes(identifier.toUint8Array(), signature.toUint8Array(), span.toUint8Array(), payload.toUint8Array());
   return {
     data,
     identifier,
     signature,
     span,
     payload,
-    address,
+    address: socAddress,
     owner: signer.publicKey().address()
   };
 }
@@ -104,13 +103,13 @@ export async function uploadSingleOwnerChunkData(requestOptions, signer, stamp,
   signer = new PrivateKey(signer);
   identifier = new Identifier(identifier);
   const cac = makeContentAddressedChunk(data);
-  const soc = makeSingleOwnerChunk(cac, identifier, signer);
+  const soc = cac.toSingleOwnerChunk(identifier, signer);
   return uploadSingleOwnerChunk(requestOptions, soc, stamp, options);
 }
-export async function uploadSingleOwnerChunkWithWrappedChunk(requestOptions, signer, stamp, identifier, rootChunk, options) {
+export async function uploadSingleOwnerChunkWithWrappedChunk(requestOptions, signer, stamp, identifier, wrappedChunk, options) {
   signer = new PrivateKey(signer);
   identifier = new Identifier(identifier);
-  const soc = makeSingleOwnerChunk(asContentAddressedChunk(rootChunk), identifier, signer);
+  const soc = wrappedChunk.toSingleOwnerChunk(identifier, signer);
   return uploadSingleOwnerChunk(requestOptions, soc, stamp, options);
 }
 /**
@@ -125,5 +124,5 @@ export async function downloadSingleOwnerChunk(requestOptions, ownerAddress, ide
   ownerAddress = new EthAddress(ownerAddress);
   const address = makeSOCAddress(identifier, ownerAddress);
   const cac = await chunkAPI.download(requestOptions, address.toHex());
-  return makeSingleOwnerChunkFromData(cac, address);
+  return unmarshalSingleOwnerChunk(cac, address);
 }

package/dist/mjs/feed/index.js

@@ -1,13 +1,13 @@
 import { Binary, Optional, Types } from 'cafe-utility';
-import { asContentAddressedChunk } from "../chunk/cac.js";
-import { makeSingleOwnerChunkFromData, uploadSingleOwnerChunkData, uploadSingleOwnerChunkWithWrappedChunk } from "../chunk/soc.js";
+import { makeContentAddressedChunk, unmarshalContentAddressedChunk } from "../chunk/cac.js";
+import { unmarshalSingleOwnerChunk, uploadSingleOwnerChunkData, uploadSingleOwnerChunkWithWrappedChunk } from "../chunk/soc.js";
 import * as bytes from "../modules/bytes.js";
 import * as chunkAPI from "../modules/chunk.js";
 import { fetchLatestFeedUpdate, probeFeed } from "../modules/feed.js";
 import { Bytes } from "../utils/bytes.js";
 import { BeeResponseError } from "../utils/error.js";
 import { ResourceLocator } from "../utils/resource-locator.js";
-import { FeedIndex, Identifier, Reference, Signature } from "../utils/typed-bytes.js";
+import { FeedIndex, Reference } from "../utils/typed-bytes.js";
 import { makeFeedIdentifier } from "./identifier.js";
 const TIMESTAMP_PAYLOAD_OFFSET = 0;
 const TIMESTAMP_PAYLOAD_SIZE = 8;
@@ -40,7 +40,7 @@ export async function updateFeedWithPayload(requestOptions, signer, topic, data,
   const identifier = makeFeedIdentifier(topic, nextIndex);
   if (data.length > 4096) {
     const uploadResult = await bytes.upload(requestOptions, data, postageBatchId, options);
-    const rootChunk = await chunkAPI.download(requestOptions, uploadResult.reference);
+    const rootChunk = unmarshalContentAddressedChunk(await chunkAPI.download(requestOptions, uploadResult.reference));
     return uploadSingleOwnerChunkWithWrappedChunk(requestOptions, signer, postageBatchId, identifier, rootChunk, options);
   }
   return uploadSingleOwnerChunkData(requestOptions, signer, postageBatchId, identifier, Types.isString(data) ? Bytes.fromUtf8(data).toUint8Array() : data, options);
@@ -53,7 +53,7 @@ export async function downloadFeedUpdate(requestOptions, owner, topic, index, ha
   index = typeof index === 'number' ? FeedIndex.fromBigInt(BigInt(index)) : index;
   const address = getFeedUpdateChunkReference(owner, topic, index);
   const data = await chunkAPI.download(requestOptions, address.toHex());
-  const soc = makeSingleOwnerChunkFromData(data, address);
+  const soc = unmarshalSingleOwnerChunk(data, address);
   let timestamp = Optional.empty();
   if (hasTimestamp) {
     const timestampBytes = Bytes.fromSlice(soc.payload.toUint8Array(), TIMESTAMP_PAYLOAD_OFFSET, TIMESTAMP_PAYLOAD_SIZE);
@@ -68,7 +68,8 @@ export async function downloadFeedUpdateAsCAC(requestOptions, owner, topic, inde
   index = typeof index === 'number' ? FeedIndex.fromBigInt(BigInt(index)) : index;
   const address = getFeedUpdateChunkReference(owner, topic, index);
   const data = await chunkAPI.download(requestOptions, address);
-  return asContentAddressedChunk(data.slice(Identifier.LENGTH + Signature.LENGTH));
+  const soc = unmarshalSingleOwnerChunk(data, address);
+  return makeContentAddressedChunk(soc.payload, soc.span);
 }
 export function makeFeedReader(requestOptions, topic, owner) {
   // TODO: remove after enough time has passed in deprecated version

package/dist/types/bee.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
 import { Readable } from 'stream';
 import { Chunk } from './chunk/cac';
+import { SingleOwnerChunk } from './chunk/soc';
 import { FeedPayloadResult } from './modules/feed';
 import type { AllSettlements, BalanceResponse, BeeOptions, BeeRequestOptions, BeeVersions, ChainState, ChequebookAddressResponse, ChequebookBalanceResponse, CollectionUploadOptions, DebugStatus, DownloadOptions, EnvelopeWithBatchId, FeedReader, FeedWriter, FileData, FileUploadOptions, GetGranteesResult, GlobalPostageBatch, GranteesResult, GsocMessageHandler, GsocSubscription, Health, LastCashoutActionResponse, LastChequesForPeerResponse, LastChequesResponse, NodeAddresses, NodeInfo, NumberString, Peer, PeerBalance, Pin, PingResponse, PostageBatch, PostageBatchBuckets, PssMessageHandler, PssSubscription, Readiness, RedistributionState, RedundancyLevel, RedundantUploadOptions, ReferenceInformation, RemovePeerResponse, ReserveState, SOCReader, SOCWriter, Settlements, Tag, Topology, TransactionInfo, UploadOptions, WalletBalance } from './types';
 import { AllTagsOptions, Collection, PostageBatchOptions, TransactionOptions, UploadResult } from './types';
@@ -8,7 +9,7 @@ import { Bytes } from './utils/bytes';
 import { Duration } from './utils/duration';
 import { Size } from './utils/size';
 import { BZZ, DAI } from './utils/tokens';
-import { BatchId, EthAddress, FeedIndex, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Topic, TransactionId } from './utils/typed-bytes';
+import { BatchId, EthAddress, FeedIndex, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Span, Topic, TransactionId } from './utils/typed-bytes';
 import { UploadProgress } from './utils/upload-progress';
 /**
  * The main component that abstracts operations available on the Bee API.
@@ -123,7 +124,7 @@ export declare class Bee {
      * Chunks uploaded with this method should be retrieved with the {@link downloadChunk} method.
      *
      * @param stamp Postage Batch ID or an Envelope created with the {@link createEnvelope} method.
-     * @param data    Raw chunk to be uploaded
+     * @param data    Raw chunk to be uploaded (Content Addressed Chunk or Single Owner Chunk)
      * @param options Additional options like tag, encryption, pinning, content-type and request options
      * @param requestOptions Options for making requests, such as timeouts, custom HTTP agents, headers, etc.
      *
@@ -131,7 +132,7 @@ export declare class Bee {
      * @see [Bee docs - Upload and download](https://docs.ethswarm.org/docs/develop/access-the-swarm/upload-and-download)
      * @see [Bee API reference - `POST /chunks`](https://docs.ethswarm.org/api/#tag/Chunk/paths/~1chunks/post)
      */
-    uploadChunk(stamp: EnvelopeWithBatchId | BatchId | Uint8Array | string, data: Uint8Array | Chunk, options?: UploadOptions, requestOptions?: BeeRequestOptions): Promise<UploadResult>;
+    uploadChunk(stamp: EnvelopeWithBatchId | BatchId | Uint8Array | string, data: Uint8Array | Chunk | SingleOwnerChunk, options?: UploadOptions, requestOptions?: BeeRequestOptions): Promise<UploadResult>;
     /**
      * Downloads a chunk as a `Uint8Array`.
      *
@@ -608,6 +609,60 @@ export declare class Bee {
      */
     makeFeedWriter(topic: Topic | Uint8Array | string, signer?: PrivateKey | Uint8Array | string, requestOptions?: BeeRequestOptions): FeedWriter;
     fetchLatestFeedUpdate(topic: Topic | Uint8Array | string, owner: EthAddress | Uint8Array | string, requestOptions?: BeeRequestOptions): Promise<FeedPayloadResult>;
+    /**
+     * Creates a Content Addressed Chunk.
+     *
+     * To be uploaded with the {@link uploadChunk} method.
+     *
+     * Payload size must be between 1 and 4096 bytes.
+     *
+     * @param rawPayload Data to be stored in the chunk. If the data is a string, it will be converted to UTF-8 bytes.
+     * @param span       Optional span for the chunk. If not provided, it will be set to the length of the payload.
+     *
+     * @example
+     *
+     */
+    makeContentAddressedChunk(rawPayload: Bytes | Uint8Array | string, span?: Span | bigint): Chunk;
+    /**
+     * Attempts to unmarshal arbitrary data into a Content Addressed Chunk.
+     * Throws an error if the data is not a valid CAC.
+     *
+     * @param data The chunk data (`span` and `payload`)
+     */
+    unmarshalContentAddressedChunk(data: Bytes | Uint8Array): Chunk;
+    /**
+     * Creates a Single Owner Chunk.
+     *
+     * To be uploaded with the {@link uploadChunk} method.
+     *
+     * Identical to chaining `makeContentAddressedChunk` and `toSingleOwnerChunk`.
+     *
+     * Payload size must be between 1 and 4096 bytes.
+     *
+     * @param address     Address of the Content Addressed Chunk
+     * @param span        Span of the Content Addressed Chunk
+     * @param payload     Payload of the Content Addressed Chunk
+     * @param identifier  The identifier of the chunk
+     * @param signer      The signer interface for signing the chunk
+     */
+    makeSingleOwnerChunk(address: Reference, span: Span, payload: Bytes, identifier: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string): SingleOwnerChunk;
+    /**
+     * Calculates the address of a Single Owner Chunk based on its identifier and owner address.
+     *
+     * @param identifier
+     * @param address
+     */
+    calculateSingleOwnerChunkAddress(identifier: Identifier, address: EthAddress): Reference;
+    /**
+     * Attempts to unmarshal arbitrary data into a Single Owner Chunk.
+     * Throws an error if the data is not a valid SOC.
+     *
+     * @param data    The chunk data
+     * @param address The address of the single owner chunk
+     *
+     * @returns a single owner chunk or throws error
+     */
+    unmarshalSingleOwnerChunk(data: Bytes | Uint8Array, address: Reference | Uint8Array | string): SingleOwnerChunk;
     /**
      * Returns an object for reading single owner chunks
      *

package/dist/types/chunk/cac.d.ts

@@ -1,26 +1,40 @@
 import { Bytes } from '../utils/bytes';
-import { Reference, Span } from '../utils/typed-bytes';
+import { Identifier, PrivateKey, Reference, Span } from '../utils/typed-bytes';
+import { SingleOwnerChunk } from './soc';
 export declare const MIN_PAYLOAD_SIZE = 1;
 export declare const MAX_PAYLOAD_SIZE = 4096;
 /**
- * General chunk interface for Swarm
+ * Content Addressed Chunk (CAC) is the immutable building block of Swarm,
+ * holding at most 4096 bytes of payload.
  *
- * It stores the serialized data and provides functions to access
- * the fields of a chunk.
+ * - `span` indicates the size of the `payload` in bytes.
+ * - `payload` contains the actual data or the body of the chunk.
+ * - `data` contains the full chunk data - `span` and `payload`.
+ * - `address` is the Swarm hash (or reference) of the chunk.
  *
- * It also provides an address function to calculate the address of
- * the chunk that is required for the Chunk API.
+ * The `toSingleOwnerChunk` method allows converting the CAC into a Single Owner Chunk (SOC).
  */
 export interface Chunk {
+    /**
+     * Contains the full chunk data - `span` + `payload`.
+     */
     readonly data: Uint8Array;
+    /**
+     * Indicates the size of the `payload` in bytes.
+     */
     span: Span;
+    /**
+     * Contains the actual data or the body of the chunk.
+     */
     payload: Bytes;
+    /**
+     * The Swarm hash (or reference) of the chunk.
+     */
     address: Reference;
+    /**
+     * Converts the CAC into a Single Owner Chunk (SOC).
+     */
+    toSingleOwnerChunk: (identifier: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string) => SingleOwnerChunk;
 }
-/**
- * Creates a content addressed chunk and verifies the payload size.
- *
- * @param payloadBytes the data to be stored in the chunk
- */
-export declare function makeContentAddressedChunk(payloadBytes: Uint8Array | string): Chunk;
-export declare function asContentAddressedChunk(chunkBytes: Uint8Array): Chunk;
+export declare function unmarshalContentAddressedChunk(data: Bytes | Uint8Array): Chunk;
+export declare function makeContentAddressedChunk(rawPayload: Bytes | Uint8Array | string, span?: Span | bigint): Chunk;

package/dist/types/chunk/soc.d.ts

@@ -1,29 +1,61 @@
 import { BeeRequestOptions, UploadOptions, UploadResult } from '../types';
 import { Bytes } from '../utils/bytes';
-import { BatchId, EthAddress, Identifier, PrivateKey, Reference, Signature } from '../utils/typed-bytes';
+import { BatchId, EthAddress, Identifier, PrivateKey, Reference, Signature, Span } from '../utils/typed-bytes';
 import { Chunk } from './cac';
 /**
- * With single owner chunks, a user can assign arbitrary data to an
- * address and attest chunk integrity with their digital signature.
+ * Single Owner Chunk (SOC) is a chunk type where the address is determined by the owner and an arbitrary identifier.
+ * Its integrity is attested by the owner's digital signature.
  *
- * This interface extends the Chunk interface so it has the same
- * properties, but the address calculation is based on the identifier
- * and the owner of the chunk.
+ * Similar to Content Addressed Chunks (CAC), SOCs have a maximum payload size of 4096 bytes.
+ *
+ * - `span` indicates the size of the `payload` in bytes.
+ * - `payload` contains the actual data or the body of the chunk.
+ * - `data` contains the full chunk data - `span` and `payload`.
+ * - `address` is the Swarm hash (or reference) of the chunk.
+ * - `identifier` is an arbitrary identifier selected by the uploader.
+ * - `signature` is the digital signature of the owner over the identifier and the underlying CAC address.
+ * - `owner` is the Ethereum address of the chunk owner.
  */
-export interface SingleOwnerChunk extends Chunk {
+export interface SingleOwnerChunk {
+    /**
+     * Contains the full chunk data - `span` + `payload`.
+     */
+    readonly data: Uint8Array;
+    /**
+     * Indicates the size of the `payload` in bytes.
+     */
+    span: Span;
+    /**
+     * Contains the actual data or the body of the chunk.
+     */
+    payload: Bytes;
+    /**
+     * The Swarm hash (or reference) of the chunk.
+     */
+    address: Reference;
+    /**
+     * An arbitrary identifier selected by the uploader.
+     */
     identifier: Identifier;
+    /**
+     * The digital signature of the owner over the identifier and the underlying CAC address.
+     */
     signature: Signature;
+    /**
+     * The Ethereum address of the chunk owner.
+     */
     owner: EthAddress;
 }
 /**
- * Verifies if the data is a valid single owner chunk
+ * Unmarshals arbitrary data into a Single Owner Chunk.
+ * Throws an error if the data is not a valid SOC.
  *
  * @param data    The chunk data
  * @param address The address of the single owner chunk
  *
  * @returns a single owner chunk or throws error
  */
-export declare function makeSingleOwnerChunkFromData(data: Bytes | Uint8Array, address: Reference | Uint8Array | string): SingleOwnerChunk;
+export declare function unmarshalSingleOwnerChunk(data: Bytes | Uint8Array, address: Reference | Uint8Array | string): SingleOwnerChunk;
 export declare function makeSOCAddress(identifier: Identifier, address: EthAddress): Reference;
 /**
  * Creates a single owner chunk object
@@ -32,7 +64,7 @@ export declare function makeSOCAddress(identifier: Identifier, address: EthAddre
  * @param identifier  The identifier of the chunk
  * @param signer      The signer interface for signing the chunk
  */
-export declare function makeSingleOwnerChunk(chunk: Chunk, identifier: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string): SingleOwnerChunk;
+export declare function makeSingleOwnerChunk(address: Reference, span: Span, payload: Bytes, identifier: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string): SingleOwnerChunk;
 /**
  * Helper function to upload a chunk.
  *
@@ -55,7 +87,7 @@ export declare function uploadSingleOwnerChunk(requestOptions: BeeRequestOptions
  * @param options
  */
 export declare function uploadSingleOwnerChunkData(requestOptions: BeeRequestOptions, signer: PrivateKey | Uint8Array | string, stamp: BatchId | Uint8Array | string, identifier: Identifier | Uint8Array | string, data: Uint8Array, options?: UploadOptions): Promise<UploadResult>;
-export declare function uploadSingleOwnerChunkWithWrappedChunk(requestOptions: BeeRequestOptions, signer: PrivateKey | Uint8Array | string, stamp: BatchId | Uint8Array | string, identifier: Identifier | Uint8Array | string, rootChunk: Uint8Array, options?: UploadOptions): Promise<UploadResult>;
+export declare function uploadSingleOwnerChunkWithWrappedChunk(requestOptions: BeeRequestOptions, signer: PrivateKey | Uint8Array | string, stamp: BatchId | Uint8Array | string, identifier: Identifier | Uint8Array | string, wrappedChunk: Chunk, options?: UploadOptions): Promise<UploadResult>;
 /**
  * Helper function to download SOC.
  *

package/dist/types/index.d.ts

@@ -2,6 +2,8 @@ import { Bee } from './bee';
 import { BeeDev } from './bee-dev';
 import { Stamper } from './stamper/stamper';
 export { MerkleTree } from 'cafe-utility';
+export { Chunk } from './chunk/cac';
+export { SingleOwnerChunk } from './chunk/soc';
 export { MantarayNode } from './manifest/manifest';
 export { SUPPORTED_BEE_VERSION, SUPPORTED_BEE_VERSION_EXACT } from './modules/debug/status';
 export * from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethersphere/bee-js",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "description": "Javascript client for Bee",
   "keywords": [
     "bee",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "axios": "^0.30.0",
-    "cafe-utility": "^32.2.0",
+    "cafe-utility": "^33.3.4",
     "debug": "^4.4.1",
     "isomorphic-ws": "^4.0.1",
     "semver": "^7.3.5",