{"_id":"@beebozy/dillithium-sdk","name":"@beebozy/dillithium-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@beebozy/dillithium-sdk","version":"0.1.0","description":"Browser-safe TypeScript SDK for the CKB Dilithium lock script: ML-DSA-65 key generation, lock args derivation, transaction hash signing, and witness serialization.","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"dillithium-wallet":"dist/src/cli.js"},"exports":{".":{"types":"./dist/index.d.ts","browser":"./dist/index.js","default":"./dist/index.js"},"./wasm/dillithium_wasm.wasm":"./dist/wasm/dillithium_wasm.wasm"},"browser":{"./dist/index.js":"./dist/index.js"},"sideEffects":false,"engines":{"node":">=20"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/beebozy/ckb-pq-dillithium-.git","directory":"sdk"},"homepage":"https://github.com/beebozy/ckb-pq-dillithium-#readme","bugs":{"url":"https://github.com/beebozy/ckb-pq-dillithium-/issues"},"keywords":["ckb","nervos","dilithium","ml-dsa","post-quantum","cryptography","wasm","typescript","sdk"],"scripts":{"build:ts":"tsc -p tsconfig.json","build:wasm:asset":"node ./scripts/copy-wasm.mjs","build":"npm run build:ts && npm run build:wasm:asset","prepack":"npm run build","test":"npm run build && tsx --test test/*.test.ts"},"devDependencies":{"@types/node":"^24.0.1","tsx":"^4.20.3","typescript":"^5.8.3"},"_id":"@beebozy/dillithium-sdk@0.1.0","gitHead":"4ab242c0704151ee8555bf63efc1338e07d89c79","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-6WG+YclHdb2LkffoRGVV5FKxJO9SqOn7j2FJ6c8823C5hm7x4R1yLLJBFALJTmjAsqKn1pP3ylBDALgIaFNe1Q==","shasum":"55ffcfa29b0459de1190de7cc3654509989d266e","tarball":"https://registry.npmjs.org/@beebozy/dillithium-sdk/-/dillithium-sdk-0.1.0.tgz","fileCount":27,"unpackedSize":3268948,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCAdeeIIzvYM9ZwvfS13yRb+2zg/G2rwWoC4Z6kGha7bQIhAJ4loZk7Dlsg6wzeZjP34QvZFphT5PH3myr1gh6Usq9m"}]},"_npmUser":{"name":"beebozy","email":"musahabeeblai@gmail.com"},"directories":{},"maintainers":[{"name":"beebozy","email":"musahabeeblai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dillithium-sdk_0.1.0_1784928869327_0.9733448040928305"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-24T21:34:29.154Z","0.1.0":"2026-07-24T21:34:29.550Z","modified":"2026-07-24T21:34:29.760Z"},"maintainers":[{"name":"beebozy","email":"musahabeeblai@gmail.com"}],"description":"Browser-safe TypeScript SDK for the CKB Dilithium lock script: ML-DSA-65 key generation, lock args derivation, transaction hash signing, and witness serialization.","homepage":"https://github.com/beebozy/ckb-pq-dillithium-#readme","keywords":["ckb","nervos","dilithium","ml-dsa","post-quantum","cryptography","wasm","typescript","sdk"],"repository":{"type":"git","url":"git+https://github.com/beebozy/ckb-pq-dillithium-.git","directory":"sdk"},"bugs":{"url":"https://github.com/beebozy/ckb-pq-dillithium-/issues"},"readme":"# @ckb/dillithium-sdk\n\nExperimental TypeScript SDK and CLI wallet for the CKB Dilithium lock script.\n\nThis package now provides both:\n\n- low-level Dilithium helpers for key generation, lock args derivation, hashing, signing, and witness encoding\n- a Node-first wallet layer for CKB address derivation, live-cell lookup, balance polling, transaction construction, signing, submission, and confirmation waiting\n\n## Install\n\n```bash\nnpm install @ckb/dillithium-sdk\n```\n\n## What this package does\n\nThe on-chain lock script expects:\n\n- `args`: `blake2b-256(publicKey)` using CKB personalization\n- `witness.lock`: serialized as  \n  `[u32 pubkey_len LE | pubkey | u32 sig_len LE | sig]`\n- ML-DSA-65 public keys and signatures\n- signatures over the witness-aware CKB signing message (raw transaction hash + serialized witnesses)\n\nThis SDK mirrors those exact formats and adds wallet helpers around them.\n\n## Runtime\n\nThis package is currently **Node.js-first**, with browser-oriented packaging work in progress.\n\nIt bundles a compiled WebAssembly module and loads it from the installed package at runtime. It is suitable for:\n\n- Node.js apps\n- CLI tools\n- server-side wallet tooling\n- test scripts\n\nBrowser usage is still considered experimental until more real-world frontend transfer validation is complete.\n\n## Quick start: low-level SDK\n\n```ts\nimport {\n  buildLockScript,\n  buildWitnessLock,\n  computeLockArgs,\n  generateKeypair,\n  signTxHash,\n  verifySignature,\n} from \"@ckb/dillithium-sdk\";\n\nconst { publicKey, secretKey } = await generateKeypair();\nconst lockArgs = await computeLockArgs(publicKey);\n\nconst lock = await buildLockScript({\n  codeHash: \"0x<deployed_code_hash>\",\n  hashType: \"data2\",\n  publicKey,\n});\n\nconst txHash = new Uint8Array(32);\nconst signature = await signTxHash(secretKey, txHash);\nconst ok = await verifySignature(publicKey, txHash, signature);\nconst witnessLock = buildWitnessLock(publicKey, signature);\n\nconsole.log({\n  lockArgs: Buffer.from(lockArgs).toString(\"hex\"),\n  lock,\n  witnessBytes: witnessLock.length,\n  ok,\n});\n```\n\n## Quick start: wallet helpers\n\n```ts\nimport {\n  CkbRpcClient,\n  addressFromPublicKey,\n  buildLockScript,\n  buildSignedTransfer,\n  generateKeypair,\n  getBalanceSummary,\n  waitForBalance,\n  waitForTransactionConfirmation,\n} from \"@ckb/dillithium-sdk\";\n\nconst scriptConfig = {\n  codeHash: \"0x<dillithium_code_hash>\",\n  hashType: \"data2\",\n  network: \"testnet\",\n  cellDep: {\n    outPoint: {\n      txHash: \"0x<deployment_tx_hash>\",\n      index: \"0x0\",\n    },\n    depType: \"code\",\n  },\n};\n\nconst { publicKey, secretKey } = await generateKeypair();\nconst lock = await buildLockScript({\n  codeHash: scriptConfig.codeHash,\n  hashType: scriptConfig.hashType,\n  publicKey,\n});\nconst address = await addressFromPublicKey(publicKey, scriptConfig);\n\nconst client = new CkbRpcClient({\n  rpcUrl: \"https://testnet.ckb.dev/rpc\",\n  indexerUrl: \"https://testnet.ckb.dev/indexer\",\n});\n\nawait waitForBalance(client, publicKey, scriptConfig, {\n  minCapacity: 80_00000000n,\n});\n\nconst balance = await getBalanceSummary(client, lock);\nconsole.log(address, balance.totalCapacity.toString());\n\nconst liveCells = await client.getCells(lock);\nconst signed = await buildSignedTransfer({\n  cells: liveCells,\n  fromLock: lock,\n  toLock: lock,\n  amount: 80_00000000n,\n  scriptConfig,\n  publicKey,\n  secretKey,\n});\n\nconst txHash = await client.sendTransaction(signed.transaction);\nawait waitForTransactionConfirmation(client, { txHash });\nconsole.log(txHash);\n```\n\n## CLI wallet\n\nThe package exposes a CLI named `dillithium-wallet`.\n\n### Generate a key file\n\n```bash\ndillithium-wallet keygen --out ./wallet.json --network testnet\n```\n\n### Print the Dilithium CKB address\n\n```bash\ndillithium-wallet address \\\n  --key-file ./wallet.json \\\n  --network testnet\n```\n\n### Wait for funding to appear\n\n```bash\ndillithium-wallet wait \\\n  --key-file ./wallet.json \\\n  --network testnet \\\n  --rpc-url https://testnet.ckb.dev/rpc \\\n  --indexer-url https://testnet.ckb.dev/indexer \\\n  --min-ckb 80\n```\n\n### Check balance or wait for it\n\n```bash\ndillithium-wallet balance \\\n  --key-file ./wallet.json \\\n  --network testnet \\\n  --rpc-url https://testnet.ckb.dev/rpc \\\n  --indexer-url https://testnet.ckb.dev/indexer\n```\n\n```bash\ndillithium-wallet balance \\\n  --key-file ./wallet.json \\\n  --network testnet \\\n  --rpc-url https://testnet.ckb.dev/rpc \\\n  --indexer-url https://testnet.ckb.dev/indexer \\\n  --wait \\\n  --min-ckb 80\n```\n\n### Confirm a known outpoint over RPC\n\n```bash\ndillithium-wallet check-outpoint \\\n  --key-file ./wallet.json \\\n  --network testnet \\\n  --rpc-url https://testnet.ckb.dev/rpc \\\n  --tx-hash 0x132b03333e9e8272ed59ed57beefbe00a6955021a03e349987d150decbe6e6a7 \\\n  --index 0\n```\n\nUse this when explorer or raw RPC shows a funding transaction but `balance` still reports zero. The command checks the exact outpoint with node RPC and tells you whether it is still live and whether its lock matches the wallet derived from the selected key file.\n\n### Dry-run a transfer\n\n```bash\ndillithium-wallet transfer \\\n  --key-file ./wallet.json \\\n  --network testnet \\\n  --rpc-url https://testnet.ckb.dev/rpc \\\n  --indexer-url https://testnet.ckb.dev/indexer \\\n  --to ckt1... \\\n  --amount-ckb 80 \\\n  --dry-run\n```\n\n### Broadcast a transfer and wait for follow-up visibility\n\n```bash\ndillithium-wallet transfer \\\n  --key-file ./wallet.json \\\n  --network testnet \\\n  --rpc-url https://testnet.ckb.dev/rpc \\\n  --indexer-url https://testnet.ckb.dev/indexer \\\n  --to ckt1... \\\n  --amount-ckb 80 \\\n  --wait\n```\n\n## API additions\n\n### Address helpers\n\n- `encodeCkbAddress(script, network)`\n- `decodeCkbAddress(address)`\n- `addressFromPublicKey(publicKey, scriptConfig)`\n- `parseAddressToLock(address)`\n\n### Wallet helpers\n\n- `CkbRpcClient`\n- `WalletError`\n- `getBalanceSummary(client, lock)`\n- `getWalletState(client, publicKey, scriptConfig)`\n- `waitForBalance(client, publicKey, scriptConfig, options?)`\n- `waitForTransactionConfirmation(client, options)`\n- `validateTransferRequest(options, recipientNetwork?)`\n- `buildTransferTransaction(options)`\n- `sealTransaction(options)`\n- `buildSignedTransfer(options)`\n- `computeTransactionHash(rawTransaction)`\n- `minimumCellCapacity(lock, dataHex?, type?)`\n\n### Constants\n\n- `WITNESS_LOCK_BYTES`\n- `DEFAULT_FEE_RATE`\n- `SHANNONS_PER_CKB`\n\n## Notes\n\n- This wallet path currently supports **plain CKB transfers only**.\n- It uses the repo’s current signing model: **sign the witness-aware CKB signing message**, not the raw transaction hash alone.\n- It does **not** yet support UDTs, DAO, multisig, or browser packaging.\n- The CLI expects deployment metadata in `deployment/scripts.json` in the current working directory to include the `dillithium-lock` entry for the chosen network.\n- The balance/transfer flow requires an indexer-backed endpoint for `get_cells`.\n- `check-outpoint` uses raw RPC `get_live_cell`, which is useful for confirming a known funding cell but does not replace indexer-backed balance discovery.\n- For test suites, build the contract artifact first so `ckb-testtool` can load `build/release/dillithium-lock`.\n\n## Practical wallet lifecycle\n\n1. generate wallet\n2. derive address\n3. fund from faucet or another wallet\n4. wait for the funding tx to be indexed\n5. confirm funded balance\n6. if explorer shows funds but `balance` stays zero, run `check-outpoint` on the known funding outpoint to confirm the cell is live and belongs to this wallet\n7. dry-run the transfer\n8. broadcast the transfer\n9. wait for tx visibility\n10. verify the balance decreased\n\n## Can the faucet be used directly from the CLI?\n\nNot in this package today.\n\nThe current supported CLI flow starts before and after the faucet step, but does not claim faucet funds programmatically. That means:\n\n- use CLI to generate wallet and print address\n- fund that address via faucet UI or another funded sender\n- return to CLI for waiting, balance checks, dry-run, signing, and sending\n\n## Development\n\nFrom the repository root:\n\n```bash\nmake build CONTRACT=dillithium-lock\nnpm install\nnpm run build:wasm\nnpm run build:sdk\nnpm test\ncargo test --package tests\n```\n\n## Publishing checklist\n\nFrom the repository root:\n\n```bash\nmake build CONTRACT=dillithium-lock\nnpm install\nnpm run build:wasm\nnpm run build:sdk\nnpm test\ncargo test --package tests\n```\n\nFrom `sdk/`:\n\n```bash\nnpm pack --dry-run\nnpm publish --access public\n```\n\n## Repository\n\nSource: https://github.com/beebozy/ckb-pq-dillithium-\n","readmeFilename":"README.md","_rev":"1-13b8ef997ac6c201a50c2c2756bd3fe1"}