feat: Make FilBeamOperator contract upgradeable by Chaitu-Tatipamula · Pull Request #13 · filbeam/contracts

Chaitu-Tatipamula · 2026-01-20T20:18:25Z

Description

This PR implements the UUPS (Universal Upgradeable Proxy Standard) proxy pattern for the FilBeamOperator contract, enabling safe contract upgrades while preserving all state.

Closes #3

Motivation

Enable bug fixes and feature additions without redeploying a new contract
Preserve state (usage data, ownership, configuration) across upgrades
Maintain a stable contract address for integrations

Key Implementation Details

Inherits Initializable, Ownable2StepUpgradeable, UUPSUpgradeable
initialize() replaces constructor (can only be called once)
_disableInitializers() prevents implementation contract initialization
_authorizeUpgrade() restricted to owner
version() function returns "1.0.0"

Testing

74 tests pass including new upgrade tests:
- test_CannotInitializeTwice
- test_CannotInitializeImplementationDirectly
- test_OnlyOwnerCanUpgrade
- test_OwnerCanUpgrade
- test_Version

How to Test

forge build
forge test -vvv

pyropy

Great start! 👏🏻

I believe we're missing two very important things:

Deployment script that upgrade the old contract without deploying a new proxy
State view contract (I'm not sure if this is needed with UUPS contract but I've seen that you have mentioned it in the docs).

It is very important to us NOT to lose on-chain state during upgrades as that could potentially cause loss for both FilBeam and storage providers.

pyropy · 2026-01-21T14:23:52Z

script/DeployFilBeamOperator.s.sol

        );

+        //Step 3: Deploy ERC1967 proxy pointing to the implementation
+        ERC1967Proxy proxy = new ERC1967Proxy(address(implementation), initializeData);


It looks like this will always deploy a new proxy contract? Should there be a separate script or way to upgrade proxy to a new implementation?

ah yes i think having a seperate script for this is nice, so i'll set it to take proxy address as an environment variable, deploy new impl and call upgradeToAndCall on the proxy

new script here script/UpgradeFilBeamOperator.s.sol

pyropy · 2026-01-21T14:41:41Z

src/FilBeamOperator.sol

+    uint256 public cdnRatePerByte;
+    uint256 public cacheMissRatePerByte;


Suggested change

uint256 public cdnRatePerByte;

uint256 public cacheMissRatePerByte;

uint256 public immutable cdnRatePerByte;

uint256 public immutable cacheMissRatePerByte;

One of the decisions we have made during this contract development is to leave the rates immutable. Why is that you may wonder? It's because the way of how we actually report the usage.

So you see, we may change the rate from current $7 to $8, but there is no way for us to know if the reported egress usage happened before or after the price change. Therefore it would be unfair to charge users a new rate for egress usage that happened under the old rate.

If the rate change happens we'd have to deploy a new set of contracts, but upgradability is there to ensure that we can issue bugfixes without copying the state between smart contracts.

ah now i get it, i was wondering why they were immutable. Thanks for letting me know-this makes total sense, this ensures fair billing without any ambiguity on which rate applies to the reported usage

pyropy · 2026-01-21T14:44:13Z

src/FilBeamOperator.sol

+    address public fwssContractAddress;
+    address public fwssStateViewContractAddress;
+    address public paymentsContractAddress;


Suggested change

address public fwssContractAddress;

address public fwssStateViewContractAddress;

address public paymentsContractAddress;

address public immutable fwssContractAddress;

address public immutable fwssStateViewContractAddress;

address public immutable paymentsContractAddress;

Since these are set during the initialization, I believe they may remain immutable. FWSS contract is doing a similar thing

https://github.com/FilOzone/filecoin-services/blob/a86e4a5018133f17a25b4bb6b5b99da4d34fe664/service_contracts/src/FilecoinWarmStorageService.sol#L232-L238

got it made them immutable and updated the scripts

pyropy · 2026-01-21T14:46:51Z

DEPLOYMENT.md

 cast call $FILBEAM_OPERATOR_ADDRESS "cdnRatePerByte()" --rpc-url $RPC_URL
 cast call $FILBEAM_OPERATOR_ADDRESS "cacheMissRatePerByte()" --rpc-url $RPC_URL
 cast call $FILBEAM_OPERATOR_ADDRESS "filBeamOperatorController()" --rpc-url $RPC_URL
+cast call $FILBEAM_OPERATOR_ADDRESS "version()" --rpc-url $RPC_URL  # Should return "1.0.0"


Suggested change

cast call $FILBEAM_OPERATOR_ADDRESS "version()" --rpc-url $RPC_URL # Should return "1.0.0"

cast call $FILBEAM_OPERATOR_PROXY_ADDRESS "version()" --rpc-url $RPC_URL # Should return "1.0.0"

Let's perhaps make the exported variable more explicit.

pyropy · 2026-01-21T14:47:19Z

DEPLOYMENT.md

+
+```bash
+# Owner calls upgradeToAndCall on the proxy
+cast send $FILBEAM_OPERATOR_ADDRESS \


Suggested change

cast send $FILBEAM_OPERATOR_ADDRESS \

cast send $FILBEAM_OPERATOR_PROXY_ADDRESS \

pyropy · 2026-01-21T14:47:33Z

DEPLOYMENT.md

+  --rpc-url $RPC_URL \
+  --private-key $OWNER_PRIVATE_KEY
+
+export NEW_IMPLEMENTATION=0x...  # New implementation address


Suggested change

export NEW_IMPLEMENTATION=0x... # New implementation address

export FILBEAM_OPERATOR_IMPL_ADDRESS=0x... # New implementation address

pyropy · 2026-01-21T14:47:47Z

DEPLOYMENT.md

+
+```bash
+# Check new version
+cast call $FILBEAM_OPERATOR_ADDRESS "version()" --rpc-url $RPC_URL


Suggested change

cast call $FILBEAM_OPERATOR_ADDRESS "version()" --rpc-url $RPC_URL

cast call $FILBEAM_OPERATOR_PROXY_ADDRESS "version()" --rpc-url $RPC_URL

pyropy · 2026-01-21T14:48:14Z

DEPLOYMENT.md

+# Should return new version (e.g., "1.1.0")
+
+# Verify state is preserved
+cast call $FILBEAM_OPERATOR_ADDRESS "cdnRatePerByte()" --rpc-url $RPC_URL


Suggested change

cast call $FILBEAM_OPERATOR_ADDRESS "cdnRatePerByte()" --rpc-url $RPC_URL

cast call $FILBEAM_OPERATOR_PROXY_ADDRESS "cdnRatePerByte()" --rpc-url $RPC_URL

Done i changed it

pyropy · 2026-01-21T14:48:36Z

README.md

-    uint256 _cdnRatePerByte,       // Rate per byte for CDN usage
-    uint256 _cacheMissRatePerByte, // Rate per byte for cache-miss usage
-    address _filBeamOperatorController      // Address authorized to report usage
+    address fwssStateViewAddress,  // FWSS State View contract address


We're missing a state view contract 👀

The state view contract is already integrated in FilBeamOperator.sol as fwssStateViewContractAddress it is used in _settlePaymentRail to actually query rail IDs, i just documented this existing parameter.

Oh, great catch! For a moment I thought it was a FilBeamStateViewContract.

yes as you said i dont think we may need a seperate FilBeamOperatorStateView contract since all the states are accessible via the public getters

…ntation improvements

pyropy

Great work! Let's upgrade the documentation before proceeding to merge this.

pyropy · 2026-01-26T11:38:58Z

src/FilBeamOperator.sol

 import "./Errors.sol";
-import {Ownable, Ownable2Step} from "@openzeppelin/contracts/access/Ownable2Step.sol";
+import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";


Suggested change

import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";

Please remove this import as it's replaced by Ownable2StepUpgradeable

pyropy · 2026-01-26T11:43:07Z

README.md

+    uint256 cacheMissRatePerByte,  // Rate per byte for cache-miss usage
+    address filBeamOperatorController // Address authorized to report usage


Suggested change

uint256 cacheMissRatePerByte, // Rate per byte for cache-miss usage

address filBeamOperatorController // Address authorized to report usage

uint256 cacheMissRatePerByte // Rate per byte for cache-miss usage

filBeamOperatorController is removed from the initialize method.

you mean filBeamOperatorController is the only thing kept in initialize method! the addresses and the rates were the ones moved to constructor to be immutable

pyropy · 2026-01-26T11:44:08Z

src/FilBeamOperator.sol

+    /// @param newImplementation Address of new implementation contract
+    function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}
+
+    function version() public pure virtual returns (string memory) {


The version() function returns a hardcoded "1.0.0" - consider documenting that this must be updated manually with each upgrade.

pyropy · 2026-01-26T11:45:14Z

DEPLOYMENT.md

+
+```bash
+# Owner calls upgradeToAndCall on the proxy
+cast send $FILBEAM_OPERATOR_PROXY_ADDRESS \


The manual upgrade instructions using forge create are good for documentation, but consider referencing the new UpgradeFilBeamOperator.s.sol script as
the preferred method

pyropy · 2026-01-26T11:46:31Z

script/UpgradeFilBeamOperator.s.sol

+
+        vm.stopBroadcast();
+
+        // Step 2: Verify the upgrade


Suggested change

// Step 2: Verify the upgrade

// Step 3: Verify the upgrade

…ning

DEPLOYMENT.md

pyropy · 2026-02-04T08:13:26Z

@juliangruber would you also be able to give this a look?

feat: make FilBeamOperator upgradeable with UUPS proxy pattern

2cc6318

pyropy requested changes Jan 21, 2026

View reviewed changes

Chaitu-Tatipamula requested a review from pyropy January 21, 2026 19:54

refactor: address PR review feedback - immutable variables and docume…

d7434fc

…ntation improvements

Chaitu-Tatipamula force-pushed the feat/uups-upgradeable branch from 7704faf to d7434fc Compare January 21, 2026 20:17

pyropy requested changes Jan 26, 2026

View reviewed changes

pyropy requested review from bajtos and juliangruber January 26, 2026 11:47

docs: address PR review feedback on documentation and contract versio…

924665d

…ning

Chaitu-Tatipamula requested a review from pyropy January 26, 2026 17:27

pyropy reviewed Jan 27, 2026

View reviewed changes

DEPLOYMENT.md Show resolved Hide resolved

DEPLOYMENT.md Show resolved Hide resolved

Chaitu-Tatipamula requested a review from pyropy January 27, 2026 11:39

docs: add missing flags to upgrade script command

6ca1cc9

juliangruber removed their request for review January 28, 2026 08:07

pyropy assigned Chaitu-Tatipamula Feb 4, 2026

		uint256 public cdnRatePerByte;
		uint256 public cacheMissRatePerByte;

	cast call $FILBEAM_OPERATOR_ADDRESS "version()" --rpc-url $RPC_URL # Should return "1.0.0"
	cast call $FILBEAM_OPERATOR_PROXY_ADDRESS "version()" --rpc-url $RPC_URL # Should return "1.0.0"

	cast send $FILBEAM_OPERATOR_ADDRESS \
	cast send $FILBEAM_OPERATOR_PROXY_ADDRESS \

	export NEW_IMPLEMENTATION=0x... # New implementation address
	export FILBEAM_OPERATOR_IMPL_ADDRESS=0x... # New implementation address

	cast call $FILBEAM_OPERATOR_ADDRESS "cdnRatePerByte()" --rpc-url $RPC_URL
	cast call $FILBEAM_OPERATOR_PROXY_ADDRESS "cdnRatePerByte()" --rpc-url $RPC_URL

		uint256 cacheMissRatePerByte, // Rate per byte for cache-miss usage
		address filBeamOperatorController // Address authorized to report usage

	uint256 cacheMissRatePerByte, // Rate per byte for cache-miss usage
	address filBeamOperatorController // Address authorized to report usage
	uint256 cacheMissRatePerByte // Rate per byte for cache-miss usage

Conversation

Chaitu-Tatipamula commented Jan 20, 2026

Description

Motivation

Key Implementation Details

Testing

How to Test

Uh oh!

pyropy 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!

pyropy 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!

Uh oh!

Uh oh!

pyropy commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants