polkamarkets-js 3.4.5 → 4.0.0

package/.claude/settings.local.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:polygonscan.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebSearch",
+      "Bash(git log:*)",
+      "Bash(forge build)",
+      "Bash(forge build --contracts test/PredictionMarketCLOB.t.sol)",
+      "Bash(forge build --contracts test/AdminRegistry.t.sol)",
+      "Bash(python3 -c \":*)",
+      "Bash(forge test --match-path \"test/AdminRegistry.t.sol\" -v)",
+      "Bash(forge test --match-test \"testGrantRoleByNonAdminReverts|testAfterTransfer\" -vvv --match-path \"test/AdminRegistry.t.sol\")",
+      "Bash(forge test --match-path \"test/FeeModule.t.sol\" -v)",
+      "Bash(forge test --match-path \"test/ConditionalTokens.t.sol\" -v)",
+      "Bash(forge test --match-path \"test/MyriadCTFExchange.t.sol\" -v)",
+      "Bash(forge test --match-path \"test/MyriadCTFExchange.t.sol\" --match-test \"testMatchOrdersWithFeesByNonOperatorReverts|testMarketMismatchReverts\" -vvv)",
+      "Bash(forge test --match-path \"test/AdminRegistry.t.sol|test/FeeModule.t.sol|test/ConditionalTokens.t.sol|test/MyriadCTFExchange.t.sol\" -v)",
+      "Bash(forge test --match-contract \"AdminRegistryTest|FeeModuleTest|ConditionalTokensTest|MyriadCTFExchangeTest\" -v)",
+      "Bash(forge test -v)",
+      "Bash(cast sig:*)",
+      "Bash(pip3 install:*)",
+      "Bash(pip install:*)",
+      "Bash(node -e \":*)",
+      "Bash(forge inspect:*)",
+      "Bash(curl -s \"https://api.github.com/repos/Polkamarkets/polkamarkets-js/releases?per_page=5\")"
+    ]
+  }
+}

package/CLOB_AUDIT_REPORT.md

@@ -0,0 +1,305 @@
+# Myriad CLOB Smart Contract Audit Report
+
+- Review date: 2026-04-08
+- Repository: `polkamarkets/bepro-js`
+- Review target: `/contracts` diff against `main`
+- Reviewed branch: `fix-135-mint-merge-match-settling`
+- Reviewer: Codex
+
+## Executive Summary
+
+This review covered the newly introduced CLOB contract stack added in the `/contracts` diff against `main`, with particular focus on:
+
+- `MyriadCTFExchange`
+- `ConditionalTokens`
+- `PredictionMarketV3ManagerCLOB`
+- `NegRiskAdapter`
+- `WrappedCollateral`
+- `FeeModule`
+- `AdminRegistry`
+- `RealitioOracle`
+
+The system introduces a substantial new settlement surface: off-chain signed orders matched on-chain, ERC1155 conditional positions, per-market fee routing, pluggable oracle resolution, and a neg-risk adapter that uses unbacked wrapped collateral minting as an internal accounting primitive.
+
+The review identified one high-severity issue and three medium-severity issues. The most important finding is a solvency failure in neg-risk void handling: malformed but currently allowed event-level void payouts can leave permanent unbacked `WCOL` in circulation and let those tokens drain future deposits.
+
+## Scope
+
+The following contracts were in scope because they are newly added or materially changed relative to `main`:
+
+- `contracts/AdminRegistry.sol`
+- `contracts/ConditionalTokens.sol`
+- `contracts/FeeModule.sol`
+- `contracts/IMarketOracle.sol`
+- `contracts/IMyriadMarketManager.sol`
+- `contracts/MyriadCTFExchange.sol`
+- `contracts/NegRiskAdapter.sol`
+- `contracts/Outcomes.sol`
+- `contracts/PredictionMarketV3ManagerCLOB.sol`
+- `contracts/WrappedCollateral.sol`
+- `contracts/oracles/RealitioOracle.sol`
+
+`CLOB_SDK_REFERENCE.md` was also reviewed because it describes expected system behavior and trust assumptions for launch.
+
+## Methodology
+
+The review was performed as a manual adversarial code audit focused on:
+
+- asset accounting and solvency
+- trust boundaries and role separation
+- order lifecycle and stale-order risk
+- settlement invariants across split, merge, redeem, and cross-market matching
+- neg-risk event resolution and cleanup
+- privileged operations, upgradeability, and wiring assumptions
+
+`forge build` succeeds locally. `forge test` could not be executed in this environment because the installed Foundry nightly crashes before test execution in `system_configuration::dynamic_store`. As a result, findings are based on source review plus compile verification rather than a successful local test run.
+
+## Severity Definitions
+
+- High: direct loss of funds, persistent insolvency, or a launch-blocking safety failure
+- Medium: meaningful integrity or availability risk, especially when combined with normal operator/admin actions
+- Low: limited impact issue or hardening gap
+- Informational: non-exploitable risk, documentation mismatch, or operational observation
+
+## Findings Summary
+
+| ID | Severity | Title |
+| --- | --- | --- |
+| H-01 | High | Neg-risk voiding can leave unbacked `WCOL` in circulation and drain future deposits |
+| M-01 | Medium | Market admins can reopen naturally closed markets and revive stale GTC orders |
+| M-02 | Medium | Market admins can swap the oracle after close and seize settlement |
+| M-03 | Medium | Rotating the global neg-risk adapter can strand live events |
+
+## Detailed Findings
+
+### H-01: Neg-risk voiding can leave unbacked `WCOL` in circulation and drain future deposits
+
+**Severity:** High
+
+**Affected contracts:**
+
+- `contracts/NegRiskAdapter.sol`
+- `contracts/WrappedCollateral.sol`
+- `contracts/PredictionMarketV3ManagerCLOB.sol`
+
+**Description**
+
+The neg-risk system relies on `WrappedCollateral` (`WCOL`) as a wrapper over real collateral plus an adapter-only unbacked mint path used during conversion and cross-market minting.
+
+That design is only solvent if event-level resolution preserves the accounting invariant between:
+
+- user-held YES sets
+- adapter-held NO inventory
+- adapter-minted unbacked `WCOL`
+
+`voidEvent()` currently validates only each market in isolation:
+
+- each per-market pair is forced to sum to `1e18` via `manager.adminVoidMarket(...)`
+- but there is no event-level bound on `sum(yesPayouts)`
+
+Relevant code:
+
+- `contracts/NegRiskAdapter.sol`
+  - `voidEvent()` accepts arbitrary `yesPayouts` arrays with only a length check
+  - each market is then voided with `YES = yesPayouts[i]` and `NO = 1e18 - yesPayouts[i]`
+- `contracts/PredictionMarketV3ManagerCLOB.sol`
+  - `adminVoidMarket()` validates only that each market's two payouts sum to `1e18`
+- `contracts/NegRiskAdapter.sol`
+  - `redeemNOPositions()` burns `min(mintedWcolPerEvent[eventId], wcolRecovered)` and then zeroes the event accounting regardless of whether all minted `WCOL` was actually recovered
+- `contracts/WrappedCollateral.sol`
+  - `unwrap()` is global and permissionless, so any surviving unbacked `WCOL` can later redeem against unrelated backing
+
+For converted or cross-market-created full YES baskets, solvency requires `sum(yesPayouts) <= 1e18`. If the sum exceeds `1e18`, YES holders can redeem more `WCOL` than the adapter can recover from its NO positions. The deficit is not tracked after cleanup because `mintedWcolPerEvent[eventId]` is zeroed even when recovery is incomplete.
+
+**Impact**
+
+This can create persistent bad debt inside `WCOL`:
+
+1. a neg-risk event is voided with an over-allocating YES vector
+2. YES holders redeem more `WCOL` than the system can safely back
+3. cleanup burns only the recoverable portion of minted `WCOL`
+4. leftover unbacked `WCOL` remains transferable and unwrap-capable
+5. future wrappers or unrelated users provide fresh underlying backing
+6. the unbacked `WCOL` drains that new backing
+
+This is a direct cross-user and cross-event solvency failure.
+
+**Exploit sketch**
+
+For a 3-outcome event:
+
+- Alice deposits `100`
+- Alice converts into a full YES basket across all three markets
+- admin voids the event with `yesPayouts = [0.5, 0.5, 0.5]`
+- Alice redeems `150 WCOL`
+- adapter NO cleanup recovers only `150 WCOL` against `200 WCOL` minted during conversion, burns `150`, and zeroes the accounting
+- `WCOL` supply still exceeds real underlying by `50`
+- Alice can later drain a new user's wrapped deposit using the surviving unbacked `WCOL`
+
+The repository now includes a proof-of-concept test at `test/POC.t.sol` demonstrating this behavior.
+
+**Why this is especially concerning**
+
+The current tests explicitly treat `50/50/50` event void payouts as acceptable for a 3-outcome event:
+
+- `test/NegRiskAdapter.t.sol`
+  - `testVoidEvent5050`
+  - `testVoidEventRedeemNOPositions`
+
+That makes the issue more than a hypothetical malicious-admin corner case. The repository already encodes an event-level payout shape that breaks wrapper solvency.
+
+**Recommendations**
+
+At minimum:
+
+1. enforce an event-level invariant in `voidEvent()`:
+   - `sum(yesPayouts) <= 1e18`
+2. do not zero `mintedWcolPerEvent[eventId]` unless full recovery occurred
+3. if partial recovery is ever possible, preserve explicit bad-debt accounting and prevent unrelated backing from being consumed silently
+
+Stronger mitigations:
+
+1. silo wrapper accounting per event rather than sharing one global redeemable wrapper
+2. treat over-allocating void vectors as invalid resolution inputs rather than as treasury/accounting events
+3. add invariant tests asserting `underlying.balanceOf(wcol) >= wcol.totalSupply()` after every resolution path
+
+---
+
+### M-01: Market admins can reopen naturally closed markets and revive stale GTC orders
+
+**Severity:** Medium
+
+**Affected contracts:**
+
+- `contracts/PredictionMarketV3ManagerCLOB.sol`
+- `contracts/MyriadCTFExchange.sol`
+
+**Description**
+
+`adminSetClosesAt()` can move `closesAt` forward on any unresolved market, even if the market has already closed by time.
+
+The manager does not persist a closed state transition. Instead, close status is derived at read time:
+
+- if `market.state == open` and `block.timestamp >= closesAt`, `getMarketState()` returns `closed`
+- `isMarketTradeable()` similarly depends on `block.timestamp < closesAt`
+
+If a market has naturally closed and an admin later extends `closesAt`, the market becomes tradeable again.
+
+**Impact**
+
+The SDK documents `expiration = 0` as GTC order behavior. That means old signed orders can remain valid indefinitely. Reopening a closed market can therefore reactivate stale orders under new information, which is a serious integrity problem for an orderbook launch.
+
+This is especially dangerous when:
+
+- users rely on market close as a hard boundary for stale orders
+- off-chain infra preserves order validity until explicit expiration or cancellation
+- admins use close-time edits operationally without realizing they are reviving execution rights
+
+**Recommendations**
+
+1. forbid extending `closesAt` after a market has already closed
+2. if edits are needed, allow only shortening while the market is still open
+3. alternatively, permanently latch close once first reached
+4. if reopening must exist, invalidate all outstanding orders for that market as part of the action
+
+---
+
+### M-02: Market admins can swap the oracle after close and seize settlement
+
+**Severity:** Medium
+
+**Affected contracts:**
+
+- `contracts/PredictionMarketV3ManagerCLOB.sol`
+
+**Description**
+
+`updateMarketOracle()` is callable by `MARKET_ADMIN_ROLE` on any unresolved market. There is no restriction that the market must still be open.
+
+As a result, after trading has ended but before settlement, a market admin can:
+
+- replace the oracle with a malicious oracle that returns a chosen result
+- replace the oracle with a non-resolving oracle and freeze permissionless settlement
+- reinitialize oracle-side state with new `oracleData`
+
+`resolveMarket()` then trusts the currently configured oracle.
+
+**Impact**
+
+This collapses the trust boundary between market administration and resolution. In the current role model, market creation/maintenance and final settlement are presented as separate concerns, but the contract lets a market admin rewrite the settlement source after trading is over.
+
+That creates a meaningful integrity risk even if `RESOLUTION_ADMIN_ROLE` is intended to be tightly controlled.
+
+**Recommendations**
+
+1. freeze oracle changes once the market closes
+2. preferably freeze oracle changes immediately after market creation unless there is a clearly documented emergency path
+3. if emergency oracle replacement is required, gate it behind `RESOLUTION_ADMIN_ROLE` plus a timelock or pause
+4. emit stronger operational guidance that oracle changes alter settlement trust assumptions
+
+---
+
+### M-03: Rotating the global neg-risk adapter can strand live events
+
+**Severity:** Medium
+
+**Affected contracts:**
+
+- `contracts/PredictionMarketV3ManagerCLOB.sol`
+- `contracts/MyriadCTFExchange.sol`
+
+**Description**
+
+The manager and exchange each store a single mutable `negRiskAdapter` address:
+
+- manager uses it to authorize neg-risk market creation and neg-risk admin resolution
+- exchange uses it for cross-market minting
+
+However, neg-risk events are stateful:
+
+- the adapter itself stores event membership and question text
+- the adapter holds NO inventory
+- the adapter tracks minted `WCOL` per event
+
+If governance rotates `negRiskAdapter` after events are already live:
+
+- the old adapter still owns the state and positions
+- the manager stops recognizing the old adapter as the authorized neg-risk resolver
+- the exchange starts calling the new adapter for cross-market operations
+- the new adapter has no knowledge of old events
+
+**Impact**
+
+This can strand live events and freeze event-specific flows even if all parties are honest. It is an availability and operational safety issue with funds in flight.
+
+**Recommendations**
+
+1. make the adapter immutable once the first neg-risk event is created
+2. or store the adapter address per event/market at creation time and always route through that stored adapter
+3. document migration explicitly if adapter replacement is intended
+
+## Informational Observations
+
+### I-01: SDK/reference documentation is materially out of sync with the contracts
+
+The reviewed `CLOB_SDK_REFERENCE.md` does not match the current contract surface in several important places:
+
+- unresolved outcome docs describe `-2`, while the manager returns `-3`
+- voided redemption example calls `redeemPositions`, while the contract exposes `redeemVoided`
+- fee docs describe array-based fee schedules and a 3-argument `withdrawFees`, while the contract uses tier structs and a 2-argument withdrawal
+
+This mismatch increases integration risk and could lead client code to make unsafe assumptions about settlement and fee behavior.
+
+### I-02: The new stack depends on transient storage reentrancy guards
+
+`PredictionMarketV3ManagerCLOB`, `MyriadCTFExchange`, and `NegRiskAdapter` use OpenZeppelin transient reentrancy guards, which require EIP-1153 support. Public BNB Chain sources indicate support is present, so this is not an immediate launch blocker for BSC, but it should be treated as a deployment precondition for any other target network.
+
+### I-03: Local test execution was blocked by a Foundry nightly crash
+
+The installed Foundry nightly panics before test execution in `system_configuration::dynamic_store`. `forge build` succeeds. The included PoC was therefore added and compile-checked, but not executed in this environment.
+
+## Conclusion
+
+The new CLOB contracts are thoughtfully structured and cover many important behaviors with tests, but the neg-risk accounting model currently has a launch-blocking solvency issue. The medium-severity findings also show that a few privileged operations remain too powerful relative to the role model described in the SDK and expected by traders.
+
+I would not recommend launching the neg-risk component in its current form before H-01 is fixed and the privileged lifecycle behaviors are narrowed or explicitly accepted as protocol trust assumptions.