@dstorage-tech/dstorage-sdk 0.0.5 → 0.0.6

package/dist/browser.mjs

@@ -99,9 +99,6 @@ var CoreErrorCode = {
   // removeReference — 10070-10079
   REMOVE_REF_REQUIRES_CHAIN: 10070,
   REMOVE_REF_NOT_SUPPORTED: 10071,
-  // executeMetaTransaction / prepareUploadCrypto — 10080-10089
-  META_TX_REQUIRES_ENCRYPTION: 10080,
-  PREPARE_UPLOAD_NO_PROVIDERS: 10081,
   // manifest / chunking — 10090-10099
   MANIFEST_INVALID_STRUCTURE: 10090,
   MANIFEST_CHUNK_COUNT_MISMATCH: 10091,
@@ -111,8 +108,6 @@ var CoreErrorCode = {
   REASSEMBLY_SIZE_MISMATCH: 10095,
   // init state — 10100-10109
   NOT_INITIALIZED: 10100,
-  // MetaTx — 10200-10209
-  META_TX_UNKNOWN_STEP: 10200,
   // generic catch-all — 10999
   UNKNOWN_ERROR: 10999
 };
@@ -133,7 +128,7 @@ function isStorePartialError(err) {
 // package.json
 var package_default = {
   name: "@dstorage-tech/dstorage-sdk",
-  version: "0.0.5",
+  version: "0.0.6",
   description: "Privacy-first decentralized storage SDK with pluggable adapters",
   license: "MIT",
   homepage: "https://dstorage.pro",
@@ -220,2337 +215,1987 @@ var package_default = {
   }
 };
 
-// src/metaTx/utils.ts
-function defaultChainToken(chainProvider) {
-  switch (chainProvider) {
-    case "midnight":
-      return "DUST";
-    default:
-      return "MOCK";
-  }
-}
-function buildInitialSteps() {
-  return [
-    {
-      id: "estimate",
-      label: "Estimate Costs",
-      description: "Calculate storage fee + chain transaction fee",
-      status: "pending"
-    },
-    {
-      id: "encrypt",
-      label: "Encrypt File",
-      description: "Client side encryption using your wallet key",
-      status: "pending"
-    },
-    {
-      id: "payment_storage",
-      label: "Storage Payment",
-      description: "Pay storage network fee",
-      status: "pending"
-    },
-    {
-      id: "upload",
-      label: "Upload to Storage",
-      description: "Send encrypted file to decentralised network",
-      status: "pending"
-    },
-    {
-      id: "chain_reference",
-      label: "Write On-Chain Reference",
-      description: "Store file pointer + metadata on blockchain",
-      status: "pending"
-    },
-    {
-      id: "complete",
-      label: "Complete",
-      description: "Meta-transaction finalised",
-      status: "pending"
-    }
-  ];
-}
-function truncateId(id) {
-  return id.length > 20 ? `${id.slice(0, 10)}\u2026${id.slice(-6)}` : id;
-}
-async function readFileAsBytes(file) {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onload = () => resolve(new Uint8Array(reader.result));
-    reader.onerror = () => reject(new Error("Failed to read file."));
-    reader.readAsArrayBuffer(file);
-  });
+// src/chunked.ts
+var CHUNK_SIZE = 10 * 1024 * 1024;
+var MAX_CHUNK_COUNT = 1e4;
+var MAX_REASSEMBLY_BYTES = MAX_CHUNK_COUNT * CHUNK_SIZE;
+function isManifest(payload) {
+  if (typeof payload !== "object" || payload === null) return false;
+  const m = payload;
+  if (m["type"] !== "dstorage-chunked-manifest") return false;
+  return Number.isInteger(m["totalSize"]) && m["totalSize"] >= 0 && m["totalSize"] <= MAX_REASSEMBLY_BYTES && Number.isInteger(m["chunkSize"]) && m["chunkSize"] > 0 && Number.isInteger(m["chunkCount"]) && m["chunkCount"] >= 0 && m["chunkCount"] <= MAX_CHUNK_COUNT;
 }
 
-// src/metaTx/MetaTx.ts
-var MetaTx = class {
-  constructor(sdk) {
-    this.progressCallback = null;
-    this.steps = buildInitialSteps();
-    this.startedAt = 0;
-    this.sdk = sdk;
-  }
-  /** Register a progress listener. Called after every step state change. */
-  onProgress(cb) {
-    this.progressCallback = cb;
-    return this;
-  }
-  // ── Public: execute the full meta-transaction ─────────────────────────────
-  async execute(file, config = {}) {
-    this.startedAt = Date.now();
-    this.steps = buildInitialSteps();
-    this.emit({ overallStatus: "running" });
+// src/dStorage.ts
+var TAG_SDK_VERSION = "dStorage-Version";
+var TAG_CONTENT_TYPE = "Content-Type";
+var TAG_CONTENT_TYPE_OCTET_STREAM = "application/octet-stream";
+var TAG_CONTENT_TYPE_JSON = "application/json";
+var TAG_CHUNK_INDEX = "dStorage-Chunk-Index";
+var TAG_CHUNK_TOTAL = "dStorage-Chunk-Total";
+var TAG_MANIFEST_UPLOAD = "dStorage-Manifest-Upload";
+function wrapError(err) {
+  if (err instanceof DStorageError || isDStorageError(err)) throw err;
+  throw new DStorageError(
+    CoreErrorCode.UNKNOWN_ERROR,
+    `[dStorage] Unexpected error: ${err instanceof Error ? err.message : String(err)}`,
+    { cause: err }
+  );
+}
+var DStorage = class {
+  constructor(config) {
+    this.wallet = null;
+    /** Encryption adapters — each wraps/unwraps per-upload DEKs using its own algorithm. */
+    this._encryptionProviders = [];
+    this._initialized = false;
+    this.config = config;
+    this.logger = config.logger;
+  }
+  // ── Public accessors ─────────────────────────────────────────────────────
+  get storageAdapter() {
+    return this.config.storageAdapter;
+  }
+  get chainAdapter() {
+    return this.config.chainAdapter;
+  }
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
+  /**
+   * Initialize the SDK:
+   *   1. Initialize the chain adapter wallet (if supported), and
+   *      deploy a new DataRegistry contract, or connect to an existing one.
+   *   2. Derive an encryption key from the chain adapter's credentials (if supported).
+   *
+   * Returns the address of the DataRegistry contract in use.
+   * Call this instead of connect() when using MidnightChainAdapter directly.
+   */
+  async init() {
     try {
-      this.startStep("estimate", "Analysing file and fetching price feeds\u2026");
-      const estimate = await this.sdk.estimateCost(file.size);
-      this.completeStep(
-        "estimate",
-        estimate.chainCost ? `${estimate.storageCost.amount} ${estimate.storageCost.token} + ${estimate.chainCost.amount} ${estimate.chainCost.token}` : `${estimate.storageCost.amount} ${estimate.storageCost.token} (storage only)`
-      );
-      this.emit({ overallStatus: "running", estimate });
-      this.startStep("encrypt", "Reading file bytes\u2026");
-      const fileBytes = await readFileAsBytes(file);
-      this.updateStepDetail("encrypt", "Encrypting with XChaCha20-Poly1305\u2026");
-      const uploadCrypto = await this.sdk.prepareUploadCrypto();
-      const uploadData = uploadCrypto.uploadScheme ? await uploadCrypto.uploadScheme.encryptPayload(fileBytes, PAYLOAD_AAD) : fileBytes;
-      const fileSizeMB = file.size / (1024 * 1024);
-      const fileSizeDisplay = fileSizeMB < 1.1 ? `${(file.size / 1024).toFixed(2)} KB` : `${fileSizeMB.toFixed(2)} MB`;
-      this.completeStep(
-        "encrypt",
-        `${fileSizeDisplay} encrypted (${(uploadData.byteLength / 1024).toFixed(2)} KB ciphertext)`
-      );
-      const uploadMetadata = {
-        "dstorage-version": "0.1.0",
-        "dstorage-filename": file.name,
-        "dstorage-filetype": file.type,
-        "dstorage-filesize": String(file.size),
-        ...config.metadata ?? {}
-      };
-      if (this.sdk.storageAdapter.paymentAdapter.provideUploadData) {
-        this.sdk.storageAdapter.paymentAdapter.provideUploadData(
-          uploadData,
-          uploadMetadata
+      if (this.config.chainAdapter?.init) {
+        await this.config.chainAdapter.init();
+      }
+      this._encryptionProviders = this.config.encryptionAdapters ?? [];
+      this._initialized = true;
+      return this.config.chainAdapter?.getContractAddress();
+    } catch (err) {
+      wrapError(err);
+    }
+  }
+  /** Tear down active state and clear all in-memory key material. */
+  destroy() {
+    this.wallet = null;
+    this._encryptionProviders = [];
+    this._initialized = false;
+    this.logger?.log(
+      "dStorage",
+      "Destroyed \u2014 encryption key cleared from memory."
+    );
+  }
+  get isConnected() {
+    return this._initialized || this.wallet !== null;
+  }
+  get connectedAddress() {
+    return this.wallet?.address ?? null;
+  }
+  // ── Core operations ───────────────────────────────────────────────────────
+  /**
+   * Encrypt content client-side, store to decentralised storage,
+   * and write a cryptographic reference on-chain.
+   *
+   * Files larger than CHUNK_SIZE (10 MB) are automatically split into chunks,
+   * each encrypted and stored independently. A manifest file ties them together.
+   * Only the manifest's storageId is written on-chain.
+   *
+   * @param bytes    Uint8Array to store
+   * @param options  Optional StoreOptions (metadata, onProgress, isPublic, refId)
+   * @returns        StoreResult containing the chainRefId/storageId needed to retrieve later
+   */
+  async store(bytes, options) {
+    try {
+      this.assertConnected();
+      const {
+        tags = {},
+        metadata: rawMeta,
+        onProgress,
+        isPublic = false,
+        refId
+      } = options ?? {};
+      if (rawMeta !== void 0 && isPublic) {
+        throw new DStorageError(
+          CoreErrorCode.METADATA_WITH_PUBLIC_UPLOAD,
+          "[dStorage] metadata cannot be used with isPublic uploads \u2014 there is no DEK to encrypt it with."
         );
       }
-      this.startStep(
-        "payment_storage",
-        `Preparing ${estimate.storageCost.amount} ${estimate.storageCost.token} payment\u2026`
-      );
-      const storageReceipt = await this.sdk.storageAdapter.paymentAdapter.pay(
-        {
-          network: this.sdk.storageAdapter.name,
-          dataSizeBytes: uploadData.byteLength,
-          expiresAt: Date.now() + 6e5
-        },
-        (msg) => this.updateStepDetail("payment_storage", msg)
-      );
-      this.completeStep(
-        "payment_storage",
-        `${storageReceipt.amount} ${storageReceipt.token}`
-      );
-      this.startStep("upload", `Uploading to ${this.sdk.storageAdapter.name}\u2026`);
-      const uploadResult = await this.sdk.storageAdapter.store(
-        uploadData,
-        uploadMetadata
-      );
-      this.completeStep(
-        "upload",
-        `Stored on ${uploadResult.provider} \u2192 ${truncateId(uploadResult.id)}`
-      );
-      let chainRefId;
-      let chainPayment;
-      let chainToken;
-      if (this.sdk.chainAdapter) {
-        this.startStep(
-          "chain_reference",
-          `Fee payment and writing reference to ${this.sdk.chainAdapter.name}\u2026`
+      if (bytes.length > CHUNK_SIZE) {
+        return this._uploadChunked(
+          bytes,
+          tags,
+          onProgress,
+          isPublic,
+          rawMeta,
+          refId
+        );
+      }
+      let uploadData;
+      let onChainStorageId;
+      const encryptionScheme = isPublic ? "" : "xchacha20poly1305-v1";
+      let uploadScheme = null;
+      let keyEnvelope = "";
+      let dek = null;
+      let ownerSecret = new Uint8Array(0);
+      if (isPublic) {
+        uploadData = bytes;
+      } else {
+        if (this._encryptionProviders.length === 0) {
+          throw new DStorageError(
+            CoreErrorCode.UPLOAD_NO_PROVIDERS,
+            "[dStorage] No encryption providers available. Call init() before uploading."
+          );
+        }
+        dek = generateDek();
+        uploadScheme = XChaChaScheme.fromKey(dek);
+        this.logger?.log(
+          "dStorage",
+          `Encrypting content using scheme: ${encryptionScheme}`
+        );
+        uploadData = await uploadScheme.encryptPayload(bytes, PAYLOAD_AAD);
+        const wrapperEntries = await Promise.all(
+          this._encryptionProviders.map(async (provider) => ({
+            wrapKeyName: provider.name,
+            ...await provider.wrapDek(dek)
+          }))
         );
-        const onChainStorageId = uploadCrypto.uploadScheme ? await uploadCrypto.uploadScheme.encryptStorageId(uploadResult.id) : uploadResult.id;
-        const { deriveOwnerSecret: deriveOwnerSecret2 } = await import("./dist-MOLWJ4Y7.mjs");
-        let ownerSecret;
-        if (uploadCrypto.dek) {
-          ownerSecret = await deriveOwnerSecret2(
-            uploadCrypto.dek,
-            new TextEncoder().encode(uploadResult.id)
+        keyEnvelope = serializeKeyEnvelope(buildKeyEnvelope(wrapperEntries));
+      }
+      const sdkVersion = package_default.version ?? "unknown";
+      const storageResult = await this.config.storageAdapter.store(uploadData, {
+        ...tags,
+        [TAG_SDK_VERSION]: sdkVersion,
+        [TAG_CONTENT_TYPE]: TAG_CONTENT_TYPE_OCTET_STREAM
+      });
+      if (isPublic) {
+        if (this.config.chainAdapter) {
+          if (this._encryptionProviders.length === 0) {
+            throw new DStorageError(
+              CoreErrorCode.PUBLIC_UPLOAD_REQUIRES_SEED_PROVIDER,
+              "[dStorage] Cannot store public data without at least one encryption seed provider. Without a provider there is no owner secret, so the reference could never be removed or updated."
+            );
+          }
+          const ownerSeed = generateDek();
+          const ownerSeedWrappers = await Promise.all(
+            this._encryptionProviders.map(async (provider) => ({
+              wrapKeyName: provider.name,
+              ...await provider.wrapDek(ownerSeed)
+            }))
           );
-        } else {
-          ownerSecret = await deriveOwnerSecret2(
-            uploadCrypto.ownerSeed,
-            new TextEncoder().encode(uploadResult.id),
+          keyEnvelope = serializeKeyEnvelope(
+            buildKeyEnvelope(ownerSeedWrappers)
+          );
+          ownerSecret = await deriveOwnerSecret(
+            ownerSeed,
+            new TextEncoder().encode(storageResult.id),
             "dstorage:owner-secret:public:v1"
           );
         }
-        const chainResult = await this.sdk.chainAdapter.writeReference({
-          storageId: onChainStorageId,
-          encryptionScheme: uploadCrypto.encryptionScheme,
-          storageProvider: uploadResult.provider,
-          writtenAt: Date.now(),
-          keyEnvelope: uploadCrypto.keyEnvelope,
-          ownerSecret
-        });
-        const finalChainReceipt = chainResult.paymentReceipt ?? {
-          amount: "<unknown>",
-          token: estimate.chainCost.token,
-          txHash: "",
-          type: "chain",
-          paidAt: 0,
-          serviceFee: "0"
-        };
-        chainRefId = chainResult.refId;
-        chainPayment = finalChainReceipt;
-        chainToken = finalChainReceipt.token;
-        this.completeStep(
-          "chain_reference",
-          `Reference written \u2192 ${finalChainReceipt.amount} ${finalChainReceipt.token} \u2192 ${truncateId(chainResult.refId)}`
-        );
+        onChainStorageId = storageResult.id;
       } else {
-        this.completeStep(
-          "chain_reference",
-          "Skipped \u2014 no chain adapter configured"
+        onChainStorageId = await uploadScheme.encryptStorageId(
+          storageResult.id
+        );
+        ownerSecret = await deriveOwnerSecret(
+          dek,
+          new TextEncoder().encode(storageResult.id)
         );
       }
-      const dataId = chainRefId ? `${uploadResult.id}::${chainRefId}` : uploadResult.id;
-      const totalDurationMs = Date.now() - this.startedAt;
-      this.completeStep(
-        "complete",
-        `Completed in ${(totalDurationMs / 1e3).toFixed(1)}s`
-      );
-      const receipt = {
-        dataId,
-        storageId: uploadResult.id,
-        ...chainRefId ? { chainRefId } : {},
-        file: {
-          name: file.name,
-          type: file.type,
-          sizeBytes: file.size
-        },
-        storagePayment: storageReceipt,
-        ...chainPayment ? { chainPayment, chainToken } : {},
-        storageToken: storageReceipt.token,
-        ...config.contractAddress ? {
-          contract: {
-            address: config.contractAddress,
-            name: config.contractName ?? config.contractAddress
-          }
-        } : {},
-        completedAt: Date.now(),
-        totalDurationMs
+      const storageCost = {
+        amount: storageResult.cost?.amount ?? "unknown",
+        token: storageResult.cost?.token ?? "AR"
       };
-      this.emit({ overallStatus: "complete", estimate, receipt });
-      return receipt;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const runningStep = this.steps.find((s) => s.status === "running");
-      if (runningStep) {
-        runningStep.status = "error";
-        runningStep.detail = message;
-      }
-      this.emit({ overallStatus: "error", error: message });
-      throw err;
-    }
-  }
-  // ── Private step helpers ──────────────────────────────────────────────────
-  startStep(id, detail) {
-    const step = this.getStep(id);
-    step.status = "running";
-    step.detail = detail;
-    step.startedAt = Date.now();
-    this.emit({ overallStatus: "running", currentStepId: id });
-  }
-  updateStepDetail(id, detail) {
-    const step = this.getStep(id);
-    step.detail = detail;
-    this.emit({ overallStatus: "running", currentStepId: id });
-  }
-  completeStep(id, detail) {
-    const step = this.getStep(id);
-    step.status = "done";
-    step.detail = detail;
-    if (step.startedAt) step.durationMs = Date.now() - step.startedAt;
-    this.emit({ overallStatus: "running", currentStepId: id });
-  }
-  getStep(id) {
-    const step = this.steps.find((s) => s.id === id);
-    if (!step)
-      throw new DStorageError(
-        CoreErrorCode.META_TX_UNKNOWN_STEP,
-        `[dStorage] Unknown meta-transaction step: ${id}`
-      );
-    return step;
-  }
-  emit(overrides) {
-    if (!this.progressCallback) return;
-    const currentRunning = this.steps.find((s) => s.status === "running");
-    this.progressCallback({
-      steps: [...this.steps.map((s) => ({ ...s }))],
-      currentStepId: currentRunning?.id ?? overrides.currentStepId ?? null,
-      overallStatus: "running",
-      ...overrides
-    });
-  }
-};
-
-// ../payment/dist/chunk-IVL4WQ5Y.mjs
-var TOKENS = {
-  AR: { symbol: "AR", name: "Arweave", decimals: 12 },
-  DUST: { symbol: "DUST", name: "Midnight", decimals: 6 },
-  MOCK: {
-    symbol: "MOCK",
-    name: "Mock Token",
-    decimals: 6
-  }
-};
-
-// ../payment/dist/chunk-R6FT3AV4.mjs
-var MockPaymentAdapter = class {
-  constructor(config) {
-    this.network = "mock";
-    this.token = config.token ?? "MOCK";
-    this.type = config.type;
-    this.quoteValidityMs = config.quoteValidityMs ?? 6e5;
-    this.logger = config.logger;
-  }
-  async estimateCost(dataSizeBytes) {
-    const kb = dataSizeBytes / 1024;
-    const amount = Math.max(1e-4, kb * 1e-3).toFixed(6);
-    this.logger?.log(
-      "dStorage/mock-payment",
-      `Estimated cost: ${amount} ${this.token}`
-    );
-    return {
-      token: this.token,
-      amount,
-      network: this.network,
-      type: this.type,
-      dataSizeBytes,
-      expiresAt: Date.now() + this.quoteValidityMs
-    };
-  }
-  async pay(instruction, onStatus) {
-    const tokenName = TOKENS[this.token]?.name ?? this.token;
-    onStatus?.(`Requesting ${tokenName} wallet signature\u2026`);
-    onStatus?.(`Broadcasting ${this.type} payment transaction\u2026`);
-    onStatus?.("Awaiting confirmation\u2026");
-    const txHash = generateSimulatedTxHash();
-    const { amount } = await this.estimateCost(instruction.dataSizeBytes);
-    this.logger?.log(
-      "dStorage/mock-payment",
-      `Simulated ${this.type} payment \u2192 txHash: ${txHash}`
-    );
-    return {
-      txHash,
-      token: this.token,
-      amount,
-      type: this.type,
-      paidAt: Date.now(),
-      serviceFee: "0"
-    };
-  }
-};
-function generateSimulatedTxHash() {
-  const hex = Array.from(
-    { length: 64 },
-    () => Math.floor(Math.random() * 16).toString(16)
-  ).join("");
-  return `0x${hex}`;
-}
-
-// ../payment/dist/index.mjs
-import { blake3 } from "@noble/hashes/blake3.js";
-var PaymentErrorCode = {
-  // adapters/arweave.ts (14000–14099)
-  ARWEAVE_NOT_INSTALLED: 14001,
-  ARWEAVE_WALLET_KEY_REQUIRED: 14002,
-  ARWEAVE_CONNECT_NOT_FOUND: 14003,
-  ARWEAVE_QUOTE_EXPIRED: 14004,
-  // adapters/managed.ts (14100–14299)
-  MANAGED_NON_OBJECT_RESPONSE: 14100,
-  MANAGED_SERVER_FAILURE: 14101,
-  MANAGED_MISSING_FIELD: 14102,
-  MANAGED_PUBLIC_KEY_MISMATCH: 14103,
-  MANAGED_TOKEN_REQUIRED: 14104,
-  MANAGED_QUOTE_EXPIRED: 14105,
-  MANAGED_UNBALANCED_TX: 14106,
-  MANAGED_SERVER_UNREACHABLE: 14107,
-  MANAGED_KEY_CHANGED: 14108,
-  MANAGED_SIGN_HTTP_ERROR: 14109,
-  MANAGED_NON_JSON_RESPONSE: 14110
-};
-var MAX_ERROR_BODY_LENGTH = 200;
-function sanitiseErrorBody(raw) {
-  return raw.replace(/[\x00-\x1f\x7f]/g, " ").replace(/<[^>]*>/g, "").trim().slice(0, MAX_ERROR_BODY_LENGTH);
-}
-var DEFAULT_QUOTE_VALIDITY_MS = 12e4;
-var CONTENT_HASH_TAG = "X-Content-Hash";
-var ArweavePaymentAdapter = class {
-  constructor(config = {}) {
-    this.network = "arweave";
-    this.token = "AR";
-    this.type = "storage";
-    this.arweaveClient = null;
-    this.pendingUpload = null;
-    this.signedUpload = null;
-    this.gateway = config.gateway ?? {
-      host: "arweave.net",
-      port: 443,
-      protocol: "https"
-    };
-    this.walletKey = config.walletKey;
-    this.quoteValidityMs = config.quoteValidityMs ?? DEFAULT_QUOTE_VALIDITY_MS;
-    this.logger = config.logger;
-  }
-  // ── Protected: lazy Arweave client ───────────────────────────────────────────
-  async getClient() {
-    if (this.arweaveClient) return this.arweaveClient;
-    try {
-      const _m = await import("arweave");
-      const raw = _m.default;
-      const ctor = typeof raw.init === "function" ? raw : raw.default ?? raw;
-      this.arweaveClient = ctor.init(this.gateway ?? {});
-      return this.arweaveClient;
-    } catch {
-      throw new DStorageError(
-        PaymentErrorCode.ARWEAVE_NOT_INSTALLED,
-        "[dStorage/arweave-payment] arweave package not installed. Run: npm install arweave"
-      );
-    }
-  }
-  // ── Protected: wallet resolution ─────────────────────────────────────────────
-  resolveWallet() {
-    if (this.walletKey && Object.keys(this.walletKey).length > 0) {
-      return this.walletKey;
-    }
-    if (typeof window === "undefined") {
-      throw new DStorageError(
-        PaymentErrorCode.ARWEAVE_WALLET_KEY_REQUIRED,
-        "[dStorage/arweave-payment] Node.js usage requires a walletKey in the config."
-      );
-    }
-    if (typeof window.arweaveWallet === "undefined") {
-      throw new DStorageError(
-        PaymentErrorCode.ARWEAVE_CONNECT_NOT_FOUND,
-        "[dStorage/arweave-payment] ArConnect extension not found. Install it from https://arconnect.io"
-      );
-    }
-    return "use_wallet";
-  }
-  // ── PaymentAdapter: provideUploadData ─────────────────────────────────────────
-  /**
-   * Store the encrypted upload payload and metadata tags so that pay() can
-   * build and sign the complete Arweave transaction in one step.
-   * Called by MetaTransaction after the encrypt step, before pay().
-   */
-  provideUploadData(data, metadata = {}) {
-    const hashHex = Array.from(blake3(data)).map((b) => b.toString(16).padStart(2, "0")).join("");
-    this.pendingUpload = {
-      data,
-      metadata: { [CONTENT_HASH_TAG]: hashHex, ...metadata }
-    };
-    this.logger?.log(
-      "dStorage/arweave-payment",
-      `Upload data staged: ${data.byteLength} bytes`
-    );
-  }
-  // ── PaymentAdapter: estimateCost ─────────────────────────────────────────────
-  /**
-   * Query the Arweave fee oracle for the real upload cost.
-   */
-  async estimateCost(dataSizeBytes) {
-    const arweave = await this.getClient();
-    const winstons = await arweave.transactions.getPrice(
-      dataSizeBytes
-    );
-    const amount = arweave.ar.winstonToAr(winstons);
-    this.logger?.log(
-      "dStorage/arweave-payment",
-      `Estimated: ${amount} AR (${winstons} Winstons)`
-    );
-    return {
-      token: this.token,
-      amount,
-      network: this.network,
-      type: this.type,
-      dataSizeBytes,
-      expiresAt: Date.now() + this.quoteValidityMs
-    };
-  }
-  // ── PaymentAdapter: pay ───────────────────────────────────────────────────────
-  /**
-   * Sign-then-store flow (when provideUploadData was called):
-   *   Creates the Arweave transaction with data + tags, prompts the wallet
-   *   for approval (ArConnect popup or JWK signing), and stores the signed
-   *   transaction for ArweaveStorageAdapter.store() to post.
-   *
-   * Pass-through fallback (when provideUploadData was NOT called):
-   *   Returns a receipt acknowledging that payment is bundled with the upload.
-   *   ArweaveStorageAdapter.store() performs the full create → sign → post flow.
-   */
-  async pay(instruction, onStatus) {
-    if (Date.now() > instruction.expiresAt) {
-      throw new DStorageError(
-        PaymentErrorCode.ARWEAVE_QUOTE_EXPIRED,
-        `[dStorage/payment] Quote expired at ${new Date(instruction.expiresAt).toISOString()}. Request a fresh quote via estimateCost() before calling pay().`
-      );
-    }
-    if (!this.pendingUpload) {
-      onStatus?.("AR fee will be deducted as part of the upload transaction.");
-      return {
-        txHash: "arweave-bundled-with-upload",
-        token: this.token,
-        amount: "0",
-        type: this.type,
-        paidAt: Date.now(),
-        serviceFee: "0"
-      };
-    }
-    const { data, metadata } = this.pendingUpload;
-    this.pendingUpload = null;
-    const arweave = await this.getClient();
-    const wallet = this.resolveWallet();
-    onStatus?.("Creating Arweave transaction\u2026");
-    const tx = await arweave.createTransaction({ data }, wallet);
-    for (const [key, value] of Object.entries(metadata)) {
-      tx.addTag(key, value);
-    }
-    onStatus?.("Requesting AR wallet approval\u2026");
-    await arweave.transactions.sign(tx, wallet);
-    const winstons = await arweave.transactions.getPrice(
-      data.byteLength
-    );
-    const arCost = arweave.ar.winstonToAr(winstons);
-    this.signedUpload = { tx, arCost };
-    this.logger?.log(
-      "dStorage/arweave-payment",
-      `Transaction signed \u2192 txId: ${tx.id}  cost: ~${arCost} AR`
-    );
-    return {
-      txHash: tx.id,
-      token: this.token,
-      amount: arCost,
-      type: this.type,
-      paidAt: Date.now(),
-      serviceFee: "0"
-    };
-  }
-  // ── Consumed by ArweaveStorageAdapter ─────────────────────────────────────────
-  /**
-   * Returns the pre-signed transaction produced by pay(), then clears it.
-   * Called by ArweaveStorageAdapter.store() to post the already-signed tx.
-   * Returns null if pay() did not sign a transaction (pass-through mode).
-   */
-  consumeSignedUpload() {
-    const signed = this.signedUpload;
-    this.signedUpload = null;
-    return signed;
-  }
-};
-var POST_SIGN_TX_API_PATH = "/api/service/sign-tx";
-function uint8ArrayToHex(bytes) {
-  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-}
-function parseSignedTxBytes(signedTx) {
-  if (signedTx.startsWith("midnight:")) {
-    const colonIdx = signedTx.lastIndexOf(":");
-    return hexToBytes(signedTx.slice(colonIdx + 1), "signedTx");
-  }
-  return hexToBytes(signedTx, "signedTx");
-}
-function parseSignTxResponse(raw) {
-  if (typeof raw !== "object" || raw === null) {
-    throw new DStorageError(
-      PaymentErrorCode.MANAGED_NON_OBJECT_RESPONSE,
-      "[dStorage/managed-payment] Signing server returned a non-object response."
-    );
-  }
-  const r = raw;
-  if (r["success"] !== true) {
-    throw new DStorageError(
-      PaymentErrorCode.MANAGED_SERVER_FAILURE,
-      `[dStorage/managed-payment] Signing server reported success:false \u2014 ${sanitiseErrorBody(JSON.stringify(r))}`
-    );
-  }
-  for (const field of [
-    "txId",
-    "signature",
-    "publicKey",
-    "txAmount",
-    "serviceFee"
-  ]) {
-    if (typeof r[field] !== "string") {
-      throw new DStorageError(
-        PaymentErrorCode.MANAGED_MISSING_FIELD,
-        `[dStorage/managed-payment] Signing server response missing or invalid field: ${field}`
+      if (this.config.chainAdapter) {
+        const contentHash = await computeBlake3Hex(uploadData);
+        const storeRecovery = {
+          storageId: storageResult.id,
+          storageProvider: storageResult.provider,
+          keyEnvelope: isPublic ? void 0 : keyEnvelope,
+          contentHash
+        };
+        onProgress?.({
+          phase: "stored",
+          chunksUploaded: 1,
+          totalChunks: 1,
+          bytesUploaded: bytes.length,
+          totalBytes: bytes.length,
+          recovery: storeRecovery
+        });
+        const encryptedMetadata = rawMeta ? bytesToBase64url(
+          await uploadScheme.encryptPayload(
+            new TextEncoder().encode(JSON.stringify(rawMeta)),
+            METADATA_AAD
+          )
+        ) : void 0;
+        try {
+          const chainResult = await this.config.chainAdapter.writeReference({
+            storageId: onChainStorageId,
+            encryptionScheme,
+            storageProvider: storageResult.provider,
+            ...refId !== void 0 ? { refId } : {},
+            ...encryptedMetadata !== void 0 ? { encryptedMetadata } : {},
+            writtenAt: Date.now(),
+            keyEnvelope,
+            contentHash,
+            ownerSecret
+          });
+          const resultRefId = chainResult.refId;
+          this.logger?.log(
+            "dStorage",
+            `Upload complete \u2192 refId: ${resultRefId}`
+          );
+          return {
+            chainRefId: resultRefId,
+            storageId: storageResult.id,
+            storageProvider: storageResult.provider,
+            chainProvider: chainResult.provider,
+            uploadedAt: storageResult.uploadedAt,
+            encryptionScheme,
+            costEstimate: {
+              storageCost,
+              chainCost: {
+                amount: chainResult.paymentReceipt?.amount ?? "unknown",
+                token: chainResult.paymentReceipt?.token ?? "DUST"
+              },
+              fileSizeBytes: uploadData.length
+            }
+          };
+        } catch {
+          throw new StorePartialError(storeRecovery);
+        }
+      }
+      this.logger?.log(
+        "dStorage",
+        `Upload complete (storage-only) \u2192 storageId: ${storageResult.id}`
       );
+      return {
+        storageId: storageResult.id,
+        storageProvider: storageResult.provider,
+        uploadedAt: storageResult.uploadedAt,
+        encryptionScheme,
+        ...uploadScheme ? { cryptoScheme: uploadScheme } : {},
+        costEstimate: { storageCost, fileSizeBytes: uploadData.length }
+      };
+    } catch (err) {
+      wrapError(err);
     }
   }
-  return r;
-}
-function assertOwnerKeyMatch(responseKey, pinnedKey) {
-  if (pinnedKey && responseKey !== pinnedKey) {
-    throw new DStorageError(
-      PaymentErrorCode.MANAGED_PUBLIC_KEY_MISMATCH,
-      "[dStorage/managed-payment] Signing server returned a public key that does not match the pinned key from the auth token \u2014 possible server compromise or MITM."
-    );
-  }
-}
-var ManagedPaymentAdapter = class _ManagedPaymentAdapter extends ArweavePaymentAdapter {
   /**
-   * Strip a RSA-4096 modulus suffix from a compound auth token
-   * (<credential>.<base64url_683_chars>), returning only the credential.
-   * A plain token (no '.' or wrong suffix length) is returned unchanged.
-   * This lets ArweaveBundlerStorageAdapter compound tokens be passed directly
-   * to any adapter that uses ManagedPaymentAdapter without breaking authentication.
+   * Register a pre-existing storageId as a new on-chain reference.
    *
-   * lastIndexOf is intentional: the credential part may itself contain dots
-   * (e.g. a JWT), so we always split at the *last* dot to reach the modulus.
+   * Use this when data has already been uploaded to the storage network by
+   * other means (e.g. a third-party tool or a separate pipeline). The content
+   * is not touched — only the chain reference is created.
+   *
+   * A fresh DEK is generated solely to encrypt the storageId and derive the
+   * ownerSecret. The resulting reference round-trips through retrieveByRefId()
+   * exactly like one created by store().
+   *
+   * Note: chunked manifests are not handled here. For large pre-existing
+   * uploads already split into chunks, register the manifest storageId.
    */
-  static _parseAuthToken(token) {
-    const dot = token.lastIndexOf(".");
-    if (dot !== -1) {
-      const suffix = token.slice(dot + 1);
-      if (suffix.length === 683 && /^[A-Za-z0-9_-]+$/.test(suffix)) {
-        return { credential: token.slice(0, dot), ownerPublicKey: suffix };
+  async registerReference(options = {}) {
+    try {
+      this.assertConnected();
+      if (!this.config.chainAdapter) {
+        throw new DStorageError(
+          CoreErrorCode.REGISTER_REF_REQUIRES_CHAIN,
+          "[dStorage] registerReference requires a chain adapter."
+        );
       }
+      if (this._encryptionProviders.length === 0) {
+        throw new DStorageError(
+          CoreErrorCode.REGISTER_REF_REQUIRES_ENCRYPTION,
+          "[dStorage] registerReference requires at least one encryption adapter."
+        );
+      }
+      let dek;
+      const recoveryEnvelope = options.keyEnvelope;
+      if (recoveryEnvelope) {
+        dek = await this._unwrapDek(recoveryEnvelope);
+      } else {
+        dek = generateDek();
+      }
+      try {
+        const scheme = XChaChaScheme.fromKey(dek);
+        const { metadata: rawMeta } = options;
+        const encryptedMetadata = rawMeta ? bytesToBase64url(
+          await scheme.encryptPayload(
+            new TextEncoder().encode(JSON.stringify(rawMeta)),
+            METADATA_AAD
+          )
+        ) : void 0;
+        const onChainStorageId = options.storageId !== void 0 ? await scheme.encryptStorageId(options.storageId) : void 0;
+        let keyEnvelope;
+        if (recoveryEnvelope !== void 0) {
+          keyEnvelope = recoveryEnvelope;
+        } else {
+          const wrapperEntries = await Promise.all(
+            this._encryptionProviders.map(async (p) => ({
+              wrapKeyName: p.name,
+              ...await p.wrapDek(dek)
+            }))
+          );
+          keyEnvelope = serializeKeyEnvelope(buildKeyEnvelope(wrapperEntries));
+        }
+        const ownerSecret = await deriveOwnerSecret(
+          dek,
+          options.storageId !== void 0 ? new TextEncoder().encode(options.storageId) : METADATA_ONLY_OWNER_SECRET_SALT
+        );
+        const chainResult = await this.config.chainAdapter.writeReference({
+          ...onChainStorageId !== void 0 ? { storageId: onChainStorageId } : {},
+          encryptionScheme: "xchacha20poly1305-v1",
+          storageProvider: options.storageProvider ?? this.config.storageAdapter.name,
+          ...options.refId !== void 0 ? { refId: options.refId } : {},
+          ...encryptedMetadata !== void 0 ? { encryptedMetadata } : {},
+          writtenAt: Date.now(),
+          keyEnvelope,
+          ...options.contentHash !== void 0 ? { contentHash: options.contentHash } : {},
+          ownerSecret
+        });
+        return { chainRefId: chainResult.refId };
+      } finally {
+        dek.fill(0);
+      }
+    } catch (err) {
+      wrapError(err);
     }
-    return { credential: token, ownerPublicKey: void 0 };
-  }
-  constructor(config) {
-    super({
-      ...config.gateway !== void 0 ? { gateway: config.gateway } : {},
-      ...config.quoteValidityMs !== void 0 ? { quoteValidityMs: config.quoteValidityMs } : {},
-      ...config.logger !== void 0 ? { logger: config.logger } : {}
-    });
-    this.signingServerUrl = config.signingServerUrl.replace(/\/$/, "");
-    if (!config.authToken || config.authToken.trim() === "") {
-      throw new DStorageError(
-        PaymentErrorCode.MANAGED_TOKEN_REQUIRED,
-        "[dStorage/managed-payment] authToken is required and must not be empty or whitespace."
-      );
-    }
-    const { credential, ownerPublicKey } = _ManagedPaymentAdapter._parseAuthToken(config.authToken);
-    this.authToken = credential;
-    this.ownerPublicKey = ownerPublicKey;
-    this.requestTimeoutMs = config.requestTimeoutMs ?? 3e4;
-    this.network = config.network;
-    this.type = config.type;
-  }
-  // ── PaymentAdapter: estimateCost ─────────────────────────────────────────────
-  /**
-   * Query the Arweave fee oracle for the real upload cost.
-   */
-  async estimateCost(dataSizeBytes) {
-    if (this.network === "arweave") {
-      return await super.estimateCost(dataSizeBytes);
-    }
-    const amount = "0.0012345";
-    this.logger?.log(
-      "dStorage/managed-payment",
-      `Estimated: ${amount} ${this.token}`
-    );
-    return {
-      token: this.token,
-      // FIXME: should be probably obtained from the signing service
-      amount,
-      network: this.network,
-      type: this.type,
-      dataSizeBytes,
-      txData: "---",
-      expiresAt: Date.now() + this.quoteValidityMs
-    };
   }
-  // ── PaymentAdapter: pay ───────────────────────────────────────────────────────
   /**
-   * Routes payment to the correct network-specific handler based on quote.network.
+   * Store new content and update an existing on-chain reference in place.
    *
-   * The Arweave path falls back to the base-class pass-through if
-   * provideUploadData() was not called. An unrecognised network throws.
-   */
-  async pay(instruction, onStatus) {
-    if (Date.now() > instruction.expiresAt) {
-      throw new DStorageError(
-        PaymentErrorCode.MANAGED_QUOTE_EXPIRED,
-        `[dStorage/payment] Quote expired at ${new Date(instruction.expiresAt).toISOString()}. Request a fresh quote via estimateCost() before calling pay().`
-      );
-    }
-    if (this.network === "managedmock") {
-      return this._payManagedMock(instruction, onStatus);
-    }
-    if (instruction.network === "midnight") {
-      return this._payMidnight(instruction, onStatus);
-    } else if (instruction.network === "arweave") {
-      return this._payArweave(instruction, onStatus);
-    } else if (instruction.network === "arweave_bundler") {
-      return this._payArweaveBundler(instruction, onStatus);
-    }
-    throw Error(`Unsupported network: ${instruction.network}`);
-  }
-  // ── Network-specific wallet provider factories ────────────────────────────────
-  /**
-   * Returns a WalletProvider-compatible object for the Midnight chain whose
-   * `balanceTx()` is fulfilled by the managed signing server instead of a
-   * local wallet. The caller supplies the public keys (from whichever source
-   * they have — HD derivation, a server endpoint, etc.); the SDK only handles
-   * the signing-server round-trip.
+   * Ownership is proved by re-deriving the ownerSecret from the existing
+   * reference — the same mechanism used by removeReference(). A fresh DEK is
+   * generated for the new content; the previous version is not modified and remains
+   * independently decryptable if the caller retained the old storageId.
    *
-   * The returned object satisfies the @midnight-ntwrk/midnight-js-types
-   * WalletProvider interface via structural typing — no Midnight package
-   * import is required from the caller's side.
+   * Note: chunking is not applied here. For large files use store() to get a
+   * new chunked reference, then removeReference() on the old one.
    *
-   * @param coinPublicKey        Midnight coin public key (hex) for the ZK fee circuit.
-   * @param encryptionPublicKey  Midnight encryption public key (hex).
-   * @param onReceipt            Optional callback invoked with the PaymentReceipt
-   *                             after each successful balanceTx call. Used internally
-   *                             by MidnightChainAdapter to capture receipt metadata;
-   *                             external callers can omit it.
+   * @param refId    The chain reference to update (returned by a prior store/registerReference).
+   * @param bytes    New content to encrypt and store.
+   * @param options  Optional StoreOptions. isPublic is ignored.
    */
-  createMidnightWalletProvider(coinPublicKey, encryptionPublicKey, onReceipt) {
-    return {
-      getCoinPublicKey: () => coinPublicKey,
-      getEncryptionPublicKey: () => encryptionPublicKey,
-      balanceTx: async (tx, _ttl) => {
-        const txData = uint8ArrayToHex(tx.serialize());
-        const receipt = await this.pay({
-          network: "midnight",
-          txData,
-          dataSizeBytes: txData.length,
-          expiresAt: Date.now() + 6e4
+  async update(refId, bytes, options) {
+    try {
+      this.assertConnected();
+      if (!this.config.chainAdapter) {
+        throw new DStorageError(
+          CoreErrorCode.UPDATE_UPLOAD_REQUIRES_CHAIN,
+          "[dStorage] update requires a chain adapter."
+        );
+      }
+      if (typeof this.config.chainAdapter.updateReference !== "function") {
+        throw new DStorageError(
+          CoreErrorCode.UPDATE_UPLOAD_NOT_SUPPORTED,
+          "[dStorage] update is not supported by this chain adapter."
+        );
+      }
+      if (this._encryptionProviders.length === 0) {
+        throw new DStorageError(
+          CoreErrorCode.UPDATE_UPLOAD_REQUIRES_ENCRYPTION,
+          "[dStorage] update requires at least one encryption adapter."
+        );
+      }
+      const { tags = {}, metadata: rawMeta } = options ?? {};
+      const ownerSecret = await this._computeOwnerSecret(refId);
+      const dek = generateDek();
+      try {
+        const scheme = XChaChaScheme.fromKey(dek);
+        const uploadData = await scheme.encryptPayload(bytes, PAYLOAD_AAD);
+        const storageResult = await this.config.storageAdapter.store(
+          uploadData,
+          {
+            ...tags,
+            [TAG_CONTENT_TYPE]: TAG_CONTENT_TYPE_OCTET_STREAM
+          }
+        );
+        const onChainStorageId = await scheme.encryptStorageId(
+          storageResult.id
+        );
+        const wrapperEntries = await Promise.all(
+          this._encryptionProviders.map(async (p) => ({
+            wrapKeyName: p.name,
+            ...await p.wrapDek(dek)
+          }))
+        );
+        const keyEnvelope = serializeKeyEnvelope(
+          buildKeyEnvelope(wrapperEntries)
+        );
+        const encryptedMetadata = rawMeta ? bytesToBase64url(
+          await scheme.encryptPayload(
+            new TextEncoder().encode(JSON.stringify(rawMeta)),
+            METADATA_AAD
+          )
+        ) : void 0;
+        const contentHash = await computeBlake3Hex(uploadData);
+        const rawNewStorageId = new TextEncoder().encode(storageResult.id);
+        const newOwnerSecret = await deriveOwnerSecret(dek, rawNewStorageId);
+        const storeRecovery = {
+          storageId: storageResult.id,
+          storageProvider: storageResult.provider,
+          keyEnvelope,
+          contentHash
+        };
+        options?.onProgress?.({
+          phase: "stored",
+          chunksUploaded: 1,
+          totalChunks: 1,
+          bytesUploaded: bytes.length,
+          totalBytes: bytes.length,
+          recovery: storeRecovery
         });
-        onReceipt?.(receipt);
-        if (!receipt.signedTx) {
-          throw new DStorageError(
-            PaymentErrorCode.MANAGED_UNBALANCED_TX,
-            "[dStorage/payment] Midnight managed payment server did not return a balanced transaction."
+        try {
+          await this.config.chainAdapter.updateReference(
+            refId,
+            {
+              storageId: onChainStorageId,
+              encryptionScheme: "xchacha20poly1305-v1",
+              storageProvider: storageResult.provider,
+              ...encryptedMetadata !== void 0 ? { encryptedMetadata } : {},
+              writtenAt: Date.now(),
+              keyEnvelope,
+              contentHash
+            },
+            ownerSecret,
+            newOwnerSecret
           );
+        } catch {
+          throw new StorePartialError(storeRecovery);
         }
-        const { Transaction } = await import("@midnight-ntwrk/midnight-js-protocol/ledger");
-        return Transaction.deserialize(
-          "signature",
-          "proof",
-          "binding",
-          parseSignedTxBytes(receipt.signedTx)
-        );
+        return { chainRefId: refId, storageId: storageResult.id };
+      } finally {
+        dek.fill(0);
       }
-    };
-  }
-  // ── Network-specific payment handlers ────────────────────────────────────────
-  /**
-   * Arweave remote-signing flow:
-   *   1. Creates the Arweave transaction locally (data + tags, no local signing).
-   *   2. Calls prepareChunks() to compute data_root (Merkle root) locally.
-   *   3. Strips the raw data from the transaction before serialising — only the
-   *      data_root and data_size (not the actual bytes) are sent to the server.
-   *   4. POSTs the stripped transaction JSON to the signing server.
-   *   5. Applies the returned id, signature, and owner to the transaction.
-   *   6. Restores the raw data so the chunked uploader can post it directly to
-   *      the Arweave gateway — the server never sees the file content.
-   *
-   * Falls back to the base-class pass-through if provideUploadData() was not called.
-   */
-  async _payArweave(instruction, onStatus) {
-    if (!this.pendingUpload) {
-      return super.pay(instruction, onStatus);
-    }
-    const { data, metadata } = this.pendingUpload;
-    this.pendingUpload = null;
-    const arweave = await this.getClient();
-    onStatus?.("Creating Arweave transaction\u2026");
-    const tx = await arweave.createTransaction({ data });
-    if (this.ownerPublicKey) {
-      tx.owner = this.ownerPublicKey;
-    }
-    for (const [key, value] of Object.entries(metadata)) {
-      tx.addTag(key, value);
+    } catch (err) {
+      wrapError(err);
     }
-    await tx.prepareChunks(tx.data);
-    const rawData = tx.data;
-    tx.data = new Uint8Array(0);
-    const body = JSON.stringify({
-      txData: tx.toJSON(),
-      network: instruction.network
-    });
-    const {
-      txId,
-      signature,
-      publicKey,
-      txAmount: arCost,
-      serviceFee
-    } = await this._sendSignTxRequest(body, instruction.network, onStatus);
-    assertOwnerKeyMatch(publicKey, this.ownerPublicKey);
-    onStatus?.("Applying remote signature\u2026");
-    tx.setSignature({ id: txId, signature, owner: publicKey });
-    tx.data = rawData;
-    this.signedUpload = { tx, arCost };
-    this.logger?.log(
-      "dStorage/managed-payment",
-      `Transaction signed remotely (${this.signingServerUrl} API service) \u2192 txId: ${txId}  cost: ~${arCost} ${this.token} (service fee: ${serviceFee})`
-    );
-    return {
-      txHash: txId,
-      token: this.token,
-      amount: arCost,
-      type: this.type,
-      paidAt: Date.now(),
-      serviceFee
-    };
   }
   /**
-   * Midnight payment flow:
-   *   POSTs the fee amount to the dStorage API service, which holds a funded
-   *   Midnight account and submits the chain transaction on behalf of the user.
+   * Retry only the on-chain reference write after a failed `update()` call.
    *
-   *   POST {baseUrl}{POST_SIGN_TX_API_PATH}
-   *        → { txData: string (hex-serialized UnboundTransaction), network: string, userId: string }
-   *        ← { txId: string, signature: string (hex-serialized FinalizedTransaction), ... }
+   * Use this when `update()` throws a `StorePartialError` — meaning the new
+   * content was stored successfully but the chain write failed. Call with the
+   * `refId` you passed to `update()` and the `err.recovery` from the caught
+   * error (or the `recovery` emitted via `onProgress` at phase `"stored"`).
    *
-   * The hex-serialized FinalizedTransaction is returned in PaymentReceipt.signedTx
-   * for the chain adapter to deserialize and pass to submitTx().
-   */
-  async _payMidnight(instruction, onStatus) {
-    const body = JSON.stringify({
-      txData: instruction.txData ?? null,
-      network: instruction.network
-    });
-    const {
-      txId,
-      signature,
-      txAmount: dustCost,
-      serviceFee
-    } = await this._sendSignTxRequest(body, instruction.network, onStatus);
-    this.logger?.log(
-      "dStorage/managed-payment",
-      `Midnight Tx signed remotely (${this.signingServerUrl} API service) \u2192 txId: ${txId}  cost: ~${dustCost} ${this.token} (service fee: ${serviceFee})`
-    );
-    return {
-      txHash: txId,
-      token: "DUST",
-      amount: dustCost,
-      type: this.type,
-      signedTx: signature,
-      paidAt: Date.now(),
-      serviceFee
-    };
-  }
-  /**
-   * Arweave Bundler
+   * The new content is already in storage; this method re-derives all chain
+   * write parameters from the recovery envelope without re-uploading.
    */
-  async _payArweaveBundler(instruction, onStatus) {
-    const body = JSON.stringify({
-      txData: instruction.txData ?? null,
-      network: instruction.network,
-      ...instruction.ownerKey !== void 0 ? { ownerKey: instruction.ownerKey } : {}
-    });
-    const {
-      txId,
-      signature,
-      txAmount: arCost,
-      serviceFee
-    } = await this._sendSignTxRequest(body, instruction.network, onStatus);
-    this.logger?.log(
-      "dStorage/managed-payment",
-      `Arweave bundler Tx signed remotely (${this.signingServerUrl} API service) \u2192 txId: ${txId}  cost: ~${arCost} ${this.token} (service fee: ${serviceFee})`
-    );
-    return {
-      txHash: txId,
-      token: "AR",
-      amount: arCost,
-      type: this.type,
-      signedTx: signature,
-      paidAt: Date.now(),
-      serviceFee
-    };
+  async retryUpdate(refId, recovery) {
+    try {
+      this.assertConnected();
+      if (!this.config.chainAdapter) {
+        throw new DStorageError(
+          CoreErrorCode.UPDATE_UPLOAD_REQUIRES_CHAIN,
+          "[dStorage] retryUpdate requires a chain adapter."
+        );
+      }
+      if (typeof this.config.chainAdapter.updateReference !== "function") {
+        throw new DStorageError(
+          CoreErrorCode.UPDATE_UPLOAD_NOT_SUPPORTED,
+          "[dStorage] retryUpdate is not supported by this chain adapter."
+        );
+      }
+      if (this._encryptionProviders.length === 0) {
+        throw new DStorageError(
+          CoreErrorCode.UPDATE_UPLOAD_REQUIRES_ENCRYPTION,
+          "[dStorage] retryUpdate requires at least one encryption adapter."
+        );
+      }
+      if (!recovery.keyEnvelope) {
+        throw new DStorageError(
+          CoreErrorCode.UNWRAP_DEK_ENVELOPE_EMPTY,
+          "[dStorage] retryUpdate requires a key envelope in the recovery object."
+        );
+      }
+      const dek = await this._unwrapDek(recovery.keyEnvelope);
+      try {
+        const scheme = XChaChaScheme.fromKey(dek);
+        const ownerSecret = await this._computeOwnerSecret(refId);
+        const onChainStorageId = await scheme.encryptStorageId(
+          recovery.storageId
+        );
+        const newOwnerSecret = await deriveOwnerSecret(
+          dek,
+          new TextEncoder().encode(recovery.storageId)
+        );
+        await this.config.chainAdapter.updateReference(
+          refId,
+          {
+            storageId: onChainStorageId,
+            encryptionScheme: "xchacha20poly1305-v1",
+            storageProvider: recovery.storageProvider,
+            writtenAt: Date.now(),
+            keyEnvelope: recovery.keyEnvelope,
+            ...recovery.contentHash !== void 0 ? { contentHash: recovery.contentHash } : {}
+          },
+          ownerSecret,
+          newOwnerSecret
+        );
+        return { chainRefId: refId, storageId: recovery.storageId };
+      } finally {
+        dek.fill(0);
+      }
+    } catch (err) {
+      wrapError(err);
+    }
   }
   /**
-   * Managed mock flow:
-   *   Sends a minimal request to the signing server with the literal network
-   *   identifier "TEST" — the server treats this as a sandbox/test flow with no
-   *   real funds involved. The SDK-side network name is "managedmock" to follow
-   *   the lowercase naming convention; the server-side string is always "TEST".
+   * Rotate the encryption adapters protecting an existing reference without
+   * re-uploading the content.
+   *
+   * Useful when you want to:
+   * - Change a password: configure [newPassword, mnemonic] and call rotateKeys().
+   *   The mnemonic unwraps the old DEK, the new envelope is wrapped under both
+   *   new adapters, and the old password wrapper is dropped.
+   * - Add or remove adapters: any single adapter that matches a wrapper in the
+   *   existing key envelope can authorise the rotation. The resulting envelope
+   *   is wrapped under exactly the adapters currently configured on this SDK.
+   *
+   * The content in storage is not touched — only the on-chain key envelope is
+   * updated. writtenAt is preserved to reflect the original upload time.
    */
-  async _payManagedMock(instruction, onStatus) {
-    const body = JSON.stringify({
-      txData: instruction.txData || "mock",
-      network: "TEST"
-    });
-    const { txId, txAmount, serviceFee } = await this._sendSignTxRequest(
-      body,
-      "TEST",
-      onStatus
-    );
-    this.logger?.log(
-      "dStorage/managed-payment",
-      `ManagedMock Tx signed remotely (${this.signingServerUrl}) \u2192 txId: ${txId}  cost: ~${txAmount} MOCK (service fee: ${serviceFee})`
-    );
-    return {
-      txHash: txId,
-      token: "MOCK",
-      amount: txAmount,
-      type: this.type,
-      paidAt: Date.now(),
-      serviceFee
-    };
+  async rotateKeys(refId) {
+    try {
+      this.assertConnected();
+      if (!this.config.chainAdapter) {
+        throw new DStorageError(
+          CoreErrorCode.ROTATE_KEYS_REQUIRES_CHAIN,
+          "[dStorage] rotateKeys requires a chain adapter."
+        );
+      }
+      if (typeof this.config.chainAdapter.updateReference !== "function") {
+        throw new DStorageError(
+          CoreErrorCode.ROTATE_KEYS_NOT_SUPPORTED,
+          "[dStorage] rotateKeys is not supported by this chain adapter."
+        );
+      }
+      if (this._encryptionProviders.length === 0) {
+        throw new DStorageError(
+          CoreErrorCode.ROTATE_KEYS_REQUIRES_ENCRYPTION,
+          "[dStorage] rotateKeys requires at least one encryption adapter."
+        );
+      }
+      const ref = await this.config.chainAdapter.readReference(refId);
+      const ownerSecret = await this._computeOwnerSecret(refId);
+      const seed = await this._unwrapDek(ref.keyEnvelope);
+      try {
+        const wrapperEntries = await Promise.all(
+          this._encryptionProviders.map(async (p) => ({
+            wrapKeyName: p.name,
+            ...await p.wrapDek(seed)
+          }))
+        );
+        const newKeyEnvelope = serializeKeyEnvelope(
+          buildKeyEnvelope(wrapperEntries)
+        );
+        await this.config.chainAdapter.updateReference(
+          refId,
+          {
+            storageId: ref.storageId ?? "",
+            encryptionScheme: ref.encryptionScheme ?? "",
+            storageProvider: ref.storageProvider,
+            writtenAt: ref.writtenAt,
+            keyEnvelope: newKeyEnvelope,
+            ...ref.encryptedMetadata !== void 0 ? { encryptedMetadata: ref.encryptedMetadata } : {},
+            ...ref.contentHash !== void 0 ? { contentHash: ref.contentHash } : {}
+          },
+          ownerSecret,
+          ownerSecret
+        );
+      } finally {
+        seed.fill(0);
+      }
+    } catch (err) {
+      wrapError(err);
+    }
   }
   /**
-   * Shared HTTP helper: POSTs a transaction payload to the signing server and
-   * returns the parsed SignTxResponse.
+   * Retrieve and decrypt data by its storageId.
+   * Decryption happens locally — the SDK never sends plaintext anywhere.
    *
-   * - Arweave: txJson is the Arweave tx JSON object (from tx.toJSON()); the server
-   *   signs it and returns the signature + owner in the response fields.
-   * - Midnight: txJson is the hex-serialized UnboundTransaction; the server balances
-   *   and signs it, returning the hex-serialized FinalizedTransaction in the
-   *   `signature` response field.
+   * Automatically detects chunked manifests and reassembles the original file.
    *
-   * Throws on network errors or non-2xx HTTP responses.
+   * @param storageId  The storageId returned from store()
    */
-  async _sendSignTxRequest(body, network, onStatus) {
-    onStatus?.(`Sending ${network} transaction to signing server\u2026`);
-    let signResp;
+  async retrieveByStorageId(storageId, dekScheme, contentHash) {
     try {
-      this.logger?.log(
-        "dStorage/managed-payment",
-        `${network}: delegating to managed payment service (serialized req length=${body.length})`
-      );
-      const signal = this.requestTimeoutMs > 0 ? AbortSignal.timeout(this.requestTimeoutMs) : void 0;
-      signResp = await fetch(
-        `${this.signingServerUrl}${POST_SIGN_TX_API_PATH}`,
-        {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${this.authToken}`
-          },
-          body,
-          ...signal !== void 0 ? { signal } : {}
+      this.assertConnected();
+      const { bytes: rawBytes, tags } = await this.config.storageAdapter.retrieve(storageId);
+      if (contentHash) {
+        const computed = await computeBlake3Hex(rawBytes);
+        if (computed !== contentHash) {
+          throw new DStorageError(
+            CoreErrorCode.CONTENT_HASH_MISMATCH,
+            `[dStorage] Content hash mismatch for storageId ${storageId}. Expected ${contentHash}, got ${computed}. The retrieved bytes do not match the hash committed on-chain \u2014 the storage content may have been tampered with.`
+          );
         }
-      );
+      }
+      return this._decryptAndReassemble(rawBytes, storageId, tags, dekScheme);
     } catch (err) {
+      wrapError(err);
+    }
+  }
+  /**
+   * Unwrap the data DEK from a key envelope and return an XChaChaScheme built from it.
+   * Throws if the KEK is not available or the envelope cannot be parsed.
+   * Only valid for private uploads (envelope.wrappers must be present).
+   */
+  async _getDekScheme(keyEnvelope) {
+    if (this._encryptionProviders.length === 0) {
       throw new DStorageError(
-        PaymentErrorCode.MANAGED_SERVER_UNREACHABLE,
-        `[dStorage/managed-payment] Could not reach signing server: ${err}`,
-        { cause: err }
+        CoreErrorCode.DECRYPT_NO_PROVIDERS,
+        "[dStorage] Cannot decrypt: no encryption providers. Call init() before retrieving private data."
       );
     }
-    if (signResp.status === 409) {
+    if (!keyEnvelope) {
       throw new DStorageError(
-        PaymentErrorCode.MANAGED_KEY_CHANGED,
-        "[dStorage/managed-payment] Signing server key has changed \u2014 re-issue your API token to obtain the updated public key."
+        CoreErrorCode.DECRYPT_ENVELOPE_EMPTY,
+        "[dStorage] Cannot decrypt: key envelope is empty.",
+        { cause: { code: "envelope_empty" } }
       );
     }
-    if (!signResp.ok) {
-      const rawBody = await signResp.text().catch(() => "");
-      const body2 = sanitiseErrorBody(rawBody);
+    const envelope = parseKeyEnvelope(keyEnvelope);
+    if (!envelope) {
       throw new DStorageError(
-        PaymentErrorCode.MANAGED_SIGN_HTTP_ERROR,
-        `[dStorage/managed-payment] POST ${POST_SIGN_TX_API_PATH} failed: HTTP ${signResp.status}${body2 ? ` \u2014 ${body2}` : ""}`
+        CoreErrorCode.DECRYPT_ENVELOPE_MALFORMED,
+        "[dStorage] Cannot decrypt: key envelope is malformed or has an invalid structure. The stored reference may be corrupted or tampered with.",
+        { cause: { code: "envelope_malformed" } }
       );
     }
-    let parsed;
-    try {
-      parsed = await signResp.json();
-    } catch {
-      throw new DStorageError(
-        PaymentErrorCode.MANAGED_NON_JSON_RESPONSE,
-        `[dStorage/managed-payment] Managed payment service returned a non-JSON response \u2014 check that the service URL is correct and reachable: ${this.signingServerUrl}${POST_SIGN_TX_API_PATH}`
+    for (const wrapper of envelope.wrappers) {
+      const provider = this._encryptionProviders.find(
+        (p) => p.name === wrapper.wrapKeyName
       );
+      if (!provider) continue;
+      try {
+        const dek = await provider.unwrapDek(wrapper);
+        return XChaChaScheme.fromKey(dek);
+      } catch {
+      }
     }
-    return parseSignTxResponse(parsed);
-  }
-};
-
-// src/chunked.ts
-var CHUNK_SIZE = 10 * 1024 * 1024;
-var MAX_CHUNK_COUNT = 1e4;
-var MAX_REASSEMBLY_BYTES = MAX_CHUNK_COUNT * CHUNK_SIZE;
-function isManifest(payload) {
-  if (typeof payload !== "object" || payload === null) return false;
-  const m = payload;
-  if (m["type"] !== "dstorage-chunked-manifest") return false;
-  return Number.isInteger(m["totalSize"]) && m["totalSize"] >= 0 && m["totalSize"] <= MAX_REASSEMBLY_BYTES && Number.isInteger(m["chunkSize"]) && m["chunkSize"] > 0 && Number.isInteger(m["chunkCount"]) && m["chunkCount"] >= 0 && m["chunkCount"] <= MAX_CHUNK_COUNT;
-}
-
-// src/dStorage.ts
-var TAG_SDK_VERSION = "dStorage-Version";
-var TAG_CONTENT_TYPE = "Content-Type";
-var TAG_CONTENT_TYPE_OCTET_STREAM = "application/octet-stream";
-var TAG_CONTENT_TYPE_JSON = "application/json";
-var TAG_CHUNK_INDEX = "dStorage-Chunk-Index";
-var TAG_CHUNK_TOTAL = "dStorage-Chunk-Total";
-var TAG_MANIFEST_UPLOAD = "dStorage-Manifest-Upload";
-function wrapError(err) {
-  if (err instanceof DStorageError || isDStorageError(err)) throw err;
-  throw new DStorageError(
-    CoreErrorCode.UNKNOWN_ERROR,
-    `[dStorage] Unexpected error: ${err instanceof Error ? err.message : String(err)}`,
-    { cause: err }
-  );
-}
-var DStorage = class {
-  constructor(config) {
-    this.wallet = null;
-    /** Encryption adapters — each wraps/unwraps per-upload DEKs using its own algorithm. */
-    this._encryptionProviders = [];
-    this._initialized = false;
-    this.config = config;
-    this.logger = config.logger;
-  }
-  // ── DStorageContext interface — public accessors ───────────────────────────
-  get storageAdapter() {
-    return this.config.storageAdapter;
-  }
-  get chainAdapter() {
-    return this.config.chainAdapter;
+    throw new DStorageError(
+      CoreErrorCode.DECRYPT_NO_WRAPPER_MATCHED,
+      "[dStorage] Cannot decrypt: this reference was not encrypted with any of your configured keys. Check that you are using the correct encryption adapter, password, seed phrase, or keypair.",
+      { cause: { code: "no_wrapper_matched" } }
+    );
   }
-  // ── Lifecycle ─────────────────────────────────────────────────────────────
   /**
-   * Initialize the SDK:
-   *   1. Initialize the chain adapter wallet (if supported), and
-   *      deploy a new DataRegistry contract, or connect to an existing one.
-   *   2. Derive an encryption key from the chain adapter's credentials (if supported).
-   *
-   * Returns the address of the DataRegistry contract in use.
-   * Call this instead of connect() when using MidnightChainAdapter directly.
+   * Unwrap the raw DEK bytes from a key envelope using the available KEKs.
+   * The ownerSecret for the reference can be re-derived as HKDF(dek, rawStorageId).
+   * Throws if no wrapper matches any available KEK.
    */
-  async init() {
-    try {
-      if (this.config.chainAdapter?.init) {
-        await this.config.chainAdapter.init();
+  async _unwrapDek(keyEnvelope) {
+    if (this._encryptionProviders.length === 0) {
+      throw new DStorageError(
+        CoreErrorCode.UNWRAP_DEK_NO_PROVIDERS,
+        "[dStorage] Cannot unwrap DEK: no encryption providers. Call init() first."
+      );
+    }
+    if (!keyEnvelope) {
+      throw new DStorageError(
+        CoreErrorCode.UNWRAP_DEK_ENVELOPE_EMPTY,
+        "[dStorage] Cannot unwrap DEK: key envelope is empty.",
+        { cause: { code: "envelope_empty" } }
+      );
+    }
+    const envelope = parseKeyEnvelope(keyEnvelope);
+    if (!envelope) {
+      throw new DStorageError(
+        CoreErrorCode.UNWRAP_DEK_ENVELOPE_MALFORMED,
+        "[dStorage] Cannot unwrap DEK: key envelope is malformed or has an invalid structure. The stored reference may be corrupted or tampered with.",
+        { cause: { code: "envelope_malformed" } }
+      );
+    }
+    for (const wrapper of envelope.wrappers) {
+      const provider = this._encryptionProviders.find(
+        (p) => p.name === wrapper.wrapKeyName
+      );
+      if (!provider) continue;
+      try {
+        return await provider.unwrapDek(wrapper);
+      } catch {
       }
-      this._encryptionProviders = this.config.encryptionAdapters ?? [];
-      this._initialized = true;
-      return this.config.chainAdapter?.getContractAddress();
-    } catch (err) {
-      wrapError(err);
     }
-  }
-  /** Tear down active state and clear all in-memory key material. */
-  destroy() {
-    this.wallet = null;
-    this._encryptionProviders = [];
-    this._initialized = false;
-    this.logger?.log(
-      "dStorage",
-      "Destroyed \u2014 encryption key cleared from memory."
+    throw new DStorageError(
+      CoreErrorCode.UNWRAP_DEK_NO_WRAPPER_MATCHED,
+      "[dStorage] Cannot unwrap DEK: this reference was not encrypted with any of your configured keys. Check that you are using the correct encryption adapter, password, seed phrase, or keypair.",
+      { cause: { code: "no_wrapper_matched" } }
     );
   }
-  get isConnected() {
-    return this._initialized || this.wallet !== null;
-  }
-  get connectedAddress() {
-    return this.wallet?.address ?? null;
-  }
-  // ── Core operations ───────────────────────────────────────────────────────
   /**
-   * Encrypt content client-side, store to decentralised storage,
-   * and write a cryptographic reference on-chain.
-   *
-   * Files larger than CHUNK_SIZE (10 MB) are automatically split into chunks,
-   * each encrypted and stored independently. A manifest file ties them together.
-   * Only the manifest's storageId is written on-chain.
+   * Compute the ownerSecret for an existing on-chain reference.
+   * Used by removeReference/updateReference to derive the ZK witness secret.
    *
-   * @param bytes    Uint8Array to store
-   * @param options  Optional StoreOptions (metadata, onProgress, isPublic, refId)
-   * @returns        StoreResult containing the chainRefId/storageId needed to retrieve later
+   * Flow:
+   *   1. Read the reference from chain to get keyEnvelope + storageId
+   *   2. Unwrap the DEK from keyEnvelope using available KEKs
+   *   3. Recover raw storageId (decrypt with DEK if private, plaintext if public)
+   *   4. Return HKDF-SHA256(dek, rawStorageId) for private, or HKDF-SHA256(ownerSeed, rawStorageId) for public
    */
-  async store(bytes, options) {
-    try {
-      this.assertConnected();
-      const {
-        tags = {},
-        metadata: rawMeta,
-        onProgress,
-        isPublic = false,
-        refId
-      } = options ?? {};
-      if (rawMeta !== void 0 && isPublic) {
-        throw new DStorageError(
-          CoreErrorCode.METADATA_WITH_PUBLIC_UPLOAD,
-          "[dStorage] metadata cannot be used with isPublic uploads \u2014 there is no DEK to encrypt it with."
-        );
-      }
-      if (bytes.length > CHUNK_SIZE) {
-        return this._uploadChunked(
-          bytes,
-          tags,
-          onProgress,
-          isPublic,
-          rawMeta,
-          refId
-        );
-      }
-      let uploadData;
-      let onChainStorageId;
-      const encryptionScheme = isPublic ? "" : "xchacha20poly1305-v1";
-      let uploadScheme = null;
-      let keyEnvelope = "";
-      let dek = null;
-      let ownerSecret = new Uint8Array(0);
-      if (isPublic) {
-        uploadData = bytes;
-      } else {
-        if (this._encryptionProviders.length === 0) {
-          throw new DStorageError(
-            CoreErrorCode.UPLOAD_NO_PROVIDERS,
-            "[dStorage] No encryption providers available. Call init() before uploading."
-          );
-        }
-        dek = generateDek();
-        uploadScheme = XChaChaScheme.fromKey(dek);
-        this.logger?.log(
-          "dStorage",
-          `Encrypting content using scheme: ${encryptionScheme}`
-        );
-        uploadData = await uploadScheme.encryptPayload(bytes, PAYLOAD_AAD);
-        const wrapperEntries = await Promise.all(
-          this._encryptionProviders.map(async (provider) => ({
-            wrapKeyName: provider.name,
-            ...await provider.wrapDek(dek)
-          }))
-        );
-        keyEnvelope = serializeKeyEnvelope(buildKeyEnvelope(wrapperEntries));
-      }
-      const sdkVersion = package_default.version ?? "unknown";
-      const storageResult = await this.config.storageAdapter.store(uploadData, {
-        ...tags,
-        [TAG_SDK_VERSION]: sdkVersion,
-        [TAG_CONTENT_TYPE]: TAG_CONTENT_TYPE_OCTET_STREAM
-      });
-      if (isPublic) {
-        if (this.config.chainAdapter) {
-          if (this._encryptionProviders.length === 0) {
-            throw new DStorageError(
-              CoreErrorCode.PUBLIC_UPLOAD_REQUIRES_SEED_PROVIDER,
-              "[dStorage] Cannot store public data without at least one encryption seed provider. Without a provider there is no owner secret, so the reference could never be removed or updated."
-            );
-          }
-          const ownerSeed = generateDek();
-          const ownerSeedWrappers = await Promise.all(
-            this._encryptionProviders.map(async (provider) => ({
-              wrapKeyName: provider.name,
-              ...await provider.wrapDek(ownerSeed)
-            }))
-          );
-          keyEnvelope = serializeKeyEnvelope(
-            buildKeyEnvelope(ownerSeedWrappers)
-          );
-          ownerSecret = await deriveOwnerSecret(
-            ownerSeed,
-            new TextEncoder().encode(storageResult.id),
-            "dstorage:owner-secret:public:v1"
-          );
-        }
-        onChainStorageId = storageResult.id;
-      } else {
-        onChainStorageId = await uploadScheme.encryptStorageId(
-          storageResult.id
-        );
-        ownerSecret = await deriveOwnerSecret(
-          dek,
-          new TextEncoder().encode(storageResult.id)
-        );
-      }
-      const storageCost = {
-        amount: storageResult.cost?.amount ?? "unknown",
-        token: storageResult.cost?.token ?? "AR"
-      };
-      if (this.config.chainAdapter) {
-        const contentHash = await computeBlake3Hex(uploadData);
-        const storeRecovery = {
-          storageId: storageResult.id,
-          storageProvider: storageResult.provider,
-          keyEnvelope: isPublic ? void 0 : keyEnvelope,
-          contentHash
-        };
-        onProgress?.({
-          phase: "stored",
-          chunksUploaded: 1,
-          totalChunks: 1,
-          bytesUploaded: bytes.length,
-          totalBytes: bytes.length,
-          recovery: storeRecovery
-        });
-        const encryptedMetadata = rawMeta ? bytesToBase64url(
-          await uploadScheme.encryptPayload(
-            new TextEncoder().encode(JSON.stringify(rawMeta)),
-            METADATA_AAD
-          )
-        ) : void 0;
-        try {
-          const chainResult = await this.config.chainAdapter.writeReference({
-            storageId: onChainStorageId,
-            encryptionScheme,
-            storageProvider: storageResult.provider,
-            ...refId !== void 0 ? { refId } : {},
-            ...encryptedMetadata !== void 0 ? { encryptedMetadata } : {},
-            writtenAt: Date.now(),
-            keyEnvelope,
-            contentHash,
-            ownerSecret
-          });
-          const resultRefId = chainResult.refId;
-          this.logger?.log(
-            "dStorage",
-            `Upload complete \u2192 refId: ${resultRefId}`
-          );
-          return {
-            chainRefId: resultRefId,
-            storageId: storageResult.id,
-            storageProvider: storageResult.provider,
-            chainProvider: chainResult.provider,
-            uploadedAt: storageResult.uploadedAt,
-            encryptionScheme,
-            costEstimate: {
-              storageCost,
-              chainCost: {
-                amount: chainResult.paymentReceipt?.amount ?? "unknown",
-                token: chainResult.paymentReceipt?.token ?? "DUST"
-              },
-              fileSizeBytes: uploadData.length
-            }
-          };
-        } catch {
-          throw new StorePartialError(storeRecovery);
-        }
-      }
-      this.logger?.log(
-        "dStorage",
-        `Upload complete (storage-only) \u2192 storageId: ${storageResult.id}`
+  async _computeOwnerSecret(refId) {
+    const ref = await this.config.chainAdapter.readReference(refId);
+    const isPublic = !ref.encryptionScheme;
+    if (isPublic) {
+      const ownerSeed = await this._unwrapDek(ref.keyEnvelope);
+      return deriveOwnerSecret(
+        ownerSeed,
+        new TextEncoder().encode(ref.storageId),
+        "dstorage:owner-secret:public:v1"
       );
-      return {
-        storageId: storageResult.id,
-        storageProvider: storageResult.provider,
-        uploadedAt: storageResult.uploadedAt,
-        encryptionScheme,
-        ...uploadScheme ? { cryptoScheme: uploadScheme } : {},
-        costEstimate: { storageCost, fileSizeBytes: uploadData.length }
-      };
-    } catch (err) {
-      wrapError(err);
     }
+    const dek = await this._unwrapDek(ref.keyEnvelope);
+    const dekScheme = XChaChaScheme.fromKey(dek);
+    const rawStorageIdBytes = ref.storageId ? new TextEncoder().encode(
+      await dekScheme.decryptStorageId(ref.storageId)
+    ) : METADATA_ONLY_OWNER_SECRET_SALT;
+    return deriveOwnerSecret(dek, rawStorageIdBytes);
   }
-  /**
-   * Register a pre-existing storageId as a new on-chain reference.
-   *
-   * Use this when data has already been uploaded to the storage network by
-   * other means (e.g. a third-party tool or a separate pipeline). The content
-   * is not touched — only the chain reference is created.
-   *
-   * A fresh DEK is generated solely to encrypt the storageId and derive the
-   * ownerSecret. The resulting reference round-trips through retrieveByRefId()
-   * exactly like one created by store().
-   *
-   * Note: chunked manifests are not handled here. For large pre-existing
-   * uploads already split into chunks, register the manifest storageId.
-   */
-  async registerReference(options = {}) {
-    try {
-      this.assertConnected();
-      if (!this.config.chainAdapter) {
-        throw new DStorageError(
-          CoreErrorCode.REGISTER_REF_REQUIRES_CHAIN,
-          "[dStorage] registerReference requires a chain adapter."
+  // Accepts an optional pre-built CryptoScheme (unwrapped from a key envelope).
+  // If no dekScheme is provided, content is treated as public (no decryption).
+  async _decryptAndReassemble(rawBytes, storageId, tags, dekScheme) {
+    const scheme = dekScheme ?? null;
+    if (scheme) {
+      let manifestBytes = null;
+      try {
+        manifestBytes = await scheme.decryptPayload(rawBytes, MANIFEST_AAD);
+      } catch {
+      }
+      if (manifestBytes !== null) {
+        const parsed = JSON.parse(
+          new TextDecoder().decode(manifestBytes)
+        );
+        if (!isManifest(parsed)) {
+          throw new DStorageError(
+            CoreErrorCode.MANIFEST_INVALID_STRUCTURE,
+            "[dStorage] Payload authenticated as manifest but has invalid structure"
+          );
+        }
+        this.logger?.log(
+          "dStorage",
+          `Manifest detected: reassembling ${parsed.chunkCount} chunks`
         );
+        return this._retrieveChunked(parsed, scheme, tags);
       }
-      if (this._encryptionProviders.length === 0) {
+      let decryptedBytes;
+      try {
+        decryptedBytes = await scheme.decryptPayload(rawBytes, PAYLOAD_AAD);
+      } catch (err) {
         throw new DStorageError(
-          CoreErrorCode.REGISTER_REF_REQUIRES_ENCRYPTION,
-          "[dStorage] registerReference requires at least one encryption adapter."
+          CoreErrorCode.DECRYPT_PAYLOAD_FAILED,
+          `[dStorage] Failed to decrypt payload: ${err}`,
+          { cause: err }
         );
       }
-      let dek;
-      const recoveryEnvelope = options.keyEnvelope;
-      if (recoveryEnvelope) {
-        dek = await this._unwrapDek(recoveryEnvelope);
-      } else {
-        dek = generateDek();
-      }
-      try {
-        const scheme = XChaChaScheme.fromKey(dek);
-        const { metadata: rawMeta } = options;
-        const encryptedMetadata = rawMeta ? bytesToBase64url(
-          await scheme.encryptPayload(
-            new TextEncoder().encode(JSON.stringify(rawMeta)),
-            METADATA_AAD
-          )
-        ) : void 0;
-        const onChainStorageId = options.storageId !== void 0 ? await scheme.encryptStorageId(options.storageId) : void 0;
-        let keyEnvelope;
-        if (recoveryEnvelope !== void 0) {
-          keyEnvelope = recoveryEnvelope;
-        } else {
-          const wrapperEntries = await Promise.all(
-            this._encryptionProviders.map(async (p) => ({
-              wrapKeyName: p.name,
-              ...await p.wrapDek(dek)
-            }))
-          );
-          keyEnvelope = serializeKeyEnvelope(buildKeyEnvelope(wrapperEntries));
-        }
-        const ownerSecret = await deriveOwnerSecret(
-          dek,
-          options.storageId !== void 0 ? new TextEncoder().encode(options.storageId) : METADATA_ONLY_OWNER_SECRET_SALT
+      this.logger?.log(
+        "dStorage",
+        `Retrieved by refId \u2192 storageId: ${storageId}`
+      );
+      return { bytes: decryptedBytes, metadata: {}, tags };
+    }
+    try {
+      const parsed = JSON.parse(new TextDecoder().decode(rawBytes));
+      if (isManifest(parsed)) {
+        this.logger?.log(
+          "dStorage",
+          `Manifest detected: reassembling ${parsed.chunkCount} chunks`
         );
-        const chainResult = await this.config.chainAdapter.writeReference({
-          ...onChainStorageId !== void 0 ? { storageId: onChainStorageId } : {},
-          encryptionScheme: "xchacha20poly1305-v1",
-          storageProvider: options.storageProvider ?? this.config.storageAdapter.name,
-          ...options.refId !== void 0 ? { refId: options.refId } : {},
-          ...encryptedMetadata !== void 0 ? { encryptedMetadata } : {},
-          writtenAt: Date.now(),
-          keyEnvelope,
-          ...options.contentHash !== void 0 ? { contentHash: options.contentHash } : {},
-          ownerSecret
-        });
-        return { chainRefId: chainResult.refId };
-      } finally {
-        dek.fill(0);
+        return this._retrieveChunked(parsed, null, tags);
       }
-    } catch (err) {
-      wrapError(err);
+    } catch {
     }
+    this.logger?.log(
+      "dStorage",
+      `Retrieved by refId \u2192 storageId: ${storageId}`
+    );
+    return {
+      bytes: rawBytes,
+      metadata: {},
+      tags
+    };
   }
   /**
-   * Store new content and update an existing on-chain reference in place.
+   * Retrieve and decrypt data using only its on-chain reference ID.
    *
-   * Ownership is proved by re-deriving the ownerSecret from the existing
-   * reference — the same mechanism used by removeReference(). A fresh DEK is
-   * generated for the new content; the previous version is not modified and remains
-   * independently decryptable if the caller retained the old storageId.
+   * Flow:
+   *   1. Look up the reference on-chain by refId to obtain the storage network ID.
+   *   2. Fetch the blob from the storage network.
+   *   3. Decrypt locally if an encryption key is available.
    *
-   * Note: chunking is not applied here. For large files use store() to get a
-   * new chunked reference, then removeReference() on the old one.
+   * Requires the chain adapter to implement readReference() (part of the
+   * ChainAdapter interface — shared by MidnightChainAdapter, MockChainAdapter, etc.).
    *
-   * @param refId    The chain reference to update (returned by a prior store/registerReference).
-   * @param bytes    New content to encrypt and store.
-   * @param options  Optional StoreOptions. isPublic is ignored.
+   * @param refId  The chainRefId returned from store()
    */
-  async update(refId, bytes, options) {
+  async retrieveByRefId(refId) {
     try {
       this.assertConnected();
       if (!this.config.chainAdapter) {
         throw new DStorageError(
-          CoreErrorCode.UPDATE_UPLOAD_REQUIRES_CHAIN,
-          "[dStorage] update requires a chain adapter."
+          CoreErrorCode.RETRIEVE_BY_REF_ID_REQUIRES_CHAIN,
+          "[dStorage] retrieveByRefId() requires a chain adapter. Configure one in DStorageConfig or use retrieveByStorageId() instead."
         );
       }
-      if (typeof this.config.chainAdapter.updateReference !== "function") {
+      const ref = await this.config.chainAdapter.readReference(refId);
+      if (!ref)
         throw new DStorageError(
-          CoreErrorCode.UPDATE_UPLOAD_NOT_SUPPORTED,
-          "[dStorage] update is not supported by this chain adapter."
+          CoreErrorCode.REF_NOT_FOUND,
+          `[dStorage] No on-chain reference found for refId: ${refId}`
         );
-      }
-      if (this._encryptionProviders.length === 0) {
+      if (ref.storageProvider && ref.storageProvider !== this.config.storageAdapter.name) {
         throw new DStorageError(
-          CoreErrorCode.UPDATE_UPLOAD_REQUIRES_ENCRYPTION,
-          "[dStorage] update requires at least one encryption adapter."
+          CoreErrorCode.STORAGE_ADAPTER_MISMATCH,
+          `[dStorage] Storage adapter mismatch: reference "${refId}" was stored on "${ref.storageProvider}" but the configured adapter is "${this.config.storageAdapter.name}". Configure a "${ref.storageProvider}" storage adapter to retrieve this reference.`
         );
       }
-      const { tags = {}, metadata: rawMeta } = options ?? {};
-      const ownerSecret = await this._computeOwnerSecret(refId);
-      const dek = generateDek();
-      try {
-        const scheme = XChaChaScheme.fromKey(dek);
-        const uploadData = await scheme.encryptPayload(bytes, PAYLOAD_AAD);
-        const storageResult = await this.config.storageAdapter.store(
-          uploadData,
-          {
-            ...tags,
-            [TAG_CONTENT_TYPE]: TAG_CONTENT_TYPE_OCTET_STREAM
-          }
-        );
-        const onChainStorageId = await scheme.encryptStorageId(
-          storageResult.id
-        );
-        const wrapperEntries = await Promise.all(
-          this._encryptionProviders.map(async (p) => ({
-            wrapKeyName: p.name,
-            ...await p.wrapDek(dek)
-          }))
-        );
-        const keyEnvelope = serializeKeyEnvelope(
-          buildKeyEnvelope(wrapperEntries)
-        );
-        const encryptedMetadata = rawMeta ? bytesToBase64url(
-          await scheme.encryptPayload(
-            new TextEncoder().encode(JSON.stringify(rawMeta)),
-            METADATA_AAD
-          )
-        ) : void 0;
-        const contentHash = await computeBlake3Hex(uploadData);
-        const rawNewStorageId = new TextEncoder().encode(storageResult.id);
-        const newOwnerSecret = await deriveOwnerSecret(dek, rawNewStorageId);
-        const storeRecovery = {
-          storageId: storageResult.id,
-          storageProvider: storageResult.provider,
-          keyEnvelope,
-          contentHash
-        };
-        options?.onProgress?.({
-          phase: "stored",
-          chunksUploaded: 1,
-          totalChunks: 1,
-          bytesUploaded: bytes.length,
-          totalBytes: bytes.length,
-          recovery: storeRecovery
-        });
-        try {
-          await this.config.chainAdapter.updateReference(
-            refId,
-            {
-              storageId: onChainStorageId,
-              encryptionScheme: "xchacha20poly1305-v1",
-              storageProvider: storageResult.provider,
-              ...encryptedMetadata !== void 0 ? { encryptedMetadata } : {},
-              writtenAt: Date.now(),
-              keyEnvelope,
-              contentHash
-            },
-            ownerSecret,
-            newOwnerSecret
+      const isPublic = !ref.encryptionScheme;
+      let storageId;
+      let dekScheme;
+      if (!ref.storageId) {
+        if (!isPublic && ref.keyEnvelope) {
+          dekScheme = await this._getDekScheme(ref.keyEnvelope);
+        }
+      } else if (isPublic) {
+        storageId = ref.storageId;
+      } else {
+        if (!ref.keyEnvelope) {
+          throw new DStorageError(
+            CoreErrorCode.RETRIEVE_BY_REF_ID_ENVELOPE_EMPTY,
+            `[dStorage] Cannot decrypt refId ${refId}: key envelope is empty.`,
+            { cause: { code: "envelope_empty" } }
           );
-        } catch {
-          throw new StorePartialError(storeRecovery);
         }
-        return { chainRefId: refId, storageId: storageResult.id };
-      } finally {
-        dek.fill(0);
+        dekScheme = await this._getDekScheme(ref.keyEnvelope);
+        storageId = await dekScheme.decryptStorageId(ref.storageId);
+      }
+      let contentBytes;
+      let contentTags;
+      if (storageId !== void 0) {
+        const r = await this.retrieveByStorageId(
+          storageId,
+          dekScheme,
+          ref.contentHash
+        );
+        contentBytes = r.bytes;
+        contentTags = r.tags;
+      } else {
+        contentBytes = new Uint8Array(0);
+        contentTags = {};
+      }
+      let metadata = {};
+      if (ref.encryptedMetadata && dekScheme) {
+        const raw = await dekScheme.decryptPayload(
+          base64urlToBytes(ref.encryptedMetadata),
+          METADATA_AAD
+        );
+        metadata = JSON.parse(new TextDecoder().decode(raw));
       }
+      return { bytes: contentBytes, tags: contentTags, metadata };
     } catch (err) {
       wrapError(err);
     }
   }
   /**
-   * Retry only the on-chain reference write after a failed `update()` call.
-   *
-   * Use this when `update()` throws a `StorePartialError` — meaning the new
-   * content was stored successfully but the chain write failed. Call with the
-   * `refId` you passed to `update()` and the `err.recovery` from the caught
-   * error (or the `recovery` emitted via `onProgress` at phase `"stored"`).
-   *
-   * The new content is already in storage; this method re-derives all chain
-   * write parameters from the recovery envelope without re-uploading.
+   * List references currently available from the configured chain adapter.
    */
-  async retryUpdate(refId, recovery) {
+  async listReferences(options) {
     try {
-      this.assertConnected();
       if (!this.config.chainAdapter) {
         throw new DStorageError(
-          CoreErrorCode.UPDATE_UPLOAD_REQUIRES_CHAIN,
-          "[dStorage] retryUpdate requires a chain adapter."
+          CoreErrorCode.LIST_REFS_REQUIRES_CHAIN,
+          "[dStorage] listReferences() requires a chain adapter."
         );
       }
-      if (typeof this.config.chainAdapter.updateReference !== "function") {
-        throw new DStorageError(
-          CoreErrorCode.UPDATE_UPLOAD_NOT_SUPPORTED,
-          "[dStorage] retryUpdate is not supported by this chain adapter."
+      let rawItems;
+      if (options?.refIds && options.refIds.length > 0) {
+        rawItems = await Promise.all(
+          options.refIds.map(async (refId) => {
+            const ref = await this.config.chainAdapter.readReference(refId);
+            return {
+              refId,
+              storageId: ref.storageId ?? null,
+              encryptionScheme: ref.encryptionScheme ?? null,
+              keyEnvelope: ref.keyEnvelope,
+              storageProvider: ref.storageProvider,
+              ownerCommitment: "",
+              ...ref.encryptedMetadata !== void 0 ? { encryptedMetadata: ref.encryptedMetadata } : {}
+            };
+          })
         );
+      } else {
+        if (typeof this.config.chainAdapter.listReferences !== "function") {
+          throw new DStorageError(
+            CoreErrorCode.LIST_REFS_NOT_SUPPORTED,
+            "[dStorage] listReferences() is not supported by this chain adapter."
+          );
+        }
+        rawItems = await this.config.chainAdapter.listReferences();
       }
-      if (this._encryptionProviders.length === 0) {
+      return Promise.all(
+        rawItems.map(async (item) => {
+          let storageId = null;
+          let decryptionError;
+          const isPublic = !item.encryptionScheme;
+          let dekScheme;
+          if (item.storageId) {
+            if (isPublic) {
+              storageId = item.storageId;
+            } else {
+              try {
+                dekScheme = await this._getDekScheme(item.keyEnvelope);
+                storageId = await dekScheme.decryptStorageId(item.storageId);
+              } catch (err) {
+                decryptionError = err instanceof Error ? err.message : String(err);
+              }
+            }
+          }
+          if (!decryptionError) {
+            if (isPublic) {
+              try {
+                await this._unwrapDek(item.keyEnvelope);
+              } catch (err) {
+                decryptionError = err instanceof Error ? err.message : String(err);
+              }
+            }
+          }
+          let metadata;
+          if (item.encryptedMetadata && dekScheme) {
+            try {
+              const raw = await dekScheme.decryptPayload(
+                base64urlToBytes(item.encryptedMetadata),
+                METADATA_AAD
+              );
+              metadata = JSON.parse(new TextDecoder().decode(raw));
+            } catch {
+            }
+          }
+          return {
+            refId: item.refId,
+            storageId,
+            storageProvider: item.storageProvider,
+            encryptionScheme: item.encryptionScheme ?? null,
+            keyEnvelope: item.keyEnvelope,
+            ownerCommitment: item.ownerCommitment,
+            ...decryptionError !== void 0 ? { decryptionError } : {},
+            ...metadata !== void 0 ? { metadata } : {}
+          };
+        })
+      );
+    } catch (err) {
+      wrapError(err);
+    }
+  }
+  /**
+   * Remove a reference from the on-chain registry.
+   * Only the owner of the reference can successfully call this — the chain
+   * enforces ownership via ZK proof using the witness-derived ownerSecret.
+   */
+  async removeReference(refId) {
+    try {
+      if (!this.config.chainAdapter) {
         throw new DStorageError(
-          CoreErrorCode.UPDATE_UPLOAD_REQUIRES_ENCRYPTION,
-          "[dStorage] retryUpdate requires at least one encryption adapter."
+          CoreErrorCode.REMOVE_REF_REQUIRES_CHAIN,
+          "[dStorage] removeReference() requires a chain adapter."
         );
       }
-      if (!recovery.keyEnvelope) {
+      if (typeof this.config.chainAdapter.removeReference !== "function") {
         throw new DStorageError(
-          CoreErrorCode.UNWRAP_DEK_ENVELOPE_EMPTY,
-          "[dStorage] retryUpdate requires a key envelope in the recovery object."
+          CoreErrorCode.REMOVE_REF_NOT_SUPPORTED,
+          "[dStorage] removeReference() is not supported by this chain adapter."
         );
       }
-      const dek = await this._unwrapDek(recovery.keyEnvelope);
-      try {
-        const scheme = XChaChaScheme.fromKey(dek);
-        const ownerSecret = await this._computeOwnerSecret(refId);
-        const onChainStorageId = await scheme.encryptStorageId(
-          recovery.storageId
-        );
-        const newOwnerSecret = await deriveOwnerSecret(
-          dek,
-          new TextEncoder().encode(recovery.storageId)
-        );
-        await this.config.chainAdapter.updateReference(
-          refId,
-          {
-            storageId: onChainStorageId,
-            encryptionScheme: "xchacha20poly1305-v1",
-            storageProvider: recovery.storageProvider,
-            writtenAt: Date.now(),
-            keyEnvelope: recovery.keyEnvelope,
-            ...recovery.contentHash !== void 0 ? { contentHash: recovery.contentHash } : {}
-          },
-          ownerSecret,
-          newOwnerSecret
+      const ownerSecret = await this._computeOwnerSecret(refId);
+      await this.config.chainAdapter.removeReference(refId, ownerSecret);
+    } catch (err) {
+      wrapError(err);
+    }
+  }
+  /**
+   * Estimate the full cost (storage + chain) for a given payload size before committing.
+   */
+  async estimateCost(sizeBytes) {
+    try {
+      const [storageQuote, chainQuote] = await Promise.all([
+        this.config.storageAdapter.estimateCost(sizeBytes),
+        this.config.chainAdapter?.estimateCost()
+      ]);
+      return {
+        storageCost: { amount: storageQuote.amount, token: storageQuote.token },
+        ...chainQuote ? {
+          chainCost: { amount: chainQuote.amount, token: chainQuote.token }
+        } : {},
+        fileSizeBytes: sizeBytes
+      };
+    } catch (err) {
+      wrapError(err);
+    }
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  /**
+   * Upload large content by splitting into CHUNK_SIZE pieces, encrypting each
+   * independently, and storing a manifest that ties them together.
+   * Only the manifest's storageId is written on-chain.
+   */
+  async _uploadChunked(bytes, tags, onProgress, isPublic = false, rawMeta, refId) {
+    if (this._encryptionProviders.length === 0) {
+      throw new DStorageError(
+        CoreErrorCode.UPLOAD_NO_PROVIDERS,
+        "[dStorage] No encryption providers available. Call init() before uploading."
+      );
+    }
+    const totalChunks = Math.ceil(bytes.length / CHUNK_SIZE);
+    const sdkVersion = package_default.version ?? "unknown";
+    const encryptionScheme = isPublic ? "" : "xchacha20poly1305-v1";
+    this.logger?.log(
+      "dStorage",
+      `Chunked upload: ${bytes.length} bytes \u2192 ${totalChunks} chunks${isPublic ? "" : `, encryption scheme: ${encryptionScheme}`}`
+    );
+    let uploadScheme = null;
+    let keyEnvelope;
+    let chunkDek;
+    let ownerSeed;
+    if (!isPublic) {
+      chunkDek = generateDek();
+      uploadScheme = XChaChaScheme.fromKey(chunkDek);
+      const wrapperEntries = await Promise.all(
+        this._encryptionProviders.map(async (provider) => ({
+          wrapKeyName: provider.name,
+          ...await provider.wrapDek(chunkDek)
+        }))
+      );
+      keyEnvelope = serializeKeyEnvelope(buildKeyEnvelope(wrapperEntries));
+    } else {
+      ownerSeed = generateDek();
+      const ownerSeedWrappers = await Promise.all(
+        this._encryptionProviders.map(async (provider) => ({
+          wrapKeyName: provider.name,
+          ...await provider.wrapDek(ownerSeed)
+        }))
+      );
+      keyEnvelope = serializeKeyEnvelope(buildKeyEnvelope(ownerSeedWrappers));
+    }
+    const chunkEntries = [];
+    let bytesUploaded = 0;
+    for (let i = 0; i < totalChunks; i++) {
+      const start = i * CHUNK_SIZE;
+      const chunk = bytes.subarray(start, start + CHUNK_SIZE);
+      onProgress?.({
+        phase: "encrypting",
+        chunksUploaded: i,
+        totalChunks,
+        bytesUploaded,
+        totalBytes: bytes.length
+      });
+      let chunkData;
+      if (isPublic) {
+        chunkData = chunk;
+      } else {
+        chunkData = await uploadScheme.encryptPayload(
+          chunk,
+          chunkAad(i, totalChunks)
         );
-        return { chainRefId: refId, storageId: recovery.storageId };
-      } finally {
-        dek.fill(0);
       }
-    } catch (err) {
-      wrapError(err);
+      onProgress?.({
+        phase: "uploading",
+        chunksUploaded: i,
+        totalChunks,
+        bytesUploaded,
+        totalBytes: bytes.length
+      });
+      const chunkResult = await this.config.storageAdapter.store(chunkData, {
+        ...tags,
+        [TAG_SDK_VERSION]: sdkVersion,
+        [TAG_CONTENT_TYPE]: TAG_CONTENT_TYPE_OCTET_STREAM,
+        [TAG_CHUNK_INDEX]: String(i),
+        [TAG_CHUNK_TOTAL]: String(totalChunks)
+      });
+      chunkEntries.push({
+        index: i,
+        storageId: chunkResult.id,
+        size: chunk.length
+      });
+      bytesUploaded += chunk.length;
+      onProgress?.({
+        phase: "uploading",
+        chunksUploaded: i + 1,
+        totalChunks,
+        bytesUploaded,
+        totalBytes: bytes.length
+      });
     }
-  }
-  /**
-   * Rotate the encryption adapters protecting an existing reference without
-   * re-uploading the content.
-   *
-   * Useful when you want to:
-   * - Change a password: configure [newPassword, mnemonic] and call rotateKeys().
-   *   The mnemonic unwraps the old DEK, the new envelope is wrapped under both
-   *   new adapters, and the old password wrapper is dropped.
-   * - Add or remove adapters: any single adapter that matches a wrapper in the
-   *   existing key envelope can authorise the rotation. The resulting envelope
-   *   is wrapped under exactly the adapters currently configured on this SDK.
-   *
-   * The content in storage is not touched — only the on-chain key envelope is
-   * updated. writtenAt is preserved to reflect the original upload time.
-   */
-  async rotateKeys(refId) {
-    try {
-      this.assertConnected();
-      if (!this.config.chainAdapter) {
-        throw new DStorageError(
-          CoreErrorCode.ROTATE_KEYS_REQUIRES_CHAIN,
-          "[dStorage] rotateKeys requires a chain adapter."
-        );
-      }
-      if (typeof this.config.chainAdapter.updateReference !== "function") {
-        throw new DStorageError(
-          CoreErrorCode.ROTATE_KEYS_NOT_SUPPORTED,
-          "[dStorage] rotateKeys is not supported by this chain adapter."
-        );
-      }
-      if (this._encryptionProviders.length === 0) {
-        throw new DStorageError(
-          CoreErrorCode.ROTATE_KEYS_REQUIRES_ENCRYPTION,
-          "[dStorage] rotateKeys requires at least one encryption adapter."
-        );
+    onProgress?.({
+      phase: "finalizing",
+      chunksUploaded: totalChunks,
+      totalChunks,
+      bytesUploaded,
+      totalBytes: bytes.length
+    });
+    const manifest = {
+      v: 1,
+      type: "dstorage-chunked-manifest",
+      totalSize: bytes.length,
+      chunkSize: CHUNK_SIZE,
+      chunkCount: totalChunks,
+      provider: this.config.storageAdapter.name,
+      chunks: chunkEntries
+    };
+    const manifestBytes = new TextEncoder().encode(JSON.stringify(manifest));
+    let manifestData;
+    if (isPublic) {
+      manifestData = manifestBytes;
+    } else {
+      manifestData = await uploadScheme.encryptPayload(
+        manifestBytes,
+        MANIFEST_AAD
+      );
+    }
+    const manifestResult = await this.config.storageAdapter.store(
+      manifestData,
+      {
+        [TAG_SDK_VERSION]: sdkVersion,
+        [TAG_CONTENT_TYPE]: isPublic ? TAG_CONTENT_TYPE_JSON : TAG_CONTENT_TYPE_OCTET_STREAM,
+        [TAG_MANIFEST_UPLOAD]: "true"
       }
-      const ref = await this.config.chainAdapter.readReference(refId);
-      const ownerSecret = await this._computeOwnerSecret(refId);
-      const seed = await this._unwrapDek(ref.keyEnvelope);
+    );
+    let onChainManifestId;
+    if (isPublic) {
+      onChainManifestId = manifestResult.id;
+    } else {
+      onChainManifestId = await uploadScheme.encryptStorageId(
+        manifestResult.id
+      );
+    }
+    const ownerSecret = chunkDek ? await deriveOwnerSecret(
+      chunkDek,
+      new TextEncoder().encode(manifestResult.id)
+    ) : await deriveOwnerSecret(
+      ownerSeed,
+      new TextEncoder().encode(manifestResult.id),
+      "dstorage:owner-secret:public:v1"
+    );
+    if (this.config.chainAdapter) {
+      const contentHash = await computeBlake3Hex(manifestData);
+      const storeRecovery = {
+        storageId: manifestResult.id,
+        storageProvider: manifestResult.provider,
+        keyEnvelope: isPublic ? void 0 : keyEnvelope,
+        contentHash
+      };
+      onProgress?.({
+        phase: "stored",
+        chunksUploaded: totalChunks,
+        totalChunks,
+        bytesUploaded: bytes.length,
+        totalBytes: bytes.length,
+        recovery: storeRecovery
+      });
+      const encryptedMetadata = rawMeta && uploadScheme ? bytesToBase64url(
+        await uploadScheme.encryptPayload(
+          new TextEncoder().encode(JSON.stringify(rawMeta)),
+          METADATA_AAD
+        )
+      ) : void 0;
       try {
-        const wrapperEntries = await Promise.all(
-          this._encryptionProviders.map(async (p) => ({
-            wrapKeyName: p.name,
-            ...await p.wrapDek(seed)
-          }))
-        );
-        const newKeyEnvelope = serializeKeyEnvelope(
-          buildKeyEnvelope(wrapperEntries)
-        );
-        await this.config.chainAdapter.updateReference(
-          refId,
-          {
-            storageId: ref.storageId ?? "",
-            encryptionScheme: ref.encryptionScheme ?? "",
-            storageProvider: ref.storageProvider,
-            writtenAt: ref.writtenAt,
-            keyEnvelope: newKeyEnvelope,
-            ...ref.encryptedMetadata !== void 0 ? { encryptedMetadata: ref.encryptedMetadata } : {},
-            ...ref.contentHash !== void 0 ? { contentHash: ref.contentHash } : {}
-          },
-          ownerSecret,
+        const chainResult = await this.config.chainAdapter.writeReference({
+          storageId: onChainManifestId,
+          encryptionScheme,
+          storageProvider: manifestResult.provider,
+          ...refId !== void 0 ? { refId } : {},
+          ...encryptedMetadata !== void 0 ? { encryptedMetadata } : {},
+          writtenAt: Date.now(),
+          keyEnvelope,
+          contentHash,
           ownerSecret
+        });
+        const resultRefId = chainResult.refId;
+        this.logger?.log(
+          "dStorage",
+          `Chunked upload complete \u2192 ${totalChunks} chunks + manifest, refId: ${resultRefId}`
         );
-      } finally {
-        seed.fill(0);
+        return {
+          chainRefId: resultRefId,
+          storageId: manifestResult.id,
+          storageProvider: manifestResult.provider,
+          chainProvider: chainResult.provider,
+          uploadedAt: manifestResult.uploadedAt,
+          encryptionScheme,
+          costEstimate: {
+            storageCost: {
+              amount: manifestResult.cost?.amount ?? "unknown",
+              token: manifestResult.cost?.token ?? "AR"
+            },
+            chainCost: {
+              amount: chainResult.paymentReceipt?.amount ?? "unknown",
+              token: chainResult.paymentReceipt?.token ?? "DUST"
+            },
+            fileSizeBytes: bytes.length
+          }
+        };
+      } catch {
+        throw new StorePartialError(storeRecovery);
       }
-    } catch (err) {
-      wrapError(err);
     }
+    this.logger?.log(
+      "dStorage",
+      `Chunked upload complete (storage-only) \u2192 ${totalChunks} chunks + manifest, storageId: ${manifestResult.id}`
+    );
+    return {
+      storageId: manifestResult.id,
+      storageProvider: manifestResult.provider,
+      uploadedAt: manifestResult.uploadedAt,
+      encryptionScheme,
+      costEstimate: {
+        storageCost: {
+          amount: manifestResult.cost?.amount ?? "unknown",
+          token: manifestResult.cost?.token ?? "AR"
+        },
+        fileSizeBytes: bytes.length
+      }
+    };
   }
   /**
-   * Retrieve and decrypt data by its storageId.
-   * Decryption happens locally — the SDK never sends plaintext anywhere.
-   *
-   * Automatically detects chunked manifests and reassembles the original file.
-   *
-   * @param storageId  The storageId returned from store()
+   * Reassemble a chunked file from its manifest.
+   * Fetches and decrypts each chunk sequentially to bound memory usage.
    */
-  async retrieveByStorageId(storageId, dekScheme, contentHash) {
-    try {
-      this.assertConnected();
-      const { bytes: rawBytes, tags } = await this.config.storageAdapter.retrieve(storageId);
-      if (contentHash) {
-        const computed = await computeBlake3Hex(rawBytes);
-        if (computed !== contentHash) {
+  async _retrieveChunked(manifest, scheme = null, tags = {}) {
+    if (manifest.chunks.length !== manifest.chunkCount) {
+      throw new DStorageError(
+        CoreErrorCode.MANIFEST_CHUNK_COUNT_MISMATCH,
+        `[dStorage] Manifest declares ${manifest.chunkCount} chunks but contains ${manifest.chunks.length} entries`
+      );
+    }
+    const sorted = [...manifest.chunks].sort((a, b) => a.index - b.index);
+    for (let i = 0; i < sorted.length; i++) {
+      if (sorted[i].index !== i) {
+        throw new DStorageError(
+          CoreErrorCode.MANIFEST_NOT_CONTIGUOUS,
+          `[dStorage] Manifest chunk list is not contiguous: expected index ${i}, got ${sorted[i].index}`
+        );
+      }
+    }
+    const result = new Uint8Array(manifest.totalSize);
+    let offset = 0;
+    for (const entry of sorted) {
+      const { bytes: rawChunkBytes } = await this.config.storageAdapter.retrieve(entry.storageId);
+      let chunkBytes = rawChunkBytes;
+      if (scheme) {
+        try {
+          chunkBytes = await scheme.decryptPayload(
+            rawChunkBytes,
+            chunkAad(entry.index, manifest.chunkCount)
+          );
+        } catch (err) {
           throw new DStorageError(
-            CoreErrorCode.CONTENT_HASH_MISMATCH,
-            `[dStorage] Content hash mismatch for storageId ${storageId}. Expected ${contentHash}, got ${computed}. The retrieved bytes do not match the hash committed on-chain \u2014 the storage content may have been tampered with.`
+            CoreErrorCode.DECRYPT_CHUNK_FAILED,
+            `[dStorage] Failed to decrypt chunk ${entry.index}: ${err}`,
+            { cause: err }
           );
         }
       }
-      return this._decryptAndReassemble(rawBytes, storageId, tags, dekScheme);
-    } catch (err) {
-      wrapError(err);
-    }
-  }
-  /**
-   * Unwrap the data DEK from a key envelope and return an XChaChaScheme built from it.
-   * Throws if the KEK is not available or the envelope cannot be parsed.
-   * Only valid for private uploads (envelope.wrappers must be present).
-   */
-  async _getDekScheme(keyEnvelope) {
-    if (this._encryptionProviders.length === 0) {
-      throw new DStorageError(
-        CoreErrorCode.DECRYPT_NO_PROVIDERS,
-        "[dStorage] Cannot decrypt: no encryption providers. Call init() before retrieving private data."
+      if (offset + chunkBytes.length > manifest.totalSize) {
+        throw new DStorageError(
+          CoreErrorCode.CHUNK_OVERFLOWS_TOTAL_SIZE,
+          `[dStorage] Chunk ${entry.index} overflows manifest totalSize`
+        );
+      }
+      result.set(chunkBytes, offset);
+      offset += chunkBytes.length;
+      this.logger?.log(
+        "dStorage",
+        `Retrieved chunk ${entry.index + 1}/${manifest.chunkCount}: ${chunkBytes.length} bytes`
       );
     }
-    if (!keyEnvelope) {
+    if (offset !== manifest.totalSize) {
       throw new DStorageError(
-        CoreErrorCode.DECRYPT_ENVELOPE_EMPTY,
-        "[dStorage] Cannot decrypt: key envelope is empty.",
-        { cause: { code: "envelope_empty" } }
+        CoreErrorCode.REASSEMBLY_SIZE_MISMATCH,
+        `[dStorage] Reassembled ${offset} bytes but manifest declares totalSize ${manifest.totalSize}`
       );
     }
-    const envelope = parseKeyEnvelope(keyEnvelope);
-    if (!envelope) {
+    return {
+      bytes: result,
+      metadata: {},
+      tags
+    };
+  }
+  assertConnected() {
+    if (!this._initialized && this.wallet === null) {
       throw new DStorageError(
-        CoreErrorCode.DECRYPT_ENVELOPE_MALFORMED,
-        "[dStorage] Cannot decrypt: key envelope is malformed or has an invalid structure. The stored reference may be corrupted or tampered with.",
-        { cause: { code: "envelope_malformed" } }
-      );
-    }
-    for (const wrapper of envelope.wrappers) {
-      const provider = this._encryptionProviders.find(
-        (p) => p.name === wrapper.wrapKeyName
+        CoreErrorCode.NOT_INITIALIZED,
+        "[dStorage] Not connected. Call dStorage.init() first."
       );
-      if (!provider) continue;
-      try {
-        const dek = await provider.unwrapDek(wrapper);
-        return XChaChaScheme.fromKey(dek);
-      } catch {
-      }
     }
-    throw new DStorageError(
-      CoreErrorCode.DECRYPT_NO_WRAPPER_MATCHED,
-      "[dStorage] Cannot decrypt: this reference was not encrypted with any of your configured keys. Check that you are using the correct encryption adapter, password, seed phrase, or keypair.",
-      { cause: { code: "no_wrapper_matched" } }
+  }
+};
+
+// ../payment/dist/chunk-IVL4WQ5Y.mjs
+var TOKENS = {
+  AR: { symbol: "AR", name: "Arweave", decimals: 12 },
+  DUST: { symbol: "DUST", name: "Midnight", decimals: 6 },
+  MOCK: {
+    symbol: "MOCK",
+    name: "Mock Token",
+    decimals: 6
+  }
+};
+
+// ../payment/dist/chunk-R6FT3AV4.mjs
+var MockPaymentAdapter = class {
+  constructor(config) {
+    this.network = "mock";
+    this.token = config.token ?? "MOCK";
+    this.type = config.type;
+    this.quoteValidityMs = config.quoteValidityMs ?? 6e5;
+    this.logger = config.logger;
+  }
+  async estimateCost(dataSizeBytes) {
+    const kb = dataSizeBytes / 1024;
+    const amount = Math.max(1e-4, kb * 1e-3).toFixed(6);
+    this.logger?.log(
+      "dStorage/mock-payment",
+      `Estimated cost: ${amount} ${this.token}`
     );
+    return {
+      token: this.token,
+      amount,
+      network: this.network,
+      type: this.type,
+      dataSizeBytes,
+      expiresAt: Date.now() + this.quoteValidityMs
+    };
   }
-  /**
-   * Unwrap the raw DEK bytes from a key envelope using the available KEKs.
-   * The ownerSecret for the reference can be re-derived as HKDF(dek, rawStorageId).
-   * Throws if no wrapper matches any available KEK.
-   */
-  async _unwrapDek(keyEnvelope) {
-    if (this._encryptionProviders.length === 0) {
+  async pay(instruction, onStatus) {
+    const tokenName = TOKENS[this.token]?.name ?? this.token;
+    onStatus?.(`Requesting ${tokenName} wallet signature\u2026`);
+    onStatus?.(`Broadcasting ${this.type} payment transaction\u2026`);
+    onStatus?.("Awaiting confirmation\u2026");
+    const txHash = generateSimulatedTxHash();
+    const { amount } = await this.estimateCost(instruction.dataSizeBytes);
+    this.logger?.log(
+      "dStorage/mock-payment",
+      `Simulated ${this.type} payment \u2192 txHash: ${txHash}`
+    );
+    return {
+      txHash,
+      token: this.token,
+      amount,
+      type: this.type,
+      paidAt: Date.now(),
+      serviceFee: "0"
+    };
+  }
+};
+function generateSimulatedTxHash() {
+  const hex = Array.from(
+    { length: 64 },
+    () => Math.floor(Math.random() * 16).toString(16)
+  ).join("");
+  return `0x${hex}`;
+}
+
+// ../payment/dist/index.mjs
+import { blake3 } from "@noble/hashes/blake3.js";
+var PaymentErrorCode = {
+  // adapters/arweave.ts (14000–14099)
+  ARWEAVE_NOT_INSTALLED: 14001,
+  ARWEAVE_WALLET_KEY_REQUIRED: 14002,
+  ARWEAVE_CONNECT_NOT_FOUND: 14003,
+  ARWEAVE_QUOTE_EXPIRED: 14004,
+  // adapters/managed.ts (14100–14299)
+  MANAGED_NON_OBJECT_RESPONSE: 14100,
+  MANAGED_SERVER_FAILURE: 14101,
+  MANAGED_MISSING_FIELD: 14102,
+  MANAGED_PUBLIC_KEY_MISMATCH: 14103,
+  MANAGED_TOKEN_REQUIRED: 14104,
+  MANAGED_QUOTE_EXPIRED: 14105,
+  MANAGED_UNBALANCED_TX: 14106,
+  MANAGED_SERVER_UNREACHABLE: 14107,
+  MANAGED_KEY_CHANGED: 14108,
+  MANAGED_SIGN_HTTP_ERROR: 14109,
+  MANAGED_NON_JSON_RESPONSE: 14110
+};
+var MAX_ERROR_BODY_LENGTH = 200;
+function sanitiseErrorBody(raw) {
+  return raw.replace(/[\x00-\x1f\x7f]/g, " ").replace(/<[^>]*>/g, "").trim().slice(0, MAX_ERROR_BODY_LENGTH);
+}
+var DEFAULT_QUOTE_VALIDITY_MS = 12e4;
+var CONTENT_HASH_TAG = "X-Content-Hash";
+var ArweavePaymentAdapter = class {
+  constructor(config = {}) {
+    this.network = "arweave";
+    this.token = "AR";
+    this.type = "storage";
+    this.arweaveClient = null;
+    this.pendingUpload = null;
+    this.signedUpload = null;
+    this.gateway = config.gateway ?? {
+      host: "arweave.net",
+      port: 443,
+      protocol: "https"
+    };
+    this.walletKey = config.walletKey;
+    this.quoteValidityMs = config.quoteValidityMs ?? DEFAULT_QUOTE_VALIDITY_MS;
+    this.logger = config.logger;
+  }
+  // ── Protected: lazy Arweave client ───────────────────────────────────────────
+  async getClient() {
+    if (this.arweaveClient) return this.arweaveClient;
+    try {
+      const _m = await import("arweave");
+      const raw = _m.default;
+      const ctor = typeof raw.init === "function" ? raw : raw.default ?? raw;
+      this.arweaveClient = ctor.init(this.gateway ?? {});
+      return this.arweaveClient;
+    } catch {
       throw new DStorageError(
-        CoreErrorCode.UNWRAP_DEK_NO_PROVIDERS,
-        "[dStorage] Cannot unwrap DEK: no encryption providers. Call init() first."
+        PaymentErrorCode.ARWEAVE_NOT_INSTALLED,
+        "[dStorage/arweave-payment] arweave package not installed. Run: npm install arweave"
       );
     }
-    if (!keyEnvelope) {
-      throw new DStorageError(
-        CoreErrorCode.UNWRAP_DEK_ENVELOPE_EMPTY,
-        "[dStorage] Cannot unwrap DEK: key envelope is empty.",
-        { cause: { code: "envelope_empty" } }
-      );
+  }
+  // ── Protected: wallet resolution ─────────────────────────────────────────────
+  resolveWallet() {
+    if (this.walletKey && Object.keys(this.walletKey).length > 0) {
+      return this.walletKey;
     }
-    const envelope = parseKeyEnvelope(keyEnvelope);
-    if (!envelope) {
+    if (typeof window === "undefined") {
       throw new DStorageError(
-        CoreErrorCode.UNWRAP_DEK_ENVELOPE_MALFORMED,
-        "[dStorage] Cannot unwrap DEK: key envelope is malformed or has an invalid structure. The stored reference may be corrupted or tampered with.",
-        { cause: { code: "envelope_malformed" } }
+        PaymentErrorCode.ARWEAVE_WALLET_KEY_REQUIRED,
+        "[dStorage/arweave-payment] Node.js usage requires a walletKey in the config."
       );
     }
-    for (const wrapper of envelope.wrappers) {
-      const provider = this._encryptionProviders.find(
-        (p) => p.name === wrapper.wrapKeyName
+    if (typeof window.arweaveWallet === "undefined") {
+      throw new DStorageError(
+        PaymentErrorCode.ARWEAVE_CONNECT_NOT_FOUND,
+        "[dStorage/arweave-payment] ArConnect extension not found. Install it from https://arconnect.io"
       );
-      if (!provider) continue;
-      try {
-        return await provider.unwrapDek(wrapper);
-      } catch {
-      }
     }
-    throw new DStorageError(
-      CoreErrorCode.UNWRAP_DEK_NO_WRAPPER_MATCHED,
-      "[dStorage] Cannot unwrap DEK: this reference was not encrypted with any of your configured keys. Check that you are using the correct encryption adapter, password, seed phrase, or keypair.",
-      { cause: { code: "no_wrapper_matched" } }
+    return "use_wallet";
+  }
+  // ── PaymentAdapter: provideUploadData ─────────────────────────────────────────
+  /**
+   * Store the encrypted upload payload and metadata tags so that pay() can
+   * build and sign the complete Arweave transaction in one step.
+   * Called by MetaTransaction after the encrypt step, before pay().
+   */
+  provideUploadData(data, metadata = {}) {
+    const hashHex = Array.from(blake3(data)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    this.pendingUpload = {
+      data,
+      metadata: { [CONTENT_HASH_TAG]: hashHex, ...metadata }
+    };
+    this.logger?.log(
+      "dStorage/arweave-payment",
+      `Upload data staged: ${data.byteLength} bytes`
     );
   }
+  // ── PaymentAdapter: estimateCost ─────────────────────────────────────────────
   /**
-   * Compute the ownerSecret for an existing on-chain reference.
-   * Used by removeReference/updateReference to derive the ZK witness secret.
+   * Query the Arweave fee oracle for the real upload cost.
+   */
+  async estimateCost(dataSizeBytes) {
+    const arweave = await this.getClient();
+    const winstons = await arweave.transactions.getPrice(
+      dataSizeBytes
+    );
+    const amount = arweave.ar.winstonToAr(winstons);
+    this.logger?.log(
+      "dStorage/arweave-payment",
+      `Estimated: ${amount} AR (${winstons} Winstons)`
+    );
+    return {
+      token: this.token,
+      amount,
+      network: this.network,
+      type: this.type,
+      dataSizeBytes,
+      expiresAt: Date.now() + this.quoteValidityMs
+    };
+  }
+  // ── PaymentAdapter: pay ───────────────────────────────────────────────────────
+  /**
+   * Sign-then-store flow (when provideUploadData was called):
+   *   Creates the Arweave transaction with data + tags, prompts the wallet
+   *   for approval (ArConnect popup or JWK signing), and stores the signed
+   *   transaction for ArweaveStorageAdapter.store() to post.
    *
-   * Flow:
-   *   1. Read the reference from chain to get keyEnvelope + storageId
-   *   2. Unwrap the DEK from keyEnvelope using available KEKs
-   *   3. Recover raw storageId (decrypt with DEK if private, plaintext if public)
-   *   4. Return HKDF-SHA256(dek, rawStorageId) for private, or HKDF-SHA256(ownerSeed, rawStorageId) for public
+   * Pass-through fallback (when provideUploadData was NOT called):
+   *   Returns a receipt acknowledging that payment is bundled with the upload.
+   *   ArweaveStorageAdapter.store() performs the full create → sign → post flow.
    */
-  async _computeOwnerSecret(refId) {
-    const ref = await this.config.chainAdapter.readReference(refId);
-    const isPublic = !ref.encryptionScheme;
-    if (isPublic) {
-      const ownerSeed = await this._unwrapDek(ref.keyEnvelope);
-      return deriveOwnerSecret(
-        ownerSeed,
-        new TextEncoder().encode(ref.storageId),
-        "dstorage:owner-secret:public:v1"
+  async pay(instruction, onStatus) {
+    if (Date.now() > instruction.expiresAt) {
+      throw new DStorageError(
+        PaymentErrorCode.ARWEAVE_QUOTE_EXPIRED,
+        `[dStorage/payment] Quote expired at ${new Date(instruction.expiresAt).toISOString()}. Request a fresh quote via estimateCost() before calling pay().`
       );
     }
-    const dek = await this._unwrapDek(ref.keyEnvelope);
-    const dekScheme = XChaChaScheme.fromKey(dek);
-    const rawStorageIdBytes = ref.storageId ? new TextEncoder().encode(
-      await dekScheme.decryptStorageId(ref.storageId)
-    ) : METADATA_ONLY_OWNER_SECRET_SALT;
-    return deriveOwnerSecret(dek, rawStorageIdBytes);
-  }
-  // Accepts an optional pre-built CryptoScheme (unwrapped from a key envelope).
-  // If no dekScheme is provided, content is treated as public (no decryption).
-  async _decryptAndReassemble(rawBytes, storageId, tags, dekScheme) {
-    const scheme = dekScheme ?? null;
-    if (scheme) {
-      let manifestBytes = null;
-      try {
-        manifestBytes = await scheme.decryptPayload(rawBytes, MANIFEST_AAD);
-      } catch {
-      }
-      if (manifestBytes !== null) {
-        const parsed = JSON.parse(
-          new TextDecoder().decode(manifestBytes)
-        );
-        if (!isManifest(parsed)) {
-          throw new DStorageError(
-            CoreErrorCode.MANIFEST_INVALID_STRUCTURE,
-            "[dStorage] Payload authenticated as manifest but has invalid structure"
-          );
-        }
-        this.logger?.log(
-          "dStorage",
-          `Manifest detected: reassembling ${parsed.chunkCount} chunks`
-        );
-        return this._retrieveChunked(parsed, scheme, tags);
-      }
-      let decryptedBytes;
-      try {
-        decryptedBytes = await scheme.decryptPayload(rawBytes, PAYLOAD_AAD);
-      } catch (err) {
-        throw new DStorageError(
-          CoreErrorCode.DECRYPT_PAYLOAD_FAILED,
-          `[dStorage] Failed to decrypt payload: ${err}`,
-          { cause: err }
-        );
-      }
-      this.logger?.log(
-        "dStorage",
-        `Retrieved by refId \u2192 storageId: ${storageId}`
-      );
-      return { bytes: decryptedBytes, metadata: {}, tags };
+    if (!this.pendingUpload) {
+      onStatus?.("AR fee will be deducted as part of the upload transaction.");
+      return {
+        txHash: "arweave-bundled-with-upload",
+        token: this.token,
+        amount: "0",
+        type: this.type,
+        paidAt: Date.now(),
+        serviceFee: "0"
+      };
     }
-    try {
-      const parsed = JSON.parse(new TextDecoder().decode(rawBytes));
-      if (isManifest(parsed)) {
-        this.logger?.log(
-          "dStorage",
-          `Manifest detected: reassembling ${parsed.chunkCount} chunks`
-        );
-        return this._retrieveChunked(parsed, null, tags);
-      }
-    } catch {
+    const { data, metadata } = this.pendingUpload;
+    this.pendingUpload = null;
+    const arweave = await this.getClient();
+    const wallet = this.resolveWallet();
+    onStatus?.("Creating Arweave transaction\u2026");
+    const tx = await arweave.createTransaction({ data }, wallet);
+    for (const [key, value] of Object.entries(metadata)) {
+      tx.addTag(key, value);
     }
+    onStatus?.("Requesting AR wallet approval\u2026");
+    await arweave.transactions.sign(tx, wallet);
+    const winstons = await arweave.transactions.getPrice(
+      data.byteLength
+    );
+    const arCost = arweave.ar.winstonToAr(winstons);
+    this.signedUpload = { tx, arCost };
     this.logger?.log(
-      "dStorage",
-      `Retrieved by refId \u2192 storageId: ${storageId}`
+      "dStorage/arweave-payment",
+      `Transaction signed \u2192 txId: ${tx.id}  cost: ~${arCost} AR`
     );
     return {
-      bytes: rawBytes,
-      metadata: {},
-      tags
+      txHash: tx.id,
+      token: this.token,
+      amount: arCost,
+      type: this.type,
+      paidAt: Date.now(),
+      serviceFee: "0"
     };
   }
+  // ── Consumed by ArweaveStorageAdapter ─────────────────────────────────────────
   /**
-   * Retrieve and decrypt data using only its on-chain reference ID.
-   *
-   * Flow:
-   *   1. Look up the reference on-chain by refId to obtain the storage network ID.
-   *   2. Fetch the blob from the storage network.
-   *   3. Decrypt locally if an encryption key is available.
-   *
-   * Requires the chain adapter to implement readReference() (part of the
-   * ChainAdapter interface — shared by MidnightChainAdapter, MockChainAdapter, etc.).
-   *
-   * @param refId  The chainRefId returned from store()
+   * Returns the pre-signed transaction produced by pay(), then clears it.
+   * Called by ArweaveStorageAdapter.store() to post the already-signed tx.
+   * Returns null if pay() did not sign a transaction (pass-through mode).
    */
-  async retrieveByRefId(refId) {
-    try {
-      this.assertConnected();
-      if (!this.config.chainAdapter) {
-        throw new DStorageError(
-          CoreErrorCode.RETRIEVE_BY_REF_ID_REQUIRES_CHAIN,
-          "[dStorage] retrieveByRefId() requires a chain adapter. Configure one in DStorageConfig or use retrieveByStorageId() instead."
-        );
-      }
-      const ref = await this.config.chainAdapter.readReference(refId);
-      if (!ref)
-        throw new DStorageError(
-          CoreErrorCode.REF_NOT_FOUND,
-          `[dStorage] No on-chain reference found for refId: ${refId}`
-        );
-      if (ref.storageProvider && ref.storageProvider !== this.config.storageAdapter.name) {
-        throw new DStorageError(
-          CoreErrorCode.STORAGE_ADAPTER_MISMATCH,
-          `[dStorage] Storage adapter mismatch: reference "${refId}" was stored on "${ref.storageProvider}" but the configured adapter is "${this.config.storageAdapter.name}". Configure a "${ref.storageProvider}" storage adapter to retrieve this reference.`
-        );
-      }
-      const isPublic = !ref.encryptionScheme;
-      let storageId;
-      let dekScheme;
-      if (!ref.storageId) {
-        if (!isPublic && ref.keyEnvelope) {
-          dekScheme = await this._getDekScheme(ref.keyEnvelope);
-        }
-      } else if (isPublic) {
-        storageId = ref.storageId;
-      } else {
-        if (!ref.keyEnvelope) {
-          throw new DStorageError(
-            CoreErrorCode.RETRIEVE_BY_REF_ID_ENVELOPE_EMPTY,
-            `[dStorage] Cannot decrypt refId ${refId}: key envelope is empty.`,
-            { cause: { code: "envelope_empty" } }
-          );
-        }
-        dekScheme = await this._getDekScheme(ref.keyEnvelope);
-        storageId = await dekScheme.decryptStorageId(ref.storageId);
-      }
-      let contentBytes;
-      let contentTags;
-      if (storageId !== void 0) {
-        const r = await this.retrieveByStorageId(
-          storageId,
-          dekScheme,
-          ref.contentHash
-        );
-        contentBytes = r.bytes;
-        contentTags = r.tags;
-      } else {
-        contentBytes = new Uint8Array(0);
-        contentTags = {};
-      }
-      let metadata = {};
-      if (ref.encryptedMetadata && dekScheme) {
-        const raw = await dekScheme.decryptPayload(
-          base64urlToBytes(ref.encryptedMetadata),
-          METADATA_AAD
-        );
-        metadata = JSON.parse(new TextDecoder().decode(raw));
-      }
-      return { bytes: contentBytes, tags: contentTags, metadata };
-    } catch (err) {
-      wrapError(err);
+  consumeSignedUpload() {
+    const signed = this.signedUpload;
+    this.signedUpload = null;
+    return signed;
+  }
+};
+var POST_SIGN_TX_API_PATH = "/api/service/sign-tx";
+function uint8ArrayToHex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function parseSignedTxBytes(signedTx) {
+  if (signedTx.startsWith("midnight:")) {
+    const colonIdx = signedTx.lastIndexOf(":");
+    return hexToBytes(signedTx.slice(colonIdx + 1), "signedTx");
+  }
+  return hexToBytes(signedTx, "signedTx");
+}
+function parseSignTxResponse(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    throw new DStorageError(
+      PaymentErrorCode.MANAGED_NON_OBJECT_RESPONSE,
+      "[dStorage/managed-payment] Signing server returned a non-object response."
+    );
+  }
+  const r = raw;
+  if (r["success"] !== true) {
+    throw new DStorageError(
+      PaymentErrorCode.MANAGED_SERVER_FAILURE,
+      `[dStorage/managed-payment] Signing server reported success:false \u2014 ${sanitiseErrorBody(JSON.stringify(r))}`
+    );
+  }
+  for (const field of [
+    "txId",
+    "signature",
+    "publicKey",
+    "txAmount",
+    "serviceFee"
+  ]) {
+    if (typeof r[field] !== "string") {
+      throw new DStorageError(
+        PaymentErrorCode.MANAGED_MISSING_FIELD,
+        `[dStorage/managed-payment] Signing server response missing or invalid field: ${field}`
+      );
     }
   }
+  return r;
+}
+function assertOwnerKeyMatch(responseKey, pinnedKey) {
+  if (pinnedKey && responseKey !== pinnedKey) {
+    throw new DStorageError(
+      PaymentErrorCode.MANAGED_PUBLIC_KEY_MISMATCH,
+      "[dStorage/managed-payment] Signing server returned a public key that does not match the pinned key from the auth token \u2014 possible server compromise or MITM."
+    );
+  }
+}
+var ManagedPaymentAdapter = class _ManagedPaymentAdapter extends ArweavePaymentAdapter {
   /**
-   * List references currently available from the configured chain adapter.
+   * Strip a RSA-4096 modulus suffix from a compound auth token
+   * (<credential>.<base64url_683_chars>), returning only the credential.
+   * A plain token (no '.' or wrong suffix length) is returned unchanged.
+   * This lets ArweaveBundlerStorageAdapter compound tokens be passed directly
+   * to any adapter that uses ManagedPaymentAdapter without breaking authentication.
+   *
+   * lastIndexOf is intentional: the credential part may itself contain dots
+   * (e.g. a JWT), so we always split at the *last* dot to reach the modulus.
    */
-  async listReferences(options) {
-    try {
-      if (!this.config.chainAdapter) {
-        throw new DStorageError(
-          CoreErrorCode.LIST_REFS_REQUIRES_CHAIN,
-          "[dStorage] listReferences() requires a chain adapter."
-        );
-      }
-      let rawItems;
-      if (options?.refIds && options.refIds.length > 0) {
-        rawItems = await Promise.all(
-          options.refIds.map(async (refId) => {
-            const ref = await this.config.chainAdapter.readReference(refId);
-            return {
-              refId,
-              storageId: ref.storageId ?? null,
-              encryptionScheme: ref.encryptionScheme ?? null,
-              keyEnvelope: ref.keyEnvelope,
-              storageProvider: ref.storageProvider,
-              ownerCommitment: "",
-              ...ref.encryptedMetadata !== void 0 ? { encryptedMetadata: ref.encryptedMetadata } : {}
-            };
-          })
-        );
-      } else {
-        if (typeof this.config.chainAdapter.listReferences !== "function") {
-          throw new DStorageError(
-            CoreErrorCode.LIST_REFS_NOT_SUPPORTED,
-            "[dStorage] listReferences() is not supported by this chain adapter."
-          );
-        }
-        rawItems = await this.config.chainAdapter.listReferences();
+  static _parseAuthToken(token) {
+    const dot = token.lastIndexOf(".");
+    if (dot !== -1) {
+      const suffix = token.slice(dot + 1);
+      if (suffix.length === 683 && /^[A-Za-z0-9_-]+$/.test(suffix)) {
+        return { credential: token.slice(0, dot), ownerPublicKey: suffix };
       }
-      return Promise.all(
-        rawItems.map(async (item) => {
-          let storageId = null;
-          let decryptionError;
-          const isPublic = !item.encryptionScheme;
-          let dekScheme;
-          if (item.storageId) {
-            if (isPublic) {
-              storageId = item.storageId;
-            } else {
-              try {
-                dekScheme = await this._getDekScheme(item.keyEnvelope);
-                storageId = await dekScheme.decryptStorageId(item.storageId);
-              } catch (err) {
-                decryptionError = err instanceof Error ? err.message : String(err);
-              }
-            }
-          }
-          if (!decryptionError) {
-            if (isPublic) {
-              try {
-                await this._unwrapDek(item.keyEnvelope);
-              } catch (err) {
-                decryptionError = err instanceof Error ? err.message : String(err);
-              }
-            }
-          }
-          let metadata;
-          if (item.encryptedMetadata && dekScheme) {
-            try {
-              const raw = await dekScheme.decryptPayload(
-                base64urlToBytes(item.encryptedMetadata),
-                METADATA_AAD
-              );
-              metadata = JSON.parse(new TextDecoder().decode(raw));
-            } catch {
-            }
-          }
-          return {
-            refId: item.refId,
-            storageId,
-            storageProvider: item.storageProvider,
-            encryptionScheme: item.encryptionScheme ?? null,
-            keyEnvelope: item.keyEnvelope,
-            ownerCommitment: item.ownerCommitment,
-            ...decryptionError !== void 0 ? { decryptionError } : {},
-            ...metadata !== void 0 ? { metadata } : {}
-          };
-        })
+    }
+    return { credential: token, ownerPublicKey: void 0 };
+  }
+  constructor(config) {
+    super({
+      ...config.gateway !== void 0 ? { gateway: config.gateway } : {},
+      ...config.quoteValidityMs !== void 0 ? { quoteValidityMs: config.quoteValidityMs } : {},
+      ...config.logger !== void 0 ? { logger: config.logger } : {}
+    });
+    this.signingServerUrl = config.signingServerUrl.replace(/\/$/, "");
+    if (!config.authToken || config.authToken.trim() === "") {
+      throw new DStorageError(
+        PaymentErrorCode.MANAGED_TOKEN_REQUIRED,
+        "[dStorage/managed-payment] authToken is required and must not be empty or whitespace."
       );
-    } catch (err) {
-      wrapError(err);
     }
+    const { credential, ownerPublicKey } = _ManagedPaymentAdapter._parseAuthToken(config.authToken);
+    this.authToken = credential;
+    this.ownerPublicKey = ownerPublicKey;
+    this.requestTimeoutMs = config.requestTimeoutMs ?? 3e4;
+    this.network = config.network;
+    this.type = config.type;
   }
+  // ── PaymentAdapter: estimateCost ─────────────────────────────────────────────
   /**
-   * Remove a reference from the on-chain registry.
-   * Only the owner of the reference can successfully call this — the chain
-   * enforces ownership via ZK proof using the witness-derived ownerSecret.
+   * Query the Arweave fee oracle for the real upload cost.
    */
-  async removeReference(refId) {
-    try {
-      if (!this.config.chainAdapter) {
-        throw new DStorageError(
-          CoreErrorCode.REMOVE_REF_REQUIRES_CHAIN,
-          "[dStorage] removeReference() requires a chain adapter."
-        );
-      }
-      if (typeof this.config.chainAdapter.removeReference !== "function") {
-        throw new DStorageError(
-          CoreErrorCode.REMOVE_REF_NOT_SUPPORTED,
-          "[dStorage] removeReference() is not supported by this chain adapter."
-        );
-      }
-      const ownerSecret = await this._computeOwnerSecret(refId);
-      await this.config.chainAdapter.removeReference(refId, ownerSecret);
-    } catch (err) {
-      wrapError(err);
+  async estimateCost(dataSizeBytes) {
+    if (this.network === "arweave") {
+      return await super.estimateCost(dataSizeBytes);
     }
+    const amount = "0.0012345";
+    this.logger?.log(
+      "dStorage/managed-payment",
+      `Estimated: ${amount} ${this.token}`
+    );
+    return {
+      token: this.token,
+      // FIXME: should be probably obtained from the signing service
+      amount,
+      network: this.network,
+      type: this.type,
+      dataSizeBytes,
+      txData: "---",
+      expiresAt: Date.now() + this.quoteValidityMs
+    };
   }
+  // ── PaymentAdapter: pay ───────────────────────────────────────────────────────
   /**
-   * Estimate the full cost (storage + chain) for a given payload size before committing.
+   * Routes payment to the correct network-specific handler based on quote.network.
+   *
+   * The Arweave path falls back to the base-class pass-through if
+   * provideUploadData() was not called. An unrecognised network throws.
    */
-  async estimateCost(sizeBytes) {
-    try {
-      const [storageQuote, chainQuote] = await Promise.all([
-        this.config.storageAdapter.estimateCost(sizeBytes),
-        this.config.chainAdapter?.estimateCost()
-      ]);
-      return {
-        storageCost: { amount: storageQuote.amount, token: storageQuote.token },
-        ...chainQuote ? {
-          chainCost: { amount: chainQuote.amount, token: chainQuote.token }
-        } : {},
-        fileSizeBytes: sizeBytes
-      };
-    } catch (err) {
-      wrapError(err);
+  async pay(instruction, onStatus) {
+    if (Date.now() > instruction.expiresAt) {
+      throw new DStorageError(
+        PaymentErrorCode.MANAGED_QUOTE_EXPIRED,
+        `[dStorage/payment] Quote expired at ${new Date(instruction.expiresAt).toISOString()}. Request a fresh quote via estimateCost() before calling pay().`
+      );
+    }
+    if (this.network === "managedmock") {
+      return this._payManagedMock(instruction, onStatus);
+    }
+    if (instruction.network === "midnight") {
+      return this._payMidnight(instruction, onStatus);
+    } else if (instruction.network === "arweave") {
+      return this._payArweave(instruction, onStatus);
+    } else if (instruction.network === "arweave_bundler") {
+      return this._payArweaveBundler(instruction, onStatus);
     }
+    throw Error(`Unsupported network: ${instruction.network}`);
   }
+  // ── Network-specific wallet provider factories ────────────────────────────────
   /**
-   * Execute a full meta-transaction for a file:
-   * estimate → encrypt → pay storage → upload → pay chain → write reference
+   * Returns a WalletProvider-compatible object for the Midnight chain whose
+   * `balanceTx()` is fulfilled by the managed signing server instead of a
+   * local wallet. The caller supplies the public keys (from whichever source
+   * they have — HD derivation, a server endpoint, etc.); the SDK only handles
+   * the signing-server round-trip.
    *
-   * Presents the entire flow as a single action with step-by-step progress.
+   * The returned object satisfies the @midnight-ntwrk/midnight-js-types
+   * WalletProvider interface via structural typing — no Midnight package
+   * import is required from the caller's side.
    *
-   * @param file        The File to encrypt and store
-   * @param onProgress  Callback fired on every step state change
-   * @param config      Optional token overrides and metadata
+   * @param coinPublicKey        Midnight coin public key (hex) for the ZK fee circuit.
+   * @param encryptionPublicKey  Midnight encryption public key (hex).
+   * @param onReceipt            Optional callback invoked with the PaymentReceipt
+   *                             after each successful balanceTx call. Used internally
+   *                             by MidnightChainAdapter to capture receipt metadata;
+   *                             external callers can omit it.
    */
-  async executeMetaTransaction(file, onProgress, config = {}) {
-    try {
-      this.assertConnected();
-      if (this._encryptionProviders.length === 0) {
-        throw new DStorageError(
-          CoreErrorCode.META_TX_REQUIRES_ENCRYPTION,
-          "[dStorage] executeMetaTransaction() requires at least one encryption provider."
+  createMidnightWalletProvider(coinPublicKey, encryptionPublicKey, onReceipt) {
+    return {
+      getCoinPublicKey: () => coinPublicKey,
+      getEncryptionPublicKey: () => encryptionPublicKey,
+      balanceTx: async (tx, _ttl) => {
+        const txData = uint8ArrayToHex(tx.serialize());
+        const receipt = await this.pay({
+          network: "midnight",
+          txData,
+          dataSizeBytes: txData.length,
+          expiresAt: Date.now() + 6e4
+        });
+        onReceipt?.(receipt);
+        if (!receipt.signedTx) {
+          throw new DStorageError(
+            PaymentErrorCode.MANAGED_UNBALANCED_TX,
+            "[dStorage/payment] Midnight managed payment server did not return a balanced transaction."
+          );
+        }
+        const { Transaction } = await import("@midnight-ntwrk/midnight-js-protocol/ledger");
+        return Transaction.deserialize(
+          "signature",
+          "proof",
+          "binding",
+          parseSignedTxBytes(receipt.signedTx)
         );
       }
-      const metaTx = new MetaTx(this);
-      metaTx.onProgress(onProgress);
-      return metaTx.execute(file, config);
-    } catch (err) {
-      wrapError(err);
-    }
+    };
   }
+  // ── Network-specific payment handlers ────────────────────────────────────────
   /**
-   * Generate a fresh random DEK, wrap it under the KEK(s), and return the crypto
-   * materials needed by MetaTx to encrypt payload and storageId.
+   * Arweave remote-signing flow:
+   *   1. Creates the Arweave transaction locally (data + tags, no local signing).
+   *   2. Calls prepareChunks() to compute data_root (Merkle root) locally.
+   *   3. Strips the raw data from the transaction before serialising — only the
+   *      data_root and data_size (not the actual bytes) are sent to the server.
+   *   4. POSTs the stripped transaction JSON to the signing server.
+   *   5. Applies the returned id, signature, and owner to the transaction.
+   *   6. Restores the raw data so the chunked uploader can post it directly to
+   *      the Arweave gateway — the server never sees the file content.
    *
-   * For private stores: the DEK is wrapped under every available KEK. The ownerSecret
-   * can later be re-derived as HKDF(dek, rawStorageId) by any KEK holder.
-   * For public stores: a random ownerSeed is generated and wrapped under all KEKs (same pattern).
+   * Falls back to the base-class pass-through if provideUploadData() was not called.
    */
-  async prepareUploadCrypto(isPublic = false) {
-    try {
-      if (this._encryptionProviders.length === 0) {
-        throw new DStorageError(
-          CoreErrorCode.PREPARE_UPLOAD_NO_PROVIDERS,
-          "[dStorage] Cannot prepare upload crypto: no encryption providers. Call init() first."
-        );
-      }
-      if (isPublic) {
-        const ownerSeed = generateDek();
-        const ownerSeedWrappers = await Promise.all(
-          this._encryptionProviders.map(async (provider) => ({
-            wrapKeyName: provider.name,
-            ...await provider.wrapDek(ownerSeed)
-          }))
-        );
-        const keyEnvelope2 = serializeKeyEnvelope(
-          buildKeyEnvelope(ownerSeedWrappers)
-        );
-        return {
-          uploadScheme: null,
-          keyEnvelope: keyEnvelope2,
-          encryptionScheme: "",
-          ownerSeed
-        };
-      }
-      const dek = generateDek();
-      const uploadScheme = XChaChaScheme.fromKey(dek);
-      const wrapperEntries = await Promise.all(
-        this._encryptionProviders.map(async (provider) => ({
-          wrapKeyName: provider.name,
-          ...await provider.wrapDek(dek)
-        }))
-      );
-      const keyEnvelope = serializeKeyEnvelope(
-        buildKeyEnvelope(wrapperEntries)
-      );
-      return {
-        uploadScheme,
-        keyEnvelope,
-        encryptionScheme: "xchacha20poly1305-v1",
-        dek
-      };
-    } catch (err) {
-      wrapError(err);
+  async _payArweave(instruction, onStatus) {
+    if (!this.pendingUpload) {
+      return super.pay(instruction, onStatus);
     }
+    const { data, metadata } = this.pendingUpload;
+    this.pendingUpload = null;
+    const arweave = await this.getClient();
+    onStatus?.("Creating Arweave transaction\u2026");
+    const tx = await arweave.createTransaction({ data });
+    if (this.ownerPublicKey) {
+      tx.owner = this.ownerPublicKey;
+    }
+    for (const [key, value] of Object.entries(metadata)) {
+      tx.addTag(key, value);
+    }
+    await tx.prepareChunks(tx.data);
+    const rawData = tx.data;
+    tx.data = new Uint8Array(0);
+    const body = JSON.stringify({
+      txData: tx.toJSON(),
+      network: instruction.network
+    });
+    const {
+      txId,
+      signature,
+      publicKey,
+      txAmount: arCost,
+      serviceFee
+    } = await this._sendSignTxRequest(body, instruction.network, onStatus);
+    assertOwnerKeyMatch(publicKey, this.ownerPublicKey);
+    onStatus?.("Applying remote signature\u2026");
+    tx.setSignature({ id: txId, signature, owner: publicKey });
+    tx.data = rawData;
+    this.signedUpload = { tx, arCost };
+    this.logger?.log(
+      "dStorage/managed-payment",
+      `Transaction signed remotely (${this.signingServerUrl} API service) \u2192 txId: ${txId}  cost: ~${arCost} ${this.token} (service fee: ${serviceFee})`
+    );
+    return {
+      txHash: txId,
+      token: this.token,
+      amount: arCost,
+      type: this.type,
+      paidAt: Date.now(),
+      serviceFee
+    };
   }
-  // ── Private helpers ────────────────────────────────────────────────────────
   /**
-   * Upload large content by splitting into CHUNK_SIZE pieces, encrypting each
-   * independently, and storing a manifest that ties them together.
-   * Only the manifest's storageId is written on-chain.
+   * Midnight payment flow:
+   *   POSTs the fee amount to the dStorage API service, which holds a funded
+   *   Midnight account and submits the chain transaction on behalf of the user.
+   *
+   *   POST {baseUrl}{POST_SIGN_TX_API_PATH}
+   *        → { txData: string (hex-serialized UnboundTransaction), network: string, userId: string }
+   *        ← { txId: string, signature: string (hex-serialized FinalizedTransaction), ... }
+   *
+   * The hex-serialized FinalizedTransaction is returned in PaymentReceipt.signedTx
+   * for the chain adapter to deserialize and pass to submitTx().
    */
-  async _uploadChunked(bytes, tags, onProgress, isPublic = false, rawMeta, refId) {
-    if (this._encryptionProviders.length === 0) {
-      throw new DStorageError(
-        CoreErrorCode.UPLOAD_NO_PROVIDERS,
-        "[dStorage] No encryption providers available. Call init() before uploading."
-      );
-    }
-    const totalChunks = Math.ceil(bytes.length / CHUNK_SIZE);
-    const sdkVersion = package_default.version ?? "unknown";
-    const encryptionScheme = isPublic ? "" : "xchacha20poly1305-v1";
+  async _payMidnight(instruction, onStatus) {
+    const body = JSON.stringify({
+      txData: instruction.txData ?? null,
+      network: instruction.network
+    });
+    const {
+      txId,
+      signature,
+      txAmount: dustCost,
+      serviceFee
+    } = await this._sendSignTxRequest(body, instruction.network, onStatus);
     this.logger?.log(
-      "dStorage",
-      `Chunked upload: ${bytes.length} bytes \u2192 ${totalChunks} chunks${isPublic ? "" : `, encryption scheme: ${encryptionScheme}`}`
+      "dStorage/managed-payment",
+      `Midnight Tx signed remotely (${this.signingServerUrl} API service) \u2192 txId: ${txId}  cost: ~${dustCost} ${this.token} (service fee: ${serviceFee})`
     );
-    let uploadScheme = null;
-    let keyEnvelope;
-    let chunkDek;
-    let ownerSeed;
-    if (!isPublic) {
-      chunkDek = generateDek();
-      uploadScheme = XChaChaScheme.fromKey(chunkDek);
-      const wrapperEntries = await Promise.all(
-        this._encryptionProviders.map(async (provider) => ({
-          wrapKeyName: provider.name,
-          ...await provider.wrapDek(chunkDek)
-        }))
-      );
-      keyEnvelope = serializeKeyEnvelope(buildKeyEnvelope(wrapperEntries));
-    } else {
-      ownerSeed = generateDek();
-      const ownerSeedWrappers = await Promise.all(
-        this._encryptionProviders.map(async (provider) => ({
-          wrapKeyName: provider.name,
-          ...await provider.wrapDek(ownerSeed)
-        }))
-      );
-      keyEnvelope = serializeKeyEnvelope(buildKeyEnvelope(ownerSeedWrappers));
-    }
-    const chunkEntries = [];
-    let bytesUploaded = 0;
-    for (let i = 0; i < totalChunks; i++) {
-      const start = i * CHUNK_SIZE;
-      const chunk = bytes.subarray(start, start + CHUNK_SIZE);
-      onProgress?.({
-        phase: "encrypting",
-        chunksUploaded: i,
-        totalChunks,
-        bytesUploaded,
-        totalBytes: bytes.length
-      });
-      let chunkData;
-      if (isPublic) {
-        chunkData = chunk;
-      } else {
-        chunkData = await uploadScheme.encryptPayload(
-          chunk,
-          chunkAad(i, totalChunks)
-        );
-      }
-      onProgress?.({
-        phase: "uploading",
-        chunksUploaded: i,
-        totalChunks,
-        bytesUploaded,
-        totalBytes: bytes.length
-      });
-      const chunkResult = await this.config.storageAdapter.store(chunkData, {
-        ...tags,
-        [TAG_SDK_VERSION]: sdkVersion,
-        [TAG_CONTENT_TYPE]: TAG_CONTENT_TYPE_OCTET_STREAM,
-        [TAG_CHUNK_INDEX]: String(i),
-        [TAG_CHUNK_TOTAL]: String(totalChunks)
-      });
-      chunkEntries.push({
-        index: i,
-        storageId: chunkResult.id,
-        size: chunk.length
-      });
-      bytesUploaded += chunk.length;
-      onProgress?.({
-        phase: "uploading",
-        chunksUploaded: i + 1,
-        totalChunks,
-        bytesUploaded,
-        totalBytes: bytes.length
-      });
-    }
-    onProgress?.({
-      phase: "finalizing",
-      chunksUploaded: totalChunks,
-      totalChunks,
-      bytesUploaded,
-      totalBytes: bytes.length
-    });
-    const manifest = {
-      v: 1,
-      type: "dstorage-chunked-manifest",
-      totalSize: bytes.length,
-      chunkSize: CHUNK_SIZE,
-      chunkCount: totalChunks,
-      provider: this.config.storageAdapter.name,
-      chunks: chunkEntries
-    };
-    const manifestBytes = new TextEncoder().encode(JSON.stringify(manifest));
-    let manifestData;
-    if (isPublic) {
-      manifestData = manifestBytes;
-    } else {
-      manifestData = await uploadScheme.encryptPayload(
-        manifestBytes,
-        MANIFEST_AAD
-      );
-    }
-    const manifestResult = await this.config.storageAdapter.store(
-      manifestData,
-      {
-        [TAG_SDK_VERSION]: sdkVersion,
-        [TAG_CONTENT_TYPE]: isPublic ? TAG_CONTENT_TYPE_JSON : TAG_CONTENT_TYPE_OCTET_STREAM,
-        [TAG_MANIFEST_UPLOAD]: "true"
-      }
+    return {
+      txHash: txId,
+      token: "DUST",
+      amount: dustCost,
+      type: this.type,
+      signedTx: signature,
+      paidAt: Date.now(),
+      serviceFee
+    };
+  }
+  /**
+   * Arweave Bundler
+   */
+  async _payArweaveBundler(instruction, onStatus) {
+    const body = JSON.stringify({
+      txData: instruction.txData ?? null,
+      network: instruction.network,
+      ...instruction.ownerKey !== void 0 ? { ownerKey: instruction.ownerKey } : {}
+    });
+    const {
+      txId,
+      signature,
+      txAmount: arCost,
+      serviceFee
+    } = await this._sendSignTxRequest(body, instruction.network, onStatus);
+    this.logger?.log(
+      "dStorage/managed-payment",
+      `Arweave bundler Tx signed remotely (${this.signingServerUrl} API service) \u2192 txId: ${txId}  cost: ~${arCost} ${this.token} (service fee: ${serviceFee})`
     );
-    let onChainManifestId;
-    if (isPublic) {
-      onChainManifestId = manifestResult.id;
-    } else {
-      onChainManifestId = await uploadScheme.encryptStorageId(
-        manifestResult.id
-      );
-    }
-    const ownerSecret = chunkDek ? await deriveOwnerSecret(
-      chunkDek,
-      new TextEncoder().encode(manifestResult.id)
-    ) : await deriveOwnerSecret(
-      ownerSeed,
-      new TextEncoder().encode(manifestResult.id),
-      "dstorage:owner-secret:public:v1"
+    return {
+      txHash: txId,
+      token: "AR",
+      amount: arCost,
+      type: this.type,
+      signedTx: signature,
+      paidAt: Date.now(),
+      serviceFee
+    };
+  }
+  /**
+   * Managed mock flow:
+   *   Sends a minimal request to the signing server with the literal network
+   *   identifier "TEST" — the server treats this as a sandbox/test flow with no
+   *   real funds involved. The SDK-side network name is "managedmock" to follow
+   *   the lowercase naming convention; the server-side string is always "TEST".
+   */
+  async _payManagedMock(instruction, onStatus) {
+    const body = JSON.stringify({
+      txData: instruction.txData || "mock",
+      network: "TEST"
+    });
+    const { txId, txAmount, serviceFee } = await this._sendSignTxRequest(
+      body,
+      "TEST",
+      onStatus
     );
-    if (this.config.chainAdapter) {
-      const contentHash = await computeBlake3Hex(manifestData);
-      const storeRecovery = {
-        storageId: manifestResult.id,
-        storageProvider: manifestResult.provider,
-        keyEnvelope: isPublic ? void 0 : keyEnvelope,
-        contentHash
-      };
-      onProgress?.({
-        phase: "stored",
-        chunksUploaded: totalChunks,
-        totalChunks,
-        bytesUploaded: bytes.length,
-        totalBytes: bytes.length,
-        recovery: storeRecovery
-      });
-      const encryptedMetadata = rawMeta && uploadScheme ? bytesToBase64url(
-        await uploadScheme.encryptPayload(
-          new TextEncoder().encode(JSON.stringify(rawMeta)),
-          METADATA_AAD
-        )
-      ) : void 0;
-      try {
-        const chainResult = await this.config.chainAdapter.writeReference({
-          storageId: onChainManifestId,
-          encryptionScheme,
-          storageProvider: manifestResult.provider,
-          ...refId !== void 0 ? { refId } : {},
-          ...encryptedMetadata !== void 0 ? { encryptedMetadata } : {},
-          writtenAt: Date.now(),
-          keyEnvelope,
-          contentHash,
-          ownerSecret
-        });
-        const resultRefId = chainResult.refId;
-        this.logger?.log(
-          "dStorage",
-          `Chunked upload complete \u2192 ${totalChunks} chunks + manifest, refId: ${resultRefId}`
-        );
-        return {
-          chainRefId: resultRefId,
-          storageId: manifestResult.id,
-          storageProvider: manifestResult.provider,
-          chainProvider: chainResult.provider,
-          uploadedAt: manifestResult.uploadedAt,
-          encryptionScheme,
-          costEstimate: {
-            storageCost: {
-              amount: manifestResult.cost?.amount ?? "unknown",
-              token: manifestResult.cost?.token ?? "AR"
-            },
-            chainCost: {
-              amount: chainResult.paymentReceipt?.amount ?? "unknown",
-              token: chainResult.paymentReceipt?.token ?? "DUST"
-            },
-            fileSizeBytes: bytes.length
-          }
-        };
-      } catch {
-        throw new StorePartialError(storeRecovery);
-      }
-    }
     this.logger?.log(
-      "dStorage",
-      `Chunked upload complete (storage-only) \u2192 ${totalChunks} chunks + manifest, storageId: ${manifestResult.id}`
+      "dStorage/managed-payment",
+      `ManagedMock Tx signed remotely (${this.signingServerUrl}) \u2192 txId: ${txId}  cost: ~${txAmount} MOCK (service fee: ${serviceFee})`
     );
     return {
-      storageId: manifestResult.id,
-      storageProvider: manifestResult.provider,
-      uploadedAt: manifestResult.uploadedAt,
-      encryptionScheme,
-      costEstimate: {
-        storageCost: {
-          amount: manifestResult.cost?.amount ?? "unknown",
-          token: manifestResult.cost?.token ?? "AR"
-        },
-        fileSizeBytes: bytes.length
-      }
+      txHash: txId,
+      token: "MOCK",
+      amount: txAmount,
+      type: this.type,
+      paidAt: Date.now(),
+      serviceFee
     };
   }
   /**
-   * Reassemble a chunked file from its manifest.
-   * Fetches and decrypts each chunk sequentially to bound memory usage.
+   * Shared HTTP helper: POSTs a transaction payload to the signing server and
+   * returns the parsed SignTxResponse.
+   *
+   * - Arweave: txJson is the Arweave tx JSON object (from tx.toJSON()); the server
+   *   signs it and returns the signature + owner in the response fields.
+   * - Midnight: txJson is the hex-serialized UnboundTransaction; the server balances
+   *   and signs it, returning the hex-serialized FinalizedTransaction in the
+   *   `signature` response field.
+   *
+   * Throws on network errors or non-2xx HTTP responses.
    */
-  async _retrieveChunked(manifest, scheme = null, tags = {}) {
-    if (manifest.chunks.length !== manifest.chunkCount) {
+  async _sendSignTxRequest(body, network, onStatus) {
+    onStatus?.(`Sending ${network} transaction to signing server\u2026`);
+    let signResp;
+    try {
+      this.logger?.log(
+        "dStorage/managed-payment",
+        `${network}: delegating to managed payment service (serialized req length=${body.length})`
+      );
+      const signal = this.requestTimeoutMs > 0 ? AbortSignal.timeout(this.requestTimeoutMs) : void 0;
+      signResp = await fetch(
+        `${this.signingServerUrl}${POST_SIGN_TX_API_PATH}`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.authToken}`
+          },
+          body,
+          ...signal !== void 0 ? { signal } : {}
+        }
+      );
+    } catch (err) {
       throw new DStorageError(
-        CoreErrorCode.MANIFEST_CHUNK_COUNT_MISMATCH,
-        `[dStorage] Manifest declares ${manifest.chunkCount} chunks but contains ${manifest.chunks.length} entries`
+        PaymentErrorCode.MANAGED_SERVER_UNREACHABLE,
+        `[dStorage/managed-payment] Could not reach signing server: ${err}`,
+        { cause: err }
       );
     }
-    const sorted = [...manifest.chunks].sort((a, b) => a.index - b.index);
-    for (let i = 0; i < sorted.length; i++) {
-      if (sorted[i].index !== i) {
-        throw new DStorageError(
-          CoreErrorCode.MANIFEST_NOT_CONTIGUOUS,
-          `[dStorage] Manifest chunk list is not contiguous: expected index ${i}, got ${sorted[i].index}`
-        );
-      }
-    }
-    const result = new Uint8Array(manifest.totalSize);
-    let offset = 0;
-    for (const entry of sorted) {
-      const { bytes: rawChunkBytes } = await this.config.storageAdapter.retrieve(entry.storageId);
-      let chunkBytes = rawChunkBytes;
-      if (scheme) {
-        try {
-          chunkBytes = await scheme.decryptPayload(
-            rawChunkBytes,
-            chunkAad(entry.index, manifest.chunkCount)
-          );
-        } catch (err) {
-          throw new DStorageError(
-            CoreErrorCode.DECRYPT_CHUNK_FAILED,
-            `[dStorage] Failed to decrypt chunk ${entry.index}: ${err}`,
-            { cause: err }
-          );
-        }
-      }
-      if (offset + chunkBytes.length > manifest.totalSize) {
-        throw new DStorageError(
-          CoreErrorCode.CHUNK_OVERFLOWS_TOTAL_SIZE,
-          `[dStorage] Chunk ${entry.index} overflows manifest totalSize`
-        );
-      }
-      result.set(chunkBytes, offset);
-      offset += chunkBytes.length;
-      this.logger?.log(
-        "dStorage",
-        `Retrieved chunk ${entry.index + 1}/${manifest.chunkCount}: ${chunkBytes.length} bytes`
+    if (signResp.status === 409) {
+      throw new DStorageError(
+        PaymentErrorCode.MANAGED_KEY_CHANGED,
+        "[dStorage/managed-payment] Signing server key has changed \u2014 re-issue your API token to obtain the updated public key."
       );
     }
-    if (offset !== manifest.totalSize) {
+    if (!signResp.ok) {
+      const rawBody = await signResp.text().catch(() => "");
+      const body2 = sanitiseErrorBody(rawBody);
       throw new DStorageError(
-        CoreErrorCode.REASSEMBLY_SIZE_MISMATCH,
-        `[dStorage] Reassembled ${offset} bytes but manifest declares totalSize ${manifest.totalSize}`
+        PaymentErrorCode.MANAGED_SIGN_HTTP_ERROR,
+        `[dStorage/managed-payment] POST ${POST_SIGN_TX_API_PATH} failed: HTTP ${signResp.status}${body2 ? ` \u2014 ${body2}` : ""}`
       );
     }
-    return {
-      bytes: result,
-      metadata: {},
-      tags
-    };
-  }
-  assertConnected() {
-    if (!this._initialized && this.wallet === null) {
+    let parsed;
+    try {
+      parsed = await signResp.json();
+    } catch {
       throw new DStorageError(
-        CoreErrorCode.NOT_INITIALIZED,
-        "[dStorage] Not connected. Call dStorage.init() first."
+        PaymentErrorCode.MANAGED_NON_JSON_RESPONSE,
+        `[dStorage/managed-payment] Managed payment service returned a non-JSON response \u2014 check that the service URL is correct and reachable: ${this.signingServerUrl}${POST_SIGN_TX_API_PATH}`
       );
     }
+    return parseSignTxResponse(parsed);
   }
 };
 
@@ -5127,7 +4772,6 @@ export {
   METADATA_AAD,
   METADATA_ONLY_OWNER_SECRET_SALT,
   ManagedPaymentAdapter,
-  MetaTx,
   MidnightChainAdapter,
   MidnightSimulatorChainAdapter,
   MnemonicEncryptionAdapter,
@@ -5150,7 +4794,6 @@ export {
   computeBlake3Hex,
   decryptStorageIdXChaCha,
   decryptXChaCha,
-  defaultChainToken,
   deriveKek,
   deriveOwnerSecret,
   deriveSymmetricKeyFromSeed,