veritasbtc-sdk

Zero-dependency JavaScript/TypeScript SDK for verifying content authenticity on Bitcoin via the VeritasBTC protocol.

Works in Node.js ≥ 18, all modern browsers, and edge runtimes (Cloudflare Workers, Vercel Edge, Deno).

npm install veritasbtc-sdk

How it works

VeritasBTC anchors SHA-256 fingerprints of files and documents onto the Stacks blockchain, which settles on Bitcoin. Once anchored, anyone can independently verify that a file existed at a specific block — without trusting any server.

This SDK lets you:

• Verify any file or hash against the Bitcoin-anchored registry
• Batch-verify multiple files in parallel
• Look up on-chain identities of content owners
• Check trust circles between identities

Quick start

import { createClient } from 'veritasbtc-sdk';

const veritas = createClient(); // defaults to mainnet

// Verify a file (browser or Node.js)
const result = await veritas.verify(file); // File or ArrayBuffer

console.log(result.verified);     // true / false
console.log(result.hash);         // SHA-256 hex fingerprint
console.log(result.anchor);       // on-chain anchor record, or null
console.log(result.identity);     // owner's registered identity, or null

API

createClient(config?)

import { createClient } from 'veritasbtc-sdk';

// Mainnet (default)
const client = createClient();

// Testnet
const client = createClient({ network: 'testnet' });

// Custom (self-hosted API proxy)
const client = createClient({
  apiUrl: 'https://your-api.com',
  contractAddress: 'SP...',
});

verify(file)

Hashes a file and checks if its fingerprint is anchored on Bitcoin.

const result = await client.verify(file); // File | ArrayBuffer | Uint8Array
// result: VerifyResult

verifyHash(hex)

Check a pre-computed SHA-256 hash.

const result = await client.verifyHash('2cf24dba...');

batchVerify(files)

Verify multiple files in parallel. Each result includes an index and error field.

const results = await client.batchVerify([file1, file2, file3]);
results.forEach(r => {
  console.log(r.index, r.verified, r.error);
});

getAnchor(file)

Returns the raw anchor record without identity lookup.

const anchor = await client.getAnchor(file);
// { hash, owner, blockHeight, contentType, label } | null

getIdentity(address)

Look up a Stacks address's registered identity.

const identity = await client.getIdentity('SP3BHPVZ...');
// { name, verificationLevel, registeredAt, status } | null

getAnchorCount(address)

Number of content anchors made by a Stacks address.

const count = await client.getAnchorCount('SP3BHPVZ...');

isInTrustCircle(owner, member)

Check if member is in owner's on-chain trust circle.

const trusted = await client.isInTrustCircle('SP...owner', 'SP...member');

Low-level helpers

import {
  sha256,          // (ArrayBuffer) => Promise<ArrayBuffer>
  buf2hex,         // (ArrayBuffer | Uint8Array) => string
  hex2buf,         // (string) => Uint8Array
  hashFile,        // (File | ArrayBuffer) => Promise<{ hash, buffer }>
  parseHash,       // (hex) => { hash, buffer }  — validates format
  bufferCVHex,     // Clarity bufferCV encoding
  principalCVHex,  // Clarity principalCV encoding
} from 'veritasbtc-sdk';

Error handling

import {
  VeritasError,
  NotFoundError,
  NetworkError,
  InvalidInputError,
  TimeoutError,
} from 'veritasbtc-sdk';

try {
  const result = await client.verifyHash(hash);
} catch (err) {
  if (err instanceof NotFoundError) {
    // hash is not anchored on Bitcoin
  } else if (err instanceof NetworkError) {
    console.error(err.status); // HTTP status code
  }
}

Types

interface AnchorRecord {
  hash: string;          // SHA-256 hex (64 chars)
  owner: string;         // Stacks address
  blockHeight: number;   // Bitcoin-anchored Stacks block
  contentType: string;   // declared content type
  label: string;         // human-readable label
}

interface IdentityRecord {
  name: string;
  verificationLevel: number;
  registeredAt: number;  // block height
  status: 'active' | 'revoked';
}

interface VerifyResult {
  verified: boolean;
  hash: string;
  anchor: AnchorRecord | null;
  identity: IdentityRecord | null;
}

interface BatchVerifyResult extends VerifyResult {
  index: number;
  error: string | null;
}

Smart contracts

Deployed on Stacks mainnet (Bitcoin-anchored):

| Contract | Address | |---|---| | veritasbtc-anchors | SP3BHPVZEKANVD62KDME41G0E02KGPMKRANWF5PQK | | veritasbtc-identity | SP3BHPVZEKANVD62KDME41G0E02KGPMKRANWF5PQK |

License

MIT © VeritasBTC