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

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

Adds an BeefyClientWrapper.sol contract to refund gas for all beefy consensus transactions (SubmitInitial, CommitRandao, SubmitFinal) once a successful SubmitFinal has been submitted.
The wrapper contract is optional, i.e. it does not need to be deployed. If it is not configured, the BeefyClient will be used as normal.
Relayers check highestPendingBlock in the wrapper contract if a submission would result in a gas refund. If the highestPendingBlock is stale for 40 minutes, submit a new session.

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

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.84%. Comparing base (7ec4f8d) to head (52f92e9).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1668      +/-   ##
==========================================
+ Coverage   81.58%   82.84%   +1.25%     
==========================================
  Files          22       23       +1     
  Lines         994     1067      +73     
  Branches      184      197      +13     
==========================================
+ Hits          811      884      +73     
  Misses        166      166              
  Partials       17       17

Flag	Coverage Δ
solidity	`82.84% <100.00%> (+1.25%)`	⬆️

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.

contracts/src/BeefyClientWrapperProxy.sol

contracts/src/BeefyClientWrapper.sol

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.

contracts/src/BeefyClientWrapper.sol

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.

Removed proxy.

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.

We should make this permissionless and stateless. See https://www.notion.so/Relayer-Decentralization-Strategy-2e8296aaabef8031af9ff87151bd3d5c?d=2e9296aaabef8079a230001cb2543324&source=copy_link#2e9296aaabef80bd9b23d3fe2b62d7d6

The tradeoff is that deposited funds in the contract can be never be withdrawn. Is this OK? Say we deposit funds and then discover a bug, we can move the funds to a new contract. Seems less than ideal to me. It does need some state, for example, to capture the gas spent in a session.

I’d expect the funds deposited in this contract to be very limited. Given the low gas prices these days, even a small initial deposit can last a long time, so we wouldn’t need to recharge it frequently.

Even if the contract were somehow exploited, we could simply abandon it and deploy a new, fixed version. The state impact would be limited to the ongoing session, which is also acceptable.

Ideally, we’d like to remove all permission-related calls if possible.

Made contract permissionless: e89647e

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

claravanstaden · 2026-02-06T07:48:20Z

contracts/src/BeefyClientWrapper.sol

+    event FundsDeposited(address indexed depositor, uint256 amount);
+    event FundsWithdrawn(address indexed recipient, uint256 amount);


Perhaps these are not necessary.

Agree, I don't think these events are nessessary.

yrong · 2026-02-06T09:34:33Z

contracts/src/BeefyClientWrapper.sol

+    function submitFiatShamir(
+        IBeefyClient.Commitment calldata commitment,
+        uint256[] calldata bitfield,
+        IBeefyClient.ValidatorProof[] calldata proofs,
+        IBeefyClient.MMRLeaf calldata leaf,
+        bytes32[] calldata leafProof,
+        uint256 leafProofOrder
+    ) external {
+        beefyClient.submitFiatShamir(commitment, bitfield, proofs, leaf, leafProof, leafProofOrder);
+
+        // Clear highest pending block if light client has caught up
+        if (beefyClient.latestBeefyBlock() >= highestPendingBlock) {
+            highestPendingBlock = 0;
+            highestPendingBlockTimestamp = 0;
+        }
+    }


Why we aren't refunding for Fiat-Shamir?

I thought the user covers the cost of the transaction in a separate flow?

We might consider switching to Fiat–Shamir as the default update mechanism in future. If that’s the case, we would need to add refund support for it.

Good point, ae6dc9e

Refunding Fiat Shamir while an interactive protocol session is on-going will cause the interactive protocol relayer to forfeit their gas refund. Is that alright? Otherwise we should refund both the Fiat Shamir and the interactive protocol relayer for submissions up to that point, and then clear they ticket?

Adding in here: 8b8ec69

A relayer could game this by submitting a SubmitInitial and then a FiatShamir though, and get refunded for both.

I’d prefer to keep things simple and not include 8b8ec69. In my opinion, refunding an unfinished interactive update seems unnecessary.

Tend to agree, reverted in 27b975b.

alistair-singh · 2026-02-06T10:03:55Z

contracts/src/BeefyClientWrapper.sol

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


We should make this permissionless and stateless. See https://www.notion.so/Relayer-Decentralization-Strategy-2e8296aaabef8031af9ff87151bd3d5c?d=2e9296aaabef8079a230001cb2543324&source=copy_link#2e9296aaabef80bd9b23d3fe2b62d7d6

alistair-singh · 2026-02-06T10:08:17Z

contracts/src/BeefyClientWrapper.sol

+        uint256 totalGasUsed = currentGas + previousGas;
+        uint256 effectiveGasPrice = tx.gasprice < maxGasPrice ? tx.gasprice : maxGasPrice;


Calculation is incorrect. I assumes that the gasprice for the submitInitial is the same as the gas price for the submitFinal. You need to snapshot the previousGas and gasPrice at time of submitInitial

Good catch too! Fixed here: 7605eac

alistair-singh · 2026-02-06T10:12:20Z

contracts/src/BeefyClientWrapper.sol

+    uint256 public highestPendingBlockTimestamp;
+
+    constructor(
+        address _beefyClient,


What happens when the beefyClient/gateway is updated? We should rather get the beefyClient address from the Gateway by initializing the Wrapper with the GatewayProxy address, that way after an upgrade, this automatically points to the new implementations.

Good catch, addressed in d650ff2.

alistair-singh · 2026-02-06T10:16:43Z

contracts/src/BeefyClientWrapper.sol

+    function _refundWithProgress(uint256 startGas, uint256 previousGas, uint256 progress) internal {
+        if (progress < refundTarget) {
+            return;
+        }


This means that if another relayer relays a block such that my relayer does not make enough progress, that relayer is "rewarded" with a 100% refund, and my relayer is punished by receiving a 0% refund. It is better the scale the refund by the progress made and refund each relayer accordingly. This way the other relayer is also punished by not receiving the 100% refund.

I moved this to off-chain checking, the relayer checks if there is a session is progress and if their update will be eligible for the refund. If not, they don't start the session. I think this is simpler, and moves the complexity off-chain.

Happy with this being offchain. We should do the same check on submitInitial to avoid race condition and save cost for relayers.

contracts/src/BeefyClientWrapper.sol

This reverts commit 8b8ec69.

alistair-singh · 2026-02-19T11:25:50Z

contracts/src/BeefyClientWrapper.sol

+     * Credited cost is forfeited when clearing a ticket.
+     */
+    function clearTicket(bytes32 commitmentHash) external {
+        if (ticketOwner[commitmentHash] != msg.sender) {


There is no real incentive for a relayer to call this method if the credited cost is forfeit. So maybe remove this method completely or credit the relayer. If we revert on submitInitial if the initial does not make enough progress, then we also dont need this method.

alistair-singh · 2026-02-19T11:33:32Z

contracts/src/BeefyClientWrapper.sol

+        }
+
+        if (refundAmount > 0 && address(this).balance >= refundAmount) {
+            (bool success,) = payable(msg.sender).call{value: refundAmount}("");


This is stateful, it means we have to hold funds in this contract which means if we abandon it we also abandon the funds in it.

This may be ok though if its a small amount, like if we are only moving $ 100 and we top it up in small increments. But we need to take care because funds in this contract are essentially blackholed. Current prices are like $ 0.06 per submitInitial/submitFinal cycle, so $100 is 166 cycles at current price.

Yes, that is intended, I am not really sure what else we can do? The options are:

Stateful contract owner (can move funds if we deploy a different contract)

Proxy pattern (to upgrade)

No owner, but needs to hold funds (because the whole point of this contract is to refund)

I understood we want the latter.

alistair-singh · 2026-02-19T11:37:11Z

contracts/src/BeefyClientWrapper.sol

+        uint256[] calldata bitfield,
+        IBeefyClient.ValidatorProof calldata proof
+    ) external {
+        uint256 startGas = gasleft();


Since we are not payout refunds on clearTickets (abandoned submitInitials) and we are not scaling refunds based on progress, We should revert here early if its under the minimum block progress. That way in a race condition where two relayers submit, one will fail atleast with minimum cost to itself.

submitInitial costs like 130k gas, plus storage costs for ticket, credit etc. So I think its quite substantial.

yrong · 2026-02-22T14:30:23Z

contracts/src/interfaces/IBeefyClient.sol

+interface IBeefyClient {
+    /* Types */
+
+    struct PayloadItem {
+        bytes2 payloadID;
+        bytes data;
+    }
+
+    struct Commitment {
+        uint32 blockNumber;
+        uint64 validatorSetID;
+        PayloadItem[] payload;
+    }
+
+    struct ValidatorProof {
+        uint8 v;
+        bytes32 r;
+        bytes32 s;
+        uint256 index;
+        address account;


We’re duplicating types here with BeefyClient. It might be better to extract the shared types, or alternatively, I’d prefer the wrapper to import BeefyClient directly rather than adding a new interface.

Done in 52f92e9.

yrong · 2026-02-22T16:06:02Z

contracts/src/BeefyClientWrapper.sol

+        if (ticketOwner[commitmentHash] != address(0)) {
+            revert TicketAlreadyOwned();
+        }


This check is necessary to prevent race conditions. However, there is a scenario where a malicious relayer could submit submitInitial but never complete the second phase (submitFinal).

In that case, an honest/canonical relayer should ideally be smart enough to skip this commitment and move on to a more recent one. Alternatively, we could include timing information so that expired tickets can be overwritten after a timeout period.

For example:

struct PendingTicket { address owner; uint256 creditedCost; // needed for refund calculation uint32 blockNumber; // optional, from commitment; helps relayers query uint64 createdAt; // optional, block.timestamp when submitInitial was executed, useful for timeout-based handling } mapping(bytes32 => PendingTicket) public pendingTickets;

This would allow timeout-based handling and prevent stalled tickets from blocking progress indefinitely.

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

contracts/src/BeefyClientWrapperProxy.sol Outdated Show resolved Hide resolved

yrong reviewed Jan 8, 2026

View reviewed changes

contracts/src/BeefyClientWrapper.sol Outdated Show resolved Hide resolved

remove receive impl

919f503

yrong reviewed Jan 8, 2026

View reviewed changes

contracts/src/BeefyClientWrapper.sol Outdated Show resolved Hide resolved

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

claravanstaden added 4 commits February 5, 2026 11:49

more tests and update outdated comment

e3112a2

add removed fiat shamir back

f086bcf

testing fixes

e81b1f9

tweaks and more tests

f7b5746

claravanstaden marked this pull request as ready for review February 6, 2026 07:47

claravanstaden commented Feb 6, 2026

View reviewed changes

cleanup

7128a44

yrong reviewed Feb 6, 2026

View reviewed changes

alistair-singh reviewed Feb 6, 2026

View reviewed changes

claravanstaden added 2 commits February 6, 2026 13:47

read beefy contract address from gateway

d650ff2

use gas cost at tx time

7605eac

yrong reviewed Feb 10, 2026

View reviewed changes

contracts/src/BeefyClientWrapper.sol Show resolved Hide resolved

yrong reviewed Feb 10, 2026

View reviewed changes

contracts/src/BeefyClientWrapper.sol Outdated Show resolved Hide resolved

claravanstaden added 6 commits February 10, 2026 08:35

remove unnecessary method

e3df622

refund fiat shamir

ae6dc9e

remove unnecessary events

ed51ff9

make permission-less contract

e89647e

refund interactive relayer

8b8ec69

fix reentrancy

cd32cc8

claravanstaden mentioned this pull request Feb 11, 2026

Compute Commitment Hash #1709

Merged

claravanstaden added 3 commits February 13, 2026 09:57

Revert "refund interactive relayer"

27b975b

This reverts commit 8b8ec69.

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

f035883

deplpy script

86fc1ea

alistair-singh reviewed Feb 19, 2026

View reviewed changes

yrong reviewed Feb 22, 2026

View reviewed changes

claravanstaden added 2 commits February 23, 2026 09:22

tweaks

94c4e39

remove interface and fix tests

52f92e9

		event FundsDeposited(address indexed depositor, uint256 amount);
		event FundsWithdrawn(address indexed recipient, uint256 amount);

		uint256 totalGasUsed = currentGas + previousGas;
		uint256 effectiveGasPrice = tx.gasprice < maxGasPrice ? tx.gasprice : maxGasPrice;

Comments

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!

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

claravanstaden Feb 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!

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!

Choose a reason for hiding this comment

Uh oh!

yrong Feb 10, 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!

Choose a reason for hiding this comment

Uh oh!

claravanstaden Feb 10, 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!

yrong Feb 13, 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!

Choose a reason for hiding this comment

Uh oh!

claravanstaden commented Jan 7, 2026 •

edited

Loading

codecov bot commented Jan 7, 2026 •

edited

Loading

yrong commented Jan 8, 2026 •

edited

Loading

claravanstaden Feb 6, 2026 •

edited

Loading

alistair-singh commented Jan 8, 2026 •

edited

Loading

yrong Feb 10, 2026 •

edited

Loading

claravanstaden Feb 10, 2026 •

edited

Loading

yrong Feb 13, 2026 •

edited

Loading

alistair-singh Feb 19, 2026 •

edited

Loading

alistair-singh Feb 19, 2026 •

edited

Loading

alistair-singh Feb 19, 2026 •

edited

Loading

yrong Feb 22, 2026 •

edited

Loading