@dcasegr/amm-engine 0.0.0-stage → 0.38.2

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# @dcasegr/amm-engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pure TypeScript planning library for the AMM market UI's matching engine.
+No UI framework, no network: it plans swaps over an inventory of pools the
+caller supplies (queried from the overlay elsewhere) and returns a set of
+legs to build, sign and broadcast. See `docs/notes.md` in the main repo,
+"Pool contract draft (2026-09-23)" and "Overlay and communication layer on
+skein (2026-09-29)" (the "Market UI and matching engine" and "Commission
+fee" paragraphs), and `pool/Pool.runar.go` for the contract this
+mirrors.
+
+## Install
+
+```
+npm install @dcasegr/amm-engine
+```
+
+ESM with type declarations (`dist/`, built by `tsc -p tsconfig.build.json`; `npm pack` builds
+it). No dependencies. Its version is the skein-amm release it is cut from (named
+`@amm-poc/matching-engine` and private before 0.38.0). The client package
+`@dcasegr/amm-client` (`../ui`, README "The packages") depends on it; the pages read this
+directory's `src/` directly (vite alias and tsconfig `paths` in `../ui`).
+
+## Test
+
+```
+npm ci
+npm test         # vitest run
+npm run typecheck
+npm run build    # dist/
+```
+
+## API
+
+```ts
+import { plan, replan, computeSwap, feeAmount } from "@dcasegr/amm-engine";
+```
+
+### `computeSwap(pool, direction, amountIn): SwapResult | null`
+
+Contract-exact swap arithmetic (BigInt), mirroring `pool/Pool.runar.go`'s
+`Swap` method bit for bit:
+
+```
+liquidityFee = ceil(amountIn * liquidityFeeBps / 10000)
+validationFee = ceil(amountIn * validationFeeBps / 10000)
+commission = ceil(amountIn * commissionBps / 10000)
+net = amountIn - liquidityFee - validationFee - commission   // must be > 0
+amountOut = floor(net * outputReserve / (inputReserve + net))
+                                                   // must be > 0
+```
+
+Returns `null` if the contract's own assertions (`net > 0`, `amountOut >
+0`) would fail for this amountIn against this pool — i.e. this is not a
+valid swap.
+
+### `plan(request: PlanRequest): Plan`
+
+Plans a fresh order against an inventory of pools. Deterministic and pure:
+no clock, no randomness; ties are always broken by outpoint (ascending).
+
+- `allowPartial: false` — only pools where the **entire** `amountIn` swaps
+  within the slippage bound are eligible; the engine picks the single best
+  one (max `amountOut`, tie-break by outpoint). If none qualify, returns an
+  empty plan with `meetsSlippageBound: false`.
+- `allowPartial: true` (default expectation) — splits the order across
+  pools by water-filling: pools are added in descending (fee-adjusted)
+  spot-price order while the next pool's marginal improvement in total
+  `amountOut` exceeds its fixed per-leg cost (`fixedCost.minerFeeSats`,
+  converted into the output asset's units — see
+  "Assumptions" below). The chosen pools are then filled so their marginal
+  price is equalized (continuous water-filling, closed form), and the
+  continuous split is rounded to integers with largest-remainder rounding
+  (ties broken by outpoint), then **re-derived from the exact BigInt
+  contract formula**. Any rounded leg the contract would reject (net <= 0
+  or out <= 0 — only possible for a sub-1-unit rounding remainder) is
+  folded into the largest other leg and re-derived, so every leg the
+  planner returns is a leg the contract would actually accept.
+- The plan's `meetsSlippageBound` flag reports whether the (would-be)
+  result satisfies the resolved slippage bound. If it doesn't, `plan()`
+  still returns the best achievable allocation (not an empty plan) with
+  the flag set to `false` — callers that want "no fill unless it clears
+  the bound" should check the flag rather than assume an empty plan.
+- An optional liveness filter (`livenessThreshold` + `now`, both supplied
+  by the caller — the engine never reads the clock) excludes pools whose
+  `lastSeen` is older than the threshold, or that have no `lastSeen` at all
+  while the filter is active.
+
+### `replan(plan: Plan, results: LegResult[]): Plan`
+
+Re-plans the remainder of an order after a round of legs has been
+attempted. Pure and deterministic, chainable: `replan()`'s return value is
+itself a valid `Plan` that can be fed back into `replan()` again for the
+next round, carrying cumulative bookkeeping (`cumulativeFilledAmountIn/Out`,
+`originalAmountIn`, `resolvedMinAmountOut`) forward automatically.
+
+Per-leg result handling:
+
+- `filled` — locked in. Its `amountIn`/`amountOut` count toward the
+  order's cumulative fill; its pool is gone (spent).
+- `rejected` with `newPoolState` — the pool is re-priced from the
+  validator's returned state (new outpoint + reserves) and stays a
+  candidate for the remainder.
+- `rejected` with no `newPoolState`, `timeout`, or a leg with no matching
+  result at all — the pool's true state is unknown (it may have raced with
+  another swap), so it is **dropped** from the candidate set rather than
+  retried against stale reserves. (See "Assumptions.")
+
+The slippage budget is cumulative across rounds: `resolvedMinAmountOut` is
+fixed once, at the first `plan()` call, against the whole order; each
+`replan()` round only needs to make up what hasn't already been filled.
+`replan()` stops (returns a plan with empty `legs`) once the order is
+fully filled, or once nothing eligible remains for the remainder.
+
+### Types
+
+See `src/types.ts` for the full shapes: `PoolState`, `FixedCost`,
+`SlippageBound`, `PlanRequest`, `Leg`, `Plan`, `LegResult`.
+
+## Assumptions
+
+A few judgment calls the task left open, made explicit here:
+
+1. **Slippage bound resolution.** `SlippageBound` supports both
+   `minAmountOut` and `toleranceBps`; when both are given, the stricter
+   (larger) resolved bound wins. `toleranceBps` is measured against a
+   "quoted mid": the unconstrained optimal split across *every* eligible
+   pool for the requested `amountIn`, ignoring fixed per-leg costs
+   entirely. This is recomputed once per `plan()` call (not once per
+   `replan()` round — the bound is fixed at the start of the order).
+2. **Fixed cost units.** `fixedCost` is always denominated in sats (the
+   miner fee, paid in BSV regardless of swap direction). The commission is
+   not a fixed cost: it is the pool's `commissionBps`, a third fee on
+   amountIn next to the LP and validator fees (in the fee multiplier `m`
+   and in `computeSwap`); each `Leg` carries its `commission`. When the output asset is BSV
+   (`tokenToBsv`), the water-filling gate compares directly in sats. When
+   the output asset is the token (`bsvToToken`), the sats cost is
+   converted to token-equivalent units using the newly-added pool's spot
+   ratio (`tokenReserve / bsvReserve`) for the comparison. This is a
+   heuristic gate for *how many* legs to use, not a settlement value.
+3. **Water-filling is continuous, then rounded and re-verified.** The
+   optimizer works in IEEE doubles for speed and simplicity (reserves at
+   realistic BSV/token magnitudes fit a double's 53-bit mantissa with no
+   meaningful loss for planning purposes). The result is converted to
+   integer BigInt amounts (largest-remainder rounding, ties by outpoint)
+   and every leg is re-derived through `computeSwap` (exact BigInt), which
+   is what the planner actually returns and what determines
+   `meetsSlippageBound`. A rounded leg the contract would reject is folded
+   into the largest other leg rather than dropped silently.
+4. **`meetsSlippageBound` on an empty/no-inventory plan.** If no bound was
+   requested (`slippage: {}`) and there's no inventory to plan against, the
+   resolved bound is `0`, so an empty plan trivially "meets" it. Callers
+   should check `filledCompletely` (or `legs.length`) separately to detect
+   "nothing was planned," rather than relying on `meetsSlippageBound` alone.
+5. **`replan()` drops pools with an unknown post-attempt state** (a
+   `rejected` leg with no `newPoolState`, a `timeout`, or a leg absent from
+   `results` entirely) rather than retrying them against the stale
+   pre-attempt reserves, since a race could have moved the pool to a state
+   the engine can't see. They simply fall out of the candidate set; a
+   caller that later learns their true state (e.g. via the overlay's spend
+   index, per the "Market UI and matching engine" note about following
+   pool continuations to the newest outpoint) can add them back into a
+   fresh `inventory` on the next top-level `plan()` call.
+6. **Liveness filter excludes pools with no `lastSeen`** whenever
+   `livenessThreshold`/`now` are supplied, on the conservative assumption
+   that "never seen" is at least as stale as "seen too long ago."
+7. **`allowPartial: false` picks the best single pool** among those that
+   can fill the *entire* `amountIn` within the slippage bound in one leg
+   (max `amountOut`, ties broken by outpoint), per the task's spec. It
+   does not attempt any splitting.
+8. **Every pool in `inventory` is assumed pre-scoped to `tokenId`** — the
+   `PoolState` shape given in the task has no per-pool token id field, so
+   the engine trusts the caller queried the overlay for the right token.
+9. **Determinism.** All internal sorts break ties by `outpoint` (lexical,
+   ascending): pool selection order, single-leg pick, and rounding-
+   remainder distribution. No leg is ever chosen by insertion order.
+
+## Files
+
+- `src/types.ts` — shared types.
+- `src/pricing.ts` — contract-exact BigInt swap arithmetic (`computeSwap`, `feeAmount`).
+- `src/allocation.ts` — continuous water-filling split + integer rounding (`planSplit`, `quoteMid`).
+- `src/planner.ts` — `plan()`, single-leg selection, liveness filter, slippage bound resolution.
+- `src/replanner.ts` — `replan()`.
+- `test/pricing.test.ts` — `computeSwap` checked against an independently transcribed oracle of the Go contract's formula, for a table of cases (typical, zero fees, high fees, tiny amounts with ceil-rounding edge cases, a reject case, asymmetric reserves, heavy price impact, realistic large BSV magnitudes).
+- `test/planner.test.ts` — single pool, split-beats-single, fixed-cost-prevents-split, `allowPartial: false`, slippage exhaustion, liveness filter, `bsvToToken` direction, determinism.
+- `test/replanner.test.ts` — re-pricing after rejection (better and worse new state), partial-fill + cumulative slippage budget, stopping when nothing eligible remains, stopping when fully filled, multi-round chaining.

package/dist/allocation.d.ts

@@ -0,0 +1,19 @@
+import type { Direction, FixedCost, Leg, PoolState } from "./types.js";
+/**
+ * Plans a split of `amountIn` across `pools` (already filtered to the
+ * requested token and liveness threshold, deduplicated by outpoint). Adds
+ * pools in descending spot-price order while the next pool's marginal
+ * improvement in total amountOut exceeds its fixed per-leg cost, then
+ * equalises marginal price across the chosen pools and rounds to exact
+ * integer, contract-valid legs.
+ *
+ * Returns legs sorted by outpoint for a deterministic, stable plan shape.
+ */
+export declare function planSplit(pools: PoolState[], direction: Direction, amountIn: bigint, fixedCost: FixedCost): Leg[];
+/**
+ * The unconstrained "quoted mid": the total amountOut an optimal split
+ * across every given pool would produce for amountIn, ignoring fixed
+ * per-leg costs entirely (used only to resolve a toleranceBps slippage
+ * bound into an absolute minAmountOut).
+ */
+export declare function quoteMid(pools: PoolState[], direction: Direction, amountIn: bigint): bigint;

package/dist/allocation.js

@@ -0,0 +1,241 @@
+/**
+ * Water-filling allocation across constant-product pools.
+ *
+ * Splitting an order across N constant-product pools to maximise total
+ * amountOut is solved by equalising the *marginal* price across the pools
+ * used (the standard water-filling / optimal-routing result). For a pool
+ * with input-side reserve R_in, output-side reserve R_out and post-fee
+ * multiplier m = (10000 - liquidityFeeBps - validationFeeBps - commissionBps) / 10000, the
+ * marginal price at post-fee input `net` is:
+ *
+ *   price(net) = R_in * R_out / (R_in + net)^2
+ *
+ * Setting price(net) = P (a shared shadow price) gives a closed form:
+ *
+ *   net(P) = sqrt(R_in * R_out / P) - R_in        (clamped to >= 0)
+ *
+ * This module works in `number` for the continuous optimisation (it is a
+ * planning heuristic, not a settlement — every leg that is actually
+ * returned is re-derived with exact BigInt contract arithmetic in
+ * pricing.ts and rejected if the contract would reject it). Reserve sizes
+ * for BSV (<= ~2.1e15 sats) and realistic token amounts fit in a double's
+ * 53-bit mantissa with no meaningful loss for this purpose.
+ */
+import { computeSwap } from "./pricing.js";
+function toPoolMath(pool, direction) {
+    const bsv = Number(pool.bsvReserve);
+    const tok = Number(pool.tokenReserve);
+    const inputReserve = direction === "tokenToBsv" ? tok : bsv;
+    const outputReserve = direction === "tokenToBsv" ? bsv : tok;
+    const feeBps = Number(pool.liquidityFeeBps) + Number(pool.validationFeeBps) + Number(pool.commissionBps);
+    const m = Math.max(0, (10000 - feeBps) / 10000);
+    const k = inputReserve * outputReserve;
+    const spotPrice = inputReserve > 0 ? (m * outputReserve) / inputReserve : 0;
+    return { pool, inputReserve, outputReserve, k, m, spotPrice };
+}
+/**
+ * Shadow price P is the marginal amountOut per unit of amountIn (pre-fee),
+ * matching `spotPrice`'s basis: d(out)/d(amountIn) = m * d(out)/d(net) =
+ * m * R_in*R_out / (R_in+net)^2. Solving for net at a given P:
+ *
+ *   net(P) = sqrt(m * k / P) - R_in
+ */
+function netAt(pm, shadowPrice) {
+    if (shadowPrice <= 0 || pm.k <= 0 || pm.m <= 0 || !isFinite(shadowPrice))
+        return Infinity;
+    const net = Math.sqrt((pm.m * pm.k) / shadowPrice) - pm.inputReserve;
+    return net > 0 ? net : 0;
+}
+function amountInAt(pm, shadowPrice) {
+    if (pm.m <= 0)
+        return 0;
+    return netAt(pm, shadowPrice) / pm.m;
+}
+function totalAmountInAt(pms, shadowPrice) {
+    let sum = 0;
+    for (const pm of pms)
+        sum += amountInAt(pm, shadowPrice);
+    return sum;
+}
+function outputAt(pm, net) {
+    if (net <= 0)
+        return 0;
+    return (net * pm.outputReserve) / (pm.inputReserve + net);
+}
+/** Finds the shadow price P such that sum(amountInAt(pm, P)) == target. */
+function solveShadowPrice(pms, target) {
+    if (pms.length === 0 || target <= 0)
+        return Infinity;
+    const maxSpot = Math.max(...pms.map((p) => p.spotPrice));
+    if (!isFinite(maxSpot) || maxSpot <= 0)
+        return Infinity;
+    let hi = maxSpot; // at P = maxSpot, at least one pool's net is ~0 -> total ~0 (upper bound on total)
+    let lo = maxSpot / 2;
+    let guard = 0;
+    while (totalAmountInAt(pms, lo) < target && guard < 400) {
+        lo = lo / 2;
+        guard++;
+        if (lo < Number.EPSILON)
+            break;
+    }
+    for (let i = 0; i < 100; i++) {
+        const mid = (lo + hi) / 2;
+        if (totalAmountInAt(pms, mid) > target)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return (lo + hi) / 2;
+}
+function totalOutputForTarget(pms, target) {
+    if (target <= 0 || pms.length === 0)
+        return 0;
+    const price = solveShadowPrice(pms, target);
+    let out = 0;
+    for (const pm of pms)
+        out += outputAt(pm, netAt(pm, price));
+    return out;
+}
+/** Fixed per-leg cost (sats), converted into the output asset's units for comparison. */
+function fixedCostInOutputUnits(pm, direction, fixedCost) {
+    const sats = Number(fixedCost.minerFeeSats);
+    if (direction === "tokenToBsv") {
+        // output asset is BSV: no conversion needed.
+        return sats;
+    }
+    // output asset is the token: convert sats -> tokens at this pool's spot ratio.
+    const bsv = Number(pm.pool.bsvReserve);
+    const tok = Number(pm.pool.tokenReserve);
+    if (bsv <= 0)
+        return Infinity;
+    return sats * (tok / bsv);
+}
+/** Largest-remainder rounding of float shares to integer BigInt summing exactly to target. */
+function roundAllocation(pms, floatShares, target) {
+    const totalFloat = floatShares.reduce((a, b) => a + b, 0);
+    if (totalFloat <= 0 || target <= 0n)
+        return pms.map(() => 0n);
+    const targetNum = Number(target);
+    const scaled = floatShares.map((s) => (s / totalFloat) * targetNum);
+    const floors = scaled.map((s) => BigInt(Math.max(0, Math.floor(s))));
+    let used = floors.reduce((a, b) => a + b, 0n);
+    let remainder = target - used;
+    const order = scaled
+        .map((s, i) => ({ i, frac: s - Math.floor(s), outpoint: pms[i].pool.outpoint }))
+        .sort((a, b) => b.frac - a.frac || (a.outpoint < b.outpoint ? -1 : a.outpoint > b.outpoint ? 1 : 0));
+    const result = [...floors];
+    let idx = 0;
+    while (remainder > 0n && idx < order.length) {
+        const target_ = order[idx].i;
+        result[target_] = (result[target_] ?? 0n) + 1n;
+        remainder -= 1n;
+        idx++;
+    }
+    if (remainder > 0n && result.length > 0) {
+        result[0] = (result[0] ?? 0n) + remainder;
+    }
+    return result;
+}
+/**
+ * Plans a split of `amountIn` across `pools` (already filtered to the
+ * requested token and liveness threshold, deduplicated by outpoint). Adds
+ * pools in descending spot-price order while the next pool's marginal
+ * improvement in total amountOut exceeds its fixed per-leg cost, then
+ * equalises marginal price across the chosen pools and rounds to exact
+ * integer, contract-valid legs.
+ *
+ * Returns legs sorted by outpoint for a deterministic, stable plan shape.
+ */
+export function planSplit(pools, direction, amountIn, fixedCost) {
+    if (pools.length === 0 || amountIn <= 0n)
+        return [];
+    const sorted = pools
+        .map((p) => toPoolMath(p, direction))
+        .sort((a, b) => b.spotPrice - a.spotPrice || (a.pool.outpoint < b.pool.outpoint ? -1 : 1));
+    const targetNum = Number(amountIn);
+    let bestN = 1;
+    let prevOut = totalOutputForTarget(sorted.slice(0, 1), targetNum);
+    for (let n = 2; n <= sorted.length; n++) {
+        const out = totalOutputForTarget(sorted.slice(0, n), targetNum);
+        const gain = out - prevOut;
+        const justAdded = sorted[n - 1];
+        const cost = fixedCostInOutputUnits(justAdded, direction, fixedCost);
+        if (gain > cost) {
+            bestN = n;
+            prevOut = out;
+        }
+        else {
+            break;
+        }
+    }
+    const active = sorted.slice(0, bestN);
+    const price = solveShadowPrice(active, targetNum);
+    const shares = active.map((pm) => amountInAt(pm, price));
+    let allocation = roundAllocation(active, shares, amountIn);
+    // Fold any allocation the contract would reject (net <= 0 or out <= 0,
+    // possible only for tiny rounded shares) into the largest remaining leg,
+    // deterministically, until every nonzero leg is contract-valid.
+    for (let pass = 0; pass < active.length; pass++) {
+        let changed = false;
+        for (let i = 0; i < active.length; i++) {
+            const amt = allocation[i];
+            if (amt <= 0n)
+                continue;
+            const result = computeSwap(active[i].pool, direction, amt);
+            if (result === null) {
+                // fold into the largest other allocation (tie-break by outpoint)
+                let bestJ = -1;
+                for (let j = 0; j < active.length; j++) {
+                    if (j === i)
+                        continue;
+                    if (bestJ === -1 ||
+                        allocation[j] > allocation[bestJ] ||
+                        (allocation[j] === allocation[bestJ] && active[j].pool.outpoint < active[bestJ].pool.outpoint)) {
+                        bestJ = j;
+                    }
+                }
+                if (bestJ === -1)
+                    break;
+                allocation[bestJ] = (allocation[bestJ] ?? 0n) + amt;
+                allocation[i] = 0n;
+                changed = true;
+            }
+        }
+        if (!changed)
+            break;
+    }
+    const legs = [];
+    for (let i = 0; i < active.length; i++) {
+        const amt = allocation[i];
+        if (amt <= 0n)
+            continue;
+        const pm = active[i];
+        const result = computeSwap(pm.pool, direction, amt);
+        if (result === null)
+            continue; // still invalid even after folding; drop it
+        legs.push({
+            outpoint: pm.pool.outpoint,
+            amountIn: amt,
+            liquidityFee: result.liquidityFee,
+            validationFee: result.validationFee,
+            commission: result.commission,
+            amountOut: result.amountOut,
+            newBsvReserve: result.newBsvReserve,
+            newTokenReserve: result.newTokenReserve,
+        });
+    }
+    legs.sort((a, b) => (a.outpoint < b.outpoint ? -1 : a.outpoint > b.outpoint ? 1 : 0));
+    return legs;
+}
+/**
+ * The unconstrained "quoted mid": the total amountOut an optimal split
+ * across every given pool would produce for amountIn, ignoring fixed
+ * per-leg costs entirely (used only to resolve a toleranceBps slippage
+ * bound into an absolute minAmountOut).
+ */
+export function quoteMid(pools, direction, amountIn) {
+    if (pools.length === 0 || amountIn <= 0n)
+        return 0n;
+    const legs = planSplit(pools, direction, amountIn, { minerFeeSats: 0n });
+    return legs.reduce((a, l) => a + l.amountOut, 0n);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export { feeAmount, computeSwap } from "./pricing.js";
+export type { SwapResult } from "./pricing.js";
+export { planSplit, quoteMid } from "./allocation.js";
+export { plan, planOrder, filterLivePools, resolveMinAmountOut } from "./planner.js";
+export { replan } from "./replanner.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { feeAmount, computeSwap } from "./pricing.js";
+export { planSplit, quoteMid } from "./allocation.js";
+export { plan, planOrder, filterLivePools, resolveMinAmountOut } from "./planner.js";
+export { replan } from "./replanner.js";

package/dist/planner.d.ts

@@ -0,0 +1,15 @@
+import type { Direction, FixedCost, Leg, Plan, PlanRequest, PoolState, SlippageBound } from "./types.js";
+/** Applies the liveness filter (pure: caller supplies `now`, engine never reads the clock). */
+export declare function filterLivePools(inventory: PoolState[], livenessThreshold: number | undefined, now: number | undefined): PoolState[];
+/**
+ * Resolves a SlippageBound to a single absolute minAmountOut. When both
+ * minAmountOut and toleranceBps are given, the stricter (larger) bound wins.
+ * toleranceBps is measured against the "quoted mid": the unconstrained
+ * optimal-split amountOut across every eligible pool right now, ignoring
+ * fixed per-leg costs.
+ */
+export declare function resolveMinAmountOut(pools: PoolState[], direction: Direction, amountIn: bigint, slippage: SlippageBound): bigint;
+/** Core planning step shared by plan() and replan(): plan `amountIn` against `pools` given an absolute minAmountOut. */
+export declare function planOrder(pools: PoolState[], direction: Direction, amountIn: bigint, allowPartial: boolean, fixedCost: FixedCost, minAmountOut: bigint): Leg[];
+/** Plans a fresh order against the given inventory. Pure, deterministic. */
+export declare function plan(request: PlanRequest): Plan;

package/dist/planner.js

@@ -0,0 +1,91 @@
+import { computeSwap } from "./pricing.js";
+import { planSplit, quoteMid } from "./allocation.js";
+/** Applies the liveness filter (pure: caller supplies `now`, engine never reads the clock). */
+export function filterLivePools(inventory, livenessThreshold, now) {
+    if (livenessThreshold === undefined || now === undefined)
+        return inventory;
+    return inventory.filter((p) => p.lastSeen !== undefined && now - p.lastSeen <= livenessThreshold);
+}
+/**
+ * Resolves a SlippageBound to a single absolute minAmountOut. When both
+ * minAmountOut and toleranceBps are given, the stricter (larger) bound wins.
+ * toleranceBps is measured against the "quoted mid": the unconstrained
+ * optimal-split amountOut across every eligible pool right now, ignoring
+ * fixed per-leg costs.
+ */
+export function resolveMinAmountOut(pools, direction, amountIn, slippage) {
+    let bound = 0n;
+    if (slippage.minAmountOut !== undefined && slippage.minAmountOut > bound) {
+        bound = slippage.minAmountOut;
+    }
+    if (slippage.toleranceBps !== undefined) {
+        const quote = quoteMid(pools, direction, amountIn);
+        const tolerant = (quote * (10000n - slippage.toleranceBps)) / 10000n;
+        if (tolerant > bound)
+            bound = tolerant;
+    }
+    return bound;
+}
+function pickBestSingleLeg(pools, direction, amountIn, minAmountOut) {
+    let best = null;
+    for (const pool of pools) {
+        const result = computeSwap(pool, direction, amountIn);
+        if (result === null)
+            continue;
+        if (minAmountOut > 0n && result.amountOut < minAmountOut)
+            continue;
+        const leg = {
+            outpoint: pool.outpoint,
+            amountIn,
+            liquidityFee: result.liquidityFee,
+            validationFee: result.validationFee,
+            commission: result.commission,
+            amountOut: result.amountOut,
+            newBsvReserve: result.newBsvReserve,
+            newTokenReserve: result.newTokenReserve,
+        };
+        if (best === null ||
+            leg.amountOut > best.amountOut ||
+            (leg.amountOut === best.amountOut && leg.outpoint < best.outpoint)) {
+            best = leg;
+        }
+    }
+    return best;
+}
+/** Core planning step shared by plan() and replan(): plan `amountIn` against `pools` given an absolute minAmountOut. */
+export function planOrder(pools, direction, amountIn, allowPartial, fixedCost, minAmountOut) {
+    if (amountIn <= 0n || pools.length === 0)
+        return [];
+    if (!allowPartial) {
+        const best = pickBestSingleLeg(pools, direction, amountIn, minAmountOut);
+        return best ? [best] : [];
+    }
+    return planSplit(pools, direction, amountIn, fixedCost);
+}
+/** Plans a fresh order against the given inventory. Pure, deterministic. */
+export function plan(request) {
+    const eligible = filterLivePools(request.inventory, request.livenessThreshold, request.now);
+    const resolvedMinAmountOut = resolveMinAmountOut(eligible, request.direction, request.amountIn, request.slippage);
+    const legs = planOrder(eligible, request.direction, request.amountIn, request.allowPartial, request.fixedCost, resolvedMinAmountOut);
+    const totalAmountIn = legs.reduce((a, l) => a + l.amountIn, 0n);
+    const totalAmountOut = legs.reduce((a, l) => a + l.amountOut, 0n);
+    const usedOutpoints = new Set(legs.map((l) => l.outpoint));
+    const remainingInventory = eligible.filter((p) => !usedOutpoints.has(p.outpoint));
+    return {
+        legs,
+        totalAmountIn,
+        totalAmountOut,
+        meetsSlippageBound: totalAmountOut >= resolvedMinAmountOut,
+        filledCompletely: totalAmountIn === request.amountIn,
+        direction: request.direction,
+        allowPartial: request.allowPartial,
+        fixedCost: request.fixedCost,
+        livenessThreshold: request.livenessThreshold,
+        now: request.now,
+        originalAmountIn: request.amountIn,
+        resolvedMinAmountOut,
+        cumulativeFilledAmountIn: 0n,
+        cumulativeFilledAmountOut: 0n,
+        remainingInventory,
+    };
+}

package/dist/pricing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Contract-exact swap arithmetic, mirroring pool/Pool.runar.go's Swap method
+ * bit for bit (BigInt, same truncation/ceiling behaviour as the Go integer
+ * division the contract uses).
+ *
+ *   lpFee         = ceil(amountIn * LpFeeBps / 10000)
+ *   validatorFee  = ceil(amountIn * ValidatorFeeBps / 10000)
+ *   commission    = ceil(amountIn * CommissionBps / 10000)
+ *   net           = amountIn - lpFee - validatorFee - commission   (must be > 0)
+ *
+ *   tokenToBsv (token in, bsv out):
+ *     out          = floor(net * bsvReserve / (tokenReserve + net))
+ *     newBsv       = bsvReserve - out
+ *     newTokens    = tokenReserve + net
+ *
+ *   bsvToToken (bsv in, token out):
+ *     out          = floor(net * tokenReserve / (bsvReserve + net))
+ *     newBsv       = bsvReserve + net
+ *     newTokens    = tokenReserve - out
+ *
+ *   out must be > 0.
+ */
+import type { Direction, PoolState } from "./types.js";
+export interface SwapResult {
+    liquidityFee: bigint;
+    validationFee: bigint;
+    commission: bigint;
+    net: bigint;
+    amountOut: bigint;
+    newBsvReserve: bigint;
+    newTokenReserve: bigint;
+}
+/** ceil(amountIn * bps / 10000), exactly as the contract computes each fee. */
+export declare function feeAmount(amountIn: bigint, bps: bigint): bigint;
+/**
+ * Computes one pool's swap exactly as the contract would, or returns null if
+ * the contract's assertions (`net > 0`, `out > 0`) would fail — i.e. this
+ * amountIn is not a valid swap against this pool.
+ */
+export declare function computeSwap(pool: Pick<PoolState, "bsvReserve" | "tokenReserve" | "liquidityFeeBps" | "validationFeeBps" | "commissionBps">, direction: Direction, amountIn: bigint): SwapResult | null;

package/dist/pricing.js

@@ -0,0 +1,35 @@
+/** ceil(amountIn * bps / 10000), exactly as the contract computes each fee. */
+export function feeAmount(amountIn, bps) {
+    return (amountIn * bps + 9999n) / 10000n;
+}
+/**
+ * Computes one pool's swap exactly as the contract would, or returns null if
+ * the contract's assertions (`net > 0`, `out > 0`) would fail — i.e. this
+ * amountIn is not a valid swap against this pool.
+ */
+export function computeSwap(pool, direction, amountIn) {
+    if (amountIn <= 0n)
+        return null;
+    const liquidityFee = feeAmount(amountIn, pool.liquidityFeeBps);
+    const validationFee = feeAmount(amountIn, pool.validationFeeBps);
+    const commission = feeAmount(amountIn, pool.commissionBps);
+    const net = amountIn - liquidityFee - validationFee - commission;
+    if (net <= 0n)
+        return null;
+    let amountOut;
+    let newBsvReserve;
+    let newTokenReserve;
+    if (direction === "tokenToBsv") {
+        amountOut = (net * pool.bsvReserve) / (pool.tokenReserve + net);
+        newBsvReserve = pool.bsvReserve - amountOut;
+        newTokenReserve = pool.tokenReserve + net;
+    }
+    else {
+        amountOut = (net * pool.tokenReserve) / (pool.bsvReserve + net);
+        newBsvReserve = pool.bsvReserve + net;
+        newTokenReserve = pool.tokenReserve - amountOut;
+    }
+    if (amountOut <= 0n)
+        return null;
+    return { liquidityFee, validationFee, commission, net, amountOut, newBsvReserve, newTokenReserve };
+}

package/dist/replanner.d.ts

@@ -0,0 +1,24 @@
+import type { LegResult, Plan } from "./types.js";
+/**
+ * Re-plans the remainder of an order after a round of legs has been
+ * attempted. Pure and deterministic: no clock, no randomness, ties broken
+ * by outpoint.
+ *
+ * Semantics for each leg result:
+ *  - filled: locked in. Its amountIn/amountOut count toward the order's
+ *    cumulative fill and its pool is gone (spent).
+ *  - rejected with newPoolState: the pool is still available, re-priced
+ *    from the validator's returned state, and stays a candidate.
+ *  - rejected with no newPoolState, or timeout, or a leg with no matching
+ *    result at all: the pool's true state is unknown (it may have raced
+ *    with another swap), so it is conservatively dropped from the
+ *    candidate set rather than retried against stale reserves.
+ *
+ * The slippage budget is cumulative across rounds: resolvedMinAmountOut
+ * (fixed at the first plan() call) applies to the whole order, and each
+ * round only needs to cover what filled legs haven't already delivered.
+ *
+ * Stops (returns a plan with empty legs) once the order is fully filled,
+ * or once nothing eligible remains for the remainder.
+ */
+export declare function replan(plan: Plan, results: LegResult[]): Plan;

package/dist/replanner.js

@@ -0,0 +1,85 @@
+import { planOrder } from "./planner.js";
+/**
+ * Re-plans the remainder of an order after a round of legs has been
+ * attempted. Pure and deterministic: no clock, no randomness, ties broken
+ * by outpoint.
+ *
+ * Semantics for each leg result:
+ *  - filled: locked in. Its amountIn/amountOut count toward the order's
+ *    cumulative fill and its pool is gone (spent).
+ *  - rejected with newPoolState: the pool is still available, re-priced
+ *    from the validator's returned state, and stays a candidate.
+ *  - rejected with no newPoolState, or timeout, or a leg with no matching
+ *    result at all: the pool's true state is unknown (it may have raced
+ *    with another swap), so it is conservatively dropped from the
+ *    candidate set rather than retried against stale reserves.
+ *
+ * The slippage budget is cumulative across rounds: resolvedMinAmountOut
+ * (fixed at the first plan() call) applies to the whole order, and each
+ * round only needs to cover what filled legs haven't already delivered.
+ *
+ * Stops (returns a plan with empty legs) once the order is fully filled,
+ * or once nothing eligible remains for the remainder.
+ */
+export function replan(plan, results) {
+    const resultByOutpoint = new Map(results.map((r) => [r.outpoint, r]));
+    let filledIn = 0n;
+    let filledOut = 0n;
+    const repriced = [];
+    for (const leg of plan.legs) {
+        const result = resultByOutpoint.get(leg.outpoint);
+        if (result === undefined)
+            continue; // unknown outcome: drop, conservative
+        if (result.status === "filled") {
+            filledIn += leg.amountIn;
+            filledOut += leg.amountOut;
+        }
+        else if (result.status === "rejected" && result.newPoolState) {
+            repriced.push(result.newPoolState);
+        }
+        // rejected without newPoolState, or timeout: pool dropped (unknown state)
+    }
+    const nextInventory = [...plan.remainingInventory, ...repriced];
+    const cumulativeFilledAmountIn = plan.cumulativeFilledAmountIn + filledIn;
+    const cumulativeFilledAmountOut = plan.cumulativeFilledAmountOut + filledOut;
+    const remainder = plan.originalAmountIn - cumulativeFilledAmountIn;
+    const remainingMinAmountOut = plan.resolvedMinAmountOut > cumulativeFilledAmountOut
+        ? plan.resolvedMinAmountOut - cumulativeFilledAmountOut
+        : 0n;
+    const base = {
+        direction: plan.direction,
+        allowPartial: plan.allowPartial,
+        fixedCost: plan.fixedCost,
+        livenessThreshold: plan.livenessThreshold,
+        now: plan.now,
+        originalAmountIn: plan.originalAmountIn,
+        resolvedMinAmountOut: plan.resolvedMinAmountOut,
+        cumulativeFilledAmountIn,
+        cumulativeFilledAmountOut,
+    };
+    if (remainder <= 0n) {
+        return {
+            ...base,
+            legs: [],
+            totalAmountIn: 0n,
+            totalAmountOut: 0n,
+            meetsSlippageBound: cumulativeFilledAmountOut >= plan.resolvedMinAmountOut,
+            filledCompletely: true,
+            remainingInventory: nextInventory,
+        };
+    }
+    const newLegs = planOrder(nextInventory, plan.direction, remainder, plan.allowPartial, plan.fixedCost, remainingMinAmountOut);
+    const totalAmountIn = newLegs.reduce((a, l) => a + l.amountIn, 0n);
+    const totalAmountOut = newLegs.reduce((a, l) => a + l.amountOut, 0n);
+    const usedOutpoints = new Set(newLegs.map((l) => l.outpoint));
+    const remainingInventory = nextInventory.filter((p) => !usedOutpoints.has(p.outpoint));
+    return {
+        ...base,
+        legs: newLegs,
+        totalAmountIn,
+        totalAmountOut,
+        meetsSlippageBound: cumulativeFilledAmountOut + totalAmountOut >= plan.resolvedMinAmountOut,
+        filledCompletely: cumulativeFilledAmountIn + totalAmountIn === plan.originalAmountIn,
+        remainingInventory,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Types for the matching engine. All monetary / reserve quantities are
+ * BigInt to mirror the pool contract's integer arithmetic exactly
+ * (see pool/Pool.runar.go). Floating point is only ever used internally,
+ * as a heuristic for *how* to split an order across pools; every number
+ * that ends up in a Leg is produced by exact BigInt contract arithmetic.
+ */
+/** Which asset is being sold. The taker always receives the other one. */
+export type Direction = "bsvToToken" | "tokenToBsv";
+/** One pool UTXO, as the caller's inventory query would report it. */
+export interface PoolState {
+    /** txid:vout of the pool UTXO. */
+    outpoint: string;
+    bsvReserve: bigint;
+    tokenReserve: bigint;
+    /** LP fee rate, in basis points, taken from amountIn (ceil). */
+    liquidityFeeBps: bigint;
+    /** Validator fee rate, in basis points, taken from amountIn (ceil). */
+    validationFeeBps: bigint;
+    /**
+     * Commission rate (the contract's CommissionBps, fixed at deploy), in basis
+     * points, taken from amountIn (ceil) and paid to the relay's address.
+     */
+    commissionBps: bigint;
+    /** The pool's validator identity key (33-byte hex or similar). Opaque to the engine. */
+    validatorIdentityKey: string;
+    /** Last time (ms epoch) this pool's validator was seen live, if known. */
+    lastSeen?: number;
+}
+/** Fixed cost the taker pays to add one more leg to a plan, in satoshis. */
+export interface FixedCost {
+    /** Estimated miner fee for this leg's transaction, in sats. */
+    minerFeeSats: bigint;
+}
+/**
+ * Slippage bound on the *total* amountOut across every leg of the order.
+ * Both forms may be given; the engine resolves them to a single absolute
+ * `minAmountOut` and uses whichever is stricter (larger).
+ */
+export interface SlippageBound {
+    /** Minimum acceptable total amountOut, in the output asset's smallest unit. */
+    minAmountOut?: bigint;
+    /**
+     * Tolerance in basis points against the "quoted mid": the total amountOut
+     * an unconstrained optimal split across all eligible pools would produce
+     * right now, ignoring fixed per-leg costs. minAmountOut is then
+     * quote * (10000 - toleranceBps) / 10000.
+     */
+    toleranceBps?: bigint;
+}
+/** A single pool's leg of a plan, with the pool's exact post-swap state. */
+export interface Leg {
+    outpoint: string;
+    amountIn: bigint;
+    liquidityFee: bigint;
+    validationFee: bigint;
+    /** The commission, in the input asset. */
+    commission: bigint;
+    amountOut: bigint;
+    /** Pool reserves after this leg, per the contract's swap arithmetic. */
+    newBsvReserve: bigint;
+    newTokenReserve: bigint;
+}
+export interface PlanRequest {
+    tokenId: string;
+    direction: Direction;
+    amountIn: bigint;
+    slippage: SlippageBound;
+    allowPartial: boolean;
+    fixedCost: FixedCost;
+    /** Pools available for this token. Assumed already scoped to tokenId. */
+    inventory: PoolState[];
+    /** Exclude pools whose validator lastSeen is older than this many ms before `now`. */
+    livenessThreshold?: number;
+    /**
+     * Caller-supplied "current time" (ms epoch) for the liveness filter. The
+     * engine never reads the clock itself, to stay pure. Required if
+     * livenessThreshold is set; pools with no lastSeen are excluded whenever
+     * a liveness filter is active.
+     */
+    now?: number;
+}
+export interface Plan {
+    /** Legs to build, sign and broadcast in parallel for this round. */
+    legs: Leg[];
+    /** Sum of this round's legs' amountIn. */
+    totalAmountIn: bigint;
+    /** Sum of this round's legs' amountOut (expected, pre-execution). */
+    totalAmountOut: bigint;
+    /**
+     * True if, assuming this round's legs all fill as planned, the
+     * cumulative amountOut (including prior rounds) meets resolvedMinAmountOut.
+     */
+    meetsSlippageBound: boolean;
+    /** True if this round's legs cover the full remaining order (originalAmountIn - cumulativeFilledAmountIn). */
+    filledCompletely: boolean;
+    direction: Direction;
+    allowPartial: boolean;
+    fixedCost: FixedCost;
+    livenessThreshold?: number;
+    now?: number;
+    /** The full order size, constant across every round. */
+    originalAmountIn: bigint;
+    /** Absolute slippage bound for the whole order, resolved once at the first plan() call. */
+    resolvedMinAmountOut: bigint;
+    /** amountIn confirmed filled in prior rounds (not including this round's legs). */
+    cumulativeFilledAmountIn: bigint;
+    /** amountOut confirmed received in prior rounds. */
+    cumulativeFilledAmountOut: bigint;
+    /**
+     * Pools not used by this round's legs but still known-live candidates for
+     * a future replan() round (i.e. the rest of the inventory passed to plan(),
+     * after the liveness/eligibility filter).
+     */
+    remainingInventory: PoolState[];
+}
+export type LegResult = {
+    outpoint: string;
+    status: "filled";
+} | {
+    outpoint: string;
+    status: "rejected";
+    newPoolState?: PoolState;
+} | {
+    outpoint: string;
+    status: "timeout";
+};

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Types for the matching engine. All monetary / reserve quantities are
+ * BigInt to mirror the pool contract's integer arithmetic exactly
+ * (see pool/Pool.runar.go). Floating point is only ever used internally,
+ * as a heuristic for *how* to split an order across pools; every number
+ * that ends up in a Leg is produced by exact BigInt contract arithmetic.
+ */
+export {};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@dcasegr/amm-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.38.2",
+  "type": "module",
+  "description": "Pure TypeScript order-matching / planning library for the AMM (skein-amm): plans swaps over an inventory of pools the caller supplies. No UI framework, no network.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shruggr/skein-amm.git",
+    "directory": "web/engine"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}