Add OUSD V3 and OETHb migration contracts by shahthepro · Pull Request #2909 · OriginProtocol/origin-dollar

shahthepro · 2026-06-01T10:06:32Z

Summary

OUSD V3 cross-chain strategy pair (Master/Remote) with bridge-agnostic adapter family (CCIP, CCTP V2, Superbridge), plus Sepolia ⇄ Base Sepolia testnet harness. Foundation for OETHb Phase 1 migration and future OUSD V3 L2 deployment rollouts.

Changes

Master + Remote strategies with separated yield channel (nonce-gated) and bridge channel (nonceless, replay-protected).
Adapters (CCIPAdapter, CCTPAdapter, SuperbridgeAdapter) on a shared AbstractAdapter base — multi-tenant whitelist, per-lane config, governor-settable maxTransferAmount cap.
CREATE3 proxies (BridgeAdapterProxy, CrossChainStrategyProxy) so paired chains share addresses (required for the transportSender == address(this) peer-parity check).
CCTPAdapter.relay() manually parses CCTP V2 burn body (works on V2.0 and V2.1, doesn't depend on V2.1-only auto-callback).
Sepolia + Base Sepolia network registration end-to-end (hardhat.config.js, helpers, addresses, scripts, fork-test.sh). Testnet deploy scripts with mock vault/token.
Production OETHb deploys (deploy/base/100-104_*, deploy/mainnet/210-211_*) with CREATE3 adapter proxies.
FLOWS.md (sequence diagrams)

codecov · 2026-06-08T10:43:22Z

Codecov Report

❌ Patch coverage is 83.38945% with 148 lines in your changes missing coverage. Please review.
✅ Project coverage is 50.57%. Comparing base (c52692d) to head (dd40635).

Files with missing lines	Patch %	Lines
...racts/strategies/BridgedWOETHMigrationStrategy.sol	0.00%	45 Missing ⚠️
...egies/crosschainV3/adapters/SuperbridgeAdapter.sol	56.52%	30 Missing ⚠️
...s/strategies/crosschainV3/adapters/CCIPAdapter.sol	54.54%	15 Missing ⚠️
...rategies/crosschainV3/adapters/AbstractAdapter.sol	86.00%	14 Missing ⚠️
...s/strategies/crosschainV3/adapters/CCTPAdapter.sol	88.29%	11 Missing ⚠️
.../strategies/crosschainV3/MasterWOTokenStrategy.sol	95.42%	8 Missing ⚠️
contracts/contracts/utils/BytesHelper.sol	0.00%	8 Missing ⚠️
...gies/crosschainV3/AbstractCrossChainV3Strategy.sol	87.93%	7 Missing ⚠️
...trategies/crosschainV3/AbstractWOTokenStrategy.sol	94.31%	5 Missing ⚠️
.../strategies/crosschainV3/RemoteWOTokenStrategy.sol	97.10%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2909      +/-   ##
==========================================
+ Coverage   44.63%   50.57%   +5.94%     
==========================================
  Files         110      123      +13     
  Lines        4920     5811     +891     
  Branches     1362     1641     +279     
==========================================
+ Hits         2196     2939     +743     
- Misses       2721     2869     +148     
  Partials        3        3

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Moved the adapter participants close to the Bridge

naddison36

The next batch review comments

naddison36 · 2026-07-01T05:18:08Z

+    }
+
+    function _opportunisticClaim() internal {
+        uint256 stored = outstandingRequestId;


nit: its not clear what store is later in the function code. I would use outstandingRequestIdMem instead

Done: d8331cf

naddison36 · 2026-07-01T05:20:48Z

+            return;
+        }
+        // `outstandingRequestId` stores the vault id verbatim.
+        uint256 vaultRequestId = stored;


Why create a new memory variable for what's stored in outstandingRequestId?

Thanks, cleaned it up in this commit: 82f0179

naddison36 · 2026-07-01T06:10:38Z

+        // auto-deposits once enough accumulates. A revert here would DoS the mint ->
+        // `_allocate` -> `deposit` path. Covers both `deposit` and `depositAll`.
+        if (_amount < IBridgeAdapter(outboundAdapter).minTransferAmount()) {
+            return;


Feels like we should emit an event here since we are not doing the requested deposit while not failing the tx

There's a new DepositSkipped event being emitted now: 82f0179

naddison36 · 2026-07-01T06:19:43Z

+    }
+
+    /// @inheritdoc IAny2EVMMessageReceiver
+    function ccipReceive(Client.Any2EVMMessage calldata message)


What guarantees, if any, does the CCIP Distributed Oracle Network (DON) provide for calling ccipReceive?
What if no DON participant calls ccipReceive? Can we retrigger the CCIP message?

From what I can tell, if the DON does not call ccipReceive then our strategy is stuck.

If for someone the CCIP message relaying fails, anyone can manually trigger it again: https://docs.chain.link/ccip/concepts/manual-execution

I'll add it as a comment though

Have added that comment: 82f0179

naddison36 · 2026-07-01T06:56:19Z

+        }
+
+        uint64 nonce = _getNextYieldNonce();
+        pendingDepositAmount = _amount;


nit: I like to make it clear when storage variables are writing back to storage. I'd add a comment like
// Store the pending deposit amount until the remote deposit is acknowledged.

Done: 82f0179

naddison36 · 2026-07-01T06:57:29Z

+        );
+
+        uint64 nonce = _getNextYieldNonce();
+        pendingWithdrawalAmount = _amount;


nit: I like to make it clear when storage variables are writing back to storage. I'd add a comment like
// Store the pending withdrawal amount until the remote withdrawal is claimed.

Done: 82f0179

naddison36 · 2026-07-01T07:00:51Z

+    function _processDepositAck(uint64 nonce, bytes memory payload) internal {
+        _markYieldNonceProcessed(nonce);
+        uint256 yieldBaseline = CrossChainV3Helper.decodeUint256(payload);
+        remoteStrategyBalance = yieldBaseline;


nit: I'd add a comment to make it clear this is a write to storage. eg

// Store the acknowledged deposit in the remote balance and clear the pending amount. remoteStrategyBalance = yieldBaseline; pendingDepositAmount = 0;

Done: 82f0179

naddison36 · 2026-07-02T08:33:19Z

+`CCTPAdapter._quoteFee` calls `tokenMessenger.getMinFeeAmount(amount)`,
+which is V2.1-only. If a chain has only V2.0 deployed, `quoteFee(amount > 0)`
+reverts. Current deploys (OETHb) don't use CCTP at all, so this is a
+non-issue. OUSD V3 spoke chains must be on V2.1 — check before deploying.


A link to where to check what CCTP version is deployed on each chain would be useful

Done in this commit: 82f0179

naddison36 · 2026-07-02T09:13:18Z

+ *
+ *         Reverts when the chosen source doesn't cover `fee`.
+ */
+library NativeFeeHelper {


nit: There's only one function in this library. Feels like it'd be simpler if consume was moved to the BridgedWOETHMigrationStrategy strategy as an internal function.

Removed it and made it an internal function: 82f0179

naddison36 · 2026-07-02T09:19:23Z

+    function bridgeToRemote(uint256 _amount)
+        external
+        payable
+        onlyOperatorGovernorOrStrategist


it still feels like migrating over 15m USD worth of ETH should have some operational checks. Setting up an automated Talos Action without human checks doesn't feel right.
Unless there are some risks with partially migrated funds. Does migrating the funds ASAP mean less risk of an accounting error?

naddison36 · 2026-07-02T09:35:10Z

+    function bridgeToRemote(uint256 _amount)
+        external
+        payable
+        onlyOperatorGovernorOrStrategist


The Operator is set to the Strategist in the deploy script so lets just use onlyGovernorOrStrategist.

// 3. Authorise the multichain strategist as the operator for `bridgeToRemote`. { contract: cMigration, signature: "setOperator(address)", args: [addresses.multichainStrategist],

clement-ux

Left some comments

sparrowDom

Minor comments otherwise LGTM

sparrowDom · 2026-07-07T08:49:13Z

+    ///      must equal the vault (enforced by the require below); Master always forwards the
+    ///      received bridgeAsset to `vaultAddress` on the leg-2 ack.
+    ///
+    ///      Only the `remoteStrategyBalance` slice is drawable here: `_amount` must be


Proposed change of this section:

/// Drawable bound is `_drawableRemoteBalance()` = `remoteStrategyBalance + /// min(0, bridgeAdjustment)`, NOT `remoteStrategyBalance` alone: /// - a NEGATIVE `bridgeAdjustment` (net BRIDGE_OUT) is folded in, lowering the cap so we /// never request more shares than Remote can actually unwrap (else it NACKs on Remote); /// - a POSITIVE `bridgeAdjustment` is excluded here even though `checkBalance` counts it /// (that + local bridgeAsset can report more). To realise it, `requestSettlement()` /// first (folds bridgeAdjustment into remoteStrategyBalance) and/or use the local /// bridgeAsset, then withdraw.

sparrowDom · 2026-07-07T08:54:30Z

+    ///      on a WITHDRAW_CLAIM_ACK (the bridgeAsset is still held when this is computed).
+    ///      `oTokenAmount` is in OToken (18dp) units, matching `_viewCheckBalance`;
+    ///      `_yieldOnlyBaseline()` is the `oTokenAmount == 0` case.
+    /// @dev Clamps to 0 rather than reverting on a negative. `_viewCheckBalance - bridgeAdjustment`


suggested fix:

/// @dev Clamps to 0 rather than reverting on a negative. `_viewCheckBalance - bridgeAdjustment` /// is principal + yield + retained fees and is never *economically* negative **while /// (w)OTokens are up-only** — the only thing that pushes it a few wei negative is the /// wOToken 4626 rounding against the strategy (~1 wei per BRIDGE_IN floor / BRIDGE_OUT /// ceil) once a `withdrawAll` drains it near 0. Reverting on that dust would freeze the /// serialized yield channel, so we clamp (matches checkBalance-never-reverts). /// CAVEAT: a real negative rebase (loss/slashing) would make this genuinely negative; the /// clamp then masks it, and because Master re-adds its OWN `bridgeAdjustment`, /// `checkBalance` OVER-reports by ~`bridgeAdjustment` (not 0). Out of scope while /// (w)OTokens never negative-rebase; revisit (signed baseline) if that changes. See DESIGN §3.10.

sparrowDom · 2026-07-07T09:01:39Z

+leg-2 claim ack lands.
+
+For `withdrawAll` (vault or governor sweep), `_withdrawRequest` is called with
+`min(remoteStrategyBalance, inboundAdapter.maxTransferAmount())` so a sweep


this should be

`min(_drawableRemoteBalance(), inboundAdapter.maxTransferAmount())` so a sweep

sparrowDom · 2026-07-07T09:04:23Z

+        Master->>Master: _processWithdrawClaimAck success:<br/>_markYieldNonceProcessed(N+2)<br/>pendingWithdrawalAmount = 0<br/>remoteStrategyBalance = yieldBaseline
+        Master->>Vault: «WETH» transfer (forwards its full bridgeAsset balance)
+        Note over Master: safeTransfer(vaultAddress, balanceOf(this))<br/>emit Withdrawal(WETH, WETH, claimed)
+    else queue not yet matured (NACK)


proposed change:

Leg-2 NACKs on four conditions, not just an immature queue: else NACK — outstandingRequestId != EMPTY / amount == 0 / bridgeAssetHeld < amount / ship out of [min,max]

sparrowDom · 2026-07-07T09:07:15Z

+        ) {
+            return;
+        }
+        // Best-effort: a mid-migration cleared inbound adapter must no-op the sweep, not


Proposed change:

// Best-effort no-op if the inbound adapter isn't wired yet (pre-configuration only — // setInboundAdapter now rejects zero, so it can't be cleared mid-migration).

shahthepro added 8 commits June 1, 2026 15:35

Add OUSD V3 contracts

a6fadbc

Fixes

35657e5

Simplify code

d8e9240

Remove root pnpm files

610e7ed

Refactor superbridge

1f4fa8e

checkpoint

bde0f2b

Add testnet files and bug fixes

700853b

Fix tests

b7cb68a

shahthepro changed the title ~~[WIP] Add OUSD V3 contracts~~ Add OUSD V3 and OETHb migration contracts Jun 8, 2026

Add flows file

d778f8f

shahthepro marked this pull request as ready for review June 8, 2026 10:06

shahthepro requested review from clement-ux, naddison36 and sparrowDom as code owners June 8, 2026 10:06

shahthepro added 2 commits June 8, 2026 14:18

Fix pnpm lock file

0e901b1

Fix slither

10ecbde

shahthepro added 13 commits June 8, 2026 15:03

Fix Base fork test

2993eaa

Commit readme files

3cf586e

Merge branch 'master' into shah/ousd-v3

ca967cb

bug fixes

fb920df

Fix hh config

443290e

Fix hh config

2df0162

Move testnet harness to shah/ousd-v3-testnet

c061d37

Fix unit test

ef27955

Fix AbstractAdapter

0cb3982

Update comment

2ffc8ef

Code simplification

550a014

bug fixes

2c2da82

Few more code cleanup

f984421

naddison36 added 17 commits June 30, 2026 13:33

More sequence diagram rendering fixes and improvements

949a938

More Deposit sequence diagram changes

9363463

More sequence diagram changes

59a7491

More deposit sequence diagram changes

c2e0b2a

More sequence diagram changes

52f9990

More deposit sequence changes

174f4ac

Added store prefix when writing to a storage variable

41836ae

Moved the adapter participants close to the Bridge

Clearer message structures

84a6396

More sequence changes

dac68cd

More sequence diagram changes

23dda86

More flow changes

d9fabdd

More deposit flow changes

0ab9c3f

Withdraw flow updates

6740b6f

More withdraw flow sequence diagram changes

65c881a

Check balance diagram changes

bbaee69

Bridge out and in sequence diagrams

e1dfa8d

Settlement flow diagram changes

4e57495

naddison36 reviewed Jul 1, 2026

View reviewed changes

Update check balance flow diagram

6039ea7

naddison36 reviewed Jul 2, 2026

View reviewed changes

shahthepro added 3 commits July 2, 2026 14:23

Merge branch 'master' into shah/ousd-v3

f20d464

Address CR comments

82f0179

Rename var

d8331cf

clement-ux reviewed Jul 6, 2026

View reviewed changes

Comment thread contracts/contracts/strategies/crosschainV3/adapters/CCTPAdapter.sol Outdated

Comment thread contracts/contracts/strategies/crosschainV3/adapters/SuperbridgeAdapter.sol

Bug fixes

97f6f1a

sparrowDom previously approved these changes Jul 7, 2026

View reviewed changes

clement-ux reviewed Jul 7, 2026

View reviewed changes

Comment thread contracts/contracts/strategies/crosschainV3/adapters/SuperbridgeAdapter.sol

Update docs and comments

4a60403

shahthepro dismissed sparrowDom’s stale review via 4a60403 July 7, 2026 10:31

Add missing check

dd40635

Uh oh!

Conversation

shahthepro commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Uh oh!

codecov Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

naddison36 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clement-ux left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sparrowDom left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

shahthepro commented Jun 1, 2026 •

edited

Loading

codecov Bot commented Jun 8, 2026 •

edited

Loading