@warptoad/skinny-fat-imt-js 0.0.4 → 0.0.6

package/CREATE2.md

@@ -0,0 +1,218 @@
+# `@warptoad/skinny-fat-imt-js/create2`
+TODO way too much text. Re write this claude slop
+
+
+Deterministic CREATE2 deployment for **any** Hardhat 3 contract — not just the IMT libraries.
+
+Freeze a contract once into a self-contained JSON artifact, then deploy it to the same address on
+every chain, mine a vanity salt for it, and verify it on Etherscan and Sourcify. Nothing downstream
+ever recompiles.
+
+## Why freezing is necessary
+
+A CREATE2 address is a function of the exact init code, and init code is **not** reproducible by
+asking someone to compile the same source. It depends on the solc version, every optimizer setting,
+the evm target, and — because solc's metadata hash covers the source paths — on the exact paths the
+build assigned. Hardhat puts npm package versions in those paths, so bumping a dependency with
+byte-identical Solidity still moves the address.
+
+So `makeCreate2()` captures the bytes *and* the solc input that produced them. Everything after that
+works off the frozen object.
+
+```
+makeCreate2()            build time, needs Hardhat  →  Create2Artifact (plain JSON)
+predictCreate2Address()  pure
+deployCreate2()          runtime, viem only
+verifyOnEtherscan()      runtime, fetch only
+verifyOnSourcify()       runtime, fetch only
+```
+
+Only `makeCreate2` touches Hardhat, through a dynamic import — consumers who just deploy a published
+artifact never need Hardhat installed.
+
+## 1. Freeze
+
+Compile with the build profile you intend to publish, then:
+
+```ts
+import { makeCreate2 } from "@warptoad/skinny-fat-imt-js/create2";
+import { writeFile } from "node:fs/promises";
+
+const artifact = await makeCreate2("MyContract");
+await writeFile("MyContract.create2.json", JSON.stringify(artifact, null, 2));
+```
+
+Run it inside your Hardhat project (`npx hardhat run scripts/freeze.ts`). Hardhat keeps a single
+`artifacts/` tree rather than one per profile, so **whichever profile you compiled last is the one
+that gets frozen**. Pin every setting in that profile — anything left to a solc default will move the
+address on the next toolchain bump.
+
+Constructor arguments and libraries are part of the init code, so they are frozen too:
+
+```ts
+await makeCreate2("MyToken", { constructorArgs: ["Token", "TKN", 18n] });
+
+await makeCreate2("SkinnyFat", {
+  libraries: { FatIMTPoseidon2WriteStorage: "0x…", /* … */ },
+});
+```
+
+Unlinked bytecode still contains `__$…$__` placeholders and is not deployable, so a contract with
+libraries throws until you supply them. Deploy and mine the libraries first — their addresses become
+part of this contract's init code, and therefore of its address.
+
+Without a Hardhat project, pass the JSON yourself:
+
+```ts
+await makeCreate2({ artifact, buildInfo, buildInfoOutput });
+```
+
+## 2. Mine a vanity salt (optional)
+
+```ts
+import { create2MiningTarget } from "@warptoad/skinny-fat-imt-js/create2";
+
+console.log(create2MiningTarget(artifact));
+// { factory: "0x4e59…", initCodeHash: "0x…" }
+```
+
+Feed those to `create2crunch` / `createXcrunch`. Any salt works if you don't care about the address —
+`keccak256(toBytes("v1"))` is fine.
+
+The default factory doesn't bind the salt to a sender, so anyone can front-run the deployment. That's
+harmless: identical init code at the same address is the outcome you wanted anyway.
+
+> Leading zeros in a **library** address buy essentially nothing in gas — a linked library address is
+> embedded in code as `PUSH20`, not passed in calldata, and code deposit has no zero-byte discount.
+> Vanity here is branding.
+
+## 3. Deploy
+
+```ts
+import { deployCreate2 } from "@warptoad/skinny-fat-imt-js/create2";
+
+const { address, alreadyDeployed } = await deployCreate2({
+  artifact, salt, walletClient, publicClient,   // factory defaults to 0x4e59…
+});
+```
+
+Idempotent — if the address already holds code it returns without sending anything, which is the
+normal case on a chain where someone deployed before you.
+
+**On gas:** a failed CREATE2 *does not revert the caller*. The factory's inner create returns the zero
+address, the factory returns that, and your transaction succeeds — burning gas and deploying nothing.
+EIP-150 forwards only 63/64 of remaining gas to the inner call, so a limit that looks sufficient can
+leave the create just short. This bit us on a real 20KB library, where Hardhat's automatic gas came in
+below the estimate and produced a "successful" transaction with no contract. `deployCreate2` therefore
+estimates with headroom and re-reads the code afterwards, turning the silent failure into a thrown
+error. Pass `gas` to override.
+
+## 4. Verify
+
+Both clients handle submission and polling themselves, from the frozen `solcInput` — so they work on
+a machine with no sources and no compiler.
+
+```ts
+import { verifyOnEtherscan, verifyOnSourcify } from "@warptoad/skinny-fat-imt-js/create2";
+
+await verifyOnEtherscan({ artifact, address, chainId, apiKey });
+await verifyOnSourcify({ artifact, address, chainId });
+```
+
+Both return `{ outcome: "verified" | "already-verified" | "failed", message }`. Sourcify also returns
+`match`, which is `"exact_match"` when the metadata hash matched too — that only happens if your
+profile kept it (`bytecodeHash` other than `"none"`). Etherscan uses the v2 multichain API, so one key
+covers every supported chain.
+
+If you're verifying a contract in the same repo that compiled it, `npx hardhat verify` works too and
+Nomic maintains the explorer clients. These functions exist for everyone else: `hardhat-verify`
+resolves the solc input from local build-info, so it can't help someone deploying your published
+artifact from a repo that doesn't contain your sources.
+
+## 5. Check a deployment independently
+
+```ts
+import { matchesOnchainBytecode } from "@warptoad/skinny-fat-imt-js/create2";
+
+const code = await publicClient.getCode({ address });
+matchesOnchainBytecode(artifact, code, address);
+```
+
+Don't compare `deployedBytecode` directly — it never equals what's on chain, for two reasons that
+aren't defects. solc protects public library functions from direct `CALL`s by opening the runtime code
+with `PUSH20 <own address>; ADDRESS; EQ` and patching the real address in at construction; and
+immutables are written the same way. Both are zeros in the compiler's output. `matchesOnchainBytecode`
+splices the address in and masks the immutables before comparing.
+
+## This package's own frozen artifacts
+
+The IMT libraries are published pre-frozen, one JSON per contract, under
+`@warptoad/skinny-fat-imt-js/create2/evm-artifacts/<Contract>`:
+
+```ts
+import type { Create2Artifact } from "@warptoad/skinny-fat-imt-js/create2";
+import artifact from "@warptoad/skinny-fat-imt-js/create2/evm-artifacts/SkinnyIMTPoseidon2Read"
+  with { type: "json" };
+
+await deployCreate2({ artifact: artifact as Create2Artifact, salt, walletClient, publicClient });
+```
+
+Available: `SkinnyIMTPoseidon2Read`, `SkinnyIMTPoseidon2WriteEvent`, `SkinnyIMTPoseidon2WriteStorage`,
+`FatIMTPoseidon2Read`, `FatIMTPoseidon2WriteEvent`, `FatIMTPoseidon2WriteStorage` — the same files
+`npx hardhat gen-artifact-create2` writes to `create2-artifacts/`. A JSON import widens `0x…` strings
+to `string`, hence the `as Create2Artifact`. Deploying one on a new chain reproduces the addresses
+these were mined for, as long as the salt matches — the salts are published alongside them, in
+`create2-artifacts/create2-salts.json`.
+
+## The tasks in this repo
+
+Four tasks, in the order you'd run them. Each defaults to the `CONTRACTS` list in
+`tasks/create2Config.ts`, and each takes names to narrow it down.
+
+```sh
+npx hardhat mine-create2 --zeros 6                  # salts -> create2-artifacts/create2-salts.json
+npx hardhat gen-artifact-create2                    # artifacts -> create2-artifacts/
+npx hardhat deploy-create2 --network sepolia
+npx hardhat verify-create2 --network sepolia
+```
+
+Only the last two touch a network. `mine-create2` searches on every core and skips any contract
+whose stored salt still lands on its stored address with enough zeros — ask for more zeros to redo
+one. `deploy-create2` reads the frozen JSON off disk rather than recompiling, so what lands on chain
+is what was frozen, published and verified. Salts come from `create2-salts.json`; `--salt` overrides
+for every contract in the run.
+
+## What invalidates an address
+
+All of these change the init code, none of them break a build, and each needs the salt re-mined:
+
+- a dependency bump — **even to a version with byte-identical Solidity**, since the version is in the
+  source path the metadata hash covers
+- a comment or whitespace edit anywhere in the compilation unit
+- any change to the build profile, or a solc upgrade
+- different constructor arguments, or different library addresses
+
+Worth a CI check that recompiles and asserts the frozen `initCodeHash` still matches, so a change
+that moves an address can't land unnoticed.
+
+## Chain caveats
+
+- The default factory must exist on the target chain. `deployCreate2` throws with a clear message if
+  it doesn't. A different factory yields a different address.
+- zkSync-family chains derive CREATE2 differently and cannot match these addresses at all.
+- If your profile targets `cancun`, the bytecode may use `PUSH0`, which reverts on pre-Shanghai
+  chains. Pin `evmVersion: "paris"` for maximum reach — and decide before you mine, since changing it
+  moves every address.
+
+## API
+
+| Export | |
+| --- | --- |
+| `makeCreate2(target, options?)` | Freeze a contract into a `Create2Artifact` |
+| `predictCreate2Address({ initCodeHash, salt, factory? })` | Pure address derivation |
+| `create2MiningTarget(artifact, factory?)` | Inputs for a vanity miner |
+| `deployCreate2({ artifact, salt, walletClient, publicClient, factory?, gas? })` | Idempotent deploy |
+| `matchesOnchainBytecode(artifact, code, address)` | Compare against chain state |
+| `verifyOnEtherscan({ artifact, address, chainId, apiKey, … })` | Submit + poll |
+| `verifyOnSourcify({ artifact, address, chainId, … })` | Submit + poll |
+| `DEFAULT_CREATE2_FACTORY` | `0x4e59b44847b379578588920cA78FbF26c0B4956C` |

package/README.md

@@ -4,6 +4,9 @@ JS library counterpart of the [skinny-fat-imt](https://github.com/warptoad/skinn
 
 Reads a contract's [LeanIMT](https://github.com/privacy-scaling-explorations/zk-kit) state over viem — from storage or from events, whichever the contract exposes — and keeps a local mirror in sync.
 
+## TODO
+Decide where to keep the create2 artifacts and all that byte code. Using this package in frontend also downloads all that? Probably less of an issues when using bundlers?
+
 ## Install
 
 ```sh
@@ -46,6 +49,26 @@ import { queryEventInChunks, queryMultiEventsInChunks, minBigInt } from "@warpto
 | --- | --- |
 | `@warptoad/skinny-fat-imt-js` | `Trees`, `identifyTree`, `getEventFilter`, `copyTree`, `ERC165_IDS`, the ABIs, `getInterfaceId`, `DEPLOY_BLOCK`, … |
 | `@warptoad/skinny-fat-imt-js/event-scanning` | `queryEventInChunks`, `queryMultiEventsInChunks`, `minBigInt`, `EventLog`, `PostQueryEventFilter` |
+| `@warptoad/skinny-fat-imt-js/create2` | `makeCreate2`, `deployCreate2`, `predictCreate2Address`, `create2MiningTarget`, `verifyOnEtherscan`, `verifyOnSourcify`, `matchesOnchainBytecode` |
+| `@warptoad/skinny-fat-imt-js/create2/evm-artifacts/<Contract>` | The frozen `Create2Artifact` JSON for each shipped IMT library |
+
+## Deterministic CREATE2 for any contract
+
+`/create2` is a general toolkit, independent of the IMT libraries — point it at any Hardhat 3 contract:
+
+```ts
+const artifact = await makeCreate2("MyContract", { constructorArgs: [...] });
+const { address } = await deployCreate2({ artifact, salt, walletClient, publicClient });
+await verifyOnEtherscan({ artifact, address, chainId, apiKey });
+```
+
+`makeCreate2` freezes the init code together with the solc input that produced it, so nothing downstream recompiles and the address holds on every chain. The IMT libraries ship pre-frozen, so bringing them to a new chain needs no compiler:
+
+```ts
+import artifact from "@warptoad/skinny-fat-imt-js/create2/evm-artifacts/SkinnyIMTPoseidon2Read" with { type: "json" };
+```
+
+See **[CREATE2.md](CREATE2.md)**.
 
 ## Development
 
@@ -53,13 +76,13 @@ import { queryEventInChunks, queryMultiEventsInChunks, minBigInt } from "@warpto
 pnpm install
 pnpm compile     # hardhat compile, then regenerate src/abis.ts
 pnpm test        # hardhat test
-pnpm typecheck   # tsc over src + test + hardhat.config.ts
+pnpm typecheck   # tsc over src + test + scripts + hardhat.config.ts
 pnpm build       # emit dist/ from src/ via tsconfig.build.json
 ```
 
 ### About `src/abis.ts`
 
-`src/abis.ts` is **generated and committed**. `scripts/genAbis.mjs` copies nine ABIs out of hardhat's `artifacts/` into `as const` tuples.
+`src/abis.ts` is **generated and committed**. `scripts/genAbis.ts` copies nine ABIs out of hardhat's `artifacts/` into `as const` tuples.
 
 The library deliberately does not import `artifacts/` directly, even though that's the obvious thing to do. `artifacts/` is gitignored, ~13MB, and hardhat's generated `artifacts.d.ts` files end with:
 
@@ -71,6 +94,14 @@ Shipping that would make the published typings require `hardhat` to be resolvabl
 
 **Whenever the contracts change, run `pnpm compile` and commit the resulting `src/abis.ts` diff.** Nothing regenerates it automatically at publish time — that's on purpose, so `npm publish` can never silently rewrite source.
 
+## deployment  
+```
+pnpm hardhat gen-artifact-create2 --network sepolia;
+pnpm hardhat mine-create2 --network sepolia --zeros 6;
+pnpm hardhat deploy-create2 --network sepolia;
+pnpm hardhat verify-create2 --network sepolia;
+```
+
 ## Publishing to npm
 
 ### One-time setup
@@ -110,7 +141,7 @@ npm whoami          # confirm the right account
    npm pack --dry-run
    ```
 
-   Expect `dist/**`, `src/**`, `README.md`, `LICENSE`, `package.json` — about 50KB. If you see `artifacts/` or a multi-MB tarball, something is wrong with `files` in package.json.
+   Expect `dist/**`, `src/**`, `README.md`, `CREATE2.md`, `LICENSE`, `package.json` — about 50KB. If you see `artifacts/` or a multi-MB tarball, something is wrong with `files` in package.json.
 
 4. Publish. `prepublishOnly` runs `pnpm build` (a clean `rm -rf dist` then `tsc -p tsconfig.build.json`), so `dist/` is always rebuilt from current source:
 
@@ -143,9 +174,22 @@ pnpm add @warptoad/skinny-fat-imt-js viem
 node -e "import('@warptoad/skinny-fat-imt-js').then(m => console.log(Object.keys(m)))"
 ```
 
+
+
+
 ### Notes
 
 - **You cannot republish a version.** Once `0.0.1` is out, `0.0.1` is taken forever, even if you unpublish. Bump and move on.
 - `npm unpublish` is only allowed within 72 hours, and only if nothing depends on it. Use `npm deprecate` instead for anything older.
 - If publish fails with `402 Payment Required`, `publishConfig.access` got lost — scoped packages need `"access": "public"`.
 - If it fails with `404`, you're either not logged in or not a member of the `@warptoad` scope.
+
+## Deployed addresses sepolia
+```
+SkinnyIMTPoseidon2WriteStorage 0x00000066C760D24272a9E8A424EF7233A0F0da83
+SkinnyIMTPoseidon2WriteEvent   0x000000D74387530f88b9Cf1A23CDf16fdDC01bf6
+SkinnyIMTPoseidon2Read         0x000000A3a94867DD396753dEFABF989246211329
+FatIMTPoseidon2WriteStorage    0x000000F35EFB6F537d3663CF263c04f467f48c73
+FatIMTPoseidon2WriteEvent      0x00000012de70B336818C26517A4B2d7c0B949C7b
+FatIMTPoseidon2Read            0x000000FF3329863F1Eb55773aDEF01863791370
+```