feat: improve soc developer api (#1123)

* feat: improve soc developer api

* test: update test coverage

* refactor: soc qol

* test: update test coverage

* feat: add unmarshalContentAddressedChunk

* style: eslint

* test: update test coverage

* test: update test coverage

* fix: unmarshal wrapped cac in soc

* test: update test coverage

* fix: unmarshal wrapped cac in soc

* test: update test coverage

* docs: revert misleading comment

* fix: add span to soc

* test: update test coverage

* fix: update SOC size validation to include Identifier length

* test: update test coverage

* test: add soc tests

* test: update test coverage

* fix: keep span when unmarshaling

* test: update test coverage

* fix: pass span

* test: update test coverage

* test: update test coverage

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: Cafe137

cheatsheet.ts

@@ -185,6 +185,9 @@ async function main() {
       onError: error => {
         console.error(error)
       },
+      onClose: () => {
+        console.log('subscription closed')
+      },
     })
   }
 
@@ -227,6 +230,9 @@ async function main() {
       onError: error => {
         console.error(error)
       },
+      onClose: () => {
+        console.log('subscription closed')
+      },
     })
   }
 

src/bee.ts

@@ -1,7 +1,14 @@
 import { Binary, Objects, System, Types } from 'cafe-utility'
 import { Readable } from 'stream'
-import { Chunk, makeContentAddressedChunk } from './chunk/cac'
-import { downloadSingleOwnerChunk, makeSOCAddress, makeSingleOwnerChunk, uploadSingleOwnerChunkData } from './chunk/soc'
+import { Chunk, makeContentAddressedChunk, unmarshalContentAddressedChunk } from './chunk/cac'
+import {
+  SingleOwnerChunk,
+  downloadSingleOwnerChunk,
+  makeSOCAddress,
+  makeSingleOwnerChunk,
+  unmarshalSingleOwnerChunk,
+  uploadSingleOwnerChunkData,
+} from './chunk/soc'
 import { makeFeedReader, makeFeedWriter } from './feed'
 import { areAllSequentialFeedsUpdateRetrievable } from './feed/retrievable'
 import * as bytes from './modules/bytes'
@@ -127,6 +134,7 @@ import {
   PrivateKey,
   PublicKey,
   Reference,
+  Signature,
   Span,
   Topic,
   TransactionId,
@@ -316,7 +324,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.
    *
@@ -326,10 +334,12 @@ export class Bee {
    */
   async uploadChunk(
     stamp: EnvelopeWithBatchId | BatchId | Uint8Array | string,
-    data: Uint8Array | Chunk,
+    data: Uint8Array | Chunk | SingleOwnerChunk,
     options?: UploadOptions,
     requestOptions?: BeeRequestOptions,
   ): Promise<UploadResult> {
+    const isSOC = 'identifier' in data && 'signature' in data && 'owner' in data
+
     data = data instanceof Uint8Array ? data : data.data
 
     if (options) {
@@ -340,8 +350,15 @@ export class Bee {
       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)
@@ -1184,7 +1201,7 @@ export class Bee {
     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)
   }
@@ -1357,6 +1374,81 @@ export class Bee {
     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: Bytes | Uint8Array | string, span?: Span | bigint): Chunk {
+    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: Bytes | Uint8Array): Chunk {
+    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: Reference,
+    span: Span,
+    payload: Bytes,
+    identifier: Identifier | Uint8Array | string,
+    signer: PrivateKey | Uint8Array | string,
+  ): SingleOwnerChunk {
+    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: Identifier, address: EthAddress): Reference {
+    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: Bytes | Uint8Array, address: Reference | Uint8Array | string): SingleOwnerChunk {
+    return unmarshalSingleOwnerChunk(data, address)
+  }
+
   /**
    * Returns an object for reading single owner chunks
    *

src/chunk/cac.ts

@@ -1,70 +1,80 @@
-import { Binary } from 'cafe-utility'
+import { Binary, Types } from 'cafe-utility'
 import { Bytes } from '../utils/bytes'
-import { Reference, Span } from '../utils/typed-bytes'
+import { Identifier, PrivateKey, Reference, Span } from '../utils/typed-bytes'
 import { calculateChunkAddress } from './bmt'
+import { makeSingleOwnerChunk, SingleOwnerChunk } from './soc'
 
 export const MIN_PAYLOAD_SIZE = 1
 export const MAX_PAYLOAD_SIZE = 4096
 
-const ENCODER = new TextEncoder()
-
 /**
- * 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 function makeContentAddressedChunk(payloadBytes: Uint8Array | string): Chunk {
-  if (!(payloadBytes instanceof Uint8Array)) {
-    payloadBytes = ENCODER.encode(payloadBytes)
-  }
+export function unmarshalContentAddressedChunk(data: Bytes | Uint8Array): Chunk {
+  data = new Bytes(data)
 
-  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 makeContentAddressedChunk(data.toUint8Array().slice(Span.LENGTH), Span.fromSlice(data.toUint8Array(), 0))
+}
 
-  return {
-    data,
-    span,
-    payload: Bytes.fromSlice(data, Span.LENGTH),
-    address: calculateChunkAddress(data),
+export function makeContentAddressedChunk(rawPayload: Bytes | Uint8Array | string, span?: Span | bigint): Chunk {
+  if (Types.isString(rawPayload)) {
+    rawPayload = Bytes.fromUtf8(rawPayload)
   }
-}
 
-export function asContentAddressedChunk(chunkBytes: Uint8Array): Chunk {
-  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}]`,
-    )
+  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 = 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: Identifier | Uint8Array | string, signer: PrivateKey | Uint8Array | string) => {
+      return makeSingleOwnerChunk(address, typedSpan, payload, identifier, signer)
+    },
   }
 }