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 82.97632% with 151 lines in your changes missing coverage. Please review.
✅ Project coverage is 50.49%. Comparing base (c52692d) to head (d8331cf).

Files with missing lines	Patch %	Lines
...racts/strategies/BridgedWOETHMigrationStrategy.sol	0.00%	45 Missing ⚠️
...egies/crosschainV3/adapters/SuperbridgeAdapter.sol	55.22%	30 Missing ⚠️
...rategies/crosschainV3/adapters/AbstractAdapter.sol	83.00%	17 Missing ⚠️
...s/strategies/crosschainV3/adapters/CCIPAdapter.sol	54.54%	15 Missing ⚠️
...s/strategies/crosschainV3/adapters/CCTPAdapter.sol	88.17%	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.49%   +5.85%     
==========================================
  Files         110      123      +13     
  Lines        4920     5807     +887     
  Branches     1362     1637     +275     
==========================================
+ Hits         2196     2932     +736     
- Misses       2721     2872     +151     
  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.

sparrowDom

Thanks for providing the fixes for previous comments. Some more comments inline:

sparrowDom · 2026-06-24T15:40:31Z

+        uint32 msgType,
+        uint256 amount,
+        bytes memory body
+    ) internal nonReentrant {


🟡 we don't have a test for Reentrency. This would be pretty convenient to have.

sparrowDom · 2026-06-24T15:51:50Z

+    //                        the fee; the pool is NOT consulted. Security gate: stops an
+    //                        attacker draining the operator-funded pool by spamming bridge
+    //                        in/out with msg.value = 0.
+    //   userFunded = false → operator/protocol-funded sends (yield deposits/withdraws/claims


⚪ Would be cool to add a monitoring section to this PR where we should probably add a capability to Talos to observe the balances of fee assets on contracts. The remote contract sometimes needs to pay the bridging fee to convey the message. It can be blocked if it fails

sparrowDom · 2026-06-26T09:31:04Z

+    ///         vault, which would be indistinguishable from "no request" if stored verbatim;
+    ///         the +1 offset keeps `0` meaning "no outstanding (unclaimed) queue request" while
+    ///         a real id of 0 is safely represented as 1. Cleared to 0 once the claim lands.
+    uint256 public outstandingRequestId;


nit: another way to approach this would be to set a const REQUEST_ID_EMPTY = type(uint256).max;
And set it to that whenever you want to treat it as empty

That's a great suggestion, will do it.

sparrowDom · 2026-06-26T09:34:43Z

+    ///      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


nit: update this docs to reflect the changes where not only remoteStrategyBalance is taken into account

sparrowDom · 2026-06-26T13:41:57Z

+    Remote->>wOETH: deposit(OETH balance, Remote)
+    Remote->>wOETH: «OETH X» (wrapper pulls OETH on deposit)
+    wOETH-->>Remote: «wOETH shares» minted
+    Remote->>Remote: yieldBaseline = _viewCheckBalance()


_viewCheckBalance() − bridgeAdjustment

sparrowDom · 2026-06-26T13:42:05Z

+    Remote->>wOUSD: deposit(OUSD balance, Remote)
+    Remote->>wOUSD: «OUSD» (wrapper pulls on deposit)
+    wOUSD-->>Remote: «wOUSD shares» minted
+    Remote->>Remote: yieldBaseline = _viewCheckBalance()


_viewCheckBalance() − bridgeAdjustment

sparrowDom · 2026-06-26T13:42:15Z

+    Note over Remote: outstandingRequestId = requestId<br/>outstandingRequestAmount = amount
+
+    Note over Master,Remote: ─── Phase B: Remote sends WITHDRAW_REQUEST_ACK ───
+    Remote->>Remote: yieldBaseline = _viewCheckBalance()


_viewCheckBalance() − bridgeAdjustment

sparrowDom · 2026-06-26T13:43:32Z

+intermediate state; value lives in exactly one slot per row, and `checkBalance`
+equals the total in every row.
+
+| State | wOETH share value | OToken bal | bridgeAsset bal | queued\* | outstandingRequestId | checkBalance |


There are 2 new states: mint-failed; unwrap-ok/queue-fail);

sparrowDom · 2026-06-26T13:44:40Z

+        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)


Can revert for multiple reasons:

outstandingRequestId != 0

amount == 0

bridgeAssetHeld < amount

shipOutOfBounds

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],

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

shahthepro added 2 commits June 24, 2026 23:01

Clamp to zero instead of revert

4b7a891

Fix comment

16daba5

sparrowDom reviewed Jun 26, 2026

View reviewed changes

shahthepro and others added 21 commits June 26, 2026 20:39

Fix docs

a31ea89

Fix comments

9bb56a5

Added OUSD v3 contract diagrams

98e9020

Updated flow diagrams

bd74d1b

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

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!

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!

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!

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!

shahthepro commented Jun 1, 2026 •

edited

Loading

codecov Bot commented Jun 8, 2026 •

edited

Loading