@upcoming/bee-js 0.8.1 → 0.10.0

package/dist/cjs/bee.js

@@ -59,6 +59,7 @@ const data_1 = require("./utils/data");
 const error_1 = require("./utils/error");
 const file_1 = require("./utils/file");
 const resource_locator_1 = require("./utils/resource-locator");
+const stamps_1 = require("./utils/stamps");
 const tokens_1 = require("./utils/tokens");
 const type_1 = require("./utils/type");
 const typed_bytes_1 = require("./utils/typed-bytes");
@@ -1158,14 +1159,60 @@ class Bee {
         }
         return stamp;
     }
+    async buyStorage(gigabytes, duration, options, requestOptions) {
+        const chainState = await this.getChainState(requestOptions);
+        const amount = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice);
+        const depth = (0, stamps_1.getDepthForSize)(gigabytes);
+        if (options) {
+            options = (0, type_1.preparePostageBatchOptions)(options);
+        }
+        return this.createPostageBatch(amount, depth, options, requestOptions);
+    }
+    async getStorageCost(gigabytes, duration, options) {
+        const chainState = await this.getChainState(options);
+        const amount = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice);
+        const depth = (0, stamps_1.getDepthForSize)(gigabytes);
+        return (0, stamps_1.getStampCost)(depth, amount);
+    }
+    async extendStorageSize(postageBatchId, gigabytes, options) {
+        const batch = await this.getPostageBatch(postageBatchId, options);
+        const depth = (0, stamps_1.getDepthForSize)(gigabytes);
+        const delta = depth - batch.depth;
+        if (delta <= 0) {
+            throw new error_1.BeeArgumentError('New depth has to be greater than the original depth', depth);
+        }
+        await this.topUpBatch(batch.batchID, BigInt(batch.amount) * 2n ** BigInt(delta - 1), options);
+        return this.diluteBatch(batch.batchID, depth, options);
+    }
+    async extendStorageDuration(postageBatchId, duration, options) {
+        const batch = await this.getPostageBatch(postageBatchId, options);
+        const chainState = await this.getChainState(options);
+        const amount = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice);
+        return this.topUpBatch(batch.batchID, amount, options);
+    }
+    async getSizeExtensionCost(postageBatchId, gigabytes, options) {
+        const batch = await this.getPostageBatch(postageBatchId, options);
+        const depth = (0, stamps_1.getDepthForSize)(gigabytes);
+        const delta = depth - batch.depth;
+        if (delta <= 0) {
+            throw new error_1.BeeArgumentError('New depth has to be greater than the original depth', depth);
+        }
+        const currentPaid = (0, stamps_1.getStampCost)(batch.depth, batch.amount);
+        const newPaid = (0, stamps_1.getStampCost)(depth, batch.amount);
+        return newPaid.minus(currentPaid);
+    }
+    async getDurationExtensionCost(postageBatchId, duration, options) {
+        const batch = await this.getPostageBatch(postageBatchId, options);
+        const chainState = await this.getChainState(options);
+        const amount = (0, stamps_1.getAmountForDuration)(duration, chainState.currentPrice);
+        return (0, stamps_1.getStampCost)(batch.depth, amount);
+    }
     /**
      * Topup a fresh amount of BZZ to given Postage Batch.
      *
      * For better understanding what each parameter means and what are the optimal values please see
      * [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive).
      *
-     * **WARNING: THIS CREATES TRANSACTIONS THAT SPENDS MONEY**
-     *
      * @param postageBatchId Batch ID
      * @param amount Amount to be added to the batch
      * @param options Request options
@@ -1185,8 +1232,6 @@ class Bee {
      * For better understanding what each parameter means and what are the optimal values please see
      * [Bee docs - Keep your data alive / Postage stamps](https://docs.ethswarm.org/docs/develop/access-the-swarm/introduction/#keep-your-data-alive).
      *
-     * **WARNING: THIS CREATES TRANSACTIONS THAT SPENDS MONEY**
-     *
      * @param postageBatchId Batch ID
      * @param depth Amount to be added to the batch
      * @param options Request options

package/dist/cjs/index.js

@@ -26,7 +26,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BeeDev = exports.Bee = exports.Utils = exports.Bytes = exports.SUPPORTED_BEE_VERSION_EXACT = exports.SUPPORTED_BEE_VERSION = exports.MantarayNode = exports.MerkleTree = void 0;
+exports.BeeDev = exports.Bee = exports.Utils = exports.Duration = exports.Bytes = exports.SUPPORTED_BEE_VERSION_EXACT = exports.SUPPORTED_BEE_VERSION = exports.MantarayNode = exports.MerkleTree = void 0;
 const bee_1 = require("./bee");
 Object.defineProperty(exports, "Bee", { enumerable: true, get: function () { return bee_1.Bee; } });
 const bee_dev_1 = require("./bee-dev");
@@ -42,6 +42,8 @@ __exportStar(require("./types"), exports);
 var bytes_1 = require("./utils/bytes");
 Object.defineProperty(exports, "Bytes", { enumerable: true, get: function () { return bytes_1.Bytes; } });
 __exportStar(require("./utils/constants"), exports);
+var duration_1 = require("./utils/duration");
+Object.defineProperty(exports, "Duration", { enumerable: true, get: function () { return duration_1.Duration; } });
 __exportStar(require("./utils/error"), exports);
 exports.Utils = __importStar(require("./utils/expose"));
 __exportStar(require("./utils/tokens"), exports);

package/dist/cjs/modules/debug/stamps.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.diluteBatch = exports.topUpBatch = exports.createPostageBatch = exports.getPostageBatchBuckets = exports.getPostageBatch = exports.getAllPostageBatches = exports.getGlobalPostageBatches = void 0;
 const cafe_utility_1 = require("cafe-utility");
+const duration_1 = require("../../utils/duration");
 const http_1 = require("../../utils/http");
+const stamps_1 = require("../../utils/stamps");
 const type_1 = require("../../utils/type");
 const typed_bytes_1 = require("../../utils/typed-bytes");
 const STAMPS_ENDPOINT = 'stamps';
@@ -35,19 +37,30 @@ async function getAllPostageBatches(requestOptions) {
     });
     const body = cafe_utility_1.Types.asObject(response.data, { name: 'response.data' });
     const stamps = cafe_utility_1.Types.asArray(body.stamps, { name: 'stamps' }).map(x => cafe_utility_1.Types.asObject(x, { name: 'stamp' }));
-    return stamps.map(x => ({
-        batchID: new typed_bytes_1.BatchId(cafe_utility_1.Types.asString(x.batchID, { name: 'batchID' })),
-        utilization: cafe_utility_1.Types.asNumber(x.utilization, { name: 'utilization' }),
-        usable: cafe_utility_1.Types.asBoolean(x.usable, { name: 'usable' }),
-        label: cafe_utility_1.Types.asEmptiableString(x.label, { name: 'label' }),
-        depth: cafe_utility_1.Types.asNumber(x.depth, { name: 'depth' }),
-        amount: (0, type_1.asNumberString)(x.amount, { name: 'amount' }),
-        bucketDepth: cafe_utility_1.Types.asNumber(x.bucketDepth, { name: 'bucketDepth' }),
-        blockNumber: cafe_utility_1.Types.asNumber(x.blockNumber, { name: 'blockNumber' }),
-        immutableFlag: cafe_utility_1.Types.asBoolean(x.immutableFlag, { name: 'immutableFlag' }),
-        exists: cafe_utility_1.Types.asBoolean(x.exists, { name: 'exists' }),
-        batchTTL: cafe_utility_1.Types.asNumber(x.batchTTL, { name: 'batchTTL' }),
-    }));
+    return stamps.map(x => {
+        const utilization = cafe_utility_1.Types.asNumber(x.utilization, { name: 'utilization' });
+        const depth = cafe_utility_1.Types.asNumber(x.depth, { name: 'depth' });
+        const bucketDepth = cafe_utility_1.Types.asNumber(x.bucketDepth, { name: 'bucketDepth' });
+        const usage = (0, stamps_1.getStampUsage)(utilization, depth, bucketDepth);
+        const batchTTL = cafe_utility_1.Types.asNumber(x.batchTTL, { name: 'batchTTL' });
+        const duration = duration_1.Duration.fromSeconds(batchTTL);
+        return {
+            batchID: new typed_bytes_1.BatchId(cafe_utility_1.Types.asString(x.batchID, { name: 'batchID' })),
+            utilization,
+            usable: cafe_utility_1.Types.asBoolean(x.usable, { name: 'usable' }),
+            label: cafe_utility_1.Types.asEmptiableString(x.label, { name: 'label' }),
+            depth,
+            amount: (0, type_1.asNumberString)(x.amount, { name: 'amount' }),
+            bucketDepth,
+            blockNumber: cafe_utility_1.Types.asNumber(x.blockNumber, { name: 'blockNumber' }),
+            immutableFlag: cafe_utility_1.Types.asBoolean(x.immutableFlag, { name: 'immutableFlag' }),
+            usage,
+            size: (0, stamps_1.getStampEffectiveBytes)(depth),
+            remainingSize: Math.ceil((0, stamps_1.getStampEffectiveBytes)(depth) * (1 - usage)),
+            theoreticalSize: (0, stamps_1.getStampTheoreticalBytes)(depth),
+            duration,
+        };
+    });
 }
 exports.getAllPostageBatches = getAllPostageBatches;
 async function getPostageBatch(requestOptions, postageBatchId) {
@@ -57,18 +70,27 @@ async function getPostageBatch(requestOptions, postageBatchId) {
         responseType: 'json',
     });
     const body = cafe_utility_1.Types.asObject(response.data, { name: 'response.data' });
+    const utilization = cafe_utility_1.Types.asNumber(body.utilization, { name: 'utilization' });
+    const depth = cafe_utility_1.Types.asNumber(body.depth, { name: 'depth' });
+    const bucketDepth = cafe_utility_1.Types.asNumber(body.bucketDepth, { name: 'bucketDepth' });
+    const usage = (0, stamps_1.getStampUsage)(utilization, depth, bucketDepth);
+    const batchTTL = cafe_utility_1.Types.asNumber(body.batchTTL, { name: 'batchTTL' });
+    const duration = duration_1.Duration.fromSeconds(batchTTL);
     return {
         batchID: new typed_bytes_1.BatchId(cafe_utility_1.Types.asString(body.batchID, { name: 'batchID' })),
-        utilization: cafe_utility_1.Types.asNumber(body.utilization, { name: 'utilization' }),
+        utilization,
         usable: cafe_utility_1.Types.asBoolean(body.usable, { name: 'usable' }),
         label: cafe_utility_1.Types.asEmptiableString(body.label, { name: 'label' }),
-        depth: cafe_utility_1.Types.asNumber(body.depth, { name: 'depth' }),
+        depth,
         amount: (0, type_1.asNumberString)(body.amount, { name: 'amount' }),
-        bucketDepth: cafe_utility_1.Types.asNumber(body.bucketDepth, { name: 'bucketDepth' }),
+        bucketDepth,
         blockNumber: cafe_utility_1.Types.asNumber(body.blockNumber, { name: 'blockNumber' }),
         immutableFlag: cafe_utility_1.Types.asBoolean(body.immutableFlag, { name: 'immutableFlag' }),
-        exists: cafe_utility_1.Types.asBoolean(body.exists, { name: 'exists' }),
-        batchTTL: cafe_utility_1.Types.asNumber(body.batchTTL, { name: 'batchTTL' }),
+        usage,
+        size: (0, stamps_1.getStampEffectiveBytes)(depth),
+        remainingSize: Math.ceil((0, stamps_1.getStampEffectiveBytes)(depth) * (1 - usage)),
+        theoreticalSize: (0, stamps_1.getStampTheoreticalBytes)(depth),
+        duration,
     };
 }
 exports.getPostageBatch = getPostageBatch;

package/dist/cjs/utils/constants.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NULL_IDENTIFIER = exports.NULL_ADDRESS = exports.NULL_TOPIC = exports.NULL_STAMP = exports.SWARM_GATEWAY_URL = void 0;
+exports.NULL_OWNER = exports.NULL_IDENTIFIER = exports.NULL_ADDRESS = exports.NULL_TOPIC = exports.NULL_STAMP = exports.SWARM_GATEWAY_URL = void 0;
 const typed_bytes_1 = require("./typed-bytes");
 exports.SWARM_GATEWAY_URL = 'https://api.gateway.ethswarm.org';
 exports.NULL_STAMP = new typed_bytes_1.BatchId('0000000000000000000000000000000000000000000000000000000000000000');
 exports.NULL_TOPIC = new typed_bytes_1.Topic('0000000000000000000000000000000000000000000000000000000000000000');
 exports.NULL_ADDRESS = new Uint8Array(32);
 exports.NULL_IDENTIFIER = new Uint8Array(32);
+exports.NULL_OWNER = new Uint8Array(20);

package/dist/cjs/utils/duration.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Duration = void 0;
+class Duration {
+    constructor(seconds) {
+        this.seconds = Math.ceil(seconds);
+        if (seconds <= 0) {
+            throw Error('Duration must be greater than 0');
+        }
+    }
+    static fromSeconds(seconds) {
+        return new Duration(seconds);
+    }
+    static fromHours(hours) {
+        return new Duration(hours * 60 * 60);
+    }
+    static fromDays(days) {
+        return new Duration(days * 24 * 60 * 60);
+    }
+    static fromWeeks(weeks) {
+        return new Duration(weeks * 7 * 24 * 60 * 60);
+    }
+    static fromYears(years) {
+        return new Duration(years * 365 * 24 * 60 * 60);
+    }
+    static fromEndDate(endDate, startDate) {
+        return new Duration((endDate.getTime() - (startDate ?? new Date()).getTime()) / 1000);
+    }
+    toSeconds() {
+        return this.seconds;
+    }
+    toHours() {
+        return this.seconds / 60 / 60;
+    }
+    toDays() {
+        return this.seconds / 24 / 60 / 60;
+    }
+    toWeeks() {
+        return this.seconds / 7 / 24 / 60 / 60;
+    }
+    toYears() {
+        return this.seconds / 365 / 24 / 60 / 60;
+    }
+    toEndDate(startDate) {
+        return new Date((startDate ?? new Date()).getTime() + this.seconds * 1000);
+    }
+}
+exports.Duration = Duration;

package/dist/cjs/utils/expose.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getStampUsage = exports.getStampTtlSeconds = exports.getStampMaximumCapacityBytes = exports.getStampEffectiveBytes = exports.getStampCost = exports.getDepthForCapacity = exports.getAmountForTtl = exports.getRedundancyStats = exports.getRedundancyStat = exports.approximateOverheadForRedundancyLevel = exports.makeMaxTarget = exports.getFolderSize = exports.makeCollectionFromFileList = exports.getCollectionSize = void 0;
+exports.getStampUsage = exports.getStampTheoreticalBytes = exports.getStampEffectiveBytes = exports.getStampDuration = exports.getStampCost = exports.getDepthForSize = exports.getAmountForDuration = exports.getRedundancyStats = exports.getRedundancyStat = exports.approximateOverheadForRedundancyLevel = exports.makeMaxTarget = exports.getFolderSize = exports.makeCollectionFromFileList = exports.getCollectionSize = void 0;
 var collection_1 = require("./collection");
 Object.defineProperty(exports, "getCollectionSize", { enumerable: true, get: function () { return collection_1.getCollectionSize; } });
 Object.defineProperty(exports, "makeCollectionFromFileList", { enumerable: true, get: function () { return collection_1.makeCollectionFromFileList; } });
@@ -13,10 +13,10 @@ Object.defineProperty(exports, "approximateOverheadForRedundancyLevel", { enumer
 Object.defineProperty(exports, "getRedundancyStat", { enumerable: true, get: function () { return redundancy_1.getRedundancyStat; } });
 Object.defineProperty(exports, "getRedundancyStats", { enumerable: true, get: function () { return redundancy_1.getRedundancyStats; } });
 var stamps_1 = require("./stamps");
-Object.defineProperty(exports, "getAmountForTtl", { enumerable: true, get: function () { return stamps_1.getAmountForTtl; } });
-Object.defineProperty(exports, "getDepthForCapacity", { enumerable: true, get: function () { return stamps_1.getDepthForCapacity; } });
+Object.defineProperty(exports, "getAmountForDuration", { enumerable: true, get: function () { return stamps_1.getAmountForDuration; } });
+Object.defineProperty(exports, "getDepthForSize", { enumerable: true, get: function () { return stamps_1.getDepthForSize; } });
 Object.defineProperty(exports, "getStampCost", { enumerable: true, get: function () { return stamps_1.getStampCost; } });
+Object.defineProperty(exports, "getStampDuration", { enumerable: true, get: function () { return stamps_1.getStampDuration; } });
 Object.defineProperty(exports, "getStampEffectiveBytes", { enumerable: true, get: function () { return stamps_1.getStampEffectiveBytes; } });
-Object.defineProperty(exports, "getStampMaximumCapacityBytes", { enumerable: true, get: function () { return stamps_1.getStampMaximumCapacityBytes; } });
-Object.defineProperty(exports, "getStampTtlSeconds", { enumerable: true, get: function () { return stamps_1.getStampTtlSeconds; } });
+Object.defineProperty(exports, "getStampTheoreticalBytes", { enumerable: true, get: function () { return stamps_1.getStampTheoreticalBytes; } });
 Object.defineProperty(exports, "getStampUsage", { enumerable: true, get: function () { return stamps_1.getStampUsage; } });

package/dist/cjs/utils/stamps.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.marshalStamp = exports.convertEnvelopeToMarshaledStamp = exports.getDepthForCapacity = exports.getAmountForTtl = exports.getStampTtlSeconds = exports.getStampCost = exports.getStampEffectiveBytes = exports.getStampMaximumCapacityBytes = exports.getStampUsage = void 0;
+exports.marshalStamp = exports.convertEnvelopeToMarshaledStamp = exports.getDepthForSize = exports.getAmountForDuration = exports.getStampDuration = exports.getStampCost = exports.getStampEffectiveBytes = exports.getStampTheoreticalBytes = exports.getStampUsage = void 0;
 const cafe_utility_1 = require("cafe-utility");
 const bytes_1 = require("./bytes");
+const duration_1 = require("./duration");
 const tokens_1 = require("./tokens");
 const type_1 = require("./type");
 /**
@@ -17,16 +18,16 @@ function getStampUsage(utilization, depth, bucketDepth) {
 }
 exports.getStampUsage = getStampUsage;
 /**
- * Utility function that calculates the theoritical maximum capacity of a postage batch based on its depth.
+ * Utility function that calculates the theoritical maximum size of a postage batch based on its depth.
  *
- * For smaller depths (up to 20), this may provide less accurate results.
+ * For smaller depths (up to 22), this may provide less accurate results.
  *
- * @returns {number} The maximum capacity of the postage batch in bytes.
+ * @returns {number} The maximum theoretical size of the postage batch in bytes.
  */
-function getStampMaximumCapacityBytes(depth) {
-    return 2 ** depth * 4096;
+function getStampTheoreticalBytes(depth) {
+    return 4096 * 2 ** depth;
 }
-exports.getStampMaximumCapacityBytes = getStampMaximumCapacityBytes;
+exports.getStampTheoreticalBytes = getStampTheoreticalBytes;
 /**
  * Based on https://docs.ethswarm.org/docs/learn/technology/contracts/postage-stamp/#effective-utilisation-table
  */
@@ -45,20 +46,34 @@ const utilisationRateMap = {
     33: 0.9842,
     34: 0.9889,
 };
+const effectiveSizeBreakpoints = [
+    [22, 4.93],
+    [23, 17.03],
+    [24, 44.21],
+    [25, 102.78],
+    [26, 225.86],
+    [27, 480.43],
+    [28, 1.0],
+    [29, 2.06],
+    [30, 4.2],
+    [31, 8.52],
+    [32, 17.2],
+    [33, 34.63],
+];
 /**
- * Utility function that calculates the effective volume of a postage batch based on its depth.
+ * Utility function that calculates the effective size of a postage batch based on its depth.
  *
- * Below 22 depth the effective volume is 0
+ * Below 22 depth the effective size is 0
  * Above 34 it's always > 99%
  *
- * @returns {number} The effective volume of the postage batch in bytes.
+ * @returns {number} The effective size of the postage batch in bytes.
  */
 function getStampEffectiveBytes(depth) {
     if (depth < 22) {
         return 0;
     }
     const utilRate = utilisationRateMap[depth] ?? 0.99;
-    return getStampMaximumCapacityBytes(depth) * utilRate;
+    return Math.ceil(getStampTheoreticalBytes(depth) * utilRate);
 }
 exports.getStampEffectiveBytes = getStampEffectiveBytes;
 /**
@@ -74,37 +89,39 @@ exports.getStampCost = getStampCost;
  *
  * For more accurate results, get the price per block and block time from the Bee node or the blockchain.
  *
- * @returns {number} The TTL of the postage batch in seconds.
+ * @returns {number} The TTL of the postage batch.
  */
-function getStampTtlSeconds(amount, pricePerBlock = 24000, blockTime = 5) {
+function getStampDuration(amount, pricePerBlock, blockTime = 5) {
     const amountBigInt = BigInt((0, type_1.asNumberString)(amount));
-    return (amountBigInt * BigInt(blockTime)) / BigInt(pricePerBlock);
+    return duration_1.Duration.fromSeconds(Number((amountBigInt * BigInt(blockTime)) / BigInt(pricePerBlock)));
 }
-exports.getStampTtlSeconds = getStampTtlSeconds;
+exports.getStampDuration = getStampDuration;
 /**
- * Utility function that calculates the amount of tokens required to maintain a given Time To Live (TTL) for a postage batch.
- *
- * This function estimates the required amount based on the provided TTL in days.
+ * Get the postage batch `amount` required for a given `duration`.
  *
- * @param {number} days - The Time To Live (TTL) in days.
- * @returns {NumberString} The estimated amount of tokens needed for the specified TTL.
+ * @param duration A duration object representing the duration of the storage.
+ * @param pricePerBlock The price per block in PLUR.
+ * @param blockTime The block time in seconds.
  */
-function getAmountForTtl(days, pricePerBlock = 24000, blockTime = 5) {
-    return (days <= 0 ? 1n : BigInt(days)) * ((24n * 60n * 60n * BigInt(pricePerBlock)) / BigInt(blockTime));
+function getAmountForDuration(duration, pricePerBlock, blockTime = 5) {
+    return (BigInt(duration.toSeconds()) / BigInt(blockTime)) * BigInt(pricePerBlock);
 }
-exports.getAmountForTtl = getAmountForTtl;
+exports.getAmountForDuration = getAmountForDuration;
 /**
- * Utility function that calculates the depth required for a postage batch to achieve the specified capacity in gigabytes.
+ * Utility function that calculates the depth required for a postage batch to achieve the specified effective size in gigabytes.
  *
- * The depth is determined based on the given gigabytes, and the result is adjusted to a minimum depth of 18.
- *
- * @param {number} gigabytes - The desired capacity of the postage batch in gigabytes.
- * @returns {number} The calculated depth necessary to achieve the specified capacity.
+ * @param gigabytes
+ * @returns
  */
-function getDepthForCapacity(gigabytes) {
-    return gigabytes <= 1 ? 18 : Math.ceil(Math.log2(Math.ceil(gigabytes)) + 18);
+function getDepthForSize(gigabytes) {
+    for (const [depth, size] of effectiveSizeBreakpoints) {
+        if (gigabytes <= size) {
+            return depth;
+        }
+    }
+    return 34;
 }
-exports.getDepthForCapacity = getDepthForCapacity;
+exports.getDepthForSize = getDepthForSize;
 function convertEnvelopeToMarshaledStamp(envelope) {
     return marshalStamp(envelope.signature, envelope.batchId.toUint8Array(), envelope.timestamp, envelope.index);
 }