{"_id":"@cyfrin/battlechain-lib-js","_rev":"6-7e833ad5dd6d29fd7599ca7c80be0e99","name":"@cyfrin/battlechain-lib-js","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@cyfrin/battlechain-lib-js","version":"1.0.0","keywords":["battlechain","safe-harbor","ethereum","hardhat","ethers"],"license":"MIT OR Apache-2.0","_id":"@cyfrin/battlechain-lib-js@1.0.0","maintainers":[{"name":"updraft-cms-github-action","email":"updraft-cms-bot@cyfrin.io"},{"name":"mike_cyfrin","email":"mikhail@cyfrin.io"},{"name":"huntercyfrin","email":"hunter@cyfrin.io"},{"name":"craigcyfrin","email":"craig@cyfrin.io"},{"name":"equious","email":"travis@cyfrin.io"},{"name":"patrickalphac","email":"patrick@cyfrin.io"},{"name":"hans-cyfrin","email":"hans@cyfrin.io"},{"name":"oatmilk13014","email":"tilak@cyfrin.io"}],"homepage":"https://github.com/Cyfrin/battlechain-lib/tree/main/packages/battlechain-lib-js","bugs":{"url":"https://github.com/Cyfrin/battlechain-lib/issues"},"dist":{"shasum":"50e817a276bdcac365eeb2d6e148d1557791382b","tarball":"https://registry.npmjs.org/@cyfrin/battlechain-lib-js/-/battlechain-lib-js-1.0.0.tgz","fileCount":70,"integrity":"sha512-iupNJKkKy70VTji/GxHID0ktbH6vlkkBfcIvBmwkFb3LKdhmq3fQ+yCoJqGZwUfBPBu2gh8ZoIhPNUxHboTi0A==","signatures":[{"sig":"MEYCIQDLDbHPdsJTa43qJRnqJzerF0RzTijur172s6EJhbLhNwIhAJUdBjV/xPEpK/srVwLjRajqukEsjRDYr4i40lWv9MVC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":360643},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"eeb5a5b4bea2050716f1c17bad323f3180d627d1","scripts":{"gen":"npm run gen-abi && npm run gen-config","lint":"oxlint","test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","gen-abi":"tsx tools/gen-abi.ts","prepare":"npm run build","typecheck":"tsc --noEmit","gen-config":"tsx tools/gen-config.ts","test:watch":"vitest","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"patrickalphac","email":"patrick@cyfrin.io"},"repository":{"url":"git+https://github.com/Cyfrin/battlechain-lib.git","type":"git","directory":"packages/battlechain-lib-js"},"_npmVersion":"11.13.0","description":"JS/TS library for deploying on BattleChain and adopting Safe Harbor agreements. Mirrors cyfrin/battlechain-lib (Solidity).","directories":{},"_nodeVersion":"24.17.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","ethers":"^6.16.0","oxlint":"^1.71.0","vitest":"^2.1.0","typescript":"^5.6.0","@types/node":"^22.10.0"},"peerDependencies":{"ethers":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/battlechain-lib-js_1.0.0_1782148363531_0.3902707013039852","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@cyfrin/battlechain-lib-js","version":"1.1.0","keywords":["battlechain","safe-harbor","ethereum","hardhat","ethers"],"license":"MIT OR Apache-2.0","_id":"@cyfrin/battlechain-lib-js@1.1.0","maintainers":[{"name":"updraft-cms-github-action","email":"updraft-cms-bot@cyfrin.io"},{"name":"mike_cyfrin","email":"mikhail@cyfrin.io"},{"name":"huntercyfrin","email":"hunter@cyfrin.io"},{"name":"craigcyfrin","email":"craig@cyfrin.io"},{"name":"equious","email":"travis@cyfrin.io"},{"name":"patrickalphac","email":"patrick@cyfrin.io"},{"name":"hans-cyfrin","email":"hans@cyfrin.io"},{"name":"oatmilk13014","email":"tilak@cyfrin.io"}],"homepage":"https://github.com/Cyfrin/battlechain-lib/tree/main/packages/battlechain-lib-js","bugs":{"url":"https://github.com/Cyfrin/battlechain-lib/issues"},"dist":{"shasum":"068fdf4690dae6ccf35dbdcaefc1efffff535f9e","tarball":"https://registry.npmjs.org/@cyfrin/battlechain-lib-js/-/battlechain-lib-js-1.1.0.tgz","fileCount":70,"integrity":"sha512-AKeQdQlxlkej5K+4HHotYTBhZba1j77EQXx4MX83PaPxEaHIItYujH9F4a3CC6YeYl8U1AxpYRXxHgdWOTX7YA==","signatures":[{"sig":"MEQCIFPHlhurhGYOgNa2tlnbVeVROVt0M22ZqalPUiEcb53BAiAdn6rzcd/7UukgP9tYl4T4iAB4YFhyQqULLNLDt0iH9g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cyfrin%2fbattlechain-lib-js@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":401279},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"ef21eee876de7d1c6bd91ecf8de1f596e23680f4","scripts":{"gen":"npm run gen-abi && npm run gen-config","lint":"oxlint","test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","gen-abi":"tsx tools/gen-abi.ts","prepare":"npm run build","typecheck":"tsc --noEmit","gen-config":"tsx tools/gen-config.ts","test:watch":"vitest","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:20b9107d-93cd-4f36-9642-bd3e49172fdd"}},"repository":{"url":"git+https://github.com/Cyfrin/battlechain-lib.git","type":"git","directory":"packages/battlechain-lib-js"},"_npmVersion":"11.17.0","description":"JS/TS library for deploying on BattleChain and adopting Safe Harbor agreements. Mirrors cyfrin/battlechain-lib (Solidity).","directories":{},"_nodeVersion":"22.22.3","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.4","ethers":"^6.16.0","oxlint":"^1.71.0","vitest":"^4.1.9","typescript":"^6.0.3","@types/node":"^25.9.3"},"peerDependencies":{"ethers":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/battlechain-lib-js_1.1.0_1782158708652_0.5954093903352156","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@cyfrin/battlechain-lib-js","version":"1.1.1","keywords":["battlechain","safe-harbor","ethereum","hardhat","ethers"],"license":"MIT OR Apache-2.0","_id":"@cyfrin/battlechain-lib-js@1.1.1","maintainers":[{"name":"updraft-cms-github-action","email":"updraft-cms-bot@cyfrin.io"},{"name":"mike_cyfrin","email":"mikhail@cyfrin.io"},{"name":"huntercyfrin","email":"hunter@cyfrin.io"},{"name":"craigcyfrin","email":"craig@cyfrin.io"},{"name":"equious","email":"travis@cyfrin.io"},{"name":"patrickalphac","email":"patrick@cyfrin.io"},{"name":"hans-cyfrin","email":"hans@cyfrin.io"},{"name":"oatmilk13014","email":"tilak@cyfrin.io"}],"homepage":"https://github.com/Cyfrin/battlechain-lib/tree/main/packages/battlechain-lib-js","bugs":{"url":"https://github.com/Cyfrin/battlechain-lib/issues"},"dist":{"shasum":"a08c31636961356d54dba7b41b397b12b2a6ebbd","tarball":"https://registry.npmjs.org/@cyfrin/battlechain-lib-js/-/battlechain-lib-js-1.1.1.tgz","fileCount":70,"integrity":"sha512-Rke5GgJdJMP5S5eBT8ZsOX8LnHLBucelBYQ9XDp/pvTVGBaEFkPX2TFFsjCNp2703+RfE+wCJlGeJ1RSFxXLdA==","signatures":[{"sig":"MEQCIGb590rEpGA4mnY5OkdKwpTuhdjVUKLwMilNVcLLOjdMAiA461qGgl0KrAoBsG/9oL9aLUowz2V0W5SggPx449sqyQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cyfrin%2fbattlechain-lib-js@1.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":401499},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"c33885dcb1ed8aff311207a1b89c4ef3032c2f65","scripts":{"gen":"npm run gen-abi && npm run gen-config","lint":"oxlint","test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","gen-abi":"tsx tools/gen-abi.ts","prepare":"npm run build","typecheck":"tsc --noEmit","gen-config":"tsx tools/gen-config.ts","test:watch":"vitest","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:20b9107d-93cd-4f36-9642-bd3e49172fdd"}},"repository":{"url":"git+https://github.com/Cyfrin/battlechain-lib.git","type":"git","directory":"packages/battlechain-lib-js"},"_npmVersion":"11.17.0","description":"JS/TS library for deploying on BattleChain and adopting Safe Harbor agreements. Mirrors cyfrin/battlechain-lib (Solidity).","directories":{},"_nodeVersion":"22.22.3","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.4","ethers":"^6.16.0","oxlint":"^1.71.0","vitest":"^4.1.9","typescript":"^6.0.3","@types/node":"^25.9.3"},"peerDependencies":{"ethers":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/battlechain-lib-js_1.1.1_1782161300925_0.893405398028567","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-06-22T17:12:43.324Z","modified":"2026-07-15T14:50:21.077Z","1.0.0":"2026-06-22T17:12:43.667Z","1.1.0":"2026-06-22T20:05:08.807Z","1.1.1":"2026-06-22T20:48:21.074Z"},"bugs":{"url":"https://github.com/Cyfrin/battlechain-lib/issues"},"license":"MIT OR Apache-2.0","homepage":"https://github.com/Cyfrin/battlechain-lib/tree/main/packages/battlechain-lib-js","keywords":["battlechain","safe-harbor","ethereum","hardhat","ethers"],"repository":{"url":"git+https://github.com/Cyfrin/battlechain-lib.git","type":"git","directory":"packages/battlechain-lib-js"},"description":"JS/TS library for deploying on BattleChain and adopting Safe Harbor agreements. Mirrors cyfrin/battlechain-lib (Solidity).","maintainers":[{"email":"updraft-cms-bot@cyfrin.io","name":"updraft-cms-github-action"},{"email":"mikhail@cyfrin.io","name":"mike_cyfrin"},{"email":"patrick@cyfrin.io","name":"patrickalphac"},{"email":"hans@cyfrin.io","name":"hans-cyfrin"}],"readme":"# @cyfrin/battlechain-lib-js\n\nJS/TS library for deploying on [BattleChain](https://docs.battlechain.com) and adopting\n[Safe Harbor](https://docs.battlechain.com) agreements. Mirrors\n[`cyfrin/battlechain-lib`](https://github.com/Cyfrin/battlechain-lib) (Solidity)\nand [`cyfrin/battlechain-lib-py`](https://github.com/Cyfrin/battlechain-lib-py) (Python).\n\nethers v6, designed for [Hardhat](https://hardhat.org/) scripts and standalone\nscripts alike.\n\n- [Installation](#installation)\n- [Quick start](#quick-start)\n- [What's included](#whats-included)\n- [Supported networks](#supported-networks)\n- [Reference](#reference)\n- [Hardhat integration](#hardhat-integration)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\n```bash\nnpm install @cyfrin/battlechain-lib-js ethers\n# or\npnpm add @cyfrin/battlechain-lib-js ethers\n```\n\n`ethers` v6 is a peer dependency.\n\nRequires Node ≥ 20.\n\n## Quick start\n\nA minimal Hardhat script that deploys a contract via `BattleChainDeployer`,\ncreates a Safe Harbor agreement, adopts it, and requests attack mode:\n\n```ts\nimport { ethers } from \"ethers\";\nimport { network } from \"hardhat\";\n\nimport * as bc from \"@cyfrin/battlechain-lib-js\";\nimport VaultArtifact from \"../artifacts/src/MyVault.sol/MyVault.json\" with { type: \"json\" };\n\nconst { ethers: hethers } = await network.connect({ network: \"battlechain\", chainType: \"l1\" });\nconst [signer] = await hethers.getSigners();\n\n// 1. Deploy through BattleChainDeployer (auto-registers with AttackRegistry)\nconst { address: vaultAddress } = await bc.bcDeploy(signer, {\n  abi: VaultArtifact.abi,\n  bytecode: VaultArtifact.bytecode,\n  contractName: \"MyVault\",\n});\n\n// 2. Build agreement defaults — chain ID, CAIP-2 scope, and Safe Harbor URI\n//    are picked automatically based on chainId.\nconst details = bc.defaultAgreementDetails({\n  protocolName: \"MyProtocol\",\n  contacts: [{ name: \"Security Team\", contact: \"sec@example.xyz\" }],\n  contracts: bc.deployedContracts(),\n  recoveryAddress: signer.address,\n  chainId: bc.TESTNET_CHAIN_ID,\n});\n\n// 3. Create + 14-day commitment + adopt, all in one call\nconst salt = ethers.id(\"v1\");\nconst agreementAddress = await bc.createAndAdoptAgreement(\n  signer,\n  details,\n  signer.address,\n  salt,\n);\n\n// 4. Enter attack mode — only valid on BattleChain\nawait bc.requestAttackMode(signer, agreementAddress);\n\n// 5. Self-approve via the testnet MockRegistryModerator (state → UNDER_ATTACK).\n//    Mainnet has no equivalent helper — approval is a real DAO governance action.\nawait bc.approveAttackRequest(signer, agreementAddress);\n```\n\nFor Solidity verification, prefer the official\n[`@nomicfoundation/hardhat-verify`](https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify)\nplugin. The lib's `verifyContract` is a Vyper-friendly fallback for\nnon-Hardhat scripts (parity with battlechain-lib-py).\n\n## What's included\n\n| Module                       | Mirrors                        | What it does                                                                |\n| ---------------------------- | ------------------------------ | --------------------------------------------------------------------------- |\n| `config`                     | `src/BCConfig.sol`             | Chain IDs, CAIP-2 ids, addresses, Safe Harbor URIs, override registration   |\n| `types`                      | `src/types/AgreementTypes.sol` | `AgreementDetails`, `BountyTerms`, `BcAccount`, `BcChain`, `AgreementState` |\n| `abi`                        | forge artifacts                | Auto-generated ABI fragments                                                |\n| `builders`                   | `BCSafeHarbor` builders        | `defaultBountyTerms`, `defaultAgreementDetails`, …                          |\n| `deploy`                     | `src/BCDeploy.sol`             | `bcDeployCreate` / `_create2` / `_create3` + tracked deployments JSON       |\n| `safeHarbor`                 | `src/BCSafeHarbor.sol`         | `createAndAdoptAgreement`, `requestAttackMode`, …                           |\n| `query`                      | `src/BCQuery.sol`              | `isAttackable` (off-chain explorer API) + on-chain primitives               |\n| `verify`                     | `verifyContract.ts` fallback   | Vyper-friendly source verification via the explorer's API                   |\n| `errors`                     | Solidity custom errors         | Typed exceptions: `NotBattleChainError`, `ApiFailedError`, …                |\n| `createxChains`              | `src/CreateXChains.sol`        | Registry of CreateX-supported chains                                        |\n\n## Supported networks\n\n| Network | Chain ID | Status                  |\n| ------- | -------- | ----------------------- |\n| Mainnet | 626      | Available               |\n| Testnet | 627      | Available               |\n\nFor local Anvil/Hardhat or unsupported chains, register addresses with `setOverrides`:\n\n```ts\nimport * as bc from \"@cyfrin/battlechain-lib-js\";\n\nbc.setOverrides(31337, {\n  registry: \"0x…\",\n  factory: \"0x…\",\n  attackRegistry: \"0x…\",\n  deployer: \"0x…\",\n});\n```\n\n## Reference\n\n### `bcDeploy(signer, artifact, args?, opts?)`\n\nRoutes the deploy through `BattleChainDeployer` on BattleChain (auto-registers\nwith the AttackRegistry) and through `CreateX` on any of the\n[190+ supported chains](./src/createxChains.ts). Persists the deployed address\nto a per-chain JSON file (`.bc_deployments.json` by default) so subsequent\nscript runs can resolve it via `getTrackedAddress(name, chainId)` or\n`getTrackedContract(name, abi, runner, chainId)`.\n\nThe JSON file exists because deployer-routed contracts perform their CREATE\ninside `BattleChainDeployer`'s call context, so Hardhat's deployment tooling\n(ignition, hardhat-deploy) doesn't see them. Use Hardhat's deployment system\nfor vanilla deploys; use `bcDeploy` only for the contracts that **must** route\nthrough `BCDeployer` (so the AttackRegistry recognizes them as top-level).\n\n### `bcDeployCreate / bcDeployCreate2 / bcDeployCreate3`\n\nLower-level: take raw `initCode` (and `salt` for CREATE2/3) and return the new\naddress. Pair `bcDeployCreate2` with `buildInitCode(artifact, args)` for\ndeterministic addresses.\n\n### `defaultAgreementDetails(opts)` and friends\n\nBuild `AgreementDetails` with sensible defaults. On BattleChain it sets the\nBattleChain CAIP-2 scope and `BATTLECHAIN_SAFE_HARBOR_URI`; on other chains it\nfalls back to the chain's `eip155:` scope and the generic Safe Harbor V3 URI.\n\nThe default bounty terms match `BCSafeHarbor.defaultBountyTerms`: 10%, $1M cap,\nretainable, anonymous, no aggregate cap.\n\n### `approveAttackRequest(signer, agreementAddress)`\n\nOn testnet, calls the permissionless `MockRegistryModerator` at\n`0x1bC64E6F187a47D136106784f4E9182801535BD3` to self-approve an attack-mode\nrequest — moves the agreement from `ATTACK_REQUESTED` (2) to `UNDER_ATTACK`\n(3). Mirrors the `cast send <moderator> \"approveAttack(address)\"` flow from\nthe BattleChain testnet docs. Throws on mainnet (where approval is a real DAO\ngovernance action).\n\n### `isAttackable(runner, contractAddress)`\n\nMirrors `BCQuery.isAttackable`. Returns `true` if any Safe Harbor agreement\ncovering the contract is in `UNDER_ATTACK` or `PROMOTION_REQUESTED`. Resolves\ncoverage via the BattleChain block explorer (works for top-level **and** child\ncontracts).\n\nFor top-level-only on-chain checks (no HTTP), use `isTopLevelContractUnderAttack`.\n\n### Network overrides\n\nSame pattern as `BCBase._setBcAddresses`: register override addresses for any\nchain and they take precedence over the canonical registry.\n\n## Hardhat integration\n\nFor Hardhat 3 starters, see\n[`cyfrin/hardhat-battlechain-starter`](https://github.com/Cyfrin/hardhat-battlechain-starter).\nThe starter uses:\n\n- **hardhat-ignition** for vanilla deploys (`MockToken`, `Attacker`)\n- **`bcDeploy`** for `VulnerableVault` (must route through BCDeployer)\n- **hardhat-verify** for contract verification (no custom verify script)\n\nThis matches how `cyfrin/vyper-template` uses moccasin's `deployments.db` for\nvanilla deploys and `.bc_deployments.json` for BCDeployer-routed deploys.\n\n## Contributing\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nTo regenerate `src/abi.ts` from a fresh forge build of `cyfrin/battlechain-lib`:\n\n```bash\nnpm run gen-abi -- /path/to/battlechain-lib\n```\n\n## License\n\nDual-licensed under [MIT](./LICENCE-MIT) and [Apache-2.0](./LICENCE-APACHE) at\nyour option.\n","readmeFilename":"README.md"}