@opendatalabs/vana-sdk 3.11.0 → 3.12.0

package/README.md

@@ -108,6 +108,42 @@ const result = await storage.upload(myBlob, "report.json");
 console.log(result.url);
 ```
 
+### Scope Vana storage to a protocol network
+
+`VanaStorage` has two independent axes. `endpoint` is the **product host**
+(e.g. `https://storage.vana.org` for production, `https://storage-dev.vana.org`
+for internal staging). `network` is the **protocol network** (`mainnet` or
+`moksha`) that scopes the blob path. They are not synonyms — `storage-dev` is a
+staging host, not a stand-in for Moksha.
+
+```typescript
+import { createVanaStorageProvider } from "@opendatalabs/vana-sdk/node";
+
+const storage = createVanaStorageProvider({
+  endpoint: "https://storage.vana.org", // product host
+  network: "moksha", // protocol namespace within that host
+  signer: {
+    address: account.address,
+    signMessage: (msg) => account.signMessage({ message: msg }),
+  },
+});
+
+// Uploads to /v1/networks/moksha/blobs/{owner}/{scope}/{collectedAt}
+const result = await storage.upload(
+  myBlob,
+  "instagram.profile/2026-05-08T20:00:00.000Z",
+);
+```
+
+When `network` is omitted, `VanaStorage` uses the legacy `/v1/blobs/...` routes,
+preserving backward compatibility. The Web3Signed audience is always the
+endpoint origin, never the network.
+
+A network-configured provider still accepts legacy same-endpoint
+`/v1/blobs/...` URLs so it can read or delete objects written before the opt-in,
+but it rejects URLs scoped to a _different_ explicit network — a Moksha provider
+won't act on a `mainnet`-scoped URL, and vice versa.
+
 ## Build a Vana app
 
 Request user-approved data, read it from the user's Personal Server, and pay
@@ -262,7 +298,7 @@ in October 2025; the report is in [`audits/`](https://github.com/vana-com/vana-s
 
 - [Documentation](https://docs.vana.org/docs/sdk)
 - [API reference](https://vana-com.github.io/vana-sdk)
-- [Discord](https://discord.gg/vanabuilders)
+- [Discord](https://discord.gg/vanaofficial)
 
 ## License
 

package/dist/index.browser.js

@@ -29028,12 +29028,14 @@ async function buildWeb3SignedHeader(params) {
 
 // src/storage/providers/vana-storage.ts
 var DEFAULT_ENDPOINT = "https://storage.vana.org";
-var BLOB_PATH_PREFIX = "/v1/blobs";
+var LEGACY_BLOB_PATH_PREFIX = "/v1/blobs";
 var DEFAULT_TOKEN_TTL_SECONDS = 300;
 var MAX_UPLOAD_ATTEMPTS = 4;
 var MAX_RATE_LIMIT_DELAY_MS = 3e4;
 var VanaStorage = class {
   endpoint;
+  network;
+  blobPathPrefix;
   signer;
   ownerAddress;
   fetchImpl;
@@ -29046,6 +29048,15 @@ var VanaStorage = class {
       );
     }
     this.endpoint = (config.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "");
+    if (config.network !== void 0 && !isProtocolNetwork(config.network)) {
+      throw new StorageError(
+        `Unsupported vana-storage network '${String(config.network)}'`,
+        "INVALID_NETWORK",
+        "vana-storage"
+      );
+    }
+    this.network = config.network;
+    this.blobPathPrefix = this.network ? `/v1/networks/${this.network}/blobs` : LEGACY_BLOB_PATH_PREFIX;
     this.signer = config.signer;
     this.ownerAddress = (config.ownerAddress ?? config.signer.address).toLowerCase();
     this.fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);
@@ -29066,7 +29077,7 @@ var VanaStorage = class {
       );
     }
     const subpath = encodeRelativePath(filename);
-    const path = `${BLOB_PATH_PREFIX}/${this.ownerAddress}/${subpath}`;
+    const path = `${this.blobPathPrefix}/${this.ownerAddress}/${subpath}`;
     const body = new Uint8Array(await file.arrayBuffer());
     const contentType = file.type !== "" ? file.type : "application/octet-stream";
     const header = await this.signRequest("PUT", path, body);
@@ -29234,12 +29245,18 @@ var VanaStorage = class {
         "vana-storage"
       );
     }
-    const segments = parsed.pathname.split("/").filter((s) => s.length > 0);
-    const isTraversal = (s) => s === "." || s === "..";
-    const valid = segments.length === 5 && segments[0] === "v1" && segments[1] === "blobs" && segments[2]?.toLowerCase() === this.ownerAddress && segments[3] !== void 0 && !isTraversal(segments[3]) && segments[4] !== void 0 && !isTraversal(segments[4]);
-    if (!valid) {
+    const route = parseBlobPath(parsed.pathname);
+    if (!route || route.owner.toLowerCase() !== this.ownerAddress) {
       throw new StorageError(
-        `URL path '${parsed.pathname}' must be /v1/blobs/${this.ownerAddress}/{scope}/{collectedAt}`,
+        `URL path '${parsed.pathname}' must be ${this.blobPathPrefix}/${this.ownerAddress}/{scope}/{collectedAt}`,
+        "INVALID_URL",
+        "vana-storage"
+      );
+    }
+    const crossNetwork = this.network ? route.network !== void 0 && route.network !== this.network : route.network !== void 0;
+    if (crossNetwork) {
+      throw new StorageError(
+        `URL network '${route.network ?? "legacy"}' does not match provider network '${this.network ?? "legacy"}'`,
         "INVALID_URL",
         "vana-storage"
       );
@@ -29247,6 +29264,26 @@ var VanaStorage = class {
     return parsed.pathname;
   }
 };
+var PROTOCOL_NETWORKS = ["mainnet", "moksha"];
+function isProtocolNetwork(value) {
+  return typeof value === "string" && PROTOCOL_NETWORKS.includes(value);
+}
+function parseBlobPath(pathname) {
+  const segments = pathname.split("/").filter((s) => s.length > 0);
+  const isTraversal = (s) => s === "." || s === "..";
+  if (segments.length === 5 && segments[0] === "v1" && segments[1] === "blobs") {
+    const [, , owner, scope, collectedAt] = segments;
+    if (isTraversal(scope) || isTraversal(collectedAt)) return null;
+    return { owner, scope, collectedAt };
+  }
+  if (segments.length === 7 && segments[0] === "v1" && segments[1] === "networks" && segments[3] === "blobs") {
+    const [, , network, , owner, scope, collectedAt] = segments;
+    if (!isProtocolNetwork(network)) return null;
+    if (isTraversal(scope) || isTraversal(collectedAt)) return null;
+    return { network, owner, scope, collectedAt };
+  }
+  return null;
+}
 function encodeRelativePath(filename) {
   const parts = filename.split("/");
   if (parts.length !== 2 || parts.some((p) => p.length === 0 || p === "." || p === "..")) {