@artblocks/abx-storage 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/upload-readiness.d.ts

@@ -0,0 +1,89 @@
+import type { ResolveStorageOptions } from './resolve.js';
+import { type ArweaveConfig } from './arweave.js';
+/**
+ * Deploy-time storage readiness — what a REAL upload needs, decided from local facts (and, for the
+ * best-effort USD estimate, one price-API call) so "dry-run passes, then the real deploy fails at
+ * upload" can't happen. Three questions, each pure aside from the one noted network call:
+ *
+ *  - {@link planTurboUpload} — is THIS ONE file free (Turbo's 100 KiB tier) or chargeable?
+ *  - {@link assessStorageReadiness} — across every backend, what does a real upload of `sizes` need
+ *    (Arweave credits, a Pinata JWT, a cloud public base)?
+ *  - {@link assessTurboFunds} — does the resolved Turbo identity have ENOUGH prepaid credits for
+ *    `sizes`, and (when it's short) does the creator's own wallet already hold some?
+ *
+ * None of this mints or spends anything — it only INTERROGATES the resolved provider. Identity
+ * creation is the caller's job (the CLI's managed-key flow owns the key file location; see
+ * `arweave-identity.ts` / `ArweaveConfig.ensureJwk`), so `assessTurboFunds` expects a config that
+ * already has one.
+ */
+/** Whether `opts` resolves to Arweave via the Turbo (prepaid-credits) provider — the only provider
+ *  with a free tier and a funds balance to check; `http-bundler` skips every readiness/funds
+ *  question below (it has its own auth, not a balance this package knows how to read). */
+export declare function isTurboArweave(opts: ResolveStorageOptions): boolean;
+export interface TurboUploadPlan {
+    /** Whether this upload is over Turbo's 100 KiB free tier (so it draws on prepaid credits). */
+    chargeable: boolean;
+    /** `size` in KB, formatted to 1 decimal — for the free-vs-credit readout. */
+    sizeKb: string;
+}
+/** The free-vs-credit decision for ONE Turbo upload of `size` bytes — from the local byte size
+ *  alone, so it works under `--dry-run` too. Null when `opts` doesn't resolve to Turbo-Arweave
+ *  (nothing to decide). */
+export declare function planTurboUpload(opts: ResolveStorageOptions, size: number): TurboUploadPlan | null;
+/** Per-backend readiness facts for a real upload of `sizes` (per-file byte counts). Each variant
+ *  carries only what its backend needs checked; a backend with nothing to check (`fs`, or anything
+ *  this package doesn't know about) reports `'other'` — a literal, not the resolved id, so the
+ *  union stays a real discriminated union (a plain `string` member would swallow the other
+ *  branches on narrowing) — callers that branch on `backend` never needed the id anyway. */
+export type StorageReadinessReport = {
+    backend: 'arweave';
+    overCount: number;
+    totalCount: number;
+    totalKb: number;
+    usd: number | null;
+} | {
+    backend: 'ipfs';
+    pinataMissingJwt: boolean;
+} | {
+    backend: 'cloud';
+    missingPublicBase: boolean;
+} | {
+    backend: 'other';
+};
+/**
+ * What a REAL deploy against `opts` needs, from `sizes` (per-file byte sizes) alone — Arweave
+ * credit needs (plus a best-effort USD estimate for the chargeable bytes), a missing Pinata JWT, or
+ * a missing cloud public base. The one network call (Turbo's price API) is best-effort: a failure
+ * there degrades `usd` to `null` rather than failing the whole check.
+ */
+export declare function assessStorageReadiness(opts: ResolveStorageOptions, sizes: number[]): Promise<StorageReadinessReport>;
+export interface TurboFundsCheck {
+    /** True when the resolved identity does NOT have enough prepaid credits for `sizes`. */
+    short: boolean;
+    address: string;
+    /** Whether the identity is an EVM one (`.env` key or a remote wallet) rather than the CLI-managed
+     *  Arweave key — decides which recovery message applies. */
+    isEth: boolean;
+    haveWinc: number;
+    needWinc: number;
+    /** How many of `sizes` are over the free tier (what this shortfall is actually for). */
+    chargeableCount: number;
+    /** Set only when checked (short, a non-eth identity, and a wallet address was given): the
+     *  creator's OWN wallet's Turbo balance, queryable by address with no key — so "spend those
+     *  instead of topping up again" can be recommended before ever proposing a top-up. Null if that
+     *  wallet has never had a Turbo balance. */
+    walletCredits?: {
+        winc: number;
+        credits: string;
+    } | null;
+}
+/**
+ * The pre-upload funds decision for a Turbo (Arweave) upload of `sizes` (per-file byte sizes):
+ * chargeable bytes → the Winston cost → compare against the identity's prepaid balance. `cfg` must
+ * already have a resolved identity (`jwk`/`ethSignerKey`/`remoteEth`) — this module only
+ * INTERROGATES the resolved provider, never mints one (see the module doc). Returns `null` when
+ * nothing is chargeable (every file is free) or the provider can't be reached right now — a
+ * best-effort check never false-blocks; the upload itself will surface any real error.
+ */
+export declare function assessTurboFunds(cfg: ArweaveConfig, sizes: number[], walletAddr?: string): Promise<TurboFundsCheck | null>;
+//# sourceMappingURL=upload-readiness.d.ts.map

package/dist/upload-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-readiness.d.ts","sourceRoot":"","sources":["../src/upload-readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,cAAc,CAAC;AACxD,OAAO,EAAyG,KAAK,aAAa,EAAC,MAAM,cAAc,CAAC;AAExJ;;;;;;;;;;;;;;;GAeG;AAEH;;0FAE0F;AAC1F,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAEnE;AAED,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;2BAE2B;AAC3B,wBAAgB,eAAe,CAAC,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAGjG;AAED;;;;4FAI4F;AAC5F,MAAM,MAAM,sBAAsB,GAC9B;IAAC,OAAO,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,GAChG;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,OAAO,CAAA;CAAC,GAC5C;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAA;CAAC,GAC9C;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC,CAAC;AAEvB;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,qBAAqB,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAc1H;AAED,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;gEAC4D;IAC5D,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,eAAe,EAAE,MAAM,CAAC;IACxB;;;gDAG4C;IAC5C,aAAa,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAuBhI"}

package/dist/upload-readiness.js

@@ -0,0 +1,85 @@
+import { ARWEAVE_FREE_UPLOAD_LIMIT, arweaveFunding, turboBalanceForAddress, turboUploadCostUsd, turboUploadWinc } from './arweave.js';
+/**
+ * Deploy-time storage readiness — what a REAL upload needs, decided from local facts (and, for the
+ * best-effort USD estimate, one price-API call) so "dry-run passes, then the real deploy fails at
+ * upload" can't happen. Three questions, each pure aside from the one noted network call:
+ *
+ *  - {@link planTurboUpload} — is THIS ONE file free (Turbo's 100 KiB tier) or chargeable?
+ *  - {@link assessStorageReadiness} — across every backend, what does a real upload of `sizes` need
+ *    (Arweave credits, a Pinata JWT, a cloud public base)?
+ *  - {@link assessTurboFunds} — does the resolved Turbo identity have ENOUGH prepaid credits for
+ *    `sizes`, and (when it's short) does the creator's own wallet already hold some?
+ *
+ * None of this mints or spends anything — it only INTERROGATES the resolved provider. Identity
+ * creation is the caller's job (the CLI's managed-key flow owns the key file location; see
+ * `arweave-identity.ts` / `ArweaveConfig.ensureJwk`), so `assessTurboFunds` expects a config that
+ * already has one.
+ */
+/** Whether `opts` resolves to Arweave via the Turbo (prepaid-credits) provider — the only provider
+ *  with a free tier and a funds balance to check; `http-bundler` skips every readiness/funds
+ *  question below (it has its own auth, not a balance this package knows how to read). */
+export function isTurboArweave(opts) {
+    return opts.backend === 'arweave' && (opts.arweave?.provider ?? 'turbo') === 'turbo';
+}
+/** The free-vs-credit decision for ONE Turbo upload of `size` bytes — from the local byte size
+ *  alone, so it works under `--dry-run` too. Null when `opts` doesn't resolve to Turbo-Arweave
+ *  (nothing to decide). */
+export function planTurboUpload(opts, size) {
+    if (!isTurboArweave(opts))
+        return null;
+    return { chargeable: size >= ARWEAVE_FREE_UPLOAD_LIMIT, sizeKb: (size / 1024).toFixed(1) };
+}
+/**
+ * What a REAL deploy against `opts` needs, from `sizes` (per-file byte sizes) alone — Arweave
+ * credit needs (plus a best-effort USD estimate for the chargeable bytes), a missing Pinata JWT, or
+ * a missing cloud public base. The one network call (Turbo's price API) is best-effort: a failure
+ * there degrades `usd` to `null` rather than failing the whole check.
+ */
+export async function assessStorageReadiness(opts, sizes) {
+    if (opts.backend === 'arweave') {
+        const chargeable = sizes.filter((s) => s >= ARWEAVE_FREE_UPLOAD_LIMIT);
+        const usd = chargeable.length ? await turboUploadCostUsd(chargeable.reduce((a, b) => a + b, 0)) : null;
+        const totalKb = Math.round(sizes.reduce((a, b) => a + b, 0) / 1024);
+        return { backend: 'arweave', overCount: chargeable.length, totalCount: sizes.length, totalKb, usd };
+    }
+    if (opts.backend === 'ipfs') {
+        return { backend: 'ipfs', pinataMissingJwt: (opts.ipfs?.mode ?? 'pinata') === 'pinata' && !opts.ipfs?.pinataJwt };
+    }
+    if (opts.backend === 'cloud') {
+        return { backend: 'cloud', missingPublicBase: !opts.cloud?.publicBase };
+    }
+    return { backend: 'other' };
+}
+/**
+ * The pre-upload funds decision for a Turbo (Arweave) upload of `sizes` (per-file byte sizes):
+ * chargeable bytes → the Winston cost → compare against the identity's prepaid balance. `cfg` must
+ * already have a resolved identity (`jwk`/`ethSignerKey`/`remoteEth`) — this module only
+ * INTERROGATES the resolved provider, never mints one (see the module doc). Returns `null` when
+ * nothing is chargeable (every file is free) or the provider can't be reached right now — a
+ * best-effort check never false-blocks; the upload itself will surface any real error.
+ */
+export async function assessTurboFunds(cfg, sizes, walletAddr) {
+    const chargeable = sizes.filter((s) => s >= ARWEAVE_FREE_UPLOAD_LIMIT);
+    if (chargeable.length === 0)
+        return null; // all free
+    const funding = await arweaveFunding(cfg);
+    let address;
+    let haveWinc;
+    try {
+        address = await funding.address();
+        haveWinc = Number((await funding.balance()).winc) || 0;
+    }
+    catch {
+        return null; // can't reach Turbo to check — don't false-block; the upload will surface any real error
+    }
+    const needWinc = (await turboUploadWinc(chargeable.reduce((a, b) => a + b, 0))) ?? 0;
+    const short = needWinc > 0 ? haveWinc < needWinc : haveWinc <= 0;
+    const isEth = !!(cfg.ethSignerKey || cfg.remoteEth);
+    let walletCredits;
+    if (short && !isEth && walletAddr) {
+        const wb = await turboBalanceForAddress(walletAddr, 'ethereum');
+        walletCredits = wb ? { winc: Number(wb.winc) || 0, credits: wb.credits } : null;
+    }
+    return { short, address, isEth, haveWinc, needWinc, chargeableCount: chargeable.length, walletCredits };
+}
+//# sourceMappingURL=upload-readiness.js.map

package/dist/upload-readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-readiness.js","sourceRoot":"","sources":["../src/upload-readiness.ts"],"names":[],"mappings":"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"}

package/dist/upload.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `abx storage upload` core — upload ONE file and return a public locator that PRESERVES the
+ * filename, so the declared mimeType survives when the locator is later attached (`abx attach`).
+ * The on-chain metadata field has no MIME slot: the URL extension IS the type declaration, so a
+ * bare content-addressed locator (`ar://<txid>`, `<gw>/ipfs/<cid>`) — which has no extension —
+ * would make the attached artifact `application/octet-stream`. Extracted from main.ts so the
+ * capability-based branch (the exact bug this guards) is unit-testable with fake backends.
+ */
+import type { StorageBackend, StoredContent } from './backend.js';
+export interface UploadResult {
+    /** A fetchable public URL for the file. */
+    locator: string;
+    /** True when `locator` carries the filename (extension → correct declared type on attach). */
+    filenamePreserved: boolean;
+    /** Set when we had to fall back to a bare (extension-less) locator — the caller warns. */
+    fallbackReason?: string;
+}
+/**
+ * Store `content` under `name` and return the best available public locator. Preference order:
+ *  1. path-addressed host (cloud/S3/R2): the object key IS the filename → `<publicBase>/<name>`.
+ *  2. content-addressed host with directory support (ipfs/arweave): wrap the single file in a
+ *     one-entry directory → `<base>/<name>` (filename preserved).
+ *  3. bare content-addressed locator (e.g. kubo IPFS with no dir-add): `<gw>/ipfs/<cid>` — no
+ *     extension; `filenamePreserved: false` so the caller can warn about the octet-stream type.
+ * Throws for a backend that can't produce any public URL (e.g. `fs`).
+ */
+export declare function uploadAndLocate(backend: StorageBackend, name: string, content: StoredContent): Promise<UploadResult>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../src/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAGhE,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,iBAAiB,EAAE,OAAO,CAAC;IAC3B,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAyB1H"}

package/dist/upload.js

@@ -0,0 +1,41 @@
+import { hashContent } from './backend.js';
+const trimSlash = (s) => s.replace(/\/+$/, '');
+/**
+ * Store `content` under `name` and return the best available public locator. Preference order:
+ *  1. path-addressed host (cloud/S3/R2): the object key IS the filename → `<publicBase>/<name>`.
+ *  2. content-addressed host with directory support (ipfs/arweave): wrap the single file in a
+ *     one-entry directory → `<base>/<name>` (filename preserved).
+ *  3. bare content-addressed locator (e.g. kubo IPFS with no dir-add): `<gw>/ipfs/<cid>` — no
+ *     extension; `filenamePreserved: false` so the caller can warn about the octet-stream type.
+ * Throws for a backend that can't produce any public URL (e.g. `fs`).
+ */
+export async function uploadAndLocate(backend, name, content) {
+    if (backend.publicBase && backend.putObject) {
+        await backend.putObject(name, content);
+        return { locator: `${trimSlash(backend.publicBase)}/${name}`, filenamePreserved: true };
+    }
+    if (backend.putDirectory && backend.locator) {
+        try {
+            const { base } = await backend.putDirectory([{ name, bytes: content.bytes, contentType: content.contentType }]);
+            return { locator: `${trimSlash(base)}/${name}`, filenamePreserved: true };
+        }
+        catch (e) {
+            const hash = hashContent(content.bytes);
+            await backend.put(hash, content);
+            const loc = await backend.locator(hash);
+            if (!loc)
+                throw e;
+            return { locator: loc, filenamePreserved: false, fallbackReason: e.message };
+        }
+    }
+    if (backend.locator) {
+        const hash = hashContent(content.bytes);
+        await backend.put(hash, content);
+        const loc = await backend.locator(hash);
+        if (!loc)
+            throw new Error(`backend '${backend.id}' stored the file but returned no durable locator`);
+        return { locator: loc, filenamePreserved: false };
+    }
+    throw new Error(`backend '${backend.id}' can't produce a public URL for an attached file — use ipfs, arweave, or cloud (with a public base).`);
+}
+//# sourceMappingURL=upload.js.map

package/dist/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../src/upload.ts"],"names":[],"mappings":"AASA,OAAO,EAAC,WAAW,EAAC,MAAM,cAAc,CAAC;AAWzC,MAAM,SAAS,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAuB,EAAE,IAAY,EAAE,OAAsB;IACjG,IAAI,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QAC5C,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACvC,OAAO,EAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,IAAI,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAC,CAAC;IACxF,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,EAAC,IAAI,EAAC,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,EAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAC,CAAC,CAAC,CAAC;YAC5G,OAAO,EAAC,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAC,CAAC;QAC1E,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACxC,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,CAAC,GAAG;gBAAE,MAAM,CAAC,CAAC;YAClB,OAAO,EAAC,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,cAAc,EAAG,CAAW,CAAC,OAAO,EAAC,CAAC;QACxF,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,YAAY,OAAO,CAAC,EAAE,mDAAmD,CAAC,CAAC;QACrG,OAAO,EAAC,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAC,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,YAAY,OAAO,CAAC,EAAE,uGAAuG,CAAC,CAAC;AACjJ,CAAC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@artblocks/abx-storage",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.41",
   "license": "MIT",
-  "description": "ABX Self-Host Toolkit (Layer 3) — the reference byte-custody / storage service. Holds the source-of-truth bytes a token's content commitment points at, content-addressed by hash, behind a pluggable backend interface.",
+  "description": "Storage adapters for ABX content using filesystem, S3-compatible, IPFS, or Arweave backends.",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -13,18 +13,19 @@
   },
   "files": [
     "dist",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.13.0"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ArtBlocks/abx.git",
     "directory": "packages/storage"
   },
-  "homepage": "https://github.com/ArtBlocks/abx#readme",
+  "homepage": "https://docs.abx.io",
   "bugs": "https://github.com/ArtBlocks/abx/issues",
   "keywords": [
     "abx",
@@ -38,12 +39,19 @@
     "access": "public"
   },
   "dependencies": {
-    "viem": "^2.21.0",
-    "@artblocks/abx-sdk": "0.1.0-alpha.4"
+    "viem": "^2.56.5",
+    "@artblocks/abx-sdk": "0.1.0-alpha.41"
   },
-  "optionalDependencies": {
-    "@ardrive/turbo-sdk": "^1.23.0",
-    "@dha-team/arbundles": "^1.0.4"
+  "peerDependencies": {
+    "@artblocks/abx-storage-arweave": ">=0.1.0-alpha.0"
+  },
+  "peerDependenciesMeta": {
+    "@artblocks/abx-storage-arweave": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@artblocks/abx-storage-arweave": "0.1.0-alpha.5"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json"