@steerprotocol/liquidity-meter 1.0.0 → 2.0.4

package/README.md

@@ -4,6 +4,10 @@ Liquidity Depth CLI
 - Estimate price impact for given USD trade sizes.
 - Batch over many pools from CSV.
 - Simulate Steer vault withdrawals on a fork and re-run the analysis “after” to see slippage effects.
+- Published package surface:
+  - `@steerprotocol/liquidity-meter` exports pure depth helpers only.
+  - `@steerprotocol/liquidity-meter/api` exports `analyzePool`.
+  - `@steerprotocol/liquidity-meter/withdraw` exports withdraw simulation helpers.
 
 Requirements
 
@@ -12,20 +16,33 @@ Requirements
 
 Install
 
-- Node module consumers (after publish):
-  - `npm install liquidity-meter`
-  - ESM-only: import from `liquidity-meter` in Node 18+
-- Local (from this repo):
+- From the repo root:
   - `npm install`
-  - `npm run generate && npm run build`
   - `npm link` (optional; installs `liquidity-depth` in your PATH)
+- As a package dependency:
+  - `npm install @steerprotocol/liquidity-meter`
 
-ESM Only
+Release Workflow
 
-- This package ships ESM only. Use Node 18+ and `import` syntax.
-- Exports:
-  - `import { analyzePool, fetchPoolSnapshotViem, computeMarketDepthBands, simulateVaultWithdraw } from 'liquidity-meter'`
-  - CLI subpath: `node ./node_modules/liquidity-meter/dist/cli/liquidity-depth.js --help`
+- Releases are automated with `semantic-release` on pushes to `master` or `main`.
+- Commit messages are validated with `commitlint` using the Conventional Commits spec.
+- CI runs unit tests on Node.js 20 and 22, then enforces coverage thresholds on Node.js 22.
+- Required repository secrets:
+  - `NPM_TOKEN` for npm publishing.
+- GitHub releases use the default `GITHUB_TOKEN` provided by Actions.
+
+Library Usage
+
+```js
+import { computeMarketDepthBands } from '@steerprotocol/liquidity-meter';
+import { analyzePool } from '@steerprotocol/liquidity-meter/api';
+import { simulateVaultWithdraw } from '@steerprotocol/liquidity-meter/withdraw';
+```
+
+Breaking Change
+
+- `analyzePool` is no longer exported from `@steerprotocol/liquidity-meter`.
+- Migrate root imports to `@steerprotocol/liquidity-meter/api`.
 
 Quick Start
 
@@ -49,9 +66,6 @@ Batch via CSV
 
 - Run the CLI over many pools and write a per-pool report:
   - `liquidity-depth --csv "/path/to/file.csv" --outdir ./reports --rpc <URL>`
-  - Reliability flags for large batches / flaky providers:
-    - `--throttle-ms N` add delay between rows and retries
-    - `--retries N` retry transient JSON-RPC failures (e.g., `-32000`, proof window, `429`)
 - CSV header expectations:
   - Pool address: prefer one of `pool`, `address`, `pool_address`, `id` (addresses embedded in URLs are auto-detected).
   - If no pool address is present, provide `token0`, `token1`, and `fee`, and with `--rpc` the tool will resolve the pool using the Uniswap v3 factory.
@@ -115,8 +129,6 @@ Options (Reference)
 - `--usd-sizes`: Comma-separated USD sizes for price impact (token1 buys, token0 sells).
 - `--prices`: `reserve|dexscreener|llama|coingecko|auto` (default: `auto`; env `PRICES_SOURCE`).
 - `--reserve-limit`: Limit for Reserve API (default: `100`; env `RESERVE_LIMIT`).
-- `--throttle-ms`: Delay between CSV rows & retries (ms).
-- `--retries`: Retries per row on transient RPC errors (default: `0`).
 - `--csv`: CSV file with pool/vault rows.
 - `--outdir`: Output directory (default: `reports`).
 - `--json` / `-j`: Emit machine-readable JSON.
@@ -141,7 +153,6 @@ Troubleshooting
 - If owner has 0 vault shares at the forked block, the withdraw step is skipped.
 - If a vault does not expose `pool()` or withdraw reverts, the run fails for that row only.
 - Logs: Reports strip noisy EVM logs; use `--debug` for pricing diagnostics.
-- zsh/newlines: keep command arguments on a single line (e.g., do not split `--rpc` URL across lines).
 
 Examples
 
@@ -149,49 +160,9 @@ Examples
   - `liquidity-depth --pool 0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8 --rpc https://mainnet.infura.io/v3/<KEY> --usd-sizes 1000,5000,10000`
 - Batch CSV:
   - `liquidity-depth --csv "/path/to/file.csv" --outdir ./reports --rpc https://developer-access-mainnet.base.org --usd-sizes 1000,5000,10000,25000,50000,100000`
-  - With backoff and retries:
-    - `liquidity-depth --csv "/path/to/file.csv" --outdir ./reports --rpc https://developer-access-mainnet.base.org --usd-sizes 1000,5000,10000,25000,50000,100000 --throttle-ms 500 --retries 2`
 - Batch with withdraw simulation for a single owner across all rows:
   - `OWNER=0xYourOwner liquidity-depth --csv "/path/to/file.csv" --outdir ./reports --rpc https://developer-access-mainnet.base.org --withdraw-pct 25 --usd-sizes 1000,5000,10000`
 
-Programmatic API
-
-- One-call analysis (before/after) with price inference and optional withdraw simulation:
-
-```
-import { analyzePool } from 'liquidity-meter'
-
-const res = await analyzePool({
-  poolAddress: '0x11e26bbd1a5547895a50fc39a2d4c0025dec0bda',
-  source: 'tevm',                          // or 'subgraph' | 'auto'
-  rpcUrl: 'https://developer-access-mainnet.base.org',
-  percentBuckets: [1, 2, 5, 10],
-  usdSizes: [1000, 5000, 10000, 25000],
-  prices: 'auto',                          // reserve | dexscreener | llama | coingecko | auto
-  withdraw: {                              // optional; TEVM only
-    vault: '0xYourVault',
-    owner: '0xYourOwner',
-    withdrawPct: 25,                       // or: withdrawShares: '1230000000000000000'
-  },
-})
-
-console.log(res.before.metrics.depthPlus2USD)
-console.log(res.after?.metrics.depthPlus2USD)
-```
-
-- Lower-level building blocks (for custom flows):
-
-```
-import {
-  fetchPoolSnapshotViem,                 // TEVM on-chain snapshot
-  fetchPoolSnapshot as fetchFromSubgraph,
-  computeMarketDepthBands,
-  computePriceImpactsBySizes,
-  fetchTokenUSDPrices,
-  simulateVaultWithdraw,                 // TEVM withdraw sim
-} from 'liquidity-meter'
-```
-
 Notes & Limitations
 
 - No transactions are sent to mainnet; all simulations run on a local fork.