feat(margin-sdk): add @uniswap/margin-sdk for the v4 margin trading periphery

[ccashwell]

@uniswap/margin-sdk

A new workspace package for the margin trading periphery (Uniswap/v4-periphery#563): leveraged spot positions built from a v4 swap composed with a borrow/supply against an external lending venue — Morpho Blue, Aave v3, or Aave v4 — all behind one MarginRouter. Follows the liquidity-launcher-sdk conventions: viem-only runtime dependency, minimal as const satisfies Abi ABIs, descriptor + PublicClient read pattern, bun test, three-target tsc build.

What's included

Module	Purpose
encode.ts	Calldata encoders + write descriptors for every entry point: increasePosition, decreasePosition (+ closePosition sugar over the FULL_CLOSE sentinel), addCollateral, execute, multicall, forwarded Permit2 permit — with SDK-side mirrors of the contract guards (mandatory slippage caps, uint128 bounds, pool↔market reconciliation, native-ETH equity handling)
account.ts	Offchain accountOf: Solady clone-with-immutable-args CREATE2 derivation, so frontends resolve account addresses with zero RPC calls
math.ts	Decimal-aware sizing (sizeIncrease / sizeDecrease from a quote + slippage, works for both the 18d/6d long and reversed-decimal short), leverage↔LTV conversions, health factors matching describePosition semantics
planner.ts / actions.ts	MarginPlanner for execute plans: v4 routing actions + the 0x30-range margin opcodes, enforcing offchain the structural rules the router reverts on (SET_ACCOUNT ordering, PULL_TO_ACCOUNT zero-amount / CONTRACT_BALANCE footguns)
reads.ts	Venue-agnostic read descriptors (drop into wagmi useReadContract(s) / viem multicall) + PublicClient helpers
abis.ts / addresses.ts / types.ts	Exact ABIs, the mainnet deployment registry, and onchain struct mirrors

Validation

The SDK is anchored to the deployed mainnet contracts, not just the source:

• Every entry-point selector confirmed against the live router via expired-deadline DeadlinePassed reverts (a wrong selector would revert empty).
• The 9 accountOf test vectors were read from the live router; the CWIA derivation reproduces them byte-for-byte.
• Entry-point calldata and planner param blobs are anchored to cast-generated ground truth.
• Adapter reads exercised live (Morpho WETH/USDC LLTV 0.86e18 read back exactly as documented).

80 unit tests, lint, typecheck, build, and dep-consistency all green.

End-to-end demos (demo/, bun run demo)

Runnable anvil-fork flows proving the SDK drives everything the v4-periphery contract tests exercise, against the live deployment and the real USDC/WETH 0.05% pool, with sizing from real v4 Quoter quotes — 60 assertions, all passing:

1. Long lifecycle (mirrors MarginRouterIntegration + E2E.fork): predicted account, Permit2 setup, 2x open with event decoding and SDK-vs-onchain health math (matches to 1 bps), top-up, leverage-only increase, partial delever, full close with residual returned.
2. Native-ETH equity (MarginRouterNative): open/top-up with raw msg.value, no approvals.
3. Shorts on Aave v3 + v4 (Aave adapter fork tests): identical code per venue, only the adapter address changes.
4. Cross-venue hedge (CrossVenueHedge.fork): isolated sub-accounts, delta-neutral within live-pool impact, independent unwind.
5. execute plans (MarginRouterExecute): a MarginPlanner plan reproducing the curated open action-for-action, repay-from-wallet, and the owner escape hatch.

Notes for reviewers

• Ships at 0.0.0 with a minor changeset — the standard release flow mints 0.1.0.
• Test vectors are pinned to the current mainnet deployment (router 0x0000000004BBC92D0657580CAe35aEBF054E5CDC); a redeploy requires regenerating them (the test files document how).
• Live-pool caveat surfaced by the demos: a full-size exact-out quote embeds its own price impact (~1.3%/WETH on the 0.05% pool today), so delta-targeted sizing should quote near-spot and buffer — demo 04 shows the pattern; could graduate into an SDK helper later.

[github-actions]

_{● Reviewed · 2026-08-27 14:22 UTC · 2 reviews · view run ↗}

Approved.

Adds @uniswap/margin-sdk, a new self-contained workspace package of viem-only calldata encoders, decimal-aware sizing math, and read descriptors for the v4 margin-trading periphery.

Assessment

The package is additive and follows the established liquidity-launcher-sdk conventions, anchored to the deployed mainnet router with 80 unit tests plus fork demos. The SDK is a signing-side encoder — the caller is the principal, and the on-chain contract remains the enforcing authority for every guard mirrored offchain, so a loose SDK check degrades to a contract revert rather than a loss. Sizing and health math guard the paths that matter: positivity, zero-collateral leverage, round-to-zero quotes, uint128 bounds, and division denominators. Slippage rounds in the protective direction (input caps up, output floors down, >100% rejected), and pricing sources are kept separate — quotes for sizing, oracle for health.

[github-actions]

Note

✅ Approved — see full review in the sticky comment ↑

[graphite-app]

Graphite Automations

"Request reviewers once CI passes on sdks monorepo" took an action on this PR • (07/24/26)

3 reviewers were added and 1 assignee was added to this PR based on Siyu Jiang (See-You John)'s automation.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	jsdom@​26.1.0

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm data-urls is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: sdks/margin-sdk/package.json → npm/jsdom@26.1.0 → npm/data-urls@5.0.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/data-urls@5.0.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm rrweb-cssom is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: sdks/margin-sdk/package.json → npm/jsdom@26.1.0 → npm/rrweb-cssom@0.8.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/rrweb-cssom@0.8.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		System shell access: npm jsdom in module child_process Module: child_process Location: Package overview From: sdks/margin-sdk/package.json → npm/jsdom@26.1.0 ℹ Read more on: This package | This alert | What is shell access? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should avoid accessing the shell which can reduce portability, and make it easier for malicious shell access to be introduced. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/jsdom@26.1.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Filesystem access: npm jsdom with module fs Module: fs Location: Package overview From: sdks/margin-sdk/package.json → npm/jsdom@26.1.0 ℹ Read more on: This package | This alert | What is filesystem access? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: If a package must read the file system, clarify what it will read and ensure it reads only what it claims to. If appropriate, packages can leave file system access to consumers and operate on data passed to it instead. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/jsdom@26.1.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[Ayoakala]

Pushed efc86705 — adds collateral withdrawal, which had no path in the SDK. Two things in here worth a look, one of which changes existing behaviour.

Withdrawing collateral without touching debt

decreasePosition withdraws collateral as part of repaying debt, but there's no way to pull collateral out while leaving debt alone (de-risking, taking excess equity off the table). The router has no curated entry point for it — the write entry points are increasePosition, decreasePosition, addCollateral, execute — so it had to be hand-rolled as an execute plan, where all three failure modes are silent rather than reverts:

• OPEN_DELTA is not "all collateral" on this action. It resolves to _getFullDebt(market.collateral) (MarginRouter.sol:569) — correct inside a swap-bearing delever, but zero in a swap-free plan, so it withdraws nothing and succeeds.
• assertHealth is opt-in and withdrawing raises LTV. ASSERT_HEALTH skips a zero bound, so an unbounded withdrawal walks the position to the liquidation edge without reverting. The curated decreasePosition makes maxLtvAfter mandatory for exactly this reason; a hand-rolled plan has no such enforcement.
• The recipient can't be a sentinel (below).

withdrawCollateralPlan(...) builds SET_ACCOUNT → ACCOUNT_WITHDRAW_COLLATERAL → ASSERT_HEALTH and rejects all three at build time. Also added account-direct encoders for the IMarginAccount escape-hatch primitives (withdrawCollateral/supplyCollateral/borrow/repay/sweep) per the TDD's "the owner can call the account's primitives directly, bypassing the router". No ABI regeneration needed — the generated MARGIN_ACCOUNT_ABI already had all five plus ReceiverNotAllowed, and src/generated/abis.ts is untouched.

⚠️ Behaviour change: sentinels on the account-scoped fund-out actions

This is the part I'd most like you to sanity-check.

_mapRecipient is called only for the router-level SWEEP (MarginRouter.sol:514). The three ACCOUNT_* fund-out handlers pass to straight through to the account unmapped:

// MarginRouter.sol:570, :577, :583
IMarginAccount(account).withdrawCollateral(adapter, market, amount, to);
IMarginAccount(account).borrow(adapter, market, amount, to);
IMarginAccount(account).sweep(currency, amount, to);

and MarginAccount._requireReceiver (:163) only accepts the clone's baked-in {owner, manager}. So MSG_SENDER/ADDRESS_THIS — idiomatic everywhere else in a v4 plan — arrive as the literal 0x…01/0x…02 and revert ReceiverNotAllowed. validateAccountRecipient now rejects them at build time; the router-level opcodes keep the lenient zero-address-only guard, since the sentinels are genuinely valid there.

This means two existing tests were asserting the wrong thing. borrow to ADDRESS_THIS asserted the planner accepts ADDR2 (= ADDRESS_THIS), and the borrow3e9ToRouter ground-truth blob ended in …0002 — so it was ground truth for a plan that would have reverted onchain. The curated increase passes address(this) literally (MarginRouter.sol:474), so I regenerated that blob against the literal router address with cast and renamed the test. Flagging explicitly in case the sentinel behaviour was intentional and I've misread the handler — but I couldn't find a mapping path for those three opcodes.

Verification

• 127 unit tests pass (was 120). New calldata and plan params anchored to fresh cast output; selector 0xe3f81c67 checked against the pinned ABI.
• demo/06-withdraw-collateral.ts — 16 assertions, green against the live mainnet deployment on an anvil fork, and the full bun run demo suite (01–06) passes on one shared fork. It covers the curated plan, a native exit (withdraw → unwrap → sweep, asserting the router nets to zero), and the account-direct escape hatch — plus it pins that maxLtvAfter really binds onchain and that the unsafe variants never build. Uses sub-IDs 7/8 to stay clear of 01–05.
• lint, typecheck, check:package (CJS + ESM + jsdom) all clean.
• check:abis not run locally (my v4-periphery checkout is on main, not the pinned fe8105a9) — but the generated bindings are untouched, and CI checks out the pin itself.

Contract behaviour verified by reading v4-periphery at the pinned commit fe8105a9e31ac6e30c9b18bd1078047cab3e1cea: Market.toSwapParams, MarginAccount._requireReceiver, MarginRouter._handleAction.

Folded into the existing changeset rather than adding a second one, since the package is still unreleased.

Two follow-ups I did not do

1. A nativePoolIncrease helper. Separately, increasePosition can't route through a native-ETH pool at all: Market.toSwapParams requires the pool's currencies to equal the market's (collateral, debt), and markets must be ERC-20 because MarginAccount.supplyCollateral approves the collateral token. So native ETH/USDC routing — which is where the deep liquidity is — has to go through execute. MarginPlanner can express it today, but hand-rolling it in a backend has the same class of risk as hand-rolled withdrawals.
2. Contract-side coverage for a native-pool swap. No test at the pin routes a margin swap through a pool with currency0 == address(0). MarginRouterExecuteNative.t.sol covers native equity only and says so: "no swap pool is needed because these plans move value between native, WETH, and the account without touching pool deltas." So ASSERT_FILL/TAKE on native currency mid-unlock is untested on both sides.