@traceability-v1/sdk

Client SDK for verifying blockchain traceability data.

Features

• ✅ Canonical Hashing: Property-order-independent JSON hashing by default
• 🔍 Dual-Mode Verification: Online (RPC fetch) and offline (cached receipts)
• 📦 Tiny Bundle: ~20KB ESM, tree-shakeable
• 🔒 Type-Safe: Full TypeScript support with strict types
• 🚀 Zero Config: Works out of the box with sensible defaults
• ⚡ Fast: Uses @noble/hashes for performance

Installation

npm install @traceability-v1/sdk
# or
pnpm add @traceability-v1/sdk
# or
yarn add @traceability-v1/sdk

Quick Start

Online Verification

import { verifyData } from '@traceability-v1/sdk';

const isValid = await verifyData({
  txHash: '0xabc123...',
  logIndex: 0,
  data: originalBatchData,
  rpcUrl: 'http://localhost:8545',
});

console.log(isValid ? '✅ Verified' : '❌ Not verified');

Offline Verification

import { verifyData } from '@traceability-v1/sdk';

const isValid = await verifyData({
  txHash: '0xabc123...',
  logIndex: 0,
  data: originalBatchData,
  txReceipt: cachedReceipt,
});

console.log(isValid ? '✅ Verified' : '❌ Not verified');

Canonical Hashing (Default Behavior)

By default, the SDK uses canonical hashing which sorts object keys before hashing. This ensures consistent hashes regardless of property order:

import { verifyData, hashData } from '@traceability-v1/sdk';

// These two objects have the same data but different property order
const data1 = { a: 1, b: 2, c: 3 };
const data2 = { c: 3, a: 1, b: 2 };

// Default behavior (canonical=true) - hashes are the same
const hash1 = hashData(data1); // Same ✅
const hash2 = hashData(data2); // Same ✅

// Disable canonical if you need exact property order preservation
const hash3 = hashData(data1, { canonical: false }); // Different
const hash4 = hashData(data2, { canonical: false }); // Different

// Verification uses canonical=true by default
const isValid = await verifyData({
  txHash: '0xabc123...',
  data: batchData,
  rpcUrl: 'http://localhost:8545',
  // canonical: true is the default
});

// Set canonical=false if your API also uses non-canonical hashing
const isValidNonCanonical = await verifyData({
  txHash: '0xabc123...',
  data: batchData,
  rpcUrl: 'http://localhost:8545',
  canonical: false, // Preserve exact property order
});

API Reference

See SDK_DESIGN.md for complete documentation.

Development

Building

The build process automatically copies the latest ABI from the trace-contract package:

# Build with auto-generated ABI
pnpm build

# The prebuild script runs automatically:
# 1. Copies ABI from packages/trace-contract/dist/abi.js
# 2. Generates src/abi.ts
# 3. Builds SDK with latest ABI

Note: The trace-contract package must be built first:

cd packages/trace-contract
pnpm build

Testing

pnpm test          # Run tests once
pnpm test:watch    # Watch mode
pnpm test:coverage # With coverage

Type Checking

pnpm typecheck

Dependencies

• viem: Ethereum client library for transaction receipt handling and log decoding
• @noble/hashes: Lightweight cryptographic hashing (keccak256)

Note: Contract ABI is auto-generated from @traceability-v1/trace-contract during build.

License

MIT