Merge remote-tracking branch 'origin/main' into ft/accounts_generation

Author: ftheirs

README.md

@@ -29,10 +29,14 @@ Network URLs/IDs are intentionally **hardcoded** in `src/networks.ts` and are co
 - **Local**: MSP `http://127.0.0.1:8080`, RPC `http://127.0.0.1:9888`
 
 Local notes:
-- `NETWORK=local` expects:
+- `NETWORK=local` matches the “normal” local StorageHub defaults when you boot a local network from the StorageHub repo with:
+  - `pnpm docker:start:solochain-evm:initialised`
+  - See StorageHub docs: [Spawning solochain-evm-initialised fullnet](https://github.com/Moonsong-Labs/storage-hub/tree/main/test#spawning-solochain-evm-initialised-fullnet)
+- It assumes:
   - MSP at `http://127.0.0.1:8080`
   - EVM/Substrate RPC at `http://127.0.0.1:9888` / `ws://127.0.0.1:9888`
-  - SIWE domain/uri: `localhost:3001` / `http://localhost:3001`
+- **SIWE domain/uri**: these should be provided by the dApp doing SIWE (they are not “network” properties). For local testing, a dApp often runs on `localhost:3000` or `localhost:3001`.
+  - `localhost:3001` / `http://localhost:3001` is what the StorageHub repo’s `demo-app` (SDK examples) commonly uses.
 
 ## Commands
 
@@ -42,6 +46,17 @@ Local notes:
 - `pnpm lint:fix` — apply safe lint fixes
 - `pnpm test` — build -> artillery
 - `pnpm test:msp-unauth` — standalone unauth MSP load test (no SIWE, no keys)
+- `pnpm test:download` — file download load test (requires SIWE auth + FILE_KEY)
+
+Examples (local):
+
+```bash
+NETWORK=local pnpm test:msp-unauth
+```
+
+```bash
+NETWORK=local STORAGEHUB_PRIVATE_KEY=0x... pnpm test
+```
 
 Examples (local):
 
@@ -97,6 +112,47 @@ Metrics emitted (counters + histograms):
 - `msp.info.ok`, `msp.info.ms`
 - `msp.req.err` (total request errors)
 
+## Download load test
+
+This test authenticates via SIWE and downloads a file from the MSP, measuring throughput and latency.
+
+Required env vars:
+- `NETWORK` (`testnet` or `stagenet`)
+- `FILE_KEY` (the file key/hash to download)
+
+Run:
+
+```bash
+NETWORK=stagenet FILE_KEY=<your-file-key> pnpm test:download
+```
+
+Knobs (optional):
+- `ARTILLERY_WORKERS=4` (parallel local processes)
+- `LOG_LEVEL=info` (see Logging section)
+
+Metrics emitted:
+- `download.siwe.ok`, `download.siwe.ms` (SIWE auth)
+- `download.file.ok`, `download.file.ms` (file download)
+- `download.bytes` (total bytes downloaded per request)
+- `download.siwe.err`, `download.file.err` (error counters)
+
+## Per-VU private keys (Artillery payload)
+
+This test expects a per-VU `privateKey` variable from `config.payload` in `scenarios/artillery.yml`.
+
+1) Create `data/private_keys.csv` (ignored by git), based on the example:
+- `data/private_keys.example.csv`
+
+Notes:
+- `pnpm preflight` will use `STORAGEHUB_PRIVATE_KEY` **if set**, otherwise it will use the **first key** in `data/private_keys.csv`.
+- If Artillery does not inject `privateKey` into `context.vars` (depends on engine/runtime), the scenario will fall back to reading keys directly from `data/private_keys.csv` (round-robin).
+
+2) Run:
+
+```bash
+NETWORK=stagenet LOG_LEVEL=info pnpm test
+```
+
 ## Scenario output
 
 Counters:

package.json

@@ -16,7 +16,8 @@
     "test:siwe:byIndex": "pnpm build && pnpm exec artillery run scenarios/siwe.byIndex.yml",
     "test:siwe:sequential": "pnpm build && pnpm exec artillery run scenarios/siwe.sequential.yml",
     "test:siwe:random": "pnpm build && pnpm exec artillery run scenarios/siwe.random.yml",
-    "test:siwe:auth:sequential": "pnpm build && pnpm exec artillery run scenarios/siwe.auth.sequential.yml"
+    "test:siwe:auth:sequential": "pnpm build && pnpm exec artillery run scenarios/siwe.auth.sequential.yml",
+    "test:download": "pnpm build && pnpm exec tsx scripts/run-artillery-parallel.ts scenarios/artillery.download.yml"
   },
   "dependencies": {
     "@storagehub-sdk/core": "0.4.0",

scenarios/artillery.download.yml

@@ -0,0 +1,28 @@
+config:
+  target: "http://localhost"
+  processor: "../dist/src/processors/download.js"
+
+  phases:
+    - name: warmup
+      duration: 10
+      arrivalRate: 1
+
+    - name: ramp
+      duration: 20
+      arrivalRate: 1
+      rampTo: 10
+
+    - name: steady
+      duration: 40
+      arrivalRate: 10
+
+    - name: cooldown
+      duration: 10
+      arrivalRate: 2
+      rampTo: 1
+
+scenarios:
+  - name: download_file
+    flow:
+      - function: downloadFile
+

src/processors/download.ts

@@ -0,0 +1,85 @@
+import { Readable } from "node:stream";
+import { readEnv } from "../config.js";
+import { getLogger } from "../log.js";
+import { authenticateWithSiwe, connectMsp } from "../sdk/msp.js";
+import { initWalletFromPrivateKey, to0xPrivateKey } from "../sdk/wallet.js";
+import { NETWORKS } from "../networks.js";
+import { nextPrivateKey } from "../privateKeys.js";
+
+type ArtilleryEvents = Readonly<{
+  emit: (type: string, name: string, value: number) => void;
+}>;
+
+type ArtilleryContext = Readonly<{
+  vars?: Record<string, unknown>;
+}>;
+
+function getFileKey(): string {
+  const key = process.env.FILE_KEY;
+  if (!key) {
+    throw new Error("FILE_KEY env var is required");
+  }
+  return key;
+}
+
+export async function downloadFile(
+  context: ArtilleryContext,
+  events: ArtilleryEvents
+): Promise<void> {
+  const logger = getLogger();
+  const env = readEnv();
+  const network = NETWORKS[env.network];
+  const fileKey = getFileKey();
+
+  // Get private key (from Artillery vars or fallback)
+  const privateKeyRaw =
+    typeof context.vars?.privateKey === "string" &&
+    context.vars.privateKey.length > 0
+      ? context.vars.privateKey
+      : nextPrivateKey().privateKey;
+
+  const privateKey = to0xPrivateKey(privateKeyRaw);
+  const { walletClient } = initWalletFromPrivateKey(network, privateKey);
+
+  // Connect and authenticate
+  const conn = await connectMsp(env, logger);
+
+  const siweStart = Date.now();
+  try {
+    await authenticateWithSiwe(conn, env, walletClient, logger);
+    events.emit("counter", "download.siwe.ok", 1);
+    events.emit("histogram", "download.siwe.ms", Date.now() - siweStart);
+  } catch (err) {
+    events.emit("counter", "download.siwe.err", 1);
+    logger.error({ err }, "siwe failed");
+    throw err;
+  }
+
+  // Download file
+  const dlStart = Date.now();
+  try {
+    const file = await conn.client.files.downloadFile(fileKey);
+    if (!file?.stream) {
+      throw new Error("downloadFile returned no stream");
+    }
+
+    // Consume stream, count bytes (no disk write)
+    // Type assertion needed: SDK returns web ReadableStream, Node expects its own variant
+    const nodeReadable = Readable.fromWeb(
+      file.stream as unknown as import("stream/web").ReadableStream
+    );
+    let totalBytes = 0;
+    for await (const chunk of nodeReadable) {
+      totalBytes += (chunk as Buffer).length;
+    }
+
+    events.emit("counter", "download.file.ok", 1);
+    events.emit("histogram", "download.file.ms", Date.now() - dlStart);
+    events.emit("histogram", "download.bytes", totalBytes);
+    logger.info({ fileKey, totalBytes }, "download complete");
+  } catch (err) {
+    events.emit("counter", "download.file.err", 1);
+    logger.error({ err, fileKey }, "download failed");
+    throw err;
+  }
+}