Willow TypeScript SDK

import { WillowClient, generateWallet, createDidFromWallet } from '@willow-network/sdk';

// 1. Generate a wallet and DID
const wallet = generateWallet();
const didDocument = createDidFromWallet(wallet);

// 2. Initialize the client (pre-seed config.did + privateKey so client.init()
//    can fetch the key id from the DID document).
const client = new WillowClient({
  apiUrl: 'http://localhost:3031',
  did: didDocument.id,
  privateKey: wallet.privateKey,
});

// 3. Register and bootstrap the identity for per-request signing
await client.registerDid(didDocument);
await client.init();

// 4. Store data (requires the 'users' subgrove to exist — see below)
await client.store('users', 'alice', {
  name: 'Alice',
  score: 100,
});

// 5. Retrieve data (automatically verified!)
const data = await client.get('users', 'alice');
console.log(data);

import { WillowClient, consoleLogger } from '@willow-network/sdk';
import WebSocket from 'ws'; // only needed on Node < 22 for subscriptions

const client = new WillowClient({
  apiUrl: 'https://api.willow.tech',
  consensusRpcUrl: 'https://your-node.example.com:26657',
  apiKey: 'wk_...',
  logger: consoleLogger,
  webSocket: WebSocket,
});

// These operations automatically verify proofs:
const data = await client.get('dataset', 'key');
const results = await client.query('dataset', { filters: { status: 'active' } });

// Query results include the verified root hash
if (results.verifiedRootHash) {
  console.log('Data verified against root:', results.verifiedRootHash);
}

// For performance-critical scenarios, skip verification:
const unverifiedData = await client.getUnverified('dataset', 'key');
const unverifiedResults = await client.queryUnverified('dataset', { /* query */ });

// Store single item
await client.store('dataset-id', 'key', { field: 'value' });

// Batch store using collection helper
const collection = client.collection('dataset-id');
await collection.batchStore([
  { key: 'key1', value: { name: 'Item 1' } },
  { key: 'key2', value: { name: 'Item 2' } },
]);

// With automatic proof verification (secure by default)
const data = await client.get('dataset-id', 'key');

// Without verification (performance mode)
const data = await client.getUnverified('dataset-id', 'key');

// Get multiple with verification
const collection = client.collection('dataset-id');
const multiple = await collection.getMultiple(['key1', 'key2', 'key3']);

// Query with automatic proof verification
const results = await client.query('dataset-id', {
  filters: { status: 'active', score: { $gte: 100 } },
  limit: 10,
  offset: 0,
});

console.log('Documents:', results.documents);
console.log('Total:', results.total);
console.log('Verified root:', results.verifiedRootHash);

// Query without verification
const results = await client.queryUnverified('dataset-id', {
  filters: { status: 'active' },
});

await client.update('dataset-id', 'key', { field: 'new value' });
await client.delete('dataset-id', 'key');

// Get checkpoint state root for verification
const checkpoint = await client.data.getCheckpointStateRoot(
  'uniswap-v3',
  'a1b2c3d4...'
);
console.log('State root:', checkpoint.state_root);
console.log('Block range:', checkpoint.block_range);

// Query historical data (routed through consensus to indexer)
const result = await client.data.queryHistorical(
  'uniswap-v3',
  'a1b2c3d4...',
  {
    path: [[97, 112, 112, 115], [117, 115, 101, 114, 115]],
    key: [117, 115, 101, 114, 49, 50, 51],
    include_proof: true,
  }
);

console.log('Provider:', result.provider_did);
console.log('Data:', result.data);
console.log('State root:', result.state_root);

// Query with automatic proof verification against checkpoint state root
const verified = await client.data.queryHistoricalVerified(
  'uniswap-v3',
  'a1b2c3d4...',
  { path: [...], key: [...] }
);
// Throws if proof verification fails

try {
  const result = await client.data.queryHistorical(...);
} catch (error) {
  if (error.can_reindex) {
    // No providers currently have this data
    // A new indexer can re-index the block range
    console.log('Data currently unavailable, can be re-indexed');
  }
}

const users = client.collection('users');

// All operations scoped to this collection
await users.store('alice', { name: 'Alice', score: 100 });
const alice = await users.get('alice');
await users.update('alice', { ...alice, score: 150 });
await users.delete('alice');

// Batch operations
await users.batchStore([
  { key: 'bob', value: { name: 'Bob' } },
  { key: 'charlie', value: { name: 'Charlie' } },
]);

// Query within collection
const highScorers = await users.query({
  filters: { score: { $gte: 100 } },
});

// Unverified variants available
const fast = await users.getUnverified('alice');
const fastQuery = await users.queryUnverified({ /* ... */ });

// Get consensus-verified root hash (recommended for security)
const verifiedRoot = await client.getRootHash();

// Get local node's root hash (for debugging)
const localRoot = await client.getRootHashLocal();

// Compare to check sync status
if (verifiedRoot === localRoot) {
  console.log('Node is in sync with blockchain');
} else {
  console.log('Node has pending changes');
}

// Per-client: every automatic verification in get()/query() enforces the root
const client = new WillowClient({
  apiUrl: 'http://localhost:3031',
  proofVerificationOptions: { expectedRootHash: knownRootHash },
});

// Per-call: pass options as the last argument
const rootHash = await verifyQueryProof(proofHex, documents, {
  expectedRootHash: knownRootHash,
});

import {
  verifyQueryProof,
  verifyItemProof,
  verifyQueryResponse,
  computeProofRootHash,
  GroveDBProofVerifier,
} from '@willow-network/sdk';

// Verify a query proof; every document must be committed to by the proof
const rootHash = await verifyQueryProof(proofHex, documents);

// Verify a single item proof: enforces that the proof contains `key` at the
// given path AND that the proven payload deep-equals `value`
const rootHash = await verifyItemProof(proofHex, 'key', value, ['path', 'to', 'item']);

// Verify a QueryResponse object (binds response.documents)
const rootHash = await verifyQueryResponse(response);

// Fully verify a proof and return just the root hash (no document binding).
// Same cryptographic checks as verifyQueryProof.
const rootHash = await computeProofRootHash(proofHex);

// Structured results instead of throwing — options bound at construction
const verifier = new GroveDBProofVerifier({ expectedRootHash: expectedRoot });
const result = await verifier.verifyQueryProof(proofHex, documents);
// result: { valid: boolean, rootHash?: string, error?: string }

const response = await fetch('http://localhost:3031/verify-gkr-proof', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    proof: proofHex,
    verification_key_hash: vkHashHex,
    public_inputs: {
      input_commitment: inputCommitmentHex,
      output_root: outputRootHex,
      block_range: [startBlock, endBlock],
      config_hash: configHashHex,
    },
  }),
});
const { data } = await response.json();
// data: { valid: boolean, error?: string }

import * as grovedb from '@willow-network/sdk/grovedb';

// Full proof verification
const result = grovedb.verifyGroveDBProof(proofBytes);
// result: { rootHash: Uint8Array, results: Array<{ path, key, value, element }> }

// Verify against expected root (throws on mismatch)
const result = grovedb.verifyProofAgainstRoot(proofBytes, expectedRootHash);

// Quick verification (root hash only)
const rootHash = grovedb.quickVerify(proofBytes);

// Hash functions (BLAKE3-based)
const hash = grovedb.blake3Hash(data);
const vHash = grovedb.valueHash(value);
const kv = grovedb.kvHash(key, value);
const node = grovedb.nodeHash(kvHash, leftHash, rightHash);
const combined = grovedb.combineHash(a, b);

// Utility functions
const hex = grovedb.bytesToHex(bytes);
const bytes = grovedb.hexToBytes(hex);
const equal = grovedb.hashEquals(hash1, hash2);

import { LightClient, LightClientConfigBuilder } from '@willow-network/sdk';

// Configure light client (chainId is a required constructor arg)
const config = new LightClientConfigBuilder('willow-chain')
  .validatorEndpoints([
    'http://validator1:26657',
    'http://validator2:26657',
    'http://validator3:26657',
  ])
  .trustThreshold(2, 3)
  .maxClockDriftSecs(10)
  .minValidatorsForConsensus(2)
  .autoSync(true)
  .build();

// Create and start light client
const lightClient = new LightClient(config);
await lightClient.start();

// Sync to latest
await lightClient.syncToLatest();

// Verify a query proof against the light client's root hash
const result = await lightClient.verifyQueryProof(proof);

// Get verified headers
const latestHeader = await lightClient.getLatestHeader();
const headerAtHeight = await lightClient.getHeaderByHeight(1000);

// Export/import state for persistence
const state = await lightClient.exportTrustedState();
// ... save to disk ...
await lightClient.importTrustedState(savedState);

// Cleanup
await lightClient.stop();

import { generateEd25519KeyPair, signEd25519, verifyEd25519 } from '@willow-network/sdk';

// Generate key pair
const { privateKey, publicKey } = generateEd25519KeyPair();

// Sign a message
const signature = signEd25519('Hello, Willow!', privateKey);

// Verify signature
const isValid = verifyEd25519('Hello, Willow!', signature, publicKey);

import { generateWallet, createDidFromWallet } from '@willow-network/sdk';

// Generate Ethereum-compatible wallet
const wallet = generateWallet();
const didDocument = createDidFromWallet(wallet);

// Use with client
const client = new WillowClient({
  apiUrl: 'http://localhost:3031',
  did: didDocument.id,
  privateKey: wallet.privateKey, // 0x-prefixed Ethereum private key
});

// Returns the consensus BroadcastResult (txHash, height, rawLog)
const result = await client.registerSubgrove({
  dataset_id: 'users',
  name: 'User Data',
  schema: {
    version: 1,
    fields: {
      name: { type: 'string' },
      score: { type: 'number' },
      active: { type: 'boolean' },
    },
    indexes: [
      { name: 'by_name', fields: ['name'], unique: false, type: 'hash' },
    ],
    required_fields: ['name'],
  },
  owner_did: didDocument.id,
  writers: [didDocument.id],
  readers: [],
});

import { WillowError } from '@willow-network/sdk';

try {
  await client.get('dataset-id', 'key');
} catch (error) {
  if (error instanceof WillowError) {
    switch (error.code) {
      case 'DATA_NOT_FOUND':
        console.log('Key does not exist');
        break;
      case 'PROOF_VERIFICATION_FAILED':
        console.error('Data may have been tampered with!');
        break;
      case 'AUTH_FAILED':
        console.log('Authentication required');
        break;
      default:
        console.error(`Error: ${error.message} (${error.code})`);
    }
  }
}