{"_id":"@b402ai/kohaku","name":"@b402ai/kohaku","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@b402ai/kohaku","version":"0.1.0","private":false,"description":"b402 execution adapter for Kohaku-compatible wallets and apps.","type":"module","main":"dist/src/index.js","types":"dist/src/index.d.ts","engines":{"node":">=22"},"sideEffects":false,"scripts":{"build":"tsc -p tsconfig.json","check":"tsc -p tsconfig.json --noEmit","clean":"rm -rf dist","format":"prettier --write .","format:check":"prettier --check .","lint":"eslint .","scan:secrets":"node scripts/scan-secrets.mjs","test":"npm run build && node --test dist/test/**/*.test.js","verify":"npm run check && npm run lint && npm run format:check && npm run test && npm run scan:secrets","test:e2e:swap":"npm run build && node --test --test-force-exit dist/test/private-swap.smoke.test.js"},"keywords":["b402","kohaku","privacy","railgun","gasless","defi"],"license":"MIT","dependencies":{"@kohaku-eth/plugins":"^0.0.1-alpha.7"},"peerDependencies":{"@b402ai/sdk":">=0.5.0"},"peerDependenciesMeta":{"@b402ai/sdk":{"optional":true}},"devDependencies":{"@eslint/js":"^9.25.0","@types/node":"^22.14.1","eslint":"^9.25.1","globals":"^16.0.0","prettier":"^3.5.3","typescript":"^5.8.3","typescript-eslint":"^8.30.1"},"gitHead":"bca39b88493e68f9ca84482937aa3b87fb27553d","_id":"@b402ai/kohaku@0.1.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-rOmVXh+2qC+YMiQw+OQjYsKXys3q7riTmD12gki0v6Nkzd2uKMH85FAkM7N9vNkh/GElujs8KGWKQgKCj9ritw==","shasum":"1095b364006d9f57fa30bf01895dea24b9d4e15f","tarball":"https://registry.npmjs.org/@b402ai/kohaku/-/kohaku-0.1.0.tgz","fileCount":30,"unpackedSize":53036,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHhq4r3FTeLTQPi13F0Nn6fGLjwOSzNjW7iot/rY7mMOAiAIgNR0tJV/RM994xrU7/byd4ml3JH6VtPrWw8TW5/9BA=="}]},"_npmUser":{"name":"mayurc9","email":"mayur@vistara.dev"},"directories":{},"maintainers":[{"name":"mayurc9","email":"mayur@vistara.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kohaku_0.1.0_1776892944474_0.8637857842661081"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-22T21:22:24.400Z","0.1.0":"2026-04-22T21:22:24.620Z","modified":"2026-04-22T21:22:24.797Z"},"maintainers":[{"name":"mayurc9","email":"mayur@vistara.dev"}],"description":"b402 execution adapter for Kohaku-compatible wallets and apps.","keywords":["b402","kohaku","privacy","railgun","gasless","defi"],"license":"MIT","readme":"# @b402ai/kohaku\n\nA b402 execution adapter for Kohaku-compatible wallets and apps.\n\nThe package implements a Kohaku-style plugin using\n`@kohaku-eth/plugins` types and routes execution through the b402 SDK. Wallets\nand apps get a small privacy surface for users:\n\n- view shielded balances\n- prepare shield and unshield operations\n- execute shield and unshield through b402\n- expose private swap, lend, and redeem actions as explicit extensions\n\nThe end-user value is simple: privacy actions can be initiated from a familiar\nwallet or app flow while b402 handles the execution path behind the adapter.\n\n## Who This Is For\n\nWallet teams can use this adapter to add a privacy plugin surface without\nbuilding Railgun/b402 execution plumbing into the wallet itself.\n\nApp developers can use the same runtime to offer private actions such as swap,\nlend, and redeem without inventing a separate app-specific privacy API.\n\nSDK evaluators can run the examples and smoke tests to inspect the integration\nboundary: Kohaku-compatible types at the edge, b402 execution underneath.\n\n## Why It Matters\n\nMost privacy flows force users into a separate app. This adapter is structured\nfor the wallet and app surface where users already make decisions:\n\n- the wallet can show shielded balances next to an account\n- the user can prepare an operation before execution\n- app-level private DeFi actions can share the same runtime and account context\n- transaction hashes stay redacted in examples by default\n\n## User Flow\n\nA wallet can register the adapter as a Kohaku-compatible plugin:\n\n1. The user connects a wallet or account.\n2. The app reads `plugin.instanceId()` and `plugin.balance()`.\n3. The user prepares a shield or unshield action.\n4. The prepared operation executes through `b402.execute(...)`.\n5. The app refreshes status and shows updated private balances.\n\nApps that want higher-level private actions can use the execution extensions:\n\n- `execution.privateSwap(...)`\n- `execution.privateLend(...)`\n- `execution.privateRedeem(...)`\n\nThese are intentionally separate from the minimal plugin surface so wallet\nintegrators can start with balances and shield/unshield before enabling private\nDeFi actions.\n\n## Supported Surface\n\n| Capability          | Surface                         | Status                                      |\n| ------------------- | ------------------------------- | ------------------------------------------- |\n| Shielded balance    | `plugin.balance()`              | Supported on Base through b402 status       |\n| Raw b402 status     | `plugin.rawStatus()`            | Supported                                   |\n| Shield              | `plugin.prepareShield()`        | Supported                                   |\n| Unshield            | `plugin.prepareUnshield()`      | Supported to the runtime smart wallet       |\n| Private swap        | `execution.privateSwap()`       | Supported, with env-gated live smoke test   |\n| Private lend        | `execution.privateLend()`       | SDK-backed extension, needs live smoke test |\n| Private redeem      | `execution.privateRedeem()`     | SDK-backed extension, needs live smoke test |\n| Private cross-chain | `execution.privateCrossChain()` | Experimental                                |\n\nThe default token registry and live tests are Base-oriented.\n\n## Install\n\n```bash\nnpm install @b402ai/kohaku @b402ai/sdk\n```\n\nFor local development beside the SDK repo:\n\n```bash\ncd ../b402-sdk\nnpm install\nnpm run build\n\ncd ../b402-kohaku\nnpm install --omit=peer\nnpm run verify\n```\n\n## Basic Usage\n\n```ts\nimport { createB402KohakuRuntime } from '@b402ai/kohaku';\n\nconst runtime = await createB402KohakuRuntime({\n  b402: {\n    privateKey: process.env.B402_PRIVATE_KEY,\n    chainId: 8453,\n    rpcUrl: process.env.B402_RPC_URL,\n    facilitatorUrl: process.env.B402_FACILITATOR_URL,\n    backendApiUrl: process.env.B402_BACKEND_API_URL,\n  },\n  plugin: {\n    chainId: 8453,\n  },\n});\n\nconst accountId = await runtime.plugin.instanceId();\nconst privateBalances = await runtime.plugin.balance();\n\nconst result = await runtime.execution.privateSwap({\n  from: 'USDC',\n  to: 'WETH',\n  amount: '0.01',\n  slippageBps: 75,\n});\n```\n\n## How Execution Works\n\nThe adapter depends on a b402 client with:\n\n```ts\nstatus(): Promise<B402StatusResult>;\nexecute(params: B402ExecuteParams): Promise<B402ExecuteResult>;\n```\n\n`plugin.balance()` calls `status()` and maps `shieldedBalances` into\nKohaku-style `AssetAmount<ERC20AssetId>` values.\n\nPrepared shield and unshield operations are lazy. Calling `prepareShield()` or\n`prepareUnshield()` returns an operation preview. Calling `operation.execute()`\ndispatches the matching b402 action:\n\n```ts\nawait client.execute({ action: 'shield', token: 'USDC', amount: '1' });\nawait client.execute({ action: 'unshield', token: 'USDC', amount: '1' });\n```\n\nThe extension layer uses the same dispatcher:\n\n```ts\nawait client.execute({ action: 'privateSwap', from: 'USDC', to: 'WETH', amount: '0.01' });\nawait client.execute({ action: 'privateLend', amount: '1', vault: 'steakhouse' });\nawait client.execute({ action: 'privateRedeem', vault: 'steakhouse' });\n```\n\n## Examples\n\n- [Wallet integration](docs/EXAMPLES.md#wallet-integration)\n- [App integration](docs/EXAMPLES.md#app-integration)\n- [Shield/unshield runbook](docs/DEMO-01-shield-unshield.md)\n- [Private swap runbook](docs/DEMO-02-private-swap.md)\n\nRun the live private swap smoke test only when you intentionally want to execute\nagainst a funded b402 environment:\n\n```bash\nB402_E2E_SWAP=1 npm run test:e2e:swap\n```\n\n## Development Checks\n\n```bash\nnpm run verify\nnpm audit --omit=dev --omit=peer\nnpm pack --dry-run\n```\n\n`npm run verify` runs TypeScript, ESLint, Prettier, unit tests, and the local\nsecret scan.\n\n## Security\n\n- Never commit `.env` files or private keys.\n- Transaction hashes from private runs should be treated as sensitive metadata.\n- Public examples should prefer redacted output, reproducible commands, and test\n  results over posting transaction links.\n","readmeFilename":"README.md","_rev":"1-16366cd99afd39d61b830fb6a5744f7a"}