Beefy client wrapper contract #1668

claravanstaden · 2026-01-07T12:40:03Z

codecov · 2026-01-07T12:41:36Z

Codecov Report

❌ Patch coverage is 86.59794% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.27%. Comparing base (1cf39a2) to head (39bf3fc).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
contracts/src/BeefyClientWrapper.sol	85.55%	26 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1668      +/-   ##
==========================================
- Coverage   91.02%   90.27%   -0.76%     
==========================================
  Files          19       21       +2     
  Lines         903     1100     +197     
  Branches      164      192      +28     
==========================================
+ Hits          822      993     +171     
- Misses         64       90      +26     
  Partials       17       17

Flag	Coverage Δ
solidity	`90.27% <86.59%> (-0.76%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 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.

yrong · 2026-01-08T06:03:09Z

contracts/src/BeefyClientWrapperProxy.sol

+        address implementation = ERC1967.load();
+        assembly {
+            let result := delegatecall(gas(), implementation, 0, 0, 0, 0)
+            returndatacopy(0, 0, returndatasize())
+            switch result
+            case 0 { revert(0, returndatasize()) }
+            default { return(0, returndatasize()) }
+        }
+    }


Seems unnecessary?

Addressed in 919f503

yrong · 2026-01-08T06:05:18Z

contracts/src/BeefyClientWrapper.sol

+        ticketOwner[commitmentHash] = msg.sender;
+        activeTicket[msg.sender] = commitmentHash;
+
+        _refundGas(startGas);


I’d suggest crediting the gas cost without refunding it immediately, and only issuing the refund after submitFinal.

Agreed, addressed in 5828412.

yrong · 2026-01-08T06:13:05Z

Cool. I assume that initially we would top up the wrapper contract ourselves, and that we would only refund the BEEFY relayer for the transaction cost of the consensus update.

We may also want to allow end users to tip for a message that is included in a relay-chain block but has not yet been finalized by BEEFY.

The tip storage could be a map from relayBlockNumber → tipFee. BEEFY relayers would monitor both this tip storage and the Beefy finality updates. Once a BEEFY commitment advances past the corresponding relayBlockNumber—making the message verifiable—they would compete to submit the consensus update and claim the tip.

I assume this would be the main incentive mechanism for the consensus relay: relayers receive additional rewards from end users only when there is a message to relay.

yrong · 2026-01-08T07:12:40Z

contracts/src/BeefyClientWrapper.sol

+    function _refundGas(uint256 startGas) internal {
+        uint256 gasUsed = startGas - gasleft() + 21000;
+        uint256 effectiveGasPrice = tx.gasprice < maxGasPrice ? tx.gasprice : maxGasPrice;
+        uint256 refundAmount = gasUsed * effectiveGasPrice;
+
+        if (address(this).balance >= refundAmount) {
+            (bool success,) = payable(msg.sender).call{value: refundAmount}("");
+            if (success) {
+                emit SubmissionRefunded(msg.sender, refundAmount, gasUsed);
+            }
+        }
+    }


This function could be exploitable. If msg.sender is a malicious contract with a receive() or fallback() function that consumes a large amount of gas, it could potentially drain the proxy contract.

I’d suggest adding a hard cap on the refundAmount to mitigate this risk.

Good catch! e43ab5f

claravanstaden · 2026-01-08T10:42:34Z

We may also want to allow end users to tip for a message that is included in a relay-chain block but has not yet been finalized by BEEFY.

@yrong good idea! Added in 39bf3fc, let me know what you think.

alistair-singh · 2026-01-08T11:21:47Z

I think this can be done way simpler. You just need a refund target, which is a number in blocks, say 300 blocks (30 minutes). You always refund, but scale it according to how much progress the relayer made. If a relayer chooses to relay every 30 blocks, they will only get 10% of gas returned as refund. If a relayer waits 300 blocks or more, it gets 100% of its gas as refund. There is no round robin, relayers must monitor open tickets and see if they will get a refund based on the pending tickets. If there is a race condition where two relayers compete, this scaled refund makes sure each one gets paid a portion based on progress made. Remember relayers can abandon tickets if there is a race condition where another relayer competes with them.

This same idea can be extended to rewards/tips. You could choose a reward target, which is a number in blocks, say 2400 (4 hours). You refund as per the above logic until 300 block refund target, for every block over, up untill 2400 you scale by amount of blocks progressed and pay a portion of the reward. So if a relayer makes 600 blocks progress, you give them a full refund for meeting the refund target (300/300), and then a 12.5% portion of the reward (300/2400).

claravanstaden · 2026-01-08T11:40:49Z

@alistair-singh this sounds cool, and is simpler. Relayers might frequently lose gas spent on submitInitial, if more than one relayer submits at the same time. What do you think about this? And do we remove the relayer whitelist then?

alistair-singh · 2026-01-08T11:25:38Z

contracts/src/BeefyClientWrapper.sol

+ * @dev Forwards BeefyClient submissions and refunds gas costs to whitelisted relayers.
+ * Implements soft round-robin scheduling to prevent competition.
+ */
+contract BeefyClientWrapper is IInitializable, IUpgradable {


Not sure why we need proxy pattern and upgradable here. We may need it, but we can get away with pointing the wrapper at the Gateway contract instead of the Beefy contract. It can read the current beefy client from the Gateway. This means when we upgrade the Beefy client on the gateway, the wrapper is automatically picks up the new Beefy Instance.

Since this is a wrapper we should also strive to rather throw it away and deploy a new wrapper if we ever have to upgrade it, avoiding forms of governance if possible. We would only really need to migrate any Eth held by the contract. So Proxy Pattern seems to heavy for this requirement.

I didn't have a proxy pattern at first, but because this contract holds state I figured it would be better, esp if we want to change some of the config. I don't have a strong opinion about this either way.

alistair-singh · 2026-01-08T11:26:07Z

contracts/src/BeefyClientWrapper.sol

+    error AlreadyInitialized();
+    error TicketAlreadyActive();
+
+    address public owner;


Who is the owner? Does our team own this key?

Yeah, could be our SAFE multisig.

alistair-singh · 2026-01-08T12:05:06Z

@alistair-singh this sounds cool, and is simpler. Relayers might frequently lose gas spent on submitInitial, if more than one relayer submits at the same time. What do you think about this? And do we remove the relayer whitelist then?

I think it might happen occasionally, but we need some system where we can tune the parameters to encourage all the relayers to pipeline consensus updates as opposed to use manually configuring and whitelisting relayers. I dont think it needs to be a perfect system either, we must trust relayers to act in their best interest. At worst, they will abandon the ticket and post another.

This edge case is something that can be addressed in the wrapper as well, by reverting early if some condition is not met. For example you can do something like compare and swap operation. e.g. The current latest ticket open is for block X, I want to relay block X+300, assuring my 100% refund, when I submit initial to claim a ticket via the wrapper i submit both X and X+300, and the submit initial in the wrapper can revert if X has changed onchain. So it still costs, but less than submit initial. The only time X will change onchain is if two relayers submit and it gets included in the same block. We can introduce random in the relayer to offset this in practise, so generate a random number N between 1-20, and the relay block X+300+N. So relayers never try to relay at the exact interval for example.

We could even do something like we do for message relayers and co-ordinate round robin offchain.

beefy client wrapper

6657bb2

github-actions bot added the Component: Ethereum label Jan 7, 2026

relayer changes

6bd9ca8

github-actions bot added the Component: Relayer label Jan 7, 2026

yrong reviewed Jan 8, 2026

View reviewed changes

remove receive impl

919f503

yrong reviewed Jan 8, 2026

View reviewed changes

claravanstaden added 3 commits January 8, 2026 09:14

refund gas at end of interactive protocol

5828412

set max refund amount

e43ab5f

add block tips

39bf3fc

alistair-singh reviewed Jan 8, 2026

View reviewed changes

Beefy client wrapper contract #1668

Are you sure you want to change the base?

Beefy client wrapper contract #1668

Uh oh!

Conversation

claravanstaden commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

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!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

claravanstaden commented Jan 8, 2026

Uh oh!

alistair-singh commented Jan 8, 2026

Uh oh!

claravanstaden commented Jan 8, 2026

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!

alistair-singh commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

claravanstaden commented Jan 7, 2026 •

edited

Loading

codecov bot commented Jan 7, 2026 •

edited

Loading

yrong commented Jan 8, 2026 •

edited

Loading

alistair-singh commented Jan 8, 2026 •

edited

Loading