@waldrop/sdk

TypeScript SDK for Waldrop - upload, fetch, encrypt, and cost-estimate Walrus blobs on Sui.

A thin wrapper around the Walrus HTTP API and the Waldrop Sui contract. No dapp backend required.

Install

bun add @waldrop/sdk @mysten/sui
# Optional - only for encrypt / decrypt
bun add @mysten/seal

Quickstart

import { WaldropClient } from "@waldrop/sdk";

const waldrop = new WaldropClient({ network: "testnet" });

// List a user's blobs
const blobs = await waldrop.blob.list({ owner: "0x..." });

// Fetch one
const { bytes, contentType } = await waldrop.blob.fetch({
  blobId: blobs[0].blobId,
});

What's in the box

// Upload
await waldrop.blob.upload({ data, fileName, contentType, epochs, signer });
await waldrop.blob.uploadBundle({ files: [...], signer });
await waldrop.blob.registerOnly({ blobId, ... }); // resume a failed upload

// Read
await waldrop.blob.list({ owner });             // → BlobRef[]
await waldrop.blob.fetch({ blobId });           // → { bytes, contentType }
await waldrop.blob.getStore({ owner });         // → summary stats

// Crypto (requires @mysten/seal)
await waldrop.crypto.encrypt({ data, blobStoreId });
await waldrop.crypto.decrypt({ bytes, blobStoreId, signer });

// Cost
await waldrop.cost.estimate({ bytesPerBlob, epochs });

// Sharing
await waldrop.blob.listViewers({ blobStoreId });
await waldrop.blob.canView({ blobStoreId, viewer });

// Subscription
await waldrop.subscription.get({ owner });
await waldrop.subscription.isActive({ owner });

Upload example

The signer must be @mysten/sui's Signer (or Ed25519Keypair). In a dapp, use dapp-kit's signAndExecuteTransaction; in a script, use an Ed25519Keypair.

import { WaldropClient } from "@waldrop/sdk";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";

const keypair = Ed25519Keypair.fromSecretKey(process.env.SUI_PRIVATE_KEY!);
const waldrop = new WaldropClient({ network: "testnet" });

const result = await waldrop.blob.upload({
  data: new TextEncoder().encode("hello waldrop"),
  fileName: "hello.txt",
  contentType: "text/plain",
  epochs: 5,
  signer: keypair,
});

console.log(result.blobId);

See examples/ for more.

Errors

The SDK throws typed errors you can narrow on:

import {
  WaldropError,
  BlobNotFoundError,
  DecryptionError,
  SealNotInstalledError,
  AggregatorError,
  InsufficientGasError,
} from "@waldrop/sdk";

try {
  await waldrop.blob.fetch({ blobId });
} catch (err) {
  if (err instanceof BlobNotFoundError) {
    // ...
  }
}

Wallet signatures

Only one wallet prompt per upload — the on-chain register_blob call. SHA-256 hashing, SEAL encryption, and the Walrus publisher PUT all run without any signature.

Decryption requires one signature too (for the SEAL session key).

Networks

Testnet defaults are baked in. Override for mainnet or custom infra:

new WaldropClient({
  network: "mainnet",
  suiGrpcUrl: "https://...",
  walrusAggregatorUrl: "https://...",
  walrusPublisherUrl: "https://...",
});

Versioning

Semver. Anything not exported from src/index.ts is internal and may change between minor releases.

License

MIT © 2026 Waldrop