feat: add CreditMessagingRecovery for emergency credit recovery by clauBv23 · Pull Request #532 · stargate-protocol/stargate-v2

clauBv23 · 2026-04-01T12:33:19Z

Problem

Credits in Stargate V2 act as a capacity gate — they must be held on a chain before tokens can be redeemed or sent cross-chain. When a chain is deprecated without properly returning its credits to origin chains, those credits become permanently lost. This leaves pools with real token balances but depleted path credits, blocking all user exit paths.

Example: Sei USDT pool holds $27.7k but only $4.2k in usable credits — $23.5k is effectively locked with no way out.

Credits are not a security primitive (they do not custody funds — every actual fund movement requires independent authorization via LP tokens or a valid cross-chain token message). They are a liveness primitive.

Solution

CreditMessagingRecovery extends CreditMessaging with two owner-only admin functions. Both operate locally only — no LayerZero message is ever sent, no cross-chain coordination is required, and no LZ fees are incurred.

mintCredits(CreditBatch[], reason) — increases credits on the current chain by calling ICreditMessagingHandler.receiveCredits(0, credits) directly, bypassing the normal credit validation. Used to restore lost credits on affected chains.

burnCredits(TargetCreditBatch[], reason) — decreases credits on the current chain by calling ICreditMessagingHandler.sendCredits(0, targets) locally, stopping before _lzSend. Uses minAmount = amount (all-or-nothing), reverting if the path has insufficient credits. Used to correct over-minted credits.

Both functions require a non-empty plain-text reason string that is emitted on-chain as a permanent audit trail, as per the team discussion.

Safety

Credits cannot move funds on their own. Over-injecting local credits beyond pool balance causes failed transactions — the pool physically cannot send what it does not hold. Over-burning locks funds in the pool (same situation as the bug being fixed).
mintCredits and burnCredits are onlyOwner (multisig), not planner-accessible.
sendCredits remains planner-accessible and unchanged.
Treasury fees and recoverToken are unaffected — they operate on poolBalanceSD and treasuryFee, which credits never touch.
No LZ message means no DVN dependency, no peer configuration needed, and no cross-chain reorg risk.

Changes

New contract — src/messaging/CreditMessagingRecovery.sol
Extends CreditMessaging with mintCredits and burnCredits.
New interface — src/interfaces/ICreditMessagingRecovery.sol
Exposes the admin functions, the CreditMessagingRecovery_EmptyReason error, and the CreditsMinted / CreditsBurned events.
Deploy script — deploy/003-deploy-message.ts
Non-alt chains now deploy CreditMessagingRecovery under the existing CreditMessaging deployment name. Alt chains continue deploying CreditMessagingAlt unchanged.
Unit tests — test/unitest/messaging/Messaging.CreditRecovery.t.sol
Extends CreditMessagingTest to prove backward compatibility — all parent tests run against CreditMessagingRecovery. Recovery-specific coverage includes: access control, empty reason revert, unavailable asset revert, local-only operation (no PacketSent event), multiple batches with multiple credits per batch, partial burns (handler returns less than requested), and empty credits arrays.
Existing credit messaging tests — test/unitest/messaging/Messaging.Credit.t.sol
Added tests asserting that mintCredits and burnCredits produce an empty revert (function does not exist) on the base CreditMessaging contract.

TBD

Should we create a similar contract for alt chains? For now CreditMessagingAlt is unchanged — the mesh can be balanced using a single CreditMessagingRecovery deployment.
There are invariant tests that check that total credits equal pool balance.
Mint/burn intentionally breaks this invariant — but so did the original bug: disconnecting a chain without returning credits already left the mesh in a state where total credits no longer matched pool balances. We decided against adjusting the invariant tests since these are emergency-only functions and the fuzzer is better spent on the normal credit flow. Gathering team thoughts on this.

changeset-bot · 2026-04-01T12:33:24Z

⚠️ No Changeset found

Latest commit: 4543ff1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Copilot

Pull request overview

Adds an emergency-only credit recovery mechanism to Stargate V2 EVM messaging by introducing an owner-controlled MintBurnCreditMessaging contract that can mint credits cross-chain without local deduction and burn local credits without sending an LZ message, plus deployment + unit test updates.

Changes:

Introduces MintBurnCreditMessaging with mintCredits, burnCredits, and quoteMintCredits.
Adds IMintBurnCreditMessaging interface for the new admin API surface.
Updates deployment to use MintBurnCreditMessaging (non-ALT) while keeping the deployment name CreditMessaging, and adds/updates unit tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/stg-evm-v2/test/unitest/messaging/Messaging.MintBurnCredit.t.sol	New unit tests for mint/burn credit emergency flows and access control.
packages/stg-evm-v2/test/unitest/messaging/Messaging.Credit.t.sol	Adds assertions that base `CreditMessaging` does not expose mint/burn functions (but encoding needs fixing).
packages/stg-evm-v2/src/messaging/MintBurnCreditMessaging.sol	New contract extending `CreditMessaging` with owner-only mint/burn credit operations and fee quoting.
packages/stg-evm-v2/src/interfaces/IMintBurnCreditMessaging.sol	New interface for emergency credit management API (parameter locations/events need alignment with intent).
packages/stg-evm-v2/deploy/003-deploy-message.ts	Deploys `MintBurnCreditMessaging` under the `CreditMessaging` deployment name for non-ALT networks.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…redit.t.sol Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-01T13:24:26Z

+    /// @dev Credits are sent to the destination chain without being deducted on the current chain.
+    function mintCredits(
+        uint32 _dstEid,
+        CreditBatch[] calldata _batches,
+        string calldata _reason
+    ) external payable onlyOwner {
+        if (bytes(_reason).length == 0) revert MintBurnCreditMessaging_EmptyReason();
+        (bytes memory message, bytes memory options) = _buildMessagePayload(_dstEid, _batches);
+        _lzSend(_dstEid, message, options, MessagingFee(msg.value, 0), msg.sender);
+        emit CreditsMinted(_dstEid, _batches, _reason);
+    }


mintCredits / quoteMintCredits can be called with _batches that contain zero total credits (empty array or batches with empty credits). In that case totalCreditNum becomes 0 and _buildOptions(_dstEid, 0) produces an options payload with a 0 gas value, then mintCredits still calls _lzSend with a no-op message. Consider adding a guard to revert (or no-op without sending) when totalCreditNum == 0, mirroring CreditMessaging.sendCredits which skips _lzSend when there are no credits to send.

intentionally omitted. mintCredits and burnCredits are emergency owner-only operations that require careful review by signers and engineers before execution, including a mandatory non-empty reason. The inputs are expected to be validated off-chain before the multisig signs. This check for dummies seems not needed imo

ravinagill15

Nice 🚀 let's add a changeset as well

tinom9 · 2026-04-05T05:46:27Z

+        if (bytes(_reason).length == 0) revert MintBurnCreditMessaging_EmptyReason();
+        (bytes memory message, bytes memory options) = _buildMessagePayload(_dstEid, _batches);
+        _lzSend(_dstEid, message, options, MessagingFee(msg.value, 0), msg.sender);
+        emit CreditsMinted(_dstEid, _batches, _reason);


Unrelated to the code, but have we thought about how the planner/indexer will handle the new event topology?

you mean when new credits were created?

I'm not sure we have an indexer here. I think the planner just queries all the information on-chain and gets the real credits in the mesh. Will double check

I don't know how the new events will affect any backend system that we already have, since CreditsSent and CreditsReceived are emitted.

Just confirmed the indexer does not index credits moving

tinom9 · 2026-04-05T05:51:26Z

+import { IMintBurnCreditMessaging } from "../interfaces/IMintBurnCreditMessaging.sol";
+import { ICreditMessagingHandler, Credit } from "../interfaces/ICreditMessagingHandler.sol";
+
+contract MintBurnCreditMessaging is CreditMessaging, IMintBurnCreditMessaging {


I'd consider renaming to CreditMessagingRecoverable, CreditMessagingAdjustable, or CreditMessagingMintableBurnable to keep the consistency with Stargate contract names:

Suffixes over prefixes. This feels like something we should respect.

Use-cases over actions (StargatePoolMigratable instead of StargatePoolBurnable). This is more subjective and I don't have a strong opinion.

We could also consider renaming mintCredits and burnCredits to mintCreditsForRecovery and burnCreditsForRecovery. No strong opinion here either, just sharing my thoughts.

I agree, however, I renamed to CreditMessagingMintableBurnable, I agree with "Use-cases over actions" but I don't like CreditMessagingRecoverable or CreditMessagingAdjustable and I cannot find a better name that describes the use case 🤔

Renamed to CreditMessagingRecovery it's a credit messaging contract that performs recovery.
658e380

Kept the function names as mintCredits and burnCredits for now, I don't like adding the for recovery, it seems too verbose.

I have been thinking about restoreCredits / trimCredits, first one implies bringing something back to what it should be, and second implies removing excess, both suggest the recovery intent. But not sure if it would make it harder to understand if the credits are increasing or decreasing. wdyt @tinom9 ?

restoreCredits and trimCredits seem less verbose, what do they really mean? I prefer mint-burn.

Let's update the PR title?

updated PR title and description. Keeping mint burn for now

…g crosschain msg

tinom9 · 2026-04-06T19:45:40Z

+    function _mockStargateReceiveCredits(Credit[] memory _credits) internal {
+        _mockStargateReceiveCredits(STARGATE_IMPL, _credits);
+    }
+
+    function _mockStargateReceiveCredits(address _stargate, Credit[] memory _credits) internal {
+        vm.mockCall(_stargate, abi.encodeCall(ICreditMessagingHandler.receiveCredits, (0, _credits)), "");
+    }


I don't love that we're mocking this.

It's a fundamentally important integration of this contract.

That said, this is consistent with the codebase, so I think it's okay to keep this file as is.

Can we have some integration tests though?

agree we should add integratio test for this

added f6cd53a

tinom9 · 2026-04-06T20:10:50Z

+    error CreditMessagingRecovery_EmptyReason();
+
+    /// @notice Emitted when credits are minted locally without a corresponding debit on a source chain.
+    event CreditsMinted(uint16 assetId, Credit[] credits, string reason);


Let's index assetId?

Suggested change

event CreditsMinted(uint16 assetId, Credit[] credits, string reason);

event CreditsMinted(uint16 indexed assetId, Credit[] credits, string reason);

Same for CreditsBurned.

asset id is removed now, it would be on each CreditBatch item

tinom9 · 2026-04-06T22:22:49Z

+    StargateBaseTestC internal pool;
+
+    function setUp() public {
+        pool = new StargateBaseTestC();


What about testing behaviour with both StargatePool and StargateOFT, instead of StargateBase mocks?

added 6b56b75

tinom9

Contracts look good to me!

TRileySchwarz · 2026-04-08T01:23:58Z

+import { ICreditMessagingRecovery } from "../interfaces/ICreditMessagingRecovery.sol";
+import { ICreditMessagingHandler, Credit } from "../interfaces/ICreditMessagingHandler.sol";
+
+contract CreditMessagingRecovery is CreditMessaging, ICreditMessagingRecovery {


Only comment I would make is I dont like the name CreditMessagingRecovery, really should be something like CreditMessagingV2 imo.

Further to that, I think to simplify the system and risk of deploying on new chains, that perhaps we deploy this on arbitrum only, and not new chains moving forward. We dont need to know that before sending to audit, and also regarding the contract name, not a huge deal to change mid audit as well. The rest of impl makes sense.

Another thing to note is that currently if the planner has the contract paused, then we cant mint or burn credits. So this creates a bit of an issue if it MUST remain paused during the mint.burn recovery or migration / chain deprecation. However I think this is fine becaause worst case the owner can 1: transfer 'planner' to the owner, 2: unpause 3: mint/burncredits, 4: pause, 5: transfer planner back to the planner. This creates an atomic situation albeit, quite complicated.

My intuition is that we only want to deploy once.

if so, I don't love CreditMessagingV2 naming, since it implies the next version (V2) of the same thing (credit messaging). I'd stick to use-case.

StargatePool -> StargatePoolMigratable.

CreditMessaging -> CreditMessagingRecovery / CreditMessagingRecoverable.

I also think this should be deployed on a single chain. @tironiigor’s plan was to deploy the new version from now on, but I agree we could deploy it on one of the main chains and continue using the current one elsewhere.

Regarding the name, I don’t have a strong opinion. I’m not a big fan of CreditMessagingRecovery either, but I don’t have a better suggestion. That said, I agree with @tino that if we go with a single-chain deployment, calling it CreditMessagingV2 could be misleading since we’d deploy V1 to new chains.

On the planner pausing point,good observation. The owner can ultimately take over the role and mint/burn if needed. It’s not ideal, but it’s possible, and everything can be done atomically. So I’d keep it in mind, but I don’t see it as an issue

Yeah, fair if only 1 deployment shouldnt be v2, but we can brainstorm a better name. Igor agrees on doing it only one chain, as long as the migration (vs. just a new version on expansion) isnt too chaotic. Looking into that now

clauBv23 added 3 commits April 1, 2026 13:57

feat: add interface and contract implementation

9ae8997

feat: add unit tests

fbe17c7

feat: start deploying MintBurnCreditMessaging instead of CreditMessaging

250baf2

ci: move the events to the interface and add natspec

f664aed

clauBv23 requested a review from Copilot April 1, 2026 12:55

Copilot started reviewing on behalf of clauBv23 April 1, 2026 12:56 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

clauBv23 and others added 5 commits April 1, 2026 15:08

fix: use event from the interface not the contract

c486302

fix: use correct type to encode data in the test

e4f4b23

feat: prevent burning and minting without reason

1ccb363

ci: set input as calldata instead of memory in the interface

ab7ab80

Update packages/stg-evm-v2/test/unitest/messaging/Messaging.MintBurnC…

c1ecc18

…redit.t.sol Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

clauBv23 requested a review from Copilot April 1, 2026 13:17

Copilot started reviewing on behalf of clauBv23 April 1, 2026 13:18 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

clauBv23 added 2 commits April 1, 2026 15:35

fix test

57b0eaf

fix: test

3a9bc0a

ravinagill15 reviewed Apr 2, 2026

View reviewed changes

tinom9 reviewed Apr 5, 2026

View reviewed changes

clauBv23 added 10 commits April 6, 2026 13:13

ci: move error to the interface

358fc24

feat: do the credits mint and burn in the local chain, without sendin…

6431dbb

…g crosschain msg

fix: tests

9f72abc

ci: rename contract name and related code names reference

658e380

feat: ensure revert data has zero lenght ensure it is non existent error

5ec9813

feat: inherit credit messaging tests in CreditMessagingRecoveryTest

83d6a47

ci: use bound instead of assume

e829f10

ci: define string reasons as constants

d7f7901

feat: check no LZ message is sent on mint and burn functions

7c43a2a

ci: fix tests functions name inconsistency

09e3f45

feat: add tests

0456965

clauBv23 requested review from ravinagill15 and tinom9 April 6, 2026 16:31

tinom9 reviewed Apr 6, 2026

View reviewed changes

clauBv23 changed the title ~~feat: add MintBurnCreditMessaging for emergency credit recovery~~ feat: add CreditMessagingRecovery for emergency credit recovery Apr 6, 2026

clauBv23 added 7 commits April 6, 2026 22:44

ci: emit a singel mint/burn ever per call

b2ebaab

fix: tests

27da496

fix: comment

f123e95

ci: pass struct not params

5f13975

ci: add revert string

375a9be

ci: add mock call check

244cf55

feat: add integration tests

f6cd53a

clauBv23 requested a review from tinom9 April 6, 2026 22:04

tinom9 reviewed Apr 6, 2026

View reviewed changes

clauBv23 added 2 commits April 7, 2026 00:42

fix: set correct function params

788f8aa

feat: make invariat tests with pool and oft contracts integration

6b56b75

clauBv23 requested a review from tinom9 April 6, 2026 23:29

fix: tests

30ae7a7

ravinagill15 previously approved these changes Apr 7, 2026

View reviewed changes

tinom9 reviewed Apr 7, 2026

View reviewed changes

TRileySchwarz reviewed Apr 8, 2026

View reviewed changes

clauBv23 added 2 commits April 10, 2026 14:39

ci: add inheritdocs to natspec

7c50c9b

ci: add natspec for event params

4543ff1

clauBv23 dismissed ravinagill15’s stale review via 4543ff1 April 10, 2026 12:59

	event CreditsMinted(uint16 assetId, Credit[] credits, string reason);
	event CreditsMinted(uint16 indexed assetId, Credit[] credits, string reason);

Conversation

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

Uh oh!

Problem

Solution

Safety

Changes

TBD

Uh oh!

changeset-bot Bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ravinagill15 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

clauBv23 Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

clauBv23 Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

clauBv23 commented Apr 1, 2026 •

edited

Loading

changeset-bot Bot commented Apr 1, 2026 •

edited

Loading

clauBv23 Apr 6, 2026 •

edited

Loading

clauBv23 Apr 6, 2026 •

edited

Loading