@meddleware/walrus-client 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-08-27
+
+### Added
+
+- Initial release as `@meddleware/walrus-client` (renamed from internal `@meddleware/sui-walrus`)
+- `createWalrusClient()` — configurable Walrus client factory with upload relay, WASM, and `rpcUrl` override support
+- `uploadBytes` / `uploadLocalFile` — Node.js and browser blob upload (quilt)
+- `uploadImageBytes` / `createBlobUploadFlow` — raw-blob variants for wallet/explorer-renderable assets
+- `createUploadFlow` — multi-step browser upload flow for wallet-popup-safe signing
+- `extendBlobLifetime` / `extendBlobLifetimeTransaction` — extend blob storage before expiry
+- `setBlobAttributes` / `setBlobAttributesTransaction` / `readBlobAttributes` — on-chain metadata management
+- `fetchOwnedWalrusBlobs` — enumerate all Walrus blobs owned by an address (dynamic type resolution, no hardcoded addresses)
+- `createRelayAccessToken` / `buildAccessProofToken` / `fetchRelayChallenge` — NFT-gated relay access helpers
+- Exported constants: `DEFAULT_RPC_URLS`, `PUBLIC_UPLOAD_RELAY_HOSTS`, `WALRUS_AGGREGATOR_HOSTS`
+- `disableUploadRelay` option to bypass relay and write directly to Walrus storage nodes

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 MeddleWare
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# @meddleware/walrus-client
+
+Walrus decentralised storage client and asset management utilities for Sui applications.
+
+[![License: 0BSD](https://img.shields.io/badge/License-0BSD-blue.svg)](LICENSE)
+
+This package provides configuration, upload helpers, and lifetime management for storing assets (images, metadata, documents) on Walrus — a decentralised storage network integrated with Sui. It works in both Node.js (scripts, deployment tools) and the browser (Vite apps with wallet signing).
+
+## Product semantics
+
+**Walrus is NOT permanent storage.** All blobs expire after their epoch count runs out. A Walrus epoch is approximately 2 weeks.
+
+- Recommended default: **200 epochs** ≈ 7.7 years (exported as `LONG_TERM_EPOCHS`)
+- **Before expiry:** Use `extendBlobLifetime()` to renew the blob
+- **Deletable blobs:** Set `deletable: true` only if cleanup is guaranteed before expiry; otherwise blobs cannot be recovered
+
+> A single Walrus reservation cannot exceed `max_epochs_ahead` (53 on testnet/mainnet, exported as `MAX_SINGLE_RESERVATION_EPOCHS`). Reaching `LONG_TERM_EPOCHS` requires periodic renewal via `extendBlobLifetime()`.
+
+## Quick start
+
+### Node.js (deployment script)
+
+```typescript
+import { createWalrusClient, uploadLocalFile, LONG_TERM_EPOCHS } from '@meddleware/walrus-client'
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
+import * as fs from 'node:fs'
+
+const keypair = Ed25519Keypair.fromSecretKey(fs.readFileSync('.secrets/keypair', 'utf-8'))
+const client = createWalrusClient({ network: 'mainnet' })
+
+const { blobId } = await uploadLocalFile(
+  client,
+  'assets/icon.png',
+  'icon.png',
+  keypair,
+  { epochs: LONG_TERM_EPOCHS, deletable: false },
+)
+
+console.log('Uploaded blob:', blobId)
+```
+
+### Browser (Vite app)
+
+```typescript
+// vite.config.ts or similar
+import walrusWasmUrl from '@mysten/walrus-wasm/web/walrus_wasm_bg.wasm?url'
+
+// In a composable or component
+import { createWalrusClient, createUploadFlow } from '@meddleware/walrus-client'
+
+const client = createWalrusClient({ network: 'testnet', wasmUrl: walrusWasmUrl })
+
+// Step 1: Create the flow (can happen immediately when file is selected)
+const flow = createUploadFlow(client, fileBytes, 'my-asset.png')
+
+// Step 2: Register (user clicks a button, signs with wallet)
+const registerTx = flow.register({ epochs: 200, owner: address })
+const result = await signAndExecuteTransaction({ transaction: registerTx })
+
+// Step 3: Upload to storage nodes
+await flow.upload({ digest: result.digest })
+
+// Step 4: Certify on-chain (user clicks another button, signs with wallet)
+const certifyTx = flow.certify()
+await signAndExecuteTransaction({ transaction: certifyTx })
+
+const files = await flow.listFiles()
+console.log('Uploaded blob ID:', files[0].blobId)
+```
+
+## API Reference
+
+### Client Factory
+
+**`createWalrusClient(options?): WalrusClient`**
+
+Creates and configures a Walrus client. Called once per session.
+
+```typescript
+const client = createWalrusClient({
+  network: 'testnet',             // 'testnet' | 'mainnet' (default: 'testnet')
+  rpcUrl: '...',                  // Optional: override the Sui fullnode URL
+  wasmUrl: '...',                 // Required for browser/Vite; ignored in Node.js
+  uploadRelayHost: '...',         // Optional upload relay URL
+  uploadRelayAuthToken: '...',    // Optional Bearer token for NFT-gated relay access
+  uploadRelayMaxTipMist: 1000000, // Optional tip max in MIST (default: 1_000_000)
+  disableUploadRelay: false,      // Bypass the relay entirely (direct to storage nodes)
+})
+```
+
+### Upload (Node.js & Browser)
+
+**`uploadBytes(client, contents, identifier, signer, options?): Promise<UploadResult>`**
+
+Core upload function (stores a quilt). Works in Node.js and browser.
+
+**`uploadLocalFile(client, filePath, identifier, signer, options?): Promise<UploadResult>`**
+
+Node.js only. Reads a file from disk and uploads it.
+
+**`createUploadFlow(client, contents, identifier, options?): WriteFilesFlow`**
+
+Browser only. Returns a multi-step flow for wallet-popup-safe signing.
+
+**`uploadImageBytes(client, contents, signer, options?): Promise<UploadResult>`** /
+**`createBlobUploadFlow(client, contents): WriteBlobFlow`**
+
+Raw-blob variants (Node.js / browser). Use these for assets that must be served directly by their blob URL (e.g. an image rendered by wallets/explorers): `GET /v1/blobs/<blobId>` returns the exact bytes. `uploadBytes`/`createUploadFlow` store a quilt instead, whose blob id does not resolve to the raw file.
+
+**Options:**
+
+```typescript
+{
+  epochs?: number               // Number of epochs to store (default: MAX_SINGLE_RESERVATION_EPOCHS)
+  deletable?: boolean           // Deletable by owner (default: false)
+  tags?: Record<string, string> // Optional metadata tags
+}
+```
+
+**Constants:**
+
+```typescript
+export const MAX_SINGLE_RESERVATION_EPOCHS = 53 // Walrus `max_epochs_ahead`
+export const LONG_TERM_EPOCHS = 200             // ~7.7 years target (needs renewal)
+```
+
+### Lifetime Extension
+
+**`extendBlobLifetime(client, blobObjectId, signer, options): Promise<{ digest: string }>`**
+
+Extend a blob's storage lifetime before expiry.
+
+**`extendBlobLifetimeTransaction(client, blobObjectId, options): Transaction`**
+
+Browser variant. Returns a transaction for wallet signing.
+
+**Options:**
+
+```typescript
+{ epochs: number }      // Add N more epochs
+// OR
+{ endEpoch: number }    // Extend to a specific Sui epoch number
+```
+
+### Metadata (Attributes)
+
+**`setBlobAttributes(client, blobObjectId, signer, attributes): Promise<{ digest: string }>`**
+
+Set or update on-chain key-value metadata.
+
+**`setBlobAttributesTransaction(client, blobObjectId, attributes): Transaction`**
+
+Browser variant. Returns a transaction for wallet signing.
+
+**`readBlobAttributes(client, blobObjectId): Promise<Record<string, string> | null>`**
+
+Read current attributes.
+
+### Query
+
+**`fetchOwnedWalrusBlobs(suiClient, walrusClient, owner): Promise<OwnedBlob[]>`**
+
+Enumerate all Walrus blobs owned by an address (resolves the Blob struct type dynamically, so no package addresses are hardcoded). Returns `{ objectId, blobId, size, endEpoch, certified }` entries.
+
+### NFT-gated relay access
+
+When the upload relay is protected by an `nft-gate` auth gateway, the caller must present a wallet-signed access proof. Use `createRelayAccessToken` to produce the Bearer token:
+
+```typescript
+import { createRelayAccessToken, createWalrusClient } from '@meddleware/walrus-client'
+
+const token = await createRelayAccessToken({
+  relayHost: 'https://sui-walrus-relay-testnet.meddleware.co.uk',
+  address: walletAddress,
+  sign: (msg) => wallet.signPersonalMessage({ message: msg }),
+})
+
+const client = createWalrusClient({
+  network: 'testnet',
+  uploadRelayAuthToken: token,
+})
+```
+
+### Re-exports
+
+- `WalrusFile` — Construct files from `Uint8Array`, `Blob`, or `string`
+- `RetryableWalrusClientError` — For retry logic during epoch transitions
+
+### Exported constants
+
+| Export | Description |
+|---|---|
+| `DEFAULT_RPC_URLS` | Default Sui fullnode URLs per network |
+| `PUBLIC_UPLOAD_RELAY_HOSTS` | Public Mysten-operated upload relay hosts (default when no `uploadRelayHost` is passed) |
+| `WALRUS_AGGREGATOR_HOSTS` | Public Walrus aggregator hosts |
+| `TESTNET_WALRUS_PACKAGE_CONFIG` | Walrus package config for testnet |
+| `MAINNET_WALRUS_PACKAGE_CONFIG` | Walrus package config for mainnet |
+
+## Prerequisites
+
+### Sui Keypair (Node.js)
+
+A `Signer` from `@mysten/sui/cryptography` with sufficient SUI to cover:
+
+- Registration transaction gas
+- Certification transaction gas
+- WAL token balance to pay for blob storage duration (in MIST)
+
+### Browser Wallet
+
+A connected Sui wallet (`@mysten/dapp-kit-core`, Sui Wallet, Movemen) to sign transactions.
+
+### Network
+
+- **Testnet:** Walrus testnet storage nodes; standard Sui testnet RPC
+- **Mainnet:** Walrus mainnet storage nodes; standard Sui mainnet RPC
+
+Network endpoints are defined in `src/client.ts` and exported as `DEFAULT_RPC_URLS`.
+
+### Upload relay
+
+`createWalrusClient` falls back to the MeddleWare upload relay when no `uploadRelayHost` is supplied. An upload relay is REQUIRED for browser uploads (direct-to-storage-node writes fail from browsers). To upload directly to Walrus storage nodes with **no** relay (e.g. from Node.js, or when the relay infra is unavailable), pass `disableUploadRelay: true`:
+
+```ts
+const client = createWalrusClient({ network: 'testnet', disableUploadRelay: true })
+```
+
+`disableUploadRelay` overrides both an explicit `uploadRelayHost` and the default fallback. To point at a public Mysten relay instead, use `PUBLIC_UPLOAD_RELAY_HOSTS[network]` as the `uploadRelayHost`.
+
+## Testing
+
+```bash
+npm run type-check   # tsc --noEmit (types only)
+npm test             # vitest run (mocked-client unit tests)
+```
+
+The unit suite (`tests/`) uses a mocked `WalrusClient` to assert the behaviour type-checking cannot: safe-default threading (`deletable:false`, default epochs), options passthrough, the `ExtendOptions` XOR, the wallet-safe `*Transaction`/flow variants, the `disableUploadRelay` path, and owned-blob parsing. `vitest` is a **dev-only** dependency; its transitive `esbuild` advisories affect only the local test dev-server and do not reach the shipped source package (runtime deps `@mysten/sui` / `@mysten/walrus` are tilde-pinned — run `npm ci`, not `npm install`, in CI/deploy).
+
+**Opt-in testnet integration check** (not automated — requires a funded testnet `Signer` + WAL): upload a small blob via `uploadBytes`, read it back via `readBlobAttributes`, then `extendBlobLifetime`, and confirm the digest/attributes. Run manually before relying on the package in a deploy pipeline.
+
+## Maintenance
+
+### Before blobs expire
+
+Blobs expire after their epoch count. A maintenance script should periodically extend critical blobs:
+
+```typescript
+const client = createWalrusClient({ network: 'mainnet' })
+const keypair = loadKeypair() // Your operational keypair
+
+for (const blobId of criticalBlobs) {
+  const { digest } = await extendBlobLifetime(
+    client,
+    blobId,
+    keypair,
+    { epochs: 50 }, // Extend by another 50 epochs (<= MAX_SINGLE_RESERVATION_EPOCHS)
+  )
+  console.log('Extended blob', blobId, 'in tx', digest)
+}
+```
+
+Run this task on a schedule (e.g., weekly) to prevent expiry.
+
+## Errors
+
+**`RetryableWalrusClientError`** is thrown during Sui epoch transitions when the client's cached state becomes stale.
+
+```typescript
+try {
+  await uploadBytes(...)
+} catch (error) {
+  if (error instanceof RetryableWalrusClientError) {
+    client.walrus.reset()
+    // Retry the operation
+  }
+}
+```
+
+## Further reading
+
+- [Walrus SDK documentation](https://docs.walrus.space/)
+- [Sui TypeScript SDK](https://sui-typescript-docs.vercel.app/)
+- Package notes: [CLAUDE.md](CLAUDE.md) · agent policy: [AGENTS.md](AGENTS.md)
+- Self-hosted relay: canonical location `infrastructure/k8s/walrus-relay` in the vault monorepo
+
+## License
+
+[0BSD](LICENSE)

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@meddleware/walrus-client",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Walrus decentralised storage client and asset management utilities for Sui applications.",
+  "author": "MeddleWare <meddleware@proton.me>",
+  "license": "0BSD",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meddleware-org/walrus-client.git"
+  },
+  "keywords": ["walrus", "sui", "decentralised-storage", "web3"],
+  "files": [
+    "src",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@mysten/sui": "~2.17.0",
+    "@mysten/walrus": "~1.1.7"
+  },
+  "devDependencies": {
+    "@types/node": "~24.12.2",
+    "typescript": "^6.0.0",
+    "vitest": "~2.1.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/access.ts

@@ -0,0 +1,91 @@
+/**
+ * NFT-gated relay access helpers.
+ *
+ * When the MeddleWare upload relay runs behind an `nft-gate` auth gateway, an upload must
+ * carry a wallet-signed **access proof** proving the caller holds the required access NFT.
+ * These helpers build that proof; the resulting token is passed to
+ * `createWalrusClient({ uploadRelayAuthToken })`, which threads it as the relay
+ * `Authorization: Bearer` header (see `client.ts`).
+ *
+ * The wire format mirrors `@meddleware/nft-gate-client` (challenge, signed message, and
+ * base64-JSON proof token). It is duplicated here — rather than depended upon — so this
+ * package stays self-contained; the gateway (`nft-gate-gateway`) is the authority that
+ * verifies these proofs.
+ *
+ * TODO(unify): once `@meddleware/nft-gate-client` is published (from the `nft-gate`
+ * standalone workspace, canonical vault location `blockchain/sui/packages/nft-gate-client-sui/`),
+ * import `fetchChallenge`/`buildAccessProof`/`personalMessageForNonce` from it and delete the
+ * duplicated logic below (keep this module as the thin Walrus-facing wrapper).
+ */
+
+/** A server-issued, time-bound challenge from the gateway's `GET /v1/challenge`. */
+export interface RelayChallenge {
+  nonce: string
+  expiresAt: number
+}
+
+/** The proof payload; `consumeDigest` is present only for single-use gates. */
+export interface AccessProofInput {
+  address: string
+  nonce: string
+  signature: string
+  consumeDigest?: string
+}
+
+/** A wallet personal-message signer (e.g. wallet-standard `sui:signPersonalMessage`). */
+export type PersonalMessageSigner = (message: Uint8Array) => Promise<{ signature: string }>
+
+/** The exact bytes the wallet signs for a nonce. MUST match the gateway's derivation. */
+export function personalMessageForNonce(nonce: string): Uint8Array {
+  return new TextEncoder().encode(`nft-gate:access:${nonce}`)
+}
+
+function toBase64(s: string): string {
+  return typeof btoa === 'function' ? btoa(s) : Buffer.from(s, 'utf-8').toString('base64')
+}
+
+/** Encode a proof as the base64(JSON) Bearer token the relay auth header carries. */
+export function buildAccessProofToken(proof: AccessProofInput): string {
+  const payload: AccessProofInput = {
+    address: proof.address,
+    nonce: proof.nonce,
+    signature: proof.signature,
+  }
+  if (proof.consumeDigest) payload.consumeDigest = proof.consumeDigest
+  return toBase64(JSON.stringify(payload))
+}
+
+/** Fetch a fresh challenge from the gateway. Tolerates `expiresAt` or `expires_at`. */
+export async function fetchRelayChallenge(
+  relayHost: string,
+  opts: { signal?: AbortSignal } = {},
+): Promise<RelayChallenge> {
+  const res = await fetch(`${relayHost.replace(/\/$/, '')}/v1/challenge`, { signal: opts.signal })
+  if (!res.ok) throw new Error(`challenge request failed: ${res.status}`)
+  const data = (await res.json()) as { nonce?: string; expiresAt?: number; expires_at?: number }
+  if (!data || typeof data.nonce !== 'string') throw new Error('challenge response missing nonce')
+  return { nonce: data.nonce, expiresAt: data.expiresAt ?? data.expires_at ?? 0 }
+}
+
+/**
+ * One-shot: fetch a challenge, sign it with the wallet, and return the token to pass as
+ * `createWalrusClient({ uploadRelayAuthToken })`. For single-use gates, supply the
+ * `consumeDigest` of the on-chain consume transaction first.
+ */
+export async function createRelayAccessToken(opts: {
+  relayHost: string
+  address: string
+  sign: PersonalMessageSigner
+  consumeDigest?: string
+  signal?: AbortSignal
+}): Promise<string> {
+  const challenge = await fetchRelayChallenge(opts.relayHost, { signal: opts.signal })
+  const message = personalMessageForNonce(challenge.nonce)
+  const { signature } = await opts.sign(message)
+  return buildAccessProofToken({
+    address: opts.address,
+    nonce: challenge.nonce,
+    signature,
+    consumeDigest: opts.consumeDigest,
+  })
+}

package/src/client.ts

@@ -0,0 +1,95 @@
+import { SuiGrpcClient } from '@mysten/sui/grpc'
+import { walrus, TESTNET_WALRUS_PACKAGE_CONFIG, MAINNET_WALRUS_PACKAGE_CONFIG } from '@mysten/walrus'
+
+export { TESTNET_WALRUS_PACKAGE_CONFIG, MAINNET_WALRUS_PACKAGE_CONFIG }
+
+export type WalrusNetwork = 'testnet' | 'mainnet'
+
+export const DEFAULT_RPC_URLS: Record<WalrusNetwork, string> = {
+  testnet: 'https://fullnode.testnet.sui.io:443',
+  mainnet: 'https://fullnode.mainnet.sui.io:443',
+}
+
+/**
+ * Public Mysten-operated upload relays. Used as the default when no `uploadRelayHost`
+ * is specified. An upload relay is REQUIRED for browser uploads — direct-to-storage-node
+ * writes fail from browsers and constrained networks. Operators who run their own relay
+ * should pass `uploadRelayHost` to `createWalrusClient` instead.
+ */
+export const PUBLIC_UPLOAD_RELAY_HOSTS: Record<WalrusNetwork, string> = {
+  testnet: 'https://upload-relay.testnet.walrus.space',
+  mainnet: 'https://upload-relay.mainnet.walrus.space',
+}
+
+/** Public Walrus aggregators (serve raw blob bytes at `/v1/blobs/<blobId>`). */
+export const WALRUS_AGGREGATOR_HOSTS: Record<WalrusNetwork, string> = {
+  testnet: 'https://aggregator.walrus-testnet.walrus.space',
+  mainnet: 'https://aggregator.walrus-mainnet.walrus.space',
+}
+
+/**
+ * Public URL that serves a RAW blob's bytes (e.g. a token icon). Only meaningful
+ * for blobs written with `uploadImageBytes` / `writeBlob` (raw), NOT quilts.
+ */
+export function walrusBlobUrl(
+  network: WalrusNetwork,
+  blobId: string,
+  aggregatorHost?: string,
+): string {
+  const host = aggregatorHost ?? WALRUS_AGGREGATOR_HOSTS[network]
+  return `${host}/v1/blobs/${blobId}`
+}
+
+export function getWalrusPackageConfig(network: WalrusNetwork) {
+  return network === 'mainnet' ? MAINNET_WALRUS_PACKAGE_CONFIG : TESTNET_WALRUS_PACKAGE_CONFIG
+}
+
+export type CreateWalrusClientOptions = {
+  network?: WalrusNetwork
+  /** Override the Sui JSON-RPC/gRPC fullnode URL. Defaults to the public Mysten endpoint for the network. */
+  rpcUrl?: string
+  wasmUrl?: string
+  uploadRelayHost?: string
+  uploadRelayAuthToken?: string
+  uploadRelayMaxTipMist?: number
+  /**
+   * When true, build a client with NO upload relay (direct-to-storage-node).
+   * Overrides `uploadRelayHost` and the default MeddleWare relay fallback, so a
+   * deployer is never hard-blocked on relay infra. Uploads then talk directly to
+   * Walrus storage nodes.
+   */
+  disableUploadRelay?: boolean
+}
+
+export function createWalrusClient({
+  network = 'testnet',
+  rpcUrl,
+  wasmUrl,
+  uploadRelayHost,
+  uploadRelayAuthToken,
+  uploadRelayMaxTipMist = 1_000_000,
+  disableUploadRelay = false,
+}: CreateWalrusClientOptions = {}) {
+  const baseUrl = rpcUrl ?? DEFAULT_RPC_URLS[network]
+  // disableUploadRelay wins over both an explicit host and the default fallback.
+  const relayHost = disableUploadRelay ? undefined : (uploadRelayHost ?? PUBLIC_UPLOAD_RELAY_HOSTS[network])
+  return new SuiGrpcClient({
+    network,
+    baseUrl,
+  }).$extend(
+    walrus({
+      ...(wasmUrl ? { wasmUrl } : {}),
+      ...(relayHost
+        ? {
+            uploadRelay: {
+              host: relayHost,
+              sendTip: { max: uploadRelayMaxTipMist },
+              ...(uploadRelayAuthToken
+                ? { headers: { Authorization: `Bearer ${uploadRelayAuthToken}` } }
+                : {}),
+            },
+          }
+        : {}),
+    }),
+  )
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+export {
+  createWalrusClient,
+  getWalrusPackageConfig,
+  walrusBlobUrl,
+  DEFAULT_RPC_URLS,
+  PUBLIC_UPLOAD_RELAY_HOSTS,
+  WALRUS_AGGREGATOR_HOSTS,
+  TESTNET_WALRUS_PACKAGE_CONFIG,
+  MAINNET_WALRUS_PACKAGE_CONFIG,
+} from './client.js'
+export type { CreateWalrusClientOptions, WalrusNetwork } from './client.js'
+
+export {
+  LONG_TERM_EPOCHS,
+  uploadBytes,
+  uploadLocalFile,
+  createUploadFlow,
+  uploadImageBytes,
+  createBlobUploadFlow,
+} from './upload.js'
+export type { WalrusClient, UploadOptions, UploadResult } from './upload.js'
+
+export {
+  extendBlobLifetime,
+  extendBlobLifetimeTransaction,
+  setBlobAttributes,
+  setBlobAttributesTransaction,
+  readBlobAttributes,
+} from './manage.js'
+export type { ExtendOptions } from './manage.js'
+
+export { fetchOwnedWalrusBlobs } from './query.js'
+export type { OwnedBlob } from './query.js'
+
+export {
+  personalMessageForNonce,
+  buildAccessProofToken,
+  fetchRelayChallenge,
+  createRelayAccessToken,
+} from './access.js'
+export type { RelayChallenge, AccessProofInput, PersonalMessageSigner } from './access.js'
+
+export { WalrusFile, RetryableWalrusClientError } from '@mysten/walrus'

package/src/manage.ts

@@ -0,0 +1,109 @@
+import type { Signer } from '@mysten/sui/cryptography'
+import type { createWalrusClient } from './client.js'
+
+/** A Walrus-extended Sui client, as returned by {@link createWalrusClient}. */
+export type WalrusClient = ReturnType<typeof createWalrusClient>
+
+/**
+ * How to extend a blob's storage: either add `epochs` more, or extend up to an
+ * absolute `endEpoch`. Exactly one of the two must be provided.
+ */
+export type ExtendOptions =
+  | { epochs: number; endEpoch?: never }
+  | { endEpoch: number; epochs?: never }
+
+/**
+ * Extend a blob's storage lifetime on-chain (Node.js — signs and executes).
+ * Since Walrus blobs expire, call this before expiry to prevent data loss.
+ *
+ * @param client A Walrus-extended client.
+ * @param blobObjectId The on-chain Blob object id (not the blob id).
+ * @param signer The keypair paying for and authorising the extension.
+ * @param options Add `epochs` more, or extend to an absolute `endEpoch`.
+ * @returns The executed transaction digest.
+ */
+export async function extendBlobLifetime(
+  client: WalrusClient,
+  blobObjectId: string,
+  signer: Signer,
+  options: ExtendOptions,
+): Promise<{ digest: string }> {
+  const result = await client.walrus.executeExtendBlobTransaction({
+    blobObjectId,
+    signer,
+    ...options,
+  })
+  return { digest: result.digest }
+}
+
+/**
+ * Build (but do not sign) a blob-lifetime-extension transaction for a browser
+ * wallet to sign. Browser counterpart of {@link extendBlobLifetime}.
+ *
+ * @param client A Walrus-extended client.
+ * @param blobObjectId The on-chain Blob object id.
+ * @param options Add `epochs` more, or extend to an absolute `endEpoch`.
+ * @returns An unsigned `Transaction`.
+ */
+export function extendBlobLifetimeTransaction(
+  client: WalrusClient,
+  blobObjectId: string,
+  options: ExtendOptions,
+) {
+  return client.walrus.extendBlobTransaction({ blobObjectId, ...options })
+}
+
+/**
+ * Set on-chain key/value attributes on a blob (Node.js — signs and executes). A
+ * `null` value deletes that attribute.
+ *
+ * @param client A Walrus-extended client.
+ * @param blobObjectId The on-chain Blob object id.
+ * @param signer The keypair authorising the write.
+ * @param attributes Attributes to set; `null` deletes the key.
+ * @returns The executed transaction digest.
+ */
+export async function setBlobAttributes(
+  client: WalrusClient,
+  blobObjectId: string,
+  signer: Signer,
+  attributes: Record<string, string | null>,
+): Promise<{ digest: string }> {
+  const result = await client.walrus.executeWriteBlobAttributesTransaction({
+    blobObjectId,
+    signer,
+    attributes,
+  })
+  return { digest: result.digest }
+}
+
+/**
+ * Build (but do not sign) a set-blob-attributes transaction for a browser wallet
+ * to sign. Browser counterpart of {@link setBlobAttributes}.
+ *
+ * @param client A Walrus-extended client.
+ * @param blobObjectId The on-chain Blob object id.
+ * @param attributes Attributes to set; `null` deletes the key.
+ * @returns An unsigned `Transaction`.
+ */
+export function setBlobAttributesTransaction(
+  client: WalrusClient,
+  blobObjectId: string,
+  attributes: Record<string, string | null>,
+) {
+  return client.walrus.writeBlobAttributesTransaction({ blobObjectId, attributes })
+}
+
+/**
+ * Read a blob's on-chain attributes.
+ *
+ * @param client A Walrus-extended client.
+ * @param blobObjectId The on-chain Blob object id.
+ * @returns The attribute map, or `null` if the blob has none.
+ */
+export async function readBlobAttributes(
+  client: WalrusClient,
+  blobObjectId: string,
+): Promise<Record<string, string> | null> {
+  return client.walrus.readBlobAttributes({ blobObjectId })
+}

package/src/query.ts

@@ -0,0 +1,58 @@
+import { blobIdFromInt } from '@mysten/walrus'
+import type { SuiJsonRpcClient } from '@mysten/sui/jsonRpc'
+import type { WalrusClient } from './upload.js'
+
+/** A Walrus blob object owned by a Sui address. */
+export type OwnedBlob = {
+  /** The on-chain Blob object id. */
+  objectId: string
+  /** Aggregator-URL-compatible blob id string (`GET /v1/blobs/<blobId>`). */
+  blobId: string
+  /** Size in bytes. */
+  size: number
+  /** Epoch at which the blob's storage expires. */
+  endEpoch: number
+  /** Whether the blob has been certified. */
+  certified: boolean
+}
+
+/**
+ * Return all Walrus blobs owned by `owner`. Resolves the on-chain Blob struct
+ * type dynamically via `getBlobType()`, so no package addresses are hardcoded.
+ *
+ * @param suiClient A JSON-RPC Sui client (provides `getOwnedObjects`).
+ * @param walrusClient A Walrus-extended client (see {@link createWalrusClient}).
+ * @param owner The address whose owned blobs to enumerate.
+ * @returns The owner's blobs; entries whose fields cannot be parsed are skipped.
+ */
+export async function fetchOwnedWalrusBlobs(
+  suiClient: SuiJsonRpcClient,
+  walrusClient: WalrusClient,
+  owner: string,
+): Promise<OwnedBlob[]> {
+  const blobType = await walrusClient.walrus.getBlobType()
+  const { data } = await suiClient.getOwnedObjects({
+    owner,
+    filter: { StructType: blobType },
+    options: { showContent: true },
+  })
+  const blobs: OwnedBlob[] = []
+  for (const item of data) {
+    if (!item.data) continue
+    const fields = (item.data.content as { fields?: Record<string, unknown> } | undefined)?.fields
+    if (!fields) continue
+    const storage = fields.storage as { fields?: { end_epoch?: unknown } } | undefined
+    try {
+      blobs.push({
+        objectId: item.data.objectId,
+        blobId: blobIdFromInt(BigInt(fields.blob_id as string)),
+        size: Number(fields.size),
+        endEpoch: Number(storage?.fields?.end_epoch ?? 0),
+        certified: fields.certified_epoch !== null && fields.certified_epoch !== undefined,
+      })
+    } catch {
+      // Skip blobs whose fields cannot be parsed.
+    }
+  }
+  return blobs
+}

package/src/upload.ts

@@ -0,0 +1,111 @@
+import { readFile } from 'node:fs/promises'
+import { WalrusFile } from '@mysten/walrus'
+import type { Signer } from '@mysten/sui/cryptography'
+import type { createWalrusClient } from './client.js'
+
+export type WalrusClient = ReturnType<typeof createWalrusClient>
+
+/**
+ * Maximum epochs a SINGLE Walrus reservation accepts (`max_epochs_ahead` on the
+ * Walrus system object; 53 on testnet/mainnet). Passing more to `writeBlob` /
+ * `writeFiles` aborts on-chain (`reserve_space`, MoveAbort code 2). ~2 years at
+ * the ~2-week epoch cadence.
+ */
+export const MAX_SINGLE_RESERVATION_EPOCHS = 53
+
+/**
+ * Recommended TARGET lifetime for critical assets (~7.7 years at a ~2-week epoch
+ * cadence). NOTE: this cannot be reached in one reservation — it exceeds
+ * {@link MAX_SINGLE_RESERVATION_EPOCHS}. Reaching it requires periodic renewal via
+ * {@link extendBlobLifetime} before expiry. When passing this as an initial
+ * `epochs` value, clamp to `MAX_SINGLE_RESERVATION_EPOCHS` first, or pass an
+ * explicit `epochs <= 53`.
+ */
+export const LONG_TERM_EPOCHS = 200
+
+export type UploadOptions = {
+  epochs?: number
+  deletable?: boolean
+  tags?: Record<string, string>
+}
+
+export type UploadResult = {
+  blobId: string
+  blobObjectId: string
+}
+
+export async function uploadBytes(
+  client: WalrusClient,
+  contents: Uint8Array,
+  identifier: string,
+  signer: Signer,
+  options: UploadOptions = {},
+): Promise<UploadResult> {
+  const file = WalrusFile.from({ contents, identifier, tags: options.tags })
+  const [result] = await client.walrus.writeFiles({
+    files: [file],
+    // Default to the largest reservation Walrus accepts; a caller wanting the
+    // LONG_TERM target must renew via extendBlobLifetime after this.
+    epochs: options.epochs ?? MAX_SINGLE_RESERVATION_EPOCHS,
+    deletable: options.deletable ?? false,
+    signer,
+  })
+  return { blobId: result.blobId, blobObjectId: result.id }
+}
+
+// Node.js only — reads a local file before uploading
+export async function uploadLocalFile(
+  client: WalrusClient,
+  filePath: string,
+  identifier: string,
+  signer: Signer,
+  options: UploadOptions = {},
+): Promise<UploadResult> {
+  const contents = await readFile(filePath)
+  return uploadBytes(client, new Uint8Array(contents), identifier, signer, options)
+}
+
+// Browser — returns a multi-step flow for wallet-popup-safe signing
+export function createUploadFlow(
+  client: WalrusClient,
+  contents: Uint8Array,
+  identifier: string,
+  options: UploadOptions = {},
+) {
+  const file = WalrusFile.from({ contents, identifier, tags: options.tags })
+  return client.walrus.writeFilesFlow({ files: [file] })
+}
+
+// ─── Raw blobs ───────────────────────────────────────────────────────────────
+// `createUploadFlow` / `uploadBytes` store a QUILT (a bundle of files); reading
+// the quilt blob id back returns the encoded quilt, not the file. For assets that
+// must be served directly by their blob URL (e.g. a token icon rendered by
+// wallets/explorers), use a RAW blob: `GET /v1/blobs/<blobId>` returns the exact
+// bytes. See `walrusBlobUrl()` in ./client.
+
+// Node.js — one-shot raw-blob upload with a keypair `Signer`.
+export async function uploadImageBytes(
+  client: WalrusClient,
+  contents: Uint8Array,
+  signer: Signer,
+  options: UploadOptions = {},
+): Promise<UploadResult> {
+  const res = await client.walrus.writeBlob({
+    blob: contents,
+    // Default to the largest reservation Walrus accepts (see uploadBytes).
+    epochs: options.epochs ?? MAX_SINGLE_RESERVATION_EPOCHS,
+    deletable: options.deletable ?? false,
+    signer,
+  })
+  return { blobId: res.blobId, blobObjectId: res.blobObject.id }
+}
+
+// Browser — multi-step raw-blob flow for wallet-popup-safe signing. Drive it as:
+//   await flow.encode()
+//   const regTx = flow.register({ owner, epochs, deletable }) // wallet signs+executes
+//   await flow.upload({ digest })                              // digest of regTx
+//   const certTx = flow.certify()                              // wallet signs+executes
+//   const { blobId } = await flow.getBlob()                    // -> walrusBlobUrl(...)
+export function createBlobUploadFlow(client: WalrusClient, contents: Uint8Array) {
+  return client.walrus.writeBlobFlow({ blob: contents })
+}