@dstorage-tech/dstorage-sdk 0.0.4

package/dist/index.d.ts

@@ -0,0 +1,2843 @@
+import { PaymentAdapter, PaymentNetworkName, TokenSymbol, NetworkType, PaymentAdapterLogger, PaymentQuote, PaymentInstruction, PaymentReceipt, MidnightWalletProvider, StorageAdapterLogger, StorageAdapter, StorageProviderName, StorageUploadResult, StorageQuote, ChainAdapter, ChainProviderName, ChainAdapterLogger, ChainReference, ChainWriteResult, ChainReferenceUpdate, DataReferenceSummary, ChainQuote, WalletBalances } from './types.js';
+export { ChainAdapter, ChainAdapterLogger, ChainProviderName, ChainQuote, ChainReference, ChainReferenceUpdate, ChainWriteResult, DataReferenceSummary, MidnightWalletProvider, NetworkType, PaymentAdapter, PaymentAdapterLogger, PaymentNetworkName, PaymentQuote, PaymentReceipt, StorageAdapter, StorageAdapterLogger, StorageProviderName, StorageQuote, StorageUploadResult, TOKENS, Token, TokenSymbol, WalletBalances } from './types.js';
+import Arweave from 'arweave';
+import Transaction from 'arweave/node/lib/transaction';
+import { JWKInterface } from 'arweave/node/lib/wallet';
+import { WalletProvider, MidnightProvider } from '@midnight-ntwrk/midnight-js-types';
+import { WalletFacade, FacadeState } from '@midnight-ntwrk/wallet-sdk/facade';
+import { NetworkId } from '@midnight-ntwrk/midnight-js-network-id';
+export { NetworkId } from '@midnight-ntwrk/midnight-js-network-id';
+export { ChainErrorCode, StorageErrorCode } from './errors.js';
+export { MockChainAdapter, MockPaymentAdapter, MockStorageAdapter, MockStorageAdapterConfig } from './adapters/mock.js';
+
+/**
+ * @dstorage/payment — adapters/arweave.ts
+ *
+ * Arweave payment adapter.
+ *
+ * ── Sign-then-post flow ───────────────────────────────────────────────────────
+ *
+ * On Arweave, data and fee share a single transaction object. The fee is
+ * deducted automatically when the transaction is posted — there is no
+ * separate payment channel.
+ *
+ * This adapter implements the two-phase flow supported by MetaTransaction:
+ *
+ *   1. provideUploadData(data, metadata)
+ *        Called after encryption. Stores the data + metadata tags so that
+ *        pay() can build the complete transaction without a separate round-trip.
+ *
+ *   2. pay(instruction, onStatus)  [payment_storage step]
+ *        Creates the Arweave transaction, attaches tags, and prompts the
+ *        wallet for approval (ArConnect popup / JWK signing). Stores the
+ *        signed transaction for the upload step to pick up.
+ *
+ *   3. ArweaveStorageAdapter.store()  [store step]
+ *        Detects the pre-signed transaction via consumeSignedTx() and simply
+ *        posts it — no additional signing or wallet interaction needed.
+ *
+ * If provideUploadData() was not called (e.g. direct use outside MetaTransaction),
+ * pay() falls back to the pass-through behaviour and store() performs the full
+ * create → sign → post flow as before.
+ *
+ * Docs: https://docs.arweave.org/developers
+ */
+
+type ArweaveWallet = JWKInterface | "use_wallet";
+interface ArweavePaymentAdapterConfig {
+    /**
+     * Arweave gateway.
+     * Defaults to mainnet (arweave.net).
+     * Use { host: 'arweave.dev', port: 443, protocol: 'https' } for testnet.
+     * Use { host: 'localhost', port: 1984, protocol: 'http' } for arlocal.
+     *
+     * Security: always use `protocol: 'https'` (the default) in production.
+     * The SDK relies on standard OS/runtime TLS — no DNS or certificate pinning
+     * is applied. Users in adversarial network environments should enforce
+     * certificate pinning at the runtime level (e.g. a custom Node.js HTTPS
+     * agent or a trusted corporate proxy).
+     */
+    gateway?: {
+        host: string;
+        port: number;
+        protocol: "http" | "https";
+    };
+    /**
+     * JWK wallet key for Node.js server-side usage.
+     * In the browser leave undefined — ArConnect is used automatically.
+     */
+    walletKey?: Record<string, string>;
+    /**
+     * How long in ms before a quote expires.
+     * Defaults to 120_000 (2 minutes) — appropriate for Arweave's volatile pricing.
+     */
+    quoteValidityMs?: number;
+    /**
+     * Optional logger for SDK operational output.
+     */
+    logger?: PaymentAdapterLogger;
+}
+/** Internal state stored between provideUploadData() and pay(). */
+interface PendingUpload {
+    data: Uint8Array;
+    metadata: Record<string, string>;
+}
+/** Result stored after pay() signs the transaction, consumed by store(). */
+interface SignedArweaveUpload {
+    tx: Transaction;
+    /** AR cost string (e.g. "0.000001234") for the upload result. */
+    arCost: string;
+}
+declare class ArweavePaymentAdapter implements PaymentAdapter {
+    readonly network: PaymentNetworkName;
+    readonly token: TokenSymbol;
+    readonly type: NetworkType;
+    protected arweaveClient: Arweave | null;
+    protected readonly gateway: ArweavePaymentAdapterConfig["gateway"];
+    private readonly walletKey;
+    protected readonly quoteValidityMs: number;
+    protected readonly logger: PaymentAdapterLogger | undefined;
+    protected pendingUpload: PendingUpload | null;
+    protected signedUpload: SignedArweaveUpload | null;
+    constructor(config?: ArweavePaymentAdapterConfig);
+    protected getClient(): Promise<Arweave>;
+    protected resolveWallet(): ArweaveWallet;
+    /**
+     * 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: Uint8Array, metadata?: Record<string, string>): void;
+    /**
+     * Query the Arweave fee oracle for the real upload cost.
+     */
+    estimateCost(dataSizeBytes: number): Promise<PaymentQuote>;
+    /**
+     * 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.
+     */
+    pay(instruction: PaymentInstruction, onStatus?: (message: string) => void): Promise<PaymentReceipt>;
+    /**
+     * 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(): SignedArweaveUpload | null;
+}
+
+/**
+ * @dstorage/payment — adapters/managed.ts
+ *
+ * Managed payment adapter — remote payment via dStorage API services.
+ *
+ * Routes payment to the correct network-specific flow based on
+ * PaymentQuote.network. All networks share the same endpoint:
+ *   POST {baseUrl}{POST_SIGN_TX_API_PATH}
+ * Currently implemented:
+ *   - "arweave": remote Arweave signing via REST API
+ *   - "arweave_bundler": remote ANS-104 bundled-upload signing via REST API
+ *   - "midnight": remote Midnight transaction balancing/signing via REST API
+ *
+ * ── Arweave flow ──────────────────────────────────────────────────────────────
+ *
+ * Instead of signing the Arweave transaction locally (ArConnect or JWK),
+ * this adapter constructs the Arweave transaction, computes the Merkle tree
+ * (data_root) locally, then sends a stripped transaction JSON — containing
+ * only metadata, data_root, and data_size but NOT the raw file bytes — to a
+ * remote REST API. The server holds a funded Arweave account, signs the
+ * stripped transaction, and returns the signature and id. The file content
+ * never leaves the client.
+ *
+ *   POST {baseUrl}{POST_SIGN_TX_API_PATH}
+ *        → { txData: object, network: string, userId: string }
+ *             txData   — Arweave transaction JSON with data stripped (tx.toJSON()
+ *                        after clearing tx.data; data_root + data_size preserved).
+ *             network  — Arweave network identifier (e.g. "arweave", "arlocal").
+ *             userId   — caller identity forwarded to the server.
+ *        ← { txId: string, signature: string, publicKey: string, txAmount: string, ... }
+ *             txId      — valid 43-char base64url Arweave transaction id.
+ *             signature — base64url RSA-PSS signature.
+ *             publicKey — server wallet's RSA modulus n (base64url).
+ *             The adapter calls tx.setSignature({ id, signature, owner }).
+ *
+ * ── Integration (Arweave) ─────────────────────────────────────────────────────
+ *
+ * ManagedPaymentAdapter extends ArweavePaymentAdapter and slots into the
+ * same sign-then-post flow used by ArweaveStorageAdapter:
+ *
+ *   MetaTransaction:
+ *     provideUploadData(data, metadata)  ← stores data + tags
+ *     pay(instruction, onStatus)          ← routes by instruction.network, creates tx,
+ *                                           sends JSON to server, applies signature
+ *
+ *   ArweaveStorageAdapter.store():
+ *     consumeSignedUpload()              ← picks up the pre-signed tx
+ *     postWithRetry(arweave, tx)         ← broadcasts to Arweave network
+ */
+
+interface ManagedPaymentAdapterConfig extends Omit<ArweavePaymentAdapterConfig, "walletKey"> {
+    /** Which network this adapter is used for */
+    network: PaymentNetworkName;
+    /** Whether this covers a storage network fee or a chain transaction fee */
+    type: NetworkType;
+    /**
+     * Base URL of the remote signing server (no trailing slash).
+     * Example: "https://api.my-server.com"
+     */
+    signingServerUrl: string;
+    /**
+     * Bearer token sent as the `Authorization` header to authenticate with the signing server.
+     * Must be a non-empty, non-whitespace string — the constructor throws immediately on
+     * an empty value so a misconfigured caller (e.g. unresolved env var) fails fast
+     * rather than silently sending unauthenticated requests to the signing service.
+     */
+    authToken: string;
+    /**
+     * Maximum time in milliseconds to wait for the signing server to respond before
+     * aborting the request and throwing. Defaults to 30 000 ms (30 s).
+     * Pass `0` to disable the timeout entirely (not recommended for production).
+     */
+    requestTimeoutMs?: number;
+}
+declare class ManagedPaymentAdapter extends ArweavePaymentAdapter {
+    readonly network: PaymentNetworkName;
+    readonly type: NetworkType;
+    private readonly signingServerUrl;
+    private readonly authToken;
+    private readonly requestTimeoutMs;
+    private readonly ownerPublicKey;
+    /**
+     * 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.
+     */
+    private static _parseAuthToken;
+    constructor(config: ManagedPaymentAdapterConfig);
+    /**
+     * Query the Arweave fee oracle for the real upload cost.
+     */
+    estimateCost(dataSizeBytes: number): Promise<PaymentQuote>;
+    /**
+     * 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.
+     */
+    pay(instruction: PaymentInstruction, onStatus?: (message: string) => void): Promise<PaymentReceipt>;
+    /**
+     * 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.
+     *
+     * 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 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.
+     */
+    createMidnightWalletProvider(coinPublicKey: string, encryptionPublicKey: string, onReceipt?: (receipt: PaymentReceipt) => void): MidnightWalletProvider;
+    /**
+     * 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.
+     */
+    private _payArweave;
+    /**
+     * 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().
+     */
+    private _payMidnight;
+    /**
+     * Arweave Bundler
+     */
+    private _payArweaveBundler;
+    /**
+     * 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".
+     */
+    private _payManagedMock;
+    /**
+     * 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.
+     */
+    private _sendSignTxRequest;
+}
+
+/**
+ * @dstorage/storage — adapters/arweave.ts
+ *
+ * Real Arweave storage adapter.
+ * Uploads encrypted blobs to the Arweave permaweb — pay once, store forever.
+ *
+ * ── Runtime environments ──────────────────────────────────────────────────────
+ *
+ *   Browser (ArConnect):
+ *     const adapter = new ArweaveStorageAdapter();
+ *     // Requires the ArConnect extension: https://arconnect.io
+ *
+ *   Node.js (JWK wallet file):
+ *     const adapter = new ArweaveStorageAdapter({
+ *       walletKey: JSON.parse(fs.readFileSync('wallet.json', 'utf8')),
+ *     });
+ *
+ * ── Testnet ───────────────────────────────────────────────────────────────────
+ *
+ *   const adapter = new ArweaveStorageAdapter({
+ *     gateway: { host: 'arweave.dev', port: 443, protocol: 'https' },
+ *   });
+ *
+ * ── Peer dependency ───────────────────────────────────────────────────────────
+ *   npm install arweave
+ *
+ * ── Notes ─────────────────────────────────────────────────────────────────────
+ *
+ *   • Arweave transactions are optimistic: a 202 response means accepted, not
+ *     confirmed. Confirmation (inclusion in a block) typically takes 2–20 minutes.
+ *     Set waitForConfirmation: true to block until the tx is on-chain.
+ *
+ *   • For large files or high-volume uploads, consider Irys (https://irys.xyz)
+ *     which bundles many transactions together for cheaper and near-instant
+ *     finality. An IrysStorageAdapter can be added alongside this one.
+ *
+ *   • storageId (txId) is PUBLIC on Arweave. Data security relies entirely on
+ *     the XChaCha20-Poly1305 encryption applied by @dstorage/crypto before reaching here.
+ */
+
+interface ArweaveGatewayConfig {
+    host: string;
+    port: number;
+    protocol: "http" | "https";
+}
+interface ArweaveAdapterConfig {
+    /**
+     * Arweave gateway to broadcast transactions to.
+     * Defaults to mainnet (arweave.net:443).
+     *
+     * Testnet: { host: 'arweave.dev', port: 443, protocol: 'https' }
+     *
+     * Security: always use `protocol: 'https'` (the default) in production.
+     * The SDK relies on standard OS/runtime TLS — no DNS or certificate pinning
+     * is applied. Users in adversarial network environments should enforce
+     * certificate pinning at the runtime level (e.g. a custom Node.js HTTPS
+     * agent or a trusted corporate proxy).
+     */
+    gateway?: ArweaveGatewayConfig;
+    /**
+     * JWK wallet key for Node.js server-side usage.
+     * Leave undefined in the browser — ArConnect is used automatically.
+     *
+     * Obtain a free wallet at https://arweave.app or generate via arweave-js:
+     *   const jwk = await Arweave.init({}).wallets.generate();
+     */
+    walletKey?: Record<string, string>;
+    /**
+     * Base URL of a local ManagedPaymentAdapter signing server.
+     * When provided, the adapter uses ManagedPaymentAdapter (remote signing)
+     * instead of the default ArweavePaymentAdapter (local signing).
+     * Example: "http://localhost:3000"
+     */
+    signingServerUrl?: string;
+    /**
+     * Bearer token sent as the `Authorization` header to authenticate with the signing server.
+     * Required when `signingServerUrl` is provided.
+     */
+    authToken?: string;
+    /**
+     * How many times to retry a failed transaction post before throwing.
+     * Uses a simple linear back-off: 1 s, 2 s, 3 s…
+     * Defaults to 3.
+     */
+    maxRetries?: number;
+    /**
+     * If true, poll Arweave until the transaction is confirmed (block included)
+     * before returning from store(). Confirmation typically takes 2–20 minutes.
+     *
+     * Defaults to false (optimistic — returns as soon as the gateway accepts
+     * the transaction with HTTP 200 or 202).
+     */
+    waitForConfirmation?: boolean;
+    /**
+     * Polling interval in ms while waiting for confirmation.
+     * Defaults to 30_000 (30 seconds).
+     */
+    confirmationPollMs?: number;
+    /**
+     * Maximum time in ms to wait for confirmation before throwing a timeout error.
+     * Defaults to 1_200_000 (20 minutes).
+     */
+    confirmationTimeoutMs?: number;
+    /**
+     * When true, skip the BLAKE3 content-hash check on retrieve.
+     * By default (false) the adapter fetches the transaction metadata and verifies
+     * that the `X-Content-Hash` tag recorded at upload time matches the retrieved
+     * bytes. Set to true only if you trust the gateway entirely or are using an
+     * Arweave node that does not expose the transaction metadata endpoint.
+     */
+    skipIntegrityCheck?: boolean;
+    /**
+     * Maximum number of bytes allowed in a single retrieve() call.
+     * The adapter rejects the download before materialising the blob if the
+     * Arweave transaction metadata reports a larger `data_size`, and always
+     * rejects after loading if the actual byte count exceeds this value.
+     * Defaults to 268_435_456 (256 MB).
+     */
+    maxRetrieveSizeBytes?: number;
+    /**
+     * Optional logger for SDK operational output.
+     * Pass `logger: console` to see all output, or inject your own logger.
+     * Omit to suppress all SDK log output.
+     */
+    logger?: StorageAdapterLogger;
+}
+declare class ArweaveStorageAdapter implements StorageAdapter {
+    readonly name: StorageProviderName;
+    readonly providerName: string;
+    paymentAdapter: PaymentAdapter;
+    private readonly gateway;
+    private readonly maxRetries;
+    private readonly shouldWaitForConfirm;
+    private readonly confirmationPollMs;
+    private readonly confirmationTimeoutMs;
+    private readonly skipIntegrityCheck;
+    private readonly maxRetrieveSizeBytes;
+    protected readonly logger: StorageAdapterLogger | undefined;
+    private arweaveClient;
+    constructor(config?: ArweaveAdapterConfig);
+    private getClient;
+    store(data: Uint8Array, metadata?: Record<string, string>): Promise<StorageUploadResult>;
+    retrieve(id: string): Promise<{
+        bytes: Uint8Array;
+        tags: Record<string, string>;
+    }>;
+    estimateCost(dataSizeBytes: number): Promise<StorageQuote>;
+    /**
+     * Upload a signed transaction using arweave-js getUploader().
+     *
+     * getUploader() sends just the tx header to /tx, then streams each 256 KB
+     * data slice to the /chunk endpoint. This avoids the ~12 MB HTTP body limit
+     * of transactions.post() and supports arbitrarily large transactions.
+     *
+     * Failed slices are retried individually up to maxRetries times with linear
+     * back-off, so a transient network error won't restart the entire upload.
+     */
+    private uploadWithChunker;
+    private pollUntilConfirmed;
+}
+
+/**
+ * @dstorage/storage — adapters/arweave-bundler.ts
+ *
+ * Arweave Bundler storage adapter — ANS-104 bundled uploads with server-side signing.
+ *
+ * ── Upload flow (no client-side Arweave wallet needed) ────────────────────────
+ *
+ *   1. Client creates an ANS-104 data item locally with the already-encrypted data.
+ *   2. Computes the 48-byte deep_hash locally — the ANS-104 signing digest.
+ *   3. Sends ONLY the hash to the dStorage API signing server.
+ *      Raw file bytes never leave the client — same privacy invariant as the
+ *      current managed Arweave flow where only the stripped tx JSON (data_root)
+ *      goes to the server.
+ *   4. Server signs the hash with its Arweave JWK (funded Turbo Credits account).
+ *   5. Client assembles the complete signed data item locally.
+ *   6. Client POSTs the signed data item directly to the ArDrive bundler.
+ *   7. Returns with near-instant finality — txId is available immediately.
+ *
+ * ── Retrieve flow ─────────────────────────────────────────────────────────────
+ *   Standard Arweave gateway fetch (identical to ArweaveStorageAdapter.retrieve).
+ *
+ * ── Peer dependency ───────────────────────────────────────────────────────────
+ *   No extra install needed — @dha-team/arbundles ships as a dependency of @ardrive/turbo-sdk.
+ *
+ * ── Server requirements ───────────────────────────────────────────────────────
+ *   The dStorage API server must expose (auth-protected via Bearer token):
+ *     POST /api/service/sign-tx  → { signature: string, txId: string, success: boolean, … }
+ *   The server's Arweave wallet must have Turbo Credits funded at https://ardrive.io.
+ *
+ * ── Auth token format ─────────────────────────────────────────────────────────
+ *   authToken must be in the format: <credential>.<base64url_modulus>
+ *   where <base64url_modulus> is the 512-byte RSA-4096 public key modulus
+ *   base64url-encoded. The adapter validates and pins the key at construction time.
+ *   Re-issue the token from the signing server to obtain the current key.
+ *
+ * ── Notes ─────────────────────────────────────────────────────────────────────
+ *   • The ArDrive bundler provides near-instant finality — unlike the 2–20 min Arweave L1 wait.
+ *   • The server holds the funded Turbo Credits account; users need no AR tokens.
+ *   • Only 48 bytes (the deep_hash) go to the server; ciphertext stays on client.
+ */
+
+interface ArweaveBundlerAdapterConfig {
+    /**
+     * Base URL of the dStorage API server that holds the funded Turbo Credits account.
+     * Example: "https://api.my-dstorage-server.com"
+     */
+    signingServerUrl?: string;
+    /**
+     * Bearer token sent as the `Authorization` header to authenticate with the signing server.
+     * Required when `signingServerUrl` is provided.
+     */
+    authToken?: string;
+    /**
+     * Arweave gateway URL used for data retrieval.
+     * Defaults to the public Arweave gateway.
+     *
+     * Security: always use an `https://` URL (the default) in production.
+     * This adapter uses `globalThis.fetch` directly — no DNS or certificate
+     * pinning is applied. Users in adversarial network environments can override
+     * `globalThis.fetch` before constructing the adapter to inject their own
+     * certificate-pinned fetch implementation.
+     */
+    gateway?: string;
+    /**
+     * Maximum number of bytes allowed in a single retrieve() call.
+     * Rejects if the `Content-Length` response header exceeds this value, and
+     * always rejects after loading if the actual byte count exceeds it.
+     * Defaults to 268_435_456 (256 MB).
+     */
+    maxRetrieveSizeBytes?: number;
+    /**
+     * Skip BLAKE3 content-hash verification on retrieve.
+     * Only set to true when connecting to a fully trusted gateway.
+     * Defaults to false.
+     */
+    skipIntegrityCheck?: boolean;
+    /**
+     * Optional logger for SDK operational output.
+     */
+    logger?: StorageAdapterLogger;
+}
+/**
+ * Stores encrypted data on Arweave via the ArDrive bundler (near-instant finality).
+ *
+ * Signing is delegated to the dStorage API server, which holds a funded Turbo Credits
+ * account. The client sends only a 48-byte ANS-104 deep_hash to the server — the
+ * encrypted file bytes never leave the client, preserving the same privacy invariant
+ * as the existing managed Arweave flow.
+ *
+ * @example
+ * const adapter = new ArweaveBundlerStorageAdapter({
+ *   signingServerUrl: "https://api.my-server.com",
+ *   authToken: "ds_...",
+ * });
+ * const { id } = await adapter.store(encryptedBytes, { "Content-Type": "application/octet-stream" });
+ */
+declare class ArweaveBundlerStorageAdapter implements StorageAdapter {
+    readonly name: StorageProviderName;
+    readonly providerName = "Arweave (Bundler)";
+    readonly paymentAdapter: PaymentAdapter;
+    private readonly signingServerUrl;
+    private readonly gateway;
+    private readonly maxRetrieveSizeBytes;
+    private readonly skipIntegrityCheck;
+    protected readonly logger: StorageAdapterLogger | undefined;
+    /** RSA-4096 public key modulus (512 bytes) parsed from the auth token at construction time. */
+    private readonly ownerPublicKey;
+    constructor(config?: ArweaveBundlerAdapterConfig);
+    store(data: Uint8Array, metadata?: Record<string, string>): Promise<StorageUploadResult>;
+    retrieve(id: string): Promise<{
+        bytes: Uint8Array;
+        tags: Record<string, string>;
+    }>;
+    estimateCost(dataSizeBytes: number): Promise<StorageQuote>;
+    /**
+     * Build a minimal signer object compatible with the @dha-team/arbundles DataItem API.
+     *
+     * The only non-trivial method is sign(): it sends the deep_hash produced by
+     * the DataItem's internal ANS-104 signing procedure to the selected payment adapter.
+     * The payment adapter responds with the RSA-PSS signature over that hash (512 bytes, ANS-104 type 1).
+     * Raw file bytes never leave the client.
+     *
+     * The owner public key is parsed from the auth token at construction time — no
+     * network round-trip is needed here.
+     */
+    private _buildSigner;
+    /**
+     * POST the 48-byte ANS-104 deep_hash to the signing server via the shared sign-tx endpoint.
+     *
+     * Uses network: "arweave_bundler" so the server routes to the bundler-specific signing path.
+     * The `dataSizeBytes` field lets the server estimate and quote the upload cost.
+     */
+    private _signHash;
+    /**
+     * Parse the compound auth token (<credential>.<base64url_modulus>) issued by the
+     * signing server. Validates that the embedded key is exactly 512 bytes (RSA-4096).
+     * Throws at construction time if the format is wrong — fail-fast before any network call.
+     *
+     * 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.
+     */
+    private static _parseToken;
+    /**
+     * POST the complete signed ANS-104 data item bytes directly to the ArDrive bundler.
+     * Server Turbo Credits are consumed based on the signing key — no client wallet needed.
+     */
+    private _uploadToBundler;
+}
+
+/**
+ * @dstorage/storage — arweave-local.ts
+ *
+ * Local Arweave testing utilities built on top of arlocal:
+ *   https://github.com/textury/arlocal
+ *
+ * arlocal is a zero-configuration local Arweave gateway for integration
+ * testing. It accepts transactions without requiring real AR tokens, exposes
+ * a /mint endpoint to fund test wallets instantly, and a /mine endpoint to
+ * fast-forward block confirmation — all fully offline.
+ *
+ * ── Quick start ───────────────────────────────────────────────────────────────
+ *
+ *   # 1. Start arlocal (once per dev session) — Docker is recommended:
+ *   docker run -d --rm -p 1984:1984 --name arlocal textury/arlocal
+ *   # alternatively, without Docker:
+ *   npx arlocal
+ *
+ *   # 2. In your code, use ArweaveLocalStorageAdapter instead of the real one
+ *   const { adapter, walletKey, address } =
+ *     await ArweaveLocalStorageAdapter.createWithTestWallet();
+ *
+ *   # 3. Mint test tokens
+ *   await adapter.testnet.mintTokens(address, 5_000_000_000_000n); // 5 AR
+ *
+ *   # 4. Use exactly like ArweaveStorageAdapter
+ *   const { id } = await adapter.store('my encrypted data');
+ *   await adapter.testnet.mine(); // confirm the tx instantly
+ *   const data = await adapter.retrieve(id);
+ *
+ * ── Exports ───────────────────────────────────────────────────────────────────
+ *
+ *   ARWEAVE_MAINNET           — gateway preset for arweave.net
+ *   ARWEAVE_LOCAL             — gateway preset for localhost:1984
+ *   arlocalGateway(port)      — build a custom-port local preset
+ *   ArweaveLocalHelper        — mint / mine / balance / reset helpers
+ *   ArweaveLocalStorageAdapter — drop-in adapter for local testing
+ *   ArweaveLocalError          — typed error thrown by helper methods
+ */
+
+/**
+ * Local arlocal gateway preset (default port 1984).
+ *
+ * @example
+ * new ArweaveStorageAdapter({ gateway: ARWEAVE_LOCAL, walletKey: testJwk })
+ * // or:
+ * new ArweaveLocalStorageAdapter({ walletKey: testJwk })
+ */
+declare const ARWEAVE_LOCAL: ArweaveGatewayConfig;
+/**
+ * Build a local arlocal gateway preset on a non-default port.
+ *
+ * @example
+ * const gw = arlocalGateway(1985);
+ * new ArweaveLocalStorageAdapter({ gateway: gw, walletKey: testJwk })
+ */
+declare function arlocalGateway(port?: number): ArweaveGatewayConfig;
+interface ArweaveLocalHelperConfig {
+    /** Base URL of the arlocal instance. Defaults to 'http://localhost:1984'. */
+    url?: string;
+}
+interface ArweaveLocalInfo {
+    network: string;
+    version: number;
+    release: number;
+    height: number;
+    current: string;
+    peers: number;
+    queue_length: number;
+    node_state_latency: number;
+}
+interface ArweaveLocalBalance {
+    /** Raw balance in Winstons (1 AR = 1_000_000_000_000 Winstons). */
+    winstons: string;
+    /** Human-readable balance, e.g. "5" for 5 AR. */
+    ar: string;
+}
+/**
+ * Helper for controlling a running arlocal instance.
+ *
+ * Use this to fund test wallets, fast-forward block confirmations, and
+ * inspect state during integration tests.
+ *
+ * @example
+ * const helper = new ArweaveLocalHelper();
+ * await helper.mintTokens(address, 1_000_000_000_000n); // 1 AR
+ * await helper.mine();
+ * const { ar } = await helper.getBalance(address);
+ */
+declare class ArweaveLocalHelper {
+    private readonly baseUrl;
+    constructor(config?: ArweaveLocalHelperConfig);
+    /**
+     * Credit a wallet address with test AR tokens.
+     *
+     * The amount is in Winstons (1 AR = 1_000_000_000_000 Winstons).
+     * Defaults to 1 AR if not specified.
+     *
+     * @example
+     * await helper.mintTokens(address, 5_000_000_000_000n); // 5 AR
+     */
+    mintTokens(address: string, winstons?: bigint | number): Promise<void>;
+    /**
+     * Fast-forward the arlocal blockchain by mining one or more blocks.
+     *
+     * Pending transactions only become "confirmed" after a block is mined.
+     * Call this after uploading if your test checks confirmed status
+     * (e.g. when using `waitForConfirmation: true`).
+     *
+     * @example
+     * await helper.mine();       // mine 1 block
+     * await helper.mine(3);      // mine 3 blocks
+     */
+    mine(blocks?: number): Promise<void>;
+    /**
+     * Query the AR token balance of a wallet address on arlocal.
+     *
+     * @example
+     * const { ar, winstons } = await helper.getBalance(address);
+     * console.log(`Balance: ${ar} AR (${winstons} winstons)`);
+     */
+    getBalance(address: string): Promise<ArweaveLocalBalance>;
+    /**
+     * Retrieve general info about the arlocal instance.
+     * Useful for confirming the server is reachable before running tests.
+     */
+    getInfo(): Promise<ArweaveLocalInfo>;
+    /**
+     * Returns `true` if the arlocal instance is reachable, `false` otherwise.
+     *
+     * Use in `beforeAll` to skip integration tests gracefully when arlocal
+     * is not running in the local environment.
+     *
+     * @example
+     * beforeAll(async () => {
+     *   if (!(await helper.isRunning())) {
+     *     console.warn('arlocal not running — skipping integration tests');
+     *   }
+     * });
+     */
+    isRunning(): Promise<boolean>;
+    /**
+     * Drop all transactions and reset arlocal state to a clean slate.
+     * Only available when arlocal is started with persistence disabled (the default).
+     */
+    reset(): Promise<void>;
+    private get;
+}
+type ArweaveLocalAdapterConfig = ArweaveAdapterConfig;
+/**
+ * A storage adapter for local Arweave integration testing using arlocal.
+ *
+ * Identical API to `ArweaveStorageAdapter` but pre-configured for a local
+ * arlocal instance. Exposes a `.testnet` helper for minting tokens, mining
+ * blocks, and inspecting state — without touching the real Arweave network.
+ *
+ * ── Requirements ──────────────────────────────────────────────────────────────
+ *
+ *   Start arlocal (Docker recommended — no npm install needed):
+ *        docker run -d --rm -p 1984:1984 --name arlocal textury/arlocal
+ *      or, via npx (installs arlocal on demand):
+ *        npx arlocal
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ * Option A — static factory (recommended for tests): auto-generates & funds wallet
+ *
+ *   const { adapter, walletKey, address } =
+ *     await ArweaveLocalStorageAdapter.createWithTestWallet();
+ *
+ *   const ds = new DStorage({
+ *     storageAdapter: adapter,
+ *     chainAdapter:   new MockChainAdapter(),
+ *   });
+ *
+ * Option B — manual config (when you already have a wallet):
+ *
+ *   const adapter = new ArweaveLocalStorageAdapter({ walletKey: myJwk });
+ *   await adapter.testnet.mintTokens(address, 2_000_000_000_000n); // 2 AR
+ *
+ * ── Replacing the real adapter ────────────────────────────────────────────────
+ *
+ *   // Development / CI — local arlocal
+ *   storageAdapter: new ArweaveLocalStorageAdapter({ walletKey: testJwk })
+ *
+ *   // Production — real Arweave mainnet
+ *   storageAdapter: new ArweaveStorageAdapter({ walletKey: realJwk })
+ */
+declare class ArweaveLocalStorageAdapter extends ArweaveStorageAdapter {
+    readonly name: StorageProviderName;
+    readonly providerName: string;
+    /** Access arlocal control methods: mint, mine, balance, reset. */
+    readonly testnet: ArweaveLocalHelper;
+    /** Resolves when the wallet has been funded on arlocal (if walletKey was provided). */
+    private readonly _initMintPromise;
+    constructor(config?: ArweaveLocalAdapterConfig);
+    /**
+     * Extract the 683-char base64url RSA modulus suffix from a compound auth token
+     * (<credential>.<modulus>). Returns undefined for plain tokens.
+     * Mirrors the same logic in ManagedPaymentAdapter._parseAuthToken.
+     */
+    private static _extractOwnerKey;
+    private _mintWallet;
+    private _mintManagedOwner;
+    private _mintToOwnerKey;
+    /**
+     * Factory method: generates a fresh Arweave wallet, mints test AR tokens
+     * into it, and returns a fully-configured adapter ready for testing.
+     *
+     * Requires arlocal to be running at the given URL.
+     *
+     * @param options.fundAr    AR to mint into the test wallet (default: 10)
+     * @param options.gateway   Override the arlocal gateway (default: localhost:1984)
+     *
+     * @example
+     * const { adapter, walletKey, address } =
+     *   await ArweaveLocalStorageAdapter.createWithTestWallet({ fundAr: 5 });
+     *
+     * // Then use adapter in your DStorage instance:
+     * const ds = new DStorage({ storageAdapter: adapter, chainAdapter: new MockChainAdapter() });
+     */
+    static createWithTestWallet(options?: {
+        fundAr?: number;
+        gateway?: ArweaveGatewayConfig;
+    }): Promise<{
+        adapter: ArweaveLocalStorageAdapter;
+        walletKey: Record<string, string>;
+        address: string;
+    }>;
+    store(data: Uint8Array, metadata?: Record<string, string>): Promise<StorageUploadResult>;
+}
+declare class ArweaveLocalError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+
+declare class DStorageError extends Error {
+    readonly code: number;
+    readonly httpStatus?: number;
+    constructor(code: number, message: string, options?: ErrorOptions & {
+        httpStatus?: number;
+    });
+}
+declare function isDStorageError(err: unknown): err is DStorageError;
+declare const CryptoErrorCode: {
+    readonly WEBCRYPTO_NOT_AVAILABLE: 12000;
+    readonly BASE64URL_INVALID: 12001;
+    readonly MISSING_KEY_INPUT: 12002;
+    readonly MNEMONIC_TOO_SHORT: 12003;
+    readonly SEED_INVALID_LENGTH: 12004;
+    readonly MNEMONIC_INVALID: 12005;
+    readonly HEX_ODD_LENGTH: 12006;
+    readonly HEX_INVALID_CHARS: 12007;
+    readonly DEK_INVALID_LENGTH: 12008;
+    readonly WRAP_KEK_INVALID_LENGTH: 12009;
+    readonly UNWRAP_KEK_INVALID_LENGTH: 12010;
+    readonly ENVELOPE_EMPTY_WRAPPERS: 12011;
+    readonly XCHACHA_INVALID_STORAGE_ID_LEN: 12012;
+    readonly XCHACHA_PAYLOAD_MALFORMED: 12013;
+    readonly XCHACHA_STORAGE_ID_MALFORMED: 12014;
+    readonly MLKEM_SEED_INVALID_LENGTH: 12015;
+    readonly MLKEM_MISSING_CIPHERTEXT: 12016;
+    readonly MLKEM_UNKNOWN_ALGORITHM: 12017;
+    readonly MLKEM_UNKNOWN_VARIANT: 12018;
+};
+type CryptoErrorCode = (typeof CryptoErrorCode)[keyof typeof CryptoErrorCode];
+
+/**
+ * @dstorage/crypto — types.ts
+ *
+ * Core types and interfaces for the crypto package:
+ *   - EncryptionScheme  — on-chain scheme identifier
+ *   - CryptoScheme      — interface every scheme implementation must satisfy
+ *   - base64url helpers — shared encoding utilities used across scheme implementations
+ */
+/**
+ * Identifies the encryption algorithm used to encrypt a storageId and content.
+ * Recorded on-chain in ReferenceEntry.encryptionScheme so the SDK can dispatch
+ * the correct decryption function at read time.
+ *
+ * Values:
+ *   "xchacha20poly1305-v1" — XChaCha20-Poly1305 (per-upload random DEK, wrapped in keyEnvelope); default
+ *   ""                     — No encryption; storageId and content are stored as plaintext (public data)
+ */
+type EncryptionScheme = "xchacha20poly1305-v1" | "";
+/**
+ * The result of wrapping a DEK under a provider's key material.
+ * Returned by every EncryptionAdapter.wrapDek() implementation and
+ * stored as a KeyWrapper entry inside the on-chain KeyEnvelope.
+ *
+ * Symmetric providers set algorithm/kekDerivation for their own scheme and
+ * leave kemCiphertext undefined. Asymmetric providers (ML-KEM) additionally
+ * populate kemCiphertext with the KEM ciphertext needed for decapsulation.
+ */
+interface WrappedDekResult {
+    /** Algorithm identifier, e.g. "xchacha20poly1305-v1" or "mlkem768-xchacha20poly1305-v1". */
+    algorithm: string;
+    /** How the KEK was derived from its source material, e.g. "hkdf-sha256-v1". */
+    kekDerivation: string;
+    /** base64url-encoded wrapped DEK ciphertext. */
+    wrappedDek: string;
+    /** base64url-encoded KEM ciphertext — present only for asymmetric providers. */
+    kemCiphertext?: string;
+}
+/**
+ * Interface for a symmetric encryption scheme.
+ *
+ * Implementations are instantiated from a random DEK via a static factory
+ * (e.g. XChaChaScheme.fromKey(dek)) for per-upload encryption.
+ */
+interface CryptoScheme {
+    /** Scheme identifier recorded on-chain. */
+    readonly schemeName: Exclude<EncryptionScheme, "">;
+    /**
+     * Encrypt raw bytes and return a self-contained serialized payload
+     * ready to be uploaded to off-chain storage.
+     *
+     * `aad` is bound into the Poly1305 auth tag and must match on decrypt.
+     * Use PAYLOAD_AAD for single-shot uploads and manifests; use chunkAad(i, n)
+     * for individual chunks so a malicious gateway cannot swap chunk order.
+     */
+    encryptPayload(bytes: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Deserialize and decrypt a payload previously produced by encryptPayload().
+     * Throws if the payload format is invalid, the auth tag fails, or the AAD mismatches.
+     */
+    decryptPayload(data: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Encrypt a 43-char base64url storage ID (32 decoded bytes) for on-chain storage.
+     * Returns a base64url-encoded encrypted form.
+     */
+    encryptStorageId(storageId: string): Promise<string>;
+    /**
+     * Decrypt a storage ID previously encrypted by encryptStorageId().
+     * Returns the original 43-char base64url storage ID.
+     */
+    decryptStorageId(encryptedId: string): Promise<string>;
+}
+/** Decode a base64url string to a Uint8Array. */
+declare function base64urlToBytes(b64url: string): Uint8Array;
+/** Encode a Uint8Array to a base64url string (no padding). */
+declare function bytesToBase64url(bytes: Uint8Array): string;
+
+/**
+ * @dstorage/crypto — keys.ts
+ * Provides seed-based key derivation utilities:
+ *
+ * - KeyDeriver: resolves a BIP-39 mnemonic or raw hex seed to raw bytes,
+ *   importing seed bytes as a CryptoKey for use with deriveKek() (keyEnvelope.ts).
+ * - hexToBytes: parses a hex string into a Uint8Array.
+ */
+/**
+ * Resolves a BIP-39 mnemonic or raw hex seed to raw bytes.
+ * Implements EncryptionAdapter — pass an instance to DStorage config.
+ */
+declare class KeyDeriver {
+    private readonly input;
+    constructor(input: {
+        mnemonic?: string;
+        seedHex?: string;
+    });
+    /**
+     * Return the raw seed bytes.
+     * Import the result as a non-extractable HKDF CryptoKey before passing to deriveKek().
+     */
+    getSeed(): Promise<Uint8Array>;
+    /** Resolves and validates the seed as a Buffer. */
+    private getSeedBuffer;
+}
+declare function hexToBytes(hex: string, label?: string): Uint8Array<ArrayBuffer>;
+
+/**
+ * @dstorage/crypto — xchacha.ts
+ * Symmetric authenticated encryption using XChaCha20-Poly1305.
+ *
+ * Key derivation:
+ *   seed bytes (from EncryptionAdapter)
+ *     → HKDF-SHA-256 (domain-separated, optionally address-bound)
+ *     → 32-byte symmetric key (KEK)
+ *     → per-upload random DEK wrapped under KEK
+ *
+ * Why XChaCha20-Poly1305:
+ *   - 192-bit nonce eliminates birthday-bound collision risk —
+ *     safe to generate random nonces indefinitely
+ *   - Pure bytes in / bytes out — no WebCrypto CryptoKey ceremony
+ *   - Better performance on hardware without AES acceleration (mobile, ARM, IoT)
+ *
+ * Why a single symmetric key instead of a KEM keypair:
+ *   A KEM step would only add value if data needed to be
+ *   encrypted for a different recipient using their public key. For single-user
+ *   self-encryption where the same party encrypts and decrypts, HKDF → XChaCha20
+ *   is simpler, has much smaller ciphertext overhead, and provides equivalent
+ *   security. If cross-user encryption is required in the future the scheme
+ *   can be extended with a KEM layer at that point.
+ *
+ * On-chain storageId format (JSON):
+ *   Same envelope as off-chain payloads — handles arbitrary-length string IDs.
+ *   { ciphertext: base64, nonce: base64, algorithm: "XChaCha20-Poly1305" }
+ *
+ * Off-chain payload format (JSON):
+ *   { ciphertext: base64, nonce: base64, algorithm: "XChaCha20-Poly1305" }
+ */
+
+/** Encrypted payload stored off-chain (Arweave, etc.). All binary fields are base64. */
+interface XChaChaPayload {
+    /** base64 — XChaCha20-Poly1305 output: ciphertext || 16-byte Poly1305 tag */
+    ciphertext: string;
+    /** base64 — 24-byte random nonce */
+    nonce: string;
+    /** Algorithm identifier */
+    algorithm: "XChaCha20-Poly1305";
+}
+/**
+ * Derive a 32-byte symmetric key for XChaCha20-Poly1305 from arbitrary seed bytes.
+ *
+ * Uses HKDF-SHA-256 with a fixed global salt (domain separator) and a versioned,
+ * context-bound `info` string per RFC 5869:
+ *   - `salt`  = fixed application-level extraction key ("dstorage-xchacha-v1")
+ *   - `info`  = versioned label, optionally binding a wallet address
+ *
+ * @param seed     High-entropy seed bytes (wallet signature, BIP-39 seed, hex seed, etc.)
+ * @param context  Optional wallet address or other per-context binding value.
+ *                 Incorporated into `info` to bind the derived key to a specific account.
+ */
+declare function deriveSymmetricKeyFromSeed(seed: Uint8Array, context?: string): Promise<Uint8Array>;
+/**
+ * Encrypt arbitrary bytes with XChaCha20-Poly1305.
+ *
+ * Non-deterministic: fresh random 24-byte nonce per call.
+ *
+ * @param key   32-byte symmetric key from deriveSymmetricKeyFromSeed()
+ * @param data  Arbitrary plaintext bytes
+ * @param aad   Additional authenticated data bound to the ciphertext (recommended)
+ */
+declare function encryptXChaCha(key: Uint8Array, data: Uint8Array, aad?: Uint8Array): Promise<XChaChaPayload>;
+/**
+ * Decrypt a payload produced by encryptXChaCha().
+ * The `aad` must match exactly what was passed to encryptXChaCha() — the Poly1305
+ * auth tag covers the AAD, so any mismatch causes decryption to throw.
+ *
+ * @param key      32-byte symmetric key (must match the key used to encrypt)
+ * @param payload  XChaChaPayload from encryptXChaCha()
+ * @param aad      Must match the AAD used during encryption
+ * @throws If Poly1305 auth tag verification fails (wrong key, tampered data, or wrong AAD)
+ */
+declare function decryptXChaCha(key: Uint8Array, payload: XChaChaPayload, aad?: Uint8Array): Promise<Uint8Array>;
+/**
+ * Encrypt a 32-byte storage ID for on-chain storage.
+ *
+ * Output is exactly 72 bytes: [ nonce(24) | ciphertext(32) | auth-tag(16) ].
+ *
+ * @param key             32-byte symmetric key from deriveSymmetricKeyFromSeed()
+ * @param storageIdBytes  Raw 32-byte storage ID
+ */
+declare function encryptStorageIdXChaCha(key: Uint8Array, storageIdBytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decrypt a storage ID previously encrypted with encryptStorageIdXChaCha().
+ * Expects exactly 72 bytes.
+ * Throws if the Poly1305 auth tag does not match (tamper-evident).
+ *
+ * @param key             32-byte symmetric key (must match encryption key)
+ * @param encryptedBytes  72-byte on-chain payload
+ */
+declare function decryptStorageIdXChaCha(key: Uint8Array, encryptedBytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * Serialize an XChaChaPayload to a compact JSON string.
+ * Safe to pass to off-chain storage APIs.
+ */
+declare function serializeXChaChaPayload(payload: XChaChaPayload): string;
+/**
+ * Deserialize a JSON string back to an XChaChaPayload.
+ * Returns null if the input is invalid or missing required fields.
+ */
+declare function deserializeXChaChaPayload(raw: string): XChaChaPayload | null;
+/** XChaCha20-Poly1305 scheme. Key derived via HKDF-SHA-256. */
+declare class XChaChaScheme implements CryptoScheme {
+    readonly schemeName: "xchacha20poly1305-v1";
+    private readonly key;
+    private constructor();
+    /**
+     * Derive a 32-byte XChaCha20-Poly1305 key from seed bytes using HKDF-SHA-256.
+     *
+     * @param seed     High-entropy seed bytes (wallet signature, BIP-39 seed, etc.)
+     * @param context  Optional wallet address or other binding context.
+     *                 Incorporated into the HKDF salt to bind the key to a specific account.
+     */
+    static create(seed: Uint8Array, context?: string): Promise<XChaChaScheme>;
+    /**
+     * Create a scheme instance from a pre-generated key (e.g. a random DEK).
+     * Bypasses HKDF derivation — use when the key is already available.
+     *
+     * @param key  32-byte symmetric key
+     */
+    static fromKey(key: Uint8Array): XChaChaScheme;
+    encryptPayload(bytes: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;
+    decryptPayload(data: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;
+    encryptStorageId(storageId: string): Promise<string>;
+    decryptStorageId(encryptedId: string): Promise<string>;
+}
+
+/**
+ * @dstorage/crypto — keyEnvelope.ts
+ *
+ * Multi-key wrapping for Data Encryption Keys (DEKs).
+ *
+ * Each private upload generates a fresh random DEK, which is then wrapped
+ * (encrypted) under a Key Encryption Key (KEK) derived from the wallet seed.
+ * The wrapped DEK and its metadata are serialised as a JSON envelope and
+ * stored on-chain in the `keyEnvelope` field of ReferenceEntry.
+ *
+ * This separates the encryption key (random, unique per upload) from the
+ * key-protecting mechanism (wallet-bound), enabling future multi-recipient
+ * access without re-encrypting stored data — just add another wrapper entry.
+ *
+ * Envelope schema (private uploads only — public uploads have no envelope):
+ *   {
+ *     "v": 1,
+ *     "wrappers": [
+ *       {
+ *         "wrapKeyName": "password",      // identifies the wrapping key source
+ *         "algorithm": "xchacha20poly1305-v1",
+ *         "kekDerivation": "hkdf-sha256-v1",
+ *         "wrappedDek": "<base64url 96 chars>"
+ *       }
+ *     ]
+ *   }
+ *
+ * The ownerSecret for private uploads is derived deterministically from the wrapped DEK:
+ *   ownerSecret = HKDF-SHA256(ikm=DEK, salt=rawStorageId, info="dstorage:owner-secret:v1")
+ * Any holder of a valid KEK can unwrap the DEK and re-derive the ownerSecret.
+ *
+ * `wrappedDek` binary layout (72 bytes):
+ *   [ nonce(24) | ciphertext(32) | auth-tag(16) ]
+ * base64url-encoded → 96 chars — identical to the on-chain storageId layout.
+ */
+
+interface KeyWrapper extends WrappedDekResult {
+    /** Identifies the wrapping key source (e.g. "password", "mnemonic", "mlkem768"). */
+    wrapKeyName: string;
+}
+interface KeyEnvelope {
+    v: 1;
+    /**
+     * Wrappers for the data DEK (content encryption key). Always present in a valid envelope.
+     * The ownerSecret for ownership proofs is derived from the same DEK:
+     *   ownerSecret = HKDF-SHA256(DEK, rawStorageId, "dstorage:owner-secret:v1")
+     * Any holder of a valid KEK can unwrap the DEK and re-derive the ownerSecret.
+     * Public uploads have no envelope (keyEnvelope = "").
+     */
+    wrappers: [KeyWrapper, ...KeyWrapper[]];
+}
+/**
+ * Generate a cryptographically random 32-byte Data Encryption Key.
+ * Uses the platform CSPRNG (`crypto.getRandomValues`) — safe in both
+ * browser and Node.js 19+.
+ */
+declare function generateDek(): Uint8Array;
+/**
+ * Derive a 32-byte Key Encryption Key from a non-extractable HKDF CryptoKey.
+ *
+ * Callers must import their raw seed bytes via `crypto.subtle.importKey("raw", seed,
+ * "HKDF", false, ["deriveBits"])` before calling this function. Accepting only
+ * CryptoKey enforces that raw key material is never held in a JS-accessible heap
+ * variable at this call site.
+ *
+ * Uses the same salt as the data encryption key ("dstorage-xchacha-v1") but a
+ * distinct info string ("dstorage:xchacha20poly1305:kek:v1") to domain-separate
+ * the KEK from all other keys derived from the same seed.
+ *
+ * @param keyMaterial  Non-extractable HKDF CryptoKey imported from the seed.
+ * @param context      Optional wallet address or other binding context, incorporated
+ *                     into the info string to bind the KEK to a specific account.
+ */
+declare function deriveKek(keyMaterial: CryptoKey, context?: string): Promise<Uint8Array>;
+/**
+ * Wrap (encrypt) a 32-byte DEK under a KEK using XChaCha20-Poly1305.
+ *
+ * Reuses the same 72-byte binary layout as on-chain storageId encryption:
+ *   [ nonce(24) | ciphertext(32) | auth-tag(16) ]
+ * base64url-encoded → 96-char string.
+ *
+ * @param dek  32-byte Data Encryption Key to protect
+ * @param kek  32-byte Key Encryption Key (from deriveKek())
+ */
+declare function wrapKey(dek: Uint8Array, kek: Uint8Array): Promise<string>;
+/**
+ * Unwrap (decrypt) a wrapped DEK string back to the original 32-byte DEK.
+ *
+ * @param wrappedDek  base64url-encoded 96-char string from wrapKey()
+ * @param kek         32-byte Key Encryption Key (from deriveKek())
+ */
+declare function unwrapKey(wrappedDek: string, kek: Uint8Array): Promise<Uint8Array>;
+/**
+ * Derive a 32-byte owner secret from the data DEK and the raw storage ID.
+ *
+ * Derivation: HKDF-SHA-256(ikm=dek, salt=rawStorageId, info=OWNER_SECRET_DOMAIN)
+ *
+ * Security properties:
+ *   - Post-quantum resistant: HKDF-SHA-256 is purely symmetric (no elliptic-curve math).
+ *   - One-way: the DEK cannot be recovered from the ownerSecret (HKDF preimage resistance).
+ *   - Key-separated: the ownerSecret cannot be used for data encryption.
+ *   - Per-upload unique: different DEK + storageId per upload → different ownerSecret.
+ *   - Derivable: any holder of a valid KEK can unwrap the DEK and re-derive the ownerSecret.
+ *
+ * @param ikm           32-byte key material (DEK for private uploads; KEK for public uploads)
+ * @param rawStorageId  Raw storage network ID bytes (e.g. Arweave txId encoded as UTF-8)
+ * @param info          HKDF info / domain separator (defaults to private-upload domain)
+ */
+declare function deriveOwnerSecret(ikm: Uint8Array, rawStorageId: Uint8Array, info?: string): Promise<Uint8Array>;
+/**
+ * Build a v1 key envelope wrapping the data DEK under one or more KEKs.
+ *
+ * Each entry wraps the same random DEK under a different KEK (one per seed
+ * provider), allowing any of the corresponding recipients to independently
+ * decrypt the same content without re-encryption.
+ *
+ * The ownerSecret for ownership proofs is derived from the same DEK:
+ *   ownerSecret = HKDF-SHA256(DEK, rawStorageId, "dstorage:owner-secret:v1")
+ * No separate ownership key is needed.
+ *
+ * @param wrappers  Non-empty array of `{ wrappedDek, wrapKeyName }` pairs.
+ *                  `wrappedDek` is the base64url-encoded output of wrapKey().
+ *                  `wrapKeyName` is a caller-chosen label (e.g. "provider-0").
+ *
+ * @throws if `wrappers` is empty.
+ */
+declare function buildKeyEnvelope(wrappers: Array<KeyWrapper>): KeyEnvelope;
+/**
+ * Serialise a KeyEnvelope to the JSON string stored on-chain.
+ */
+declare function serializeKeyEnvelope(envelope: KeyEnvelope): string;
+/**
+ * Parse and validate a JSON string from the chain.
+ * Returns null for empty strings or malformed / unrecognised envelopes.
+ */
+declare function parseKeyEnvelope(raw: string): KeyEnvelope | null;
+/**
+ * Find a wrapper by its wrapKeyName. Returns null if not found.
+ */
+declare function findWrapper(envelope: KeyEnvelope, wrapKeyName: string): KeyWrapper | null;
+
+/**
+ * @dstorage/crypto — mlkem.ts
+ *
+ * Post-quantum DEK wrapping via ML-KEM (CRYSTALS-Kyber, NIST FIPS 203).
+ *
+ * Hybrid encryption pattern:
+ *   wrapDek:   ML-KEM encapsulate(PK) → sharedSecret → HKDF → KEK → XChaCha20 wraps DEK
+ *   unwrapDek: ML-KEM decapsulate(SK, ct) → sharedSecret → HKDF → KEK → XChaCha20 unwraps DEK
+ *
+ * This provides post-quantum confidentiality for the DEK:
+ *   - Only the holder of the Secret Key can recover the DEK.
+ *   - Encapsulation (upload) requires only the Public Key.
+ *   - A quantum computer cannot recover sharedSecret from the KEM ciphertext alone.
+ *
+ * Key sizes (variant mlkem768, NIST recommended):
+ *   Public key:  1184 bytes
+ *   Secret key:  2400 bytes
+ *   Ciphertext:  1088 bytes
+ *   Shared secret: 32 bytes
+ */
+
+type MLKemVariant = "mlkem512" | "mlkem768" | "mlkem1024";
+/**
+ * Generate a random ML-KEM keypair.
+ *
+ * @param variant  ML-KEM variant. Default: "mlkem768" (NIST recommended, 192-bit security).
+ */
+declare function mlkemGenerateKeypair(variant?: MLKemVariant): {
+    pk: Uint8Array;
+    sk: Uint8Array;
+};
+/**
+ * Generate a deterministic ML-KEM keypair from a 64-byte seed (d‖z, per FIPS 203).
+ * The same seed always produces the same keypair.
+ *
+ * Requires exactly 64 bytes — derive via Web Crypto HKDF deriveBits (512 bits) before calling.
+ *
+ * @param seed64   64-byte seed material
+ * @param variant  ML-KEM variant. Default: "mlkem768".
+ */
+declare function mlkemGenerateKeypairFromSeed(seed64: Uint8Array, variant?: MLKemVariant): {
+    pk: Uint8Array;
+    sk: Uint8Array;
+};
+/**
+ * Wrap a DEK under a ML-KEM public key.
+ *
+ * Encapsulates a shared secret, derives a KEK from it via HKDF, then wraps
+ * the DEK with the same XChaCha20-Poly1305 scheme used by symmetric providers.
+ * The KEM ciphertext is stored alongside the wrapped DEK so the holder of the
+ * secret key can reverse the process at retrieval time.
+ *
+ * @param dek      32-byte Data Encryption Key to protect
+ * @param pk       ML-KEM public key
+ * @param context  Domain-separation string bound into the KEK derivation
+ * @param variant  ML-KEM variant. Default: "mlkem768".
+ */
+declare function mlkemWrapDek(dek: Uint8Array, pk: Uint8Array, context: string, variant?: MLKemVariant): Promise<WrappedDekResult>;
+/**
+ * Unwrap a DEK from a ML-KEM wrapped DEK result.
+ *
+ * The ML-KEM variant is read from `data.algorithm` (e.g. "mlkem768-xchacha20poly1305-v1"),
+ * so the caller does not need to supply it — the key envelope is self-describing.
+ *
+ * @param data     WrappedDekResult containing algorithm, kemCiphertext, and wrappedDek
+ * @param sk       ML-KEM secret key
+ * @param context  Domain-separation string bound into the KEK derivation (must match
+ *                 the value used to wrap)
+ */
+declare function mlkemUnwrapDek(data: WrappedDekResult, sk: Uint8Array, context: string): Promise<Uint8Array>;
+
+/** BLAKE3 hash of `bytes`, returned as a raw 32-byte Uint8Array. */
+declare function computeBlake3(bytes: Uint8Array): Promise<Uint8Array>;
+/** BLAKE3 hash of `bytes`, returned as a 64-character lowercase hex string. */
+declare function computeBlake3Hex(bytes: Uint8Array): Promise<string>;
+
+/**
+ * @dstorage/chain — adapters/midnightSimulator.ts
+ *
+ * Midnight chain adapter backed by DataRegistrySimulator — runs the real
+ * DataRegistry Compact circuits in-process without requiring a live network,
+ * proof server, indexer, or wallet.
+ *
+ * Ownership is enforced by the real circuit (ownerSecret/ownerCommitment).
+ * RefIds are circuit-derived (not random UUIDs). State is per-instance (no
+ * shared module-level Map).
+ *
+ * ⚠️  Not for production: not decentralised, not immutable.
+ *     Replace with the real MidnightChainAdapter for production use.
+ */
+
+declare class MidnightSimulatorChainAdapter implements ChainAdapter {
+    readonly name: ChainProviderName;
+    readonly providerName: string;
+    readonly paymentAdapter: PaymentAdapter;
+    private readonly senderPk;
+    private simulatorPromise;
+    private readonly logger;
+    private blockHeight;
+    constructor(options?: {
+        /**
+         * Sender public key passed to the DataRegistrySimulator.
+         * Affects Zswap local state only — does not influence DataRegistry circuit
+         * ownership (which is controlled by ownerSecret).
+         * Defaults to a fixed all-zeros test key.
+         */
+        senderPk?: string;
+        logger?: ChainAdapterLogger;
+    } & ({
+        signingServerUrl: string;
+        authToken: string;
+    } | {
+        signingServerUrl?: never;
+        authToken?: never;
+    }));
+    private getSimulator;
+    estimateCost(): Promise<ChainQuote>;
+    writeReference(ref: ChainReference): Promise<ChainWriteResult>;
+    readReference(refId: string): Promise<ChainReference>;
+    listReferences(): Promise<DataReferenceSummary[]>;
+    removeReference(refId: string, ownerSecret?: Uint8Array): Promise<void>;
+    updateReference(refId: string, update: ChainReferenceUpdate, ownerSecret?: Uint8Array, newOwnerSecret?: Uint8Array): Promise<void>;
+    setContractAddress(_address: string): void;
+    getContractAddress(): string;
+    deployDataRegistry(): Promise<string>;
+}
+
+/**
+ * @dstorage/chain — adapters/httpGateway.ts
+ *
+ * HTTP Gateway chain adapter — delegates reference storage to a remote REST
+ * service. Useful for testing, staging environments, or custom backends that
+ * expose a simple HTTP API instead of a blockchain node.
+ */
+
+interface HttpGatewayChainAdapterConfig {
+    /** Scheme + host (+ optional port) shared by all endpoints. e.g. "http://localhost:3200" */
+    baseUrl: string;
+    /** Path appended to baseUrl for write (POST /{refId}) and update operations. e.g. "/api/refs" */
+    writePath: string;
+    /** Path appended to baseUrl for read (GET /{refId}) operations. */
+    readPath: string;
+    /** Path appended to baseUrl for listReferences (GET) operations. */
+    listPath: string;
+    /** Path appended to baseUrl for removeReference (DELETE /{refId}) operations. */
+    deletePath: string;
+    /**
+     * Optional headers included in every outgoing request.
+     * Useful for API tokens, authorization, or any other fixed headers required by
+     * the gateway. Example: `{ "Authorization": "Bearer mytoken", "X-Api-Key": "abc" }`
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional custom fetch implementation. Useful when the gateway uses a custom CA
+     * or client certificate: supply an undici Agent configured with the appropriate
+     * `ca`, `cert`, and `key` options. Defaults to `globalThis.fetch` when omitted.
+     */
+    customFetch?: typeof fetch;
+    logger?: ChainAdapterLogger;
+}
+declare class HttpGatewayChainAdapter implements ChainAdapter {
+    readonly name: ChainProviderName;
+    readonly providerName = "HTTP-Gateway-Chain-Adapter";
+    private readonly logger;
+    private readonly fetchFn;
+    private readonly extraHeaders;
+    private readonly writeUrl;
+    private readonly readUrl;
+    private readonly listUrl;
+    private readonly deleteUrl;
+    constructor(config: HttpGatewayChainAdapterConfig);
+    writeReference(ref: ChainReference): Promise<ChainWriteResult>;
+    updateReference(refId: string, update: ChainReferenceUpdate, _ownerSecret?: Uint8Array, _newOwnerSecret?: Uint8Array): Promise<void>;
+    readReference(refId: string): Promise<ChainReference>;
+    listReferences(): Promise<DataReferenceSummary[]>;
+    removeReference(refId: string, ownerSecret?: Uint8Array): Promise<void>;
+    getContractAddress(): string;
+    estimateCost(): Promise<ChainQuote>;
+}
+
+/**
+ * Minimal interface the adapter requires from a wallet provider passed via
+ * walletMode: "provider". Any object implementing WalletProvider and
+ * MidnightProvider with an accessible WalletFacade satisfies this.
+ */
+interface AdapterWalletProvider extends WalletProvider, MidnightProvider {
+    readonly wallet: WalletFacade;
+}
+
+/**
+ * @dstorage/chain — adapters/midnight.ts
+ *
+ * Midnight Network chain adapter.
+ *
+ * Uses DataRegistryAPI (deployContract / findDeployedContract / callTx) from
+ * @midnight-ntwrk/midnight-js-contracts via the api.ts wrapper, so that
+ * midnight.ts only needs to manage the wallet lifecycle and provider assembly.
+ *
+ * Wallet lifecycle:
+ *   - 'provider': accepts a pre-built wallet provider (Node.js CLI)
+ *   - 'connector': connect to browser wallet extension (browser dApp)
+ *
+ * Transaction flow (handled by DataRegistryAPI internally):
+ *   1. Build  — construct the unproven circuit call
+ *   2. Prove  — send to proof server for ZK proof generation
+ *   3. Balance — attach DUST fees via the connected wallet
+ *   4. Submit — broadcast to the Midnight node
+ *   5. Confirm — wait for block inclusion
+ *
+ * Docs: https://docs.midnight.network/develop/tutorial/building-a-dapp
+ */
+
+interface WalletAddresses {
+    unshielded: string;
+    shielded: string;
+    dust: string;
+}
+type SUPPORTED_NETWORKS = {
+    [K in "preprod" | "undeployed"]: EnvironmentConfiguration;
+};
+declare const NETWORKS: SUPPORTED_NETWORKS;
+/** Internal environment configuration passed to wallet SDK providers. */
+interface EnvironmentConfiguration {
+    networkId: string;
+    nodeHttp: string;
+    nodeWs: string;
+    indexerHttp: string;
+    indexerWs: string;
+    proofServer: string;
+    proofServerMaxRetries?: number;
+}
+interface BaseConfig {
+    /**
+     * Midnight node RPC endpoint.
+     */
+    nodeEndpoint?: string;
+    nodeWsEndpoint?: string;
+    /**
+     * Optional logger for SDK operational output.
+     * Pass `logger: console` to see all output, or inject your own logger.
+     * Omit to suppress all SDK log output.
+     */
+    logger?: ChainAdapterLogger;
+    /**
+     * Midnight indexer HTTP (GraphQL) endpoint for state queries.
+     */
+    indexerEndpoint?: string;
+    /**
+     * Midnight indexer WebSocket endpoint for real-time subscriptions.
+     */
+    indexerWsEndpoint?: string;
+    /**
+     * Proof server URL.
+     */
+    proofServerEndpoint: string;
+    /**
+     * Number of times to retry a proof-server circuit call on failure before
+     * giving up. Uses exponential backoff (1 s, 2 s, 4 s, …).
+     * Defaults to 3. Set to 1 to disable retries.
+     */
+    proofServerMaxRetries?: number;
+    /**
+     * On-chain address of an already-deployed DataRegistry contract.
+     * If omitted, sdk.init() will deploy a new contract and return its address.
+     */
+    contractAddress?: string;
+    /**
+     * Target network. Controls wallet networkId, address format, and fee overhead.
+     */
+    network: NetworkId;
+    /**
+     * Base URL of the dStorage managed payment signing server (no trailing slash).
+     * When provided, transaction balancing is delegated to the server instead of
+     * the local wallet.
+     */
+    signingServerUrl?: string;
+    /**
+     * Bearer token sent as the `Authorization` header to authenticate with the signing server.
+     * Required when `signingServerUrl` is provided.
+     */
+    authToken?: string;
+}
+type MidnightChainAdapterConfig = BaseConfig & ({
+    /**
+     * Provider mode: the caller builds, starts, syncs, and passes in a wallet provider.
+     * The adapter uses it directly without managing any wallet lifecycle.
+     * Use this mode for Node.js CLI apps (e.g., the dStorage console demo).
+     */
+    walletMode: "provider";
+    /**
+     * A fully initialised wallet provider (started and synced before passing in).
+     * Must implement AdapterWalletProvider (WalletProvider + MidnightProvider + .wallet).
+     */
+    walletProvider: AdapterWalletProvider;
+    /**
+     * LevelDB encryption password for the private state store.
+     * Must satisfy the policy: at least 3 of 4 character classes
+     * (uppercase, lowercase, digits, special characters).
+     * Recommended derivation: "Aa1!" + seedHex (all 4 classes guaranteed).
+     */
+    privateStatePassword: string;
+    /**
+     * Path to the directory that contains the compiled DataRegistry contract's ZK artifacts.
+     * Expected sub-directories:
+     *   ${zkArtifactsPath}/keys/${circuitId}.prover
+     *   ${zkArtifactsPath}/keys/${circuitId}.verifier
+     *   ${zkArtifactsPath}/zkir/${circuitId}.bzkir
+     *
+     * Required for write operations (storeReference, etc.) in provider mode.
+     */
+    zkArtifactsPath?: string;
+} | {
+    /**
+     * Browser wallet connector mode.
+     * Delegates all key management to the wallet extension (e.g., Midnight Lace).
+     */
+    walletMode: "connector";
+    /**
+     * Wallet connector name. Default: 'mnLace' (Midnight Lace).
+     * Example: window.midnight.mnLace
+     */
+    connectorName?: string;
+    /**
+     * Base URL from which the ZK artifacts for the DataRegistry contract are served.
+     * Must be an absolute http/https URL.
+     *
+     * In Vite apps: copy the compiled contract's keys/ and zkir/ directories
+     * to public/ and set this to window.location.origin.
+     *
+     * Required for write operations (storeReference, etc.) in connector mode.
+     */
+    zkConfigBaseUrl?: string;
+    /**
+     * Allow a proof server URL supplied by the wallet extension to override
+     * `proofServerEndpoint`. Default: `false`.
+     *
+     * When `false` (default): if the wallet returns a `proverServerUri` that differs
+     * from the configured endpoint, it is logged as a warning and ignored — the
+     * developer-configured endpoint is always used.
+     *
+     * Set to `true` only when you trust the connected wallet extension to supply a safe
+     * proof server (e.g. Midnight Lace in a controlled deployment). A compromised wallet
+     * extension can redirect ZK witness inputs — including the ownerSecret — to an
+     * attacker-controlled server, allowing reference takeover or deletion.
+     */
+    allowWalletProofServer?: boolean;
+});
+declare class MidnightChainAdapter implements ChainAdapter {
+    readonly name: ChainProviderName;
+    readonly providerName: string;
+    readonly managedPaymentAdapter: ManagedPaymentAdapter | null;
+    _lastPaymentReceipt: PaymentReceipt | undefined;
+    private facade;
+    private connectorAPI;
+    private addresses;
+    private connectorCoinPublicKey;
+    private connectorEncPublicKey;
+    private connectorIndexerHttp;
+    private connectorIndexerWs;
+    private connectorProofServer;
+    private readonly walletMode;
+    private readonly connectorName;
+    private readonly allowWalletProofServer;
+    private readonly logger;
+    private _contractAddress;
+    private _zkArtifactsPath;
+    private _zkConfigBaseUrl;
+    private _initialized;
+    private _api;
+    private _injectedWalletProvider;
+    private _injectedPrivateStatePassword;
+    private readonly config;
+    constructor(config: MidnightChainAdapterConfig);
+    /**
+     * If a payment adapter was set, it delegates wallet provider wrapping to
+     * the payment adapter, otherwise returns the provider unchanged (no wrapping needed).
+     * When the managed payment adaper is set, It wraps the wallet provider's balanceTx()
+     * to route transaction balancing through the managed signing server instead of the
+     * local wallet. The server receives the hex-serialized UnboundTransaction,
+     * balances and signs it, and returns the FinalizedTransaction in the receipt.
+     */
+    private _withProofRetry;
+    private _wrapPaymentProvider;
+    /**
+     * Build a mode-specific ZK config provider.
+     *
+     * Facade (Node.js): reads ZK artifact files from the local filesystem via zkArtifactsPath.
+     * Connector (browser): fetches ZK artifacts over HTTP via zkConfigBaseUrl.
+     */
+    private _buildZkConfigProvider;
+    /**
+     * midnight-js-contracts expects privateStateProvider.setContractAddress().
+     * Some providers (e.g. in-memory) do not implement it, so we add a no-op shim.
+     * Providers that already implement it (e.g. levelPrivateStateProvider) are left
+     * untouched — their real implementation must run so the contract address is set
+     * before any private state access.
+     */
+    private _withContractAddressShim;
+    /**
+     * Assemble DataRegistryProviders from mode-specific pieces.
+     */
+    private _assembleDataRegistryProviders;
+    /**
+     * Build providers for connector (browser) mode.
+     * Uses in-memory private state, FetchZkConfigProvider, and the Lace wallet connector API.
+     */
+    private _buildConnectorProviders;
+    /**
+     * Build DataRegistryProviders using a pre-built, already-started wallet provider.
+     * The caller is responsible for wallet construction, sync, and fund-waiting before
+     * passing the provider to the adapter via walletMode: "provider".
+     */
+    private _buildWalletProviderMode;
+    /**
+     * Lazily initialize and return the DataRegistryAPI.
+     * Joins the existing contract at the configured address.
+     * Throws if no address is configured and no deployment has occurred.
+     */
+    private _getAPI;
+    /** Midnight contract addresses are 32 bytes encoded as 64 lowercase hex chars. */
+    private static _validateContractAddress;
+    /**
+     * Set the contract address to use for subsequent operations.
+     * Resets the cached DataRegistryAPI so the next call re-joins at the new address.
+     */
+    setContractAddress(address: string): void;
+    /**
+     * Get the contract address
+     */
+    getContractAddress(): string;
+    /**
+     * List references currently stored in the joined/deployed DataRegistry contract.
+     * For Arweave references, storageId is the original txId string.
+     * For other providers, storageId is the hex of the stored Bytes<32>.
+     */
+    listReferences(): Promise<DataReferenceSummary[]>;
+    /**
+     * Look up a single reference by its refId.
+     * Returns { storageId, storageProvider } with the storageId decoded to the
+     * original storage network identifier (e.g. Arweave txId), or null if not found.
+     */
+    readReference(refId: string): Promise<ChainReference>;
+    estimateCost(): Promise<ChainQuote>;
+    writeReference(ref: ChainReference): Promise<ChainWriteResult>;
+    removeReference(refId: string, ownerSecret?: Uint8Array): Promise<void>;
+    /**
+     * Update the mutable fields of an existing reference.
+     *
+     * `update.storageId` is stored verbatim on-chain without format validation. Passing a
+     * malformed storageId permanently bricks the reference (silent decryption failure on read).
+     * Validate the format against the storage provider before calling this method.
+     */
+    updateReference(refId: string, update: ChainReferenceUpdate, ownerSecret?: Uint8Array, newOwnerSecret?: Uint8Array): Promise<void>;
+    /**
+     * Initialize the wallet.
+     * Branches based on wallet mode:
+     *   - 'facade': derive keys, build WalletFacade, wait for sync (Node.js CLI)
+     *   - 'connector': connect to browser wallet extension, extract addresses (browser dApp)
+     *
+     * Must be called before write operations or getBalances().
+     * All Midnight wallet SDK imports are dynamic to avoid hard build-time failures.
+     */
+    init(): Promise<string>;
+    /**
+     * Initialize in connector mode: connect to browser wallet extension.
+     *
+     * Discovers available wallets by enumerating window.midnight, as per the
+     * dApp connector spec: https://docs.midnight.network/api-reference/dapp-connector
+     */
+    private _initConnector;
+    /**
+     * Return wallet addresses derived during init().
+     * Throws if init() not yet called.
+     */
+    getAddresses(): WalletAddresses;
+    /**
+     * Read NIGHT and DUST balances.
+     */
+    getBalances(): Promise<WalletBalances>;
+}
+
+/**
+ * @dstorage/chain — adapters/midnight/sync.ts
+ *
+ * Wallet sync-waiting helper.
+ */
+
+/**
+ * Wait for a WalletFacade to report `isSynced`, falling back to the current
+ * facade state after `timeoutMs`.
+ *
+ * `isSynced` (and `waitForSyncedState()`) gate on an internal `isConnected` flag
+ * on the shielded/dust sub-wallets that only flips true once a non-empty batch of
+ * events arrives from the indexer — on a quiet chain (idle Preprod, fresh
+ * undeployed network) it can stay false forever even though the wallet has
+ * genuinely caught up, so waiting on it unconditionally can hang indefinitely.
+ */
+declare function waitForFacadeSync(facade: Pick<WalletFacade, "state">, timeoutMs?: number): Promise<FacadeState>;
+
+declare const EncryptionErrorCode: {
+    readonly KEYPAIR_MISSING_SECRET_KEY: 13001;
+    readonly MNEMONIC_TOO_SHORT: 13002;
+    readonly PASSWORD_UNSUPPORTED_KDF: 13003;
+    readonly PASSWORD_EMPTY_SALT: 13004;
+    readonly PASSWORD_UNKNOWN_PRESET: 13005;
+    readonly PASSWORD_TOO_SHORT: 13006;
+    readonly PASSWORD_TOO_FEW_DISTINCT: 13007;
+    readonly PASSWORD_SEQUENTIAL_RUN: 13008;
+    readonly PASSWORD_KEYBOARD_WALK: 13009;
+    readonly PASSWORD_ENTROPY_TOO_LOW: 13010;
+};
+type EncryptionErrorCode = (typeof EncryptionErrorCode)[keyof typeof EncryptionErrorCode];
+
+/**
+ * @dstorage/encryption — types.ts
+ *
+ * The EncryptionAdapter interface: the unified abstraction for how the
+ * dStorage SDK wraps and unwraps per-upload Data Encryption Keys (DEKs).
+ *
+ * Both symmetric (password, mnemonic) and asymmetric (ML-KEM) adapters implement
+ * this interface, so the core SDK calls wrapDek/unwrapDek uniformly with no
+ * knowledge of which algorithm is in use.
+ *
+ * The result of wrapDek() is stored as a KeyWrapper entry in the on-chain
+ * KeyEnvelope. At retrieval time, the same result is passed back to unwrapDek()
+ * to recover the DEK.
+ */
+
+/**
+ * Wraps and unwraps per-upload DEKs using adapter-specific key material.
+ *
+ * Implementations:
+ *   PasswordEncryptionAdapter  — symmetric: scrypt → HKDF → KEK → XChaCha20
+ *   MnemonicEncryptionAdapter  — symmetric: BIP-39 seed → HKDF → KEK → XChaCha20
+ *   KeypairEncryptionAdapter    — asymmetric: ML-KEM encapsulate/decapsulate + HKDF + XChaCha20
+ */
+interface EncryptionAdapter {
+    /** Stable identifier used as wrapKeyName in key envelopes. */
+    readonly name: string;
+    /**
+     * Wrap a DEK under this adapter's key material.
+     * Called once per upload, per adapter.
+     *
+     * @param dek  32-byte Data Encryption Key to protect
+     * @returns    WrappedDekResult to store in the on-chain key envelope
+     */
+    wrapDek(dek: Uint8Array): Promise<WrappedDekResult>;
+    /**
+     * Unwrap a DEK from a previously wrapped result.
+     * Called at retrieval time using the same result that wrapDek() returned.
+     *
+     * @param data  WrappedDekResult from the on-chain key envelope
+     * @returns     32-byte Data Encryption Key
+     * @throws      If the adapter's key material cannot decrypt the wrapped DEK
+     */
+    unwrapDek(data: WrappedDekResult): Promise<Uint8Array>;
+    /**
+     * Zero any raw key bytes held by this adapter and mark it unusable.
+     * Optional — only adapters holding raw byte arrays implement this.
+     * Call after the adapter is no longer needed to minimise the window
+     * during which secret key material sits in GC-reachable memory.
+     */
+    destroy?(): void;
+}
+
+declare class KeypairEncryptionAdapter implements EncryptionAdapter {
+    readonly name: string;
+    readonly publicKey: Uint8Array;
+    private secretKey;
+    private readonly variant;
+    private readonly context;
+    private constructor();
+    /**
+     * Upload-only adapter — holds only the Public Key.
+     * wrapDek() works normally; unwrapDek() throws (no SK available).
+     */
+    static fromPublicKey(pk: Uint8Array, context: string, variant?: MLKemVariant): KeypairEncryptionAdapter;
+    /**
+     * Full adapter — holds both Public Key and Secret Key.
+     * Both wrapDek() and unwrapDek() work.
+     */
+    static fromKeypair(pk: Uint8Array, sk: Uint8Array, context: string, variant?: MLKemVariant): KeypairEncryptionAdapter;
+    /**
+     * Generate a fresh random ML-KEM keypair.
+     *
+     * Returns the adapter (with both PK+SK) plus the raw keys so the caller
+     * can persist the secret key and share the public key separately.
+     *
+     * @param context  Domain-separation string bound into the KEK derivation
+     * @param variant  Default: "mlkem768".
+     */
+    static generateKeypair(context: string, variant?: MLKemVariant): {
+        adapter: KeypairEncryptionAdapter;
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+    /**
+     * Deterministically derive a ML-KEM keypair from a BIP-39 mnemonic phrase or hex seed.
+     *
+     * Delegates to MnemonicEncryptionAdapter.intoKeypairEncryptionAdapter() so all
+     * mnemonic/seed handling lives in a single place.
+     *
+     * Same inputs + variant always produce the same keypair.
+     *
+     * `seedHex` may be either 32 bytes (64 hex chars) or 64 bytes (128 hex chars) —
+     * both are expanded to the 64-byte ML-KEM seed via HKDF.
+     *
+     * @param input    { mnemonic } (24-word BIP-39) or { seedHex } (32- or 64-byte hex)
+     * @param context  Domain-separation string bound into the KEK derivation
+     * @param variant  Default: "mlkem768"
+     */
+    static fromMnemonic(input: {
+        mnemonic?: string;
+        seedHex?: string;
+    }, context: string, variant?: MLKemVariant): Promise<KeypairEncryptionAdapter>;
+    /**
+     * Deterministically derive a ML-KEM keypair from a password and salt.
+     *
+     * Delegates to PasswordEncryptionAdapter.intoKeypairEncryptionAdapter() so all
+     * password handling (scrypt params, entropy validation, 64-byte seed derivation)
+     * lives in a single place.
+     *
+     * Same password + salt + variant always produces the same keypair.
+     *
+     * @param password  User password (validated for entropy)
+     * @param salt      Domain salt — must not be empty
+     * @param context   Domain-separation string bound into the KEK derivation
+     * @param variant   Default: "mlkem768"
+     * @param params    Optional custom scrypt params
+     */
+    static fromPassword(password: string, salt: string, context: string, variant?: MLKemVariant, params?: {
+        N?: number;
+        r?: number;
+        p?: number;
+    }): Promise<KeypairEncryptionAdapter>;
+    /**
+     * Zero the Secret Key bytes and mark this adapter as read-only.
+     * Call when the adapter is no longer needed to minimise the window
+     * during which raw ML-KEM key material sits in GC-reachable memory.
+     * After destroy(), unwrapDek() will throw.
+     */
+    destroy(): void;
+    wrapDek(dek: Uint8Array): Promise<WrappedDekResult>;
+    unwrapDek(data: WrappedDekResult): Promise<Uint8Array>;
+}
+
+declare class MnemonicEncryptionAdapter implements EncryptionAdapter {
+    readonly name = "mnemonic";
+    /**
+     * Non-extractable HKDF CryptoKey imported from the BIP-39 / hex seed.
+     * Raw seed bytes are zeroed immediately after import.
+     */
+    private readonly kekMaterialPromise;
+    constructor(input: {
+        mnemonic?: string;
+        seedHex?: string;
+    });
+    wrapDek(dek: Uint8Array): Promise<WrappedDekResult>;
+    unwrapDek({ wrappedDek }: WrappedDekResult): Promise<Uint8Array>;
+    /**
+     * Deterministically derive a ML-KEM keypair from this adapter's key material.
+     *
+     * Uses Web Crypto HKDF to derive a 64-byte ML-KEM seed from the stored
+     * CryptoKey with info="dstorage:mlkem-seed:v1", domain-separated from the
+     * symmetric KEK derivation path. The same derivation applies to all seed
+     * types (mnemonic or hex), producing consistent, domain-separated keypairs.
+     *
+     * @param context  Domain-separation string bound into the KEK derivation
+     * @param variant  ML-KEM variant. Default: "mlkem768".
+     */
+    intoKeypairEncryptionAdapter(context: string, variant?: MLKemVariant): Promise<KeypairEncryptionAdapter>;
+}
+
+/**
+ * Named scrypt parameter presets. Use these at construction time as a
+ * convenience — they expand to concrete N/r/p values. For persistence,
+ * always store the actual values from `getKdfParams()`, not the preset name.
+ *
+ * "v1"      — N=131072, 128 MB, ~500ms–1s  — OWASP-recommended minimum.
+ *             Use for all sensitive data (default).
+ * "v1-lite" — N=65536,  64 MB,  ~200–400ms — half the work factor of "v1".
+ *             An offline attacker needs half the resources to brute-force the
+ *             same password. Use only on memory-constrained devices (mobile,
+ *             low-RAM embedded). Prefer "v1" whenever the environment allows.
+ */
+declare const KDF_PRESETS: {
+    readonly v1: {
+        readonly N: 131072;
+        readonly r: 8;
+        readonly p: 1;
+    };
+    readonly "v1-lite": {
+        readonly N: 65536;
+        readonly r: 8;
+        readonly p: 1;
+    };
+};
+type KdfPreset = keyof typeof KDF_PRESETS;
+/**
+ * The resolved scrypt parameters to store alongside encrypted data.
+ * Interoperable: any scrypt implementation in any language can re-derive
+ * the key from these values without knowledge of this SDK's preset names.
+ */
+interface StoredKdfParams {
+    /** Always "scrypt" — identifies the KDF algorithm. */
+    kdf: "scrypt";
+    N: number;
+    r: number;
+    p: number;
+}
+interface PasswordEncryptionAdapterConfig {
+    /** The user's password. Validated for entropy at construction time. */
+    password: string;
+    /**
+     * Domain salt — REQUIRED, must not be empty.
+     *
+     * Recommended: an app-specific label combined with a per-user identifier,
+     * e.g. `"myapp:v1:alice@example.com"` or `"myapp:v1:" + tenantId`.
+     *
+     * Using a string is convenient; it is UTF-8 encoded before use.
+     * Pass a Uint8Array if you prefer raw bytes.
+     *
+     * Same password + same salt → same seed, forever. Different salts produce
+     * independent seeds even for identical passwords.
+     */
+    salt: string | Uint8Array;
+    /**
+     * Named scrypt preset. Controls N/r/p parameters.
+     * Default: "v1" (N=131072, 128 MB, ~500ms–1s).
+     *
+     * Takes precedence over `params` when both are provided.
+     * Preset names are convenience shorthands — use `getKdfParams()` to get
+     * the actual values for storage.
+     */
+    preset?: KdfPreset;
+    /**
+     * Custom scrypt parameters. Only used when `preset` is not provided.
+     * Prefer `preset` for well-known configurations.
+     */
+    params?: {
+        N?: number;
+        r?: number;
+        p?: number;
+    };
+    /**
+     * Minimum password length. Default: 12 characters.
+     */
+    minPasswordLength?: number;
+    /**
+     * Minimum estimated entropy in bits (charset-based estimate). Default: 60 bits.
+     *
+     * The built-in estimator uses character pool size × length. It catches trivially
+     * weak passwords but does not detect dictionary words. Use `additionalValidators`
+     * for higher assurance.
+     */
+    minEntropyBits?: number;
+    /**
+     * Optional additional password validator functions. Each receives the password
+     * and should throw an Error with a helpful message if the password is rejected.
+     * Run after the built-in checks. Useful for integrating zxcvbn or a blacklist.
+     *
+     * @example
+     * additionalValidators: [(pw) => {
+     *   if (zxcvbn(pw).score < 3) throw new Error("Password is too common.");
+     * }]
+     */
+    additionalValidators?: Array<(password: string) => void>;
+}
+/** Config for `PasswordEncryptionAdapter.fromKdfParams()` — reconstructs from stored metadata. */
+interface FromKdfParamsConfig extends StoredKdfParams {
+    password: string;
+    salt: string | Uint8Array;
+    minPasswordLength?: number;
+    minEntropyBits?: number;
+    additionalValidators?: Array<(password: string) => void>;
+}
+declare class PasswordEncryptionAdapter implements EncryptionAdapter {
+    readonly name = "password";
+    private readonly salt;
+    private readonly N;
+    private readonly r;
+    private readonly p;
+    /**
+     * Non-extractable HKDF CryptoKey imported from the scrypt output.
+     * The raw scrypt bytes are zeroed immediately after import; this handle is
+     * the only in-memory representation of the secret from this point on.
+     */
+    private readonly kekMaterialPromise;
+    constructor(config: PasswordEncryptionAdapterConfig);
+    /**
+     * Reconstruct an adapter from parameters previously stored via `getKdfParams()`.
+     * Use this when loading existing encrypted data — ensures the exact same N/r/p
+     * are used regardless of what the current SDK defaults are.
+     *
+     * @example
+     * const adapter = PasswordEncryptionAdapter.fromKdfParams({
+     *   password,
+     *   salt: meta.salt,
+     *   kdf: meta.kdf,
+     *   N: meta.N,
+     *   r: meta.r,
+     *   p: meta.p,
+     * });
+     */
+    static fromKdfParams(config: FromKdfParamsConfig): PasswordEncryptionAdapter;
+    /**
+     * Returns the resolved KDF parameters to store alongside encrypted data.
+     *
+     * These values are language- and SDK-agnostic: any scrypt implementation
+     * can re-derive the key from `{ kdf, N, r, p }` + the original salt and
+     * password, without any knowledge of this SDK's preset names.
+     *
+     * @example
+     * const meta = {
+     *   ...adapter.getKdfParams(),  // { kdf: "scrypt", N: 131072, r: 8, p: 1 }
+     *   salt: "myapp:alice@example.com",
+     * };
+     * await db.save({ encryptedData, meta });
+     */
+    getKdfParams(): StoredKdfParams;
+    wrapDek(dek: Uint8Array): Promise<WrappedDekResult>;
+    unwrapDek({ wrappedDek }: WrappedDekResult): Promise<Uint8Array>;
+    /**
+     * Deterministically derive a ML-KEM keypair from this adapter's key material.
+     *
+     * Uses Web Crypto HKDF to derive a 64-byte ML-KEM seed from the stored
+     * CryptoKey, domain-separated from the symmetric KEK derivation path with
+     * info="dstorage:mlkem-seed:v1". This is equivalent to noble's
+     * hkdf(sha256, scryptOutput, undefined, info, 64) but avoids materialising
+     * the raw scrypt output in a JS-accessible variable.
+     *
+     * Same password + salt + variant always produces the same keypair.
+     *
+     * @param context  Domain-separation string bound into the KEK derivation
+     * @param variant  ML-KEM variant. Default: "mlkem768".
+     */
+    intoKeypairEncryptionAdapter(context: string, variant?: MLKemVariant): Promise<KeypairEncryptionAdapter>;
+}
+/**
+ * Generate a cryptographically random password suitable for use with
+ * `PasswordEncryptionAdapter` when post-quantum-safe key derivation is required.
+ *
+ * Produces 32 random bytes (256 bits of real entropy) encoded as a 43-character
+ * base64url string. When combined with `intoKeypairEncryptionAdapter()`, this
+ * provides a fully recoverable path to ML-KEM 192-bit post-quantum security:
+ * the password is the only secret needed to re-derive the same ML-KEM keypair
+ * on any device, without storing the private key itself.
+ *
+ * @example
+ * const password = generatePqsPassword(); // store this securely
+ * const adapter = new PasswordEncryptionAdapter({ password, salt: "myapp:alice" });
+ * const keypairAdapter = await adapter.intoKeypairEncryptionAdapter("myapp:v1");
+ * await sdk.connect(keypairAdapter); // full 192-bit PQ security
+ */
+declare function generatePqsPassword(): string;
+
+/**
+ * @dstorage/core — types.ts
+ * Top-level types for the dStorage SDK public API.
+ */
+
+/**
+ * Minimal logger interface accepted by every SDK class.
+ * Compatible with `console` — pass `logger: console` for zero-boilerplate logging.
+ * Omit the field entirely to suppress all SDK output.
+ */
+interface Logger {
+    log(component: string, msg: string): void;
+    warn(component: string, msg: string): void;
+    error(component: string, msg: string): void;
+    debug?(component: string, msg: string): void;
+}
+/** Wallet connection info returned after connecting */
+interface WalletInfo {
+    address: string;
+    chainProvider: ChainProviderName;
+    /** The raw signature (or PBKDF2 seed) used to derive the encryption key (kept in memory only) */
+    _signatureHex: string;
+}
+/** Configuration passed to dStorage constructor */
+interface DStorageConfig {
+    /** Storage adapter to use (MockStorageAdapter | ArweaveStorageAdapter | ...) */
+    storageAdapter: StorageAdapter;
+    /**
+     * Chain adapter to use (MockChainAdapter | MidnightChainAdapter | ...).
+     * When omitted the SDK operates in storage-only mode — uploads store to the
+     * storage backend but no on-chain reference is written.
+     */
+    chainAdapter?: ChainAdapter;
+    /**
+     * Encryption adapters that wrap and unwrap per-upload Data Encryption Keys (DEKs).
+     * Each adapter produces an independent wrapped DEK; any of them can independently decrypt.
+     *
+     * Choose the adapter(s) preferred by the user:
+     *   PasswordEncryptionAdapter  — scrypt-derived from a user password + salt
+     *   MnemonicEncryptionAdapter  — BIP-39 mnemonic or hex seed (Node.js / facade mode)
+     *   KeypairEncryptionAdapter   — post-quantum asymmetric (ML-KEM keypair)
+     *
+     * When omitted or empty, no encryption key is available and all uploaded data
+     * will be stored as plaintext (public).
+     *
+     * @example
+     * // Single adapter (most common)
+     * encryptionAdapters: [new PasswordEncryptionAdapter({ password, salt })]
+     *
+     * @example
+     * // Two adapters — data accessible by either password or mnemonic
+     * encryptionAdapters: [
+     *   new PasswordEncryptionAdapter({ password, salt }),
+     *   new MnemonicEncryptionAdapter({ mnemonic }),
+     * ]
+     */
+    encryptionAdapters?: EncryptionAdapter[];
+    /**
+     * Optional logger for SDK operational output.
+     * Pass `logger: console` to see all output, or inject your own logger.
+     * Omit to suppress all SDK log output.
+     */
+    logger?: Logger;
+}
+/**
+ * Payload included in both `StorePartialError.recovery` and the `"stored"`
+ * phase of `StoreProgress`. Contains enough information to retry a failed
+ * chain write via `registerReference()` without re-uploading.
+ *
+ * `keyEnvelope` is the DEK encrypted under the user's KEK — safe to persist
+ * (e.g. in localStorage or a database). It is `undefined` for public uploads
+ * since their on-chain reference does not depend on a content DEK.
+ */
+interface StoreRecovery {
+    storageId: string;
+    /** Storage provider that holds the content — required by registerReference(). */
+    storageProvider: StorageProviderName;
+    keyEnvelope: string | undefined;
+    /**
+     * BLAKE3 hash of the ciphertext bytes stored at `storageId`, hex-encoded (64 chars).
+     * Pass to `registerReference()` to preserve the on-chain integrity check on the recovered reference.
+     */
+    contentHash?: string;
+}
+interface StoreProgress {
+    phase: "encrypting" | "uploading" | "stored" | "finalizing";
+    chunksUploaded: number;
+    totalChunks: number;
+    bytesUploaded: number;
+    totalBytes: number;
+    /**
+     * Present when `phase === "stored"`. Fired after the storage write succeeds
+     * and before the chain write begins — persist this to recover from a partial
+     * failure without re-uploading.
+     */
+    recovery?: StoreRecovery;
+}
+interface StoreOptions {
+    /**
+     * Unencrypted key/value tags forwarded to the storage layer (e.g. Arweave tx tags).
+     * Never written on-chain.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Encrypted key/value metadata stored on-chain alongside the key envelope.
+     * Encrypted with the content DEK — only holders of a valid KEK can read it.
+     * Returned in `RetrieveResult.metadata` after decryption.
+     * Not supported for public (`isPublic: true`) stores.
+     */
+    metadata?: Record<string, string>;
+    onProgress?: (progress: StoreProgress) => void;
+    /** When true, content is stored unencrypted and the storageId is written on-chain as plaintext. */
+    isPublic?: boolean;
+    /**
+     * Optional caller-supplied reference ID, forwarded to the chain adapter as
+     * {@link ChainReference.refId}. Adapters that control their own ID generation
+     * (e.g. mock, HTTP gateway) use this as the stored and returned identifier.
+     * Adapters where the on-chain protocol determines the ID (e.g. Midnight)
+     * ignore this field — the chain-assigned ID is returned instead.
+     */
+    refId?: string;
+}
+/**
+ * Aggregated cost estimate for a complete store operation.
+ * Built from two quotes — one from the storage adapter and one from the chain adapter.
+ */
+interface CostEstimate {
+    storageCost: {
+        amount: string;
+        token: TokenSymbol;
+    };
+    /** Chain cost. Undefined when no chain adapter is configured. */
+    chainCost?: {
+        amount: string;
+        token: TokenSymbol;
+    };
+    /** File size in bytes */
+    fileSizeBytes: number;
+}
+/** Result returned from dStorage.store() */
+interface StoreResult {
+    /**
+     * The primary on-chain reference ID.
+     * Undefined when no chain adapter is configured (storage-only mode).
+     */
+    chainRefId?: string;
+    /** The storage network content ID */
+    storageId: string;
+    /** Storage provider used */
+    storageProvider: StorageProviderName;
+    /** Chain provider used. Undefined when no chain adapter is configured. */
+    chainProvider?: ChainProviderName;
+    /** Timestamp */
+    uploadedAt: number;
+    /**
+     * Encryption algorithm used for the stored data and on-chain storageId.
+     * "xchacha20poly1305-v1" for private (encrypted) stores.
+     * Empty string ("") for public (unencrypted) stores.
+     */
+    encryptionScheme: string;
+    /**
+     * Decryption scheme for the stored content.
+     * Present only for private stores in storage-only mode (no chainAdapter).
+     * In chain mode the scheme is recoverable from the on-chain key envelope instead.
+     * Pass this back to retrieveByStorageId() to decrypt locally.
+     */
+    cryptoScheme?: CryptoScheme;
+    /** Estimated cost of the store operation */
+    costEstimate: CostEstimate;
+}
+/** Options for dStorage.listReferences() */
+interface ListReferencesOptions {
+    /** When provided, only references whose refId appears in this array are returned. */
+    refIds?: string[];
+}
+/** Options for dStorage.registerReference() */
+interface RegisterReferenceOptions {
+    /** The pre-existing storage network ID to register. Omit for metadata-only references. */
+    storageId?: string;
+    /**
+     * Storage provider name recorded in the chain reference.
+     * Defaults to the configured `storageAdapter.name`.
+     */
+    storageProvider?: StorageProviderName;
+    /**
+     * Optional caller-supplied reference ID, forwarded to the chain adapter as
+     * {@link ChainReference.refId}. Adapters that control their own ID generation
+     * (e.g. mock, HTTP gateway) use this as the stored and returned identifier.
+     * Adapters where the on-chain protocol determines the ID (e.g. Midnight)
+     * ignore this field — the chain-assigned ID is returned instead.
+     */
+    refId?: string;
+    /**
+     * Encrypted key/value metadata stored on-chain alongside the key envelope.
+     * Encrypted with the content DEK — only holders of a valid KEK can read it.
+     * Returned in `RetrieveResult.metadata` after decryption via retrieveByRefId().
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Recovery: the `keyEnvelope` from a `StorePartialError` (or from the
+     * `"stored"` phase of `onProgress`). When provided, the DEK is unwrapped
+     * from this envelope and used to encrypt the storageId and derive the
+     * ownerSecret — producing a reference identical to what `store()` would have
+     * written, without requiring a re-upload.
+     */
+    keyEnvelope?: string;
+    /**
+     * BLAKE3 hash of the ciphertext bytes at `storageId`, hex-encoded (64 chars).
+     * When passed from `StorePartialError.recovery.contentHash`, this ensures the
+     * recovered reference carries the same on-chain hash as a normal `store()` write.
+     */
+    contentHash?: string;
+}
+/** Result returned from dStorage.registerReference() */
+interface RegisterReferenceResult {
+    /** The on-chain reference ID — use with retrieveByRefId(). */
+    chainRefId: string;
+}
+/** Result returned from dStorage.update() */
+interface UpdateResult {
+    /** Same refId as the input — updated in place. */
+    chainRefId: string;
+    /** StorageId of the newly stored content. */
+    storageId: string;
+}
+/** Result returned from dStorage.retrieveByRefId() / retrieveByStorageId() */
+interface RetrieveResult {
+    /** The raw decrypted bytes */
+    bytes: Uint8Array;
+    /** Decrypted on-chain metadata (empty when none was provided at upload time or when retrieved without a chain reference) */
+    metadata: Record<string, string>;
+    /** Unencrypted tags attached to the storage-layer upload (e.g. Arweave tx tags) */
+    tags: Record<string, string>;
+}
+/** AAD for single-shot payload encryption (non-chunked user content). */
+declare const PAYLOAD_AAD: Uint8Array;
+/**
+ * AAD for chunked manifest encryption.
+ * Using a distinct label from PAYLOAD_AAD means a ciphertext produced for a
+ * manifest cannot decrypt successfully under PAYLOAD_AAD and vice versa —
+ * manifest detection is cryptographic, not based on JSON shape inspection.
+ */
+declare const MANIFEST_AAD: Uint8Array;
+/** AAD for encrypted on-chain metadata (stored in ChainReference.encryptedMetadata). */
+declare const METADATA_AAD: Uint8Array;
+/**
+ * HKDF salt for ownerSecret derivation in metadata-only references (no storageId).
+ * Using a fixed non-empty sentinel avoids RFC 5869's empty-salt substitution
+ * (which silently substitutes zeros(32)) and creates a clear domain boundary
+ * from normal-upload ownerSecrets whose salt is the plaintext storageId.
+ */
+declare const METADATA_ONLY_OWNER_SECRET_SALT: Uint8Array;
+/**
+ * Per-chunk AAD that binds a ciphertext to its position in a chunked upload.
+ * A malicious gateway swapping two chunks will produce an AEAD auth failure
+ * because the stored AAD won't match the expected index.
+ */
+declare const chunkAad: (index: number, total: number) => Uint8Array;
+
+/**
+ * @dstorage/core — metaTx/types.ts
+ *
+ * All public interfaces and type aliases for the MetaTx orchestrator.
+ */
+
+type MetaTxStepId = "estimate" | "encrypt" | "payment_storage" | "upload" | "chain_reference" | "complete";
+type MetaTxStepStatus = "pending" | "running" | "done" | "error";
+interface MetaTxStepState {
+    id: MetaTxStepId;
+    label: string;
+    description: string;
+    status: MetaTxStepStatus;
+    /** Live detail message updated during the step */
+    detail?: string;
+    /** Duration in ms (set when done) */
+    durationMs?: number;
+    startedAt?: number;
+}
+interface MetaTxProgress {
+    steps: MetaTxStepState[];
+    currentStepId: MetaTxStepId | null;
+    overallStatus: "idle" | "awaiting_confirmation" | "running" | "complete" | "error";
+    /** Cost estimate — set after 'estimate' step completes */
+    estimate?: CostEstimate;
+    /** Final receipt — set when complete */
+    receipt?: MetaTxReceipt;
+    /** Error message if overallStatus is 'error' */
+    error?: string;
+}
+interface MetaTxReceipt {
+    dataId: string;
+    storageId: string;
+    /** Undefined when no chain adapter is configured (storage-only mode). */
+    chainRefId?: string;
+    /** Original file info */
+    file: {
+        name: string;
+        type: string;
+        sizeBytes: number;
+    };
+    /** Payment receipts */
+    storagePayment: PaymentReceipt;
+    /** Undefined when no chain adapter is configured. */
+    chainPayment?: PaymentReceipt;
+    /** Tokens used */
+    storageToken: TokenSymbol;
+    /** Undefined when no chain adapter is configured. */
+    chainToken?: TokenSymbol;
+    /** Contract invoked (if selected) */
+    contract?: {
+        address: string;
+        name: string;
+    };
+    completedAt: number;
+    /** Duration of the full meta-transaction in ms */
+    totalDurationMs: number;
+}
+interface MetaTxConfig {
+    /** Optional metadata to attach to the on-chain reference */
+    metadata?: Record<string, string>;
+    /** Selected contract address (from the contract registry) */
+    contractAddress?: string;
+    /** Selected contract name (for display / receipt) */
+    contractName?: string;
+}
+/**
+ * Crypto materials for a single upload: a fresh random DEK wrapped in a
+ * key envelope, ready to encrypt payload and storageId.
+ *
+ * For private uploads: uploadScheme encrypts content; dek is the per-upload
+ * Data Encryption Key used both to encrypt content AND to derive
+ * ownerSecret = HKDF(dek, rawStorageId). Any KEK holder can re-derive the
+ * ownerSecret by unwrapping the envelope DEK.
+ * For public uploads: uploadScheme is null; ownerSeed is a random secret wrapped
+ * under every KEK in keyEnvelope, and ownerSecret = HKDF(ownerSeed, rawStorageId).
+ * Any single KEK holder can re-derive the ownerSecret by unwrapping the envelope.
+ */
+interface UploadCrypto {
+    /** XChaChaScheme built from a fresh random DEK. null for public uploads. */
+    uploadScheme: CryptoScheme | null;
+    /** JSON-encoded KeyEnvelope wrapping the DEK (private) or ownerSeed (public) under every KEK. */
+    keyEnvelope: string;
+    /** Encryption scheme identifier to record on-chain. "" for public uploads. */
+    encryptionScheme: EncryptionScheme;
+    /**
+     * The raw per-upload DEK for private uploads; undefined for public uploads.
+     * Used by MetaTx to derive ownerSecret = HKDF(dek, rawStorageId) after upload.
+     * Not stored anywhere — must not be persisted.
+     */
+    dek?: Uint8Array;
+    /**
+     * The raw ownerSeed for public uploads; undefined for private uploads.
+     * Used by MetaTx to derive ownerSecret = HKDF(ownerSeed, rawStorageId) after upload.
+     * Not stored anywhere — must not be persisted.
+     */
+    ownerSeed?: Uint8Array;
+}
+/**
+ * Minimal SDK surface required by MetaTx.
+ * Implemented by DStorage — MetaTx receives the SDK instance directly
+ * rather than individual adapters/keys/address to avoid redundant constructor args.
+ */
+interface DStorageContext {
+    readonly storageAdapter: StorageAdapter;
+    readonly chainAdapter: ChainAdapter | undefined;
+    /** Wallet address of the connected user, or null if using init() / facade mode. */
+    readonly connectedAddress: string | null;
+    /**
+     * Generate a fresh random DEK, wrap it under the KEK, and return the
+     * upload crypto materials needed to encrypt payload and storageId.
+     * @param isPublic  Pass true to skip encryption (returns null scheme + no envelope).
+     */
+    prepareUploadCrypto(isPublic?: boolean): Promise<UploadCrypto>;
+    /** Estimate the full cost (storage + chain) for a given payload size. */
+    estimateCost(sizeBytes: number): Promise<CostEstimate>;
+}
+
+/**
+ * @dstorage/core — metaTx/utils.ts
+ *
+ * Helpers used internally by MetaTx and one exported utility.
+ */
+
+/**
+ * Return the default chain payment token for a given chain provider name.
+ */
+declare function defaultChainToken(chainProvider: string): TokenSymbol;
+
+/**
+ * @dstorage/core — metaTx/MetaTx.ts
+ *
+ * The MetaTx orchestrator.
+ *
+ * Presents a single conceptual action to the user while internally executing:
+ *   [0] Estimate   → compute storage + chain costs
+ *   [1] Encrypt    → XChaCha20-Poly1305 encrypt the file client-side
+ *   [2] PayStorage → simulate storage payment (AR / MOCK)
+ *   [3] Upload     → upload encrypted blob to decentralised storage
+ *   [4] Reference  → pay chain fee + write CID + metadata reference on-chain
+ *   [✓] Complete   → return full receipt
+ *
+ * Usage:
+ *   const metaTx = new MetaTx(dStorage);
+ *   metaTx.onProgress((progress) => updateUI(progress));
+ *   const receipt = await metaTx.execute(file);
+ */
+
+declare class MetaTx {
+    private sdk;
+    private progressCallback;
+    private steps;
+    private startedAt;
+    constructor(sdk: DStorageContext);
+    /** Register a progress listener. Called after every step state change. */
+    onProgress(cb: (progress: MetaTxProgress) => void): this;
+    execute(file: File, config?: MetaTxConfig): Promise<MetaTxReceipt>;
+    private startStep;
+    private updateStepDetail;
+    private completeStep;
+    private getStep;
+    private emit;
+}
+
+/**
+ * @dstorage/core — dStorage.ts
+ *
+ * The main SDK class. Orchestrates:
+ *   1. Encryption adapter key wrapping (@dstorage/encryption + @dstorage/crypto)
+ *   2. Client-side encryption         (@dstorage/crypto)
+ *   3. Decentralised storage          (@dstorage/storage)
+ *   4. On-chain reference writing     (@dstorage/chain)
+ *
+ * Developer API:
+ *   const ds = new DStorage(config);
+ *   await ds.init();
+ *   const { chainRefId, storageId } = await ds.store(new TextEncoder().encode("hello"));
+ *   const { bytes } = await ds.retrieveByRefId(chainRefId);
+ *   await ds.listReferences();
+ *   await ds.removeReference(chainRefId);
+ */
+
+declare class DStorage implements DStorageContext {
+    private config;
+    private wallet;
+    /** Encryption adapters — each wraps/unwraps per-upload DEKs using its own algorithm. */
+    private _encryptionProviders;
+    private _initialized;
+    private readonly logger;
+    constructor(config: DStorageConfig);
+    get storageAdapter(): StorageAdapter;
+    get chainAdapter(): ChainAdapter | undefined;
+    /**
+     * 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.
+     */
+    init(): Promise<string | undefined>;
+    /** Tear down active state and clear all in-memory key material. */
+    destroy(): void;
+    get isConnected(): boolean;
+    get connectedAddress(): string | null;
+    /**
+     * 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
+     */
+    store(bytes: Uint8Array, options?: StoreOptions): Promise<StoreResult>;
+    /**
+     * 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.
+     */
+    registerReference(options?: RegisterReferenceOptions): Promise<RegisterReferenceResult>;
+    /**
+     * Store new content and update an existing on-chain reference in place.
+     *
+     * 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.
+     *
+     * Note: chunking is not applied here. For large files use store() to get a
+     * new chunked reference, then removeReference() on the old one.
+     *
+     * @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.
+     */
+    update(refId: string, bytes: Uint8Array, options?: StoreOptions): Promise<UpdateResult>;
+    /**
+     * 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.
+     */
+    retryUpdate(refId: string, recovery: StoreRecovery): Promise<UpdateResult>;
+    /**
+     * 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.
+     */
+    rotateKeys(refId: string): Promise<void>;
+    /**
+     * 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()
+     */
+    retrieveByStorageId(storageId: string, dekScheme?: CryptoScheme, contentHash?: string): Promise<RetrieveResult>;
+    /**
+     * 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).
+     */
+    private _getDekScheme;
+    /**
+     * 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.
+     */
+    private _unwrapDek;
+    /**
+     * Compute the ownerSecret for an existing on-chain reference.
+     * Used by removeReference/updateReference to derive the ZK witness secret.
+     *
+     * 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
+     */
+    private _computeOwnerSecret;
+    private _decryptAndReassemble;
+    /**
+     * 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()
+     */
+    retrieveByRefId(refId: string): Promise<RetrieveResult>;
+    /**
+     * List references currently available from the configured chain adapter.
+     */
+    listReferences(options?: ListReferencesOptions): Promise<DataReferenceSummary[]>;
+    /**
+     * 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.
+     */
+    removeReference(refId: string): Promise<void>;
+    /**
+     * Estimate the full cost (storage + chain) for a given payload size before committing.
+     */
+    estimateCost(sizeBytes: number): Promise<CostEstimate>;
+    /**
+     * Execute a full meta-transaction for a file:
+     * estimate → encrypt → pay storage → upload → pay chain → write reference
+     *
+     * Presents the entire flow as a single action with step-by-step progress.
+     *
+     * @param file        The File to encrypt and store
+     * @param onProgress  Callback fired on every step state change
+     * @param config      Optional token overrides and metadata
+     */
+    executeMetaTransaction(file: File, onProgress: (progress: MetaTxProgress) => void, config?: MetaTxConfig): Promise<MetaTxReceipt>;
+    /**
+     * Generate a fresh random DEK, wrap it under the KEK(s), and return the crypto
+     * materials needed by MetaTx to encrypt payload and storageId.
+     *
+     * 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).
+     */
+    prepareUploadCrypto(isPublic?: boolean): Promise<UploadCrypto>;
+    /**
+     * 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.
+     */
+    private _uploadChunked;
+    /**
+     * Reassemble a chunked file from its manifest.
+     * Fetches and decrypts each chunk sequentially to bound memory usage.
+     */
+    private _retrieveChunked;
+    private assertConnected;
+}
+
+/**
+ * @dstorage/core — chunked.ts
+ *
+ * Defines the manifest shape and helpers for large-file (chunked) uploads.
+ * SDK-level chunking splits files into CHUNK_SIZE pieces before encryption,
+ * bounding peak memory usage to ~2× the chunk size regardless of file size.
+ */
+
+/**
+ * Nominal SDK chunk size: 10 MB per piece.
+ *
+ * Each chunk becomes one independent Arweave transaction, so larger chunks
+ * mean fewer transactions and therefore less total base-fee overhead.
+ * 10 MB sits comfortably below the arweave.net gateway POST limit (~12 MB)
+ * while halving transaction count compared to 5 MB.
+ *
+ * The Arweave adapter uses getUploader() which sends each transaction's data
+ * in 256 KB network slices, so 10 MB chunks upload reliably without hitting
+ * any HTTP body size limit.
+ */
+declare const CHUNK_SIZE: number;
+interface ChunkEntry {
+    index: number;
+    storageId: string;
+    /** Actual byte count in this chunk (last chunk may be smaller). */
+    size: number;
+}
+interface ChunkManifest {
+    v: 1;
+    type: "dstorage-chunked-manifest";
+    totalSize: number;
+    chunkSize: number;
+    chunkCount: number;
+    provider: StorageProviderName;
+    chunks: ChunkEntry[];
+}
+declare function isManifest(payload: unknown): payload is ChunkManifest;
+
+declare const CoreErrorCode: {
+    readonly METADATA_WITH_PUBLIC_UPLOAD: 10001;
+    readonly UPLOAD_NO_PROVIDERS: 10002;
+    readonly PUBLIC_UPLOAD_REQUIRES_SEED_PROVIDER: 10003;
+    readonly CHAIN_WRITE_FAILED: 10004;
+    readonly REGISTER_REF_REQUIRES_CHAIN: 10010;
+    readonly REGISTER_REF_REQUIRES_ENCRYPTION: 10011;
+    readonly UPDATE_UPLOAD_REQUIRES_CHAIN: 10020;
+    readonly UPDATE_UPLOAD_NOT_SUPPORTED: 10021;
+    readonly UPDATE_UPLOAD_REQUIRES_ENCRYPTION: 10022;
+    readonly ROTATE_KEYS_REQUIRES_CHAIN: 10023;
+    readonly ROTATE_KEYS_NOT_SUPPORTED: 10024;
+    readonly ROTATE_KEYS_REQUIRES_ENCRYPTION: 10025;
+    readonly DECRYPT_NO_PROVIDERS: 10030;
+    readonly DECRYPT_ENVELOPE_EMPTY: 10031;
+    readonly DECRYPT_ENVELOPE_MALFORMED: 10032;
+    readonly DECRYPT_NO_WRAPPER_MATCHED: 10033;
+    readonly UNWRAP_DEK_NO_PROVIDERS: 10034;
+    readonly UNWRAP_DEK_ENVELOPE_EMPTY: 10035;
+    readonly UNWRAP_DEK_ENVELOPE_MALFORMED: 10036;
+    readonly UNWRAP_DEK_NO_WRAPPER_MATCHED: 10037;
+    readonly DECRYPT_PAYLOAD_FAILED: 10038;
+    readonly RETRIEVE_BY_REF_ID_REQUIRES_CHAIN: 10050;
+    readonly REF_NOT_FOUND: 10051;
+    readonly STORAGE_ADAPTER_MISMATCH: 10052;
+    readonly RETRIEVE_BY_REF_ID_ENVELOPE_EMPTY: 10053;
+    readonly CONTENT_HASH_MISMATCH: 10054;
+    readonly LIST_REFS_REQUIRES_CHAIN: 10060;
+    readonly LIST_REFS_NOT_SUPPORTED: 10061;
+    readonly REMOVE_REF_REQUIRES_CHAIN: 10070;
+    readonly REMOVE_REF_NOT_SUPPORTED: 10071;
+    readonly META_TX_REQUIRES_ENCRYPTION: 10080;
+    readonly PREPARE_UPLOAD_NO_PROVIDERS: 10081;
+    readonly MANIFEST_INVALID_STRUCTURE: 10090;
+    readonly MANIFEST_CHUNK_COUNT_MISMATCH: 10091;
+    readonly MANIFEST_NOT_CONTIGUOUS: 10092;
+    readonly DECRYPT_CHUNK_FAILED: 10093;
+    readonly CHUNK_OVERFLOWS_TOTAL_SIZE: 10094;
+    readonly REASSEMBLY_SIZE_MISMATCH: 10095;
+    readonly NOT_INITIALIZED: 10100;
+    readonly META_TX_UNKNOWN_STEP: 10200;
+    readonly UNKNOWN_ERROR: 10999;
+};
+type CoreErrorCode = (typeof CoreErrorCode)[keyof typeof CoreErrorCode];
+/**
+ * Thrown when `store()` succeeds at the storage layer but fails to write the
+ * on-chain reference. The content is permanently on the storage network — use
+ * `err.recovery` with `registerReference()` to retry only the chain write.
+ */
+declare class StorePartialError extends DStorageError {
+    readonly recovery: StoreRecovery;
+    constructor(recovery: StoreRecovery);
+}
+declare function isStorePartialError(err: unknown): err is StorePartialError;
+
+export { ARWEAVE_LOCAL, type AdapterWalletProvider, type ArweaveBundlerAdapterConfig, ArweaveBundlerStorageAdapter, type ArweaveLocalAdapterConfig, type ArweaveLocalBalance, ArweaveLocalError, ArweaveLocalHelper, type ArweaveLocalHelperConfig, type ArweaveLocalInfo, ArweaveLocalStorageAdapter, ArweavePaymentAdapter, ArweaveStorageAdapter, CHUNK_SIZE, type ChunkEntry, type ChunkManifest, CoreErrorCode, type CostEstimate, CryptoErrorCode, type CryptoScheme, DStorage, type DStorageConfig, type DStorageContext, DStorageError, type EncryptionAdapter, EncryptionErrorCode, type EncryptionScheme, type FromKdfParamsConfig, HttpGatewayChainAdapter, type HttpGatewayChainAdapterConfig, KDF_PRESETS, type KdfPreset, KeyDeriver, type KeyEnvelope, type KeyWrapper, KeypairEncryptionAdapter, type ListReferencesOptions, type Logger, MANIFEST_AAD, METADATA_AAD, METADATA_ONLY_OWNER_SECRET_SALT, type MLKemVariant, ManagedPaymentAdapter, MetaTx, type MetaTxConfig, type MetaTxProgress, type MetaTxReceipt, type MetaTxStepId, type MetaTxStepState, type MetaTxStepStatus, MidnightChainAdapter, type MidnightChainAdapterConfig, MidnightSimulatorChainAdapter, MnemonicEncryptionAdapter, NETWORKS, PAYLOAD_AAD, PasswordEncryptionAdapter, type PasswordEncryptionAdapterConfig, type RegisterReferenceOptions, type RegisterReferenceResult, type RetrieveResult, type StoreOptions, StorePartialError, type StoreProgress, type StoreRecovery, type StoreResult, type StoredKdfParams, type UpdateResult, type UploadCrypto, type WalletAddresses, type WalletInfo, type WrappedDekResult, type XChaChaPayload, XChaChaScheme, arlocalGateway, base64urlToBytes, buildKeyEnvelope, bytesToBase64url, chunkAad, computeBlake3, computeBlake3Hex, decryptStorageIdXChaCha, decryptXChaCha, defaultChainToken, deriveKek, deriveOwnerSecret, deriveSymmetricKeyFromSeed, deserializeXChaChaPayload, encryptStorageIdXChaCha, encryptXChaCha, findWrapper, generateDek, generatePqsPassword, hexToBytes, isDStorageError, isManifest, isStorePartialError, mlkemGenerateKeypair, mlkemGenerateKeypairFromSeed, mlkemUnwrapDek, mlkemWrapDek, parseKeyEnvelope, serializeKeyEnvelope, serializeXChaChaPayload, unwrapKey, waitForFacadeSync, wrapKey };