@meddleware/walrus-ui 0.1.19 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meddleware/walrus-ui",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Standalone Vue 3 SPA for uploading blobs to Walrus decentralised storage and managing owned blobs — wallet-connected, NFT-gated relay support.",
   "author": "Meddleware <dev@meddleware.co.uk>",
   "license": "0BSD",

package/src/access-resume.ts

@@ -21,6 +21,55 @@ export function consumeStorageKey(network: string, gateId: string, address: stri
   return `mw:walrus:consume:${network}:${gateId}:${address}`
 }
 
+// ── Register-resume (Walrus flow) ───────────────────────────────────────────────────────────
+// A blob registered on-chain but not yet uploaded/certified can be resumed WITHOUT re-registering
+// (no new WAL/gas): persist its register transaction digest, keyed by a hash of the file content,
+// and reuse it when the same file is uploaded again — even after a page reload, since the user
+// re-selects the file (only the tiny digest is persisted, never the bytes).
+
+/** Stable per-(network, address) key under which a pending register digest + content hash is stored. */
+export function registerStorageKey(network: string, address: string): string {
+  return `mw:walrus:register:${network}:${address}`
+}
+
+/** Cheap content fingerprint (length + head/tail bytes) to match a retry to the same file. */
+export function contentKey(bytes: Uint8Array): string {
+  const head = Array.from(bytes.slice(0, 16)).join(',')
+  const tail = Array.from(bytes.slice(-16)).join(',')
+  return `${bytes.length}:${head}:${tail}`
+}
+
+/** Return the stored register digest iff it was saved for this exact file content. */
+export function loadRegisterResume(
+  storage: StorageLike,
+  key: string,
+  content: string,
+): string | null {
+  const raw = storage.getItem(key)
+  if (!raw) return null
+  try {
+    const v = JSON.parse(raw) as { contentKey?: string; registerDigest?: string }
+    return v.contentKey === content && v.registerDigest ? v.registerDigest : null
+  } catch {
+    return null
+  }
+}
+
+/** Persist a register digest against a file content key so the upload can resume later. */
+export function saveRegisterResume(
+  storage: StorageLike,
+  key: string,
+  content: string,
+  registerDigest: string,
+): void {
+  storage.setItem(key, JSON.stringify({ contentKey: content, registerDigest }))
+}
+
+/** Clear any stored register-resume entry (on success, or to fall back to a fresh register). */
+export function clearRegisterResume(storage: StorageLike, key: string): void {
+  storage.removeItem(key)
+}
+
 /**
  * True if `err` is the gateway's "this consume was already redeemed" rejection (HTTP 409 with
  * `code: 'redeemed'`). Distinguished from transient failures so we only re-consume (spend a new

package/src/components/WalrusView.vue

@@ -11,15 +11,24 @@ import {
   MAX_SINGLE_RESERVATION_EPOCHS,
 } from '@meddleware/walrus-relay'
 import type { UploadResult } from '@meddleware/walrus-relay'
-import { CopyableAddress, ExplorerLink, suiExplorerUrl } from '@meddleware/ui'
+import { CopyableAddress, ExplorerLink, UiNotice, suiExplorerUrl } from '@meddleware/ui'
 // Lightweight URL import — just the wasm asset URL (does not pull the walrus client).
 import walrusWasmUrl from '@mysten/walrus-wasm/web/walrus_wasm_bg.wasm?url'
 import { WalletGuard } from '@meddleware/wallet-adapter'
 import { useWallet, getSuiClient } from '../wallet.js'
 import { fetchChallenge, buildAccessProof } from '@meddleware/nft-gate-client'
 import { NETWORK, relayHosts, accessGate, uploadRelayMaxTipMist, walruscanBlobUrl } from '../config.js'
-import { runBlobUpload, type UploadResumeState } from '../upload-flow.js'
-import { consumeStorageKey, isRedeemedConflict, resolveGatedAuthToken } from '../access-resume.js'
+import { runBlobUpload } from '../upload-flow.js'
+import {
+  consumeStorageKey,
+  isRedeemedConflict,
+  resolveGatedAuthToken,
+  registerStorageKey,
+  contentKey,
+  loadRegisterResume,
+  saveRegisterResume,
+  clearRegisterResume,
+} from '../access-resume.js'
 import { useOwnedBlobs } from '../composables/useOwnedBlobs.js'
 import MyBlobs from './MyBlobs.vue'
 
@@ -52,30 +61,17 @@ async function onPurchase(): Promise<void> {
   }
 }
 
-// The relay auth token for the current attempt. The walrus client reads it PER REQUEST (a provider),
-// so a retained flow resumed after a failure presents a fresh challenge signature. Undefined ⇒
-// ungated (no header).
-const authTokenRef = ref<string | undefined>(undefined)
-// A same-session registered blob retained after a failed upload, keyed by file content, so a retry
-// resumes from the relay upload instead of re-registering (no new WAL/gas). Cleared on success or
-// when a resumed attempt itself fails (fall back to a fresh full upload).
-const uploadSession = ref<{ key: string; state: UploadResumeState } | null>(null)
-
-/** Cheap content key (length + head/tail bytes) to match a retry to the same selected file. */
-function contentKey(bytes: Uint8Array): string {
-  const head = Array.from(bytes.slice(0, 16)).join(',')
-  const tail = Array.from(bytes.slice(-16)).join(',')
-  return `${bytes.length}:${head}:${tail}`
-}
-
 // Wire the shared WalrusUpload widget to the extracted upload orchestration + the wallet. The
 // register/upload/certify sequence lives in src/upload-flow.ts (unit-tested); this closure gathers
-// the wallet-bound inputs and manages two resume layers so an interrupted upload wastes nothing:
+// the wallet-bound inputs and manages two resume layers so an interrupted upload wastes nothing —
+// both persisted in localStorage, so they survive a page reload once the same file is re-selected:
 //   1. Single-use consume: the relay treats the permanent on-chain `consumeDigest` as the one-time
 //      redemption token, so a use is only spent when an upload succeeds. The digest is persisted and
 //      reused across retries/reload (re-signing a fresh challenge is free); cleared on success.
-//   2. Walrus flow (same session): a registered-but-not-uploaded blob is retained and reused on a
-//      retry of the same file, skipping re-encode/re-register (no new WAL/gas).
+//   2. Walrus register: a registered-but-not-uploaded blob is resumed by its persisted register
+//      digest (matched to the re-selected file by content hash), skipping the register transaction
+//      (no new WAL/gas). Cleared on success, or when a resumed attempt itself fails (fall back to a
+//      fresh register).
 async function performUpload(
   bytes: Uint8Array,
   opts: { relayHost: string; onStatus: (s: string) => void },
@@ -84,83 +80,73 @@ async function performUpload(
   const executor = await buildExecutor()
   const address = account.value.address
   const key = contentKey(bytes)
+  const storage = window.localStorage
 
   const gated = !!(gate && gateState.hasAccess.value === true && gateState.nftId.value)
   const consumeKey = gate ? consumeStorageKey(NETWORK, gate.gateId, address) : null
-
-  // Resolve this attempt's relay token (gated only) and stash it where the client reads it.
-  async function setToken(forceFresh: boolean): Promise<void> {
-    if (!gated) {
-      authTokenRef.value = undefined
-      return
+  const regKey = registerStorageKey(NETWORK, address)
+
+  // Resolve this attempt's relay token (gated only); reuses a stored consume, fresh challenge each time.
+  const token = (forceFresh: boolean): Promise<string | undefined> =>
+    !gated
+      ? Promise.resolve(undefined)
+      : resolveGatedAuthToken({
+          storage,
+          key: consumeKey as string,
+          relayHost: opts.relayHost,
+          address,
+          nftId: gateState.nftId.value as string,
+          fetchChallenge,
+          buildConsume: (id, nonce) => gateState.buildConsume(id, nonce),
+          signAndExecute: (tx) => executor.signAndExecute(tx),
+          waitForTransaction: (digest) => executor.waitForTransaction(digest),
+          buildAccessProof,
+          sign: signPersonalMessage,
+          forceFresh,
+        })
+
+  const runOnce = async (authToken: string | undefined): Promise<UploadResult> => {
+    // Resume the register step iff a digest was saved for THIS exact file (survives reload).
+    const resumeRegisterDigest = loadRegisterResume(storage, regKey, key) ?? undefined
+    try {
+      const r = await runBlobUpload({
+        bytes,
+        network: NETWORK,
+        relayHost: opts.relayHost,
+        address,
+        wasmUrl: walrusWasmUrl,
+        maxTipMist: uploadRelayMaxTipMist(),
+        epochs: MAX_SINGLE_RESERVATION_EPOCHS,
+        executor,
+        suiClient: getSuiClient(),
+        authToken,
+        onStatus: opts.onStatus,
+        resumeRegisterDigest,
+        onRegistered: (digest) => saveRegisterResume(storage, regKey, key, digest),
+      })
+      // Success → clear both resume layers (the use is now genuinely spent for an upload).
+      clearRegisterResume(storage, regKey)
+      if (consumeKey) storage.removeItem(consumeKey)
+      return r
+    } catch (e) {
+      // A resumed attempt that fails drops the saved register digest so the next try does a full
+      // fresh register (never worse than today). A non-resumed failure keeps the digest that
+      // onRegistered saved, so the next try (or a reload + re-select) resumes without re-registering.
+      if (resumeRegisterDigest !== undefined) clearRegisterResume(storage, regKey)
+      throw e
     }
-    authTokenRef.value = await resolveGatedAuthToken({
-      storage: window.localStorage,
-      key: consumeKey as string,
-      relayHost: opts.relayHost,
-      address,
-      nftId: gateState.nftId.value as string,
-      fetchChallenge,
-      buildConsume: (id, nonce) => gateState.buildConsume(id, nonce),
-      signAndExecute: (tx) => executor.signAndExecute(tx),
-      waitForTransaction: (digest) => executor.waitForTransaction(digest),
-      buildAccessProof,
-      sign: signPersonalMessage,
-      forceFresh,
-    })
-  }
-
-  const deps = (resume?: UploadResumeState) => ({
-    bytes,
-    network: NETWORK,
-    relayHost: opts.relayHost,
-    address,
-    wasmUrl: walrusWasmUrl,
-    maxTipMist: uploadRelayMaxTipMist(),
-    epochs: MAX_SINGLE_RESERVATION_EPOCHS,
-    executor,
-    suiClient: getSuiClient(),
-    // Provider: resolved per request so a resumed flow uses the fresh token.
-    authToken: () => authTokenRef.value,
-    onStatus: opts.onStatus,
-    resume,
-    onRegistered: (state: UploadResumeState) => {
-      uploadSession.value = { key, state }
-    },
-  })
-
-  const succeed = (r: UploadResult): UploadResult => {
-    uploadSession.value = null
-    if (consumeKey) window.localStorage.removeItem(consumeKey) // use spent only on success
-    return r
   }
 
-  // Reuse a retained registration for this exact file, if any.
-  const resumeFor = () => (uploadSession.value?.key === key ? uploadSession.value.state : undefined)
-  const wasResuming = resumeFor() !== undefined
-
-  await setToken(false)
   try {
-    return succeed(await runBlobUpload(deps(resumeFor())))
+    return await runOnce(await token(false))
   } catch (e) {
-    // A resumed attempt failed → drop the retained registration so the next try does a full fresh
-    // upload (re-register), guaranteeing behaviour no worse than a non-resumed run.
-    if (wasResuming) uploadSession.value = null
-
     if (gated && isRedeemedConflict(e)) {
       // Stored consume already redeemed (a prior upload actually landed): clear it, spend a fresh
-      // use, and retry — resuming the registered blob if we still hold it.
-      window.localStorage.removeItem(consumeKey as string)
-      await setToken(true)
-      const resume2 = resumeFor()
-      try {
-        return succeed(await runBlobUpload(deps(resume2)))
-      } catch (e2) {
-        if (resume2) uploadSession.value = null
-        throw e2
-      }
+      // use, and retry — resuming the registered blob if one is still saved for this file.
+      storage.removeItem(consumeKey as string)
+      return await runOnce(await token(true))
     }
-    throw e // keep the retained registration so a manual retry resumes
+    throw e // keep the saved register digest so a manual retry / reload resumes
   }
 }
 
@@ -228,6 +214,17 @@ function onSettled(): void {
 
         <!-- Access held (or ungated relay): show the upload form. -->
         <template v-else>
+          <!-- Gated relays spend a use before the file is stored — make the "attempt, not a
+               guarantee" nature explicit, while reassuring that attempts resume. -->
+          <UiNotice v-if="gateState.gateConfigured" type="info" class="use-notice">
+            Uploading spends <strong>one use</strong> of your access NFT (an on-chain step) before
+            the file is stored — it pays for an upload <em>attempt</em>, not a guaranteed upload.
+            Your attempt resumes automatically, even after a page reload if you re-select the same
+            file, so a use is normally not lost. A use is spent without a completed upload only if
+            you abandon the upload entirely, cancel a required wallet approval, or wait long enough
+            that the reserved storage lapses.
+          </UiNotice>
+
           <WalrusUpload
             :hosts="relayHosts(NETWORK)"
             :connected="!!account"
@@ -316,6 +313,12 @@ function onSettled(): void {
   text-align: center;
 }
 
+.use-notice {
+  margin: 1rem 0;
+  font-size: 0.85rem;
+  line-height: 1.5;
+}
+
 .tabs {
   display: flex;
   gap: 0.25rem;

package/src/upload-flow.ts

@@ -27,22 +27,14 @@ interface BuiltTx {
 export interface BlobUploadFlow {
   encode(): Promise<void>
   register(opts: { owner: string; epochs: number; deletable: boolean }): BuiltTx
-  upload(opts: { digest: string }): Promise<void>
+  // `digest` = the register transaction digest. When resuming without a prior `register()` call on
+  // this flow instance, the SDK accepts the digest + `deletable` to upload against the already
+  // registered blob (see `@mysten/walrus` WriteBlobFlowUploadOptions).
+  upload(opts: { digest: string; deletable?: boolean }): Promise<void>
   certify(): BuiltTx
   getBlob(): Promise<{ blobId: string }>
 }
 
-/**
- * A same-session resume point: a flow whose blob is already registered on-chain, plus the register
- * transaction digest. Passing this to {@link runBlobUpload} skips encode + register (no new WAL/gas)
- * and retries from the relay upload — so an interrupted upload never re-registers. Not serialisable
- * / not for cross-reload use (the flow holds the encoded blob in memory).
- */
-export interface UploadResumeState {
-  flow: BlobUploadFlow
-  registerDigest: string
-}
-
 export interface RunBlobUploadDeps {
   bytes: Uint8Array
   network: string
@@ -67,20 +59,25 @@ export interface RunBlobUploadDeps {
   /** Lazy loader for the Walrus client module (keeps wasm out of the eager bundle). */
   loadWalrusClient?: () => Promise<WalrusClientModule>
   /**
-   * Resume a prior same-session upload from its registered blob (skips encode + register). Omit for
-   * a fresh upload.
+   * Resume from a blob registered in a PRIOR attempt (this session or a previous page load) by
+   * passing its register transaction digest. The file is re-encoded (client-side, no gas) but the
+   * on-chain `register` transaction is skipped — so an interrupted upload never re-registers (no new
+   * WAL/gas), even across a reload once the same file is re-selected. Omit for a fresh upload.
    */
-  resume?: UploadResumeState
+  resumeRegisterDigest?: string
   /**
-   * Called once the blob is registered (fresh uploads only), handing back the flow + register digest
-   * so the caller can retain them and resume the relay upload after a failure without re-registering.
+   * Called with the register transaction digest immediately after a fresh register succeeds, so the
+   * caller can PERSIST it (e.g. to localStorage) and resume the upload after a failure/reload
+   * without re-registering.
    */
-  onRegistered?: (state: UploadResumeState) => void
+  onRegistered?: (registerDigest: string) => void
 }
 
 /**
- * Register → upload → certify a blob and resolve its id + public URL. Two wallet approvals
- * (register, certify) are requested via `executor`; `onStatus` narrates each step.
+ * Register → upload → certify a blob and resolve its id + public URL. Encoding is always performed
+ * (client-side, no gas); when `resumeRegisterDigest` is supplied the on-chain register transaction
+ * is skipped and the upload proceeds against the already-registered blob. Up to two wallet approvals
+ * (register — skipped on resume — and certify) are requested via `executor`; `onStatus` narrates.
  */
 export async function runBlobUpload(deps: RunBlobUploadDeps): Promise<UploadResult> {
   // The real module's flow types are richer than the narrow structural subset we use here, so the
@@ -90,28 +87,26 @@ export async function runBlobUpload(deps: RunBlobUploadDeps): Promise<UploadResu
     (async () => (await import('@meddleware/walrus-client')) as unknown as WalrusClientModule)
   const { createWalrusClient, createBlobUploadFlow, walrusBlobUrl } = await load()
 
-  let flow: BlobUploadFlow
-  let registerDigest: string
+  const client = createWalrusClient({
+    network: deps.network,
+    wasmUrl: deps.wasmUrl,
+    uploadRelayHost: deps.relayHost,
+    uploadRelayAuthToken: deps.authToken,
+    uploadRelayMaxTipMist: deps.maxTipMist,
+  })
+  const flow = createBlobUploadFlow(client, deps.bytes)
 
-  if (deps.resume) {
-    // Same-session resume: the blob is already registered on-chain. Skip encode + register (no new
-    // WAL/gas) and retry from the relay upload. The retained flow keeps its registered state; its
-    // client resolves the relay token per request, so a fresh challenge is used on retry.
-    flow = deps.resume.flow
-    registerDigest = deps.resume.registerDigest
-  } else {
-    const client = createWalrusClient({
-      network: deps.network,
-      wasmUrl: deps.wasmUrl,
-      uploadRelayHost: deps.relayHost,
-      uploadRelayAuthToken: deps.authToken,
-      uploadRelayMaxTipMist: deps.maxTipMist,
-    })
-    flow = createBlobUploadFlow(client, deps.bytes)
-
-    deps.onStatus('Encoding…')
-    await flow.encode()
+  // Encoding is deterministic from the content and costs no gas, so it always runs — including on a
+  // resume, where it re-derives the slivers for the re-selected file.
+  deps.onStatus('Encoding…')
+  await flow.encode()
 
+  let registerDigest: string
+  if (deps.resumeRegisterDigest) {
+    // Resume: the blob was registered in a prior attempt. Skip the register transaction (no new
+    // WAL/gas) and upload against the existing on-chain registration.
+    registerDigest = deps.resumeRegisterDigest
+  } else {
     deps.onStatus('Registering blob (approve in wallet)…')
     const regTx = flow.register({ owner: deps.address, epochs: deps.epochs, deletable: false })
     regTx.setSenderIfNotSet(deps.address)
@@ -119,12 +114,12 @@ export async function runBlobUpload(deps: RunBlobUploadDeps): Promise<UploadResu
     const reg = await deps.executor.signAndExecute(regTx)
     await deps.executor.waitForTransaction(reg.digest)
     registerDigest = reg.digest
-    // Hand the registered flow back so the caller can resume the relay upload after a failure.
-    deps.onRegistered?.({ flow, registerDigest })
+    // Persist point: hand back the digest so the upload can be resumed after a failure/reload.
+    deps.onRegistered?.(registerDigest)
   }
 
   deps.onStatus('Uploading to the relay…')
-  await flow.upload({ digest: registerDigest })
+  await flow.upload({ digest: registerDigest, deletable: false })
 
   deps.onStatus('Certifying (approve in wallet)…')
   const certTx = flow.certify()