Beefy client wrapper contract by claravanstaden · Pull Request #1668 · Snowfork/snowbridge

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

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

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.83%. Comparing base (8b31be0) to head (f086bcf).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1668      +/-   ##
==========================================
+ Coverage   81.20%   82.83%   +1.63%     
==========================================
  Files          22       23       +1     
  Lines        1016     1113      +97     
  Branches      196      213      +17     
==========================================
+ Hits          825      922      +97     
  Misses        174      174              
  Partials       17       17

Flag	Coverage Δ
solidity	`82.83% <100.00%> (+1.63%)`	⬆️

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.

yrong · 2026-01-11T16:47:39Z

encourage all the relayers to pipeline consensus updates as opposed to use manually configuring and whitelisting relayers

Agreed. If the goal is simply to have multiple BEEFY relayers cooperate to update the light client, then on-chain or off-chain round-robin (RR) coordination may not be necessary.

As we’ve observed with the Flashbots RPC, multiple relayers can submit updates concurrently, and only one will succeed—the others will fail without incurring any fees.

This effectively provides a form of round-robin behavior at the RPC level.

# Conflicts: # relayer/contracts/beefy_client.go # web/packages/test/scripts/start-relayer.sh

yrong · 2026-02-05T02:57:30Z

contracts/src/BeefyClientWrapper.sol

+    function createFinalBitfield(bytes32 commitmentHash, uint256[] calldata bitfield)
+        external
+        view
+        returns (uint256[] memory)
+    {
+        return beefyClient.createFinalBitfield(commitmentHash, bitfield);
+    }
+
+    function latestBeefyBlock() external view returns (uint64) {
+        return beefyClient.latestBeefyBlock();
+    }
+
+    function createInitialBitfield(uint256[] calldata bitsToSet, uint256 length)
+        external
+        view
+        returns (uint256[] memory)
+    {
+        return beefyClient.createInitialBitfield(bitsToSet, length);
+    }


It seems these view functions are simply forwarding, and I'm not sure they're necessary, as the relayer can directly retrieve states from the BeefyClient.

Good point, added in e919c32.

yrong · 2026-02-05T03:00:06Z

contracts/src/BeefyClientWrapper.sol

+    }
+
+    function _creditGas(uint256 startGas, bytes32 commitmentHash) internal {
+        uint256 gasUsed = startGas - gasleft() + 21000;


Is 21,000 necessary here? I assume it's only for refunding the last transfer call?

The 21000 accounts for the base transaction gas cost (intrinsic gas) that's deducted by the EVM before contract execution begins, so it's not captured by gasleft(). It's added for each transaction (submitInitial, commitPrevRandao, submitFinal) to ensure the relayer is refunded for the full transaction cost, not just the contract execution portion. Let me know what you think of this.

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

changes

c7da3c1

claravanstaden closed this Jan 22, 2026

claravanstaden added 3 commits February 4, 2026 14:41

Merge branch 'main' into clara/beefy-wrapper-contract

70b59ff

# Conflicts: # relayer/contracts/beefy_client.go # web/packages/test/scripts/start-relayer.sh

simplify

1d3e81d

cleanup

7c94d09

claravanstaden reopened this Feb 4, 2026

github-actions bot added the Component: Web label Feb 4, 2026

claravanstaden added 4 commits February 4, 2026 16:19

remove proxy

9b8fd88

add fiat shamir back

d1f0576

revert fiat shamir

6228a56

relayer tweaks

f9b4923

yrong reviewed Feb 5, 2026

View reviewed changes

claravanstaden added 4 commits February 5, 2026 11:28

use beefy client directly

e919c32

more tests

70ac4b0

more tests and update outdated comment

e3112a2

add removed fiat shamir back

f086bcf

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!

yrong commented Jan 11, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 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