@ethersphere/bee-js 10.2.0 → 10.4.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/mjs/modules/debug/stamps.js

@@ -1,11 +1,8 @@
 import { Types } from 'cafe-utility';
-import { Duration } from "../../utils/duration.js";
 import { http } from "../../utils/http.js";
-import { Size } from "../../utils/size.js";
-import { getStampEffectiveBytes, getStampTheoreticalBytes, getStampUsage } from "../../utils/stamps.js";
+import { mapPostageBatch } from "../../utils/stamps.js";
 import { asNumberString } from "../../utils/type.js";
 import { BatchId, EthAddress } from "../../utils/typed-bytes.js";
-import { normalizeBatchTTL } from "../../utils/workaround.js";
 const STAMPS_ENDPOINT = 'stamps';
 const BATCHES_ENDPOINT = 'batches';
 export async function getGlobalPostageBatches(requestOptions) {
@@ -63,60 +60,7 @@ export async function getAllPostageBatches(requestOptions) {
   }).map(x => Types.asObject(x, {
     name: 'stamp'
   }));
-  return stamps.map(x => {
-    const utilization = Types.asNumber(x.utilization, {
-      name: 'utilization'
-    });
-    const depth = Types.asNumber(x.depth, {
-      name: 'depth'
-    });
-    const bucketDepth = Types.asNumber(x.bucketDepth, {
-      name: 'bucketDepth'
-    });
-    const usage = getStampUsage(utilization, depth, bucketDepth);
-    const batchTTL = normalizeBatchTTL(Types.asNumber(x.batchTTL, {
-      name: 'batchTTL'
-    }));
-    const duration = Duration.fromSeconds(batchTTL);
-    const effectiveBytes = getStampEffectiveBytes(depth);
-    return {
-      batchID: new BatchId(Types.asString(x.batchID, {
-        name: 'batchID'
-      })),
-      utilization,
-      usable: Types.asBoolean(x.usable, {
-        name: 'usable'
-      }),
-      label: Types.asEmptiableString(x.label, {
-        name: 'label'
-      }),
-      depth,
-      amount: asNumberString(x.amount, {
-        name: 'amount'
-      }),
-      bucketDepth,
-      blockNumber: Types.asNumber(x.blockNumber, {
-        name: 'blockNumber'
-      }),
-      immutableFlag: Types.asBoolean(x.immutableFlag, {
-        name: 'immutableFlag'
-      }),
-      usage,
-      usageText: `${Math.round(usage * 100)}%`,
-      size: Size.fromBytes(effectiveBytes),
-      remainingSize: Size.fromBytes(Math.ceil(effectiveBytes * (1 - usage))),
-      theoreticalSize: Size.fromBytes(getStampTheoreticalBytes(depth)),
-      duration,
-      calculateSize(encryption, redundancyLevel) {
-        const effectiveBytes = getStampEffectiveBytes(this.depth, encryption, redundancyLevel);
-        return Size.fromBytes(effectiveBytes);
-      },
-      calculateRemainingSize(encryption, redundancyLevel) {
-        const effectiveBytes = getStampEffectiveBytes(this.depth, encryption, redundancyLevel);
-        return Size.fromBytes(Math.ceil(effectiveBytes * (1 - this.usage)));
-      }
-    };
-  });
+  return stamps.map(x => mapPostageBatch(validateRawPostageBatch(x)));
 }
 export async function getPostageBatch(requestOptions, postageBatchId, encryption, erasureCodeLevel) {
   const response = await http(requestOptions, {
@@ -127,58 +71,7 @@ export async function getPostageBatch(requestOptions, postageBatchId, encryption
   const body = Types.asObject(response.data, {
     name: 'response.data'
   });
-  const utilization = Types.asNumber(body.utilization, {
-    name: 'utilization'
-  });
-  const depth = Types.asNumber(body.depth, {
-    name: 'depth'
-  });
-  const bucketDepth = Types.asNumber(body.bucketDepth, {
-    name: 'bucketDepth'
-  });
-  const usage = getStampUsage(utilization, depth, bucketDepth);
-  const batchTTL = normalizeBatchTTL(Types.asNumber(body.batchTTL, {
-    name: 'batchTTL'
-  }));
-  const duration = Duration.fromSeconds(batchTTL);
-  const effectiveBytes = getStampEffectiveBytes(depth, encryption, erasureCodeLevel);
-  return {
-    batchID: new BatchId(Types.asString(body.batchID, {
-      name: 'batchID'
-    })),
-    utilization,
-    usable: Types.asBoolean(body.usable, {
-      name: 'usable'
-    }),
-    label: Types.asEmptiableString(body.label, {
-      name: 'label'
-    }),
-    depth,
-    amount: asNumberString(body.amount, {
-      name: 'amount'
-    }),
-    bucketDepth,
-    blockNumber: Types.asNumber(body.blockNumber, {
-      name: 'blockNumber'
-    }),
-    immutableFlag: Types.asBoolean(body.immutableFlag, {
-      name: 'immutableFlag'
-    }),
-    usage,
-    usageText: `${Math.round(usage * 100)}%`,
-    size: Size.fromBytes(effectiveBytes),
-    remainingSize: Size.fromBytes(Math.ceil(effectiveBytes * (1 - usage))),
-    theoreticalSize: Size.fromBytes(getStampTheoreticalBytes(depth)),
-    duration,
-    calculateSize(encryption, redundancyLevel) {
-      const effectiveBytes = getStampEffectiveBytes(depth, encryption, redundancyLevel);
-      return Size.fromBytes(effectiveBytes);
-    },
-    calculateRemainingSize(encryption, redundancyLevel) {
-      const effectiveBytes = getStampEffectiveBytes(depth, encryption, redundancyLevel);
-      return Size.fromBytes(Math.ceil(effectiveBytes * (1 - usage)));
-    }
-  };
+  return mapPostageBatch(validateRawPostageBatch(body), encryption, erasureCodeLevel);
 }
 export async function getPostageBatchBuckets(requestOptions, postageBatchId) {
   const response = await http(requestOptions, {
@@ -262,4 +155,38 @@ export async function diluteBatch(requestOptions, id, depth) {
   return new BatchId(Types.asString(body.batchID, {
     name: 'batchID'
   }));
+}
+function validateRawPostageBatch(raw) {
+  return {
+    amount: asNumberString(raw.amount, {
+      name: 'amount'
+    }),
+    batchID: Types.asString(raw.batchID, {
+      name: 'batchID'
+    }),
+    batchTTL: Types.asNumber(raw.batchTTL, {
+      name: 'batchTTL'
+    }),
+    bucketDepth: Types.asNumber(raw.bucketDepth, {
+      name: 'bucketDepth'
+    }),
+    blockNumber: Types.asNumber(raw.blockNumber, {
+      name: 'blockNumber'
+    }),
+    depth: Types.asNumber(raw.depth, {
+      name: 'depth'
+    }),
+    immutableFlag: Types.asBoolean(raw.immutableFlag, {
+      name: 'immutableFlag'
+    }),
+    label: Types.asEmptiableString(raw.label, {
+      name: 'label'
+    }),
+    usable: Types.asBoolean(raw.usable, {
+      name: 'usable'
+    }),
+    utilization: Types.asNumber(raw.utilization, {
+      name: 'utilization'
+    })
+  };
 }

package/dist/mjs/utils/expose.js

@@ -2,4 +2,4 @@ export { getCollectionSize, makeCollectionFromFileList } from "./collection.js";
 export { getFolderSize } from "./collection.node.js";
 export { makeMaxTarget } from "./pss.js";
 export { approximateOverheadForRedundancyLevel, getRedundancyStat, getRedundancyStats } from "./redundancy.js";
-export { getAmountForDuration, getDepthForSize, getStampCost, getStampDuration, getStampEffectiveBytes, getStampEffectiveBytesBreakpoints, getStampTheoreticalBytes, getStampUsage } from "./stamps.js";
+export { getAmountForDuration, getDepthForSize, getStampCost, getStampDuration, getStampEffectiveBytes, getStampEffectiveBytesBreakpoints, getStampTheoreticalBytes, getStampUsage, mapPostageBatch, unmapPostageBatch } from "./stamps.js";

package/dist/mjs/utils/stamps.js

@@ -2,8 +2,11 @@ import { Binary } from 'cafe-utility';
 import { capacityBreakpoints } from "../types/index.js";
 import { Bytes, parseSizeToBytes } from "./bytes.js";
 import { Duration } from "./duration.js";
+import { Size } from "./size.js";
 import { BZZ } from "./tokens.js";
 import { asNumberString } from "./type.js";
+import { BatchId } from "./typed-bytes.js";
+import { normalizeBatchTTL } from "./workaround.js";
 const MAX_UTILIZATION = 0.9;
 /**
  * Utility function that calculates usage of postage batch based on its utilization, depth and bucket depth.
@@ -137,4 +140,49 @@ export function marshalStamp(signature, batchId, timestamp, index) {
     throw Error('invalid index length');
   }
   return new Bytes(Binary.concatBytes(batchId, index, timestamp, signature));
+}
+export function mapPostageBatch(raw, encryption, erasureCodeLevel) {
+  const usage = getStampUsage(raw.utilization, raw.depth, raw.bucketDepth);
+  const batchTTL = normalizeBatchTTL(raw.batchTTL);
+  const duration = Duration.fromSeconds(batchTTL);
+  const effectiveBytes = getStampEffectiveBytes(raw.depth, encryption, erasureCodeLevel);
+  return {
+    batchID: new BatchId(raw.batchID),
+    utilization: raw.utilization,
+    usable: raw.usable,
+    label: raw.label,
+    depth: raw.depth,
+    amount: asNumberString(raw.amount),
+    bucketDepth: raw.bucketDepth,
+    blockNumber: raw.blockNumber,
+    immutableFlag: raw.immutableFlag,
+    usage,
+    usageText: `${Math.round(usage * 100)}%`,
+    size: Size.fromBytes(effectiveBytes),
+    remainingSize: Size.fromBytes(Math.ceil(effectiveBytes * (1 - usage))),
+    theoreticalSize: Size.fromBytes(getStampTheoreticalBytes(raw.depth)),
+    duration,
+    calculateSize(encryption, redundancyLevel) {
+      const effectiveBytes = getStampEffectiveBytes(raw.depth, encryption, redundancyLevel);
+      return Size.fromBytes(effectiveBytes);
+    },
+    calculateRemainingSize(encryption, redundancyLevel) {
+      const effectiveBytes = getStampEffectiveBytes(raw.depth, encryption, redundancyLevel);
+      return Size.fromBytes(Math.ceil(effectiveBytes * (1 - this.usage)));
+    }
+  };
+}
+export function unmapPostageBatch(batch) {
+  return {
+    batchID: batch.batchID.toHex(),
+    utilization: batch.utilization,
+    usable: batch.usable,
+    label: batch.label,
+    depth: batch.depth,
+    amount: batch.amount,
+    bucketDepth: batch.bucketDepth,
+    blockNumber: batch.blockNumber,
+    immutableFlag: batch.immutableFlag,
+    batchTTL: batch.duration.toSeconds()
+  };
 }

package/dist/mjs/utils/workaround.js

@@ -6,8 +6,11 @@ export function normalizeBatchTTL(batchTTL) {
   if (batchTTL < 1) {
     return 1;
   }
-  if (batchTTL > 315569260) {
-    return 315569260;
+  // Cap `batchTTL` (represents seconds) to 100 years.
+  // We can assume `storagePrice` is invalid (e.g. 1).
+  // This is needed to prevent Date objects breaking.
+  if (batchTTL > 3155695200) {
+    return 3155695200;
   }
   return batchTTL;
 }