{"_id":"@alx-protocol/sdk","_rev":"2-e28fc03bb0ea390f7ac8d42c7034a28c","name":"@alx-protocol/sdk","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@alx-protocol/sdk","version":"1.0.0","keywords":["alx","protocol","sdk","typescript","blocks","lineage","settlement","attribution","deterministic","verifiable"],"license":"MIT","_id":"@alx-protocol/sdk@1.0.0","maintainers":[{"name":"xandrlabsdev","email":"team@xandrlabs.ai"}],"homepage":"https://github.com/xandrlabs/alx-protocol#readme","bugs":{"url":"https://github.com/xandrlabs/alx-protocol/issues"},"dist":{"shasum":"e3d64b1754114583379a0a1f47e711446443f087","tarball":"https://registry.npmjs.org/@alx-protocol/sdk/-/sdk-1.0.0.tgz","fileCount":34,"integrity":"sha512-aBOWokZSoABkszVhNUn9dq6oYvCSbZMbZgjCL79Lf5BOMVmgsiBRkzOCMZg495FWC0U1eOFrye2GsIJmFm1QIg==","signatures":[{"sig":"MEQCIF3i4UVDMlc6WbRF1b6IatJVXbYo/bPKmCCDZf3yxwbnAiAatOzRgLhXW93vp7i8+LfdojakwVwEAZOOWNQLI5D/Ow==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84081},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./block":{"types":"./dist/block.d.ts","import":"./dist/block.js"},"./trace":{"types":"./dist/block-trace.d.ts","import":"./dist/block-trace.js"},"./merkle":{"types":"./dist/merkle.d.ts","import":"./dist/merkle.js"},"./replay":{"types":"./dist/replay.d.ts","import":"./dist/replay.js"},"./lineage":{"types":"./dist/block-lineage.d.ts","import":"./dist/block-lineage.js"},"./signatures":{"types":"./dist/signatures.d.ts","import":"./dist/signatures.js"},"./canonicalization":{"types":"./dist/canonicalization.d.ts","import":"./dist/canonicalization.js"}},"gitHead":"dc393ae1020191dcd7e9fa78a42e7c618f82b0fd","scripts":{"build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"xandrlabsdev","email":"team@xandrlabs.ai"},"repository":{"url":"git+https://github.com/xandrlabs/alx-protocol.git","type":"git","directory":"reference-implementations/typescript"},"_npmVersion":"11.12.1","description":"ALX Protocol TypeScript SDK — deterministic infrastructure for verifiable content, interoperable context, and traceable attribution","directories":{},"_nodeVersion":"20.19.0","dependencies":{"js-sha3":"^0.9.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^25.6.0"},"peerDependencies":{"ethers":"^6.0.0"},"peerDependenciesMeta":{"ethers":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.0_1777871722725_0.8526100804268295","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"_id":"@alx-protocol/sdk@1.0.1","dist":{"shasum":"af12d921fd8cac27e79c02e5c867f2c98087053b","tarball":"https://registry.npmjs.org/@alx-protocol/sdk/-/sdk-1.0.1.tgz","fileCount":75,"integrity":"sha512-Yvvn5NsF/d/PYfU7jXnJug5rVTmVx1pNthsJ/hF6qHXgvdQIvNNm9pMMHgedi3SAQ4I7y8Er76A/N3BmoJTTdQ==","signatures":[{"sig":"MEUCIAxIFfKeXy9eMB7OriWJtweEG+lMaaxM8HTEq2XtAaGSAiEA3RUG/RCyzhP2PeBWBypgVqDZYWxmsTeb+WlTIyTWKS4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAwrFzRABaPEZWcx1DyQ4ClEmnGCFTGLRR90feek8nj7AiEA3unJ9k2IvEkGfjD4E5CWcut/ILYcgMWw0sg1hFDgJkY="}],"unpackedSize":297100},"main":"./dist/index.js","name":"@alx-protocol/sdk","type":"module","_from":"file:alx-protocol-sdk-1.0.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=20 <23"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./p256":{"types":"./dist/p256.d.ts","import":"./dist/p256.js"},"./block":{"types":"./dist/block.d.ts","import":"./dist/block.js"},"./trace":{"types":"./dist/block-trace.d.ts","import":"./dist/block-trace.js"},"./eip712":{"types":"./dist/eip712.d.ts","import":"./dist/eip712.js"},"./merkle":{"types":"./dist/merkle.d.ts","import":"./dist/merkle.js"},"./replay":{"types":"./dist/replay.d.ts","import":"./dist/replay.js"},"./ed25519":{"types":"./dist/ed25519.d.ts","import":"./dist/ed25519.js"},"./lineage":{"types":"./dist/block-lineage.d.ts","import":"./dist/block-lineage.js"},"./hash-utils":{"types":"./dist/hash-utils.d.ts","import":"./dist/hash-utils.js"},"./middleware":{"types":"./dist/middleware.d.ts","import":"./dist/middleware.js"},"./signatures":{"types":"./dist/signatures.d.ts","import":"./dist/signatures.js"},"./canonicalization":{"types":"./dist/canonicalization.d.ts","import":"./dist/canonicalization.js"}},"license":"MIT","scripts":{"build":"tsc","typecheck":"tsc --noEmit"},"version":"1.0.1","_npmUser":{"name":"xandrlabsdev","email":"team@xandrlabs.ai"},"homepage":"https://alxprotocol.com","keywords":["alx","protocol","sdk","typescript","blocks","lineage","attribution","deterministic","verifiable"],"_resolved":"C:\\Users\\Lenovo\\AppData\\Local\\Temp\\795be6801d619fba2bb0341627e28b2c\\alx-protocol-sdk-1.0.1.tgz","_integrity":"sha512-Yvvn5NsF/d/PYfU7jXnJug5rVTmVx1pNthsJ/hF6qHXgvdQIvNNm9pMMHgedi3SAQ4I7y8Er76A/N3BmoJTTdQ==","_npmVersion":"10.8.2","description":"ALX Protocol TypeScript SDK — deterministic infrastructure for verifiable content, interoperable context, and traceable attribution","directories":{},"maintainers":[{"name":"xandrlabsdev","email":"team@xandrlabs.ai"}],"_nodeVersion":"20.20.2","dependencies":{"js-sha3":"^0.9.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^25.6.0"},"peerDependencies":{"ethers":">=6.17.0 <7","@noble/curves":">=1.8.1 <2","@noble/ed25519":"^3.0.0","@noble/secp256k1":"^3.0.0"},"peerDependenciesMeta":{"ethers":{"optional":true},"@noble/curves":{"optional":true},"@noble/ed25519":{"optional":true},"@noble/secp256k1":{"optional":true}},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.1_1789177555296_0.4161065999755904"}}},"time":{"created":"2026-05-04T05:15:22.610Z","modified":"2026-09-12T01:45:55.703Z","1.0.0":"2026-05-04T05:15:22.870Z","1.0.1":"2026-09-12T01:45:55.502Z"},"license":"MIT","homepage":"https://alxprotocol.com","keywords":["alx","protocol","sdk","typescript","blocks","lineage","attribution","deterministic","verifiable"],"description":"ALX Protocol TypeScript SDK — deterministic infrastructure for verifiable content, interoperable context, and traceable attribution","maintainers":[{"name":"xandrlabsdev","email":"team@xandrlabs.ai"}],"readme":"# @alx-protocol/sdk\r\n\r\nTypeScript/JavaScript SDK for ALX Protocol, an open protocol that gives every output, human or machine, a deterministic identity, declared lineage, and independent verification.\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install @alx-protocol/sdk\r\n```\r\n\r\n## Quickstart\r\n\r\nALX Protocol derives deterministic Block identity from content and parent hashes. `validateBlock()` recomputes stored identities, and Graph operations validate and traverse declared lineage. Applications select their own storage layer.\n\r\nThe example creates a financial risk report Block, adds a signed compliance review, validates the Graph, traces lineage, and detects modified Block data.\n\r\n```ts\r\nimport {\r\n  createBlock,\r\n  createSignedBlock,\r\n  validateBlock,\r\n  validateSignedBlock,\r\n  buildGraph,\r\n  validateGraph,\r\n  traceAttribution,\r\n} from \"@alx-protocol/sdk\";\r\n\r\n// Step 1: AI generates a draft financial risk summary\r\nconst report = createBlock({\r\n  workflow: \"compliance-audit-trail\",\r\n  task: \"generate-financial-risk-summary\",\r\n  agentRole: \"report-generation-agent\",\r\n  summary: \"Moderate liquidity risk due to increased debt obligations and uneven cash flow.\",\r\n  riskLevel: \"medium\",\r\n  outputType: \"draft-report\",\r\n});\r\n\r\nconsole.log(report.blockHash);          // deterministic identity\r\nconsole.log(validateBlock(report).ok);  // true\r\n\r\n// Step 2: Compliance reviewer checks the report and signs their review\r\n// (Use any Signer — EIP-712, Ed25519, cloud KMS, or a mock for testing)\r\nconst reviewSigner = {\r\n  algorithm: \"ed25519\",\r\n  getId: async () => \"compliance-reviewer-001\",\r\n  sign: async (data) => \"0x\" + Buffer.from(data).toString(\"hex\"), // mock\r\n};\r\n\r\nconst review = await createSignedBlock(\r\n  {\r\n    workflow: \"compliance-audit-trail\",\r\n    task: \"review-financial-risk-summary\",\r\n    agentRole: \"compliance-review-agent\",\r\n    reviewStatus: \"changes-required\",\r\n    findings: [\r\n      { issue: \"Risk summary lacks source references.\", severity: \"medium\" },\r\n      { issue: \"Confidence score missing.\", severity: \"low\" },\r\n    ],\r\n    outputType: \"compliance-review\",\r\n  },\r\n  [report.blockHash],  // ← linked to the original report\r\n  reviewSigner,\r\n);\r\n\r\nconsole.log(review.attestation.attester);   // \"compliance-reviewer-001\"\r\nconsole.log(review.attestation.algorithm);  // \"ed25519\"\r\n\r\n// Step 3: Validate the full pipeline\r\nconst graph = buildGraph([report, review.block]);\nconst verification = validateGraph(\n  review.block,\n  { kind: \"finite\", blocks: [report] },\n  {\n    protocolVersion: \"1\",\n    validationMode: \"closed-world\",\n    graphRoot: review.block.blockHash,\n    externalParents: [],\n  },\n);\nconsole.log(verification.status);  // \"valid\"\n\r\n// Step 4: Trace attribution from the review back to the source\r\nconst trace = traceAttribution(review.block.blockHash, graph);\nconsole.log(trace.nodes.length);  // 2\r\nconsole.log(trace.leaves);        // [report.blockHash] — the original source\r\n\r\n// Step 5: Tamper detection — any change invalidates the chain\r\nconst tampered = { ...report, content: { ...report.content, riskLevel: \"low\" } };\r\nconsole.log(validateBlock(tampered).ok);  // false — integrity broken\r\n```\r\n\r\nThe workflow produces linked Blocks for a report and review. The attestation remains outside Block identity. `validateBlock()` detects changes when stored identities no longer match recomputed values. PostgreSQL, S3, IPFS, and flat files are application storage options.\n\r\n## API Overview\r\n\r\n| Layer | Functions & Types |\r\n|-------|-------------------|\r\n| Canonicalization | `canonicalizeProtocolJson`, `CANONICALIZATION_ALGORITHM` |\r\n| Block Operations | `createBlock`, `validateBlock`, `deriveBlockHash`, `deriveContentHash` |\r\n| Signed Blocks | `createSignedBlock`, `validateSignedBlock`, `Signer`, `Verifier` |\r\n| Graph Validation | `validateGraph`, `GraphVerification`, `GraphValidationStatus`, `validateLineage`, `buildGraph`, `verifyGraph` |\n| Attribution Tracing | `traceAttribution`, `TraceNode`, `TraceEdge`, `AttributionTrace` |\r\n| Merkle Proofs | `buildMerkleTree`, `getMerkleProof`, `verifyMerkleProof` |\r\n| EIP-712 Signing | `Eip712Signer`, `Eip712Verifier` (requires `ethers` peer dependency) |\r\n| Replay Protection | `buildReplayScopeKey`, `validateReplayWindow` |\r\n| Hash Utilities | `normalizeHash`, `normalizeHashes`, `sanitizeImportedParentHashes`, `HASH_PATTERN`, `compareHashesConstantTime` |\n| Error Codes | `ErrorCode`, `protocolError` (all errors prefixed with `ALX_*`) |\r\n\r\nSub-path imports are available for tree-shaking:\n\r\n```ts\r\nimport { createBlock } from \"@alx-protocol/sdk/block\";\r\nimport { buildMerkleTree } from \"@alx-protocol/sdk/merkle\";\r\nimport { Eip712Signer } from \"@alx-protocol/sdk/eip712\";\n```\n\n## Canonical Graph verification\n\n`validateGraph(seed, source, context)` verifies the reachable Block Graph within an explicit verification context. Its status is `valid`, `invalid`, `incomplete`, or `resource_limit_reached`; `checked: false` is reserved for callers that did not request Graph verification.\n\nThe result applies only to the supplied context. A depth- or resource-bounded `valid` result does not claim that unexamined ancestry is valid. A missing required Block produces `incomplete`, while a known protocol violation takes precedence and produces `invalid`.\n\nThe older adjacency-only `validateGraph(graph, context?)` overload remains temporarily available for compatibility and is deprecated. New integrations should use the canonical three-argument operation.\n\n## Imported Parent Hashes\n\nUse `sanitizeImportedParentHashes()` when an importer must inspect untrusted lineage data before deciding whether to reject, quarantine, or repair a source record.\n\n```ts\nimport {\n  createBlock,\n  sanitizeImportedParentHashes,\n} from \"@alx-protocol/sdk\";\n\nconst importedParents: unknown = [\n  \"0x\" + \"A\".repeat(64),\n  \"invalid\",\n];\nconst inspection = sanitizeImportedParentHashes(importedParents);\n\nif (!inspection.ok) {\n  console.error(inspection.rejected, inspection.collectionErrors);\n} else {\n  const block = createBlock(\n    { task: \"review-imported-market-research\" },\n    inspection.parentHashes,\n  );\n  console.log(block.blockHash);\n}\n```\n\nThe result reports rejected values, normalized duplicates, and collection overflow. `parentHashes` is sorted and unique. Callers use it only when `ok` is `true`. Core Block creation does not call the sanitizer and remains fail closed.\n\n## Documentation\n\r\n- [Quick Start](https://alxprotocol.com/documentation/guides/quick-start)\n- [JavaScript Reference Surface](https://alxprotocol.com/documentation/specification/javascript-reference)\r\n- [Troubleshooting](https://alxprotocol.com/documentation/guides/troubleshooting)\r\n- [Specification](https://alxprotocol.com/documentation/specification/)\r\n- [Python and Rust Implementations](https://alxprotocol.com/documentation/reference/sdk)\r\n- [Documentation](https://alxprotocol.com/documentation/)\r\n\r\n## Adapters\r\n\r\nThis SDK is the protocol core. Optional adapters extend it to external systems (IPFS, MCP, EAS) without changing Block identity, hashing, or validation semantics. Adapters import from `@alx-protocol/sdk` — the protocol flows outward, never inward.\r\n\r\n## Protocol conformance\n\r\nThe TypeScript self-test executes every required core suite discovered through\nthe protocol's suite index. External TypeScript, Python,\nand Rust adapters exercise the portable JSON-interface cases; each maintained\nimplementation also uses native tests for language values that the adapter\ninterface cannot represent. A complete conformance claim requires every\napplicable required suite, not a fixed historical vector count.\n\r\n```bash\r\nnpx @alx-protocol/cli conformance run\r\n```\r\n\r\n## License\n\nMIT\n\n## Related Documents\n\n- [Protocol specification](https://alxprotocol.com/documentation/specification/)\n- [Conformance vectors](https://alxprotocol.com/documentation/conformance/vectors)\n","readmeFilename":"README.md"}