@opendatalabs/vana-sdk
Version:
A TypeScript library for interacting with Vana Network smart contracts.
101 lines (100 loc) • 3.48 kB
TypeScript
import { type StorageProvider, type StorageUploadResult, type StorageFile, type StorageListOptions, type StorageProviderConfig } from "../index";
import { type Web3SignedSignFn } from "../../auth/web3-signed-builder";
/**
* Wallet-style signer used by {@link VanaStorage} to authenticate every
* request. For Personal Server flows this can be a registered server wallet
* signing requests for the owner's storage namespace.
*
* @category Storage
*/
export interface VanaStorageSigner {
/** EIP-191 address (`0x...`). */
address: `0x${string}`;
/** EIP-191 personal_sign callback (e.g. viem `account.signMessage`). */
signMessage: Web3SignedSignFn;
}
/**
* Configuration for {@link VanaStorage}.
*
* @category Storage
*/
export interface VanaStorageConfig {
/**
* Base URL of the vana-storage Worker. Defaults to `https://storage.vana.org`.
*/
endpoint?: string;
/**
* Wallet signer used to authenticate writes and reads.
*/
signer: VanaStorageSigner;
/**
* Owner namespace under which blobs are stored. Defaults to the signer address.
*/
ownerAddress?: `0x${string}`;
/**
* Optional `fetch` implementation. Defaults to the global `fetch`.
* Useful for tests and for environments that need a custom HTTP client.
*/
fetchImpl?: typeof fetch;
}
/**
* Storage provider that talks to the vana-storage Worker
* (`https://storage.vana.org` by default). All requests are authenticated
* with Web3Signed headers signed by the configured wallet.
*
* @remarks
* Filenames passed to {@link VanaStorage.upload} must be of the form
* `"{scope}/{collectedAt}"` (e.g. `"instagram.profile/2026-05-08T20:00:00.000Z"`).
* The owner address is prepended automatically to produce the canonical
* blob path `/v1/blobs/{owner}/{scope}/{collectedAt}`.
*
* @category Storage
*
* @example
* ```typescript
* import { privateKeyToAccount } from "viem/accounts";
* import { VanaStorage } from "@opendatalabs/vana-sdk/node";
*
* const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
* const storage = new VanaStorage({
* signer: {
* address: account.address,
* signMessage: (msg) => account.signMessage({ message: msg }),
* },
* });
*
* const result = await storage.upload(
* new Blob([ciphertext]),
* "instagram.profile/2026-05-08T20:00:00.000Z",
* );
* ```
*/
export declare class VanaStorage implements StorageProvider {
private readonly endpoint;
private readonly signer;
private readonly ownerAddress;
private readonly fetchImpl;
constructor(config: VanaStorageConfig);
/**
* Upload an encrypted blob to vana-storage.
*
* @param file - The blob to upload.
* @param filename - Required relative key in the form `"{scope}/{collectedAt}"`.
* The owner address is prepended automatically.
*/
upload(file: Blob, filename?: string): Promise<StorageUploadResult>;
/**
* Download a blob by URL. The URL must point at a path under this
* provider's endpoint.
*/
download(url: string): Promise<Blob>;
/**
* Listing is not supported by vana-storage — file discovery is handled by
* the Gateway DataRegistry, not the storage layer.
*/
list(_options?: StorageListOptions): Promise<StorageFile[]>;
delete(url: string): Promise<boolean>;
getConfig(): StorageProviderConfig;
private signRequest;
private pathFromUrl;
}