@bind-protocol/sdk

TypeScript SDK for the Bind Protocol - privacy-preserving credential issuance and verification using zero-knowledge proofs.

Installation

npm install @bind-protocol/sdk

Quick Start

import { BindClient } from '@bind-protocol/sdk';

const client = new BindClient({
  apiKey: 'your-api-key',
});

// Submit a prove job
const result = await client.submitProveJob('bind.mobility.riskband.v1', {
  signals: JSON.stringify(telemetryData),
  timestamp: new Date().toISOString(),
});

// Wait for completion
const job = await client.waitForProveJob(result.data.jobId);

if (job.status === 'completed') {
  console.log('Proof generated:', job.attestationId);
}

Architecture

The SDK is organized into modules:

@bind-protocol/sdk
├── core/           # Main client, types, and errors
│   ├── BindClient  # API client for prove jobs and policies
│   ├── types       # TypeScript type definitions
│   └── errors      # Custom error classes
└── adapters/       # Data source adapters
    └── dimo/       # DIMO Network integration

Import Paths

// Main entry point (recommended)
import { BindClient, DimoAdapter } from '@bind-protocol/sdk';

// Or import specific modules
import { BindClient } from '@bind-protocol/sdk/core';
import { DimoAdapter } from '@bind-protocol/sdk/adapters/dimo';

Core Module

BindClient

The main client for interacting with the Bind Protocol API.

import { BindClient } from '@bind-protocol/sdk';

const client = new BindClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.bindprotocol.com', // optional
});

Methods

| Method | Description | |--------|-------------| | submitProveJob(circuitId, inputs) | Submit a prove job for async processing | | getProveJob(jobId) | Get status and results of a prove job | | listProveJobs(options?) | List prove jobs with optional filters | | waitForProveJob(jobId, options?) | Poll until job completes or fails | | listPolicies() | List all public policies (no auth required) | | getPolicy(policyId) | Get a specific policy by ID |

Error Handling

The SDK provides typed errors for common scenarios:

import {
  BindError,
  ApiError,
  AuthenticationError,
  TimeoutError,
  InsufficientCreditsError
} from '@bind-protocol/sdk';

try {
  await client.submitProveJob(circuitId, inputs);
} catch (error) {
  if (error instanceof InsufficientCreditsError) {
    console.log(`Need ${error.required} credits, have ${error.available}`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof TimeoutError) {
    console.log(`Timed out after ${error.timeoutMs}ms`);
  }
}

Adapters

Adapters abstract data sources and transform their data into circuit inputs.

DIMO Adapter

Fetches vehicle telemetry from the DIMO Network and transforms it for risk band evaluation.

import { BindClient, DimoAdapter } from '@bind-protocol/sdk';
import { DIMO } from '@dimo-network/data-sdk';

// Initialize DIMO client (see DIMO docs for auth)
const dimoClient = new DIMO('Production');
await dimoClient.auth.getToken({ /* ... */ });

// Create adapter
const dimo = new DimoAdapter({ dimoClient });

// Fetch telemetry
const data = await dimo.fetchData({
  vehicleTokenId: '12345',
  from: '2024-01-01',
  to: '2024-01-31',
});

// Transform to circuit inputs
const inputs = dimo.toCircuitInputs(data, 'bind.mobility.riskband.v1');

// Submit prove job
const client = new BindClient({ apiKey: 'your-api-key' });
const result = await client.submitProveJob('bind.mobility.riskband.v1', inputs);

Creating Custom Adapters

Implement the DataAdapter interface to create adapters for other data sources:

import type { DataAdapter, ProveJobInputs } from '@bind-protocol/sdk';

interface MyDataQuery {
  userId: string;
  dateRange: { from: string; to: string };
}

interface MyData {
  metrics: number[];
  timestamp: string;
}

class MyAdapter implements DataAdapter<MyConfig, MyDataQuery, MyData> {
  readonly id = 'my-adapter';
  readonly name = 'My Data Source';
  readonly description = 'Fetches data from my service';

  async fetchData(query: MyDataQuery): Promise<MyData> {
    // Fetch from your data source
  }

  toCircuitInputs(data: MyData, circuitId: string): ProveJobInputs {
    // Transform to circuit inputs
    return {
      metrics: JSON.stringify(data.metrics),
      timestamp: data.timestamp,
    };
  }
}

Policies and Circuits

Understanding Policies

A Policy defines what data is evaluated and what credentials are issued:

• Input specifications (what data is needed)
• Evaluation rules (how data is scored/validated)
• Output claims (what the credential asserts)
• Privacy controls (what verifiers can see)

Understanding Circuits

A Circuit is the zero-knowledge proof implementation that cryptographically proves a policy was evaluated correctly without revealing the underlying data.

// List available policies
const policies = await client.listPolicies();

for (const policy of policies) {
  console.log(`${policy.id}: ${policy.metadata.title}`);
  console.log(`  Outputs: ${policy.outputs.map(o => o.name).join(', ')}`);
}

// Get policy details
const policy = await client.getPolicy('bind.mobility.riskband.v1');
console.log(policy.outputs); // [{ name: 'riskBand', type: 'enum', ... }]

Complete Example: Insurance Risk Assessment

import { BindClient, DimoAdapter } from '@bind-protocol/sdk';
import { DIMO } from '@dimo-network/data-sdk';

async function generateRiskCredential(vehicleTokenId: string) {
  // 1. Set up clients
  const dimoClient = new DIMO('Production');
  await dimoClient.auth.getToken({ /* ... */ });

  const dimo = new DimoAdapter({ dimoClient });
  const bind = new BindClient({ apiKey: process.env.BIND_API_KEY });

  // 2. Fetch 30 days of telemetry
  const telemetry = await dimo.fetchData({
    vehicleTokenId,
    from: '2024-12-01',
    to: '2024-12-31',
  });

  // 3. Transform and submit prove job
  const inputs = dimo.toCircuitInputs(telemetry, 'bind.mobility.riskband.v1');
  const result = await bind.submitProveJob('bind.mobility.riskband.v1', inputs);

  if (!result.success) {
    throw new Error(result.error);
  }

  // 4. Wait for proof generation
  const job = await bind.waitForProveJob(result.data.jobId, {
    onProgress: (j) => console.log(`Status: ${j.status}`),
  });

  if (job.status !== 'completed') {
    throw new Error(job.error || 'Proof generation failed');
  }

  // 5. Return credential
  return {
    policyId: 'bind.mobility.riskband.v1',
    attestationId: job.attestationId,
    zkVerifyTxHash: job.zkVerifyTxHash,
  };
}

Types

All types are exported from the main package:

import type {
  // Client options
  BindClientOptions,

  // Prove job types
  ProveJobStatus,
  ProveJobInputs,
  ProveJob,
  ProveJobSummary,
  SubmitProveJobResponse,
  GetProveJobResponse,
  ListProveJobsOptions,
  ListProveJobsResponse,

  // Credential types
  BindCredential,

  // Policy types (from @bind-protocol/policy-spec)
  PublicPolicySpec,
  PolicyId,
  PolicyMetadata,

  // Adapter types
  DataAdapter,
  TelemetryData,

  // DIMO types
  DimoAdapterConfig,
  DimoQuery,
  DimoTelemetryData,
} from '@bind-protocol/sdk';

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | BIND_API_URL | API base URL | https://api.bindprotocol.com |

License

MIT

Links

• Bind Protocol
• Documentation
• DIMO Network