@morpho-dev/router 0.3.0 → 0.4.1

package/docs/integrator.md

@@ -0,0 +1,78 @@
+# Documentation
+
+This document is intended for **technical integrators** and **product/design teams**. It explains how the router works end-to-end, how to integrate with it, and what the main user-facing implications are.
+
+At a high level, the router indexes and exposes offers published to the on-chain mempool and computes the *takeable* amount for each offer. In practice, this means the router aims to surface offers with a takeable amount that can be executed without reverting at take time, minimizing execution failures for takers.
+
+## Forge a supported offer
+
+Not every offer published to the mempool will be indexed by the router. The router applies a **gatekeeper** that validates both **offer validity** (e.g., the offer is not expired) and the **supported format** (e.g., the callback type is supported by the router).
+
+These checks serve the same goal: **minimize take-time failures**. Validity checks eliminate offers that are expected to revert on-chain. Supported-format checks further reduce failure risk by restricting the full set of protocol possibilities to a subset the router understands and can reason about, providing a more controlled integration surface and fewer unpredictable execution paths.
+
+To run these checks and validate your offers, call **`POST /v1/validate`**. If validation fails, the response includes `data.issues` describing what needs to be fixed.
+
+## Push offers to the mempool
+
+Once your offer is valid, you must **publish it on-chain** to make it available to all mempool consumers. The router is one consumer of the mempool, but anyone can publish to it or listen to it.
+
+```
+POST /v1/validate  →  { payload, root }  →  sign(root)  →  publish(payload + sig)
+    { offers: [...] }
+```
+
+Offers are published as a *batch* using a Merkle tree so that a single signature can cover a whole group of offers. The Merkle **root** is a compact commitment to the full set: changing any offer changes the root, which makes the signature invalid. To keep calldata (and therefore gas costs) low, the offer set is embedded in the `payload` as a **gzipped** representation rather than being sent as plain JSON.
+
+Use **`POST /v1/validate`** to obtain `payload` (the encoded representation of your offers, with the root already embedded) and `root` (the Merkle root to sign). To publish, append your signature to the payload: `data = payload + signature`.
+
+## Router takeable computation
+
+Publishing an offer to the mempool (even with a supported format) does **not** guarantee that it is currently takeable. A core responsibility of the router is to compute the **takeable** amount for each offer: the maximum amount that can be executed *without reverting*, given current state.
+
+The router computes `takeable = min(availableLiquidity, offerRemaining)`.
+
+`offerRemaining` is the remaining, unconsumed portion of the offer (i.e., the total offered amount minus what has already been taken by other takers).
+
+`availableLiquidity` is the amount of liquidity the router can safely source for the offer at execution time. It is derived from the offer’s **callback**.
+
+A **callback** is the on-chain "liquidity source" used during settlement: it tells the protocol *where* to pull assets from (e.g., the maker’s wallet, or a specific vault position) when the offer is filled. Callbacks are extremely flexible, but that flexibility also means the router cannot reliably compute takeability for arbitrary callback logic.
+
+To keep takeability deterministic and indexable, the router only supports a **whitelist** of callback formats with well-defined semantics:
+
+- **Buy with empty callback (`0x`)** (`BuyWithEmptyCallback`): source the buy-side liquidity from the maker’s ERC20 balance/allowance.
+- **Buy with Vault V1 callback** (`BuyVaultV1Callback`): source the buy-side liquidity from specific Vault V1 positions listed in the callback data (and registered in the router’s allowed vault factories).
+- **Sell with ERC20 callback** (`SellERC20Callback`): source the sell-side collateral from ERC20 collateral contracts listed in the callback data (must match the offer’s `collaterals`).
+
+In practice, the router indexes the underlying source (wallet balances/allowances, Vault V1 positions, etc.) and caps the offer by what is actually available. If an offer uses a non-whitelisted callback address or an unsupported callback shape, it may still be valid on-chain, but it will be rejected by the router’s gatekeeper (see **`POST /v1/validate`**).
+
+If `availableLiquidity = 0`, the offer is **not** treated as invalid. The offer remains indexed, but it is returned with `takeable = 0` (and therefore will not be executed by router consumers).
+
+### Takeable by user intent
+
+A "user intent" is the user-facing action an offer is meant to execute (e.g., enter supply, enter borrow, exit supply/withdraw, or exit borrow/repay). The router accounts for intent when computing takeable because each intent has different execution constraints and denominations (assets vs shares vs obligation units) and can rely on different sources of liquidity; as a result, the safe amount that can be taken without reverting must be capped using intent-specific rules.
+
+#### Main: Enter supply
+
+For *Enter supply*, the offer must be denominated in **assets**. The router decodes the callback to identify the liquidity source (the "position"), indexes the position balance, and caps the offer amount by the indexed balance.
+
+#### Main: Enter borrow
+
+For *Enter borrow*, the offer must be denominated in **assets**. The router evaluates takeable by inspecting the callback "position" (the same mechanism as **Enter supply**) and does **not** take Morpho V2 collateral or health into account when computing takeable; the callback is responsible for enforcing its own safety constraints. As a result, collateral already deposited on Morpho V2 does not increase borrow takeable. If a user wants to leverage more of their Morpho V2 collateral, they must withdraw that collateral and use it in a callback.
+
+#### Secondary: exit supply (withdraw)
+
+For *Exit supply (withdraw)*, the offer must be denominated in **shares**. The router checks the share balance on Morpho V2 and caps the offer amount by the share balance.
+
+#### Secondary: exit borrow (repay)
+
+For *Exit borrow (repay)*, the offer must be denominated in **obligation units**. The router checks the outstanding debt on Morpho V2.
+
+### Overcommitting protection
+
+When multiple offers rely on the same liquidity source, it is possible to **overcommit** liquidity (i.e., promise the same units of liquidity to multiple offers). Without protection, executing one offer can make another offer in the same batch invalid, causing **unpredictable batch failures**. The router’s goal is to make taker execution as reliable as possible, especially for **batched** execution (multicalls).
+
+The router enforces a simple rule: **liquidity promised by a group of offers is reserved and cannot be promised twice**. For example, if a Vault V1 position has 80 units available and Offer A reserves 50 units, then a second offer attempting to reserve 50 units from the same position will only see 20 units as available and will be capped accordingly.
+
+The same concept applies to exit intents (shares and debt): the router prevents overcommitting those balances as well.
+
+To get the amount already reserved on a position you can query the user’s positions via `/v1/users/[:userAddress]/positions`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morpho-dev/router",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Router package for Morpho protocol",
   "type": "module",
   "license": "MIT",
@@ -13,7 +13,8 @@
     "url": "git@github.com:morpho-org/router.git"
   },
   "files": [
-    "dist/*"
+    "dist/*",
+    "docs/*"
   ],
   "main": "./dist/index.node.js",
   "module": "./dist/index.node.mjs",
@@ -66,11 +67,13 @@
     "drizzle-orm": "^0.43.1",
     "hono": "^4.9.7",
     "js-base64": "^3.7.8",
+    "marked": "^17.0.1",
     "openapi-fetch": "^0.15.0",
     "openapi-metadata": "^0.2.2",
     "pako": "^2.1.0",
     "pg": "^8.16.0",
     "reflect-metadata": "^0.2.2",
+    "smol-toml": "^1.6.0",
     "viem": "^2.37.13",
     "zod": "^4.1.12",
     "zod-openapi": "^5.4.3"
@@ -88,11 +91,14 @@
     "lint:ci": "biome ci src/",
     "migrations:create": "drizzle-kit generate --config src/database/drizzle/drizzle.config.ts --name",
     "migrations:run": "drizzle-kit migrate --config src/database/drizzle/drizzle.config.ts",
-    "openapi:generate": "tsx src/cli/dump-swagger.ts && pnpm openapi-typescript src/api/Schema/generated/swagger.json -o src/api/Schema/generated/swagger.d.ts && biome check --write src/api/Schema/generated",
-    "test": "vitest",
-    "test:api": "vitest --config vitest.api.config.ts run",
+    "openapi:generate": "node --import tsx src/cli/dump-swagger.ts && pnpm openapi-typescript src/api/Schema/generated/swagger.json -o src/api/Schema/generated/swagger.d.ts && biome check --write src/api/Schema/generated",
+    "test": "vitest run",
+    "test:e2e": "./scripts/e2e-run.sh",
+    "test:tenderly": "vitest --config vitest.tenderly.config.ts run",
     "test:ui": "vitest --ui",
     "test:watch": "vitest watch",
+    "e2e:setup": "./scripts/e2e-setup.sh",
+    "e2e:teardown": "./scripts/e2e-teardown.sh",
     "typecheck": "pnpm openapi:generate && tsc --project tsconfig.json --noEmit --incremental"
   }
 }