feat(the-compact-sdk): implement The Compact SDK #438

ccashwell · 2025-11-18T22:47:31Z

This PR introduces @uniswap/the-compact-sdk, a comprehensive TypeScript SDK for interacting with The Compact v1 protocol. The SDK provides a fluent, type-safe API for creating compacts, processing claims, and managing resource locks with full EIP-712 signing support.

socket-security · 2025-11-18T22:48:02Z

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

Package	Supply Chain Security	Quality	Maintenance
@types/node@24.9.1 ⏵ 24.10.1	⁺¹	⁺¹
sane@4.1.0 ⏵ 5.0.1			⁺³²
semantic-release@25.0.1 ⏵ 25.0.2			⁺¹

View full report

socket-security · 2025-11-18T22:48:04Z

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		Dynamic module loading: npm `jest-util` Location: Package overview From: `?` → `npm/[email protected]` ℹ Read more on: This package \| This alert \| What is dynamic require? 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 `[email protected]`. Suggestion: Packages should avoid dynamic imports when possible. Audit the use of dynamic require to ensure it is not executing malicious or vulnerable code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore npm/[email protected]`. 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.

Ignoring alerts on:

[email protected]

View full report

semgrep-code-uniswap · 2025-11-18T22:52:50Z

Semgrep found 2 ssc-cee3e6d5-d7c8-4c35-9815-076aa1ebfd49 findings:

package-lock.json
- L21038 - Triage
- L38446 - Triage

Risk: Affected versions of rollup are vulnerable to Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting').

Manual Review Advice: A vulnerability from this advisory is reachable if you use Rollup to bundle JavaScript with import.meta.url and the output format is set to cjs, umd, or iife formats, while allowing users to inject scriptless HTML elements with unsanitized name attributes

Fix: Upgrade this library to at least version 2.79.2 at sdks/package-lock.json:38446.

Reference(s): GHSA-gcx4-mw62-g8wm, CVE-2024-47068

Semgrep found 4 ssc-aff5e8de-c638-4356-8a93-120597e35ce9 findings:

package-lock.json
- L23924 - Triage
- L24097 - Triage
- L40231 - Triage
- L40336 - Triage

Risk: Affected versions of @babel/traverse, babel-traverse, @babel/plugin-transform-runtime, @babel/preset-env, @babel/helper-define-polyfill-provider, babel-plugin-polyfill-corejs2, babel-plugin-polyfill-corejs3, babel-plugin-polyfill-es-shims, and babel-plugin-polyfill-regenerator are vulnerable to Incomplete List Of Disallowed Inputs. An attacker can exploit a vulnerability in the internal Babel methods path.evaluate() or path.evaluateTruthy() by compiling specially crafted code, potentially resulting in arbitrary code execution during compilation. babel-traverse does not have a fix version. If you are using babel-traverse, switch to @babel/traverse.

Manual Review Advice: A vulnerability from this advisory is reachable if you use Babel to compile untrusted JavaScript

Fix: Upgrade this library to at least version 0.5.3 at sdks/package-lock.json:40336.

Reference(s): GHSA-67hx-6x53-jw92, CVE-2023-45133

ccashwell · 2025-11-19T14:49:06Z

@SocketSecurity ignore npm/[email protected]

semgrep-code-uniswap · 2025-11-19T14:53:51Z

Semgrep found 1 ssc-cee3e6d5-d7c8-4c35-9815-076aa1ebfd49 finding:

yarn.lock
- L10793 - Triage

Risk: Affected versions of rollup are vulnerable to Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting').

Manual Review Advice: A vulnerability from this advisory is reachable if you use Rollup to bundle JavaScript with import.meta.url and the output format is set to cjs, umd, or iife formats, while allowing users to inject scriptless HTML elements with unsanitized name attributes

Fix: Upgrade this library to at least version 2.79.2 at sdks/yarn.lock:10793.

Reference(s): GHSA-gcx4-mw62-g8wm, CVE-2024-47068

Semgrep found 2 ssc-aff5e8de-c638-4356-8a93-120597e35ce9 findings:

yarn.lock
- L141 - Triage
- L3726 - Triage

Risk: Affected versions of @babel/traverse, babel-traverse, @babel/plugin-transform-runtime, @babel/preset-env, @babel/helper-define-polyfill-provider, babel-plugin-polyfill-corejs2, babel-plugin-polyfill-corejs3, babel-plugin-polyfill-es-shims, and babel-plugin-polyfill-regenerator are vulnerable to Incomplete List Of Disallowed Inputs. An attacker can exploit a vulnerability in the internal Babel methods path.evaluate() or path.evaluateTruthy() by compiling specially crafted code, potentially resulting in arbitrary code execution during compilation. babel-traverse does not have a fix version. If you are using babel-traverse, switch to @babel/traverse.

Manual Review Advice: A vulnerability from this advisory is reachable if you use Babel to compile untrusted JavaScript

Fix: Upgrade this library to at least version 0.5.3 at sdks/yarn.lock:3726.

Reference(s): GHSA-67hx-6x53-jw92, CVE-2023-45133

Fix witness typestring generation to omit final closing parenthesis per The Compact spec, and add comprehensive tests validating complex nested mandate structures like those used in Tribunal. Changes: - Fix buildWitnessTypestring to remove final closing paren - Add 8 new tests for complex nested mandate types - Test simple nested structures - Test arrays in nested structures - Test alphabetical sorting of multiple nested types - Test Tribunal-like deeply nested structures with recursive refs - Test full Tribunal-style mandate with 5 nested types - Test bytes vs bytes32 in nested structures Added comprehensive tests to validate SDK mandate encoding against Tribunal's reference implementation: - Nested custom types (Mandate_*) - Arrays of nested types (Mandate_Fill[]) - Recursive type references (Mandate_Compact contains Mandate) - Complex multi-level nesting (up to 5 nested types) - Mandate typehash matches Tribunal's MANDATE_TYPEHASH constant - Mandate_Fill typehash matches MANDATE_FILL_TYPEHASH - Mandate_FillComponent typehash matches MANDATE_FILL_COMPONENT_TYPEHASH - Mandate_Lock typehash matches MANDATE_LOCK_TYPEHASH - All typehashes computed from typestrings match Tribunal contract constants - Full Tribunal mandate encoding test case from TribunalBasicTest.sol - Validates encoding structure (address + fillsHash = 64 bytes) - Verifies hash computation is deterministic These tests ensure the SDK's EIP-712 encoding is compatible with Tribunal's on-chain mandate derivation functions (deriveMandateHash, deriveFillHash).

@param

1) Add collectCoverageFrom and coverage reporting configuration to enable test coverage measurement. Includes text, text-summary, and HTML reporters. 2) Add complete parameter and return type documentation to all functions: Price Curve Library: - Document all parameters with types and descriptions - Add return type documentation with value ranges - Clarify scaling factor semantics (1e18 = neutral) - Document error conditions and edge cases Tribunal Builders: - Full @param documentation for all builder methods - Document chaining behavior with @returns - Add class-level documentation with usage examples - Document build() method preconditions Convenience Functions: - Complete parameter documentation for createSameChainFill() - Full parameter docs for createCrossChainFill() - Clarify cross-chain callback semantics 3) Add many new test cases for claim and batch claim functionality

…lders Add extensive class-level and method documentation to all builder classes in compact.ts and claim.ts, improving API discoverability and usage examples.

Replace basic README with comprehensive documentation covering all aspects of the SDK usage, from installation to advanced patterns.

Add functional e2e tests using Supersim for testing against forked chains

…eriods Add E2E test demonstrating batch compacts covering multiple resource locks with different reset periods, processed in a single batch claim transaction.

Add a simpler `fromCompact()` method to BaseBatchClaimBuilder that pre-fills sponsor, nonce, expires, and signature from a BatchCompact struct without requiring ids/amounts upfront. This provides a cleaner API for building batch claims: Before: ClaimBuilder.batch(domain) .sponsor(compact.sponsor) .nonce(compact.nonce) .expires(compact.expires) .addClaim()... After: ClaimBuilder.batch(domain) .fromCompact({ compact, signature }) .addClaim()... The method is inherited by BatchClaimBuilder, BatchMultichainClaimBuilder, and ExogenousBatchMultichainClaimBuilder, providing consistent API across all batch claim builder types.

Add calculators for various auction types including dutch and reverse dutch, stepped schedules and multi-phase auctions, as well as utils for conversion, evaluation and validation of curve configurations. - Dutch auction curves (exact-in mode, decreasing prices) - Reverse Dutch auction curves (exact-out mode, increasing prices) - Stepped price calculators with configurable intervals - Multi-phase auction builder supporting N phases - Percentage conversion utilities - Price evaluation and validation helpers - Curve composition tools (concatenate, plateau, flat price)

Add the official Tribunal allocator mandate type definition to the SDK and update README documentation with accurate usage examples. 1. **New TribunalMandate export** in src/builders/mandate.ts: - Complete type definition matching official Tribunal allocator structure - Includes all nested types: Fill, FillComponent, Lock, BatchCompact, RecipientCallback - Supports dynamic pricing via priceCurve arrays (compatible with price curve calculators) 2. **README improvements**: - Show integration with price curve calculators (createDutchAuction) - Demonstrate actual Tribunal mandate structure with all required fields - Document dynamic pricing, cross-chain fills, fill validation, callbacks

Update README to showcase the TribunalBuilder's fluent interface for composing Tribunal mandates, rather than passing inline configuration objects. Example pattern: ```typescript const mandate = TribunalBuilder.mandate() .adjuster(adjuster) .fill(f => f.chainId(1n).tribunal(addr).component(c => ...)) .build() const compact = await client.sponsor.compact() // ... .witness(TribunalMandate, mandate) .build() ```

marktoda

looks great! Love the builder pattern, feels quite clean.

Any thoughts for integration tests <> the code itself? for UniswapX we had a mini hardhat test suite that built orders with the SDK and executed them against the real solidity

sdks/the-compact-sdk/dist/cjs/src/abi/index.js.map

marktoda · 2025-11-20T00:27:41Z

sdks/the-compact-sdk/src/builders/claim.ts

+   * @returns This builder for chaining
+   * @throws {Error} If lockTag is not set before calling this method
+   */
+  addTransfer(params: { recipient: `0x${string}`; amount: bigint }): this {


probably worth doing some isAddress validation with viem or ethers just to check eip55 checksum and length etc. Presume there should be better types than 0xstring also

It is actually validated elsewhere but I am refactoring this file to be more DRY and will enforce Viem's Address or Hex types as appropriate

ccashwell · 2025-11-20T13:31:00Z

looks great! Love the builder pattern, feels quite clean.

Any thoughts for integration tests <> the code itself? for UniswapX we had a mini hardhat test suite that built orders with the SDK and executed them against the real solidity

I do have some E2E integration tests in sdks/the-compact-sdk/src/e2e.test.ts which use the SDK to perform the entire lifecycle from deposit to claim under a handful of different scenarios, more to be done here for sure.

Refactored claim builder hierarchy to eliminate code duplication by introducing base classes: - Created BaseClaimBuilder abstract class with common fields (sponsor, nonce, expires, allocatorData, sponsorSignature, witness) - Created BaseSingleResourceClaimBuilder extending BaseClaimBuilder with single resource fields (id, allocatedAmount, claimants, lockTag) and methods (addTransfer, addConvert, addWithdraw, addClaimant, addComponent) - Refactored SingleClaimBuilder to extend BaseSingleResourceClaimBuilder - Refactored MultichainClaimBuilder to extend BaseSingleResourceClaimBuilder - Refactored ExogenousMultichainClaimBuilder to extend MultichainClaimBuilder - Refactored BaseBatchClaimBuilder to extend BaseClaimBuilder

Implemented allocator address to allocator ID conversion matching the Solidity IdLib.sol implementation: - Added `allocatorToAllocatorId(allocator: Address): bigint` function to convert allocator addresses to uint96 allocator IDs - Added internal `toCompactFlag(allocator: Address): number` helper to compute 4-bit compact flags using bit manipulation and population counting - Compact flag represents the position of the first set bit in the upper 72 bits of the address, used for efficient storage - Final allocator ID combines: upper 4 bits (compact flag) + lower 88 bits of address

ccashwell requested a review from a team as a code owner November 19, 2025 14:47

ccashwell force-pushed the the-compact-sdk branch from ea4483d to 336bb1e Compare November 19, 2025 15:26

ccashwell and others added 17 commits November 19, 2025 16:21

feat(client): complete ArbiterClient with multichain support and TSDoc

ac8439a

test(client): add comprehensive unit tests

d09d24c

chore(test, doc): update to jest 29.x, add comprehensive TSDoc to bui…

b8562e2

…lders Add extensive class-level and method documentation to all builder classes in compact.ts and claim.ts, improving API discoverability and usage examples.

docs: create comprehensive README with detailed SDK usage guide

261d1f5

Replace basic README with comprehensive documentation covering all aspects of the SDK usage, from installation to advanced patterns.

feat(e2e): add comprehensive end-to-end integration test suite

5415672

Add functional e2e tests using Supersim for testing against forked chains

test(e2e): add comprehensive batch compact test with multiple reset p…

e91ebea

…eriods Add E2E test demonstrating batch compacts covering multiple resource locks with different reset periods, processed in a single batch claim transaction.

chore(docs): update E2E_TESTING.md

b2577f8

Update README.md

c8b42fb

Update README.md

4d02937

chore(eslint): resolve eslint warnings

2b9cdd9

chore(monorepo): update yarn.lock

6786c5f

chore(eslint): resolve remaining code style warnings

2cb0119

chore(monorepo): modify deps to more closely match monorepo

8be5ee6

chore(ci): resolve monorepo dep mismatch

3ce7a77

ccashwell force-pushed the the-compact-sdk branch from 079252f to 35c880c Compare November 19, 2025 21:22

ccashwell force-pushed the the-compact-sdk branch 3 times, most recently from 3b6f0e6 to 4aaae2c Compare November 19, 2025 21:56

ccashwell force-pushed the the-compact-sdk branch from 4aaae2c to c373b3e Compare November 19, 2025 22:29

ccashwell marked this pull request as draft November 19, 2025 22:29

marktoda reviewed Nov 20, 2025

View reviewed changes

chore: rm dist and add to gitignore

363128d

ccashwell added 3 commits November 20, 2025 08:45

feat(tribunal): add random default salt, update types

789b96e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(the-compact-sdk): implement The Compact SDK #438

feat(the-compact-sdk): implement The Compact SDK #438

Uh oh!

ccashwell commented Nov 18, 2025

Uh oh!

socket-security bot commented Nov 18, 2025 •

edited

Loading

Uh oh!

socket-security bot commented Nov 18, 2025 •

edited

Loading

Uh oh!

semgrep-code-uniswap bot commented Nov 18, 2025

Uh oh!

ccashwell commented Nov 19, 2025

Uh oh!

semgrep-code-uniswap bot commented Nov 19, 2025

Uh oh!

marktoda left a comment

Uh oh!

Uh oh!

marktoda Nov 20, 2025

Uh oh!

ccashwell Nov 20, 2025

Uh oh!

ccashwell commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(the-compact-sdk): implement The Compact SDK #438

Are you sure you want to change the base?

feat(the-compact-sdk): implement The Compact SDK #438

Uh oh!

Conversation

ccashwell commented Nov 18, 2025

Uh oh!

socket-security bot commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security bot commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

semgrep-code-uniswap bot commented Nov 18, 2025

Uh oh!

ccashwell commented Nov 19, 2025

Uh oh!

semgrep-code-uniswap bot commented Nov 19, 2025

Uh oh!

marktoda left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marktoda Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

ccashwell Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

ccashwell commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

socket-security bot commented Nov 18, 2025 •

edited

Loading

socket-security bot commented Nov 18, 2025 •

edited

Loading