Waldrop SDK · API Reference

client.cost

Live Walrus storage cost forecasting. Reads the on-chain Walrus System object (versioned dynamic field) and applies the same math the dapp's wizard renders.

estimate

client.cost.estimate(args: EstimateArgs): Promise<EstimateResult>

Forecast the cost of storing bytesPerBlob × numBlobs for epochs Walrus epochs. Pricing is fetched live unless you pass args.pricing (useful for memoizing inside a UI render loop).

const r = await client.cost.estimate({
  bytesPerBlob: 10 * 1024 * 1024,    // 10 MiB
  numBlobs: 1,
  epochs: 26,
});

console.log(`${r.totalWal.toFixed(6)} WAL`);
console.log(`storage ${r.storageFrost} FROST`);
console.log(`write   ${r.writeFrost}   FROST`);
console.log(`units   ${r.totalUnits} × 1 MiB`);

Args

FieldTypeDescription
bytesPerBlobnumberRaw payload size in bytes.
numBlobsnumber?Default 1.
epochsnumberWalrus epochs of storage.
pricingWalrusSystemSnapshot?Skip the live fetch by passing a memoized snapshot.

Result

interface EstimateResult {
  totalFrost: number;
  storageFrost: number;        // units × price-per-epoch × epochs
  writeFrost: number;          // units × write-price (one-time)
  totalUnits: number;          // 1 MiB encoded storage units
  totalWal: number;            // totalFrost / 1e9
  isAvailable: boolean;        // false when pricing came back empty
  pricing: WalrusSystemSnapshot;
}

The math:

encoded_bytes = raw_bytes × 5            // 5× redundancy, safe upper bound
units_per_blob = ceil(encoded_bytes / 1 MiB)
total_units = units_per_blob × num_blobs

storage_cost = total_units × storage_price_per_unit × epochs
write_cost   = total_units × write_price_per_unit          // one-time
total        = storage_cost + write_cost
Why 5× redundancy

Walrus encodes data with RaptorQ + erasure coding across storage shards. The exact factor depends on n_shards, but 5× is a safe upper bound for UI display. The publisher does an authoritative calculation at PUT time, so this estimate is approximate but tightly bounded.

getPricing

client.cost.getPricing(): Promise<WalrusSystemSnapshot>

Just the live Walrus pricing snapshot — useful if you want to memoize and run calculateCost() yourself.

interface WalrusSystemSnapshot {
  currentEpoch: number;                  // committee epoch
  epochDurationMs: number;               // 0 when not on System object
  epochDays: number;                     // rounded, 0 when unavailable
  storagePricePerUnitFrost: number;      // FROST / unit / epoch
  writePricePerUnitFrost: number;        // FROST / unit (one-time)
  isAvailable: boolean;                  // both prices > 0
}
Where pricing lives on-chain

The Walrus System wrapper exposes only { id, version, package_id }. The actual prices live in a dynamic object field keyed by u64 = version. The SDK derives the field id via deriveDynamicFieldID and reads it — the same path @mysten/walrus's WalrusClient.systemState() uses, but without pulling in the full Walrus SDK as a dep.

Power-user

Both helpers are also exported standalone:

import { calculateCost, readWalrusSystem, WALRUS_SYSTEM_OBJECTS } from "@waldrop/sdk";

const pricing = await readWalrusSystem(suiClient, "testnet");
const breakdown = calculateCost({
  bytesPerBlob: 10 * 1024 * 1024,
  numBlobs: 1,
  epochs: 26,
  storagePricePerUnitFrost: pricing.storagePricePerUnitFrost,
  writePricePerUnitFrost: pricing.writePricePerUnitFrost,
});
Edit this page on GitHub ↗
Waldrop · 2026cryptokarigar