{"_id":"@1matrix/traceability-sdk","_rev":"2-da4459499ec1c22d876444299d2d474e","name":"@1matrix/traceability-sdk","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@1matrix/traceability-sdk","version":"1.0.0","keywords":["blockchain","traceability","verification","keccak256","ethereum","data-integrity","canonical-json"],"author":{"name":"1MATRIX"},"license":"MIT","_id":"@1matrix/traceability-sdk@1.0.0","maintainers":[{"name":"hieu1m","email":"hieutt@1matrix.com"},{"name":"manhtv","email":"manhtv@1matrix.com"}],"homepage":"https://github.com/OneMatrixL1/traceability-v1/tree/main/packages/sdk#readme","bugs":{"url":"https://github.com/OneMatrixL1/traceability-v1/issues"},"dist":{"shasum":"2e8b988613f053cd35bc4f47d9faf56e403413f6","tarball":"https://registry.npmjs.org/@1matrix/traceability-sdk/-/traceability-sdk-1.0.0.tgz","fileCount":8,"integrity":"sha512-I5qHBeC+4NFP/vCjFuSfW+nfaIiL70cysOJ99z130Gm+A3FgTFVOVk0ZORO70aMbpoTDv2d4qLxeDJ9XYEy+5Q==","signatures":[{"sig":"MEQCIHoeT6gzKZEAJb5m7z7jN58DnTavf9S9OfF8WbVEdyTsAiAB8zYbPJr5gKWw+Ac5vMCzUHsXPBugaZZmm5DYpbCrTA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68373},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"321f5a84f1eb21757ca05dd2b94a682603099e65","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts --clean","prebuild":"node scripts/copy-abi.js","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm build && pnpm typecheck && pnpm test"},"_npmUser":{"name":"manhtv","email":"manhtv@1matrix.com"},"repository":{"url":"git+https://github.com/OneMatrixL1/traceability-v1.git","type":"git","directory":"packages/sdk"},"_npmVersion":"10.9.4","description":"Client SDK for verifying blockchain traceability data","directories":{},"_nodeVersion":"22.21.0","dependencies":{"@noble/hashes":"^1.8.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","vitest":"^1.0.4","typescript":"^5.3.3","@types/node":"^20.10.0","@vitest/coverage-v8":"^1.0.4"},"peerDependencies":{"viem":"^2.0.0"},"peerDependenciesMeta":{"viem":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/traceability-sdk_1.0.0_1763610462709_0.249317707161832","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@1matrix/traceability-sdk","version":"1.0.1","description":"Client SDK for verifying blockchain traceability data","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"prebuild":"node scripts/copy-abi.js","build":"tsup src/index.ts --format cjs,esm --dts --clean","dev":"tsup src/index.ts --format cjs,esm --dts --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","prepublishOnly":"pnpm build && pnpm typecheck && pnpm test"},"keywords":["blockchain","traceability","verification","keccak256","ethereum","data-integrity","canonical-json"],"author":{"name":"1MATRIX"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/OneMatrixL1/traceability-v1.git","directory":"packages/sdk"},"bugs":{"url":"https://github.com/OneMatrixL1/traceability-v1/issues"},"homepage":"https://github.com/OneMatrixL1/traceability-v1/tree/main/packages/sdk#readme","engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"peerDependencies":{"viem":"^2.0.0"},"dependencies":{"@noble/hashes":"^1.8.0"},"peerDependenciesMeta":{"viem":{"optional":false}},"devDependencies":{"@types/node":"^20.10.0","@vitest/coverage-v8":"^1.0.4","tsup":"^8.0.1","typescript":"^5.3.3","vitest":"^1.0.4"},"_id":"@1matrix/traceability-sdk@1.0.1","gitHead":"321f5a84f1eb21757ca05dd2b94a682603099e65","_nodeVersion":"22.21.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-/ZONlr+Tx/w/O9uOk580wlSSLisgWt7T2O181BmhR9a/2NCbClNB215JPDj4PEeQ9FgWzsg7SgQbpzWPagUOPQ==","shasum":"c3dc1961bb6f2f724b0dfd8a20dd7936e8cd3bd9","tarball":"https://registry.npmjs.org/@1matrix/traceability-sdk/-/traceability-sdk-1.0.1.tgz","fileCount":8,"unpackedSize":68373,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDkJF1XJAGIVTma4Sgl1DE9GtlwBit+KXPLU3BHEg18HAIhAPQj8iDqA8XKzv7aZ79Xyuhg4Hk3brcB79+pGzAi6c4O"}]},"_npmUser":{"name":"manhtv","email":"manhtv@1matrix.com"},"directories":{},"maintainers":[{"name":"hieu1m","email":"hieutt@1matrix.com"},{"name":"manhtv","email":"manhtv@1matrix.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/traceability-sdk_1.0.1_1763610596300_0.040939550194639684"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-20T03:47:42.602Z","modified":"2025-11-20T03:49:56.743Z","1.0.0":"2025-11-20T03:47:42.903Z","1.0.1":"2025-11-20T03:49:56.473Z"},"bugs":{"url":"https://github.com/OneMatrixL1/traceability-v1/issues"},"author":{"name":"1MATRIX"},"license":"MIT","homepage":"https://github.com/OneMatrixL1/traceability-v1/tree/main/packages/sdk#readme","keywords":["blockchain","traceability","verification","keccak256","ethereum","data-integrity","canonical-json"],"repository":{"type":"git","url":"git+https://github.com/OneMatrixL1/traceability-v1.git","directory":"packages/sdk"},"description":"Client SDK for verifying blockchain traceability data","maintainers":[{"name":"hieu1m","email":"hieutt@1matrix.com"},{"name":"manhtv","email":"manhtv@1matrix.com"}],"readme":"# @traceability-v1/sdk\n\n[![npm version](https://badge.fury.io/js/%40traceability-v1%2Fsdk.svg)](https://www.npmjs.com/package/@traceability-v1/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/@traceability-v1/sdk.svg)](https://nodejs.org)\n\nClient SDK for verifying blockchain traceability data.\n\n## Features\n\n- ✅ **Canonical Hashing**: Property-order-independent JSON hashing by default\n- 🔍 **Dual-Mode Verification**: Online (RPC fetch) and offline (cached receipts)\n- 📦 **Tiny Bundle**: ~20KB ESM, tree-shakeable\n- 🔒 **Type-Safe**: Full TypeScript support with strict types\n- 🚀 **Zero Config**: Works out of the box with sensible defaults\n- ⚡ **Fast**: Uses `@noble/hashes` for performance\n\n## Installation\n\n```bash\nnpm install @traceability-v1/sdk\n# or\npnpm add @traceability-v1/sdk\n# or\nyarn add @traceability-v1/sdk\n```\n\n## Quick Start\n\n### Online Verification\n\n```typescript\nimport { verifyData } from '@traceability-v1/sdk';\n\nconst isValid = await verifyData({\n  txHash: '0xabc123...',\n  logIndex: 0,\n  data: originalBatchData,\n  rpcUrl: 'http://localhost:8545',\n});\n\nconsole.log(isValid ? '✅ Verified' : '❌ Not verified');\n```\n\n### Offline Verification\n\n```typescript\nimport { verifyData } from '@traceability-v1/sdk';\n\nconst isValid = await verifyData({\n  txHash: '0xabc123...',\n  logIndex: 0,\n  data: originalBatchData,\n  txReceipt: cachedReceipt,\n});\n\nconsole.log(isValid ? '✅ Verified' : '❌ Not verified');\n```\n\n### Canonical Hashing (Default Behavior)\n\nBy default, the SDK uses canonical hashing which sorts object keys before hashing. This ensures consistent hashes regardless of property order:\n\n```typescript\nimport { verifyData, hashData } from '@traceability-v1/sdk';\n\n// These two objects have the same data but different property order\nconst data1 = { a: 1, b: 2, c: 3 };\nconst data2 = { c: 3, a: 1, b: 2 };\n\n// Default behavior (canonical=true) - hashes are the same\nconst hash1 = hashData(data1); // Same ✅\nconst hash2 = hashData(data2); // Same ✅\n\n// Disable canonical if you need exact property order preservation\nconst hash3 = hashData(data1, { canonical: false }); // Different\nconst hash4 = hashData(data2, { canonical: false }); // Different\n\n// Verification uses canonical=true by default\nconst isValid = await verifyData({\n  txHash: '0xabc123...',\n  data: batchData,\n  rpcUrl: 'http://localhost:8545',\n  // canonical: true is the default\n});\n\n// Set canonical=false if your API also uses non-canonical hashing\nconst isValidNonCanonical = await verifyData({\n  txHash: '0xabc123...',\n  data: batchData,\n  rpcUrl: 'http://localhost:8545',\n  canonical: false, // Preserve exact property order\n});\n```\n\n## API Reference\n\nSee [SDK_DESIGN.md](../../docs/SDK_DESIGN.md) for complete documentation.\n\n## Development\n\n### Building\n\nThe build process automatically copies the latest ABI from the trace-contract package:\n\n```bash\n# Build with auto-generated ABI\npnpm build\n\n# The prebuild script runs automatically:\n# 1. Copies ABI from packages/trace-contract/dist/abi.js\n# 2. Generates src/abi.ts\n# 3. Builds SDK with latest ABI\n```\n\n**Note**: The trace-contract package must be built first:\n\n```bash\ncd packages/trace-contract\npnpm build\n```\n\n### Testing\n\n```bash\npnpm test          # Run tests once\npnpm test:watch    # Watch mode\npnpm test:coverage # With coverage\n```\n\n### Type Checking\n\n```bash\npnpm typecheck\n```\n\n## Dependencies\n\n- **viem**: Ethereum client library for transaction receipt handling and log decoding\n- **@noble/hashes**: Lightweight cryptographic hashing (keccak256)\n\n**Note**: Contract ABI is auto-generated from `@traceability-v1/trace-contract` during build.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}