@varity-labs/sdk Overview

Varity Team Core Contributors Updated March 2026

The Varity SDK provides the core building blocks for your application: a zero-config database, credential management, and infrastructure utilities. Install it once and start building immediately.

v2.0.0-beta.2

What’s Included

Database

Zero-config database with typed collections and CRUD operations

Credentials

Credential resolution, validation, and dev/production management

Infrastructure

Platform configuration and utilities via subpath imports

Quick Start

The most common pattern is the zero-config database:

import { db } from '@varity-labs/sdk';

// Define a collection with TypeScript types
const users = db.collection<{ name: string; email: string }>('users');

// Create
await users.add({ name: 'Alice', email: 'alice@example.com' });

// Read
const allUsers = await users.get({ limit: 10, orderBy: 'name' });

// Update
await users.update('user-id', { name: 'Alice Smith' });

// Delete
await users.delete('user-id');

Main Exports

Everything available from import { ... } from '@varity-labs/sdk':

Database

Export	Type	Description
db	Database instance	Pre-configured singleton — use this for most apps
Database	class	Database class. Constructor accepts optional Partial<DatabaseConfig>
Collection	class	Typed CRUD class with add(), get(), update(), delete() methods

import { db, Database } from '@varity-labs/sdk';

// Option 1: Use the pre-configured singleton (recommended)
const posts = db.collection<{ title: string; body: string }>('posts');
await posts.add({ title: 'Hello World', body: 'First post' });

// Option 2: Create a custom instance with your own config
const customDb = new Database({
  proxyUrl: 'https://your-proxy.example.com',
  appToken: 'your-app-token',
});
const items = customDb.collection('items');

Credentials

Export	Type	Description
VARITY_DEV_CREDENTIALS	const (object)	Shared dev credentials containing privy.appId, thirdweb.clientId, and rateLimits
resolveCredentials	function	(appId?, clientId?) => CredentialConfig — resolves with fallback to dev credentials
validateCredentials	function	(appId, clientId) => void — throws if credentials are invalid
isUsingDevCredentials	function	(appId?, clientId?) => boolean — check if using shared dev credentials
isProductionCredentials	function	(appId?, clientId?) => boolean — check if using production credentials
getCredentialWarning	function	(environment) => string | null — get a warning message if credentials need attention
logCredentialUsage	function	(appId?, clientId?) => void — log which credentials are being used
getUpgradeInstructions	function	() => string — get instructions for upgrading to production credentials

import {
  resolveCredentials,
  isUsingDevCredentials,
  getCredentialWarning,
  VARITY_DEV_CREDENTIALS,
} from '@varity-labs/sdk';

// Resolve credentials with automatic fallback to dev credentials
const creds = resolveCredentials(
  process.env.NEXT_PUBLIC_PRIVY_APP_ID,
  process.env.NEXT_PUBLIC_THIRDWEB_CLIENT_ID,
);
console.log(creds.privy.appId);
console.log(creds.thirdweb.clientId);

// Check if using dev credentials (useful for showing warnings)
if (isUsingDevCredentials()) {
  console.warn('Using shared dev credentials -- set your own before deploying');
}

// Get environment-specific warnings
const warning = getCredentialWarning('production');
if (warning) {
  console.warn(warning);
}

Version

Export	Type	Description
VERSION	const (string)	SDK version ('2.0.0-beta.2')
SDK_VERSION	const (string)	Same as VERSION

import { VERSION } from '@varity-labs/sdk';

console.log(`Running Varity SDK ${VERSION}`);

Type Exports

The SDK exports these TypeScript types from the main entry point:

import type {
  CredentialConfig,   // { privy: { appId }, thirdweb: { clientId } }
  DatabaseConfig,     // { proxyUrl?: string, appToken?: string }
  QueryOptions,       // { limit?, offset?, orderBy? }
  Document,           // { id: string, created_at?, updated_at?, [key]: any }
  CollectionResponse, // { success: boolean, data?: T, error?: string }
} from '@varity-labs/sdk';

Note

Beta release — The main SDK entry point currently exports database and credential utilities only. Additional modules (storage, analytics, notifications) are planned for future releases. See the subpath imports below for infrastructure access.

Advanced: Subpath Imports for Infrastructure Access

For apps that need direct access to chain configuration, blockchain services, thirdweb integration, or gas tracking, the SDK provides subpath imports. These are separate from the main entry point and are primarily used by the UI Kit and CLI internally.

Chains (@varity-labs/sdk/chains)

Chain definitions for Varity L3, Arbitrum, and Base networks, plus USDC formatting utilities.

import {
  varityL3,
  varityL3Testnet,
  formatUSDC,
  parseUSDC,
  formatAddress,
  getVarityExplorerUrl,
  USDC_DECIMALS,
  VARITY_USDC_ADDRESS,
  SUPPORTED_CHAINS,
} from '@varity-labs/sdk/chains';

// Format a raw USDC amount (6 decimals) for display
const display = formatUSDC(BigInt(1500000)); // "1.50"

// Parse a human-readable amount to raw
const raw = parseUSDC('25.00'); // BigInt(25000000)

// Get an explorer URL
const url = getVarityExplorerUrl('0xabc...');

Blockchain Services (@varity-labs/sdk/blockchain)

Direct blockchain interaction services for licensing and revenue splits.

import {
  BlockchainService,
  NFTLicensingService,
  RevenueSplitService,
} from '@varity-labs/sdk/blockchain';

Thirdweb Integration (@varity-labs/sdk/thirdweb)

Wrappers around thirdweb services including Engine, Nebula, Storage, Bridge, Gateway, and x402.

import {
  createThirdwebWrapper,
  createEngineClient,
  createNebulaClient,
  createStorageClient,
  varietyTestnet,
  getVarityChain,
  isVarityChain,
  VARITY_TESTNET_RPC,
} from '@varity-labs/sdk/thirdweb';

Gas Tracking (@varity-labs/sdk/tracking)

Track gas usage, calculate costs in USDC, and manage billing cycles.

import {
  trackGasUsage,
  trackTransactionGasUsage,
  waitForTransactionReceipt,
  calculateGasInUSDC,
  createGasTracker,
} from '@varity-labs/sdk/tracking';

What about createVaritySDK and the class-based SDK?

You may see references to a class-based SDK pattern (createVaritySDK, sdk.connect(), sdk.storage, sdk.analytics, etc.) in older code or documentation. This v1 API exists in the SDK source code but is currently commented out and not exported from the package.

The current SDK (v2.0.0-beta.2) uses a modular approach:

• Database: Use the db singleton or create a Database instance directly
• Credentials: Use the standalone credential functions
• Infrastructure: Use subpath imports (/chains, /blockchain, /thirdweb, /tracking)

The class-based API may be re-enabled in a future release once the underlying infrastructure is fully set up.

Next Steps

Installation

Get the SDK installed and configured in your project. View Guide

Infrastructure Config

Learn about chain configuration and utilities. View Guide

Related Resources

• Quick Start - Build your first app
• @varity-labs/ui-kit - React components
• Deploy Your App - Ship to production