How it works

The pipeline

Every step hands a pinned, hashed artifact to the next, so a result can always be traced back to the block it was computed from.

1. SnapshotReads the whole account and all 21 pools at one block, then rechecks the block hash.snapshot.ts
2. ReconcileRebuilds health equity and margin requirements from raw state and compares them with the bank's own getter.reconcile.ts
3. ScenarioFixes absolute BTC and ETH prices; every other held market stays at its reference mark. The object is hashed.scenario.ts
4. CandidatesPrices 25, 50, 75 and 100% reductions against the live book, then values what remains at the scenario prices.candidates.ts
5. Confirm and refreshJournals the chosen action before anything is sent and re-reads the account right before sending.action.ts · journal.ts · refresh.ts
6. GuardExecutes the reduction only if the live position equals the confirmed one, and reverts if the position flips or grows.ReduceOnlyGuard.sol
7. Bind and recomputeCredits a receipt only if it is the confirmed action, then values the real post-fill account at the original scenario prices.receipt.ts · recompute.ts
8. Clean upCloses what the run opened through the guard, revokes grants, withdraws and verifies the end state at one block.cleanup.ts · txlog.ts

What comes from dreamDEX

Margin Rescue is built on dreamDEX's perps testnet and uses the venue's own contracts and tools as they are. Nothing of the venue is forked, wrapped or re-hosted; the only new contract is the owner's own guard.

What is Margin Rescue's own: the TypeScript client (snapshot, reconciliation, scenario, candidates, executor, run ledger, this site) and ReduceOnlyGuard.sol, deployed by each owner for their own account.

One snapshot, one block

An analysis starts by sampling one block number and hash. Every read that follows is pinned to that block: the bank's collateral and health getters, every position in every one of the factory's 21 pools (the bank's active list is cross-checked against the full factory list), resting orders, the account mode, wallet balance and allowance, and the BTC and ETH order books. TP/SL stops are listed from the indexer, paged to the end, refused if the indexer has not yet processed the pinned block, and then checked on chain at that block. After the reads, the block hash is checked again to confirm the block is still canonical.

Anything missing or inconsistent becomes a named problem on the snapshot: a stale mark, a pool outside the bank's list, a failed read, an unlisted stop set. Any problem blocks a recommendation.

The accounting

Health is rebuilt from raw integers with the deployment's own rounding. No floating point is used anywhere a decision is made.

E_risk  = unlocked + Σ floor((mark − entry) × size / oneBase)
                   − Σ ceil(size × (cumFunding − entryFundingIndex) / (1e18 × oneBase))
E_total = E_risk + locked
MM      = Σ ceil(floor(|size| × mark / oneBase) × mmBps / 10000)
buffer  = E_risk − MM

E_risk is what the bank compares with its requirements. Collateral locked behind resting orders is not part of it, and cancelling an order only moves collateral from locked to unlocked. TP/SL stops prepay STT, which is not USDso collateral and is never counted.

Because every reconciled account matched the bank to the raw unit, the model is treated as deployment-exact and the numerical error bound is zero. Truncation fails for every account with a negative, inexact PnL leg, by at most one raw unit per such leg.

The fixed scenario

A scenario is a canonical JSON object whose id is its SHA-256. It fixes the chain, MarginBank, account, reference block number, hash and time, and, for every held market, the pool, units, reference mark, absolute scenario price, configured risk rates and fees. It also records the funding assumption, the model version and the target buffer.

Only BTC and ETH can be shocked. Every other held market stays at its reference mark and stays in the calculation. A shock of −8% on a reference of 79,976.86 becomes the absolute price 73,578.71, and that price is kept: after an execution the account is valued at 73,578.71 again, not shocked another 8% from wherever the market went.

The shock is instantaneous and static: no price path, no stop or liquidation on the way, no funding accrual during the shock. A later snapshot with changed risk rates or a newly held market cannot be valued under the old scenario.

Candidates

The candidate set is small and explicit: no action; reductions of 25, 50, 75 and 100% of each BTC or ETH position, aligned down to the lot and deduplicated; and, on request, cancelling all ordinary resting orders.

Each reduction is previewed now, against the order book read at the reference block, with a protective IOC limit 50 bps beyond the touch. Realized PnL is floored per fill, fees are charged per fill, and funding owed on the whole position is settled once. The remaining portfolio is then valued at the scenario prices.

A candidate is unavailable if it rounds to zero, falls below the minimum order, would leave a remainder below the minimum, would self-match a resting order of the same account, or finds nothing inside its limit. If doing nothing already meets the target, nothing is recommended. Among candidates that meet it, the smallest current notional reduction is preferred, then the lowest cost. That is a choice among the evaluated candidates, not a global optimum.

The reduce-only guard

The venue has no immediate reduce-only order: placeOrder and placeOrderFor take no such flag, the order type is a closed enum of four, and the official close helper sends a plain opposite-side IOC. So ReduceOnlyGuard acts as the account's own operator, with these properties:

• Deployed per owner, with the chain (50383), MarginBank and trusted pools fixed at construction.
• Admitted by the owner's per-pool grant of placeOrderFor (selector 0x80054449) in the OperatorPermissionsRegistry, the same grant dreamDEX's “Link a bot” writes.
• Callable only by the owner. It places only IOC orders for the owner, cancelling the taker on a self-match.
• Each action has an id that commits to the chain, guard, bank, owner, pool, the exact signed position the owner confirmed, side, quantity, limit, deadline, order type and a nonce.
• Before the venue call: the live position must equal the confirmed one exactly, the side must reduce it, and 0 < quantity ≤ |position|, on the lot and above the minimum. The id is reserved and a reentrancy lock held.
• After the venue call: the position must be on the same side or flat, no larger, and reduced by at most the quantity. Otherwise the whole transaction reverts, venue fills included.
• It holds no tokens and has no deposit, withdraw, approve, cancel or arbitrary-call function.

On a fork of the real venue, a test-only harness that skips the guard's preconditions makes the venue flip a position. The production postcondition then reverts everything, and the trace is kept as evidence.

Execution and the run ledger

An action record is written before anything is broadcast. It tracks three states separately: the transaction (NOT_SENT, PENDING, UNKNOWN, REVERTED, CONFIRMED, NOT_INCLUDED, INVALIDATED), the fill (NO_FILL, PARTIAL_FILL, REQUESTED_FILL) and the goal (GOAL_MET, GOAL_NOT_MET, BASELINE_CHANGED, UNAVAILABLE, EVIDENCE_MISMATCH).

Refresh. Right before sending, the account is read again at one pinned block. The confirmation is invalidated, and never sent, if any position, collateral, order, stop, account mode, allowance or risk setting changed, if the fresh read does not reconcile exactly, if the candidates re-evaluated under the original scenario now select a different one, if the confirmed order would fill a different amount against the fresh book, or if less than 30 seconds remain to its deadline.

Unknown transactions. Every transaction a run sends is persisted with its hash and nonce before the signed bytes leave the process; the bytes themselves are never written. A step without a receipt is resolved from chain data before anything else is sent. Only a canonical receipt settles it. A failed lookup is not “not found”, and a used nonce proves nothing until the transaction that consumed it is located with a different hash. Until then the step stays UNKNOWN, its worst-case fee stays reserved, and the run stops with exit 40 so it can be resumed.

Cleanup. Cleanup is driven by chain state. Each remaining position is closed by a guarded full close, at most three attempts per leg; a leg the guard cannot close is reported and never closed with an unguarded order. Grants are revoked, collateral withdrawn and the allowance cleared, and the end state is verified at one block across all 21 pools. Every main-phase send must leave enough gas under the plan's cap for the cleanup the run could need right after it: at most 12 transactions at 13M gas each for the live plan.

Binding and recomputation

Before a receipt is credited, it is bound to the saved confirmation: sender, destination, exact calldata, hash, nonce, value, chain, the guard's single ReduceExecuted event and the taker order's owner. A mismatch is EVIDENCE_MISMATCH. In tests, 19 synthetic tamperings and six alterations of a real fork receipt were all refused.

Then the ledger has to be explained by the transaction's own rows: the size moved by exactly the fills, realized PnL floored per fill, funding settled once on the whole position, fees on each fill's notional, unlocked collateral moved by realized − funding − fees, and nothing else in the account touched. Anything unexplained gives BASELINE_CHANGED rather than credit. Finally the real remaining portfolio is valued at the scenario's original absolute prices and shown beside the baseline, the forecast and the account's actual health.

Exit codes

An unexpected error is classified from the run ledger persisted before each broadcast and the process's own count of signatures and broadcasts, never assumed to be a refusal. After 40, 50 or 60 no fresh run of the account starts until that run is finished. A resume that stops before signing anything writes nothing and exits with the run's own state; one that reaches a new result it cannot write exits with that result, never 0.

The read-only commands exit non-zero too: reconcile 3 unless EXACT, analyze 3 when blocked, plan and refresh 4 when the confirmation is refused or invalidated, and recompute 0 only for GOAL_MET.

Network, contracts, versions

Evidence

Each claim on this site is labelled by where it was checked. Fixture means synthetic data in unit tests. Fork means a local anvil fork of the real venue at a recorded block. Live means the Somnia Hideki network itself. The live write, one guarded reduction on the project's own test account, has run: goal met, cleanup verified. The app shows its transactions, recomputation and cleanup.

Limitations

• The scenario is static. It says nothing about the path to the shocked prices, about fills of resting orders or stops on the way, or about liquidation. An expected fill is not a guaranteed fill.
• Candidates are finite. The preferred candidate is the best among those evaluated, not a global optimum.
• Faults on the fork were injected by the rehearsal. They show how the executor responds, not how often such events happen live.
• Stops are listed from the indexer and checked on chain; the registry has no on-chain enumeration, so their completeness still rests on the indexer.
• Fork gas figures follow Ethereum's schedule, not Somnia's. The live plan asks the live RPC for estimates.
• Testnet only. Nothing here touches mainnet or real funds.