Wallet and Network Integration: Connect to Vana networks (supports Vana Mainnet 1480 and Moksha Testnet 14800 out of the box) with easy provider configuration.
Data Contribution Workflow: Submit data to a DLP and request validation:
- Register encrypted data files on-chain (DataRegistry) and give the DLP access.
- Trigger the Satya TEE network to validate your contribution (TeePool).
- Claim your reward tokens from the DLP after successful validation.
Data Liquidity Pool Management: (Upcoming) For DLP owners:
- Create a new DLP (via factory or registry) and configure its parameters.
- Register the validation logic (refiner) for your DLP in the DataRefinerRegistry.
- Update DLP settings (pause/unpause contracts, update trusted forwarder or public key, etc.).
Data Query & Access: (Upcoming) Enable data buyers to run queries on contributed data securely:
- Set query permissions with prices (through QueryEngine).
- Approve or revoke query requests (for DLP/refiner owners).
- Automatically handle payments and result retrieval via TEE ComputeEngine.
Utilities: Helper functions for encryption, key management, and result decoding to abstract away the cryptographic details of interacting with the Vana network.

Installation

npm install vana-sdk

Quick Start Example

import { VanaProvider } from "vana-sdk";
import { privateKeyToAccount } from "viem/accounts";
import { createPublicClient, createWalletClient, http } from "viem";
import { mokshaTestnet } from "vana-sdk/chains";

// Create your viem clients
const publicClient = createPublicClient({
  chain: mokshaTestnet,
  transport: http("https://rpc.moksha.vana.org"),
});

const signer = privateKeyToAccount("0x..."); // Your private key
const walletClient = createWalletClient({
  chain: mokshaTestnet,
  transport: http("https://rpc.moksha.vana.org"),
  account: signer,
});

// Connect to Vana
const vana = new VanaProvider({
  chainId: mokshaTestnet.id,
  rpcUrl: "https://rpc.moksha.vana.org",
  signer,
});

// Example file URL and encryption key
const fileUrl = "https://example.com/mydata.csv";
const dlpAddress = vana.getContractAddress("DataLiquidityPoolProxy");
const encryptedKey = await encryptFileKey(myFileEncryptionKey, dlpPublicKey);
const signerAddress = await vana.signerAddress();

// Register file in the DataRegistry with permissions
await walletClient.writeContract({
  address: vana.contracts.dataRegistry.address,
  abi: vana.contracts.dataRegistry.abi,
  functionName: "addFileWithPermissions",
  args: [
    fileUrl,
    signerAddress,
    dlpAddress,
    [{ account: dlpAddress, key: encryptedKey }],
  ],
});

// Get file ID from DataRegistry
const fileId = await publicClient.readContract({
  address: vana.contracts.dataRegistry.address,
  abi: vana.contracts.dataRegistry.abi,
  functionName: "fileIdByUrl",
  args: [fileUrl],
});

// Request TEE validation
await walletClient.writeContract({
  address: vana.contracts.teePool.address,
  abi: vana.contracts.teePool.abi,
  functionName: "requestContributionProof",
  args: [fileId],
});

// Wait for validation (in a real app, listen for events)
// ...wait for ProofAdded event...

// Claim reward for contribution
await walletClient.writeContract({
  address: vana.contracts.dataLiquidityPool.address,
  abi: vana.contracts.dataLiquidityPool.abi,
  functionName: "claimReward",
  args: [fileId],
});

Interacting with Contracts

The SDK provides a streamlined way to interact with Vana smart contracts through the VanaProvider class, which gives you access to contract addresses and ABIs, while leveraging viem's client interface for actual blockchain interactions.

Using Contracts with Viem Clients

The Vana SDK uses a simple pattern for contract interaction:

Use the VanaProvider to access contract information (address and ABI)
Use viem's publicClient for read operations and walletClient for write operations

import { VanaProvider } from "vana-sdk";
import { privateKeyToAccount } from "viem/accounts";
import { createPublicClient, createWalletClient, http } from "viem";
import { mokshaTestnet } from "vana-sdk/chains";

// Create viem clients
const publicClient = createPublicClient({
  chain: mokshaTestnet,
  transport: http("https://rpc.moksha.vana.org"),
});

const signer = privateKeyToAccount("0x...");
const walletClient = createWalletClient({
  chain: mokshaTestnet,
  transport: http("https://rpc.moksha.vana.org"),
  account: signer,
});

// Initialize Vana provider
const vana = new VanaProvider({
  chainId: mokshaTestnet.id,
  rpcUrl: "https://rpc.moksha.vana.org",
  signer,
});

// Read operations
const fileId = await publicClient.readContract({
  address: vana.contracts.dataRegistry.address,
  abi: vana.contracts.dataRegistry.abi,
  functionName: "fileIdByUrl",
  args: [fileUrl],
});

// Write operations
await walletClient.writeContract({
  address: vana.contracts.dataRegistry.address,
  abi: vana.contracts.dataRegistry.abi,
  functionName: "addFile",
  args: [fileUrl, owner],
});

await walletClient.writeContract({
  address: vana.contracts.teePool.address,
  abi: vana.contracts.teePool.abi,
  functionName: "requestContributionProof",
  args: [fileId],
});

Available Contracts

The VanaProvider gives you access to the following contracts:

dataRegistry: For registering and managing data files
teePool: For managing TEE computation and validation
dataLiquidityPool: For managing token rewards
computeEngine: For execution of data analytics

TypeScript ABI Pattern

The SDK uses a type-safe approach for contract ABIs:

Contract ABI Definitions: All contract ABIs are defined as TypeScript files in the src/abi directory.
Central Registry: The abi/index.ts file provides a central registry of all available contract ABIs.
Type Safety: The SDK leverages TypeScript's type system to ensure you can only request ABIs for supported contracts:

// Access a contract's ABI
import { getAbi } from "vana-sdk";
const dataRegistryAbi = getAbi("DataRegistry");

This pattern makes it easy to extend the SDK with new contracts while maintaining full type safety.

Extending the SDK

You can extend the SDK with custom contract wrappers using the BaseContractClient if needed:

import { BaseContractClient, VanaProvider } from "vana-sdk";
import { privateKeyToAccount } from "viem/accounts";
import { createPublicClient, createWalletClient, http } from "viem";

// Create a custom client for a contract
export class MyCustomContractClient extends BaseContractClient<"DataRegistry"> {
  constructor(provider: VanaProvider) {
    super("DataRegistry", provider);
  }

  // Use with a provider
  static withProvider(privateKey: string, rpcUrl: string) {
    const signer = privateKeyToAccount(privateKey);
    const provider = new VanaProvider({
      chainId: 14800,
      rpcUrl,
      signer,
    });
    return new MyCustomContractClient(provider);
  }

  // Add custom methods
  async addFileWithNotification(fileUrl: string, owner: string): Promise<any> {
    const walletClient = createWalletClient({
      transport: http(this.provider.rpcUrl),
      account: this.provider.signer,
    });

    // Call a write function on the contract
    const hash = await walletClient.writeContract({
      address: this.contract.address,
      abi: this.contract.abi,
      functionName: "addFile",
      args: [fileUrl, owner],
    });

    // Custom logic, like sending a notification
    console.log(`File added with transaction: ${hash}`);
    return hash;
  }
}

Project Structure

src/abi – TypeScript definitions of contract ABIs for type-safe interaction.
src/config – Network configuration (contract addresses, chains).
src/core – Core SDK classes (provider setup, client configuration).
src/contracts – Base contract interfaces and controllers.
src/utils – Utility functions (encryption helpers, formatters).

Contributing

We welcome contributions! If you want to add support for a new feature or contract:

Open an issue or draft a proposal for discussion if it's a significant addition.
Follow the coding style (run npm run lint to ensure ESLint passes).
Add unit tests for any new modules if possible.

TODOs and Future Plans

Implement specialized contract client classes for common operations.
Implement DataRefinerRegistry module: allow DLP owners to register and update data refiners.
Implement QueryEngine and ComputeEngine modules: enabling the data query flow (permissions, payments, result handling).
Event listening utilities: e.g. a helper to wait for a ProofAdded event or query completion events instead of manual polling.
DLP Factory support: add functions to create new DLPs via the DLP root contract, and to look up existing DLPs by ID or owner.
Comprehensive Testing: create a suite of tests (using Hardhat or Foundry scripts with Moksha testnet or local fork).
Documentation Site: expand the README into a full documentation site with guides.