@warptoad/skinny-fat-imt-js 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 warptoad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# @warptoad/skinny-fat-imt-js
+
+JS library counterpart of the [skinny-fat-imt](https://github.com/warptoad/skinny-fat-imt) contracts, used to sync the onchain tree client side.
+
+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.
+
+## Install
+
+```sh
+pnpm add @warptoad/skinny-fat-imt-js viem
+```
+
+`viem` is a **peer dependency**, so it isn't installed for you. That's deliberate: two copies of viem in one tree produce `PublicClient` types that look identical but don't unify, and you'd get baffling assignability errors passing your client into `Trees`.
+
+ESM only, Node >= 22.
+
+## Usage
+
+```ts
+import { Trees } from "@warptoad/skinny-fat-imt-js";
+import { createPublicClient, http } from "viem";
+
+const client = createPublicClient({ transport: http(rpcUrl) });
+const trees = new Trees(contractAddress, client);
+
+// full node: read the trees straight from contract storage
+const synced = await trees.sync([treeId]);
+
+// archive node: replay the contract's events, discovering treeIds as it goes
+const all = await trees.sync([], { fullNodeMode: false, autoDiscovery: true });
+```
+
+`fullNodeMode` (default `true`) reads current storage, so a plain full node is enough — that's what the name means. It's the cheap path, but it only sees the tree as it is now.
+
+Turning it off replays events, which needs a provider that still has the logs. Recent history is fine on a full node; anything older than roughly a year wants an archive node, and `autoDiscovery` scans all the way back to the deployment block, so it always does. In exchange you get history: `syncToRoot` to reconstruct an old root, and treeId discovery, neither of which storage reads can do.
+
+`syncTreesStorage` / `syncTreesEvent` are the two paths directly if you'd rather not go through `sync`.
+
+The event-scanning helpers are a separate entry point, so you can chunk `getLogs` calls against any contract without pulling in the tree machinery:
+
+```ts
+import { queryEventInChunks, queryMultiEventsInChunks, minBigInt } from "@warptoad/skinny-fat-imt-js/event-scanning";
+```
+
+| Entry point | Exports |
+| --- | --- |
+| `@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` |
+
+## Development
+
+```sh
+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 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.
+
+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:
+
+```ts
+declare module "hardhat/types/artifacts" { interface ArtifactMap { … } }
+```
+
+Shipping that would make the published typings require `hardhat` to be resolvable in the consumer's project, and would inject our contract names into *their* `ArtifactMap`. Baking the ABIs in keeps full viem inference with no hardhat dependency at all — `hardhat` stays a devDependency and never enters a consumer's graph.
+
+**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.
+
+## Publishing to npm
+
+### One-time setup
+
+Log in. The `@warptoad` scope must already exist on npm and your account must be able to publish to it.
+
+```sh
+npm login
+npm whoami          # confirm the right account
+```
+
+`publishConfig.access` is already set to `public` in package.json. Without it npm assumes scoped packages are private and rejects the publish on a free account.
+
+> The package name is `@warptoad/skinny-fat-imt-js`, all lowercase — npm rejects uppercase in package names, so `skinny-fat-IMT-js` is not a valid name.
+
+### Publishing a version
+
+1. Make sure the ABIs are current and everything passes:
+
+   ```sh
+   pnpm compile     # only needed if the contracts changed
+   pnpm typecheck
+   pnpm test
+   ```
+
+   Commit any `src/abis.ts` diff before continuing.
+
+2. Bump the version. This writes package.json, commits, and tags:
+
+   ```sh
+   npm version patch    # or: minor / major
+   ```
+
+3. Check what will actually ship before you ship it:
+
+   ```sh
+   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.
+
+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:
+
+   ```sh
+   npm publish
+   ```
+
+5. Push the commit and tag:
+
+   ```sh
+   git push --follow-tags
+   ```
+
+### Publishing a prerelease
+
+To try a version out without moving the `latest` tag:
+
+```sh
+npm version prerelease --preid=rc     # 0.0.1 -> 0.0.2-rc.0
+npm publish --tag next
+```
+
+Consumers get it with `pnpm add @warptoad/skinny-fat-imt-js@next`; plain `pnpm add @warptoad/skinny-fat-imt-js` still resolves to the last stable release.
+
+### Verifying the published package
+
+```sh
+mkdir /tmp/check && cd /tmp/check && pnpm init
+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.